外觀

語言

高效 AI 駕馭術

Claude Code token 用量怎麼查?用 ccusage 和 Python 算出每週用量,附完整教學(2026)

我那兩張每週 token 和換算費用的圖是怎麼算的:ccusage 的指令、把 JSON 轉成圖表數字的 Python,以及另一支加總對話紀錄、分出 subagent 用量的腳本。

Kelvin Wang · · 4 分鐘閱讀

重點整理

  1. ccusage 讀的是本機 ~/.claude/projects 底下的對話紀錄,不用登入、不用 API key,只算得到這台電腦的用量。
  2. ccusage claude weekly --json 給每週、每個模型的 token 和換算費用;沒用的週不會列出來,畫圖前要補成 0。
  3. ccusage 分不出 subagent;subagent 的紀錄放在 subagents/ 資料夾,自己加總就分得出來。

Claude Code 與 Codex 如何指定 subagent 模型那篇開頭有三張圖:30 天的 token 用在哪、每週 token 數、每週換算費用。數字都是在我的 Mac 上跑兩支工具算出來的:每週的兩張用 ccusage,subagent 那張用一支自己寫的 Python。兩支都只讀本機檔案,不用登入,也不會把資料送到別的地方。

ccusage 是什麼?怎麼裝?

ccusage 是開源的命令列工具,讀 Claude Code 存在本機的對話紀錄(~/.claude/projects/ 底下的 .jsonl 檔),把每一則回覆的 token 加總,再照公開的 API 價格換算成美元1。不用裝也能跑:

npx ccusage@latest claude weekly

常用的話裝成全域指令(我是用 npm 裝的):

npm install -g ccusage
ccusage claude weekly

要注意這幾件事:

  • 只算得到這台電腦。紀錄存在本機,別台電腦、雲端上的 Claude Code 要在那邊各跑一次。
  • 換算費用不是帳單。用訂閱的話實際付的是月費,這個數字只告訴你同樣的量照 API 價格要多少錢。Claude Code 裡面看自己的用量是 /usage2。
  • 指令要加 claude。ccusage 20 版起預設把 Codex 等其他 AI 工具的紀錄也算進去,這篇的指令都寫成 ccusage claude …,只算 Claude Code,JSON 欄位跟之前一樣。我畫那幾張圖時用的是 18.0.5,那時還只算 Claude Code。
  • 適合手動跑,不適合接在狀態列。每跑一次都要讀完全部紀錄;狀態列是每個視窗每次更新都跑一次,視窗一多就會佔掉好幾 GB 記憶體。狀態列改用什麼、實測數字,寫在Claude Code 狀態列記憶體實測。

每週用量的指令有哪些?

ccusage claude weekly               # 每週一列:token、換算費用、用了哪些模型
ccusage claude weekly --breakdown   # 每週再拆到每個模型
ccusage claude weekly --json > weekly.json   # 給程式讀的格式
ccusage claude daily                # 改成每天;monthly 是每月

每週預設從週日開始,用本機時區分週;--start-of-week monday 改成週一、--timezone Asia/Taipei 指定時區,--since 20260901 只看某天以後1。

怎麼把 ccusage 的 JSON 轉成每週長條圖?

--json 的輸出是一個 weekly 陣列,每週有 totalTokens、totalCost,modelBreakdowns 裡是每個模型的 token 和 cost。畫圖前我做了三件事:

  1. 補上沒用的週。那一週沒有任何紀錄時 ccusage 不會列出來,直接畫的話時間軸會跳過,看起來像是連續在用。我的 8/2、8/9 兩週就是這樣,補成 0。
  2. token 換成億、費用照模型拆開。費用圖是依模型堆疊,所以每個模型一條數列。
  3. 推估還沒過完的那週。匯出時 11/15 那週才過 2.49 天,用目前的平均速度乘到 7 天:34.2 億 × 7 ÷ 2.49 ≈ 96.4 億,913 美元 × 7 ÷ 2.49 ≈ 2,571 美元。圖上用虛框畫,跟實際用掉的量分開。
"""把 `ccusage claude weekly --json` 轉成每週長條圖要的數字。
用法:ccusage claude weekly --json > weekly.json && python3 weekly_chart.py weekly.json
可以在最後加匯出時間(例如 2026-11-17T11:40),推估就照那個時間點算;不加就用現在。
"""
import json, sys
from datetime import date, datetime, timedelta, timezone

data = json.load(open(sys.argv[1]))["weekly"]
TZ = timezone(timedelta(hours=8))          # 跟 ccusage 一樣用本機時區分週(台北)
now = datetime.fromisoformat(sys.argv[2]).replace(tzinfo=TZ) if len(sys.argv) > 2 else datetime.now(TZ)

# 1. 沒用的週 ccusage 不會列出來,補成 0,時間軸才不會跳過
first = date.fromisoformat(data[0]["week"])
last = date.fromisoformat(data[-1]["week"])
by_week = {w["week"]: w for w in data}
weeks = []
d = first
while d <= last:
    weeks.append(d.isoformat())
    d += timedelta(days=7)

# 2. 每週 token(億)和每個模型的換算費用(美元)
models = sorted({m["modelName"] for w in data for m in w["modelBreakdowns"]})
tokens = [round(by_week[w]["totalTokens"] / 1e8, 2) if w in by_week else 0 for w in weeks]
cost = {m: [] for m in models}
for w in weeks:
    per = {m["modelName"]: m["cost"] for m in by_week.get(w, {}).get("modelBreakdowns", [])}
    for m in models:
        cost[m].append(round(per.get(m, 0), 2))

# 3. 最後一週還沒過完:照目前的平均速度推到 7 天
start = datetime.fromisoformat(weeks[-1]).replace(tzinfo=TZ)
days = min(7, (now - start).total_seconds() / 86400)
cur = by_week[weeks[-1]]
print("週:", [w[5:] for w in weeks])
print("token(億):", tokens)
for m in models:
    print(f"{m}(美元):", cost[m])
print(f"最後一週過了 {days:.2f} 天")
if days < 7:
    print(f"推到週末:{cur['totalTokens'] / 1e8 * 7 / days:.1f} 億 token、"
          f"{cur['totalCost'] * 7 / days:,.0f} 美元")

跑法:

ccusage claude weekly --json > weekly.json
python3 weekly_chart.py weekly.json 2026-11-17T11:40

最後的時間是我匯出 JSON 的時間,推估就照那個時間點算;不加的話用現在的時間,數字會跟圖上不一樣。印出來的陣列直接貼進文章的長條圖元件。

subagent 用了多少,怎麼算?

ccusage 把同一台電腦的紀錄全部加在一起,分不出主對話和 subagent。Claude Code 把 subagent 的對話另外存在 subagents/ 資料夾,所以自己讀紀錄就分得出來。這支腳本做的事:

  • 只算最近 30 天。用每一行的 timestamp 篩。
  • 同一則回覆只算一次。一則回覆會在紀錄裡寫好幾行,用訊息的 id 去重。
  • 四種 token 都加進去。輸入、快取寫入、讀快取、輸出;九成以上是讀快取,每一輪對話都會把前面的內容再讀一次。
"""加總 Claude Code 本機對話紀錄,看 30 天內主對話和 subagent 各用了多少 token、跑哪個模型。
用法:python3 subagent_split.py
"""
import collections, datetime, glob, json, os

ROOT = os.path.expanduser("~/.claude/projects")
cut = (datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=30)).isoformat()
agg = collections.defaultdict(collections.Counter)
seen = set()

for f in glob.glob(ROOT + "/**/*.jsonl", recursive=True):
    kind = "subagent" if "/subagents/" in f else "主對話"    # subagent 的紀錄放在 subagents/ 資料夾
    for line in open(f, errors="ignore"):
        if '"usage"' not in line:
            continue
        try:
            d = json.loads(line)
        except json.JSONDecodeError:
            continue
        if d.get("timestamp", "") < cut:
            continue
        m = d.get("message") or {}
        u, mid = m.get("usage"), m.get("id")
        if not u or not mid or (kind, mid) in seen:     # 同一則回覆會寫好幾行,用 id 去重
            continue
        seen.add((kind, mid))
        model = m.get("model", "?")
        if model.startswith("<"):                         # 合成的訊息,不是真的 API 呼叫
            continue
        family = next((k for k in ("opus", "sonnet", "haiku", "fable") if k in model), model)
        agg[(kind, family)]["token"] += sum(u.get(k, 0) for k in (
            "input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "output_tokens"))

total = sum(c["token"] for c in agg.values())
for (kind, family), c in sorted(agg.items(), key=lambda kv: -kv[1]["token"]):
    print(f"{kind:8} {family:7} {c['token'] / 1e8:7.1f} 億  {c['token'] / total:6.1%}")
sub = sum(c["token"] for (k, _), c in agg.items() if k == "subagent")
print(f"合計 {total / 1e8:.1f} 億,subagent 佔 {sub / total:.1%}")
python3 subagent_split.py

我這台 Mac 有 1,400 多個紀錄檔,跑一次大約半分鐘。30 天是往回算的,每天跑出來的數字都會不同:我寫那篇時是約 150 億、subagent 佔 47%,隔幾個小時再跑變成 146 億、50.3%,因為最早那一天掉出範圍、最近幾小時又派了不少 subagent。

想深入 Claude Code 狀態列哪個最省記憶體?ccusage、ccstatusline、claude-pace 開 6 個視窗實測(2026) 狀態列為什麼不該跑 ccusage,改用什麼,各工具的記憶體實測。 GitHub kelvin-sl/cc-usage-lite 只讀 stdin 的輕量狀態列,可以取代 ccusage statusline;報表照樣用 ccusage。

資料來源

  1. 1. ccusage · GitHub · 2026-11-19 查詢
  2. 2. Manage costs effectively · Claude Code Docs · 2026-11-17 查詢

關於作者

Kelvin Wang

電機工程師,和 AI Agent 做工具,分享工程與投資的實作筆記。

更多關於我