跳到主要內容

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   # 將 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 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 任務無輸出，或 Agent 返回 [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   # 必須存在
hermes cron edit <job_id> --script ~/.hermes/scripts/your-script.py

作業執行時提示“技能未找到” 該技能必須安裝在運行調度器的機器上。若在不同機器間切換，技能不會自動同步——請使用 hermes skills install <skill-name> 重新安裝。

作業運行但未交付任何內容 很可能是交付目標存在問題（參見上方“交付失敗”部分），或響應被靜默抑制（[SILENT]）。

作業卡住或超時 調度器使用基於非活動狀態的超時機制（默認 600 秒，可通過 HERMES_CRON_TIMEOUT 環境變量配置，設為 0 表示無限制）。只要 Agent 持續調用工具，其運行時間就不會受限制——計時器僅在長時間無活動後觸發。對於長時間運行的任務，應使用腳本處理數據收集，僅交付最終結果。

檢查項 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   # 您的用戶應該擁有它

性能問題​

作業啟動緩慢​

每個 Cron 作業都會創建一個全新的 AIAgent 會話，可能涉及提供方認證和模型加載。對於時間敏感的調度任務，建議增加緩衝時間（例如使用 0 8 * * * 而非 0 9 * * *）。

重疊作業過多​

調度器在每個週期內按順序執行作業。如果多個作業在同一時間觸發，它們將依次運行。建議錯開調度時間（例如使用 0 9 * * * 和 5 9 * * *，而非都設為 0 9 * * *），以避免延遲。

腳本輸出過大​

輸出量達到數兆字節的腳本會拖慢 Agent 運行速度，並可能觸及 token 限制。應在腳本層面進行過濾或摘要處理——僅輸出 Agent 推理所需的內容。

診斷命令​

hermes cron list                    # 顯示所有作業、狀態、next_run 時間
hermes cron run <job_id>            # 下一個報價的時間表（用於測試）
hermes cron edit <job_id>           # 修復配置問題
hermes logs                         # 查看最近的Hermes日誌
hermes skills list                  # 驗證已安裝的 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）。