Claude Code 支出追蹤工具比較：日誌、用量與 OTel

Claude Code 支出追蹤工具實際讀取的資料

每個 Claude Code 支出追蹤工具都會讀取 3 種資料來源之一，而資料來源會決定它能回答哪一類問題。日誌解析器會讀取儲存在本機磁碟上的工作階段文字記錄檔。儀表板會讀取 Anthropic 為你的帳戶或組織保留的使用量記錄。指標後端會讀取你啟用 Claude Code 後所發出的 OpenTelemetry (OTel) 串流。這 3 種工具可能同時正確，卻仍然顯示不同結果，因為它們計算的是不同項目。

本指南不會重新解釋 token。Claude Code 如何計算 token 使用量涵蓋輸入、輸出、快取寫入與快取讀取；在釐清這些內容前，任何儀表板的資訊都缺乏完整意義。本節只聚焦於較狹窄的問題：對於每一類工具，它能看見什麼，以及永遠無法看見什麼。

為什麼同一天出現 3 個 Claude Code 用量追蹤工具

同一天發布了 3 個不同的 Claude Code 用量追蹤工具。它們不是同一工具的 3 個版本，這正是重點所在。其中 1 個會解析本機工作階段檔案；1 個會包裝帳戶用量頁面；另 1 個則是由你自行執行的代管式追蹤後端。

它們會同時出現，是因為 agent 工作階段的成本不再一目了然。聊天的成本大致可從畫面上看到；agent 會讀取 20 個檔案、執行測試套件，並在每一輪重新傳送完整對話，因此帳單取決於你從未輸入的內容。在訂閱方案中，甚至完全看不到美元金額，只有用量列會在某些日子比其他日子更快耗盡。這 3 種工具分別填補了這個缺口的不同部分。

方法 1：使用本機日誌解析器了解今天的用量成本

Claude Code 會將每段對話以 JSON Lines (JSONL) 格式儲存在 ~/.claude/projects/<project>/<session-id>.jsonl，其中 <project> 是工作目錄路徑，非英數字元會替換為 -。該檔案中的每次 assistant 回合都包含此次請求的 token 數量。日誌解析器會加總這些數量並計算價格。

ccusage 是多數人最後採用的工具。它不需要安裝：

npx ccusage@latest daily
npx ccusage@latest daily --breakdown
npx ccusage@latest blocks
npx ccusage@latest session --json

daily 依日期計算總量。--breakdown 依模型拆分每筆資料，藉此找出某個使用 Opus 的下午是否占了一週用量的大部分。blocks 依訂閱重設的五小時時段分組。session 依對話計算總量，--instances 則依專案分組，讓你看出哪個 repository 成本較高。加入 --since 和 --until 可限制日期範圍，並執行 npx ccusage@latest daily --help 以確認你的版本所要求的日期格式。截至 August 2026，它也能讀取其他 agent CLI，包括 Codex 和 OpenCode；如果你要比較這些工具，這項功能很實用。

價格來自模型價格表，而此工具提供 3 種成本模式。--mode auto 會優先使用 Claude Code 寫入檔案的 costUSD 值；如果沒有該值，則依 token 數量計算。--mode calculate 一律依 token 計算，忽略任何已記錄的成本。--mode display 只顯示已記錄的成本，沒有記錄成本的資料列則輸出 $0.00。如果總額看起來不正確，請先使用 calculate 執行相同報表，再使用 display 執行一次。兩者差距很大，表示大多數項目都沒有已記錄的成本，因此你看到的全部都是估算值。

相同資料也能提供給提示列使用。ccusage statusline 會輸出一行精簡資訊，供 Claude Code 狀態列顯示；將它如同其他狀態列命令一樣接到 ~/.claude/settings.json 即可。設定區塊及其接收的欄位，請參閱 建立 Claude Code 狀態列。

日誌解析器無法看見未在這台機器上發生的活動。另一台筆電、claude.ai 上的工作階段，或團隊成員的工作，其轉錄資料都儲存在各自的磁碟上。舊資料也可能已遺失，因為在 cleanupPeriodDays 設定下，轉錄資料預設會在 30 天後清理；除非你曾經封存，否則上一季的資料已不存在。

還有一項結構性風險。Anthropic 的文件指出，項目格式屬於 Claude Code 的內部格式，且會隨版本變更，因此直接解析這些檔案的腳本可能在任何版本發布時失效。所有採用這種方式的工具都適用這項限制。這也是自行撰寫 jq JSONL 單行命令不像看起來那麼理想的原因：受維護的解析器會替你追蹤格式變更，而欄位重新命名的當天，你的單行命令就可能回報一個看似可靠但實際錯誤的數字。

最後，訂閱方案中的美元金額需要加以說明。Pro 或 Max 不會按 token 計費，因此這個數字代表按照 API 公開定價計算時，你的 token 原本會產生的成本。它衡量的是使用量的多寡，不是你的實際帳單。如果你真正想知道的是應該選擇哪個方案，則需要另行比較；請參閱 API 計費與 Claude 訂閱方案的比較。

方法 2：內建用量畫面會顯示是哪個模型消耗了預算

Claude Code 內建報表，但大多數人從未開啟。請在工作階段中執行 /usage。頂端的 Session 區塊會顯示各模型使用的 token 數量，以及目前工作階段的金額。該金額是根據 token 數量與標準牌價，在本機計算而得。這個數字不包含折扣或促銷價格，因此可能與帳單不同。/clear 開始新的對話時，總數會重設。

在 Pro、Max、Team 或 Enterprise 方案中，同一個畫面也會顯示已使用的方案額度，並以總用量百分比標示近期用量分別來自 skills、subagents、plugins 與個別 MCP servers 的比例。若某些行為占近期用量的 10% 以上，畫面會加以標示，例如較長的 context 或 cache miss。按下 d 或 w，即可在最近 24 小時與最近 7 天之間切換。這些數字是約略值，根據這台機器的本機工作階段歷程計算，因此不會計入第二台裝置的用量。當該長條為空白，而不只是數值偏低時，畫面會告知你此用量視窗已關閉，但不會說明如何繼續工作；達到額度上限後該怎麼做則是另一項涉及模型、context 與方案的決策。

當開發人員超過 1 人時，數字會移至帳戶層級。API 組織可使用 Console usage 頁面、顯示每位成員支出與 accepted lines 的 Claude Code dashboard，以及使用 admin key 後回傳相同每日個人指標的 Claude Code Analytics API。Teams 與 Enterprise 方案可在管理主控台取得每日更新並支援 CSV 匯出的支出報表；Enterprise 另提供 analytics API。你能看到哪些內容，取決於每位開發人員的登入方式，因此混合型組織必須查看兩份報表，再手動加總。

若要估算預算，Anthropic 成本文件截至 August 2026 公布的數字為：每位開發人員每個工作日平均約 $13，每月約 $150 至 $250，且 90% 的使用者每個工作日低於 $30。請將這些數字視為 enterprise deployment 的公開基準，不要當作團隊成本的預測。先讓一小組進行試行並測量，再外推結果。

dashboard 無法辨識的是低於每日及個人層級的資訊。它們會告訴你 Opus 佔用了週二的大部分用量，但不會告訴你是哪個 prompt、哪個 repository 或哪個 CI job 所造成。報表也會延遲，因為組織層級報表每日更新，因此適合用於檢討，不適合用來在今天下午攔截失控的 agent。要攔截失控的 agent，需要的是限制，而不是報表；這就是 在 VPS 上限制 agent 成本的主題。

形式 3：自行建置的 OpenTelemetry stack 告訴你是哪個 prompt 退步

設定一個環境變數後，Claude Code 會產生 OpenTelemetry metrics 和 events。這是唯一能將每位使用者的 token 與 cost data，近乎即時串流到你所控制系統的選項。這些 metrics 包含 claude_code.cost.usage（以 USD 計）、claude_code.token.usage（以 tokens 計）、claude_code.session.count 和 claude_code.active_time.total。

Token metric 的重點在於其 attributes。每個 data point 都帶有 type，其值可能是 input、output、cacheRead 或 cacheCreation，以及 model 和 query_source，其值可能是 main、subagent 或 auxiliary。此外還包含 agent.name、skill.name、mcp_server.name 和 mcp_tool.name。這足以回答任何 dashboard 都無法回答的問題：帳單中有多少來自 subagents，而不是你自己的 turns；某個 MCP server 是否讓 input tokens 加倍；有人修改 CLAUDE.md 後，cache reads 是否大幅下降。Cache 行為通常是意外成本的來源，而prompt caching 何時能回本會說明如何解讀這些資料。

有一點需要更正，因為每個相關討論串都會提到這件事。Langfuse 是適合 self-hosted 的 tracing backend，在 VPS 上執行 Langfuse 的方式請參閱自行託管 Langfuse 進行 agent tracing。它的 OTLP endpoint 只接受 traces。Claude Code 匯出的是 metrics 和 log events，不是 spans，因此將 OTEL_EXPORTER_OTLP_ENDPOINT 指向 Langfuse 只會讓專案保持空白，也不會提供任何值得閱讀的錯誤訊息。對於你自行透過 API 建置的 agents，Langfuse 才是正確工具，因為你自己的程式會為每個 span 建立 prompt、model 和 cost。至於 Claude Code CLI，metrics store 才是相符的選擇。

在自有 VPS 上設定 Claude Code 支出追蹤

只需要 2 個服務：接收指標的 collector，以及儲存指標的 Prometheus。請勿將兩者暴露在公開網際網路上，因為開放的 OTLP 埠會接受任何找到它的人的寫入要求。撰寫 /opt/ccmetrics/compose.yaml：

services:
  collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel/config.yaml"]
    volumes:
      - ./collector.yaml:/etc/otel/config.yaml:ro
    ports:
      - "10.8.0.1:4318:4318"
    restart: unless-stopped
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports:
      - "127.0.0.1:9090:9090"
    restart: unless-stopped

volumes:
  prom-data:

10.8.0.1 是伺服器在 WireGuard tunnel 內的位址，因此 collector 只能從你的機器連線，其他來源都無法存取。連接埠前的位址在這裡確實有作用，因為 Docker published ports 不會受到 ufw 過濾：請參閱 Docker published ports 為何會繞過 ufw。設定 tunnel 本身的方式請參閱 在自有 VPS 上設定 WireGuard VPN。

/opt/ccmetrics/collector.yaml：

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]

/opt/ccmetrics/prometheus.yml。由於 Prometheus 透過 Compose network，以服務名稱連線至 collector，因此 8889 埠不會 published 至主機：

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: claude-code
    static_configs:
      - targets: ["collector:8889"]

cd /opt/ccmetrics
docker compose up -d
docker compose logs collector

collector 日誌最後應顯示 Everything is ready. Begin running and processing data.。如果日誌停在設定錯誤，表示 YAML 解析失敗，容器會持續在迴圈中重新啟動。

現在將 Claude Code 指向這個 collector。在每台執行 Claude Code 的機器上，將以下內容加入 ~/.claude/settings.json：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "none",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://10.8.0.1:4318",
    "OTEL_METRIC_EXPORT_INTERVAL": "10000"
  }
}

啟動工作階段，傳送 1 個提示，等待匯出間隔結束（此處為 10 秒，預設為 60 秒），再向 Prometheus 查詢它已取得的資料：

curl -s http://localhost:9090/api/v1/label/__name__/values | grep -o 'claude_code[a-z_]*'

你應該會取得數個以 claude_code_ 開頭的名稱。exporter 會將句點改為底線，並附加單位，因此實際字串取決於你的 collector 版本。結果為空表示沒有資料送達。請確認通訊協定與埠號一致，因為 http/protobuf 會使用 4318，而 grpc 會使用 4317；不一致時通常會靜默失敗。執行 claude --debug，debug log 會回報 OTel 匯出錯誤。

如果只有 1 台機器且不需要伺服器，請跳過上述所有步驟。設定 OTEL_METRICS_EXPORTER=prometheus 後，Claude Code 本身會在 http://localhost:9464/metrics 提供 scrape endpoint。當 prometheus 是唯一列出的 exporter 時，Claude Code 會從指標名稱中省略 USD、tokens 和 s 單位，讓 scrape 結果維持有效的 Prometheus 文字格式。

這種架構涉及 1 項隱私決策。預設只有計數會離開機器，不會傳送提示文字或工具輸出。OTEL_LOG_USER_PROMPTS=1 和 OTEL_LOG_TOOL_CONTENT=1 會改變這項行為；啟用後，你的 metrics box 會包含原始程式碼及 context 中的其他內容。請先確認需求，再刻意啟用這些選項，並閱讀 避免將 secrets 放入 agent context。

追蹤腳本與 CI 執行的支出

非互動式執行最容易造成意外，因為沒有人監看畫面。使用 --output-format json 搭配 claude -p，即可在結果 payload 中回報該次執行的成本：

claude -p "summarise the failing tests" --output-format json | jq '.total_cost_usd'

payload 會包含 total_cost_usd 以及依模型分類的明細，因此 CI 工作不需要使用 dashboard，也能記錄自身支出。將該值附加至檔案，或將其作為 metric 推送至上方的 collector。這是目前成本最低且實用的支出追蹤方式，每次執行只需進行一次 jq 呼叫。

失敗模式與可觀察到的現象

報表是空的。 npx ccusage@latest daily 沒有列出任何資料列，表示它讀取的位置不是 Claude Code 寫入資料的位置。CLAUDE_CONFIG_DIR 會變更該位置，因此必須告知剖析器新的位置。若有資料列，但內容只回溯到約 1 個月前，這是 cleanupPeriodDays 的預設行為：文字記錄預設會在 30 天後移除。

兩台電腦回報的總量不同。 這是預期行為，不是錯誤。/usage 和任何日誌剖析器都只會讀取本機工作階段歷程，因此另一台裝置或 claude.ai 的用量不會出現在任何一方。

本機總量與發票不符。 本機數值是依據標準牌價和 token 數量計算而來。這些數值不包含促銷價格或合約折扣；使用訂閱方案時，token 也不會個別計費。API 計費應以 Console usage 頁面為準。

執行相同工作，但費用增加。 先檢查快取欄位。長工作階段在每次互動時都會重新傳送完整歷程；快取有效時會套用快取價格，快取失效後則套用完整輸入價格。因此，只要中斷時間較長，就會重新處理整段對話。這會顯示為輸入數量很大、輸出數量很小，而 輸入與輸出 token 計價 說明了兩者為何會各自變動。

某天使用子代理程式的用量高得不合理。 每個子代理程式都會使用自己的上下文視窗，因此 token 用量會隨執行的子代理程式數量及各自執行時間增加。只有 OTel 資料能透過 claude_code.token.usage 上的 query_source 屬性區分這些用量。日誌剖析器只會顯示總量，無法進一步區分。

FAQ

ccusage 會顯示 Max 方案的實際計費金額嗎？

不會。訂閱方案不是依 token 計費，因此日誌剖析工具會按照 API 的標準牌價計算 token 費用，顯示相同工作若透過 API 執行所需的費用。這適合用來相對比較每天的使用量，也能比較不同專案或模型之間的差異。若要查看實際應付金額，API 計費請查看 Console 的 usage 頁面，訂閱方案則請查看方案計費頁面。

Claude Code 會將這些工具讀取的工作階段檔案儲存在哪裡？

儲存在 ~/.claude/projects/<project>/<session-id>.jsonl。其中，<project> 是工作目錄路徑，非英數字元會替換為 -。每一行都是一個 JSON 物件，代表一則訊息、一次工具使用或一筆中繼資料。CLAUDE_CONFIG_DIR 會移動整個目錄，而 settings.json 中的 cleanupPeriodDays 會控制 30 天的保留期限。Anthropic 將項目格式列為內部格式，且不同版本可能變更，因此請使用持續維護的工具進行剖析，不要自行撰寫 script。

我可以將 Claude Code 遙測資料傳送到 Langfuse 嗎？

不能直接傳送。Langfuse 的 OTLP endpoint 接受 traces，但 Claude Code 匯出的是 metrics 和 log events，而不是 spans，因此沒有可接收這些資料的位置。請將 Claude Code metrics 傳送至 OpenTelemetry collector，並儲存到 Prometheus。若要使用 Langfuse，請用於自己透過 API 建立的 agents；此時由你自己的程式碼產生 spans，並在其中帶入 prompt、model 與 cost。

為什麼本機數據與 Console 的 usage 頁面不一致？

因為計算方式不同。/usage 和日誌剖析工具會加總目前所在電腦上的工作階段檔案中的 token 數量，再按照標準牌價計算費用。Console 會統計所有電腦與所有 key 的實際組織計費金額，並套用任何折扣。數值不一致是正常情況。若差異非常大，通常表示還有第二台裝置、CI runner 或其他團隊成員使用同一個帳戶計費。

如何追蹤 CI 中一次 claude -p 執行的費用？

使用 --output-format json 執行，並從結果中讀取 total_cost_usd，例如使用 claude -p "..." --output-format json | jq '.total_cost_usd'。同一個 payload 也包含每個 model 的明細與工作階段 ID。為每個 job 記錄該數值，即可取得每條 pipeline 的支出，不需要 agent、dashboard 或額外服務。