跳到主要内容

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:00 | 2025 年 6 月 1 日 UTC 早上 9:00 |

如果任务触发一次然后从列表中消失，那是一次性调度（30m、1d 或 ISO 时间戳）— 预期行为。

检查 3：gateway 是否在运行？​

Cron 任务由 gateway 的后台 tick 线程触发，该线程每 60 秒 tick 一次。常规 CLI 聊天会话不会自动触发 cron 任务。

如果你期望任务自动触发，需要一个正在运行的 gateway（hermes gateway 或 hermes serve）。对于一次性调试，你可以用 hermes cron tick 手动触发一次 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 任务没有输出或 agent 用 [SILENT] 响应，投递被抑制。这对于监控任务是故意的 — 但确保你的提示词不会意外抑制所有内容。

说"如果没有变化则响应 [SILENT]"的提示词也会静默吞下非空响应。检查你的条件逻辑。

检查 3：平台令牌权限​

每个消息平台 bot 需要特定权限来接收消息。如果投递静默失败：

  • Telegram：Bot 必须是目标群组/频道的管理员
  • Discord：Bot 必须有权在目标频道发送
  • Slack：Bot 必须被添加到工作区并有 chat:write 作用域

检查 4：响应包装​

默认情况下，cron 响应用 header 和 footer 包装（config.yaml 中的 cron.wrap_response: true）。某些平台或集成可能处理不好。要禁用：

cron:
  wrap_response: false

技能加载失败​

检查 1：验证技能已安装​

hermes skills list

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

检查 2：检查技能名称 vs. 技能文件夹名称​

技能名称区分大小写，必须与已安装技能的文件夹名称匹配。如果你的任务指定 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   # 必须存在
hermes cron edit <job_id> --script ~/.hermes/scripts/your-script.py

任务执行时的"技能未找到" 技能必须安装在运行调度器的机器上。如果你在机器之间移动，技能不会自动同步 — 用 hermes skills install <skill-name> 重新安装。

任务运行但不投递任何内容 可能是投递目标问题（参见上面的投递失败）或静默抑制的响应（[SILENT]）。

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

检查 3：锁竞争​

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

杀死重复的 gateway 进程：

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 * * *）以避免延迟。

大脚本输出​

转储兆字节输出的脚本会减慢 agent 并可能触及令牌限制。在脚本级别过滤/摘要 — 只发出 agent 需要推理的内容。

诊断命令​

hermes cron list                    # 显示所有任务、状态、next_run 时间
hermes cron run <job_id>            # 为下次 tick 调度（用于测试）
hermes cron edit <job_id>           # 修复配置问题
hermes logs                         # 查看最近 Hermes 日志
hermes skills list                  # 验证已安装技能

获取更多帮助​

如果你通过本指南排查后问题仍然存在：

  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 和调度
    • 投递目标
    • 你期望的 vs. 实际发生的
    • 来自日志的相关错误消息

完整 cron 参考，请参阅用 Cron 自动化任何事情 和定时任务 (Cron)。