Claude Code Token 机制与上下文管理

一、核心概念：为什么“输出少，输入就多”？

在大模型（LLM）的底层逻辑中，上下文窗口（Context Window）的分配并不是“输入”和“输出”独立计算的，它们共享同一个固定大小的总配额池。

1. 黄金公式

总请求 Token 数 = 输入历史 (Messages) + 预留输出 (Completion)

2. 核心名词拆解

输入（Messages / Input）：你发给模型的项目代码、之前的对话历史，以及 Claude Code 自动读取的文件内容
输出（Completion / Output）：模型正在思考并即将给你的回复
预留机制（重点）：当你向模型发起请求时，Claude Code 需要向 API 宣告一个最大可能生成的长度（默认通常高达 32,000 Tokens）。即使模型最后只回复了 100 个字，API 依然会按照预留的 32,000 空间去计算总容量是否超限
水杯比喻：水杯总容量固定（如 DeepSeek 官方 API 虽为 128K，但报错显示中转或特定节点硬限制在 102,400）。如果你强行给未来要倒进去的“输出”预留了 32,000 的空间，那么你的历史记录（输入）只要超过 70,400，水杯就会直接溢出报错，导致请求失败

3. 常见消耗 Token 的操作

Shell 输出：运行 npm install、庞大的 grep 搜索或详尽的测试报告
大文件读取：使用 cat 或编辑器打开数千行的源文件
思考链（Thinking blocks）：模型在解决复杂逻辑时的内部推理过程
累积对话：持续数小时的交互，未经过压缩的历史记录

当总请求量超过限制时，API 会返回 400 Error，导致任务中断。

二、参数调整操作指南

要防止溢出，核心就是调整 Completion（输出）的预留值。针对不同场景，有以下几种操作方式：

方式 A：环境变量修改（临时生效 / 当前终端）

操作时机：在终端启动（输入 claude）之前
作用范围：仅在当前终端窗口生效，关闭终端或重启系统后失效
具体命令：
- Mac / Linux：export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192
- Windows (CMD)：set CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192
- Windows (PowerShell)：$env:CLAUDE_CODE_MAX_OUTPUT_TOKENS="8192"
效果：强制将每次回答的预留空间限制在 8192 Tokens（足够写大部分代码），从而给“输入历史”多腾出约 2.4 万 Tokens 的空间

方式 B：配置文件修改（永久生效 / 项目或全局）

操作时机：打开 Claude Code 之前或之后都可以，但修改后需要重新启动 Claude Code 才能读取
作用范围：
- 全局修改（作用于电脑上所有项目）：修改用户根目录下的 ~/.claude/settings.json 文件
- 项目修改（仅作用于当前项目目录）：在项目根目录下的 .claude/settings.json 中配置

具体做法：在 JSON 文件中加上 env 环境变量字典：

{
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "8192"
  }
}

方式 C：会话内命令调整（即时生效 / 当前对话）

操作时机：打开 Claude Code 之后，在对话进行中直接输入
作用范围：仅作用于当前这一次对话会话，重新开启会话或重启 Claude 会失效
常用命令：
- /context：查看当前上下文占用百分比
- /compact：触发自动压缩，让 Claude 把之前冗长的对话进行总结沉淀，迅速释放“输入”占据的大量 Token，且保留当前的业务结论
- /clear：彻底清除当前会话历史。适合上一个重构任务已落盘，开启全新任务的场景

三、四大前沿实践策略（防止信息丢失）

策略 A：外部状态文件法 (The State File Pattern)

核心思想：将“记忆”从 AI 的对话历史中提取出来，持久化到磁盘上

操作：在项目根目录创建 TASK_PROGRESS.md
要求 AI 执行：“在开始前，请将任务拆解到 TASK_PROGRESS.md。每完成一个步骤，请更新该文件。如果发生重启或压缩，请首先读取此文件”
优势：即使执行 /compact 或程序崩溃，AI 只要重新读取该文件，就能实现“无损断点续传”

策略 B：利用 `CLAUDE.md` 注入长效记忆

核心思想：利用 Claude Code 自动读取项目根目录 CLAUDE.md 的特性

内容：存放项目的技术栈、核心架构说明、必须遵守的编码规范、常用的测试命令
优势：即使历史记录被清理，这些“硬知识”依然会在每次请求时作为 System Prompt 的一部分存在

策略 C：主动上下文截断与“微重构”

核心思想：预防胜于治疗，不要让垃圾信息进入上下文

使用 /undo：如果一个搜索命令返回了 500 行无关代码，立即输入 /undo 撤销该操作，这会从上下文中移除那 500 行
精确读取：明确要求 AI “只读取函数 X 的定义，不要读取整个文件”
限制输出：使用 grep -l 只列出文件名，而不是 grep -r 输出所有匹配行

策略 D：多会话流水线 (Multi-Session Pipeline)

核心思想：物理隔离不同性质的任务 Token

调研与实现分离：
- 窗口 1：专门用于阅读庞大的文档或搜索代码，得出结论后整理成简报
- 窗口 2：负责编写代码。只从窗口 1 复制关键的结论和参数
子任务并行：如果需要修改两个互不干扰的模块，开两个终端窗口分别运行 claude

四、遇到 400 错误时的紧急预案

当你看到 maximum context length is 102400 tokens 报错时，请按以下步骤操作：

手动保存：将你认为重要的 AI 推理出的关键逻辑、未提交的代码手动复制到本地记事本
强制保存进度：命令 AI（如果还能响应）：“请将当前完成情况和下一步计划写入 TASK_PROGRESS.md”
执行压缩：输入 /compact
引导恢复：“刚才因为 Token 溢出进行了压缩。请读取 TASK_PROGRESS.md 并继续执行步骤 X”
模型降级（备选）：如果是因为模型试图输出太长（Completion 溢出），尝试切换到更强大的模型（如 Opus）或者命令它：“请分段输出代码，不要一次性重写整个文件”

五、总结备忘

想要保留全部历史，只是解决超限报错 ➡️ 使用方式 A 或 B 调整 Token 数
代码已经写完了，不需要之前的聊天细节 ➡️ 在窗口里使用方式 C 输入 /compact 或 /clear
信赖文件，不信赖对话历史：勤做 Git Commit，保持对话简洁，任务完成一个阶段就 /compact 一次

六、下一步

掌握 Token 管理后，可探索国产大模型适配指南以降低使用成本。