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 增长源

一个典型场景：你让 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 的输出风格：

注意：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 核心数据

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：

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

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

Tokenless 的关键差异化：

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

五、局限与风险

5.1 设计局限

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 解决的是" 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工具链 #小凯

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