返回指南
集成·2026年7月26日·更新于 2026年10月10日·阅读约 12 分钟

Claude Code Router——将 Claude Code 路由到任何模型,或完全跳过路由器

大多数使用 claude-code-router 的人只是想让 Claude Code 在更便宜的地方运行——这只需更换 base URL,而不是安装路由器。以下介绍路由器何时真正值得使用、config.json 已不再生效后现在如何配置,以及网关会破坏哪些功能的诚实清单。

最后审核于 。

大多数搜索Claude Code Router的人,其实想要的是两种不同的事情之一:让 Claude Code 在多个模型提供商之间路由,或者只是在比 Anthropic 标价更便宜的地方运行 Claude Code。只有第一种情况需要路由器。Claude Code 原生读取 ANTHROPIC_BASE_URL,因此第二种情况只需设置三个环境变量,完全不需要额外软件。

本指南涵盖两条路径,包括精确的变量名称、会导致静默 401 的凭据陷阱,以及任何网关后会停止工作的功能的真实清单。如果你最近读过另一篇 CCR 介绍,请先跳到选项 B:那些文章让你编辑的 config.json 已经不是路由器读取的配置。

你实际需要哪一个?

你的目标使用
以更低成本在 Claude Code 中运行 Claude切换基础 URL — 无需安装
每项任务使用不同模型(规划 / 编码 / 后台)二选一:ANTHROPIC_DEFAULT_* 变量,或路由器
在一个 Claude Code 后面混用多个提供商claude-code-router
使用非 Claude 模型驱动 Claude Codeclaude-code-router
逐请求日志:提供商、模型、延迟、令牌数、费用claude-code-router
将子代理发送到不同于主循环的模型claude-code-router — 层级变量无法做到这一点

路由器是一个本地服务:需要额外运行、配置并保持最新的进程;截至 2026 年,它还是一个带有独立 UI 的桌面应用,而不是供你编辑的文件。只有在你确实需要多提供商路由、逐请求计费或子代理级别的模型选择时,这项成本才值得承担。如果一个基础 URL 就能满足需求,它就不值得。

选项 A — 替换基础 URL(无需安装)

Kunavo 在 /v1/messages 提供原生 Anthropic Messages API,这正是 Claude Code 调用的端点。将 Claude Code 指向该端点:

~/.zshrc
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL 仅填写源站地址——Claude Code 会自行追加 /v1/messages,因此不要包含路径。请保留模型配置行:Claude Code 的内置默认模型及其 opus 别名都会解析为最新的 Opus;如果 Kunavo 尚未提供该模型,首次请求就会返回 404。sonnet 别名会请求 Sonnet 5.5,而 Kunavo 不提供该模型,因此如果缺少 ANTHROPIC_DEFAULT_SONNET_MODEL 这一行,/model sonnet、opusplan 的执行阶段以及任何设置为 model: sonnet 的子代理都会返回 404。opus 别名固定指向 Opus 5.5(claude-opus-5-5),这需要 Claude Code v2.1.280 或更高版本——如果你的版本较旧,请运行 claude update。注册并充值 $10 后,即可从控制台获取密钥;密钥仅显示一次。

使用哪个凭据变量——以及为什么这很重要

Claude Code 会将两个凭据变量发送到不同的 HTTP 标头中;如果密钥放在服务器不读取的标头中,请求会失败并返回 401:

变量发送的标头在 Kunavo 上
ANTHROPIC_AUTH_TOKENAuthorization: Bearer推荐 — 到处可用
ANTHROPIC_API_KEYx-api-key一次性批准后,可用于聊天和模型发现

建议使用 ANTHROPIC_AUTH_TOKEN,理由很具体:ANTHROPIC_API_KEY 需要在交互式会话中进行一次性批准;如果你曾拒绝过某个密钥,之后它会被忽略且不会再次提示——变量明明已设置,却明显未被使用,这是一个容易困惑的失败原因。Kunavo 不决定模型发现使用哪个变量。Claude Code 的网关模型发现功能在设置 仅 ANTHROPIC_AUTH_TOKEN 时发送 bearer 令牌,否则回退到 x-api-key;而 Kunavo 的 /v1/models 端点会从任一标头读取密钥。

让配置持久生效

Shell 导出变量只对当前终端及从该终端启动的任何程序生效——从 Dock 打开的编辑器看不到它们,后台代理也看不到。将这些值放入设置文件,以覆盖所有场景:

~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

所有项目都使用 ~/.claude/settings.json。绝不要把密钥放入项目的 .claude/settings.json 中——该文件会被提交。

信任之前先验证

先直接测试端点,这样失败时可以定位到配置,而不是 Claude Code:

verify.sh
curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

然后从同一个 Shell 启动 claude 并运行 /status。显示 Anthropic base URL 和 api.kunavo.com 的一行,以及标明变量的 Auth token 一行,就能确认两部分都已生效。

设置自定义模型——明确选择 slug

Kunavo 通过精确匹配解析模型 slug,不会为带日期后缀的名称创建别名,因此 claude-sonnet-4-5-20250929 会返回 404,而 claude-sonnet-5 可以成功。始终设置 ANTHROPIC_MODEL,不要依赖内置默认值:

角色标识符(slug)每 1M 个令牌的输入 / 输出
日常编码(默认)claude-sonnet-5$1.40 / $7.00
上一代claude-sonnet-4-6$2.10 / $10.50
最复杂的重构、计划模式claude-opus-5-5$2.80 / $14.00
后台任务、快速请求claude-haiku-4-5$0.70 / $3.50

别名变量无需任何路由器即可按任务路由:ANTHROPIC_DEFAULT_OPUS_MODEL对应 opus别名和计划模式,ANTHROPIC_DEFAULT_SONNET_MODEL对应 sonnet以及 opusplan的执行阶段,ANTHROPIC_DEFAULT_HAIKU_MODEL对应 haiku和 Claude Code 的后台工作,包括摘要和标题。通过 Kunavo 使用时,后两项必须设置,否则它们会请求 Kunavo 不提供的模型 ID(Sonnet 5.5,以及 v2.1.293 起的 Haiku 5.5):将 Haiku 项设为 claude-haiku-4-5,后台工作也就不会占用主模型。(ANTHROPIC_SMALL_FAST_MODEL是同一设置已弃用的写法。)

可选:在选择器中显示所有模型

设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1(Claude Code v2.1.129+)后,Claude Code 会在启动时查询 GET /v1/models,并将发现的内容添加到标记为 来自网关 的 /model 选择器中。Kunavo 提供该端点,因此所有已启用的 Claude 模型都会显示出来,/model 也会变成实时菜单,而不是需要手动维护的列表。两种凭据变量都可用于此功能——见上文。

选项 B — claude-code-router,如今实际的工作方式

从这里开始,因为几乎所有关于 CCR 的资料描述的都是已经不存在的版本。路由器过去是一个 JSON 文件和一个 ccr code 命令。现在它是一个本地控制平面,包含桌面应用、管理 UI、请求日志和模型网关;而教程中都会展示的 config.json 已经不再配置它。

CCR 将运行时配置保存在 ~/.claude-code-router/config.sqlite(Windows 上为 %APPDATA%\claude-code-router\config.sqlite)。当尚不存在 SQLite 配置时,它会将旧版 config.json 作为迁移来源读取一次。首次运行后,编辑该文件不会影响正在运行的配置——既没有错误,也没有警告。你精心粘贴的 Providers 代码块根本不是配置。

这也包括 2026-09-06 之前的本页面:这里曾经放置的 JSON 代码片段是错误的,而且是那种会浪费整个下午的错误,因为没有任何提示告诉你它被忽略了。现在配置通过 UI 完成(或者用于备份,选择 Settings → Export data——CCR 运行时不要复制正在使用的 SQLite 文件)。

安装并启动

CCR 提供两种方式:GitHub Releases 中的桌面应用(托盘、自动更新、桌面集成)和用于无头或受监管部署的 npm CLI。两者共享同一个配置目录。

安装并启动
# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

添加 Kunavo 只需创建一个提供商条目——Providers → Add provider,预设为 Other / custom API endpoint,端点为 https://api.kunavo.com,填入你的 sk-kn- 密钥——以及一个 Agent Config → Add profile → Claude Code 配置文件。包含Check Connection和模型发现的逐字段版本,见 Claude Code Router 集成页面。本节其余内容涵盖该页面未涉及的部分:凭据、成本和故障模式。

三个凭据,以及 401 分别对应哪个凭据

这是一个正常配置看起来像坏掉的最常见原因。CCR 有三个独立的密钥,它们分别验证三个不同的跳转:

凭据验证对象发送位置
你的 Kunavo 密钥(sk-kn-…)CCR → KunavoProviders → 提供商的 API key 字段
CCR 客户端密钥任何客户端 → CCR 网关在 API Keys 页面创建;没有它,网关会拒绝模型请求
管理令牌(ccr_web_token)你 → CCR UI 和 RPC在 URL 中由 ccr ui 打印——将其视为密码

端口配对也容易让人出错:管理服务默认为 127.0.0.1:3458,模型网关默认为 127.0.0.1:3456。将基础 URL 指向 3458 会到达 UI,而不是网关。(Docker 会有意将两者置于同一个 Nginx 端点之后,因此 Docker 指南看起来不同。)UI 可访问并不代表网关正常工作:在网关地址检查 /health,并确认 Server 显示 Running。

逐层映射才是重点

Claude Code 不会请求一个模型,而是请求一个层级——主循环需要 Sonnet 或 Opus,后台工作(子代理、搜索、摘要、对话标题)需要速度快的小模型。Agent Config 中的 Claude Code 配置文件将它们显示为独立字段:默认的 Model,以及可选的 Fable、Opus、Sonnet 和 Haiku 覆盖项,每项都接受一个 Provider/model 值。留空某个层级后,Claude Code 会自行选择。

层级映射到每 1M 个令牌的输入 / 输出实际运行的内容
OpusKunavo/claude-opus-5-5/ $14.00计划模式、复杂重构
Sonnet(默认)Kunavo/claude-sonnet-5$1.40 / $7.00主代理循环——你大部分令牌的消耗所在
Sonnet,上一代Kunavo/claude-sonnet-4-6$2.10 / $10.50相同循环,价格比 Sonnet 5 高 50%
HaikuKunavo/claude-haiku-4-5$0.70 / $3.50子代理、文件分类、标题、摘要

复制别人的层级映射前先阅读这张表,因为最明显的拆分就是第一个杠杆:claude-sonnet-5 在 Kunavo 上比 claude-opus-5-5 便宜 50%($1.40 / $7.00 对比 $2.80 / )。第二个杠杆是 Haiku 层级:按 $0.70 / $3.50 计费时,它比 Sonnet 5 便宜 2×,而且还承载着你看不见的用量——每个子代理、每次文件分类处理、每个生成的标题。claude-sonnet-4-6 已不再是便宜的 Sonnet:按 $2.10 / $10.50 计费时,它比 Sonnet 5 贵 50%,这就是上面的代码片段设置 ANTHROPIC_MODEL=claude-sonnet-5 的原因。

子代理路由——层级映射无法做到的事情

层级覆盖会将所有子代理固定到一个模型。CCR 可以做得更细:当 Claude Code 请求匹配内置路由时,它会将可用模型列表注入 Agent / Task 工具描述中;Claude Code 则会在每个生成的代理提示前加上一个标记,说明它需要的模型:

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCR 会移除该标记并据此路由这一个请求,因此搜索子代理可以运行在 Haiku 上,而审查子代理运行在 Opus 上;这是按任务选择,而不是固定绑定。这个开关很容易被忽略:除非 Models 页面中至少有一个模型填写了 Description,否则该机制处于关闭状态。没有描述时,CCR 不会注入任何内容,所有子代理都会悄然回退到配置文件默认模型。请将描述写成任务适配说明——Haiku 可写“代码搜索、文件分类、低成本并行子代理”,Opus 可写“架构分析、高风险审查”。生效后,请求日志会将 builtin:claude-code-subagent 显示为路由原因。

协议选择,以及它会在缓存方面带来的成本

CCR 会探测端点并选择通信协议。提供裸源站 https://api.kunavo.com 时,它使用 Anthropic Messages;提供 https://api.kunavo.com/v1 时,它使用 OpenAI 兼容格式。同一个密钥上的两个接口都处于可用状态,你可以在 Advanced settings 中覆盖自动检测。

优先使用 Anthropic Messages 形式。它会在通信中保留 cache_control,因此提示缓存可以到达模型,缓存输入按输入费率的 10% 计费(工作原理)——对于每一步都重新发送稳定前缀的代理循环,这是可获得的最大单项节省。需要坦诚说明的是,路径中的路由器仍会编辑请求:CCR 会移除 Claude Code 注入的计费标头系统消息,并在启用子代理路由时将模型列表添加到工具描述中。两者都位于你的缓存断点之前,因此每次内容变化都会造成一次缓存未命中,而新的前缀随后会升温。之后它会保持稳定——但这确实是选项 A 的缓存效果略好于选项 B 的一个原因,此外选项 A 也更易于运行。

不过,在 OpenAI 兼容形式下,提示缓存同样能到达模型。对于较长的提示,Kunavo 会在该路由上自行设置缓存断点:设在系统提示、工具定义,以及对话中已有助手回合时的最后一条消息上。随消息或工具定义一起传来的 cache_control 会被保留。

回退:重试还是故障转移

值得在需要之前设置 Routing 页面的 Default on failure。Retry 会在 408、409、429 和 5xx 时向同一模型重新发送请求,遵循 Retry-After;否则会从 1s 开始指数退避,最高 30s。Fallback targets 会遍历按顺序排列的备用模型列表,并在出现任何 4xx 或 5xx 时触发,因为模型未找到或提供商拒绝可能只影响当前目标。单独的规则可以覆盖全局设置。发生回退时,响应会携带 x-ccr-fallback-attempts 和 x-ccr-fallback-model,便于你事后判断。

验证它确实位于请求路径中

从配置文件启动 Claude Code,发送一条消息,然后在 CCR 中打开 Request logs。该行会显示 request model(Claude Code 请求的模型)、resolved provider 和 resolved model(请求发送到哪里)——这三个信息共同构成证明。在 CLI 中,/model 会列出 CCR 暴露的模型。如果 Claude Code 有回复但没有日志行,说明你是自行启动 Claude Code,而不是通过 CCR 启动;此时配置文件的范围是 Only opened from CCR。

一次编码会话的成本

Claude Code 会在每一步重新发送系统提示、对话和最新文件上下文,因此每令牌费率会迅速累积。在 claude-sonnet-5 上按 Kunavo 费率计算:

单位Token(输入 / 输出)KunavoAnthropic 标价
一次代理式步骤25,000 / 1,200$0.043$0.062
一个 20 步任务约 500k / 约 24k~$0.87~$1.24
高强度的一天(5 个任务)—~$4.34~$6.20

在提示缓存之前,这大约相当于主线模型优惠 30%。完整费率见 Claude API 定价指南,成本计算器可使用你自己的令牌数量。

仍然有效的功能——以及无效的功能

将 Claude Code 指向任何网关都会改变一些行为。在提交之前了解以下简短列表很有价值:

功能通过网关
编码、工具、子代理、MCP、钩子不受影响
提示缓存可用——原生 Messages API 路由
你的 claude.ai 订阅不使用;改为按令牌向密钥计费
远程控制不可用——需要 claude.ai 身份
语音听写不可用——原因相同
/context 令牌数量在本地估算(见下文)

关于最后一行:令牌计数是 Anthropic 自己的网关规范标记为可选的唯一端点;当该端点不存在时,Claude Code 会在本地估算上下文用量。Kunavo 目前不提供 /v1/messages/count_tokens,因此你的 /context 数值是估算值,而不是精确计数。除这个数字外,没有任何功能降级——自动压缩和会话本身不受影响。

故障排除

基础 URL 路径

症状原因和修复方法
每个请求中的 401密钥位于服务器不读取的标头中。在 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 之间切换,然后重试上面的 curl。
Claude Code 要求你登录,但 curl 可以正常工作可访问的基础 URL 并不是凭据。请在首次运行设置前能读取的位置设置 ANTHROPIC_AUTH_TOKEN:Shell 导出变量或 ~/.claude/settings.json。
ANTHROPIC_API_KEY 已设置但被忽略,且没有提示之前拒绝过一次性批准。在 /config → Use custom API key 下启用它,或切换到 ANTHROPIC_AUTH_TOKEN。
404 命名模型精确 slug 匹配——删除任何日期后缀,并使用上表中的 slug。
400 命名 thinking 或 adaptiveClaude Code 会在 4.6+ 模型上请求自适应推理。在 Opus 4.6 和 Sonnet 4.6 上,CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 可解决此问题。
/fast 表示快速模式已禁用可用性检查会直接调用 api.anthropic.com,不会遵循你的基础 URL。请设置 CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1。
选择器中缺少模型启用 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1,或通过 ANTHROPIC_DEFAULT_*_MODEL 变量为模型命名。

……以及路由器位于请求路径中时

症状原因和修复方法
修改 config.json 没有任何影响不能这样做。运行时配置位于 config.sqlite;JSON 文件只是一次性迁移来源。请在 UI 中进行更改。
找不到 ccr code不在当前命令集中。按名称启动配置文件:ccr "My Profile";或者从桌面应用启动 ccr-app "My Profile"。
安装后找不到 ccrnpm 的全局 bin 不在 PATH 中,或者 Node 版本低于 22。检查 npm prefix -g 和 node --version。
UI 可以加载,但模型请求失败管理服务和网关是不同端口上的不同服务。确认 Server 显示 Running,并将客户端指向 :3456,而不是 :3458。
网关返回 401,但提供商检查通过没有 CCR 客户端密钥。在 API Keys 页面创建一个——它与您的 sk-kn- 密钥是不同的凭据。
Claude Code 正在运行,但 Request logs 中没有任何内容你直接启动了 Claude Code,而配置文件范围是 Only opened from CCR。请从 CCR 启动,或将范围切换为 System default。
每个子代理都使用默认模型子代理路由受 Models 页面中的 Description 字段控制。没有描述时,CCR 不会注入路由指令,也不会写入标记。
/model 未列出任何 CCR 模型没有配置提供商和模型,或者配置文件已禁用。请先在提供商上运行 Check Connection。

API 本身的逐错误修复方法,见无效 API 密钥和速率限制故障排除页面。

常见问题

我需要 claude-code-router 才能通过其他 API 使用 Claude Code 吗?

不需要。Claude Code 原生读取 ANTHROPIC_BASE_URL,因此只要将其指向任何提供 Anthropic Messages API 的端点,就无需额外软件——设置三个环境变量即可。以下情况值得运行 CCR:你希望在多个提供商之间路由、记录每次请求的提供商、模型、延迟、token 和成本,或让不同子代理使用不同模型,而不是所有子代理使用同一个模型。如果你的目标只是通过更便宜的端点运行 Claude,那么切换基础 URL 是更小巧、更可靠的设置:无需额外服务,提示缓存也会直接透传。

为什么编辑 claude-code-router 的 config.json 没有任何作用?

因为它已经不是 CCR 读取的配置文件。当前构建将运行时配置保存在 ~/.claude-code-router/config.sqlite 中(Windows 上为 %APPDATA%\claude-code-router\config.sqlite),并且只有在尚不存在 SQLite 配置时,才会将旧版 config.json 读取一次,作为迁移来源。首次运行后,JSON 文件会被静默忽略,不会报错,因此手动编辑的 Providers 数组或 Router 块根本不会生效。请改用 CCR 桌面端 UI 进行修改;如果需要文件级备份,请使用 Settings → Export data。大多数第三方 CCR 教程仍然介绍 JSON 文件。

现在如何通过 claude-code-router 启动 Claude Code?

使用配置文件名称,而不是 ccr code。依次进入 Agent Config → Add profile → Claude Code 创建配置文件,选择模型并保存,然后启动:使用 npm CLI 时运行 ccr "Claude Code - Work",使用桌面应用时运行 ccr-app "Claude Code - Work";桌面应用还会为每张配置文件卡片提供一个用于 CLI 的终端按钮和一个用于 Claude 应用的播放按钮。当前 CLI 命令集为 start、ui、stop、serve 和 web,后面可接配置文件名称或 ID;没有 code 子命令。在双短横线后追加代理自身的标志,例如:ccr "Claude Code - Work" cli -- --model sonnet。

Claude Code 可以使用自定义模型吗?

从机制上说可以:ANTHROPIC_MODEL 接受 ANTHROPIC_BASE_URL 背后的端点所提供的任何 slug,而 claude-code-router 还可以在其上实现跨提供商的按任务路由。诚实的限制是,Anthropic 自己的网关文档说明,任何网关都不支持将 Claude Code 路由到非 Claude 模型,因此非 Claude 模型上的工具调用和代理行为属于未经测试的范围,而不是受支持的配置。在 Kunavo 上,受支持的路径是通过更便宜的端点使用 Claude slug;目录中的其他模型应通过 OpenAI 兼容 API 访问,而不是通过 Claude Code 访问。精确 slug 规则和模型表位于上面的设置自定义模型部分,完整目录位于模型页面。

Claude Code 需要什么基础 URL 和环境变量?

将 ANTHROPIC_BASE_URL 设为 https://api.kunavo.com(Claude Code 会自行在后面追加 /v1/messages),将 ANTHROPIC_AUTH_TOKEN 设为你的 sk-kn- 密钥,并将 ANTHROPIC_MODEL 设为准确的模型标识,例如 claude-sonnet-5。别名也要固定指定:设置 ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5,供 /model opus 和计划模式使用(Opus 5.5 需要 Claude Code v2.1.280 或更高版本——运行 claude update);设置 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5,否则 sonnet 别名会请求 Kunavo 不提供的 Sonnet 5.5;设置 ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5,否则 haiku 别名也会请求 Kunavo 不提供的模型 ID(v2.1.293 起为 Haiku 5.5)。这一行还会让后台任务按最便宜的费率计费。

我应该使用 ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY?

使用 ANTHROPIC_AUTH_TOKEN。它会作为 Authorization: Bearer 标头发送并立即生效;而 ANTHROPIC_API_KEY 会作为 x-api-key 发送,需要一次性交互式批准——如果你曾经拒绝过某个密钥,之后它会被静默忽略。在 Kunavo 上,这项批准造成了全部差异:Claude Code 网关的 /v1/messages 和 /v1/models 端点背后的模型发现,都可以从任一标头读取密钥。

为什么 Claude Code 提示模型不可用?

Kunavo 会严格匹配模型 slug,不会为带日期后缀的名称创建别名,因此请求 claude-sonnet-4-5-20250929 会返回 404,而 claude-sonnet-5 可以成功。请将 ANTHROPIC_MODEL 设置为目录中的准确 slug,不要依赖 Claude Code 的内置默认值。另一个常见原因是 sonnet 别名:未固定时,它会请求 Sonnet 5.5,而 Kunavo 不提供该模型,因此在设置 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5 之前,/model sonnet、opusplan 的执行阶段以及任何设置为 model: sonnet 的子代理都会返回 404。

Claude Code 通过网关运行时,哪些功能会停止工作?

按设计有三项。Remote Control 和语音听写都需要 claude.ai 身份,在设置网关凭据后不可用。/fast 可用性检查会直接调用 api.anthropic.com,而不会遵循你的基础 URL,因此在普通请求正常工作时,它仍可能报告快速模式不可用;设置 CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1 可恢复该模式。编码、工具、子代理、MCP 和提示缓存不受影响。

我可以改用 Claude Pro 或 Max 订阅吗?

不可以。聊天订阅不包含 API 访问权限,设置网关凭据后会有意停用你的 claude.ai 登录——订阅限制不再适用,使用量会改为按 token 计费到该密钥。完整说明请参阅Claude Code 是否免费。

这适用于 VS Code 扩展吗?

适用,但该扩展会在启动前检查凭据,因此请将凭据设置在 VS Code 自己的 claudeCode.environmentVariables 设置中,而不要只设置在 ~/.claude/settings.json 中。

Cursor、Kilo Code 或 Cline 呢?

它们使用 OpenAI 兼容的提供商字段,而不是环境变量——基础 URL 为 https://api.kunavo.com/v1,密钥相同。设置方法和按工具进行的模型路由,请参阅 Cline、Roo Code 和 Kilo Code 指南。