跳到主要内容

定时任务排错指南

当定时任务表现不符合预期时，请按顺序进行以下检查。大多数问题可归入以下四类之一：时间调度、投递、权限或技能加载。

任务未触发​

检查 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日 UTC 时间上午 9:00

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

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

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

如果你希望任务自动触发，你需要一个正在运行的网关（使用 hermes gateway 进行前台运行，或使用 hermes gateway start 启动已安装的服务）。若仅用于一次性调试，你可以使用 hermes cron tick 手动触发一次检查。

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

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

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

投递失败​

检查 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 主服务器
email在 config.yaml 中配置了 SMTP
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] 的使用​

如果你的定时任务没有产生输出，或者智能体回复了 [SILENT]，那么投递会被抑制。这对于监控任务是有意为之 — 但请确保你的提示词没有意外地抑制了所有输出。

一个提示词如果写着“如果没有变化请回复 [SILENT]”，那么即使是非空的响应也会被静默吞掉。请检查你的条件逻辑。

检查 3：平台令牌权限​

每个消息平台的机器人需要特定的权限才能接收消息。如果投递静默失败：

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

检查 4：响应包装​

默认情况下，定时任务的响应会被包装上页眉和页脚（config.yaml 中的 cron.wrap_response: true）。某些平台或集成可能无法很好地处理这种情况。要禁用：

cron:
  wrap_response: false

技能加载失败​

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

hermes skills list

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

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

技能名称是大小写敏感的，并且必须与已安装技能的文件夹名称匹配。如果你的作业指定了 ai-funding-daily-report，但技能文件夹是 ai-funding-daily-report，请通过 hermes skills list 确认确切的名称。

检查 3：需要交互式工具的技能​

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

请查看该技能的文档，确认它能在非交互式（无头）模式下工作。

检查 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：常见错误模式​

脚本报错 "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" 该技能必须安装在运行调度器的机器上。如果你在不同的机器间切换，技能不会自动同步 — 请使用 hermes skills install <skill-name> 重新安装它们。

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

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

检查 3：锁竞争​

调度器使用基于文件的锁来防止重叠的检查周期。如果两个网关实例正在运行（或者一个 CLI 会话与网关冲突），任务可能会被延迟或跳过。

终止重复的网关进程：

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

检查 4：jobs.json 文件权限​

任务存储在 ~/.hermes/cron/jobs.json 文件中。如果你的用户无法读取/写入此文件，调度器将静默失败：

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

性能问题​

任务启动缓慢​

每个定时任务都会创建一个新的 AI智能体会话，这可能涉及提供商身份验证和模型加载。对于时间敏感的调度，请添加缓冲时间（例如，使用 0 8 * * * 而不是 0 9 * * *）。

太多任务同时运行​

调度器在每个检查周期内顺序执行任务。如果多个任务在同一时间到期，它们会一个接一个地运行。考虑错开调度计划（例如，使用 0 9 * * * 和 5 9 * * * 而不是两者都用 0 9 * * *）以避免延迟。

脚本输出过大​

输出大量数据的脚本会拖慢智能体的速度，并可能触达令牌限制。请在脚本层面进行过滤/摘要 — 只输出智能体推理所需的必要信息。

诊断命令​

hermes cron list                    # 显示所有任务、状态、下次运行时间
hermes cron run <job_id>            # 计划在下一次检查周期运行（用于测试）
hermes cron edit <job_id>           # 修复配置问题
hermes logs                         # 查看最近的 Hermes 日志
hermes skills list                  # 验证已安装的技能

获取更多帮助​

如果你已按照本指南操作但问题仍然存在：

  1. 使用 hermes cron run <job_id> 运行该任务（将在下一次网关检查周期触发），并在聊天输出中观察错误信息
  2. 检查 ~/.hermes/logs/agent.log 文件中的调度器消息和 ~/.hermes/logs/errors.log 文件中的警告信息
  3. 在 github.com/NousResearch/hermes-agent 上提交 issue，并附上：
    • 任务 ID 和调度计划
    • 投递目标
    • 你的预期行为与实际发生了什么
    • 日志中相关的错误信息

有关定时任务的完整参考，请参阅使用定时任务自动化任何事和定时任务（Cron）。