跳到主要内容

Cron 故障排查

当一个 cron 任务表现异常时，建议按下面顺序逐项检查。大多数问题都可以归类到四类之一：时间、投递、权限，或者技能加载。

任务没有触发​

检查 1：确认任务存在且处于激活状态​

hermes cron list

找到对应任务，并确认状态是 [active]，而不是 [paused] 或 [completed]。如果显示 [completed]，说明重复次数可能已经耗尽，此时需要编辑任务来重置它。

检查 2：确认 schedule 正确​

错误格式的 schedule 可能会悄悄变成一次性任务，或者直接被拒绝。先验证你的表达式：

Your expressionShould evaluate to
0 9 * * *每天 9:00 AM
0 9 * * 1每周一 9:00 AM
every 2h从现在起每 2 小时一次
30m30 分钟后
2025-06-01T09:00:00UTC 时间 2025 年 6 月 1 日 9:00 AM

如果某个任务触发一次后就从列表里消失，这通常说明它本来就是一次性 schedule（例如 30m、1d 或 ISO 时间戳），属于预期行为。

检查 3：gateway 是否在运行​

Cron 任务是由 gateway 后台的 ticker 线程触发的，ticker 每 60 秒跑一次。普通 CLI 聊天会话不会自动触发 cron 任务。

如果你希望任务自动执行，就必须有一个正在运行的 gateway（hermes gateway 或 hermes serve）。如果你只是为了排查问题，也可以手动执行 hermes cron tick 来触发一次 tick。

检查 4：系统时钟与时区​

任务使用本地时区。如果机器时钟不准，或者时区和你预期不同，任务就会在错误时间触发。请检查：

date
hermes cron list   # Compare next_run times with local time

投递失败​

检查 1：确认 deliver 目标正确​

投递目标区分大小写，而且要求对应平台已经配置好。目标写错时，响应可能会被悄悄丢弃。

TargetRequires
telegram在 ~/.hermes/.env 中配置 TELEGRAM_BOT_TOKEN
discord在 ~/.hermes/.env 中配置 DISCORD_BOT_TOKEN
slack在 ~/.hermes/.env 中配置 SLACK_BOT_TOKEN
whatsapp已配置 WhatsApp 网关
signal已配置 Signal 网关
matrix已配置 Matrix homeserver
email在 config.yaml 中配置 SMTP
sms已配置 SMS provider
local对 ~/.hermes/cron/output/ 拥有写权限
origin发送回创建该任务的聊天会话

其它支持的平台还包括 mattermost、homeassistant、dingtalk、feishu、wecom、weixin、bluebubbles、qqbot 和 webhook。你也可以使用 platform:chat_id 语法指定某个具体聊天，例如 telegram:-1001234567890。

如果投递失败，任务本身仍然会运行，只是不会发到任何地方。可以用 hermes cron list 查看 last_error 字段（如果当前实现有提供）。

检查 2：确认 [SILENT] 的使用是否正确​

如果 cron 任务没有任何输出，或者 agent 回复了 [SILENT]，投递会被抑制。这是很多监控类任务的预期行为，但要确认你的 prompt 没有不小心把所有情况都压成静默。

像“如果没有变化就回复 [SILENT]”这样的 prompt，一旦条件写错，也可能把本应发送的非空结果一起吃掉。

检查 3：平台 token 权限​

不同消息平台的机器人都需要特定权限，否则投递可能静默失败：

  • Telegram：机器人必须是目标群组 / 频道管理员
  • Discord：机器人必须拥有目标频道的发送权限
  • Slack：机器人必须已加入 workspace，并具备 chat:write scope

检查 4：响应包装​

默认情况下，cron 响应会加上头尾包装（config.yaml 中 cron.wrap_response: true）。某些平台或集成不一定能很好处理这种包装。如果你怀疑是这个问题，可以关闭：

cron:
  wrap_response: false

技能加载失败​

检查 1：确认技能已安装​

hermes skills list

技能必须先安装，才能附加到 cron 任务上。如果缺少某个技能，请先通过 hermes skills install <skill-name> 或 CLI 中的 /skills 安装。

检查 2：确认技能名与目录名一致​

技能名区分大小写，且必须与已安装技能的目录名一致。如果你的任务里写的是某个名字，请用 hermes skills list 核对准确名称。

检查 3：技能是否依赖交互式工具​

Cron 任务运行时会禁用 cronjob、messaging 和 clarify 这些 toolset。这样可以避免递归创建 cron、直接发消息（投递由 scheduler 统一处理）以及交互式提问。如果某个技能依赖这些工具集，它在 cron 场景中就无法工作。

请检查该技能文档，确认它支持非交互（headless）模式。

检查 4：多技能加载顺序​

当你给一个任务附加多个技能时，它们会按顺序加载。如果 Skill A 依赖 Skill B 提供的上下文，那么 B 就必须先加载：

/cron add "0 9 * * *" "..." --skill context-skill --skill target-skill

在这个例子里，context-skill 会先于 target-skill 加载。

任务错误与失败​

检查 1：回看最近任务输出​

如果任务确实跑了但失败了，你通常可以在这些地方看到错误上下文：

  1. 任务投递到的聊天里（前提是投递本身成功）
  2. ~/.hermes/logs/agent.log（scheduler 消息）或 errors.log（warning）
  3. hermes cron list 中该任务的 last_run 元数据

检查 2：常见错误模式​

脚本报 "No such file or directory" script 路径必须是绝对路径，或者相对于 Hermes 配置目录。请检查：

ls ~/.hermes/scripts/your-script.py   # Must exist
hermes cron edit <job_id> --script ~/.hermes/scripts/your-script.py

执行时提示 "Skill not found" 该技能必须安装在运行 scheduler 的那台机器上。如果你换了机器，技能不会自动同步，需要重新执行 hermes skills install <skill-name>。

任务运行了，但什么都没投递 通常是投递目标问题（见上方 Delivery Failures），或者响应被 [SILENT] 静默抑制了。

任务卡住或超时 Scheduler 使用的是基于“无活动”的超时机制（默认 600 秒，可通过环境变量 HERMES_CRON_TIMEOUT 配置；设为 0 表示不限制）。只要 agent 还在持续调用工具，它就可以一直跑；只有长时间无活动才会触发超时。对于长任务，建议让脚本处理数据采集，只把最终结果交给 agent 分析。

检查 3：锁竞争​

Scheduler 使用基于文件的锁来避免多个 tick 重叠。如果你同时运行了两个 gateway 实例，或者 CLI 会话与 gateway 冲突，任务可能会被延迟甚至跳过。

先清理重复的 gateway 进程：

ps aux | grep hermes
# Kill duplicate processes, keep only one

检查 4：jobs.json 权限​

任务定义保存在 ~/.hermes/cron/jobs.json。如果当前用户对这个文件没有读写权限，scheduler 可能会静默失败：

ls -la ~/.hermes/cron/jobs.json
chmod 600 ~/.hermes/cron/jobs.json   # Your user should own it

性能问题​

任务启动太慢​

每个 cron 任务都会创建一个全新的 AIAgent 会话，这可能包含 provider 认证和模型初始化。对时间敏感的任务，建议预留一些缓冲，例如用 0 8 * * *，而不是把任务卡在恰好需要的时间点。

同一时刻重叠任务太多​

Scheduler 在每个 tick 中按顺序执行任务。如果多个任务同一时刻到期，它们会一个接一个运行。你可以把计划稍微错开，例如用 0 9 * * * 和 5 9 * * *，而不是都挤在 0 9 * * *。

脚本输出过大​

如果脚本一口气打印几 MB 内容，不仅会拖慢 agent，也很容易撞上 token 限制。最好在脚本层就先筛选和总结，只输出 agent 真正需要推理的内容。

诊断命令​

hermes cron list                    # Show all jobs, states, next_run times
hermes cron run <job_id>            # Schedule for next tick (for testing)
hermes cron edit <job_id>           # Fix configuration issues
hermes logs                         # View recent Hermes logs
hermes skills list                  # Verify installed skills

获取更多帮助​

如果你已经按本指南检查过，问题仍然存在：

  1. 运行 hermes cron run <job_id>（会在下一次 gateway tick 触发），同时观察聊天输出是否报错
  2. 检查 ~/.hermes/logs/agent.log 中的 scheduler 消息，以及 ~/.hermes/logs/errors.log 中的 warning
  3. 在 github.com/NousResearch/hermes-agent 提 issue，并提供：
    • 任务 ID 与 schedule
    • 投递目标
    • 你的预期结果与实际现象
    • 日志中的相关报错信息

完整 cron 参考请参阅 Automate Anything with Cron 和 Scheduled Tasks (Cron)。