claude-code/docs/context/token-budget.mdx

---
title: "Token 预算管理"
description: "精打细算每一个 token——AI 的'注意力'是有限资源"
---

{/* 本章目标：解释 token 预算管理的思路 */}

## Token 是什么

简单理解：token 约等于一个英文单词或半个中文字。AI 处理的所有输入和输出都按 token 计费。

| 类型 | 说明 | 谁付费 |
|------|------|--------|
| 输入 token | 发给 AI 的所有内容（System Prompt + 对话历史 + 工具结果） | 用户 |
| 输出 token | AI 生成的回复和工具调用 | 用户 |
| 缓存 token | 重复发送的内容如果命中缓存，价格更低 | 部分用户 |

## 预算控制的三个层面

<CardGroup cols={3}>
  <Card title="单次请求" icon="1">
    每次 API 调用的最大输入/输出 token
  </Card>
  <Card title="单轮对话" icon="arrows-rotate">
    一个 Agentic Loop 内的累计 token 消耗
  </Card>
  <Card title="整个会话" icon="clock">
    全部对话轮次的累计花费（美元）
  </Card>
</CardGroup>

## 工具输出的预算控制

工具返回的内容可能非常长（一个大文件、一段长日志），直接全部塞给 AI 会浪费大量 token。系统对此有专门的控制：

- **结果截断**：超过长度限制的工具输出自动截断
- **结果替换**：已经被 AI"消化"过的旧工具结果，可以被替换为简短的摘要
- **按需读取**：大文件不一次性读完，AI 可以指定读取范围

## 缓存的经济学

System Prompt 每次都要发送，但大部分内容不变。缓存机制让这部分"免费"（或大幅降价）：

- 首次发送：全价
- 后续请求命中缓存：约 1/10 的价格
- 这就是为什么 System Prompt 的结构被精心设计——不变的部分放前面，变化的部分放后面

## token 警告与自动压缩

| token 使用率 | 系统行为 |
|-------------|---------|
| < 70% | 正常运行 |
| 70% ~ 90% | 显示警告，提示用户可以手动压缩 |
| > 90% | 自动触发压缩 |
| 接近 100% | 强制压缩或终止当前轮次 |