Claude Code 缓存优化代理

claude-code-cache-fix 是第三方本机代理，用来稳定 Claude Code 长会话的请求前缀、cache markers、工具排序、TTL 观测和 thinking block 处理。它不是 RTK，也不是 Pragma 服务器组件。

当前支持基线

本文按 claude-code-cache-fix@4.2.1 编写。安装与升级都固定到这个版本，避免上游默认值变化后文档仍显示旧行为。

快速跳转是否需要Pragma 配置健康检查直连回退

可选增强适合 Claude Code 长会话经常 resume、MCP/Skills 多、会话很长，或需要观察 cache、TTL、quota 状态。

不适用 CodexCodex / Copilot 不安装cache-fix 处理 Anthropic Messages 请求。Codex 与 Copilot 用户使用 RTK。

本机第三方代理请求与认证头会经过它只绑定 127.0.0.1，安装前审查源码；不要部署到 VPS，也不要开放公网端口。

先决定是否真的需要

先使用 RTK 省 token 配置 解决长命令输出。只有出现下面任一情况时，再增加 cache-fix：

• --resume、MCP、Skills 或工具定义较多，长会话缓存表现明显波动；
• 想观察 cache read/create、TTL tier、Q5h/Q7d 或 session health；
• 遇到 omitted thinking block 导致的历史重放问题；
• 接受本机 Node 代理读取并整理 /v1/messages 请求体。

短会话、Codex、Copilot、只用网页聊天，通常不需要它。

四条认证路径并列存在

cache-fix 不替你登录，也不会把 OAuth 转成 API key。它只透明转发 Claude Code 已有的认证头。先按当前认证方式选择 upstream：

认证 / 上游	CACHE_FIX_PROXY_UPSTREAM	Claude 启动时的 ANTHROPIC_BASE_URL	关键边界
Pragma API key	https://pragma.academic-ruc.cc	http://127.0.0.1:9801	保留原 Pragma key；不要漏设 upstream
官方 Anthropic API key	默认 https://api.anthropic.com，可不写	http://127.0.0.1:9801	服务端价格与 TTL 由 Anthropic API 账户决定
Claude OAuth / Max / Pro	默认 https://api.anthropic.com，可不写	http://127.0.0.1:9801	不填写 Pragma key；CACHE_FIX_OAUTH_REFRESH 默认保持 off
其他 Anthropic-compatible 中转	该中转的 Claude/Anthropic 根地址	http://127.0.0.1:9801	必须先确认 /v1/messages、流式响应和认证头兼容

如果你还不确定路径，先使用 省 token 决策中心。这四条路线是并列关系，不存在“API 取代 OAuth”或“OAuth 取代 API”。

Pragma API 专用配置

正确链路：

Claude Code → 127.0.0.1:9801 → pragma.academic-ruc.cc → 上游模型

前置：先按 创建 API Key 完成 Pragma ANTHROPIC_AUTH_TOKEN 配置（一般在你的 shell profile 里）。cache-fix 只透明转发这个认证头，不会替你登录；如果环境里没有它，下面的链路会在 Claude 端返回 401。

启动代理前设置：

export CACHE_FIX_PROXY_UPSTREAM="https://pragma.academic-ruc.cc"
cache-fix-proxy server

另开 terminal，在确认代理健康后启动 Claude：

ANTHROPIC_BASE_URL="http://127.0.0.1:9801" claude

你的 Pragma ANTHROPIC_AUTH_TOKEN 保持原配置，不要把真实 key 写进本文命令、截图或反馈日志。

只改 ANTHROPIC_BASE_URL 会走错上游

cache-fix 默认 upstream 是 https://api.anthropic.com。Pragma 用户如果漏设 CACHE_FIX_PROXY_UPSTREAM=https://pragma.academic-ruc.cc，请求可能绕过 Pragma 并返回 401，或进入错误账户。

官方 API key 路线

官方 API 用户可以使用默认 upstream：

cache-fix-proxy server

健康后启动：

ANTHROPIC_BASE_URL="http://127.0.0.1:9801" claude

原 ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN 由 Claude Code 继续携带。cache-fix 改善请求稳定性，但不会为 API 账户创造不存在的缓存价格、TTL 或折扣。

OAuth / Max / Pro 路线

OAuth 用户同样使用官方 upstream，不需要 Pragma API key：

cache-fix-proxy server
ANTHROPIC_BASE_URL="http://127.0.0.1:9801" claude

默认不要设置：

CACHE_FIX_OAUTH_REFRESH=on

代理自管 OAuth refresh 是 4.2.x 的可选高级功能，会接触并写入共享 OAuth 凭据。4.2.0 曾出现 refresh scope 变窄问题，4.2.1 才修复。普通用户继续让 Claude Code 管理登录与刷新，只有理解凭据文件、锁和回滚后才考虑开启。

其他中转 / custom upstream

只有同时满足以下条件，才建议把 cache-fix 接到其他中转：

1. 提供 Anthropic Messages 兼容的 /v1/messages；
2. 正确支持 SSE 流式响应；
3. 接受 Claude Code 当前使用的认证头；
4. 不要求 cache-fix 无法生成的私有签名；
5. 用短请求验证 200/401/429/5xx 能原样、可解释地返回。

示例：

export CACHE_FIX_PROXY_UPSTREAM="https://your-anthropic-upstream.example"
cache-fix-proxy server

不要把 OpenAI-compatible /v1 地址机械填到这里。Codex custom provider 也不能复用本页，它走的是 Responses API。

安装与升级

需要 Node.js 18+：

node --version
npm install -g claude-code-cache-fix@4.2.1
cache-fix-proxy --help

升级时仍固定版本：

npm install -g claude-code-cache-fix@4.2.1

升级后必须重启代理

v4 默认关闭 extension hot reload。npm 安装完成只更新磁盘文件，正在运行的 Node 进程不会自动载入新代码。必须从外部 terminal 重启 supervisor/代理，再做健康检查。

v4.2.1 默认行为

功能	默认	含义
thinking-block-sanitize v1	开启	丢弃 omitted/空文本 thinking block；off 可关闭，v2 为额外 opt-in
extension hot reload	关闭	代码或配置变化后需要 supervisor 级重启；CACHE_FIX_HOT_RELOAD=on 才开启
bootstrap-defense	audit	代理透传并记录 hash/元数据，不阻断；block/allowlist 需明确 opt-in
auto-1M guard	warn	发现 1M beta token 时告警和记录，不默认剥离；strip 会修改请求
OAuth refresh	off	不由 proxy 接管 OAuth 凭据刷新
bind	127.0.0.1	只监听本机，不应改成公网地址

默认值里有会修改请求体的功能，尤其是 thinking sanitize。升级前后应跑短会话与 resume 回归，不要只看进程能启动。

健康检查：200 与 503 的意义

curl -i http://127.0.0.1:9801/health

健康状态：

HTTP/1.1 200 OK
{"status":"ok"}

扩展加载失败时可能返回：

HTTP/1.1 503 Service Unavailable
{"status":"degraded", ...}

503 degraded 不是“代理还能凑合用”。它表示请求变换链不完整，需要重启进程并检查日志。若重启后仍 degraded，先走直连回退，不要让 Claude 长期指向半坏的 9801。

安全启动与直连回退

不要把 ANTHROPIC_BASE_URL=http://127.0.0.1:9801 永久锁死后再忘记代理。更安全的是保留两种启动方式；如果 settings 文件里已有固定 Base URL，也要在独立 terminal 中先备份并清理，不能只依赖 env -u。

Pragma API：

if curl -fsS http://127.0.0.1:9801/health >/dev/null; then
  ANTHROPIC_BASE_URL="http://127.0.0.1:9801" claude
else
  ANTHROPIC_BASE_URL="https://pragma.academic-ruc.cc" claude
fi

官方 API / OAuth：

if curl -fsS http://127.0.0.1:9801/health >/dev/null; then
  ANTHROPIC_BASE_URL="http://127.0.0.1:9801" claude
else
  ANTHROPIC_BASE_URL="https://api.anthropic.com" claude
fi

其他中转把 fallback 地址替换成自己已验证的 Anthropic 根地址。

直连 fallback 分支同样需要当前 shell 里有对应认证：Pragma / 官方 API 用户要保证 ANTHROPIC_AUTH_TOKEN（或官方 ANTHROPIC_API_KEY）已由 profile 提供。如果临时开一个干净 terminal 排障、环境里没有 token，直连分支会返回 401，这是缺认证，不是 Pragma 或上游故障。

不要在当前 Claude 会话里重启自己的代理

如果当前 Claude Code 正通过 9801 通信，在这个会话内执行 npm 升级、kill、service restart 或重写 Base URL，会切断自己正在使用的链路。请在独立 terminal 完成代理维护，确认 /health 为 200 后再新开 Claude 会话。

三层验收

层级	验证	成功标准
proxy_running	curl -i /health	HTTP 200 且 status=ok
claude_routed	新开 Claude，发送“请只回复 OK”	正常返回，代理日志/观测时间更新
cache_observed	查看 ~/.claude/quota-status/	真实会话后出现或更新 account/session 文件

如果代理健康但短请求失败，按顺序检查：

1. Claude 与 proxy 是否在同一 WSL/macOS/Linux 执行平面；
2. ANTHROPIC_BASE_URL 是否为 9801；
3. upstream 是否与认证方式匹配；
4. 401/403 是认证问题，429 是额度/限流，502/503 是代理或上游问题；
5. 立即用直连启动方式区分“代理故障”与“上游故障”。

Windows 与 VS Code

Windows 用户优先让 Claude Code、Node.js、环境变量和 cache-fix 全部运行在同一个 WSL 环境：

which claude

如果输出指向 /mnt/c/Users/.../AppData/Roaming/npm/claude，实际运行的是 Windows shim。此时 WSL 里的 9801 和环境变量不一定被 Windows 进程读取，应先改为 WSL-native Claude，或放弃 WSL 代理路线。

入口	口径
Claude Code CLI on WSL/macOS/Linux	推荐验证路径
VS Code integrated terminal	按 terminal 内实际 CLI 环境判断
VS Code sidebar	可实验，但必须证明请求真的经过 9801
Claude Desktop / Windows 原生	不作为通用默认路线

长期服务

首次先用前台 cache-fix-proxy server 验证。通过后再安装用户服务：

cache-fix-proxy install-service

上一步会写入 service 文件：Linux/WSL 为 ~/.config/systemd/user/cache-fix-proxy.service，macOS 为 ~/Library/LaunchAgents/com.cnighswonger.cache-fix-proxy.plist。下面的 systemctl / launchctl 命令都基于这个文件；如果跳过 install-service 直接 enable，会遇到 "Unit not found" 或找不到 plist。

Linux / WSL：

systemctl --user daemon-reload
systemctl --user enable --now cache-fix-proxy
systemctl --user enable --now cache-fix-proxy-healthcheck.timer

macOS：

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.cnighswonger.cache-fix-proxy.plist
launchctl enable gui/$(id -u)/com.cnighswonger.cache-fix-proxy
launchctl kickstart gui/$(id -u)/com.cnighswonger.cache-fix-proxy

install-service 会捕获安装当时的 CACHE_FIX_PROXY_UPSTREAM、port 和 debug 配置。修改 upstream 或环境变量后，需要 install-service --force 重新生成，或正确编辑 service 文件，再由 supervisor 重启。

升级代码后的重启：

# Linux
systemctl --user restart cache-fix-proxy

# macOS：代码更新可 kickstart；plist 内容变化需 bootout + bootstrap
launchctl kickstart gui/$(id -u)/com.cnighswonger.cache-fix-proxy

不要把 cache-fix 部署到 Pragma VPS，不要让多个未托管孤儿进程争抢 9801。

与 RTK 如何叠加

工具	处理对象	与认证关系	验证方式
RTK	git diff、测试、日志等 shell 输出	无关	rtk session、rtk gain --history
cache-fix	Claude Code /v1/messages 请求与响应	upstream 必须匹配认证	/health、短请求、quota-status

shell 输出 → RTK → Claude Code 上下文
Claude Code 请求 → cache-fix（可选）→ 当前认证对应的 upstream

如何理解“省了多少”

下面三件事不能画等号：

• cache hit rate；
• cache read/create token 数；
• 用户最终账单或订阅额度消耗。

上游 README 的 A/B 命中率来自特定 Claude Code 版本、特定 warm-turn 基线。API key 用户受实际缓存读写价格与 TTL 影响；订阅/OAuth 用户受 Q5h/Q7d、模型、thinking 和服务端策略影响；中转用户还受中转计费与缓存实现影响。cache-fix 只能改善客户端请求稳定性，不能保证“resume 不再计费”，也不能保证固定百分比节省。

安全与隐私

• 代理只应绑定 127.0.0.1；
• /v1/messages 请求体和认证头会经过本机 Node 进程；
• debug 日志开启前先确认不会记录敏感上下文；
• 不粘贴 API key、Authorization header、Cookie、OAuth token 或完整请求体到 issue/聊天；
• CACHE_FIX_OAUTH_REFRESH、bootstrap block/allowlist、auto-1M strip、thinking sanitize v2 都属于高级变更，启用前先备份并做回归。

常见问题

cache-hit 95% 是否代表账单省 95%？

不是。命中率、cache token、订阅 quota 与账单是不同指标。

代理健康但 Claude 不走它？

通常是执行平面或环境变量不一致。先检查 which claude、当前进程环境和 Base URL，再用直连/代理两次短请求对照。

代理挂了会不会把 Claude 一起“改死”？

如果把 Base URL 永久写死到 9801 而没有健康门禁，会。使用本页的安全启动方式，并始终保留直连 fallback。

能替代 RTK 吗？

不能。两者作用层不同；Codex 用户只使用 RTK。

给 agent 的安全配置提示词

请在独立 terminal 中配置 claude-code-cache-fix@4.2.1，不要在正在通过 9801 通信的 Claude 会话里重启代理。

先识别我的认证路径：Pragma API、官方 Anthropic API、Claude OAuth/订阅，或其他 Anthropic-compatible 中转。不要在这些路径之间搬运或猜测 key。

要求：
1. proxy 只绑定 127.0.0.1:9801；
2. upstream 必须与认证路径匹配；Pragma 为 https://pragma.academic-ruc.cc；
3. CACHE_FIX_OAUTH_REFRESH 默认保持 off；
4. 解释 v4.2.1 的 thinking sanitize、bootstrap audit、hot reload off 与 supervisor restart；
5. 验证 /health 的 200 ok 与 503 degraded；
6. 创建代理启动和直连 fallback 两种方式；
7. 只做本机配置，不修改 Pragma VPS、API、Caddy、数据库或账号池；
8. 不打印或记录完整 API key/OAuth token。

相关链接

• 省 token 决策中心
• RTK 省 token 配置
• claude-code-cache-fix v4.2.1
• 上游 README
• PackyAPI cache-fix 指南（可借鉴上手结构，不照搬计费承诺）