Claude Code 支出追蹤工具比較:日誌、用量與 OTel
Claude Code 支出追蹤工具回答的問題不同。比較本機 JSONL 日誌解析器、內建用量頁面與自建 OpenTelemetry,了解各自能看見及無法看見的資料。
Claude Code 支出追蹤工具實際讀取的資料
每個 Claude Code 支出追蹤工具都會讀取 3 種資料來源之一,而資料來源會決定它能回答哪一類問題。日誌解析器會讀取儲存在本機磁碟上的工作階段文字記錄檔。儀表板會讀取 Anthropic 為你的帳戶或組織保留的使用量記錄。指標後端會讀取你啟用 Claude Code 後所發出的 OpenTelemetry (OTel) 串流。這 3 種工具可能同時正確,卻仍然顯示不同結果,因為它們計算的是不同項目。
本指南不會重新解釋 token。Claude Code 如何計算 token 使用量涵蓋輸入、輸出、快取寫入與快取讀取;在釐清這些內容前,任何儀表板的資訊都缺乏完整意義。本節只聚焦於較狹窄的問題:對於每一類工具,它能看見什麼,以及永遠無法看見什麼。
為何同一天出現 3 個 Claude Code 費用追蹤器
同一天發布了 3 個不同的 Claude Code 費用追蹤器。它們不是同一工具的 3 個版本,這才是重點。其中一個會解析本機工作階段檔案;一個會包裝帳戶用量頁面;另一個則是由你自行執行的代管追蹤後端。
這些工具同時出現,是因為代理工作階段的成本不再一目了然。聊天的費用大致可由畫面上的資訊判斷。代理程式會讀取 20 個檔案、執行測試套件,並在每次互動時重新傳送完整對話,因此帳單取決於你從未輸入的上下文。在訂閱方案中,Claude Code 顯示的工作階段金額只是估算值;Anthropic 表示,這個數字與計費無關。真正重要的是用量列,而它在某些日子的消耗速度會比其他日子快。這 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 --jsondaily 依日期加總。--breakdown 依模型拆分每一列,因此可以找出某個使用 Opus 的下午是否占了一週用量的大部分。blocks 依訂閱重設所使用的五小時時段分組。session 依對話加總,daily --instances 則依專案分組,讓你看出哪個儲存庫成本較高。加入 --since 與 --until 可限制日期範圍,並執行 npx ccusage@latest daily --help 以取得你的版本所要求的日期格式。截至 October 2026,它也會讀取其他 agent CLI,包括 Codex 與 OpenCode;如果你要比較這些工具,這項功能很重要。預設報告會合併所有偵測到的來源;在 daily 或 session 前加入 claude,即可只查看 Claude Code。
價格來自模型價格表,而該工具提供 3 種成本模式。--mode auto 會在檔案中存在 costUSD 值時使用 Claude Code 寫入的該值;若不存在,則依 token 數量計算。--mode calculate 一律依 token 計算,並忽略任何已記錄的成本。--mode display 只顯示已記錄的成本,對沒有記錄成本的列輸出 $0.00。如果總額看起來不正確,請在 calculate 下執行相同報告,再於 display 下執行一次。兩者差距很大,表示大多數項目沒有記錄成本,因此你看到的全部都是估算值。如果你支付的是合約費率,請在 ccusage.json 設定檔的 defaults 下設定 pricingOverrides,即可取代個別模型的價格。
相同資料也能提供給提示列。ccusage statusline 會輸出一行精簡資訊,供 Claude Code 狀態列使用;你可以像其他狀態列命令一樣,將它接入 ~/.claude/settings.json。如需設定區塊及其接收的欄位,請參閱 建立 Claude Code 狀態列。
日誌解析器看不到未在這台電腦上發生的活動。另一台筆記型電腦上的活動、claude.ai 中的工作,以及團隊成員的工作,其逐字稿都儲存在各自的磁碟上。依預設,較舊的終端機工作階段會在 cleanupPeriodDays 下閒置 30 天後清除,但保留期限可以設定:使用 3650 這類較大的值,即可保留數年的歷史記錄。從 Desktop 或 Cowork 啟動,或最近在其中繼續的工作階段,其逐字稿依預設會保留超過該期限,但 HIPAA 設定等情況除外。
還有一項風險,而且是結構性的。Anthropic 的文件指出,項目格式屬於 Claude Code 的內部格式,會在不同版本間變更,因此直接解析這些檔案的指令碼可能在任何版本中斷。這適用於所有採用此類方法的工具。這也是自行撰寫 jq JSONL 單行命令比看起來更糟的原因:維護中的解析器會替你追蹤格式變更;而你的單行命令可能在欄位重新命名的那天,輸出看似確定但實際錯誤的數字。
最後,訂閱方案下的金額需要附帶說明。在 Pro 或 Max 方案額度內的用量不會按 token 計費,因此該數字表示依 API 的標準牌價計算時,你的 token 原本會產生的成本。它衡量的是用量負載,不是你的帳單。例外是用量點數:如果啟用該功能,超過方案額度的用量會依標準 API 費率另行計費,而 claude.ai 會在 Settings > Usage 中顯示該月份的支出。如果真正的問題是應該選擇哪個方案,則需另行比較:請參閱 API 計費與 Claude 訂閱方案的比較。
方法 2:內建使用量畫面會告訴你是哪個模型消耗了預算
Claude Code 內建報表功能,但大多數人從未開啟。請在工作階段中執行 /usage。頂端的 Session 區塊會顯示各模型的 token 用量,以及目前工作階段的金額。除非管理員在受管理設定中設定 modelPricing 表格,否則該金額會根據 token 數量與標準牌價,在本機計算;若已設定,Total cost 行會顯示 at your organization's configured rates。無論是哪種情況,這個金額都只是估算值,可能與帳單不同。對 Pro 或 Max 而言,Anthropic 表示這項用量與計費無關,因為已包含在方案中。/clear 開始新的對話時,總量會重設。
在 Pro、Max、Team 或以席次計費的 Enterprise 方案中,同一畫面會顯示已使用的方案上限。按用量計費的 Enterprise 沒有可耗盡的包含額度,因為每個 token 都會依 API 牌價計費。在這些方案中,畫面也會將近期用量依 skills、subagents、plugins 和個別 MCP servers,顯示為總量的百分比。畫面會標示占近期用量 10% 以上的行為,例如較長的 context 或 cache miss。按 d 或 w,即可在最近 24 小時與最近 7 天之間切換。這些數值為約略值,並根據此機器上的本機工作階段歷程計算,因此不會計入第二台裝置的用量。額度用盡時,Claude Code 會顯示受限的額度及其重設時間;空白的用量列不代表額度已用盡。工作階段可以等待並在重設後繼續,而 達到額度上限後的處理方式 則是另一項需要依模型、context 與方案決定的事項。
當開發人員超過 1 人後,數據會轉為帳戶層級。API 組織可使用 Console Cost 頁面、顯示各成員支出與 accepted lines 的 Claude Code dashboard,以及使用管理員金鑰取得相同每日每位使用者指標的 Claude Code Analytics API。Teams 與 Enterprise 方案可在管理主控台取得支出報表並匯出 CSV。報表每日更新;以席次計費的方案會涵蓋 usage-credit 支出,按用量計費的 Enterprise 則涵蓋完整用量。Enterprise 另提供 analytics API。你能看到哪些資料取決於各開發人員的登入方式,因此混合型組織必須查看兩份報表,再手動加總。
若要估算預算,Anthropic 成本文件截至 October 2026 公布的數值為:每位開發人員每個活躍日平均約 $13,每位開發人員每月約 $150 到 $250;其中 90% 的使用者每個活躍日低於 $30。請將此數值視為企業部署的公開基準,不要視為團隊用量的預測。先讓一小組進行試用並測量,再外推到整個團隊。
dashboard 無法查看的,是低於天與個人層級的資料。它們會告訴你 Opus 佔用了週二的大部分用量,但不會告訴你是哪個 prompt、哪個 repository 或哪個 CI job 所造成。它們也會延遲,因為組織報表每日更新;因此 dashboard 適合用於檢視,不適合用來在今天下午即時攔截失控的 agent。要攔截失控的 agent,需要設定限制,而不是查看報表;相關內容請見 在 VPS 上限制 agent 成本。
方式 3:自建 OpenTelemetry stack 告訴你是哪個 prompt 造成效能退化
啟用 telemetry 並設定 exporters 後,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。你自行設定的 MCP servers 名稱,以及自訂 subagents 的名稱,會以 custom 傳送;除非設定 OTEL_LOG_TOOL_DETAILS=1,該設定也會將 Bash commands 和 tool input 加入 tool events。這些資料足以回答任何 dashboard 都無法回答的問題:帳單中有多少來自 subagents,而不是你自己的 turns;某個 MCP server 是否讓 input tokens 增加一倍;有人修改 CLAUDE.md 後,cache reads 是否大幅減少。cache 行為通常最容易出現意外,而prompt caching 何時能回本會說明應該如何解讀這些資料。
有一點需要更正,因為每個相關討論串都會提到這件事。Langfuse 是適合自架的 tracing backend,並可參考自架 Langfuse 進行 agent tracing,將其執行在 VPS 上。它的 OTLP endpoint 只接受 traces。Claude Code 預設會匯出 metrics 和 log events,而不是 spans,因此將 OTEL_EXPORTER_OTLP_ENDPOINT 指向 Langfuse 會讓專案保持空白,也不會提供任何有用的錯誤訊息。Span export 確實存在,但目前屬於 beta;必須設定 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 和 OTEL_TRACES_EXPORTER 才會啟用。Langfuse 自己的 Claude Code integration 採用不同方式:Stop hook,或安裝 Stop hook 的 plugin,會在每次回應後讀取 session transcripts,並將其轉換為 traces,因此同樣受限於 log parser 只能處理本機資料。若是你自行透過 API 建立的 agents,且由自己的程式為每個 span 建立 prompt、model 和 cost,Langfuse 就是合適的工具。若要取得 Claude Code CLI 的 spend totals,metrics store 才是合適的選擇。
設定自行管理 VPS 的 Claude Code 支出追蹤
只需要兩項服務:接收指標的 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 發布的埠不會受到 ufw 過濾:請參閱 Docker 發布的埠為何會繞過 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。埠 8889 從未發布到主機,因為 Prometheus 會透過 Compose network 使用服務名稱連線到 collector:
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 collectorcollector 日誌最後應顯示 Everything is ready. Begin running and processing data.。日誌若因設定錯誤而停止,表示 YAML 無法解析,容器也會在迴圈中反覆重新啟動。
現在將 Claude Code 指向該服務。在每台執行 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"
}
}啟動工作階段、傳送一個提示、等待匯出間隔(此處為 10 秒,預設為 60 秒),然後要求 Prometheus 查詢已收到的資料:
curl -s http://localhost:9090/api/v1/label/__name__/values | grep -o 'claude_code[a-z_]*'你應該會取得數個以 claude_code_ 開頭的名稱。Exporter 會將句點改為底線,並附加單位,因此確切字串取決於你的 collector 版本。結果為空表示沒有資料送達。確認 protocol 與埠號相符,因為 http/protobuf 會使用 4318,而 grpc 會使用 4317;兩者不符時通常會靜默失敗。執行 claude --debug-file /tmp/claude-debug.log,並在該檔案中尋找 [3P telemetry] 行;Claude Code 會在這些行回報 OTel 匯出錯誤。
若只有一台機器且不需要伺服器,請略過上述所有步驟。設定 CLAUDE_CODE_ENABLE_TELEMETRY=1 與 OTEL_METRICS_EXPORTER=prometheus,Claude Code 本身就會在 http://localhost:9464/metrics 暴露 scrape endpoint。當 prometheus 是唯一列出的 exporter 時,Claude Code 會從匯出的指標中省略 USD、tokens 與 s 單位,讓 scrape 維持有效的 Prometheus 文字格式。指標名稱不會改變;合併多個 exporter 的設定(例如 otlp,prometheus)則會保留這些單位。
採用這種架構時,還涉及一項隱私決策。預設只有計數與中繼資料會離開機器,不包含提示文字或工具輸出。OTEL_LOG_USER_PROMPTS=1 會將提示文字加入匯出的事件,也會啟用 assistant 回應文字;除非由 OTEL_LOG_ASSISTANT_RESPONSES=0 覆寫。OTEL_LOG_TOOL_CONTENT=1 會將選定的工具輸出加入 trace spans,並依內容限制套用排除與截斷,預設上限為 60 KB。這些旗標可能會暴露所選內容中的原始碼與 secret;它們不會自動匯出 context 中的所有內容。完整的對話內容需要另外設定 OTEL_LOG_RAW_API_BODIES。請務必有意識地啟用這些選項,並先閱讀 避免將 secret 放入 agent context。
以指令碼與 CI 執行追蹤支出
非互動式執行最容易造成意外,因為沒有人在畫面前監看。claude -p 搭配 --output-format json,會在結果承載資料中回報該次執行的費用:
claude -p "summarise the failing tests" --output-format json | jq '.total_cost_usd'承載資料包含 total_cost_usd 以及依模型細分的費用,因此 CI 工作不需使用儀表板即可記錄自身支出。與所有本機數值一樣,這只是用戶端估算值;如果執行作業使用 --continue 或 --resume 延續對話,回報的會是整段對話的總費用,也包含先前的執行。您可以將數值附加至檔案,或將其作為指標推送至上方的收集器。這是最實用且成本最低的支出追蹤方式,每次執行只需進行一次 jq 呼叫。
失敗模式與可觀察到的現象
報表是空的。 npx ccusage@latest daily 未列出任何資料列,表示它讀取的位置不是 Claude Code 寫入的位置。CLAUDE_CONFIG_DIR 會變更該位置,而 ccusage 也會讀取同一個變數,因此兩者必須使用相同的值。如果缺少較舊的工作階段,請檢查 cleanupPeriodDays:終端機工作階段預設會在閒置 30 天後清除,而 Desktop 與 Cowork 的轉錄內容通常會保留超過這段期間。
兩台機器回報的總數不同。 這是預期行為,不是錯誤。/usage 分解資料與任何日誌剖析器都只會讀取本機工作階段歷程,因此另一台裝置或 claude.ai 的使用量不會出現在其中。
本機總數與發票不一致。 除非設定合約費率,否則本機數值會依標準牌價,根據 token 數量計算:在受管理設定中使用 modelPricing 表格搭配 /usage,或在 ccusage 中使用 pricingOverrides。使用訂閱方案時,方案額度內的使用量根本不會依 token 計費,只有使用量點數會計費。API 計費應以 Console Cost 頁面為準。
執行相同工作時,成本卻上升。 請先檢查快取欄位。長時間工作階段會在每次操作時重新傳送完整歷程;快取有效時會依快取費率計價,快取失效後則依完整輸入費率計價。因此,只要長時間中斷一次,就會重新處理整段對話。這會呈現為輸入數量很大、輸出數量很小,而 輸入與輸出 token 計價 會說明兩者為何能獨立變動。
包含子代理程式的一天,看起來不可能。 每個子代理程式都會使用自己的內容視窗,因此 token 使用量會隨執行的數量及各自持續時間增加。在方案中,/usage 歸因資料會以百分比顯示這台機器的子代理程式占比。若要查看每個請求的詳細資料,OTel 資料會透過 claude_code.token.usage 上的 query_source 屬性區分各個請求。日誌剖析器只能顯示總量,無法說明細節。
FAQ
ccusage 是否會顯示我在 Max 方案中實際支付的費用?
不會。訂閱方案額度內的使用量不是按 token 計費,因此日誌剖析工具會依標準 API 公開定價計算 token 費用,顯示相同工作若透過 API 執行所需的費用。這適合用來相對比較某天的使用量,也能比較不同專案或模型之間的使用程度。若要查看實際應付金額,API 計費請查看 Console 的 Cost 頁面;訂閱費用請查看方案計費頁面。若已啟用 usage credits,超過額度的使用量會依標準 API 費率計費,claude.ai 會在 Settings > Usage 下顯示該筆費用。
Claude Code 會將這些工具讀取的工作階段檔案儲存在哪裡?
儲存在 ~/.claude/projects/<project>/<session-id>.jsonl,其中 <project> 是工作目錄路徑,非英數字元會替換為 -。每一行都是一個 JSON 物件,代表一則訊息、一次工具使用或一筆中繼資料。CLAUDE_CONFIG_DIR 會搬移整個目錄,而 settings.json 中的 cleanupPeriodDays 控制保留期限;終端機工作階段預設會在閒置 30 天後保留期限到期,Desktop 和 Cowork 的文字記錄通常會保留超過該期限。Anthropic 將項目格式列為內部格式,且可能在不同版本間變更,因此請使用持續維護的工具解析,不要使用自行撰寫的 script。
我可以將 Claude Code 遙測資料傳送至 Langfuse 嗎?
使用預設遙測設定時不行。Langfuse 的 OTLP endpoint 接受 traces,但 Claude Code 預設匯出的是 metrics 和 log events,而不是 spans,因此沒有可接收這些資料的目的地。Span 匯出功能仍屬 beta,必須手動啟用;Langfuse 自己的 Claude Code 整合則使用 Stop hook,將工作階段文字記錄轉換為 traces。若要統計費用總額,請將 Claude Code metrics 傳送至 OpenTelemetry collector,並儲存在 Prometheus。若是自行透過 API 建置的 agents,請使用 Langfuse;此時由自有程式碼發出包含 prompt、model 和 cost 的 spans。
為什麼我的本機數字與 Console usage 頁面不一致?
因為兩者的計算方式不同。/usage 和日誌剖析工具會加總目前使用的電腦上工作階段檔案中的 token 數量,除非已設定合約費率,否則會依標準公開定價計算;受管設定中的 /usage 會透過 modelPricing 設定費率,而 ccusage 則透過 pricingOverrides 設定。Console 涵蓋組織在不同電腦及金鑰上的使用量;若要查看實際 API 費用,請使用其 Cost 頁面,因為 Claude Code analytics dashboard 顯示的費用數字只是估算值。數字不一致屬正常情況。若差異非常大,通常表示還有第二台裝置、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 或額外服務。