Hermes Agent Cron 故障排查：定时任务问题诊断与修复

Hermes Agent 的 Cron 定时任务功能是自动化工作流的核心组件，但在实际使用中可能会遇到任务不执行、投递失败、Skill 加载错误等问题。本文系统地梳理了 Cron 定时任务的常见故障场景，按类别提供了排查思路和修复方案，帮助开发者快速定位并解决问题。

任务未触发

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

hermes cron list

查找目标任务，确认其状态为 [active]（而非 [paused] 或 [completed]）。如果显示 [completed]，可能是重复次数已耗尽——编辑任务以重置即可。

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

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

如果任务执行一次后从列表中消失，说明它是单次调度（30m、1d 或 ISO 时间戳）——这是预期行为。

检查 3：Gateway 是否在运行？

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

如果你期望任务自动触发，需要运行一个 Gateway（hermes gateway 前台运行，或 hermes gateway start 安装为服务）。用于一次性调试时，可以手动触发 tick：hermes cron tick。

检查 4：检查系统时钟和时区

任务使用本地时区。如果机器时钟错误或时区与预期不同，任务会在错误的时间触发。验证方法：

date
hermes cron list   # 对比 next_run 时间与本地时间

投递失败

检查 1：确认投递目标配置正确

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

其他支持的平台包括 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 权限

每个消息平台 Bot 都需要特定权限才能发送消息。如果投递静默失败：

• Telegram：Bot 必须是目标群组/频道的管理员
• Discord：Bot 必须有在目标频道发送消息的权限
• Slack：Bot 必须已添加到工作区并具有 chat:write 权限范围

检查 4：响应包装

默认情况下，Cron 响应会加上头部和尾部包装（cron.wrap_response: true，在 config.yaml 中配置）。某些平台或集成可能无法正确处理。禁用方法：

cron:
  wrap_response: false

Skill 加载失败

检查 1：确认 Skill 已安装

hermes skills list

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

检查 2：检查 Skill 名称与文件夹名称

Skill 名称区分大小写，必须与已安装 Skill 的文件夹名匹配。如果你的任务指定了 ai-funding-daily-report 但 Skill 文件夹名不同，请通过 hermes skills list 确认准确名称。

检查 3：需要交互式工具的 Skill

Cron 任务运行时会禁用 cronjob、messaging 和 clarify 工具集。这可以防止递归创建 Cron、直接发送消息（投递由调度器处理）和交互式提示。如果某个 Skill 依赖这些工具集，它在 Cron 上下文中将无法工作。

查看 Skill 文档，确认它支持非交互式（headless）模式运行。

检查 4：多 Skill 加载顺序

使用多个 Skill 时，它们按顺序加载。如果 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   # 必须存在
hermes cron edit <job_id> --script ~/.hermes/scripts/your-script.py

执行时出现"Skill not found" Skill 必须安装在运行调度器的机器上。如果你在不同机器之间切换，Skill 不会自动同步——需要用 hermes skills install <skill-name> 重新安装。

任务运行但无投递 可能是投递目标问题（参见上方"投递失败"部分）或响应被静默抑制（[SILENT]）。

任务挂起或超时 调度器使用基于不活跃的超时机制（默认 600 秒，可通过 HERMES_CRON_TIMEOUT 环境变量配置，0 表示无限制）。只要 Agent 持续调用工具就可以继续运行——计时器仅在持续不活跃后触发。长时间运行的任务应使用脚本处理数据收集，只投递最终结果。

检查 3：锁竞争

调度器使用基于文件的锁来防止重叠 tick。如果运行了两个 Gateway 实例（或 CLI 会话与 Gateway 冲突），任务可能会被延迟或跳过。

终止重复的 Gateway 进程：

ps aux | grep hermes
# 终止重复进程，只保留一个

检查 4：jobs.json 的权限

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

ls -la ~/.hermes/cron/jobs.json
chmod 600 ~/.hermes/cron/jobs.json   # 当前用户应拥有该文件

性能问题

任务启动缓慢

每个 Cron 任务会创建一个新的 AIAgent 会话，这可能涉及提供商认证和模型加载。对于时间敏感的调度，建议添加缓冲时间（例如用 0 8 * * * 代替 0 9 * * *）。

过多重叠任务

调度器在每个 tick 内按顺序执行任务。如果多个任务在同一时间到期，它们会依次运行。建议错开调度时间（例如 0 9 * * * 和 5 9 * * *，而非两个都用 0 9 * * *）以避免延迟。

脚本输出过大

输出大量数据的脚本会拖慢 Agent，并可能触及 Token 限制。应在脚本层面进行过滤和摘要——只输出 Agent 需要推理的内容。

诊断命令

hermes cron list                    # 显示所有任务、状态和下次运行时间
hermes cron run <job_id>            # 安排下次 tick 执行（用于测试）
hermes cron edit <job_id>           # 修复配置问题
hermes logs                         # 查看最近的 Hermes 日志
hermes skills list                  # 验证已安装的 Skill

获取更多帮助

如果你已按本指南排查但问题仍然存在：

1. 使用 hermes cron run <job_id> 运行任务（在下次 Gateway tick 时触发），观察聊天输出中的错误
2. 检查 ~/.hermes/logs/agent.log 中的调度器消息和 ~/.hermes/logs/errors.log 中的警告
3. 在 github.com/NousResearch/hermes-agent 提交 Issue，附上：
   • 任务 ID 和调度表达式
   • 投递目标
   • 期望行为与实际行为
   • 日志中的相关错误信息