Headroom 完整指南 2026：用開源工具減少 60-95% 的 LLM Token 成本

Headroom 是什麼？

Headroom 是一個開源的 LLM token 壓縮層，專門用於壓縮 AI Agent 讀取的所有內容——工具輸出、日誌、RAG 檢索結果、檔案和對話歷史——在發送給 LLM 之前進行智慧壓縮。

核心價值：同樣的答案，只用 5-40% 的 token。對於每天大量使用 AI 程式設計助手（Claude Code、Cursor、Codex 等）的開發者來說，這意味著 API 成本直接降低 60-95%。

為什麼需要 Headroom？

現代 AI 程式設計助手的工作流程通常是這樣的：

使用者提問 → Agent 搜尋程式碼庫 → 返回 100+ 檔案片段 → 
Agent 整理所有上下文 → 發送給 LLM → LLM 回答

問題在於：Agent 發送的上下文中，大部分是冗餘的。比如：

• 搜尋結果返回 100 個程式碼片段，但真正相關的只有 5-10 個
• 日誌檔案包含大量無關的時間戳和除錯資訊
• RAG 檢索的文件區塊有很多重複的前綴

Headroom 透過三層架構解決這個問題：

1. ContentRouter — 檢測內容類型（JSON、程式碼、純文字），自動選擇最佳壓縮器
2. 智慧壓縮器 — SmartCrusher（JSON）、CodeCompressor（AST 感知）、Kompress-base（HF 模型）
3. CCR（可逆壓縮） — 原始資料儲存在本機，LLM 需要時可以按需檢索

Headroom vs 其他方案

特性	Headroom	原生 Provider 壓縮	手動精簡 prompt
Token 節省	60-95%	20-40%	取決於人工
跨 Agent 共享記憶	✅	❌	❌
可逆壓縮（CCR）	✅	❌	N/A
零程式碼接入（Proxy）	✅	❌	N/A
本機運行	✅	❌（雲端）	✅
支援多語言	Python + TS	僅限 SDK	N/A

---

安裝 Headroom

Headroom 支援 Python 和 Node.js，推薦使用 pip 安裝全功能版本。

Python 安裝

# 安裝完整版本（包含 proxy、MCP、ML 等所有功能）
pip install "headroom-ai[all]"

# 或者按需安裝子模組
pip install "headroom-ai[proxy]"   # 僅代理模式
pip install "headroom-ai[mcp]"     # 僅 MCP 伺服器
pip install "headroom-ai[ml]"      # 機器學習壓縮模型

要求：Python 3.10+

Node.js / TypeScript 安裝

npm install headroom-ai

驗證安裝

# 檢查版本和功能
headroom --version

# 執行效能測試，查看當前環境的壓縮效果
headroom perf

---

快速上手：三種使用模式

Headroom 提供三種接入方式，從易到難：

模式一：Wrap 指令（最簡單，零設定）

如果你已經在使用某個 AI 程式設計助手，只需一條指令即可啟用 Headroom：

# 包裝 Claude Code
headroom wrap claude

# 包裝 Codex
headroom wrap codex

# 包裝 Cursor
headroom wrap cursor

# 包裝 Aider
headroom wrap aider

# 包裝 GitHub Copilot CLI
headroom wrap copilot

執行後，Headroom 會自動： 1. 啟動本機代理服務（預設埠號 8787） 2. 修改對應 Agent 的設定，將請求路由到代理 3. 列印設定說明，告訴你如何驗證是否生效

範例：包裝 Claude Code

$ headroom wrap claude

✅ Headroom proxy started on port 8787
✅ Claude Code config updated

To verify, run:
  claude "What is 2+2?"

You should see compression stats in the output.

之後每次使用 claude 指令時，請求都會先經過 Headroom 壓縮，再發送給 Anthropic API。

模式二：Proxy 代理模式（零程式碼改動，適合任何語言）

如果你不想修改現有程式碼，或者使用的是不支援 wrap 的工具，可以單獨啟動代理服務：

# 啟動代理，監聽 8787 埠號
headroom proxy --port 8787

然後修改你的應用程式或 Agent 設定，將 API 端點指向 http://localhost:8787 而不是原始的 Anthropic/OpenAI 端點。

範例：OpenAI 相容客戶端

from openai import OpenAI

# 原本的設定
# client = OpenAI(api_key="sk-...")

# 改為透過 Headroom 代理
client = OpenAI(
    api_key="sk-...",
    base_url="http://localhost:8787/v1"  # 指向 Headroom 代理
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "解釋這段程式碼"}]
)

所有經過代理的請求都會被自動壓縮，無需修改業務邏輯。

模式三：Library 函式庫模式（最靈活，嵌入應用程式）

如果你正在開發自己的 AI 應用程式，可以直接呼叫 Headroom 的壓縮函數：

Python 範例

from headroom import compress

messages = [
    {"role": "user", "content": "分析這個日誌檔案"},
    {"role": "assistant", "content": "請提供日誌內容"},
    {"role": "user", "content": "[... 10000 行日誌 ...]"}
]

# 壓縮訊息
compressed = compress(messages, model="claude-3-sonnet")

print(f"原始 token: {compressed.original_tokens}")
print(f"壓縮後 token: {compressed.compressed_tokens}")
print(f"節省: {compression.savings_percent}%")

# 發送給 LLM
response = anthropic_client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=1024,
    messages=compressed.messages  # 使用壓縮後的訊息
)

TypeScript 範例

import { compress } from 'headroom-ai';

const messages = [
  { role: 'user', content: 'Analyze this codebase' },
  { role: 'assistant', content: 'Please provide the files' },
  { role: 'user', content: '[... 50 files ...]' }
];

const compressed = await compress(messages, { model: 'gpt-4' });

console.log(`Saved ${compressed.savingsPercent}% tokens`);

---

核心功能詳解

1. 智慧壓縮演算法

Headroom 內建了多種壓縮演算法，根據內容類型自動選擇：

SmartCrusher — JSON 壓縮

專門處理結構化資料（API 回應、設定檔案、資料庫查詢結果）：

from headroom import SmartCrusher

data = {
    "users": [
        {"id": 1, "name": "Alice", "email": "alice@example.com", "created_at": "2024-01-01"},
        {"id": 2, "name": "Bob", "email": "bob@example.com", "created_at": "2024-01-02"},
        # ... 1000+ records
    ]
}

crusher = SmartCrusher()
compressed = crusher.compress(data)

# 保留關鍵欄位，移除冗餘中繼資料
# 原始: 50,000 tokens → 壓縮後: 5,000 tokens (90% 節省)

CodeCompressor — AST 感知程式碼壓縮

理解程式碼語法樹，只保留關鍵結構：

from headroom import CodeCompressor

code = """
def calculate_total(items):
    '''Calculate total price with tax'''
    total = 0
    for item in items:
        if item.active:
            total += item.price * item.quantity
    tax = total * 0.08
    return total + tax
"""

compressor = CodeCompressor(language="python")
compressed = compressor.compress(code)

# 保留函數簽名、控制流程、關鍵變數
# 移除註解、空白、非關鍵實作細節

支援的語言：Python、JavaScript、Go、Rust、Java、C++

Kompress-base — 通用文字壓縮

基於 HuggingFace 訓練的專用模型，處理自然語言、文件、日誌等：

# 首次使用時會自動下載模型（約 500MB）
headroom proxy

# 模型快取位置: ~/.cache/headroom/kompress-base

2. CCR 可逆壓縮

CCR（Compress-Cache-Retrieve） 是 Headroom 的核心創新：壓縮後的資料發送給 LLM，但原始資料仍然儲存在本機。如果 LLM 需要查看完整內容，可以呼叫 headroom_retrieve 工具取得。

工作流程：

1. Headroom 壓縮內容 → 發送給 LLM
2. LLM 發現需要更多細節 → 呼叫 headroom_retrieve(chunk_id)
3. Headroom 從本機快取返回原始資料
4. LLM 獲得完整資訊，繼續推理

優勢： - LLM 首次接收的是壓縮版，token 用量少 - 只在必要時才檢索完整內容，避免一次性發送大量資料 - 原始資料永遠不會遺失

3. 跨 Agent 共享記憶

如果你同時使用多個 AI 助手（比如 Claude Code + Codex + Cursor），Headroom 可以讓它們共享壓縮後的上下文：

# 啟用共享記憶
headroom wrap claude --memory
headroom wrap codex --memory

現在，Claude Code 處理過的程式碼庫索引會被快取，Codex 可以直接複用，無需重新掃描。這對於大型專案特別有用。

4. MCP 伺服器整合

Headroom 可以作為 MCP（Model Context Protocol）伺服器運行，任何支援 MCP 的客戶端都可以呼叫：

# 安裝 MCP 伺服器
headroom mcp install

# 可用的 MCP 工具：
# - headroom_compress: 壓縮任意內容
# - headroom_retrieve: 檢索原始資料
# - headroom_stats: 查看壓縮統計

範例：在 Claude Desktop 中使用

// claude_desktop_config.json
{
  "mcpServers": {
    "headroom": {
      "command": "headroom",
      "args": ["mcp", "serve"]
    }
  }
}

---

實戰案例

案例一：程式碼庫搜尋優化

場景： 讓 AI 助手在一個 10 萬行程式碼的專案中尋找某個功能的實作。

不使用 Headroom：

Agent 搜尋 → 返回 100 個相關檔案 → 全部發送給 LLM → 
Token 用量: 17,765 → 成本高，回應慢

使用 Headroom：

headroom wrap claude
claude "找到使用者認證模組的實作"

Agent 搜尋 → Headroom 壓縮 100 個檔案 → 
Token 用量: 1,408 → 節省 92%

實際測試資料：

工作負載	壓縮前	壓縮後	節省
程式碼搜尋（100 個結果）	17,765	1,408	92%
SRE 事故除錯	65,694	5,118	92%
GitHub Issue 分類	54,174	14,761	73%
程式碼庫探索	78,502	41,254	47%

案例二：多 Agent 協作

場景： 用 Claude Code 做程式碼審查，用 Codex 產生單元測試，用 Cursor 重構程式碼。

傳統方式： 每個 Agent 都要獨立掃描程式碼庫，重複消耗 token。

使用 Headroom 共享記憶：

# 第一步：Claude Code 掃描並快取
headroom wrap claude --memory
claude "審查 src/auth/ 目錄的程式碼品質"

# 第二步：Codex 複用快取
headroom wrap codex --memory
codex "為 src/auth/ 產生單元測試"
# Codex 直接使用 Claude 快取的索引，無需重新掃描

# 第三步：Cursor 繼續複用
headroom wrap cursor --memory
cursor "重構 src/auth/ 的錯誤處理"

節省效果： 第二次及後續的 Agent 可以節省 40-60% 的初始掃描 token。

案例三：日誌檔案分析

場景： 除錯生產環境問題時，需要讓 AI 分析 10,000 行的日誌檔案。

from headroom import compress
import anthropic

# 讀取日誌
with open("production.log") as f:
    logs = f.read()

messages = [
    {"role": "user", "content": f"分析這個日誌，找出錯誤原因:\n{logs}"}
]

# 壓縮
compressed = compress(messages, model="claude-3-sonnet")

print(f"原始: {compressed.original_tokens} tokens")
print(f"壓縮後: {compressed.compressed_tokens} tokens")
print(f"節省: {compressed.savings_percent}%")

# 發送
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=2048,
    messages=compressed.messages
)

print(response.content[0].text)

典型效果： 65,694 tokens → 5,118 tokens（節省 92%），而且關鍵錯誤資訊不會遺失。

---

效能基準測試

Headroom 在標準基準測試上保持了準確性：

基準測試	類別	樣本數	基線準確率	Headroom 準確率	差異
GSM8K	數學	100	0.870	0.870	±0.000
TruthfulQA	事實性	100	0.530	0.560	+0.030
SQuAD v2	QA	100	—	97%	19% 壓縮率
BFCL	工具呼叫	100	—	97%	32% 壓縮率

結論： Headroom 在保持準確性的同時，實現了顯著的 token 節省。

重現基準測試：

python -m headroom.evals suite --tier 1

---

進階設定

CacheAligner — 提升 Provider KV 快取命中率

CacheAligner 會穩定 prompt 的前綴，使得 Anthropic/OpenAI 的 KV 快取能夠命中，進一步降低成本：

from headroom import CompressionMiddleware

# 在 ASGI 應用中新增中介軟體
app.add_middleware(CompressionMiddleware)

headroom learn — 從失敗中學習

Headroom 可以挖掘失敗的會話，自動將修正寫入 CLAUDE.md 或 AGENTS.md：

# 啟用學習模式
headroom wrap claude --learn

# 當 Claude Code 給出錯誤答案時，Headroom 會：
# 1. 分析失敗原因
# 2. 產生修正提示
# 3. 寫入專案的 CLAUDE.md
# 4. 下次會話自動套用修正

自訂壓縮策略

你可以透過 Pipeline 擴充自訂壓縮行為：

from headroom import PipelineExtension

class MyCustomCompressor(PipelineExtension):
    def on_input_received(self, event):
        # 在接收輸入時執行自訂邏輯
        print(f"Received {len(event.content)} bytes")

    def on_input_compressed(self, event):
        # 在壓縮完成後執行
        print(f"Compressed to {event.compressed_size} bytes")

# 註冊擴充
pipeline.register(MyCustomCompressor())

---

常見問題

Q1: Headroom 會影響回答品質嗎？

答： 不會。基準測試顯示準確率保持不變（GSM8K: 0.870 → 0.870）。CCR 可逆壓縮確保 LLM 可以隨時檢索完整內容。

Q2: 資料安全性如何？

答： Headroom 完全本機運行，所有壓縮、快取、儲存都在你的機器上完成。原始資料不會發送到任何外部伺服器。

Q3: 支援哪些 LLM Provider？

答： 理論上支援所有 Provider，因為 Headroom 工作在 prompt 層面。已驗證支援的包括： - Anthropic (Claude) - OpenAI (GPT-4, GPT-3.5) - AWS Bedrock - Google Gemini - 任何 OpenAI 相容 API

Q4: 壓縮會增加延遲嗎？

答： 本機壓縮通常在 10-50ms 內完成，相比網路請求（幾百 ms 到幾秒）可以忽略不計。而且由於發送的 token 更少，整體回應時間通常會更快。

Q5: 適合個人開發者還是團隊？

答： 兩者都適合。 - 個人開發者：每天使用 AI 助手，節省 API 費用 - 團隊：跨 Agent 共享記憶，避免重複掃描程式碼庫；統一壓縮策略，便於成本控制

---

總結

Headroom 是一個解決實際問題的高品質開源工具。對於重度使用 AI 程式設計助手的開發者來說，它可以：

✅ 降低 60-95% 的 token 成本 — 直接省錢
✅ 零程式碼接入 — headroom wrap claude 一條指令搞定
✅ 跨 Agent 共享記憶 — Claude、Codex、Cursor 共用快取
✅ 可逆壓縮（CCR） — 原始資料不遺失，LLM 可按需檢索
✅ 本機運行 — 資料安全，無隱私洩漏風險

如果你的團隊每月在 LLM API 上的支出超過 $100，Headroom 幾乎肯定能幫你省下一大筆錢。

立即開始：

pip install "headroom-ai[all]"
headroom wrap claude  # 或你使用的任何 Agent
headroom perf         # 查看節省效果

專案地址： https://github.com/chopratejas/headroom
文件： https://headroom-docs.vercel.app/docs