Qwake 指南

如何在 macOS、Linux、Windows 上使用 Qwake

一篇实用的 Qwake 跨平台使用指南，覆盖 macOS LaunchAgent、Linux cron/systemd 和 Windows Task Scheduler。

Qwake 能保证什么，不能保证什么

Qwake 会通过你本机已有的 CLI 发送极小 wake 请求。它可以验证定时任务是否尝试运行，以及 provider 是否接受了请求。但如果电脑关机、完全深度睡眠、断网，或 provider 拒绝请求，它不能保证额度一定刷新。

安装 Qwake

npm install -g @sysiphus/qwake
qwake init
qwake doctor
qwake wake mock

macOS：推荐使用 LaunchAgent

当前内置的 schedule installer 主要支持 macOS LaunchAgent。对笔记本工作流来说，它通常比 cron 更适合，因为 launchd 和用户会话集成更好。定时任务默认启用 smart skipping：只有上一次成功 wake 已经超过配置的 5 小时窗口加 buffer 后，Qwake 才会真的调用 provider。

qwake schedule install claude --times 06:05,11:10,16:15,21:20
qwake schedule status claude
qwake schedule run claude
qwake schedule logs claude

可以用 --window-minutes 300 --buffer-minutes 5 调整 smart guard；如果你明确希望每个定时点都调用 provider，可以用 --no-smart 关闭。

健康日志通常是：

[2026-06-01 09:20:00 +08:00] wake agent=claude status=success exitCode=0 limited=false durationMs=1842 utc=2026-06-01T01:20:00.000Z
[2026-06-01 11:10:00 +08:00] wake agent=claude status=skipped exitCode=0 limited=false durationMs=3 utc=2026-06-01T03:10:00.000Z nextWakeAt=2026-06-01T06:25:00.000Z

schedule run 会让 launchd 手动触发一次已安装任务，这样不用等到下一个定时点，也能验证真实的系统调度链路。 MacBook 合盖后仍然执行，通常是因为 macOS 尚未进入完全深度睡眠、机器短暂唤醒，或接了外部电源。判断是否执行，以日志时间戳为准。

如果想看 launchd 底层状态：

launchctl list | rg qwake
cat ~/Library/LaunchAgents/com.qwake.claude.plist

卸载：

qwake schedule uninstall claude

Linux：cron 或 systemd timer

Qwake 目前还没有自动安装 Linux 调度任务。简单场景可以用 cron；如果需要更好的可观测性，可以用 systemd user timer。

# cron
5 6 * * * qwake wake claude --smart >> ~/.qwake/logs/claude.log 2>> ~/.qwake/logs/claude.error.log
10 11 * * * qwake wake claude --smart >> ~/.qwake/logs/claude.log 2>> ~/.qwake/logs/claude.error.log
15 16 * * * qwake wake claude --smart >> ~/.qwake/logs/claude.log 2>> ~/.qwake/logs/claude.error.log
20 21 * * * qwake wake claude --smart >> ~/.qwake/logs/claude.log 2>> ~/.qwake/logs/claude.error.log

如果用 systemd user timer，可以把同样的命令放进 user service，并用下面命令查看：

systemctl --user status qwake-claude.timer
journalctl --user -u qwake-claude.service

Windows：Task Scheduler

Qwake 目前还没有自动安装 Windows 调度任务。通过 npm 全局安装后，Windows 通常会在 npm 的全局 bin 目录生成 qwake.cmd 和 qwake.ps1 这类命令 shim。先用下面命令找到实际路径：

where qwake
qwake doctor
qwake wake claude --smart

如果 where qwake 输出的是 qwake.cmd 结尾的路径，可以在任务计划程序里直接指向它。但更推荐写一个 batch wrapper，因为日志路径更容易控制。创建 %USERPROFILE%\qwake-claude.bat：

@echo off
set QWAKE_LOG_DIR=%USERPROFILE%\.qwake\logs
if not exist "%QWAKE_LOG_DIR%" mkdir "%QWAKE_LOG_DIR%"
qwake wake claude --smart >> "%QWAKE_LOG_DIR%\claude.log" 2>> "%QWAKE_LOG_DIR%\claude.error.log"

Task Scheduler GUI 建议配置：

选择 Create Task，不要选 Basic Task，这样更方便添加多个触发时间。
Triggers：添加四个 daily trigger，分别是 06:05、11:10、16:15、21:20。这是固定工作日时间方案，配合 smart mode 使用。
Action：start a program。
Program/script：%USERPROFILE%\qwake-claude.bat。
Start in：%USERPROFILE%。
Conditions：如果希望 Windows 尝试从睡眠中唤醒执行任务，可以勾选 “Wake the computer to run this task”。

如果你更喜欢命令行方式，也可以用 schtasks 创建四个任务：

schtasks /Create /TN "Qwake Claude 0605" /SC DAILY /ST 06:05 /TR "%USERPROFILE%\qwake-claude.bat" /F
schtasks /Create /TN "Qwake Claude 1110" /SC DAILY /ST 11:10 /TR "%USERPROFILE%\qwake-claude.bat" /F
schtasks /Create /TN "Qwake Claude 1615" /SC DAILY /ST 16:15 /TR "%USERPROFILE%\qwake-claude.bat" /F
schtasks /Create /TN "Qwake Claude 2120" /SC DAILY /ST 21:20 /TR "%USERPROFILE%\qwake-claude.bat" /F

也可以做成每 5 小时触发一次的 interval-based schedule。它不如固定工作日时间直观，但 smart mode 会跳过窗口内的重复请求：

schtasks /Create /TN "Qwake Claude Every 5h" /SC HOURLY /MO 5 /TR "%USERPROFILE%\qwake-claude.bat" /F

后续可以这样验证：

type "%USERPROFILE%\.qwake\logs\claude.log"
type "%USERPROFILE%\.qwake\logs\claude.error.log"
schtasks /Query /TN "Qwake Claude 0605" /V /FO LIST

排障

如果定时唤醒没有执行，先看：

qwake schedule status claude
qwake schedule run claude
qwake schedule logs claude
qwake doctor

如果 macOS + nvm 环境下看到 env: node: No such file or directory，说明旧 schedule 没拿到 Node 路径。升级到最新版 Qwake 后重新安装 schedule，它会使用绝对 Node 路径。