Token 优化指南

面向 Cursor · Claude Code · Codex（Cursor 全套餐已可用 Grok 4.5）。已�?GitHub API 扫描 token-optimization 专题�?strong>802 仓，�?stars 排序�?026-06），�?专题分析；安装配置见各章节�?/p>

最后更新：2026-07-15 · 专题 #1 RTK�?6K★）· #2 Headroom�?1K★）· #3 LeanCTX�?.9K★）· AINav 工具卡片

Grok 4.5�?026-07）：主打编程/Agent，API �?$2 / $6 每百�?token（输�?输出），官方称任�?token 效率更高。在 Cursor �?Grok 4.5 时仍建议配合下文 RTK / Headroom / Rules 压缩，避�?Agent 多轮把「便宜单价」打成「贵账单」。独�?CLI �?Grok Build�?

🚀 Headroom �?专题旗舰（全栈压缩）

headroomlabs-ai/headroom �?专题 #2�?1K★）：全栈压�?strong>工具输出、日志、RAG、文件与历史，CCR 可逆。适合重度编码 / 长任�?/ RAG / 团队控本 �?最佳实�?/a>�?/p>

四种接入
  • Library �?Python/TS compress()
  • Proxy �?headroom proxy --port 8787
  • Wrap �?headroom wrap claude|codex
  • MCP �?headroom mcp install
Agent 兼容

Claude Code Codex wrap �?/p>

Cursor 手动代理 URL（见下）

�?Agent 共享 memory · headroom learn 写规�?/p>

实测节省（官方）

代码搜索 92% · SRE 排障 92% · Issue 分拣 73%

输出侧：HEADROOM_OUTPUT_SHAPER=1 减废�?thinking

安装�?0 秒）
pip install "headroom-ai[all]"    # Python 3.10+，推�?
# �?npm install headroom-ai

headroom perf                     # 查看节省
headroom dashboard                # 代理运行时开面板

企业网络 SSL 拦截�?Corporate / SSL 章节�?/p>

Claude Code
headroom wrap claude
# 可选：--memory --code-graph --1m

一键起代理并启�?Claude Code；压缩经代理管道进入模型�?/p>

Codex
headroom wrap codex

�?Claude 共享 memory 存储�?code>headroom learn 可写 AGENTS.md�?/p>

Cursor
headroom wrap cursor
# 或先起代理：
headroom proxy --port 8787

Cursor 无自�?wrap：命令会打印需�?Cursor Settings 里粘贴的 Override OpenAI Base URL（及 Anthropic 等价项）。按终端提示填入即可�?/p>

MCP 与输出压�?/div> 
headroom mcp install
# 工具：headroom_compress / headroom_retrieve / headroom_stats
export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

输出塑形：减少模型寒暄与 routine 步骤上的深度 thinking（代理侧，无需改业务代码）�?/p>

🎯 LeanCTX �?上下文门控（专题 #3�?/h2>

yvgude/lean-ctx �?�?Headroom「压体积」互补：控制 Agent 能看见什�?/strong>，减少无关文件、工具结果与 RAG 垃圾注入。适合长任务、多 MCP、大仓扫库�?/p>

�?Headroom / RTK 怎么�?/div>
  • LeanCTX �?门控注入源（哪些进上下文�?/li>
  • Headroom / RTK �?压缩已进入上下文的内�?/li>
  • Tokscale �?观测三者叠加后的真实用�?/li>

三省接入：作�?Agent 中间件或上下文层，与 Cursor Rules / Claude Code / Codex �?MCP 工具链并列部署；详见仓库 README �?examples/�?/p>

📐 Headroom 最佳实践：分层策略 + 基线量化 + 动态调�?/h2>

核心原则�?strong>不要无脑开最高压�?/strong>。唯一判断标准—�?em>总成�?= 省下�?Token �?< 返工多花�?Token �?/em>。ContentRouter 会按 JSON / 代码 AST / 文本自动选压缩器；你要做的是按场景设力度，并�?holdout 对照�?/p>

一、前置：先算清「基准账」（必做�?/h3>

所�?Agent 统一�?Headroom 代理 1�? �?/strong>后再调参，不要上来就拉满压缩�?/p> 

# 代理运行中或 wrap 会话结束�?
headroom perf              # 汇总节省与近期趋势
headroom stats             # 更细的统计（亦可 MCP：headroom_stats�?
headroom output-savings    # 输出侧节省（含置信区间）
headroom dashboard         # 可视化面板（需 proxy 在跑�?/pre>
    
重点�?3 个指�?/strong>（可�?Tokscale 交叉验证账单）：

    
    
      
  • 单任务平�?Token 成本
    • 
      
  • 任务首次成功�?/strong>（无需返工的比例）
    • 
      
  • 返工�?/strong>（修偏方向、重跑测�?检索的次数�?/li>
    

    
成功率掉 5%+ 时，先降压缩力度或加�?holdout，再谈继续省 Token�?/div>

二、按内容类型分层压缩（最关键�?/h3>
内容类型建议力度场景落地方式
日志 / 测试输出 / 工具返回
pytest�?code>ls -R、JSON 列表		 80�?5% 跑测试、读日志、修 bug；重复高、语义密度低 代理默认 ContentRouter �?SmartCrusher 自动识别，一般无需额外配置
RAG 检索片�?/ 企业文档 chunks 70�?0% 内部 Agent、知识库问答；压重复与低相关段落 检索后先压缩再�?Prompt（见下方 RAG 示例）；保留标题/来源等元数据�?/td>
大型仓库文件 / 非核心代�?/td> 50�?0% Cursor 改大仓、扫引用；压空行/注释，留签名与核心逻辑 Claude/Codex�?code>headroom wrap �?--code-graph；压后可�?headroom_retrieve 回查原文
异常堆栈 / 权限 JSON / 安全逻辑 �?0% �?bypass 线上事故、权限校验、金�?医疗 敏感任务走代�?bypass 或临时不�?wrap；可�?.contextignore 硬排除路�?/td>
核心业务逻辑 / 安全审计 不建议压 架构设计、审计；缺上下文易漏风险 该任务直连模型或 bypass；宁可多 Token 也不误判
经验边界�?/strong>官方 benchmark 显示日志/工具类压�?90%+ 准确率几乎不降；代码语义类压�?70% 可能丢关键信�?/strong>，不要迷�?95%。压过头�?CCR headroom_retrieve 拉回原文�?

三、分场景落地（Codex / Claude Code / Cursor�?/h3>
1. AI 编码日常（三省）
# Claude Code / Codex：代码图 + �?Agent 记忆
headroom wrap claude --code-graph --memory
headroom wrap codex --code-graph --memory

# Cursor：统一出口代理（Settings �?Base URL�?
headroom proxy --port 8787
export HEADROOM_OUTPUT_SHAPER=1
export HEADROOM_OUTPUT_HOLDOUT=0.1   # 10% 对照组，dashboard �?measured

改大仓、长测试：常�?50�?0% 输入节省�?code>--code-graph 帮助 CodeCompressor 少压断引用�?/p>

注意：环境变量名�?HOLDOUT 不是 HOLDOFF；对已在跑的共享 proxy，Headroom 支持 loopback 热同�?runtime-env�?/small>

2. RAG / 企业内部 Agent
from headroom import compress

def retrieve_and_compress(query):
    chunks = rag_retrieve(query)
    msgs = [{"role": "user", "content": c.text} for c in chunks]
    return compress(msgs, model="claude-sonnet-4-20250514")

多文档检索常�?60�?0% 输入 Token；无关片段被压掉，模型更少「读偏」�?/p>

3. 团队成本管控
  • 全员统一 headroom proxy --port 8787 出口，Dashboard 看总账
  • 日常开发：默认代理 + 输出塑形；核心评�?事故：成员自�?bypass 或不�?wrap
  • 定期�?code>headroom learn --verbosity --apply 从会话学简洁偏�?/li>
  • �?Tokscale 并用：Headroom 看压缩率，Tokscale 对账真实账单
4. 输出 Token（常被忽略）
export HEADROOM_OUTPUT_SHAPER=1
export HEADROOM_OUTPUT_HOLDOUT=0.1
headroom proxy --port 8787

headroom learn --verbosity          # 预览从会话学到的简洁度
headroom learn --verbosity --apply  # 写入配置，proxy 沿用

Opus 档输出单价可达输�?5×；塑形减寒暄�?routine 步骤上的 deep thinking�?/p>

四、三条红�?/h3>
�?永远�?holdout

至少 HEADROOM_OUTPUT_HOLDOUT=0.05�?code>0.1。成功率�?5%+ 立刻降力度或加大对照比例�?/p>

�?三类不激进压

线上事故排查、安全审计、金�?医疗——bypass 或直连，宁多�?Token 不误判�?/p>

�?返工 > 节省

模型因上下文被压而修错方向，返工 Token 常为省下�?2�? �?/strong>�?/p>

五、进阶：�?AI 工程基础设施

  • CI/CD / Agent 巡检：流水线默认高压缩（日志/测试输出为主�?/li>
  • 人工核心开�?/strong>：临�?bypass 或关 OUTPUT_SHAPER
  • Mac 加�?/strong>�?code>export HEADROOM_EMBEDDER_RUNTIME=pytorch_mps，压缩嵌入几乎不拖慢代理
  • 敏感路径：项�?.contextignore / 全局 ~/.claude/.contextignore 硬排除审计文�?/li>

按此�?2�? 周，编码账单常见�?40�?0%，且返工率不应明显上升。若某栈（Go 微服务调试、Java 大仓重构）要更细参数，以 headroom perf + holdout 实测为准，再微调�?/p>

🧱 五层框架（单工具 vs 组合�?/h2>
路径 A（一站式）：Headroom（见 最佳实�?/a>）wrap/proxy/MCP�?strong>路径 B（组合）�?/strong>RTK + Caveman + mcprune + Tokscale �?更细、可混搭�?/div>
�?规约�?每轮固定成本

压缩 AGENTS.md�?code>.cursor/rules�?code>CLAUDE.md。Power User 常在开聊前就烧�?5�? �?token�?/p>

工具�?/strong>codex-tokens-compress、Caveman /caveman-compress

�?CLI 输入�?最大隐性开销

git status、测试日志�?code>rg 输出经代理压缩后再进上下文，通常�?60�?0%�?/p>

工具�?/strong>RTK�?a href="https://github.com/claudioemmanuel/squeez" target="_blank" rel="noopener">squeez（专题热门）

�?Agent 输出�?/div>

去掉寒暄与重复解释，保留技术结论与完整代码块�?/p>

工具�?/strong>Caveman Skill（约 65�?7% 输出 token�?/p>

�?浏览�?/ 单页�?/div>

默认无障碍树，禁止先截图。首屏全�?snapshot，之后用 ref 操作�?diff�?/p>

工具�?/strong>mcprune�?a href="https://github.com/malovnik/agent-browser" target="_blank" rel="noopener">agent-browser

�?MCP �?/div>

压工�?description 与大�?JSON 返回�?/p>

工具�?/strong>caveman-shrink�?a href="https://tokentamer.app/" target="_blank" rel="noopener">Token Tamer�?a href="https://github.com/ooples/token-optimizer-mcp" target="_blank" rel="noopener">token-optimizer-mcp

�?观测�?/div>

先量化再优化：按�?模型/任务类型看账单�?/p>

工具�?/strong>Tokscale（三端均支持�?/p>

📦 三套推荐组合

一站式�? 个）

Headroom �?�?分层最佳实�?/a> �?wrap/proxy；Claude/Codex 一键，Cursor 配代�?+ holdout�?/p>

HeadroomHOLDOUT+Tokscale
极简组合�? 个）

RTK + Caveman �?不装 Headroom 时的最�?CLI + 输出覆盖�?/p>

RTKCaveman
重度浏览�?/div>

任一路径 + mcprune（页面快照仍建议专用剪枝）�?/p>

+mcprune

⌨️ Cursor 安装配置

Cursor RTK �?CLI 输出压缩
  1. 安装 RTK（见 官方安装，Rust 单二进制）�?/li>
  2. 初始�?Cursor hook�?/li> 
rtk init -g --agent cursor

重启 Cursor。Hook 通过 preToolUse 自动�?git status 改写�?rtk git status�?/p>

Windows 注意�?/strong>�?bash hook 不可用，�?Cursor Settings �?Rules 中写明：终端命令一律加 rtk 前缀�?code>rtk git�?code>rtk rg�?code>rtk test 等）�?/div>

局限：内置 Read/Grep 工具不走 shell hook；大文件请用 rtk read / rtk grep �?shell 等价命令�?/p>

Cursor Caveman �?输出 + 规约压缩
# macOS / Linux / WSL / Git Bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex

安装器会写入 Cursor Rules，实现会话级简洁输出。手动触发：/caveman；压规约�?code>/caveman-compress CLAUDE.md（对 .cursor/rules 同理）�?/p>

Cursor Tokscale �?用量统计
npx tokscale@latest
# �?npm i -g tokscale

Cursor 需从浏览器导出会话 Cookie 后登录（非解�?~/.cursor 本地库）�?/p> 

tokscale cursor login
tokscale cursor sync

�?cursor.com 开发者工�?�?Cookies 复制 WorkosCursorSessionToken。详�?Tokscale Cursor 文档�?/p>

Cursor MCP 配置路径

项目级：.cursor/mcp.json · 全局�?code>~/.cursor/mcp.json（版本不同可能为 Settings �?MCP）。浏览器�?mcprune 示例见下�?MCP 章节�?/p>

🟠 Claude Code 安装配置

Claude Code RTK
rtk init -g
# 重启 Claude Code

自动安装 PreToolUse hook，Bash 命令透明改写。与 Cursor 相同�?code>Read/Grep/Glob 内置工具不经�?hook�?/p>

Claude Code Caveman
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

支持 hook 自动激活；/caveman-stats 看本会话节省量；/caveman-compress 压缩 CLAUDE.md / 项目记忆文件�?/p>

Claude Code 专题插件：Token Optimizer

alexgreensh/token-optimizer（专题高星）�?上下文工程插件：智能压缩、Dashboard、MCP/技能瘦身等�?/p> 

/plugin marketplace add alexgreensh/token-optimizer
/plugin install token-optimizer@alexgreensh-token-optimizer
# 会话内：/token-optimizer

安装后建议在 /plugin 中对�?Marketplace 开�?auto-update�?/p>

Claude Code MCP

编辑 ~/.claude.json 或项�?.mcp.json �?mcpServers。mcprune / caveman-shrink 配置�?#mcp�?/p>

🟢 Codex 安装配置

Codex 特点�?/strong>部分能力�?AGENTS.md 软约束，hook 覆盖不如 Claude Code/Cursor 完整；Read/Grep 硬注入限制在演进中（�?codex#18491）。规约写清楚收益最大�?
Codex RTK
rtk init -g --codex          # 项目�?AGENTS.md
rtk init -g --global --codex # 用户�?~/.codex/AGENTS.md

依赖模型遵循 AGENTS.md 中的 RTK 指令（规则级集成，非 guaranteed hook）�?/p>

Codex Caveman + 规约压缩
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --only codex

或全量安装后写入 AGENTS.md。用 codex-tokens-compress 生成高密�?AGENTS.md 规则段�?/p>

Codex squeez（专�?· �?Codex CLI�?/div>

squeez �?Rust 零依赖，支持 Claude Code / Codex CLI / Copilot CLI 等，Bash 最高约 95% 压缩 + MCP�?/p> 

# 见仓�?README 按宿主安�?hook；Codex 侧重 ~/.codex/AGENTS.md 软约�?+ bash 管道
Codex Token Optimizer 插件

�?token-optimizer �?Codex 原生插件，TUI �?/plugins 安装。Dashboard 默认 http://localhost:24843/token-optimizer�?/p>

🌐 MCP / 浏览器（三端通用配置�?/h2>
mcprune �?剪枝 Playwright 页面快照
  1. 克隆并安装：
git clone https://github.com/hamr0/mcprune.git
cd mcprune && npm install && npx playwright install chromium

写入 MCP 配置（路径换成你的绝对路径）�?/p> 

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/path/to/mcprune/mcp-server.js", "--mode", "auto"]
    }
  }
}

可�?--headless；模�?act（操作）/ browse（读文档�? auto�?/p>

caveman-shrink �?压缩 MCP 工具描述
{
  "mcpServers": {
    "fs-compact": {
      "command": "npx",
      "args": [
        "caveman-shrink",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/your/project"
      ]
    }
  }
}

将任意上�?MCP 包一层；压缩 description �?prose 字段，工具语义不变�?/p>

单页浏览 checklist（Agent 侧）
  • 默认无障碍树�?strong>禁止为读文字先截图（画布/验证码除外）
  • 每任�?�? 次全�?browser_snapshot，之后用 ref 点击
  • 电商/表单�?mcprune act；文档站�?browse
  • 单步页面感知预算建议 �?6000 tokens
  • �?API / fetch 就不开浏览�?/li>

📋 可复�?Rules 模板

粘贴�?Cursor Rules�?code>CLAUDE.md �?AGENTS.md�?/p> 

## Token 优化

### CLI（必须）
- 终端命令�?RTK：rtk git / rtk rg / rtk test / rtk read
- 不用内置 Read/Grep 读大文件；用 rtk �?head/tail

### 浏览�?
- 默认无障碍树；禁止为读正文先截图
- 每任务最�?1 次全�?snapshot；之后只�?ref 或增�?
- Playwright MCP �?mcprune；模�?act=操作 browse=读文�?

### 输出
- 技术回复：结论先行，无寒暄；代码块保持完整可运�?

### MCP
- �?JSON 返回先精简；工具列表可�?caveman-shrink 包装

### 预算
- 单步页面感知 �?6000 tokens；超限则剪枝或换 API/深链

🔗 GitHub token-optimization 专题分析

�?802 个公开仓库打该 topic（GitHub Search API�?026-06-26）。下表为 Top 项目�?strong>能力分档，星标随社区变化，以专题页为准�?/p>

第一梯队：CLI / 全栈代理（编码助手主战场�?/h3>
#项目�?/th>定位AINav
1rtk-ai/rtk66KCLI 命令输出代理，Rust，三�?hook/规约�?收录
2headroomlabs-ai/headroom51K全栈上下文压缩：库·代理·MCP·wrap·CCR�?收录
3yvgude/lean-ctx2.9K上下文门控：控制 Agent 可见信息�?收录
�?/td>edouard-claude/snip347声明�?YAML �?RTK �?CLI 代理�?/td>
�?/td>zdk/lowfat543精简命令行输出噪�?/td>�?/td>
�?/td>entroly416本地代理，多模型账单 70�?5% 宣称�?/td>

第二梯队：Claude Code / Codex 插件与中间件

#项目�?/th>定位AINav
6alexgreensh/token-optimizer1.4K上下文工程插件，Dashboard，ghost token�?收录
4cytostack/openwolf2.0KClaude Code 开源中间件，削上下�?/td>�?/td>
9nadimtuhin/claude-token-optimizer480Claude 文档/规约压缩模板�?/td>
12ooples/token-optimizer-mcp415MCP 缓存+压缩，偏 Claude Code�?/td>
13IyadhKhalfallah/clauditor408配额监控与自动限�?/td>�?/td>

第三梯队：MCP · 代码探索 · 浏览�?/h3>
#项目�?/th>定位AINav
5jgravelle/jcodemunch-mcp1.9KMCP 代码探索，宣�?95%+ �?Token�?收录
�?/td>hamr0/mcprune�?/td>Playwright 快照剪枝（未�?Top50 但三省常用）�?收录
�?/td>malovnik/agent-browser�?/td>无障碍树浏览�?MCP�?收录

第四梯队：上下文控制 · 记忆 · 编码格式

#项目�?/th>定位
3yvgude/lean-ctx2.9K控制 Agent「能看见什么」的上下文注入（见第一梯队�?/td>
7lucasrosati/claude-code-memory-setup803Obsidian + Graph �?Claude 会话 Token
�?/td>flightlesstux/prompt-caching127Claude Code 自动 prompt cache
�?/td>skibidiskib/ai-codex273紧凑代码库索引，�?50K+ 宣称

不在专题内但三省常用（高星未�?topic�?/h3>
Caveman�?7K★）未广泛打 token-optimization topic，但在社区与 tokless 安装器中�?RTK 并列推荐 �?AINav 仍收录为输出�?/strong>首�?Skill�?

选型速查（Cursor / Claude Code / Codex�?/h3>
诉求专题首�?/th>组合建议
只压 CLI 测试/git 输出RTK (#1)+ Caveman 压输出；Tokscale 观测
全栈 + RAG + 团队代理Headroom (#2)�?分层最佳实�?/a> + holdout
Claude 插件一站式token-optimizer (#6)�?RTK 二选一或叠加需实测
大仓 MCP 探代�?/td>jcodemunch-mcp (#5)+ mcprune 处理浏览器页
一键装多个插件tokless (#42)聚合 RTK / Caveman �?/td>
说明�?/strong>此前页面曾链�?chopratejas/headroom，官方主仓已迁至 headroomlabs-ai/headroom。专题页�?JS 渲染，完整列表请�?GitHub 专题 �?API search/repositories?q=topic:token-optimization�?