<!-- Source: https://hermesbible.com/docs/guides/cron-troubleshooting -->

當定時任務未如預期運作時，依序進行以下檢查。大多數問題屬於四個類別之一：時間、傳遞、權限或技能載入。

---

工作未觸發

檢查 1：驗證工作存在且處於啟用狀態

hermes cron list

尋找該工作並確認其狀態為 [active]（非 [paused] 或 [completed]）。如果顯示 [completed]，重複次數可能已耗盡 — 編輯工作以重置它。

檢查 2：確認排程正確

格式錯誤的排程會靜默地預設為一次性或完全被拒絕。測試你的表達式：

如果工作觸發一次後從清單中消失，那是一次性排程（30m、1d 或 ISO 時間戳）— 這是預期行為。

檢查 3：閘道是否在執行？

定時任務由閘道的背景嘀嗒執行緒觸發，每 60 秒嘀嗒一次。正常的 CLI 聊天工作階段不會自動觸發定時任務。

如果你期望工作自動觸發，你需要一個運行中的閘道（前台執行 hermes gateway，或安裝的服務執行 hermes gateway start）。對於一次性除錯，你可以使用 hermes cron tick 手動觸發嘀嗒。

檢查 4：檢查系統時鐘和時區

工作使用本地時區。如果你機器的時鐘不正確或與預期不同的時區，工作會在錯誤的時間觸發。驗證：

date
hermes cron list   # 將 next_run 時間與本地時間比較

---

傳遞失敗

檢查 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：回應包裝

預設情況下，定時回應會被標頭和頁尾包裝（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   # 你的使用者應該擁有它

---

效能問題

工作啟動緩慢

每個定時任務建立一個全新的 AIAgent 工作階段，可能涉及供應商認證和模型載入。對於時間敏感的排程，添加緩衝時間（例如 0 8 * * * 而非 0 9 * * *）。

太多重疊的工作

排程器在每個嘀嗒內依序執行工作。如果多個工作同時到期，它們會一個接一個地運行。考慮錯開排程（例如 0 9 * * * 和 5 9 * * * 而非兩者都是 0 9 * * *）以避免延遲。

大量腳本輸出

輸出數百萬位元組的腳本會拖慢代理程式並可能觸達代幣限制。在腳本層級過濾/摘要 — 僅輸出代理程式需要推理的內容。

---

診斷指令

hermes cron list                    # 顯示所有工作、狀態、next_run 時間
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 和排程
   • 傳遞目標
   • 你的預期 vs. 實際發生的
   • 日誌中的相關錯誤訊息

---

完整定時參考，請參閱使用 Cron 自動化任何事和定時任務 (Cron)。

---

---

Google Gemini