【2026 最新】Agent Observability 是什麼？監看 Claude Code 工具、Token、成本與卡關位置

最後更新：2026年7月22日 · Terry Chen

Agent Observability 教學首圖：把 Claude Code 黑盒變成 Mission Control，監看 Logs、Traces 與 Metrics

你把一個改程式的任務交給 Claude Code，十分鐘後畫面還在轉。它是在認真跑測試、等待你的批准，還是第三次讀同一個檔案？Agent Observability 要解決的，就是這種「看得到 Agent 在動，卻不知道它有沒有前進」的焦慮。

先修正一個常見誤會：Claude Code 並不是完全沒有監控。現在官方已提供 /usage、/context、/insights、status line、hooks 與 OpenTelemetry（OTel）資料輸出。真正的缺口，是新手不知道每種訊號回答什麼問題，也不知道何時該從一行狀態列升級成「任務指揮中心」。

這篇專為第一次接觸 observability 的讀者寫。我們會先用白話建立心智模型，再安裝一個本機 dashboard，實際追蹤 Claude Code session；最後給你一組判讀「正常、繞路、疑似卡住」的規則。你不需要先懂分散式系統，也不會被一串縮寫淹沒。

這不是想像出來的需求。在 2026 年 7 月 22 日查閱的一則 r/ClaudeCode 求助帖中，開發者逐項詢問 tools、skills、模型、Token、成本與時間；另一則 Agentglass 展示討論則直接質疑「估算花費是否等於實際帳單」以及「慢任務會不會被誤判為卡住」。社群訊號能證明痛點存在，但技術事實仍要回到官方文件與原始碼。

Table of Contents

先說結論：Agent Observability 不是讀心術

Agent Observability ＝「發生什麼」＋「卡在哪裡」＋「花了多少」。

Logs / events 記錄發生什麼：讀檔、搜尋、執行命令、成功／失敗與批准結果。
Traces / spans 協助定位時間花在哪裡：一次任務怎麼穿過模型、工具、hook 與子代理，每一步各花多久。
Metrics 聚合資源與趨勢：Token、估算成本、延遲、錯誤率與 context 變化。

你觀察的是 Agent 留下的「工作腳印」，不是 Claude 未公開的內心推理。即使畫面顯示某段 API 等待了 20 秒，也只能說這段 request 花了 20 秒，不能把它命名成「思考 20 秒」。

Agent Observability 是什麼？先看懂三種訊號

Agent Observability 三種訊號：Logs 回答發生什麼、Traces 回答卡在哪裡、Metrics 回答花了多少 — Tool call 是 Agent 的工作單位；logs、traces、metrics 則是理解這些工作的三種視角。

1. Logs / events：像逐筆工作日誌

「Claude 呼叫了 Read」「Bash 測試失敗」「使用者拒絕這個工具」都是 event。單筆 event 最適合回答：剛剛發生了什麼？如果你要找重複讀檔、相同命令一直重試，第一站通常就是事件時間軸。

2. Traces / spans：像任務的行車紀錄器

Trace 把同一次使用者要求串成完整路徑，span 則是其中一段工作。Claude Code 現行 beta traces 可以把一個 interaction 拆成 LLM request 與 tool，tool 還能再區分「等待使用者批准」和「實際執行」。Hook span 另需額外的 detailed beta 設定與資格，不屬於本文的新手路線。所以你能分辨：它不是模型想太久，而是卡在 permission；也不是 permission，而是測試真的跑了六分鐘。官方的 span 結構可見 Claude Code Monitoring 文件。

3. Metrics：像汽車儀表板

Metric 是可聚合、可比較的數字。Claude Code 會直接輸出 input/output/cache Token、估算成本與 session count 等 metrics；觀測後端也能把 events／traces 聚合成 API 延遲、工具失敗率。單一事件告訴你「這次 Read 失敗」，聚合後的 metric 則能回答「最近一週 Read 的失敗率是不是突然升高」。OpenTelemetry 對 logs、metrics、traces 的正式定義，可參考 OTel Signals 官方文件。

Tool call 不是第四種訊號。它是 Agent 真正工作的單位：讀檔、改檔、執行測試、呼叫 MCP。你可以把一次 tool call 記成 event，也可以把它畫成 span，再把幾千次 tool call 聚合成 metric。

先別裝 dashboard：Claude Code 內建的第一層監控

截至 2026 年 7 月 22 日，Claude Code 官方最新 release 為 v2.1.217。先確認版本，避免照著新文件卻使用舊指令：

claude --version
claude update

接著從五個內建入口開始：

/usage：Token、成本與時間。看本 session 的 input/output/cache Token、依模型分組的用量、估算成本、API duration 與 wall duration。部分方案還能查看近期 skill、subagent、plugin 與 MCP 歸因，但它依本機歷史計算，不是跨裝置總帳。
/context all：Context 膨脹來源。它會拆出 system prompt、memory、skills、MCP tools 與 conversation。當 Agent 越跑越慢，先看是不是載入太多工具或對話，而不是先怪模型。
/insights：回顧摩擦點。它會產生歷史 session、專案區域、互動模式與 friction points 報告，適合定期回顧。
/statusline：把關鍵數字放在終端機底部。直接輸入 /statusline show model name and context percentage with a progress bar。Status line 在本機執行，不會額外消耗 API Token。它顯示的是最近一次 API response 的 context snapshot，不是 session 累積 Token；更新預設採事件驅動，並非連續串流，需要時可另設 refreshInterval。
claude agents：查看多個背景 session。Agent View 的官方介面聚焦 Working、Needs input、Completed 等狀態與 session activity；截至本文日期仍是 research preview。

白話說：如果你只想知道「context 還剩多少」或「這個 session 大概花多少」，內建工具已經夠用。想把多次 session 放在一起比較、回看每個 tool call，才需要下一層。指令細節可核對 /usage 官方說明與 status line 文件；更多背景可搭配 AlphaLab 的 Claude 省 Token 實戰，理解 cache、context 與成本為什麼會一起變化。

兩種常見 Agent Observability 路線：Transcript Scanner vs OpenTelemetry

Agent Observability 兩條路線比較：Transcript Scanner 適合個人快速回看，OpenTelemetry 適合團隊長期監控 — 兩條路線不是互斥：先用 scanner 建立直覺，有跨服務追蹤與集中告警需求時再加入 OTel。

路線 A：直接讀 Transcript，可回看既有歷史

Claude Code 預設把 session 放在 ~/.claude/projects/<project>/<session-id>.jsonl；若設定 CLAUDE_CONFIG_DIR，根目錄會跟著改變。JSONL 可以想成「每一行一筆 JSON 的流水帳」，通常含訊息、tool use 與 tool result；子代理資料則放在 parent session 底下。Scanner 可以讀取你安裝它以前的既有紀錄，所以非常適合個人除錯。

代價是耦合：Anthropic 明確說 transcript entry 是內部格式，可能隨版本改變。它也是 plaintext，prompt、檔案內容與命令輸出都可能留在電腦上；預設清理週期不等於「資料不敏感」。詳細路徑與限制見 Claude Code Sessions 官方文件。

路線 B：主動送出 OTel，適合長期與團隊

OpenTelemetry 是 vendor-agnostic、tool-agnostic 的 observability framework 與 toolkit，包含規格、協定與語意慣例。Claude Code 能主動輸出 metrics 與 events，distributed traces 目前則是 beta。你可以把資料送到 console 驗證，也可以接 OTLP 後端，做跨 session 查詢、保留政策、dashboard 與告警。

它的優勢是結構化與可攜；成本是你要管理 exporter、儲存、權限與敏感資料。OTel 已正式支援 traces、metrics、logs，但要把通用訊號與 GenAI 欄位的成熟度分開看：截至 2026 年 7 月 22 日，GenAI／agent semantic conventions 文件仍標示為 Development，欄位可能演進。不要把「使用開放標準」誤解成「永遠不用改設定」。來源見 OpenTelemetry GenAI Agent Spans。

實戰：安裝本機 Mission Control，追蹤 Claude Code session

這次示範使用開源的 Agentglass。它不是 Anthropic 官方產品，而是讀取 Claude Code transcript、可選擇接 hooks，並把 tool calls、Token、估算成本與時間軸整理成 dashboard 的第三方工具。GitHub API 在 2026 年 7 月 22 日顯示 191 stars、21 forks；這只能當早期採用訊號，不能當成熟度或安全性背書。

Agentglass README 明確說明 scanner 不需 hooks 即可載入既有歷史；本次寫作前也以 Claude Code v2.1.217、Bun 1.3.14 做過一次隔離環境驗證，結果相符。這只是一筆本機測試，不是對每個作業系統與未來版本的保證。

步驟 0：確認 Bun

bun --version

如果終端機找不到 Bun，可用官方列出的 npm 安裝方式，再重新開啟終端機：

npm install -g bun

Agentglass 原始碼安裝目前要求 Bun 1.1 以上；執行 hooks setup 需要 Python 3。Terminal 在 macOS／Linux 也優先用 Python 3 的 PTY bridge 支援即時 resize；Linux 缺 Python 時可退回 util-linux script，但功能較受限。下方環境變數與反斜線續行範例適用 macOS、Linux 與 WSL。請以 Bun 官方安裝文件與 Agentglass 最新 README 為準。

步驟 1：三段指令啟動 dashboard

git clone https://github.com/SirAllap/agentglass.git
cd agentglass && bun install
AGENTGLASS_ROOT=/path/to/your-project bun run dev

把 /path/to/your-project 換成要觀察的專案絕對路徑，然後開啟 http://localhost:6180。設定 AGENTGLASS_ROOT 的好處，是讓 cockpit 只顯示與操作指定專案；若不設定，工具會掃描這台機器上的所有 Claude 專案。它不是檔案隱私沙盒：scanner 仍要先開啟 transcript 判讀 cwd，既有資料庫裡的其他專案紀錄也不會因 scope 改變而自動刪除。

第一次先不要執行 bun run setup。這不是因為 setup 有錯，而是它會修改全域 ~/.claude/settings.json、安裝 hooks。先只用 transcript scanner 檢視既有紀錄，再決定是否需要更低延遲的即時事件，會比較容易理解每一層在做什麼。注意：Agentglass 本身還有 terminal、Git 等可寫能力，不能因為沒有裝 hooks 就把整個應用程式視為唯讀。

Agentglass Mission Control 本機 dashboard 官方示範畫面，顯示 session、事件、Token、估算成本與 radar — Agentglass 官方 demo dashboard；畫面為示範資料，不是作者的真實專案或帳單。來源：Agentglass GitHub。

步驟 2：跑一個可驗證的 Claude Code 任務

在目標專案另開終端機，給 Claude Code 一個範圍明確、最後能驗證的任務：

claude
請找出目前最慢的一個測試，先只分析原因，不要改檔；列出你讀過的檔案與執行過的命令。

回到 dashboard，不要先盯著漂亮的大數字，先回答四個問題：

事件時間軸有沒有持續出現新證據？
同一個檔案或命令是否在短時間反覆出現？
工具失敗後，Agent 有沒有改變方法？
Token / context 增加時，有沒有換來新發現、patch 或測試結果？

如果 UI 沒有立即更新，先重新整理並確認 session 的 project path，再看 transcript 是否有寫入。Dashboard 沒顯示事件，不等於 Agent 沒做事；scanner 解析、檔案寫入與遙測傳送本身都可能有延遲，OTel 也可能因設定錯誤、queue overflow、重試逾時或程序崩潰而遺失資料。

步驟 3（選用）：加 hooks，取得更即時的 tool event

bun run setup
# hooks 會從下一個 Claude Code session 起生效

# 想移除 Agentglass hooks 時
bun run setup:undo

Setup 會先備份並合併既有設定，但任何會改全域設定的腳本都值得先閱讀。Hooks 能得到 PreToolUse、PostToolUse、失敗與 duration 等資料；它們也可能看到完整工具輸入與結果，所以不是「開了就沒有代價」。

步驟 4：在共用電腦先縮小能力面

Agentglass API server 預設綁定 127.0.0.1，但 source dev 模式的 Vite UI 可能監聽所有介面，而且 localhost 也不等於多使用者隔離。它還包含 terminal、檔案瀏覽、chat、Git 與 Docker 操作面。若你只想看資料，可在啟動前關閉不需要的能力：

AGENTGLASS_TERMINAL_DISABLED=1 \
AGENTGLASS_FS_BROWSE_DISABLED=1 \
AGENTGLASS_CHAT_DISABLED=1 \
AGENTGLASS_GIT_WRITE_DISABLED=1 \
AGENTGLASS_DOCKER_WRITE_DISABLED=1 \
AGENTGLASS_COMMIT_DISABLED=1 \
AGENTGLASS_AUTOFETCH_SECONDS=0 \
AGENTGLASS_ROOT=/path/to/your-project \
bun run dev

這些開關是在縮小能力面，不是完整 filesystem sandbox；例如 AGENTGLASS_FS_BROWSE_DISABLED 只關閉 project picker 的目錄自動完成。若是共用機器，再依 Agentglass SECURITY.md 設定 AGENTGLASS_TOKEN。也不要把服務隨手綁到 0.0.0.0。Token 並不保護 /ingest 與 OTLP intake，因此同一台機器上的其他程序仍可能送入偽造遙測。它是 local-first，但不是「永不連網」：更新檢查、用量查詢、webhook、Git（設定 project scope 時預設會立即 fetch，之後定期 fetch；上例已關閉）或 chat 等功能都可能依設定產生外連。

進階：用 OpenTelemetry 看 Claude Code 的正式訊號

想先確認 Claude Code 到底會輸出什麼，不需要立刻架 Grafana。官方建議可以把 metrics 與 logs 先印到 console：

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_LOGS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000
export OTEL_LOGS_EXPORT_INTERVAL=5000
claude

送出一個 prompt 後，找 claude_code.session.count、claude_code.token.usage 或 claude_code.user_prompt。若沒有資料，執行 claude --debug，再到 debug log 查看 OTel exporter error。確認訊號後，再把 exporter 換成 OTLP、送往自己的 Collector 或觀測後端；完整變數以官方 Quick Start 為準。

只有真的要找完整 Bash command、file path 或 search pattern 時，才考慮開：

export OTEL_LOG_TOOL_DETAILS=1

新手預設不要開 OTEL_LOG_TOOL_CONTENT=1 或 OTEL_LOG_RAW_API_BODIES=1：前者需要先啟用 tracing，並可能輸出讀到的檔案與 Bash output；後者可能包含完整對話歷史。觀測資料本身也要當敏感資料管理。

完整追蹤範例：一個 flaky test 任務怎麼看？

假設你交代：「修好偶發失敗的登入測試，最後跑測試驗證。」一次合理路徑可能是：

讀測試與實作檔。Transcript scanner 會顯示 Read 了哪些檔；若走 OTel，需開 OTEL_LOG_TOOL_DETAILS=1 才會帶 file path。Trace 則顯示兩個 Read span 各花多久。
執行單一測試，重現失敗。Bash 回傳非零 exit code，但這是有價值的失敗，因為它產生 stack trace。
搜尋共享狀態。Agent 改用 Grep 找到測試間共用的 session cache，代表失敗後有換方法。
修改並再跑單一測試。這時 Token 增加，同時出現 patch 與新測試結果，資源消耗換來了進展。
跑相關 test suite。耗時可能最長，但 tool span 持續執行，這是「慢工作」，不一定是卡住。

反過來，Agentglass 目前的「possible loop」警示會把 30 分鐘內至少六次完全相同的 Bash 命令列為可疑；這只是現行程式碼中的啟發式範例，不是驗證過的通用分類器。真正值得人工介入的訊號，是相同錯誤反覆出現、context 持續上升，卻沒有新假設。重點不是失敗次數本身，而是失敗後有沒有產生新資訊。

想先理解 Agent 為什麼會「觀察 → 思考 → 行動 → 再觀察」，可讀 Agent Harness 是什麼；想看工作迴圈如何落成程式，再接著讀 30 行打造 AI Agent Harness。

建立「正常／繞路／疑似卡住」的判讀規則

以下是給個人 coding agent 的起始 heuristic（經驗規則），不是 Anthropic 官方分類器，也不保證適合每個專案。

正常：事件有前進，失敗能換來新證據

工具序列與目標相符：先讀、再查、修改、最後驗證。
失敗後改變輸入、範圍或工具，而不是原封不動重試。
Token / context 增長，同時出現新發現、patch 或測試結果。

繞路：資源在增加，工作狀態沒改變

短時間反覆讀同一檔案或執行相同命令，沒有新參數與新證據。
工具連續失敗，但錯誤訊息、假設與下一步都一樣。
大量掃描不相關目錄，或在明確任務中不斷擴大範圍。

疑似卡住：相對基準異常，而且沒有 evidence of life

不要設「五分鐘沒回覆就中止」這種全域秒錶。一次 build 可能正常跑十分鐘；若某次 Read 明顯超過它自己的歷史基準，才值得查看。較穩健的規則是：執行時間明顯超過同類工具的歷史 P95，且沒有新 event、檔案變動或輸出，再標成疑似卡住。這是本文提供的起始試探值，要依本機誤報率調整。接著先檢查三件事：是否等待 permission、是否為長測試／部署、是否只是 UI 更新延遲。最後才人工中止。

P95 可以想成「100 次裡有 95 次會在這時間內完成」。如果資料還不夠，就先用每種工具各自的粗略基準，累積足夠的同類樣本，再按照誤報情況調整。固定閾值很簡單，卻容易把慢任務誤報成卡住。

四個最常踩的坑：可觀測，不等於真相全開

把估算成本當帳單。Claude Code 的 /usage、status line、OTel cost metric，以及 Agentglass dashboard 顯示的美元值都是本機估算；訂閱方案的 session cost 與帳務無直接關聯。以供應商實際帳務為準。
把某個 tool call 當成所有 Token 的原因。官方 OTel 把 Token 放在 claude_code.llm_request span，tool span 另有近似的 result tokens；因此你能定位高成本 request，卻不能把整個 request 的 Token 都歸因給單一 Read。
為了「看更多」打開所有內容遙測。Prompt、file path、command、tool output 與 OAuth 身分欄位都可能敏感。先收 metadata，再按除錯目的逐項開啟。
把漂亮 dashboard 當品質保證。Agent 可以用很少 Token 做錯事，也可以用很多 Token 解對難題。Observability 幫你縮小問題位置，不能替代 code review、測試與人類判斷。

如果你的真正痛點是比較兩個 coding agent 的工作方式，而不是監控單一 session，可延伸閱讀 Claude Code vs Codex 客觀比較；若還分不清聊天介面、終端機工具與 Cowork，則先看 Claude vs Claude Code vs Cowork。

你該選哪一層？一分鐘決策

只想知道目前 session 的 Token、context 與時間：先用 /usage、/context all、/statusline。
個人想回看 tool timeline、找重複動作：加 transcript scanner；Agentglass 是一個可實作的開源選項。
需要即時 tool event 與低延遲：在看過腳本與備份設定後，再加 hooks。
團隊要長期留存、跨工具查詢、告警與權限：採 OTel，並設計 Collector、儲存、redaction 與 retention。
同時有個人除錯與團隊治理：混合使用。Scanner 補歷史與細節，OTel 負責標準化、聚合與跨系統關聯。

Agent Observability 常見問題 FAQ

1. Agentglass 是 Anthropic 官方工具嗎？

不是。它是由 SirAllap 維護、採 MIT 授權的第三方開源專案。Claude Code 官方能力與第三方 dashboard 要分開評估。

2. Dashboard 能看到 Claude 真正的思考內容或思考時間嗎？

不能這樣承諾。你能量到 LLM request、首 token、tool、permission 與整個 turn 的時間，也能看到被記錄的輸出；這些不是 private chain-of-thought。Claude Code 的 OTel raw-body 路線也會遮蔽 extended-thinking 內容。

3. 開監控會額外燒 Claude Token 嗎？

官方 status line 在本機執行，而且不消耗 API Token。使用者自訂的 status-line script 仍可自行連網。Transcript scanner 讀本機檔案，OTel exporter 傳遙測；它們仍會吃 CPU、I/O、網路與儲存。若你使用 dashboard 的「Explain」或 chat 功能，可能另行呼叫模型。

4. Dashboard 的 cost 就是信用卡會被收的金額嗎？

不是。它通常是依 Token 與本機價目表算出的估值，未知模型還可能套 fallback。訂閱方案 session 顯示的美元值不應拿來判斷帳務；實際費用以供應商帳務為準。

5. 一定要安裝 Claude Code hooks 嗎？

不一定。Agentglass 的 scanner 可以先讀既有 transcript；hooks 的價值是較低延遲的 hook event、各事件 payload 與 gating。先不裝、確認需要後再裝，是比較安全的學習順序。

6. 本機工具就代表資料一定不離開電腦嗎？

不能直接畫等號。遙測資料庫主要存本機，不代表所有功能都沒有外連；更新、Git、webhook、用量查詢與模型 chat 可能使用網路。也別忘了 plaintext transcript 本身就是敏感資料。

7. 什麼時候值得上 OpenTelemetry？

當你開始需要跨 session、跨 agent、長期留存或自動告警。一個人偶爾回看任務，scanner 更省事；團隊要比較基準、集中權限與追蹤跨服務路徑，OTel 才真正發揮價值。

8. 如何降低「卡住」的誤判？

固定分鐘數通常不可靠。用同類工具的歷史 P95、重複錯誤、事件是否前進、是否等待 permission 一起判斷，並把結果叫「疑似卡住」，最後由人類確認。

給新手的 5 個重點

先記住：Logs 看發生什麼、Traces 看卡在哪裡、Metrics 看花多少。
先用 Claude Code 內建 /usage、/context all、/statusline，不要一開始就架整套平台。
個人回看先選 transcript scanner；團隊治理與跨系統關聯再選 OTel。
成本是估算、卡住是 heuristic、時間不是內心推理；不要把 dashboard 讀成絕對真相。
觀測資料可能比原始碼更集中地收錄 prompt、命令與檔案內容，權限、遮蔽與保留週期要一起設計。

📚 延伸閱讀

Agent Harness 是什麼？——先懂 Agent 的模型與執行層如何組成。
如何打造 AI Agent Harness——用完整工作迴圈理解工具呼叫與 stop condition。
Claude 怎麼省 Token？——把 context、cache 與成本觀測接到實際優化。
Claude Code vs Codex——比較兩種 coding agent 的工作流與適用情境。
Claude vs Claude Code vs Cowork——釐清聊天、終端機與協作介面的差別。
當 AI 開始打造下一代 AI——從更大的視角理解 agent 工具鏈如何演進。
AlphaLab AI 專區——持續追蹤 AI 工具、方法論與實戰教學。
AlphaLab 課程——把 AI 工具落地成可重複的研究與工作流程。

結語：從「相信它」變成「看得見、量得到、能除錯」

Agent Observability 的目的，不是讓你盯著另一個更花俏的畫面，而是讓每一次介入都有證據。你知道它剛做了什麼、時間花在哪裡、資源換來什麼；看到重複錯誤時能提早換策略，遇到長測試時也不會因為焦慮就誤殺。

先從三個官方指令開始，接著用本機 scanner 回看一個真實任務。等你真的遇到跨代理、長期留存與告警需求，再升級 OpenTelemetry。這條路徑的核心一直沒變：發生什麼＋卡在哪裡＋花了多少。

免責聲明：本文為教育用途，資料查核至 2026 年 7 月 22 日。Claude Code、Agentglass 與 OpenTelemetry 仍可能快速更新，實作前請以 Claude Code Monitoring、Claude Code Costs、Status Line、Agentglass GitHub、OpenTelemetry Observability Primer與 GenAI Semantic Conventions為準。AI 具有輸出錯誤資訊的可能，重要決策請由人類複核。本文無業配內容。