# Claude Code 成本优化

> Claude Code 成本控制工作流:上下文、模型、缓存、MCP、Hooks、子代理和 Passion8 网关观测。

URL: https://docs.passion8.cc/docs/claude-code/cost-saving
Language: zh-CN
Publisher: Passion8

Claude Code 成本失控通常不是单次回答贵,而是上下文越来越厚、任务边界模糊、反复 miss 缓存。先管住工作流,再看缓存字段。




只记一条:新任务先 `/clear`,大任务先 `/plan`,长会话在自然断点 `/compact`。不要把早上的报错带到晚上的部署任务里。




## 成本来源

| 来源 | 为什么涨 | 控制方式 |
| --- | --- | --- |
| 输入 token | 历史、文件、日志、工具输出进入上下文 | `/clear`、精准 `@文件`、少贴长日志 |
| 输出 token | 长解释、重复总结、无约束代码生成 | 要求短结论、表格、diff 或只给方案 |
| 工具输出 | Bash、MCP、浏览器、数据库吐大量内容 | 分页、过滤、限制输出 |
| 缓存写入 | 第一次处理稳定前缀更贵 | 稳定内容少变 |
| 缓存 miss | 模型、effort、MCP 工具定义变化 | 开局定配置,中途少切 |

上下文占用怎么形成,看 [上下文窗口](https://docs.passion8.cc/docs/claude-code/context)。每个内置工具的输出和权限行为,看 [工具参考](https://docs.passion8.cc/docs/claude-code/tools)。

## 推荐工作流





### 开新任务


```text
/clear
```

然后用一句话讲清目标、范围和不动的边界。




### 复杂任务先计划


```text
先只读相关文件,列出最小改动方案和验证命令,不要修改文件。
```




### 执行时控制输出


```text
按方案修改。最终只汇报改了哪些文件、跑了什么验证、剩余风险。
```




### 结束时整理


任务完成后再 `/compact`,或换任务直接 `/clear`。







## `/clear`、`/compact`、`/context`

| 命令 | 什么时候用 | 成本影响 |
| --- | --- | --- |
| `/clear` | 换任务、换模块、旧上下文无关 | 最干净,避免旧历史持续计费 |
| `/compact` | 同一任务很长但还要继续 | 摘要会有一次成本,后续上下文变短 |
| `/context` | 不知道 token 花在哪里 | 先看占用再决定清理 |
| `/rewind` | 想放弃某段错误方向 | 回到旧前缀,通常比 compact 更适合回退 |

## 本地 UI 不一定花 token

| 功能 | 成本判断 |
| --- | --- |
| `/statusline` 脚本刷新 | 本地执行,不调用模型,不花 token |
| `/usage`、`/cost` | 查看用量,不改变 prompt |
| `/theme` | 终端主题,不改变模型请求 |
| 切 `outputStyle` | 生效后改变 system prompt,首轮更贵 |
| OTel metrics/logs | 主要是本机和观测系统成本,不直接增加模型 token |

如果你只是想随时看上下文和成本,优先用 [状态栏](https://docs.passion8.cc/docs/claude-code/statusline),不要让 Claude 每隔几轮“总结一下当前成本”。

## 模型与 effort

模型和 effort 都是缓存 key 的一部分。中途切换会让下一轮全量 miss。

建议:

- 开局用 `/model` 定好模型
- 开局用 `/effort` 定好强度
- 不要在长会话中反复 Sonnet/Opus 切换
- 需要强模型审查时,尽量放在任务末尾独立跑

## 缓存策略

详细机制见 [Prompt 缓存](https://docs.passion8.cc/docs/claude-code/prompt-caching)。这里给使用判断:

| 场景 | 建议 |
| --- | --- |
| 连续 5 分钟内反复改同一模块 | 默认缓存足够 |
| 大上下文,中间经常停 10 到 50 分钟 | API/provider 可考虑 `ENABLE_PROMPT_CACHING_1H=1` |
| Claude subscription 且未超计划额度 | Claude Code 会自动请求 1 小时 TTL |
| 使用 Passion8 或自定义网关 | 看 usage 字段是否透传 cache 读写 |
| 缓存字段一直为 0 | 检查 prompt 太短、网关、模型、effort、MCP |

API 价格倍率:

| 类型 | 价格倍率 |
| --- | --- |
| 5 分钟缓存写入 | 约 1.25 倍输入价 |
| 1 小时缓存写入 | 约 2 倍输入价 |
| 缓存读取 | 约 0.1 倍输入价 |

## 记忆与规则的成本

`CLAUDE.md` 每次启动都会进入上下文。它能省重复解释,但写太长也会增加固定输入。

推荐:

- 根 `CLAUDE.md` 控制在 200 行以内
- 长流程写成 skill 或 custom command
- 模块规则放 `.claude/rules/` 并用 `paths`
- 临时报错、今天的 TODO 不要写进长期记忆

## MCP 成本

MCP 的成本来自两部分:

1. 工具定义进入上下文
2. 工具返回内容进入上下文

优化方式:

- 只连接本任务需要的 server
- 对大工具集开启 tool search,前提是 provider 或网关支持
- 数据库查询必须 limit
- 浏览器工具只截取关键 DOM 或文本
- 调高 `MAX_MCP_OUTPUT_TOKENS` 前先让工具过滤

自定义 `ANTHROPIC_BASE_URL` 时,tool search 可能默认关闭。Passion8 是否支持取决于网关是否转发相关字段。

## 子代理成本

[子代理](https://docs.passion8.cc/docs/claude-code/subagents) 适合隔离大规模调研,因为主会话只接收最终结果,不会把每个文件读取都塞进主上下文。但子代理不是免费:

| 场景 | 判断 |
| --- | --- |
| 大仓库调研、方案对比、并行审查 | 值得用子代理 |
| 一个小文件的小修改 | 不必开子代理 |
| 子代理需要反复多轮 | 注意它有自己的缓存和 5 分钟 TTL |
| `/fork` 复制当前上下文 | 更容易复用父会话缓存,但上下文也更重 |
| 并行改同一仓库 | 用 [Worktrees](https://docs.passion8.cc/docs/claude-code/worktrees) 隔离文件改动 |

## Hooks 帮你省返工

Hook 不一定省本轮 token,但能减少返工:

| Hook | 价值 |
| --- | --- |
| `PostToolUse` 轻量格式化 | 少把格式问题交给模型反复修 |
| `PreToolUse` 阻止危险命令 | 避免跑偏造成大回滚 |
| `Stop` 记录摘要 | 长任务结束后留审计记录 |
| `UserPromptSubmit` 检查敏感信息 | 防止 Key 和隐私进入上下文 |

Hook 要短。每次编辑后跑完整构建可能拖慢工作流,更适合在任务结束时运行。

## 反例

- 一个会话从安装、写代码、闲聊到部署全混在一起
- 每次贴完整日志,不截关键错误
- 要求“看看整个项目”,但不说目标
- 中途频繁改范围
- 一边连接大量 MCP,一边不用这些工具
- 把密钥、临时报错、待办都写进 `CLAUDE.md`

遇到这些情况,先 `/clear`,把任务缩小重说。

## 官方参考

- [Manage costs effectively](https://code.claude.com/docs/en/costs.md)
- [How Claude Code uses prompt caching](https://code.claude.com/docs/en/prompt-caching.md)
- [Explore the context window](https://code.claude.com/docs/en/context-window.md)
- [Claude API prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md)
- [Status line](https://code.claude.com/docs/en/statusline.md)
- [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md)