Claude Code 缓存优化代理

约 1637 字大约 5 分钟

2026-07-21

claude-code-cache-fix 是一个第三方开源工具。它在 Claude Code 与 NexAPI 之间运行本地代理，通过稳定请求结构、工具顺序和缓存标记，提高长对话的 Prompt Cache 命中率，从而减少重复上下文带来的额度消耗。

简单来说，它不会让模型变得更聪明，也不能降低模型本身的价格，只是让可复用的上下文更容易命中缓存。

为什么需要缓存优化

重度使用 Claude Code 时，下面这些情况可能导致相同上下文没有被服务器识别为可复用内容：

使用 claude --resume 恢复较长的历史会话。
启用了较多 MCP、Skills、Hooks 或工具定义。
Claude Code 版本变化后，请求中的标记发生变化。
工具定义的排列顺序不稳定，导致请求结构产生差异。

缓存优化代理会对本地请求进行规范化，让相同的上下文尽量保持一致。

代理处理内容	可能带来的效果
修正恢复会话时的请求结构	降低 `--resume` 后重复计算上下文的概率
移除版本号等不稳定标记	减少客户端升级造成的缓存失效
固定工具和 MCP 定义顺序	让相同配置生成更稳定的请求
补充 `cache_control` 标记	明确标识适合缓存的内容
记录缓存和额度状态	便于在 `~/.claude/quota-status/` 中排查

适合谁用

重度使用 Claude Code、对额度消耗比较敏感。
经常恢复长会话，或启用了较多 MCP、Skills 和 Hooks。
已经完成 NexAPI 直连配置，并愿意维护一个本地代理进程。
熟悉基本的终端命令，能够查看日志和处理端口问题。

以下情况建议暂时不要使用：

刚开始使用 Claude Code，基础直连配置还没有验证成功。
完全不希望接触终端、环境变量或后台服务。
主要问题是模型价格、令牌分组、错误模型、大文件读取或服务端额度限制。

它不能解决所有额度问题

该工具只能优化本地请求结构和缓存相关问题，无法解决模型自身价格、长上下文固有消耗、服务端配额降级、令牌分组错误或频繁读取大文件等问题。

使用前须知

Windows 请使用 WSL

不建议在 Windows 原生 CMD 或 PowerShell 中运行该代理。Windows 用户应在 WSL 的 Linux 环境中完成 Node.js、Claude Code、NexAPI 和缓存代理的整套配置。

不要混用 Windows 原生 Claude Code 与 WSL 中的代理，否则容易出现路径、环境变量、后台进程和 127.0.0.1:9801 端口不一致的问题。

这是第三方工具

安装前请自行评估

claude-code-cache-fix 不是 NexAPI 官方维护的工具，并且会经过本机 API 请求。安装前请检查其最新源码、README、依赖和安全性；更新版本前也建议重新查看变更说明。

开始前准备

先按照 Claude Code 手动配置完成 NexAPI 直连，并确认可以正常对话。
准备一个支持目标 Claude 模型的 NexAPI API 令牌。
确认使用 Linux、macOS 或 WSL 环境，并已安装 Node.js 和 npm。
备份 ~/.claude/settings.json。

最小验证流程

下面的流程适合先验证代理是否能够正常启动。长期使用时，再配置为后台服务。

步骤一：安装代理

npm install -g claude-code-cache-fix

安装后可检查命令是否存在：

cache-fix-proxy --help

步骤二：启动本地代理

在 Linux、macOS 或 WSL 终端中运行：

CACHE_FIX_PROXY_UPSTREAM=https://nexapi.ehytech.com cache-fix-proxy server

保持该终端处于运行状态。代理默认监听 http://127.0.0.1:9801，并将请求转发到 NexAPI。

上游地址与本地地址不要填反

代理上游：https://nexapi.ehytech.com
Claude Code 请求地址：http://127.0.0.1:9801

步骤三：修改 Claude Code 配置

打开 ~/.claude/settings.json，将 ANTHROPIC_BASE_URL 改为本地代理地址。ANTHROPIC_AUTH_TOKEN 仍然使用你的 NexAPI API 令牌。

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:9801",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxx"
  },
  "includeCoAuthoredBy": false
}

如果文件中已经配置了模型映射、MCP 或其他设置，请保留原有字段，只修改 ANTHROPIC_BASE_URL。

不要泄露 API 令牌

不要把包含真实 API 令牌的 settings.json 提交到仓库或发送给他人。发现泄露后，应立即在 NexAPI 控制台删除旧令牌并重新创建。

步骤四：检查代理健康状态

另开一个同环境的终端，运行：

curl http://127.0.0.1:9801/health

正常情况下会返回：

{"status":"ok"}

步骤五：验证 Claude Code

完全退出已经运行的 Claude Code，然后重新打开终端并运行：

claude

发送一条简单消息。能够正常收到回复，说明 Claude Code、本地代理与 NexAPI 已经连通。

长期运行

手动运行 cache-fix-proxy server 只适合临时验证。长期使用时，可以根据操作系统将它配置为后台服务：

Linux / WSL：使用 systemd 或发行版支持的用户级服务。
macOS：使用 launchd。
容器环境：使用现有的进程管理或容器编排方案。

后台服务中必须保留 CACHE_FIX_PROXY_UPSTREAM=https://nexapi.ehytech.com，并确认服务重启后仍监听 127.0.0.1:9801。具体配置以项目的最新 README为准。

故障排查

现象	检查项
`/health` 无法访问	代理进程是否运行、端口 `9801` 是否被占用
健康检查正常但 Claude Code 无法连接	`ANTHROPIC_BASE_URL` 是否为 `http://127.0.0.1:9801`，是否已重启 Claude Code
`401` 或认证失败	NexAPI API 令牌是否完整、有效，令牌分组是否正确
直连正常、代理模式失败	`CACHE_FIX_PROXY_UPSTREAM` 是否为 `https://nexapi.ehytech.com`，查看代理终端日志
Windows 与 WSL 行为不一致	Claude Code、配置文件和代理是否全部运行在同一个 WSL 环境
缓存效果不明显	检查 `~/.claude/quota-status/`，并排查模型、上下文长度和大文件读取

停用与回滚

如果代理出现问题，可以随时恢复直连：

停止 cache-fix-proxy 进程或后台服务。
将 settings.json 中的 ANTHROPIC_BASE_URL 改回 https://nexapi.ehytech.com。
完全退出并重新启动 Claude Code。