Claude Code 之類的 AI 代理日常在用時，是不是一下子就碰到限制了？
Netflix 的資深工程師以開源形式釋出的「Headroom」這個 token 減量工具，幾天內就超過了 6k stars・400 forks（截至 2026/06/03）而成為話題。
順帶一提，根據官方基準測試，在建置日誌可達 93.9%、JSON 可達 90.6% 的 token 減量（不過實際運用的中位數只有 4.8%——這個數字落差後面會提到）。
Headroom GitHub 倉庫: https://github.com/chopratejas/headroom
3 行總結
- Headroom 是一個將送往 AI 代理的上下文進行壓縮、以降低 token 消耗的 OSS
- 在 JSON、資料庫結果、日誌上，預期能有很大效果
- 但在從原始碼生成設計文件、或從設計文件生成程式碼這類以程式碼為中心的工作流程中，效果有限
token 成本膨脹的真正原因
稍微研究一下 Claude Code 之類的 AI 代理為什麼那麼貴，會發現一個意外的事實。
成本的主因不是「輸出 token」，而是 「輸入 token」。
AI 代理不只是會話文字，還會把這些東西一個接一個塞進上下文：
- 資料庫查詢結果（動輒回傳 500 行）
- 建置日誌與錯誤日誌
- API 回應 JSON
- RAG 抓回來的文件片段
- 檔案樹
而且這些 大多是人類一眼就能看出結構、快速略讀的重複性資料。
但 LLM 會全部讀一遍。也全部都會計費。
Headroom 的開發者 Tejas Chopra 本人也提到，平常開發工作中 Claude Code 的月費曾達到 287 美元，追查後發現是大量不必要的資料庫列與巢狀 JSON 塞滿了上下文。導入 Headroom 後，費用下降到約 110 美元（這是自述數字，僅供參考）。
Headroom 到底是什麼工具
一句話說，就是 在資料送達 LLM 之前，先壓縮上下文的一層。
這和「摘要」不同。重點在於，會依照資料種類改變壓縮方式。
AI 代理（Claude Code、Cursor、Codex...）
↓ 工具輸出・日誌・RAG 結果・檔案
┌──────────────────────────────┐
│ Headroom（本地執行） │
│ ContentRouter 判定資料種類 │
│ ├─ SmartCrusher （JSON） │
│ ├─ CodeCompressor （AST） │
│ └─ Kompress-base （文字） │
└──────────────────────────────┘
↓ 壓縮後的提示詞
LLM 供應商（Anthropic・OpenAI...）例如，假設有一個 500 行的 JSON 陣列。人類通常會先快速確認欄位結構，接著只找有錯誤或異常值的列。Headroom 的 SmartCrusher 也是同樣概念：保留開頭、結尾、重要欄位與錯誤列，把重複部分改寫成統計性表達。
定量的減量資料（官方基準測試）
依內容種類的減量率
內容類型減量前減量後減量率處理時間JSON 陣列（100 筆）3,163 tokens297 tokens90.6%1msJSON 陣列（500 筆）9,526 tokens1,614 tokens83.1%2msShell 輸出（200 行）3,238 tokens469 tokens85.5%1ms建置日誌（200 行）2,412 tokens148 tokens93.9%1msgrep 結果（150 筆）2,624 tokens2,624 tokens0%（刻意如此）<1msPython 原始碼（480 行）2,958 tokens2,958 tokens0%（刻意如此）<1ms合計**23,9218,11066.1%**5msgrep 和程式碼是 0% 減量，這是設計如此。因為「本來就已經很精簡的格式若再多做壓縮，會破壞正確性」，所以它刻意不壓縮。
對準確度的影響
在 100 筆 JSON 日誌（第 67 筆埋有 FATAL 錯誤的測試）中，從 10,144 tokens → 1,260 tokens（減少 87.6%），仍維持 4/4 的正確率。
另外，F1 分數 0.85→0.87 這個數字是另一個 QA 準確度基準測試的結果，不能和 JSON 壓縮的話混在一起看。官方說明為，去除 HTML 雜訊後，LLM 更容易聚焦在本質內容上。
⚠️ 實際運用的數字不同（這點很重要）
先老實說明「60～95% 減量」這種宣傳語和真實情況之間的落差。
官方從代理的實際運用 50,000+ 次 session（250+ 個 instance，2026 年 3～4 月）統計出的數字如下。
百分位實際減量率P254.8%中位數（P50）**4.8%P756.9%平均11.3%中位數只有 4.8%**。
為什麼會這樣？因為真實 session 裡大量混有「短對話回合」。官方文件也說明，若是包含大量檔案讀取或 shell 輸出的重度工具使用 session，減量可達 40～80%。
也就是說，效果會因 使用方式 而大幅不同。
成本換算
比較壓縮處理的時間成本與可節省的 token 成本後，在驗證的 5 種情境中，多數情況下 Headroom 帶來的效益都大於成本。代理的額外開銷中位數為 52ms，和 LLM 的推理時間（2～10 秒）相比，幾乎可忽略不計。
使用方式非常多樣
可以依照自己的工作流程選擇。
以下摘自 GitHub README：
1. CLI 包裝器（最方便）
pip install "headroom-ai[all]"
# 直接包裝既有代理
headroom wrap claude
headroom wrap cursor
headroom wrap codex2. 當作代理伺服器使用（零程式碼修改）
headroom proxy --port 8787它會以 OpenAI 相容的 proxy 啟動，因此只要改 endpoint URL，既有程式就能原封不動運作。
3. 作為 Python 函式庫整合
from headroom import compress
compressed = compress(messages, model="claude-sonnet-4-6")
# 之後照一般 API 呼叫即可4. 作為 MCP 伺服器
headroom mcp installMCP 相容的客戶端可以把它當成 headroom_compress、headroom_retrieve 等工具來使用。
「可逆壓縮（CCR）」這個機制很有意思
Headroom 的特色功能之一是 CCR（Compress, Cache and Retrieve）。
它的設計是：把壓縮前的原文保存在本地（Redis 或 SQLite），當 LLM 需要更詳細資訊時，可以透過 MCP 工具取回原始資料。
這和單純的摘要、截斷有很大不同。
- 摘要：有可能刪掉之後還會需要的那一行
- 截斷：容易丟掉日誌中間的錯誤或離群值
- CCR：先送出壓縮版，若有需要再回到原始資料
它強調「local-first」也是這個原因：不需要把公司內部日誌或機密資料送到外部服務。
這些情況下效果較明顯
官方文件也明確寫了「有效場景很偏」。
較容易有效的情況：
- 處理大量 JSON 的 API 回應
- 經常讀取資料庫列
- 有結構化日誌或建置／測試輸出
- 長時間的代理 session
- 混合多個代理（例如 Claude Code + Codex）
效果較弱的情況：
- 只有短對話
- 只有程式碼的 session
- 單次查詢
這些情況下效果較不明顯
官方的 Limitations 頁面很誠實地列出「不適用的案例」，這裡整理兩個常被討論的使用情境。
從原始碼生成設計文件
把程式碼讀進去，讓 LLM 寫設計文件，這種模式 幾乎沒效果。
根據官方文件，原始碼為了維持正確性，設計上是不壓縮的。再加上，如果最近的訊息中包含 analyze、review、explain、fix、debug 之類關鍵字，對話中的所有程式碼都會自動被保護。
而設計文件生成的情境通常幾乎一定會包含這些關鍵字，因此壓縮不會啟動。
從設計文件生成程式碼
把設計文件（文字／文件）當輸入來生成程式碼，這種模式 效果也不大。
RAG 取得的文件目前會直接通過（零壓縮）；即使是直接貼上的純文字，也只會減少 43～46%。此外，官方文件也明講，文字壓縮需要時間，因此「雖然能降低成本，但會增加延遲」。
以程式碼或設計文件為主的工作流程，幾乎不在 Headroom 的主要設計目標內。
⚠️ 企業導入前想確認的資安問題
我看到有人在推文裡問「proxy/wrap 模式會不會把資訊送到外部？」所以這部分我也仔細查了一下。
結論：Headroom 本身並沒有把資料送到外部伺服器
壓縮處理本身是本地端完成
README 明確寫著 Headroom (runs locally — your data stays here)，壓縮與轉換都在本地完成。Headroom 並不是把工具輸出或日誌拿到外部伺服器處理。
但前提是，壓縮後的資料會送到 LLM 供應商（Anthropic、OpenAI 等）這件事本來就是如此；這在導入 Headroom 前後都一樣。Headroom 沒有新增資訊外洩路徑。
⚠️ 注意點 ①：匿名遙測預設為 ON
官方設定文件中列出以下環境變數：
HEADROOM_TELEMETRY 預設: on（匿名遙測）文件沒有詳述實際送出哪些內容，但看起來應該是「匿名使用統計」。如果在意，可以明確關掉。
export HEADROOM_TELEMETRY=off若是企業資安政策較嚴格，建議不要維持預設值，而是考慮關閉。
⚠️ 注意點 ②：預設設定下，可能會公開到整個 LAN
文件中有 --host 0.0.0.0 這個啟動參數範例。這代表不只綁定本機，還會綁定到 LAN 上的所有介面。
headroom proxy \
--port 8787 \
--host 0.0.0.0 \ # ← 會公開到整個 LAN
...不過環境變數預設是 HEADROOM_HOST: 127.0.0.1（僅限本機），所以只要不要照抄命令列範例，通常不會有問題。但若在共享開發伺服器或 Docker 中執行，還是要注意別不小心對 LAN 開放。
「資訊會送到外部」推文的真偽
原推文的說法，整體來說是 有誤解，但也不是完全沒風險。
- ❌ 錯誤：Headroom 本身會把資料送到外部伺服器
- ✅ 正確的疑慮：預設遙測是開啟的，這點需要確認
- ✅ 正確的疑慮：依設定不同，可能會對 LAN 開放
- ✅ 正確的疑慮：headroomlabs.ai 的儀表板可能會彙整顯示「整個社群節省的 token 數」，但這部分含有推測，因此不下定論
若要處理企業敏感日誌或機密資料庫結果，建議在導入前先與資安團隊確認。
最後
在 AI 代理已經進入日常開發流程的今天，和「要不要用更強的模型」一樣重要的問題，變成了 「每次到底在讓模型讀什麼」。
Headroom 以本地、可逆、支援多代理的方向，切入了這個問題。幾天內就能累積這麼多 Star，也反映出有很多開發者正面臨同樣的痛點。
我自己也打算找時間實際試用看看。有試過的人，歡迎在留言分享感想！
參考連結
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
