Agent 上下文压缩不是删历史：从六大工具到云端四级水位线，TaoToken 统一 Key 配置实战

1. 长会话跑着跑着就“变傻”，问题多半出在上下文压缩

如果你用 Claude Code 或 Codex 跑过一个超过两小时的重构任务，大概率见过这种场面：前半小时模型思路清晰，改文件、跑测试、修报错一气呵成；到第四十分钟开始，它突然忘了你强调过“不要动 public 接口”，或者把十分钟前已经修好的 bug 又改回去。你以为是模型能力不行，其实更可能是上下文压缩策略在背后“帮倒忙”。

Agent 上下文压缩不是简单删历史。它要解决的核心问题是：当会话窗口被用户指令、工具输出、错误日志、文件内容塞满时，如何让模型在下一轮调用里仍然看见真正重要的东西。粗暴截断会丢关键细节，全量摘要会让语义漂移，而压缩决策不稳定还会打碎 Prompt Cache 前缀，让成本不降反升。

这篇面向正在用 Claude Code、Codex 等 Agent 工具做长任务的同学，给出一套可跟做的方案：用 TaoToken 统一 Key 接入，在 settings.json 和 config.toml 里配置好通道，然后按四级水位线理解压缩触发点，最后用真实请求验证压缩后的行为并排查常见报错。全程不需要你改 Agent 源码，配置骨架可以直接复制。

2. 前置准备：TaoToken 统一 Key 与通道配置

TaoToken 在这里的角色是统一 API 通道：你不需要为 Claude Code、Codex 分别维护不同的 Key 和 endpoint，用一个 Key 就能让多个 Agent 工具走同一条接入路径。对上下文压缩场景来说，这一点很关键——压缩触发依赖真实的 usage.totalTokens，而统一通道能保证不同工具返回的 token 用量口径一致，水位线阈值才有可比性。

先拿到 Key。打开 https://taotoken.net/api-keys ，创建一个新 Key，复制保存。注意 Key 只在创建时完整显示一次，后面配置里要用。

然后确认你的接入地址。API 基地址是 https://taotoken.net/api ，不要加多余路径。模型对话调试入口在 https://taotoken.net/model-conversation ，配置完可以先在那里发一条测试消息，确认 Key 和通道都通。

如果你还没决定用哪个工具，可以先看接入文档 https://taotoken.net/doc ，里面按 Claude Code、Codex 等分别给了配置示例。长期跑编码任务的话，Coding Plan 页面 https://taotoken.net/coding-plan 有面向 Agent 长会话的说明，适合先了解计费和上下文策略。

注意：Key 不要写进会提交到 Git 的文件。下面配置里用环境变量引用，或者放在本地 settings 文件并加入 .gitignore。

3. 可复制配置：settings.json 与 config.toml 骨架

Claude Code 走 settings.json，Codex 走 config.toml。两个文件我都给一份最小可用骨架，你按自己系统改路径即可。

3.1 Claude Code 的 settings.json

Claude Code 的配置文件通常放在用户目录下的 .claude/settings.json。核心是 env 段里的 base URL 和 Key 引用。

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoTokenKey", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" }, "permissions": { "allow": [ "Read", "Edit", "Bash(git status)", "Bash(npm test)" ] }, "context": { "compaction": { "enabled": true, "tier1Threshold": 0.60, "tier2Threshold": 0.80, "tier3Threshold": 0.95, "protectRecentMessages": 6, "protectUserText": true } } }

这里 context.compaction 段是本文的重点。tier1Threshold 到 tier3Threshold 对应后面要讲的四级水位线，protectRecentMessages 表示最近 6 条消息不参与压缩，protectUserText 保证用户原话不被摘要吞掉。不同版本字段名可能有差异，如果启动时报 unknown field，先删掉 context 段确认基础通道能通，再逐项加回。

3.2 Codex 的 config.toml

Codex 的配置一般在 ~/.codex/config.toml。结构比 JSON 更扁平。

model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" [context.compaction] enabled = true tier1_threshold = 0.60 tier2_threshold = 0.80 tier3_threshold = 0.95 protect_recent = 6 protect_user_text = true replacement_cache = true

env_key 指向环境变量名，你在 shell 里 export TAOTOKEN_API_KEY="sk-..." 即可，不要把 Key 明文写进 toml。replacement_cache = true 对应后面要讲的跨轮缓存，保证同一段历史在不同轮次被压成同一种形态，Prompt Cache 前缀才稳定。

3.3 环境变量与启动验证

配置写完后，先导出环境变量再启动工具。

export TAOTOKEN_API_KEY="sk-你的TaoTokenKey" export ANTHROPIC_API_KEY="$TAOTOKEN_API_KEY"

然后启动 Claude Code，发一条最简单的消息确认通道通。

claude -p "回复 ok 两个字"

如果返回 ok，说明 Key 和 base URL 都对。如果报 401，检查 Key 是否复制完整；如果报连接超时，检查 base_url 是否误加了 /v1 之类的后缀。

4. 四级水位线：压缩触发后怎么验证

配置里的三个阈值对应四级水位线里的 Tier 1 到 Tier 3，Tier 0 是默认不压缩。理解每一级触发后发生什么，才能验证配置是否真的生效。

Tier 0 是窗口使用率低于 60%，什么都不做。这是最稳的状态，任何压缩都有信息损失风险，窗口够用就别压。

Tier 1 在 60% 左右触发，做字符串级整理，不调用 LLM。典型动作是截短老工具输出、保留代码块的文件名和前几行、grep 结果只留前几条命中。这一级的目标是挡住无意义膨胀。

Tier 2 在 80% 左右触发，把更老的工具输出替换成占位符，比如 [Content compacted to save space]。模型看到的是“这里曾有内容但已压缩”，而不是继续吞完整日志。

Tier 3 在 95% 附近触发，动用 LLM 做增量摘要。注意是增量：只把上次摘要之后、保护区之前的新增消息合并进旧摘要，而不是每次全量重写。这样摘要输入更短，语义漂移更小。

验证压缩是否真的触发，最直接的办法是看工具返回的 usage。在 Claude Code 里跑一个长任务，观察每轮返回的 token 用量。

claude -p "读取 src 目录下所有 ts 文件，统计每个文件的行数，输出表格" --output-format json

返回的 JSON 里会有 usage 字段。如果 input_tokens 在某一轮突然下降，而任务还在继续，说明 Tier 1 或 Tier 2 生效了。如果下降幅度很大且伴随一段摘要文本，说明 Tier 3 被触发。

另一个验证点是 Prompt Cache。TaoToken 通道返回的 usage 里通常带 cache_read_input_tokens 和 cache_creation_input_tokens。理想情况下，压缩决策稳定后，cache_read 应该持续增长，cache_creation 只在真正新增内容时上升。如果每轮 cache_creation 都很高，说明压缩把前缀打碎了，需要检查 replacement_cache 是否开启。

5. 本篇常见错排查

5.1 报 401 Unauthorized

最常见的原因是 Key 没生效。先确认环境变量导出成功。

echo $TAOTOKEN_API_KEY

如果输出为空，说明 export 没执行或写在了错误的 shell 配置文件里。另一个原因是 settings.json 里 ANTHROPIC_API_KEY 写的是明文旧 Key，覆盖了环境变量。检查配置文件优先级，环境变量通常优先于文件里的值。

5.2 报 model not found

模型名写错了。Claude Code 和 Codex 用的模型名不同，不要混用。Claude Code 用 claude-sonnet-4-20250514 这类，Codex 用 gpt-5-codex 这类。具体可用模型列表看接入文档 https://taotoken.net/doc ，不要凭记忆填。

5.3 压缩后模型行为漂移，忘记用户约束

这是保护区配置不对。检查 protectRecentMessages 是否太小，protectUserText 是否为 true。如果用户贴的关键代码被摘要吞了，模型下一步就会做错。把 protectRecentMessages 调到 8 或 10 试试，代价是压缩释放的空间变少，但行为稳定性会明显提升。

5.4 Prompt Cache 命中率低，成本反而上升

典型症状是 cache_creation_input_tokens 每轮都很高。原因通常是压缩决策不稳定，同一段历史在不同轮次被压成不同形态。解决办法是开启 replacement_cache，让一个 part 一旦决定如何替换就固定下来，后续轮次直接复用。Codex 的 config.toml 里 replacement_cache = true 就是干这个的。

5.5 工具输出被压没了，模型找不到文件路径

这是 Tier 2 的占位符替换太激进。检查是否把带状态意义的工具输出也压了。Task、Skill 这类结构化状态工具不应该被替换成占位符，AskUserQuestion 这类代表用户回答的也不该压。如果配置里没有按工具类型区分，先手动把关键工具加入保护名单。

6. 下一步：按你的场景选入口

配置跑通之后，接下来做什么取决于你的使用场景。

如果你在排查接入问题、Key 报错、通道不通，先去 API Keys 页面 https://taotoken.net/api-keys 重新确认 Key 状态，再对照接入文档 https://taotoken.net/doc 检查配置字段。

如果你想先验证模型在压缩后的行为是否符合预期，用模型对话入口 https://taotoken.net/model-conversation 发几条长上下文测试消息，观察返回的 usage 和摘要文本。

如果你要长期跑编码任务或 Agent 工作流，Coding Plan 页面 https://taotoken.net/coding-plan 有面向长会话的通道说明，适合先把计费和上下文策略对齐再上生产。

压缩配置不是一次调好就完事。跑一段时间后回头看 cache_read 和 cache_creation 的比例，如果 cache_read 占比持续上升，说明你的水位线和保护区设置是稳的；如果 cache_creation 一直很高，就回来调 replacement_cache 和阈值。这套东西的价值不在于某个具体数字，而在于让模型每一轮都看见这一轮最该看的东西。