Tokenless：把 Claude Code 的"token 水龙头"拧紧 80%

一句话定位

Tokenless 是一个本地运行的 Claude Code 上下文压缩中间件，通过 PreToolUse hooks 拦截工具输出、生成索引式 packet、本地存储原始证据，让 Claude 看到的上下文更瘦，而你需要细节时又能随时展开。Coding 模式省 47% token，Chat 模式省 80% token——不调用额外 LLM、不上云、不做智能总结，纯靠策略驱动的确定性压缩。

---

一、问题诊断：为什么 Claude Code 长会话越来越贵

Claude Code 的计费模型是按 API token 消耗。但真正的"token 黑洞"往往不是你写的代码，而是反复进入上下文的历史噪音。

1.1 三个 token 增长源

来源	典型场景	token 规模
大工具输出	测试日志、构建日志、搜索结果、tree 输出、git diff、大文件读取	单次可达 10K-100K+
Agent 轨迹开销	Task/Plan 工具重复携带上下文、长会话的往返历史	每轮累加
响应冗长	Claude 详细解释、代码块、分析过程进入下一轮请求	每轮累加

一个典型场景：你让 Claude Code 运行 npm test，测试输出 5000 行。Claude 看到结果后给你分析。下一轮你问"能不能优化一下"，这 5000 行测试输出 + Claude 的上轮回复全部进入新请求的上下文。几轮之后，上下文膨胀到 200K token，单次请求成本几美元。

1.2 Claude Code 的原生对策

Claude Code 本身有 token 优化机制：

Prompt Caching：重复内容（如系统提示）自动缓存，降低成本
Auto-compaction：接近上下文上限时自动压缩历史
/compact 命令：手动触发对话摘要
/clear 命令：清空前文重新开始

但这些机制的问题在于：

/compact 会丢失粒度细节，你需要告诉 Claude"保留什么"
/clear 意味着丢失全部上下文，需要重新注入背景
auto-compaction 是被动防御，在膨胀之后才触发
工具输出永远是完整进入上下文的——这是最大的开销

---

二、Tokenless 的三层干预

Tokenless 的核心思路是"本地保留原始证据，给 Claude 发索引"。它通过 Claude Code 的 hooks 系统，在三个层面拦截和压缩。

2.1 第一层：Read Packets（大文件读取压缩）

当 Claude Code 读取一个大文件时，Tokenless 拦截输出，将其替换为一个紧凑的 packet：

TOKENLESS-READ-PACKET/0.1
file: /path/to/src/App.tsx
artifact_id: ctx_20260518_abc123
summary: large TSX source packet with imports, declarations, snippets, and nearby files

压缩策略（policy-based，非 LLM 总结）：

低风险文件（CSS/HTML/JSON/日志/文档/lockfiles/生成文件）：>4K token 时压缩
大型 JS/TS/React/Python 源码：>30K token 时压缩，保留 imports、symbols、snippets
大型 Vue/Svelte 单文件组件：>12K token 时压缩，保留组件结构
Go/Rust/Java/Swift/C++：默认不压缩（避免编译型语言的结构破坏）
小文件：直接通过，不压缩

需要细节时展开：

tokenless expand latest --around "DashboardShell" --data-dir ~/.tokenless
tokenless expand latest --lines 120:170 --data-dir ~/.tokenless

2.2 第二层：Edit/Write Packets（工具结果压缩）

当 Claude 执行 Edit、MultiEdit 或 Write 工具后，成功输出通常包含完整的文件片段（old_string + new_string）。对于大文件，这又是一笔 token 开销。

Tokenless 的保守策略：

Edit/MultiEdit 成功输出：>3K token 时压缩为 TOKENLESS-EDIT-PACKET/0.1
低风险 Write 输出：>5K token 时压缩为 TOKENLESS-WRITE-PACKET/0.1
失败/有风险输出：绝不压缩（保留完整错误信息）

风险信号直通（不压缩）：Error、Failed、old_string not found、multiple matches、ambiguous、permission denied、conflict、No changes、partial。

2.3 第三层：响应风格压缩（Chat/Coding Profile）

Tokenless 提供三种响应 profile，直接改变 Claude 的输出风格：

Profile	行为	效果
chat	短、可读的自然语言	6 轮自然对话省 80% 响应 token
coding	密集结构化输出	5 轮 coding 省 47% 请求 token + 44% 响应 token
off	完全关闭，原生行为	基准对照

注意：chat/coding profile 只改变输出风格，不启用 packet 压缩。要与 packet 压缩叠加使用才能达到最大效果。

2.4 Launcher 的隐藏优化：禁用 Task/Plan 工具

tokenless launch 默认禁用高消耗的 Task/Plan 工具：

TaskCreate、TaskUpdate、TaskList、TaskGet
EnterPlanMode、ExitPlanMode

这些工具的 schema 描述和历史记录会反复进入请求上下文。禁用后减少固定开销 + 防止 task-list 历史膨胀。

需要时可通过环境变量启用：TOKENLESS_ALLOW_TASK_TOOLS=1 tokenless launch

---

三、Benchmark 真实数据解析

Tokenless 的 benchmark 基于实际 Claude Code API body 测量，不是 hook 端的估算。

3.1 核心数据

场景	Baseline (off)	Tokenless	节省
5-turn CRM vibe coding, coding profile	4,697,867 request tokens	2,476,391	47.3%
6-turn 自然对话, chat profile	7,223 response tokens	1,442	80.0%
大型 CSS 视觉编辑	1,017,642 request tokens	403,995-473,354	~54-60%
10k-line React/TSX 编辑	917,137 request tokens	545,456	40.5%
多文件 React dashboard	628,261 request tokens	512,521	18.4%
Task/Plan 启用 vs Launcher 默认	1,524,894 request tokens	1,087,753	28.7%

3.2 数据解读

最强场景：自然对话（80% 省 token）

这是 chat profile 单独生效的结果
没有 file tool 或 packet reducer 参与
说明输出风格控制本身就是最有效的 token 节省手段
从 7,223 response tokens → 1,442，意味着 Claude 从"详细解释"模式切换到了"精炼要点"模式

Coding 场景（47.3% 省 token）

coding profile + packet compression 叠加
request tokens 省 47.3%，response tokens 省 44.4%，request count 省 39.3%
注意：request count 减少了 39.3%——这意味着 Claude 需要更少轮次完成任务，因为上下文更干净

大型 CSS 编辑（54-60% 省 token）

CSS 是"低风险文件"，会被 aggressively 压缩
Tokenless 对 CSS/SCSS/Less/HTML/SVG 生成"确定性可编辑摘要"：变量、色板、选择器、媒体查询、动画规则、sections、id/class、交互元素

多文件 Dashboard（18.4% 省 token）

这是最弱场景
可能因为 dashboard 场景涉及大量小文件交互，而小文件不被压缩
说明 Tokenless 的增益与"文件大小分布"强相关——大文件场景收益最大

Task/Plan 禁用（28.7% 省 token）

仅仅是禁用工具 schema + 历史，就有近 30% 节省
说明 Task/Plan 工具的上下文开销不容小觑

3.3 外部研究背书

Tokenless 白皮书引用了 6 篇论文支撑其"压缩不会自动降低质量"的 premise：

论文	核心发现	对 Tokenless 的意义
Brevity Constraints Reverse Performance Hierarchies	简洁约束让大模型在逆缩放问题上准确率提升 26.3%	verbose 不总是更好
Prompt Compression in the Wild	压缩率在 workload、硬件匹配时，质量可保持不变	端到端加速可行
LLMLingua	高压缩比下保留语义完整性	高压缩率可行
LongLLMLingua	长上下文压缩改善关键信息感知	压缩后反而更好
Selective Context	剪枝冗余上下文：50% cost reduction，36% memory reduction，32% latency reduction	冗余剪枝有效
Gist Tokens	学习的 prompt compression：26x 压缩，40% FLOPs reduction	极限压缩可行

这些研究共同指向一个结论：上下文长度是一个可控的工程变量，更短的上下文不必然意味着更低的质量——在某些情况下，去除冗余信息后模型反而表现更好（因为注意力更集中）。

---

四、与 Claude Code 原生策略的对比

策略	原理	粒度	信息损失	适用场景
`/compact`	LLM 总结历史对话	粗（整轮摘要）	高（丢失细节）	长对话后 checkpoint
`/clear`	清空历史	最粗	全部丢失	切换任务
Prompt Caching	重复内容复用	细（token 级）	无	系统提示/重复引用
Auto-compaction	自动摘要	粗	中	被动防御
Tokenless	本地存储 + 索引替换	最细（按需展开）	可控（随时展开原始内容）	工具输出、大文件、长会话

Tokenless 的关键差异化：

/compact 是"摘要"：LLM 重新表述，信息必然损失
Tokenless 是"索引"：原始内容一个字不少，只是从 API 上下文移到了本地磁盘
/clear 是"遗忘"：全部清空，需要时无法恢复
Tokenless 是"折叠"：需要时 expand 一键展开

---

五、局限与风险

5.1 设计局限

局限	说明
仅支持 Claude Code	hooks 系统绑定到 Claude Code 的 PreToolUse 接口，Cursor/Copilot 需适配
Policy-based 压缩不完美	压缩策略是规则驱动，可能遗漏某些噪声输出
小文件可能轻微膨胀	强制小文件走 Tokenless 路径时，packet 包装本身有开销
Read packets 不是编辑证明	压缩后的索引不能用于精确编辑，编辑前需要展开
Token 计数是估算	API-body token 计数 ≠ 精确账单，仅供参考
生态锁定	紧密绑定 Claude Code + Bun.js 环境

5.2 使用风险

最大的风险：编辑前忘记展开

当你看到：

TOKENLESS-READ-PACKET/0.1
file: /path/to/src/App.tsx
artifact_id: ctx_20260518_abc123

然后直接说"在第 120 行加个函数"——Claude 不知道第 120 行是什么。你需要先：

tokenless expand ctx_abc123 --lines 110:130 --data-dir ~/.tokenless

这个"展开-编辑"循环是 Tokenless 的使用税：省 token 的代价是多敲几个命令。

另一个风险：上下文碎片化

如果 packet 太多，Claude 的上下文变成了一堆 artifact_id 的列表，而不是连贯的代码视图。这可能导致：

跨文件重构时丢失全局视角
符号依赖关系被隐藏在 packet 内部
需要频繁展开才能理解代码结构

---

六、使用建议：什么时候开，什么时候关

6.1 推荐开启 Tokenless 的场景

频繁运行测试/构建：日志输出巨大且重复
浏览大型代码库：需要 rg/find/tree 探索，输出量大
处理生成文件：lockfiles、dist、build 输出、CSS/HTML 模板
长会话维护：超过 10 轮的复杂任务
预算敏感：个人开发者、小团队、Max plan 用户接近上限

6.2 建议关闭 Tokenless 的场景

精确重构：需要跨文件理解符号依赖，不宜碎片化
安全审计：法律/金融/医疗/安全代码审查，不应压缩
小白用户：不熟悉 CLI 展开操作，可能忘记展开导致编辑错误
短会话：<5 轮、<10 个文件的任务，压缩收益不明显

6.3 最佳实践

# 1. 安装并配置
npm install -g github:MaxForAI/Tokenless
tokenless repair-hooks --user
tokenless install-commands --user  # 安装 /tokenless 快捷命令

# 2. 启动 Claude Code（默认启用 compression + 禁用 Task/Plan）
tokenless launch

# 3. 根据任务切换 profile
tokenless style coding    # 编码任务，密集输出
tokenless style chat      # 对话任务，精炼回复
tokenless style off       # 需要完整上下文时关闭

# 4. 定期查看统计
tokenless stats --data-dir ~/.tokenless
tokenless api-usage --since 24h

# 5. 定期清理旧 artifacts
tokenless clean --data-dir ~/.tokenless --older-than 7d
tokenless clean --data-dir ~/.tokenless --keep 100

---

七、生态定位："拧紧水龙头" vs "烧干湖水"

Tokenless 和 Garry Tan 的 Tokenmaxxing 哲学形成了有趣的张力：

	Tokenless	Tokenmaxxing (gstack)
核心哲学	省 token：拧紧水龙头，减少浪费	花 token：把 token 烧到极限，换取完整信息
策略	压缩、折叠、本地存储	完整实现、并行会话、穷尽信息
前提	Claude Code 上下文是稀缺资源	Claude Code 上下文成本趋近于零（信息密度 > 成本）
适合谁	预算敏感、个人开发者、长会话维护	创业团队、YC 背景、有 GBrain 缓存
风险	碎片化、忘记展开、信息丢失	token 账单爆炸、没有本地缓存时重复支付

两者并不矛盾：Tokenless 解决的是" Claude Code 原生上下文的浪费问题"，Tokenmaxxing 解决的是"如何最大化 token 的投资回报率"。你完全可以：

用 Tokenless 压缩工具输出和文件读取（减少浪费）
同时用 Tokenmaxxing 的"烧干湖水"策略给 AI 完整任务指令（最大化 ROI）

---

八、一句话总结

Tokenless 不是让 Claude Code "更聪明"，而是让它"更近视"——只看清需要看清的部分，把其余细节藏在触手可及的地方。47% 的 coding 节省来自去除冗余的工具输出和文件内容，80% 的 chat 节省来自让 Claude 学会闭嘴。这是 2026 年 AI 编程工具链中，最务实、最工程师思维的 token 优化方案。

---

参考

Tokenless GitHub: https://github.com/MaxForAI/Tokenless
Claude Code Token 管理文档: https://code.claude.com/docs/en/costs
Prompt Compression in the Wild (论文)
LLMLingua / LongLLMLingua (微软论文)
Selective Context (论文)
Gist Tokens (论文)
Brevity Constraints Reverse Performance Hierarchies (论文)

#Tokenless #ClaudeCode #Token优化 #AI编程 #上下文压缩 #Agent工具链 #小凯