Claude Code 接入配置

把 Claude Code 指向 HybridInference 网关，而不是 Anthropic，让它使用该部署签发的模型和 API key。

配置

编辑 ~/.claude/settings.json（Windows 上是 %USERPROFILE%\.claude\settings.json）：

{
  "model": "<gateway-model-id>",
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<your-api-key>"
  }
}

/anthropic 是网关的 Anthropic 兼容接口。Claude Code 把 Messages API 请求发到 /anthropic/v1/messages，把 token 计数发到 /anthropic/v1/messages/count_tokens；两者都注册在 apps/backend/serving/servers/routers/anthropic_messages.py 里，该文件同时把相同的处理器挂在裸的 /v1/messages 路径上，供没有配置 /anthropic 前缀的客户端使用。

顶层的 model 设置是可选的。它决定初始使用的模型，之后也可以用 /model 换。

这件事在客户端一侧的所有细节——某个 Claude Code 版本读哪些变量、它的请求超时是多少、只改 settings.json 够不够——都归 Claude Code 管，不归网关管。请参阅 Anthropic 当前的 LLM 网关、模型配置和安装文档。

模型家族与别名

Claude Code 发送的是 claude-sonnet-4-6、claude-opus-4-7 这类 Anthropic 家族 ID，而不是网关的模型 id。这两个就在下文那张固定兼容表里，会被改写成 claude-sonnet-4.6 和 claude-opus-4.7——所以一个部署要注册的是改写之后的那个 id，而不是 Claude Code 发来的那个。把 claude-sonnet-4-6 注册成模型 id 或别名，只会拿到 404。

表里没有的 id 会原样通过，按发来的样子去注册表里查；模型条目自己的 aliases: 列表就是为这种情况准备的。加载哪份注册表，取自 MODELS_CONFIG_PATH 指向的文件，否则取生效的 distribution manifest 里的 paths.models 条目，再否则取随仓库分发的 config/examples/models.openrouter.yaml。没有任何机制保证某个家族 ID 一定在某个部署上注册过，所以先查 GET /v1/models。

当用户选用长上下文变体时，Claude Code 还会在模型 id 后面追加一个方括号形式的上下文窗口标记（claude-sonnet-4-6[1m]）。网关在做别名和注册表查找之前会先剥掉这个标记，所以不需要额外注册带方括号的形式。

要显式映射 Claude Code 的家族选择器，把下面这些受支持的变量按需加进同一个 env 块：

{
  "ANTHROPIC_DEFAULT_OPUS_MODEL": "<gateway-model-id>",
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "<gateway-model-id>",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<fast-gateway-model-id>"
}

Haiku 这一项映射留给 Claude Code 体量较小的后台调用。网关不会读取这些变量中的任何一个——Claude Code 在本地解析它们，只把解析出的 id 发过来——所以上面链接的 Anthropic 模型配置文档才是「你这个版本支持哪些变量」的权威来源。

Anthropic 的 ID——既包括当前的家族选择符（claude-sonnet-4-6、claude-opus-4-7），也包括旧的和带日期的那些（claude-3-5-sonnet-latest、claude-sonnet-4-5、claude-3-opus-20240229 等）——都会先经过 apps/backend/serving/adapters/anthropic_aliases.py 里一张固定的兼容表，被改写成本项目的规范 id（claude-sonnet-4.6、claude-opus-4.6、claude-opus-4.7）。无法识别的 id 原样通过。两种情况下，结果都会再拿去注册表里查，所以一个部署需要注册的是改写后的 id——作为模型 id，或者写进该模型的 aliases: 列表。返回 404 说明这个部署对最终的 id 没有任何路由。

使用与验证

cd your-project
claude

用 /status 确认当前生效的模型和网关配置，用 /model 换模型。只要选中的网关模型支持所需的工具调用，工具使用、文件编辑、搜索等本地 agent 功能都照常可用。

这些设置只覆盖模型推理，而且只对这台机器上的 Claude Code 生效。Anthropic 托管的那些产品功能不属于网关实现的 Messages API；其他地方的 Claude 会话——网页版、别的客户端——都不会读这份本地配置。

故障排查

报错

原因

处理

401 认证错误

API key 不对

检查 ~/.claude/settings.json 里的 ANTHROPIC_AUTH_TOKEN

404 找不到模型

网关对最终的模型 id 没有注册任何路由，或者你这把 key 的角色看不到它

查 GET /v1/models（它列出这把 key 能访问的模型），再更新 model 或对应的 ANTHROPIC_DEFAULT_*_MODEL

429 被限流

请求过多

等一会儿再重试

503 没有可用的 provider

模型解析出来了，但它的路由目前没有一条能提供服务

重试，或换一个模型

504/超时

网关或上游的某次请求超出了截止时间

先查网关健康状况，确有必要时再调整超时

卸载

从 ~/.claude/settings.json 中删掉网关专用的 model 值，以及 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_DEFAULT_*_MODEL 这几个键。文件里与此无关的其他 Claude Code 设置和环境变量要保留。之后 Claude Code 就会恢复直连 Anthropic。