1. 从一次 499 报错说起：cch 架构与 Nginx 在 Claude Code 链路里到底谁管什么
如果你正在用 Claude Code 接入自建网关，多半见过这个场景：终端里claude命令跑着跑着突然卡住，日志里蹦出一行API Error: 499，或者local proxy failed，再或者reading 'choices'这种看起来跟模型八竿子打不着的报错。我第一次遇到时也懵了——明明 Key 是对的，模型 ID 也没写错，为什么请求就是落不到后端？
后来把链路一层层拆开才明白：Claude Code 发出的请求，中间可能穿过 Nginx、穿过 cch（Claude Code Hub）这类自研网关，最后才到真正的 API 通道。每一层都有自己的职责，也都有自己的坑。cch 架构是什么？简单说，CCH = Claude Code Hub，是一个自研的 AI API 代理网关系统，技术栈是 Next.js 15（App Router）做前端入口、Hono 做 API 核心逻辑、PostgreSQL 存配置和用量、Redis 做限流和会话状态。它解决的是"多个 Claude Code 客户端如何统一鉴权、统一计费、统一转发"的问题。而Nginx 是什么？它是一个高性能的 Web 服务器和反向代理服务器，负责在最外层接收请求、做 SSL 终止、做负载均衡、做超时控制，然后把请求转给后面的 cch 或直接转给上游 API。
这两者的关系，用一句话概括：Nginx 是"门卫 + 调度员"，cch 是"翻译官 + 记账员"。Claude Code 客户端只认一个 Base URL，这个 URL 指向 Nginx；Nginx 根据配置把请求转给 cch；cch 再根据你的 Key 和模型映射，把请求转发到 TaoToken 这类统一 API 通道。链路里任何一环配置错了，你看到的报错都不一样。这篇就按这个顺序，把每一层的角色、配置、验证方法和常见报错拆开讲，让你能自己定位问题出在哪一层。
适合谁看？如果你正在用 Claude Code，并且想通过自建网关或统一 API 通道来管理多个项目的 Key、控制用量、或者只是想搞清楚请求到底走了哪条路，这篇就是写给你的。不需要你懂 Nginx 源码，也不需要你读过 Hono 文档，跟着配置和验证步骤走就行。
2. 接入前的准备：TaoToken 统一 Key 通道与 cch 网关的定位
在动手配 Nginx 之前，得先把"请求最终要落到哪里"这件事定下来。Claude Code 本身只是一个客户端，它需要一个兼容 Anthropic API 的端点。你可以直接填官方端点，也可以填一个统一网关的端点。我这边实测下来，用 TaoToken 作为统一 Key/API 通道比较省心，因为它把 Key 管理、模型映射、用量查看都放在一个控制台里，Claude Code 侧只需要改一个 Base URL 和 Key 就行。
TaoToken 的 API 地址是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 Base URL 使用。控制台和 Key 管理在https://taotoken.net/console和https://taotoken.net/api-keys，模型对话测试页在https://taotoken.net/model-chat。如果你打算长期用 Claude Code 做编码或 Agent 任务，可以看一下 Coding Plan 页面https://taotoken.net/coding-plan，它针对长期编码场景做了额度规划。接入文档在https://taotoken.net/doc，Claude Code 相关的说明在https://taotoken.net/claude-code-anthropic。
那 cch 在这里扮演什么角色？如果你只是一个人用 Claude Code，其实可以跳过 cch，直接让 Claude Code 指向 TaoToken 的 API 地址。但如果你团队里有多个开发者、多个项目、多个 Key 需要统一管理，cch 就有价值了：它可以在 TaoToken 的 Key 之上再做一层项目级或用户级的 Key，做用量隔离和审计。Nginx 则是在 cch 前面再加一层，负责 HTTPS、域名、超时和负载均衡。
所以典型的链路是：
Claude Code 客户端 -> Nginx（SSL 终止、反向代理、超时控制） -> cch（Hono 核心逻辑，鉴权、Key 映射、用量记录） -> TaoToken API（统一 Key/API 通道） -> 上游模型如果你不部署 cch，链路就短一层：
Claude Code 客户端 -> Nginx（可选，也可以直连） -> TaoToken API这篇的重点是讲清楚每一层的作用和配置，所以下面会给出 Nginx 反代配置片段、Claude Code 侧 Base URL 设置步骤，以及一次真实请求的验证方法。你根据自己的实际情况决定要不要加 cch 这一层。
有一点要提前说清楚：Nginx 和 cch 都不是"必须"的。Nginx 的价值在于统一入口、HTTPS、超时可控；cch 的价值在于多租户和多 Key 管理。如果你只是本地开发，Claude Code 直接指向https://taotoken.net/api就能跑。但一旦你要把服务暴露给团队或外部，Nginx 这层就值得加上。
3. 可复制配置：Nginx 反代片段与 Claude Code Base URL 设置
这一节是整篇最核心的部分，配置直接给全，你复制后改域名和端口就能用。先给 Nginx 的反代配置，再给 Claude Code 侧的设置，最后给 cch 的 Docker Compose 环境变量片段。
3.1 Nginx 反向代理配置片段
假设你的 cch 服务跑在本机127.0.0.1:3000（Next.js + Hono 默认端口），你想通过https://cch.yourdomain.com对外提供服务。Nginx 配置文件放在/etc/nginx/conf.d/cch.conf：
upstream cch_backend { server 127.0.0.1:3000; keepalive 32; } server { listen 443 ssl http2; server_name cch.yourdomain.com; ssl_certificate /etc/nginx/ssl/cch.yourdomain.com.pem; ssl_certificate_key /etc/nginx/ssl/cch.yourdomain.com.key; # Claude Code 的请求体可能较大，放宽限制 client_max_body_size 20m; # 关键：AI 请求耗时长，读超时要给足 proxy_read_timeout 600s; proxy_send_timeout 600s; proxy_connect_timeout 30s; # 关闭缓冲，让流式响应实时透传 proxy_buffering off; proxy_cache off; location / { proxy_pass http://cch_backend; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Connection ""; } } server { listen 80; server_name cch.yourdomain.com; return 301 https://$host$request_uri; }几个参数值得单独说。proxy_read_timeout 600s是必须调的，默认 60s 对于长上下文或 Agent 任务根本不够，请求还没返回就被 Nginx 掐断，客户端看到的就是 499。proxy_buffering off是为了让 SSE 流式响应不被 Nginx 缓冲，否则 Claude Code 会感觉"卡住不动，然后一次性吐出来"。proxy_http_version 1.1和Connection ""配合 keepalive，减少频繁建连的开销。
如果你不想部署 cch，直接让 Nginx 反代到 TaoToken API，把proxy_pass改成：
proxy_pass https://taotoken.net/api; proxy_ssl_server_name on; proxy_set_header Host taotoken.net;但注意，这种直连方式下 Nginx 只是做了一层转发，鉴权还是靠 Claude Code 侧带的 Key。如果你需要 cch 的 Key 映射和用量记录，还是走 cch 那一层。
3.2 Claude Code 侧 Base URL 设置
Claude Code 通过环境变量读取 API 端点。在~/.claude/settings.json或项目级.claude/settings.json里配置：
{ "env": { "ANTHROPIC_BASE_URL": "https://cch.yourdomain.com", "ANTHROPIC_API_KEY": "sk-your-cch-or-taotoken-key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }如果你跳过 cch，直接指向 TaoToken：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-your-taotoken-key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }这里三个字段必须成对出现：Base URL、Key、Model ID。少任何一个都会报鉴权或模型不存在的错。Model ID 要跟你实际在 TaoToken 控制台里开通的模型一致，写错了会返回model not found。
3.3 cch 的 Docker Compose 环境变量片段
如果你要部署 cch，克隆项目后编辑.env：
git clone https://github.com/ding113/claude-code-hub.git cd claude-code-hub cp .env.example .env.env里必须改的是ADMIN_TOKEN，其他保持默认：
ADMIN_TOKEN=your-secure-token-here DSN=postgres://postgres:postgres@postgres:5432/claude_code_hub REDIS_URL=redis://redis:6379启动：
docker compose up -d docker compose ps docker compose logs -f app看到 app 容器状态是Up且日志没有报错，就说明 cch 起来了。然后在 cch 后台里配置上游为 TaoToken 的 API 地址和 Key，这样 cch 就能把 Claude Code 的请求转发到 TaoToken。
4. 验证请求链路：一次真实请求如何落到 TaoToken
配置写完不算完，得验证请求真的按预期走了。我常用的方法是分三层验证：先验证 Nginx 能通，再验证 cch 能通，最后验证 Claude Code 端到端能通。
4.1 验证 Nginx 层
用 curl 直接打 Nginx 的域名，看是否返回 cch 的响应：
curl -i https://cch.yourdomain.com/health如果 cch 有健康检查接口，应该返回 200。如果没有，可以打一个不存在的路径，看返回的是 cch 的 404 页面还是 Nginx 的 502。返回 502 说明 Nginx 连不上后端，检查upstream里的地址和端口。
4.2 验证 cch 到 TaoToken 的转发
在 cch 后台配置好上游后，用 curl 模拟一次 Anthropic 格式的请求：
curl -X POST https://cch.yourdomain.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: sk-your-cch-key" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 64, "messages": [{"role": "user", "content": "ping"}] }'如果返回里有content字段和正常的文本，说明 cch 成功把请求转发到了 TaoToken 并拿到了响应。如果返回 401，检查 cch 后台里配置的 TaoToken Key 是否正确；如果返回model not found，检查 Model ID 是否在 TaoToken 控制台里开通。
4.3 验证 Claude Code 端到端
最后在终端里跑 Claude Code：
claude -p "用一句话说明当前请求走的是哪个端点"如果 Claude Code 正常返回内容，说明整条链路通了。这时候你可以去 TaoToken 控制台的用量页面看，应该能看到这次请求的记录。如果看不到，说明请求没落到 TaoToken，可能被 cch 拦截了或者 Nginx 转到了别的地方。
我实测下来，最容易出问题的是 Model ID 和超时设置。Model ID 写错会直接报错，超时设置太短会在长任务里随机失败。把这两个盯住，链路基本就稳了。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
链路一长，报错就多。下面这几个是我踩过的坑，按报错信息对照排查。
5.1 401 Unauthorized
这个最常见，原因有三个：Key 没带、Key 错了、Key 没权限。先检查 Claude Code 的settings.json里ANTHROPIC_API_KEY是否填了，再检查这个 Key 在 cch 或 TaoToken 后台是否有效。如果用了 cch，还要检查 cch 后台里配置的上游 Key 是否正确。注意，Claude Code 侧的 Key 和 cch 上游的 Key 是两回事，前者用于 cch 鉴权，后者用于 cch 向 TaoToken 鉴权。
5.2 local proxy failed
这个报错通常出现在 Claude Code 启动时，说明它连不上你配置的 Base URL。检查ANTHROPIC_BASE_URL是否写对，域名是否能解析，Nginx 是否在跑。如果是本地开发，确认端口没被占用。还有一个容易忽略的点：如果你的 Base URL 带了路径（比如https://cch.yourdomain.com/api），而 Nginx 的location没匹配上，也会报这个错。
5.3 reading 'choices'
这个报错看起来像 OpenAI 格式的残留，实际上是因为请求发到了不兼容 Anthropic 格式的端点。Claude Code 发的是 Anthropic Messages API 格式，如果你的 Base URL 指向了一个只支持 OpenAI Chat Completions 格式的服务，就会在解析响应时报reading 'choices'。解决办法是确认你的端点支持 Anthropic 格式。TaoToken 的/api端点是兼容 Anthropic 格式的，cch 也是按 Anthropic 格式转发的，所以走这两条路不会出这个问题。
5.4 OAuth 相关报错
如果你在 Claude Code 里用了 OAuth 登录而不是 API Key，可能会遇到 token 过期或刷新失败。这种情况下，检查你的 OAuth 配置是否指向了正确的端点。如果你用的是统一 Key 通道，建议直接用 API Key 模式，避免 OAuth 的额外复杂度。在settings.json里确保ANTHROPIC_API_KEY有值，Claude Code 会优先用 Key 而不是 OAuth。
5.5 499 和超时
499 是 Nginx 特有的状态码，表示客户端在服务端返回前断开了连接。在 Claude Code 场景里，这通常是因为proxy_read_timeout太短，Nginx 等不及后端返回就掐断了，客户端收到断开后重试或报错。把proxy_read_timeout和proxy_send_timeout都调到 600s 以上，基本能解决。如果调了还不行，检查 cch 或 TaoToken 侧是否有更短的超时限制。
排查的顺序建议是：先看 Claude Code 的报错，确定是哪一层的问题；再用 curl 逐层验证；最后对照上面的报错表定位。不要一上来就改配置，先确认问题出在哪一层，改起来才有方向。
6. 把链路固定下来：Claude Code 长期接入的配置建议
链路调通之后，下一步是让它稳定跑下去。我自己的做法是把配置分成三层管理：Nginx 层管域名和超时，cch 层管 Key 和用量，Claude Code 层只管 Base URL 和 Model ID。这样任何一层出问题，改动范围都可控。
如果你团队里有多个人用 Claude Code，建议在 cch 里给每个人分配独立的 Key，这样用量和审计都能分开。cch 的 PostgreSQL 会记录每个 Key 的请求量，Redis 做限流，避免某个人跑飞了影响其他人。Nginx 层可以再加一层limit_req做粗粒度限流，但精细限流交给 cch 更合适。
对于长期编码和 Agent 任务，TaoToken 的 Coding Plan 页面有专门的额度规划，比按量付费更适合高频使用。接入文档在https://taotoken.net/doc，Claude Code 相关的说明在https://taotoken.net/claude-code-anthropic，遇到配置问题可以先翻文档。Key 管理在https://taotoken.net/api-keys，模型对话测试在https://taotoken.net/model-chat，这两个页面在调试阶段用得最多。
最后说一个实用技巧：在 Nginx 配置里加一行add_header X-Upstream $upstream_addr;，这样响应头里会带上实际转发的后端地址。调试时用curl -i一看就知道请求落到了哪个 upstream，比翻日志快得多。链路这东西，配一次调通之后，后面就是复制粘贴的事，关键是第一次要把每一层的作用搞清楚。
