跳到主要内容

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）。对于一次性调试，您可以手动触发一次计时器：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
emailconfig.yaml 中配置了 SMTP
sms已配置 SMS 服务商
local对 ~/.hermes/cron/output/ 有写入权限
origin交付到创建任务的聊天中

其他支持的平台包括 mattermost、homeassistant、dingtalk、feishu、wecom、weixin、bluebubbles 和 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：检查技能名称与技能文件夹名称是否一致​

技能名称区分大小写，且必须与已安装技能的文件夹名称完全匹配。如果任务中指定 ai-funding-daily-report，但技能文件夹名为 ai-funding-daily-report，请通过 hermes skills list 确认确切名称。

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

Cron 任务运行时禁用了 cronjob、messaging 和 clarify 工具集。这可防止递归创建 Cron 任务、直接发送消息（交付由调度器处理）以及交互式提示。如果某技能依赖这些工具集，则在 Cron 环境中无法运行。

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

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

使用多个技能时，它们按顺序加载。如果技能 A 依赖技能 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：常见错误模式​

脚本报“没有这样的文件或目录” script 路径必须是绝对路径（或相对于 Hermes 配置目录的相对路径）。请确认：

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

作业执行时提示“技能未找到” 该技能必须安装在运行调度器的机器上。若在不同机器间切换，技能不会自动同步——请使用 hermes skills install <skill-name> 重新安装。

作业运行但未交付任何内容 很可能是交付目标存在问题（参见上方“交付失败”部分），或响应被静默抑制（[SILENT]）。

作业卡住或超时 调度器使用基于非活动状态的超时机制（默认 600 秒，可通过 HERMES_CRON_TIMEOUT 环境变量配置，设为 0 表示无限制）。只要代理持续调用工具，其运行时间就不会受限制——计时器仅在长时间无活动后触发。对于长时间运行的任务，应使用脚本处理数据收集，仅交付最终结果。

检查项 3：锁竞争​

调度器使用基于文件的锁机制，防止任务周期重叠。如果运行了两个网关实例（或 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 * * *）。

重叠作业过多​

调度器在每个周期内按顺序执行作业。如果多个作业在同一时间触发，它们将依次运行。建议错开调度时间（例如使用 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）。