sidebar_position: 12 title: “Cron Troubleshooting” description: “Diagnose and fix common Hermes cron issues — jobs not firing, delivery failures, skill loading errors, and performance problems”

Cron任务故障排查

当Cron作业无法按预期运行时，请按顺序进行以下检查。大多数问题可归为四大类别：时间设置、任务投递、权限问题或技能加载故障。

作业未能触发

检查1：确认作业存在且处于活跃状态

hermes cron list

请查找该任务，并确认其状态为 [active]（而非 [paused] 或 [completed]）。如果显示为 [completed]，则可能已用完重复执行次数——需编辑该任务以重置计数。

检查项 2：确认调度时间设置正确

格式错误的调度规则会默认以单次执行方式运行，或直接被拒绝。请测试您的表达式：

如果任务仅执行一次后就从列表中消失，说明这是单次执行调度（如 30m、1d 或 ISO 时间戳格式）——属于正常现象。

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

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

如果您希望任务能自动执行，就必须确保网关正在运行（前台模式可使用 hermes gateway，已安装的服务则可使用 hermes gateway start）。在临时调试时，可以使用 hermes cron tick 手动触发一次计时。

桌面应用： 桌面端的主后端会运行独立的计时器，同时监控每个本地配置文件中的cron存储——因此，即使某个配置文件的后端处于休眠状态，该配置文件下的任务仍会继续执行（桌面端会在约10分钟后让闲置的配置文件后端进入休眠状态）。您无需保持某个配置文件处于打开状态，其计划任务依然可以正常运行。

检查项4：检查系统时间与时区

任务会依据本地时区执行。如果您的机器时钟出现偏差，或所处时区与预期不同，任务将会在错误的时间被触发。请务必核实：

date
hermes cron list   # Compare next_run times with local time

交付失败

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

交付目标对大小写敏感，必须配置正确的平台。若目标配置错误，响应将会被静默丢弃。

其他支持的平台还包括 mattermost、homeassistant、dingtalk、feishu、wecom、weixin、bluebubbles、qqbot 以及 webhook。您也可以使用 platform:chat_id 语法指定特定聊天窗口作为目标（例如：telegram:-1001234567890）。

如果交付失败，任务仍会正常运行——只是不会发送到任何地方。您可以查看 hermes cron list 中的 last_error 字段（如有显示）以获取最新错误信息。

检查项 2：检查 [SILENT] 的使用情况

如果您的定时任务没有输出，交付功能将会被禁用。此外，若代理响应中包含定时任务静默标记 [SILENT]，交付功能同样会被禁用。这是为监控任务而设计的机制——但请确保您的提示语不会意外导致所有内容都被静默处理。

请使用如下提示语：“若无变化，则仅回复 [SILENT]。”避免要求智能体在较长的解释内容中加入 [SILENT]，因为 cron 会将该标记视为抑制信号。

检查项 3：平台令牌权限

每个消息平台机器人都需要特定的权限才能接收消息。如果消息发送失败且无任何反馈：

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

检查项 4：响应封装

默认情况下，cron 的响应会带有页眉和页脚（在 config.yaml 中设置为 cron.wrap_response: true）。某些平台或集成可能无法正确处理这种格式。如需禁用该功能：

cron:
  wrap_response: false

检查项 5：通过中继连接的平台（Hermes Cloud / Team Gateway）

当平台的凭证存储在中间件连接器中（例如由 Team Gateway 托管的 Slack 或 Discord 平台），而非本地的 .env 文件中时，正在运行的网关所关联的实时中继适配器是唯一的发送方——不存在独立的发送路径。

• 只要网关处于运行状态，定时触发的工作任务即可正常执行：其调度机制会负责通过中继连接进行发送。
• 独立的 hermes cron run <id> 命令会自动通过 api_server（POST /api/jobs/{id}/run）将任务转发给网关。为此，需在 api_server 平台上启用并设置长度为 16 位以上的 API_SERVER_KEY。该命令还会同时传递 --prompt 参数或 cronjob(action='run', prompt=...) 上下文选项，且这些选项仅适用于当前此次触发任务。
• 如果无法连接到网关，任务将会因“通过中继连接的平台……请启动网关”这样的错误而失败，而不会出现“平台 ‘slack’ 未配置/未启用”这类容易产生误解的提示。请先启动网关，然后再试。

技能加载失败

检查项 1：确认技能已安装

hermes skills list

在将技能添加到定时任务之前，必须先安装这些技能。如果某个技能缺失，请使用 hermes skills install <skill-name> 命令或通过 CLI 的 /skills 接口进行安装。

检查 2：确认技能名称与文件夹名称是否一致

技能名称是区分大小写的，且必须与已安装技能的文件夹名称完全匹配。如果您的任务指定了 ai-funding-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：常见错误模式

脚本相关的“找不到文件或目录”错误 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> 命令重新安装。

任务虽已运行但无输出结果 可能是交付目标存在问题（参见上文“交付失败”部分），或者没有生成任何输出，又或是响应中包含了 cron 的静默标记 [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

性能问题

任务启动缓慢

每个定时任务都会创建一个新的 AIAgent 会话，这一过程可能涉及服务提供者身份验证以及模型加载。对于对时间要求严格的调度任务，请预留足够的缓冲时间（例如将时间设置为 0 8 * * * 而非 0 9 * * *）。

重叠任务过多

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

脚本输出量过大

生成大量输出数据的脚本会降低代理的处理速度，还可能超出令牌限制。应在脚本层面对输出进行过滤或汇总，仅传递代理所需的信息以供处理。

诊断命令

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）。