Claude Code接入AI网关的避坑指南

dev.to · AI#Claude Code#AI网关#工程踩坑

Editor brief · 编辑速览

实际踩坑经验总结：Claude Code对接AI网关时，4个环境变量中2个未文档化导致接入失败，附稳定配置方案。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

如果你每天都用 Claude Code，总有一天会想把它走网关：比如当 api.anthropic.com 返回 529 时做故障转移，或者想把 Claude/GPT/Gemini 合并到一张账单，又或者只是想有一份能真正 grep 的使用日志。理论上设一个环境变量就够了。实际上需要四个，其中两个在任何文档里都找不到。以下是我们踩过的坑以及稳定运行了两个月的配置。

为何"OpenAI 兼容"还不够

大多数网关都宣称"支持 Claude"，因为它们代理了 /v1/chat/completions。但 Claude Code 不走那个接口。它调用的是 Anthropic Messages API（POST /v1/messages，带 x-api-key 和 anthropic-version 请求头），而 tool-use payload——tool_use / tool_result content blocks、cache_control 标记、流式事件类型——与 OpenAI function calling 没有一对一的对应关系。翻译层能处理简单的单轮对话，却在多轮 agentic 循环里悄悄丢弃了某些字段。症状包括：工具"运行"了但返回空结果、prompt caching 被静默禁用、第三轮调用时收到 400 错误。

经验法则：把 Claude Code 指向一个网关之前，先确认它暴露了原生的 /v1/messages 端点。如果文档只提 chat completions，免谈。

四个变量

# ~/.zshrc 或 ~/.bashrc
export ANTHROPIC_BASE_URL="https://apiflux.ai"          # 你的网关；遇到路径错误可以试试 ".../v1"
export ANTHROPIC_API_KEY="sk-your-gateway-key"          # 网关的 KEY，不是 Anthropic 的 key
export DISABLE_INTERLEAVED_THINKING=1
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

前两个变量一看就懂。后两个让我们折腾了一个下午。

Claude Code 默认会发送 anthropic-beta 请求头——包括 interleaved thinking，以及当前版本开启的各种实验性 beta。部分网关背后的上游（尤其是 Bedrock 和 Vertex）并不接受所有 beta 标记，而失败表现也很不友好：要么收到空的 assistant 回复，要么得到一个通用的 400。设置这两个变量后，beta 请求头被去掉，一切变得确定性。代价是失去了 interleaved thinking，但对于写代码这个场景，我们没觉得可惜。

$env:ANTHROPIC_BASE_URL="https://apiflux.ai"
$env:ANTHROPIC_API_KEY="YOUR_GATEWAY_KEY"
$env:DISABLE_INTERLEAVED_THINKING="1"
$env:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS="1"

用 claude doctor 验证一下，然后发一个便宜的请求，检查它是否以相同的 API key 出现在网关日志里。如果请求成功了但日志里没有，那就是你以为自己用的 key 和实际用的不是同一个。

故障转移实际是怎样的

费这么大周折的原因：一个模型 ID 可以背后对接多个上游通道。在我们这边，claude-opus-5 会依次尝试 Anthropic → Amazon Bedrock → Vertex AI；如果主通道返回 529 或过载，路由器自动重试下一个通道，Claude Code 完全感知不到。我们先用 LiteLLM 自己搭过这套：轮转三个 provider 的 key 和配额，运维成本超出了我们对一个副项目的预期。

两个让网关调试更轻松的习惯

保留 X-Request-Id 响应头。它在网关日志里是同一个 ID——提交工单时贴这个 ID 而不是截图。用一个非生产环境的 key 来做评估。零数据保留的网关仍然会记录元数据（模型、token、状态）；你肯定不想让这份日志流到别人手里。

同一套 key，其他 CLI 也免费

网关配好之后，其他编程 CLI 就顺带免费得到了。

Codex CLI（~/.codex/config.toml）——走 OpenAI 协议，所以最简单：

model_provider = "apiflux"
model = "gpt-5"

[model_providers.apiflux]
name = "ApiFlux"
base_url = "https://apiflux.ai/v1"
env_key = "APIFLUX_API_KEY"

OpenCode——添加一个自定义 OpenAI 兼容 provider，指向 https://apiflux.ai/v1，然后从网关的模型列表里选一个模型 ID。

三套工具，一套 key，一张发票。

价格，有人肯定会问

每 1M token，2026 年 8 月，网关价格与官方列表对比：

如果你已经让 Claude Code 走其他网关了，我很想了解你是否也需要那两个禁用 beta 的变量，还是说那只是 Bedrock/Vertex 回源才有的问题。评论区开放。

Jason Zhu——ApiFlux 作者。@ApiFluxAI on X。