ccusage 讀取 AI 寫程式工具留下的本機日誌,整理每日、每月與模型用量。想知道 Codex 花了多少 token、把報表交給 AI 分析時適合用;想查訂閱還剩多少額度,應看客戶端的額度資訊,這份日誌報表不能代替它。
本文先用一份公開的合成日誌跑通流程,釐清最容易加錯的地方:兩筆累計值 1200、1800,總量是 1800,不是 3000。
Windows 安裝與第一份報表
準備 Node.js 與 Codex CLI,在空資料夾開 PowerShell。這次使用 Node 24、ccusage 20.0.51:
node --version
npm.cmd install --no-audit --no-fund ccusage@20.0.51
node .\node_modules\ccusage\src\cli.js --version
使用 npm.cmd 可避開 PowerShell 把 npm 解析成執行政策禁止的 .ps1。這是一般 CLI,不用加入 MCP 設定。
將下面程式存成 make-sample.cjs:
const fs = require('node:fs');
const dir = 'usage-records/sessions/2026/11/16';
fs.mkdirSync(dir, { recursive: true });
const rows = [{ timestamp: '2026-11-16T08:00:00Z', type: 'turn_context',
payload: { model: 'gpt-5.2-codex' } }];
const usage = (input, cached, output) => ({ input_tokens: input,
cached_input_tokens: cached, output_tokens: output,
reasoning_output_tokens: 0, total_tokens: input + output });
rows.push({ timestamp: '2026-11-16T08:01:00Z', type: 'event_msg',
payload: { type: 'token_count', info: { model: 'gpt-5.2-codex',
total_token_usage: usage(1000,100,200), last_token_usage: usage(1000,100,200) } } });
rows.push({ timestamp: '2026-11-16T08:02:00Z', type: 'event_msg',
payload: { type: 'token_count', info: { model: 'gpt-5.2-codex',
total_token_usage: usage(1500,150,300), last_token_usage: usage(500,50,100) } } });
fs.writeFileSync(`${dir}/usage.jsonl`, rows.map(x => JSON.stringify(x)).join('\n')+'\n');
執行:
node .\make-sample.cjs
$env:CODEX_HOME = (Resolve-Path .\usage-records).Path
node .\node_modules\ccusage\src\cli.js codex daily --json --offline --timezone UTC
daily 中應出現 2026-11-16,totalTokens 為 1800。這裡固定 UTC,讓日誌日期與報表日期相同。
三個實際用途
1. 核對一天的快取與輸出
把上面的日報指令與以下要求貼給 Codex,允許它在這個範例資料夾執行終端命令:
只讀目前資料夾的 usage-records。每次命令都先把 CODEX_HOME 設為它的完整路徑,
執行 ccusage codex daily --json --offline --timezone UTC。
列出 totalTokens、inputTokens、cacheReadTokens、outputTokens,解釋累計值如何去重。
這份資料得到 1800/1350/150/300。原始累計 input 1500 含快取,報表把其中 150 移到 cacheReadTokens;不要再把快取加回原始 input 一次。
2. 匯出月報,讓 AI 找用量較高的月份
node .\node_modules\ccusage\src\cli.js codex monthly --json --offline --timezone UTC
請 AI「依月份整理 totalTokens 與模型,先列數據,再說有哪些用量問題值得追查」。範例只有 2026-11 一個月份、總量 1800。實際有多個月份才適合談趨勢;日報與月報是同一批資料的不同分組,不要相加。
3. 確認日期篩選真的生效
node .\node_modules\ccusage\src\cli.js codex daily --since 20261117 --json --offline --timezone UTC
請 AI 核對是否為 daily: []、總量 0。資料只到 11 月 16 日,這個結果正好能分辨「篩選掉了」與「原本讀不到日誌」。
換成自己的日誌
範例成功後,在同一個安裝資料夾另開 PowerShell 視窗,執行相同報表指令,讓 ccusage 使用預設 Codex 日誌位置;若 Codex 裝在自訂位置,將 CODEX_HOME 指向那個資料夾。先在終端核對 JSON,再決定提供給 AI 的欄位,避免把整份對話日誌貼出去。Claude Code 的資料來源請看官方來源說明;本文的核心是 Codex 日誌,沒有專用 Cursor 外掛步驟。
常見錯誤
沒有資料,或報表一直是 0
先移除日期篩選,確認 CODEX_HOME 內有 sessions 日誌,再檢查是否包含 token_count 與模型資訊。舊日誌若沒有這些欄位,ccusage 無法補出歷史用量。別把空報表解讀成完全沒使用。
切換終端後讀到另一份資料
PowerShell 的環境變數以程序為範圍,新視窗不會繼承你在另一個視窗後來設定的值。需要固定資料來源時,在同一段命令明確設定 CODEX_HOME;請 AI 執行時也寫清楚完整路徑。
日期少一天,或時區不同
指定 --timezone UTC 先核對原始時間,再依需要改成所在地時區。--since 20261117 使用年月日格式;測試資料是 11 月 16 日,被篩掉是正常結果。
看見美元數字,卻與帳單不一樣
costUSD 是依 token 與價格資料估算,--offline 使用內附價格。它不是訂閱帳單,也不是剩餘額度;價格版本與缺少的日誌都會影響解讀。
費用、限制與替代方式
ccusage 採 MIT 授權,本機程式不另收費,--offline 報表不需要即時抓價格;AI 客戶端的模型使用另計。資料完整度取決於留下多少日誌,不能靠它重建已刪除的對話用量。只想看當前額度,用客戶端資訊較直接;需要自己的資料查詢流程可參考 DuckDB MCP。
FAQ
ccusage 可以查 Codex 嗎?
可以,使用 codex daily 或 codex monthly 限定來源。只執行不帶來源的總覽時,可能包含其他工具,因此比較前先確認範圍。
累計 1200、1800 為什麼不是 3000?
第二筆表示到那個時間為止已累計 1800,包含第一筆的 1200。新增量是 600,所以結果是 1200+600。不要直接把每筆 total_token_usage 相加。
快取 token 要再加一次嗎?
先看欄位定義。這份報表的 inputTokens 已扣除 cacheReadTokens;原始日誌的 input_tokens 則包含快取,因此兩種資料不能混著加。
ccusage 要裝成 MCP 嗎?
本文這個流程直接執行 CLI,再讓 Codex 分析 JSON。無須註冊 MCP;若你只需要報表,在終端執行即可。
參考與我們測了什麼
安裝、Codex 來源、環境變數、原始碼。查閱日期:2026-11-16。
Windows、Node 24、ccusage 20.0.51、Codex CLI 0.169.0;Codex 真正執行合成日誌的日報、月報與日期篩選,結果為 1800、1800、0。 資料刻意公開可重現,沒有讀取私人日誌或核對帳單;Claude Code 來源、Cursor 與跨工具總覽未測。