大多数搜索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 Code | claude-code-router |
| 逐请求日志:提供商、模型、延迟、令牌数、费用 | claude-code-router |
| 将子代理发送到不同于主循环的模型 | claude-code-router — 层级变量无法做到这一点 |
路由器是一个本地服务:需要额外运行、配置并保持最新的进程;截至 2026 年,它还是一个带有独立 UI 的桌面应用,而不是供你编辑的文件。只有在你确实需要多提供商路由、逐请求计费或子代理级别的模型选择时,这项成本才值得承担。如果一个基础 URL 就能满足需求,它就不值得。
选项 A — 替换基础 URL(无需安装)
Kunavo 在 /v1/messages 提供原生 Anthropic Messages API,这正是 Claude Code 调用的端点。将 Claude Code 指向该端点:
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 tasksANTHROPIC_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_TOKEN | Authorization: Bearer | 推荐 — 到处可用 |
ANTHROPIC_API_KEY | x-api-key | 一次性批准后,可用于聊天和模型发现 |
建议使用 ANTHROPIC_AUTH_TOKEN,理由很具体:ANTHROPIC_API_KEY 需要在交互式会话中进行一次性批准;如果你曾拒绝过某个密钥,之后它会被忽略且不会再次提示——变量明明已设置,却明显未被使用,这是一个容易困惑的失败原因。Kunavo 不决定模型发现使用哪个变量。Claude Code 的网关模型发现功能在设置 仅 ANTHROPIC_AUTH_TOKEN 时发送 bearer 令牌,否则回退到 x-api-key;而 Kunavo 的 /v1/models 端点会从任一标头读取密钥。
让配置持久生效
Shell 导出变量只对当前终端及从该终端启动的任何程序生效——从 Dock 打开的编辑器看不到它们,后台代理也看不到。将这些值放入设置文件,以覆盖所有场景:
{
"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:
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 → Kunavo | Providers → 提供商的 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 个令牌的输入 / 输出 | 实际运行的内容 |
|---|---|---|---|
| Opus | Kunavo/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% |
| Haiku | Kunavo/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(输入 / 输出) | Kunavo | Anthropic 标价 |
|---|---|---|---|
| 一次代理式步骤 | 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 或 adaptive | Claude 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"。 |
安装后找不到 ccr | npm 的全局 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 指南。