AI 代理監控：Claude Code 如何捕捉無聲故障

AI 代理監控意味著追蹤自主代理每次執行時的行為、產出和成本，以便在使用者或資料受到影響之前發現故障。如果您是個人開發者，定期執行 Claude Code，則可以跳過企業級的 OpenTelemetry 儀表板。透過檢查代理預期輸出的 Claude Code Stop hook、記錄 total_cost_usd 的 cron 包裝器，以及免費的心跳檢查，就能捕捉大多數無聲故障，例如夜間彙總「完成」卻未寫入檔案的情況。

哪種選項適合您呢？請從最便宜且能告知任務失敗的設定開始。只有當單一日誌行無法解釋失敗原因時，才添加追蹤功能。

以下是針對不同情境的監控建議：對於初學者，只有一個排程的 Claude Code 任務，建議使用 cron 包裝器、輸出檢查和免費的心跳服務（Healthchecks.io，業餘方案免費）。若為日常工作使用，有多個重複性任務，則可使用 Stop/StopFailure hook 寫入 JSONL 執行日誌，並為每個任務添加心跳檢查。

對於預算敏感且使用 API 金鑰計費的用戶，建議使用 --output-format json 進行成本記錄，並設定 --max-budget-usd 上限。

如果您想在不運行伺服器的情況下獲得圖表，可以將 Claude Code 的 OpenTelemetry 匯出功能整合到 Grafana Cloud 免費方案。若應用程式是基於 LangGraph 建構的多代理系統，則 LangSmith 開發者方案（每月 5k 追蹤免費）會是好選擇。對於已有 Datadog 或 Splunk 合約的公司，則應使用其供應商的代理可觀察性產品。

選擇這些方案的原因在於：初學者方案無需費用，能捕捉「從未執行」和「執行但無產出」的問題。日常使用方案則增加了可供搜尋的歷史記錄。預算方案則能在命令列層級阻止失控的開銷。越往下的方案雖然增加了可見性，但也需要更多供應商帳戶和設定。

AI 代理監控是指記錄代理每次執行時的行為、產出和完成情況。這些記錄能幫助您偵測錯誤、漂移和無聲故障。傳統的正常運行時間監控只問程序是否存活，而代理監控則問工作是否完成。Datadog 的 AI 可觀察性解釋器將兩者區分為「不僅回答系統是否運行，還要回答其輸出是否正確、有根據、安全且有用」。

對於個人開發者而言，每次執行有三件事需要關注：程序結果，即 claude -p 是否以代碼 0 退出（成功）；工作結果，即產物是否存在、是否最新，以及是否包含合理數據（這需要自行定義）；以及成本和行為，即執行花費多少、進行了多少輪次，以及是否遇到 API 錯誤。

舉一個無聲故障的例子：假設一個夜間任務要求 Claude Code 將昨天的訂單彙總到 reports/daily-2026-10-22.csv。如果來源 API 返回空頁面，Claude 寫入一個只有標頭的 CSV 檔案，解釋說「沒有找到訂單」，然後以代碼 0 退出。

此時，所有程序層級的訊號都是綠色的，但您的每週營收圖表卻悄悄地少了一天。一個常見的陷阱是將代理的最終訊息視為狀態，因為模型可能聽起來很有自信，但檔案卻是空的，因此務必檢查檔案本身。

AI 監控與 AI 代理監控有何不同？AI 監控是一個總稱，泛指監測任何 AI 系統，包括模型、數據和輸出。AI 代理監控則將重點縮小到呼叫工具並自主行動的多步驟執行。一般 AI 監控關注模型呼叫或預測的延遲、錯誤率、漂移和輸出品質分數，典型故障是錯誤或降級的答案，主要由服務模型的機器學習團隊使用。

AI 代理監控則關注整個執行過程，包括提示詞、工具呼叫和寫入的檔案，其典型訊號是任務完成度、工具故障、循環、重試和每次執行的成本，典型故障是錯誤的行動、跳過的步驟或「成功」卻沒有輸出，主要適用於讓代理執行重複性工作的人。Datadog 的解釋器將代理特定部分描述為追蹤「多步驟決策鏈、監控工具選擇和執行，以及偵測代理循環和失控行為」。

例如，如果您只呼叫 Claude API 來分類支援工單，那麼一般的 AI 監控（樣本準確性、延遲、成本）就足夠了；但一旦 Claude Code 讀取檔案、運行腳本並撰寫報告，您就需要知道哪個步驟出了問題。

什麼是監控代理？監控代理可以是安裝在主機上的收集軟體，例如 Datadog Agent，也可以是負責監控其他代理的 AI 代理。這兩種含義在搜尋結果中容易混淆。傳統的定義是前者：「Datadog Agent 是運行在您主機上的軟體」，它收集指標和日誌並傳送到後端，不涉及 AI。

較新的含義是判斷另一個代理工作的 LLM（大型語言模型）。Claude Code 直接支援這一點，除了 shell 命令 hook 之外，它還有 prompt 和 agent hook 類型，預設逾時分別為 30 秒和 60 秒，而命令 hook 為 600 秒。

一個 prompt 類型的 Stop hook 可以詢問模型執行是否真的完成了任務。陷阱與解決方案：判斷者是非確定性的且會消耗 token。應優先使用確定性的 shell 檢查，例如檔案是否存在、行數、是否為有效的 JSON。只有當腳本無法回答的問題（例如「這份摘要是否忠於原文？」）

才添加 LLM 判斷者。此外，監控者也可能無聲失敗，如果監控代理崩潰，將不會有任何警報。因此，應搭配外部心跳服務（下文會介紹），它會預期收到 ping，並在未收到時發出警報。

代理式監控與無代理式監控有何不同？代理式監控會在機器上安裝收集器，以獲取深入的即時數據。無代理式監控則透過 API 發送或拉取數據，設定較少且細節較少。代理式監控需要安裝和更新守護程式（例如 Datadog Agent、OTel Collector），能提供主機指標、程序數據和本地日誌，但需要維護升級、配置和主機資源使用，對於個人開發者而言，在單一筆記型電腦或 5 美元虛擬私人伺服器上顯得過度。

無代理式監控則無需守護程式，透過 HTTP 或 OTLP 推送數據，或輪詢 API，僅能獲取明確發送的數據，維護工作極少，通常適合個人開發者。本指南中的 hook 式設定屬於無代理式。Claude Code 本身透過 hook 或內建的 OpenTelemetry 匯出器發送數據，並透過 curl 發送心跳。

Claude Code 的匯出器可以與收集器對話，或直接連接到 OTLP 端點。您可以設定 OTEL_EXPORTER_OTLP_ENDPOINT，並為 OTEL_METRICS_EXPORTER 選擇 otlp、prometheus、console 或 none。

陷阱是，採用無代理式後，卻假設能看到主機問題，例如磁碟已滿或 cron 守護程式死亡，這些都不會出現在 Claude Code 的遙測數據中，因為 Claude Code 根本沒有啟動。解決方案是：外部心跳服務能捕捉「完全沒有運行」的情況，這正是無代理式設定所遺漏的環節。

單一代理與多代理：哪個需要更多監控？多代理系統需要更多監控，因為故障通常發生在代理之間的交接點。單一代理可以透過一次執行結束檢查來監控。單一代理的故障通常隱藏在最終輸出和工具錯誤中，最低限度的訊號是 Stop hook、退出代碼和產物檢查，成本風險是一個上下文視窗。

多代理系統的故障則隱藏在交接、子代理的部分結果和共享狀態中，最低限度的訊號是每個代理的完成事件和連結它們的追蹤，Claude Code 除了 Stop hook 外，還需 SubagentStop hook（當子代理完成時），成本風險更高，因為代理團隊在計畫模式下運行時，使用的 token 約是標準會話的七倍。

在 Claude Code 內部，SubagentStop 接收與 Stop 相同的欄位，包括 last_assistant_message。在無頭執行中，--output-format stream-json 會用 parent_tool_use_id 標記每個子代理訊息，以便您分辨哪個子代理說了什麼。

在 Claude Code 之外，當設定了 LangSmith 環境變數時，LangGraph 應用程式會將追蹤發送到 LangSmith。在子代理追蹤文件中，您可以透過 lc_agent_name 中繼資料鍵進行過濾。供應商中立的標準是 OpenTelemetry 的 GenAI 代理 span，例如 invoke_agent 和 execute_tool，但該規範仍標記為「開發中」，因此屬性名稱可能會改變。

例如，如果一個研究子代理返回「沒有找到來源」，而寫作子代理仍然起草了一篇文章，那麼記錄每個子代理最後訊息的 SubagentStop hook 將會在您的執行日誌中顯示這個空的交接。每個角色的模型選擇也對成本很重要。

如何追蹤 AI 代理成本？要追蹤 AI 代理成本，請從每次 claude -p --output-format json 執行中記錄 total_cost_usd，並按任務將這些數字加總。使用 --output-format json 時，Claude Code 的回應「包含 total_cost_usd 和每個模型的成本明細」。

文件也警告說：「這兩個數字都是客戶端估計值，可能與您的實際帳單不同。」作為參考，Anthropic 報告指出，在企業部署中，「每個活躍開發者每天的平均成本約為 13 美元」，90% 的使用者每天活躍成本低於 30 美元（截至 2026 年 10 月，請查閱官方頁面）。

一個無人值守的任務應該只花費其中一小部分，如果不是，則需要調查。具體步驟包括：使用 --output-format json 運行您的任務，並透過 jq -r '.total_cost_usd' 管道輸出。每次運行後，追加一行 CSV 數據，包含日期、任務名稱、退出代碼和成本。

使用 --max-budget-usd（一個有文件記錄的 CLI 標誌）添加硬性上限，例如，對於通常花費 0.30 美元的任務設定 --max-budget-usd 2。如果執行達到上限，Claude Code 也會停止任何剩餘的背景工作。

每週一次，按成本排序 CSV 數據，如果一個任務在輸入沒有變化但成本翻倍，通常表示正在循環或重試。要獲取 API 計費的權威數字，請使用 Claude Console 中的「使用量」頁面。如果您使用 Pro 或 Max 訂閱而非 API 金鑰，則美元數字並非您的帳單。

使用量文件說明「Claude Max 和 Pro 訂閱者的使用量已包含在訂閱中」，在這些方案下，請檢查使用量頁面以了解方案使用情況，而非依賴美元估計值。有關完整教學，請參閱 /claude-code-how-to-see-token-usage-and-reduce-it/。

陷阱是：--continue 和 --resume 會報告整個對話的總成本，包括之前的運行，將這些值加總會導致重複計算。因此，請將每個排程任務作為一個新的會話啟動，或者只記錄差異。

哪些 AI 代理監控工具適合個人開發者？對於個人而言，免費的心跳服務加上 Claude Code hook 就能滿足大多數需求。Datadog、Splunk 和 AppDynamics 等企業級套件主要在您已經付費使用的情況下才有意義。Claude Code hook 加上日誌檔案能提供執行層級檢查和 JSONL 歷史記錄，費用為 0 美元，但不適用於需要共享儀表板的團隊，且檢查需自行編寫和維護。

Healthchecks.io 則在任務未發送 ping 或發送 /fail 時發出警報，業餘方案免費，適用於 20 個任務和 100 條日誌，但僅知道「是否發送 ping」，無法提供詳細原因。Grafana Cloud 可為 Claude Code 的 OTel 指標提供圖表，免費方案包含 1 萬個活躍序列、50 GB 日誌和 14 天保留期，供 3 位使用者使用，但儀表板和警報需自行設計。

LangSmith 為 LangGraph/LangChain 應用程式提供逐步追蹤，開發者方案免費，包含 1 個席位和每月 5k 基本追蹤，但最適合 LangChain 生態系統內的純 Claude Code CLI 任務。Datadog Agent Observability 提供工具、交接、重試和錯誤的圖表，但價格未公開，不適用於沒有 Datadog 帳戶的個人開發者。

Splunk AI Agent Monitoring 監控效能、品質、token 和預估成本，為企業定價，不適用於小型團隊，且 Splunk 表示該產品「預計將被棄用」。AppDynamics AI Agent Monitoring 提供 LLM 應用程式效能和使用情況的儀表板，為企業定價，不適用於沒有內部部署 AppDynamics 的用戶，且需要 Python Agent 和 Events Service。