~/教學/SAVE.md

文章 / Claude Code

Headroom:讓 Claude Code 用更少 token 做同樣的事,額度撐更久

Headroom 是免費開源的工具,夾在 Claude Code 和模型中間,先把 log、搜尋結果這些輸出壓縮再送出去。附安裝、headroom wrap claude 用法、怎麼看省多少和什麼時候省不到。

Claude Code 的額度常常不是被你的問題吃掉,而是被它讀進去的東西吃掉:一大段 log、幾百筆搜尋結果、整包 JSON。Headroom 是一個免費開源(Apache 2.0)的工具,夾在 Claude Code 和模型中間,先把這些工具輸出壓縮,重要的留著,再送出去。這篇是 Reels 裡 SAVE 那支影片的完整版:我們在自己電腦上跑出來的真實數字、安裝指令、怎麼用 headroom wrap claude 接上 Claude Code、怎麼看省了多少,以及它省不到的情況。

01先看結果:同一個除錯任務,token 從 55,957 變 24,340

Reels 畫面:3D 筆電上的終端機跑 Headroom 官方測試,SRE incident debugging 那一行 55,957 → 24,340、省 57% 被圈起來,旁邊綠色印章寫省 57%
真實執行:我們在自己電腦上重跑 Headroom 官方的測試程式,數字和 README 一模一樣。

照著做完,你會得到這些:

  1. Claude Code 照常用,但它讀的工具輸出(log、搜尋結果、JSON)會先在你自己的電腦上壓縮,再送給模型。
  2. 重複的內容被壓掉,錯誤訊息這類重要的行會留著。
  3. 一行指令就能看到這一輪省了多少 token。
  4. 讀得少,同樣的額度就用得比較久。

02第 1 步:安裝 Headroom

Reels 畫面:GitHub 上 headroomlabs-ai/headroom 的頁面,Star 78.7k 被圈起來,Apache-2.0 license 被標起來,旁邊紙條寫 Apache 2.0・免費
GitHub 上的 Headroom:Apache 2.0 授權,2026 年 11 月 3 日約 7.9 萬顆星。

Headroom 是 headroomlabs-ai 做的開源專案,需要 Python 3.11 以上。開啟終端機,選一種裝法:

安裝(pip)
pip install "headroom-ai[all]"
另一種裝法(uv,裝在獨立環境)
uv tool install --python 3.13 "headroom-ai[all]"

裝好之後先做一次健康檢查:

檢查
headroom doctor

03第 2 步:用 headroom wrap claude 開 Claude Code

Reels 畫面:Headroom README 的 How it works 圖,你的 agent(Claude Code)在上面,中間的 Headroom 方框被綠色圈起來,下面是 LLM provider
README 的架構圖:Headroom 在你的電腦上跑,夾在 Claude Code 和模型中間。

以後要用 Claude Code 時,改用這一行開:

開 Claude Code(經過 Headroom)
headroom wrap claude

這行指令會做三件事:

  1. 在你的電腦上開一個本機代理(proxy)。
  2. 幫這個專案裝上 Serena(一個看程式碼結構的 MCP 工具),只裝在這個專案。
  3. 用這個代理啟動 Claude Code。之後照常打字就好,送出去的東西會先經過 Headroom 壓縮。
Reels 畫面:README 的 Get started,headroom wrap claude 那一行被圈起來,下方是黑色指令卡
README 的 Get started:先安裝,再用 headroom wrap claude 開。

不想裝 Serena,或想手動接:

不要 Serena
headroom wrap claude --code-memory none
手動:先開代理,再讓 Claude Code 走它
headroom proxy --port 8787
ANTHROPIC_BASE_URL=http://localhost:8787 claude

04第 3 步:看省了多少,用在對的工作上

Reels 畫面:筆電上的終端機,我們專案的兩個工具輸出:node --test 4,134 → 4,134、0% 標紅,npm ls --all --json 15,246 → 11,121、27% 標綠
真實執行:同一個工具,測試結果文字沒省,npm ls 的 JSON 省 27%。

開著 headroom wrap claude 的時候,另開一個終端機看即時節省:

看即時節省
headroom dashboard

Headroom 最有感的是 Claude Code 要讀一大堆輸出的時候:

  1. 很長、很重複的 log 和建置、測試輸出。
  2. API 回傳的 JSON、資料庫查詢結果、幾百筆的搜尋結果。
  3. 工具用很多次的長對話,輸出一直累積。

這種工作可以直接叫 Claude Code 去讀,讓 Headroom 幫你壓:

適合的工作(換成你的檔案)
幫我讀[log 檔或指令,例如:logs/server.log],找出第一個錯誤、它發生的原因,和最可能的修法。

05答案會不會變差?

Reels 畫面:README 的 Accuracy 表,GSM8K 那一行被圈起來,Baseline 0.870 和 Headroom 0.870 都標綠
官方 README 資料:GSM8K 數學題,用和不用 Headroom 都是 0.870。

Headroom 的 README 有一張準確度表:GSM8K 數學題 100 題,不用是 0.870,用了也是 0.870;TruthfulQA 從 0.530 到 0.560,官方自己說這個差距在誤差範圍內,算沒有差別。被壓掉的原文會先存在你的電腦上,模型需要時可以呼叫 headroom_retrieve 拿回完整內容。

Reels 畫面:Claw'd 站在寫著 Headroom 的壓縮機上,左邊一疊灰色方塊推進去,右邊出來一疊比較矮的綠色方塊,下方計數器寫 24,340 token
同樣的答案,送進去的 token 少了。

06要注意

  1. 不是每次都省:短的輸出、純文字、程式碼大多原封不動送出,省最多的是重複的 log 和 JSON。
  2. 它預設會送匿名統計(壓縮比例、模型名稱、作業系統,不含你的提示或程式碼);不想要就設環境變數 HEADROOM_TELEMETRY=off。
  3. Claude Code 走 Headroom 的時候,Remote Control 用不了;需要時就直接開 claude,不要經過它。
  4. headroom wrap claude 會幫專案裝 Serena;不想要就加 --code-memory none。不用了就輸入 headroom unwrap claude 還原。
  5. README 裡有付費的 Headroom Enterprise(給團隊),個人用開源版就好,原始碼都在 GitHub 上。
  6. 這篇是在主頁連結輸入關鍵字 SAVE 找到的,不會私訊。

資料來源

延伸閱讀