Skip to main content

Cron 故障排除

当 Cron 任务未按预期运行时，请按以下步骤逐一排查。大多数问题可归类为四类：时间设置、交付失败、权限问题或技能加载失败。

任务未触发​

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

hermes cron list

查找该任务，并确认其状态为 [active]，而不是 [paused] 或 [completed]。如果显示为 [completed]，很可能是重复次数已经耗尽，需要编辑任务并重置计数。

检查 2：确认调度表达式正确​

格式错误的调度表达式会静默降级为一次性任务，或直接被拒绝。请测试你的表达式：

你的表达式应该解析为
0 9 * * *每天上午 9:00
0 9 * * 1每周一上午 9:00
every 2h从现在起每 2 小时一次
30m从现在起 30 分钟后
2025-06-01T09:00:002025 年 6 月 1 日上午 9:00 UTC

如果任务只执行一次就从列表中消失，说明它是一次性任务，例如 30m、1d 或 ISO 时间戳，这属于预期行为。

检查 3：网关是否正在运行？​

Cron 任务由网关的后台定时器线程触发，该线程每 60 秒触发一次。普通的 CLI 会话不会自动触发 Cron 任务。

如果你希望任务自动运行，必须确保网关正在运行，也就是 hermes gateway 或 hermes serve。如果只是临时调试，可以手动触发一次 tick：hermes cron tick。

检查 4：检查系统时间和时区​

任务使用本地时区。如果机器的时钟不准，或时区与预期不符，任务将在错误的时间触发。请验证：

date
hermes cron list   # Compare next_run times with local time

交付失败​

检查 1：确认交付目标正确​

交付目标区分大小写，且需要正确配置对应平台。配置错误的目标会静默丢弃响应。

目标所需配置
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 服务商
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 任务没有输出，或者代理返回 [SILENT]，交付就会被抑制。这通常是监控类任务的预期行为，但也要确认提示词没有误把所有结果都静默掉。

像“若无变化则返回 [SILENT]”这样的提示，也可能把本该发出的结果一起吞掉。建议顺手检查一下条件逻辑。

检查 3：平台令牌权限​

每个消息平台的机器人需要特定权限才能接收消息。若交付静默失败：

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

检查 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：技能名 vs. 技能文件夹名​

技能名称区分大小写，并且必须与已安装技能的文件夹名完全一致。遇到名称对不上时，先用 hermes skills list 确认实际名称。

检查 3：依赖交互工具的技能​

Cron 任务运行时会禁用 cronjob、messaging 和 clarify 这几个工具集，以防递归创建定时任务、绕过调度器直接发消息，或在后台任务里触发交互式提问。如果某个技能依赖这些工具，它就无法在 Cron 环境中正常运行。

请查阅技能文档，确认其是否支持非交互模式（无头模式）。

检查 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 中的调度器消息，或 errors.log 里的警告
  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” 错误（任务执行时）
技能必须安装在运行调度器的那台机器上。如果你切换了机器，技能不会自动同步，需要重新安装：hermes skills install <skill-name>

任务运行但无任何输出
这通常是交付目标配置有误，或者响应被 [SILENT] 静默抑制了。可先回到“交付失败”一节继续排查。

任务卡住或超时
调度器使用基于“不活动”的超时机制，默认是 600 秒，可通过环境变量 HERMES_CRON_TIMEOUT 调整，设为 0 表示不限制。只要代理还在持续调用工具，计时器就不会触发；只有长时间无活动时才会判定超时。对于运行时间很长的任务，建议把数据收集放进脚本里，只把最终结果交给代理处理。

检查 3：锁竞争问题​

调度器使用文件锁防止多个 tick 重叠。若运行了两个网关实例（或 CLI 会话与网关冲突），任务可能延迟或跳过。

终止重复的网关进程：

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

检查 4：jobs.json 权限问题​

任务存储在 ~/.hermes/cron/jobs.json 中。如果这个文件对当前用户不可读或不可写，调度器可能会静默失败：

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

性能问题​

启动缓慢​

每个 Cron 任务都会创建一个新的 AIAgent 会话，这里面可能包含提供商认证、模型初始化等额外开销。对于时间特别敏感的任务，建议预留缓冲，例如使用 0 8 * * * 而不是 0 9 * * *。

过多重叠任务​

调度器会在每次 tick 中串行执行任务。如果多个任务同一时刻触发，它们会排队依次运行。建议把时间错开，比如用 0 9 * * * 和 5 9 * * *，而不是都设成 0 9 * * *，这样更不容易堆积延迟。

脚本输出过大​

脚本输出数兆字节的数据会拖慢代理并可能触及 token 限制。应在脚本层面进行过滤或摘要，仅输出代理所需推理的内容。

诊断命令​

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> 触发任务，并观察聊天输出或日志里的报错信息。
  2. 检查 ~/.hermes/logs/agent.log 中的调度消息，以及 ~/.hermes/logs/errors.log 里的警告。
  3. 到 github.com/NousResearch/hermes-agent 提交问题时，尽量附上任务 ID、调度计划、交付目标、期望结果、实际现象以及相关日志。

有关完整的 cron 参考信息，请参阅 使用 Cron 实现自动化 和 计划任务（Cron）。