省 token 配置决策中心

先选择你的实际使用方式，再安装组件。“适用于所有用户”指每个人都能得到正确分支，不代表每个人都应安装 RTK、cache-fix 和代理链。

RTK压缩本机 shell 命令输出；与 OAuth、API key、provider 无关。

cache-fix整理 Claude Code 的 Anthropic Messages 请求；只适用于 Claude Code。

Headroom高级实验层；必须按具体模型/provider 做 canary，不能作为普通用户默认。

选择你的路径

客户端

认证 / 上游

系统

入口

Claude Code + Pragma API Key：RTK 主线，cache-fix 按需

推荐组合

RTK 先解决长命令输出；当上下文接近 100k token、频繁 resume/compact，或单日调用量高于订阅额度约 80% 时，再增加 cache-fix。三个信号任一命中即值得开启，都没有就先只用 RTK。两者是不同层，不互相替代。

shell 输出 → RTK 0.43.0 → Claude Code 上下文
Claude Code 请求 → cache-fix 9801（可选）→ Pragma
每层分别健康检查、真实短请求和回滚

RTK: 推荐；认证方式不影响 RTK
cache-fix: 可选：upstream 必须显式设为 https://pragma.academic-ruc.cc

打开对应技术指南 →

默认推荐矩阵

使用场景	普通用户默认	可选增强	不适用 / 不默认
Claude Code + Pragma API	RTK	上下文近 100k / 频繁 resume / 用量近额度 80% 时加 cache-fix，upstream 指向 Pragma	Headroom 不作为公共默认
Claude Code + 官方 API key	RTK	cache-fix 默认官方 upstream	不需要 Pragma 配置
Claude Code + OAuth / Max / Pro	RTK	cache-fix 默认官方 upstream；OAuth refresh 保持 off	不填写 Pragma API key
Claude Code + 其他中转	RTK	仅在 Anthropic Messages/认证头兼容时使用 cache-fix	不盲套 Pragma upstream
Codex OAuth / API / custom provider	RTK	provider-specific Headroom canary（高级）	cache-fix 不适用
GitHub Copilot CLI	手动 `rtk <命令>`	无自动 hook	cache-fix 不适用
sidebar / 桌面端	先切 terminal CLI	仅做明确的产品级实验	不承诺读取 CLI hook

两层省 token 的真实关系

text

命令执行层：shell output → RTK → agent context

Claude 请求层：Claude Code → cache-fix（可选）→ Anthropic-compatible upstream

模型代理层：Headroom（高级、逐 provider/模型 canary）→ upstream

RTK 省下的是进入模型上下文的命令输出；cache-fix 改善的是 Claude Code 请求前缀、cache markers、TTL 与可观测性。任何命中率或单条命令压缩比例都不等于整张账单节省比例。

通用安装原则

先只启用 RTK，完成真实任务 E2E。
Claude Code 用户确有长会话缓存问题时，再单独启用 cache-fix。
每增加一层代理，都要保留直连启动方式。
不在正在依赖该代理的 agent 会话中重启或重装代理。
不用文件不可变锁掩盖错误配置；认证轮换、升级和回滚必须可执行。

通用验收顺序

层级	验收	失败时怎么做
RTK 本体	`rtk --version`、受支持命令 fixture	不进入 agent hook 测试
Hook 配置	配置存在且 Codex/Claude 协议正确	恢复 hook 备份，不改认证
Agent E2E	真实长输出任务后出现 RTK history/session 记录	回退为手动 `rtk <cmd>`
cache-fix 进程	`/health` 为 `200 {"status":"ok"}`	不启动走 9801 的 Claude
Claude 路由	短请求正常且日志/观测更新	立即使用直连启动方式
经济性	对照 cache read/create、TTL、quota 与实际用量	不用 hit rate 代替费用结论

下一步

RTK 省 token 配置：安装、hook、WSL 边界、Codex bridge 与 E2E。
Claude Code 缓存优化：Pragma、官方 API、OAuth、其他中转四条认证路径。
客户端配置总览：先完成基础客户端与 Base URL 配置。
故障排查：401、404、429、网络和服务状态。

省 token 配置决策中心 ​

选择你的路径 ​

Claude Code + Pragma API Key：RTK 主线，cache-fix 按需

默认推荐矩阵 ​

两层省 token 的真实关系 ​

通用安装原则 ​

通用验收顺序 ​

下一步 ​