硅基流动接入 Claude Code 的配置与验证顺序

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

先把结论摆在前面：这件事的难点不是环境变量怎么写，而是两边文档的交界处有一段空白。 硅基流动官方文档写明它的 API 兼容 OpenAI 与 Anthropic 两套对话协议，也给出了 API 基址和鉴权头；Claude Code 官方文档写明 ANTHROPIC_BASE_URL 用于把请求改道到代理或网关，并给出了凭据变量、验证请求和排错表。但硅基流动的文档里没有针对 Claude Code 的接入说明，也没有写 Anthropic 协议下的具体端点路径；而 Claude Code 文档反过来还有一句必须知道的话——Anthropic 不背书、不维护、不审计第三方网关产品，也不支持通过任何网关把 Claude Code 路由到非 Claude 模型。所以正确的做法是：先用一条 curl 把「地址加凭据」这条路验通，再去动 Claude Code 的配置；curl 不通就不要在客户端里反复试，那只会把客户端自身的报错和上游的报错混在一起。

先分清哪句话是谁说的

这一步看着啰嗦，但它决定了后面每一步该信谁。

硅基流动官方文档这边，明确写着的有这么几条：API 基址是 https://api.siliconflow.cn/v1，聊天端点是 https://api.siliconflow.cn/v1/chat/completions，鉴权头是 authorization: Bearer <你的 apikey>，API Key 在控制台的「API 密钥」页面新建。协议方面，官方的说法是兼容 OpenAI 与 Anthropic 对话协议，并且大语言模型可以直接用 OpenAI 官方库调用，只需要把 base_url 指到上面那个基址；官方给出的 Python 示例要求 Python 3.7.1 或更高版本。

Claude Code 官方文档这边，关于走网关的部分写得相当细：ANTHROPIC_BASE_URL 的作用是覆盖 API 端点，把请求路由到代理或网关；在 Anthropic Messages 这套格式下，网关需要提供的端点是 /v1/messages，另有可选的 /v1/messages/count_tokens；推理请求实际发往 /v1/messages?beta=true，所以网关侧要按路径匹配而不是按完整 URL 匹配。请求头里 anthropic-version 与 anthropic-beta 必须原样转发，后者是一串逗号分隔的能力值，官方特意提醒不要按当前看到的取值做白名单，因为这个集合会随版本变化。

两边一拼就能看出空白在哪：硅基流动写的是「兼容 Anthropic 对话协议」，但官方文档里没有找到 Anthropic 协议对应的端点路径说明，也没说 /v1 这个基址下是否直接提供 /v1/messages。这一格必须你自己去官方文档与控制台确认，不能靠猜，更不能拿 OpenAI 兼容层的路径去推断 Anthropic 兼容层的路径——这正是最容易出错的地方。

凭据变量选哪一个：Bearer 还是 x-api-key

Claude Code 官方给出的对照关系很清楚，三个选项各自落到不同的 HTTP 头上：

• ANTHROPIC_AUTH_TOKEN：值会被加上 Bearer 前缀，放进 Authorization 头。对方告诉你是「bearer token」或「Authorization 头」时用它。
• ANTHROPIC_API_KEY：放进 x-api-key 头。对方说的是「API key」或「x-api-key」时用它。
• apiKeyHelper：一条命令，Claude Code 运行它取当前凭据，取到的值两个头都会发。适合凭据会轮换或来自密钥库的情况。

硅基流动官方文档写的鉴权头是 authorization: Bearer <你的 apikey>，正好对上第一种形态。Claude Code 官方也给了一个兜底规则：不确定属于哪一种就先用 ANTHROPIC_AUTH_TOKEN，如果验证请求返回 401，说明凭据到了网关却在一个它不读的头里，换另一个变量再试一次。

有个副作用一定要提前知道：凭据变量优先级高于已保存的 claude.ai 登录。用 ANTHROPIC_AUTH_TOKEN 时立即接管，用 ANTHROPIC_API_KEY 时在交互式会话里会提示你批准一次（非交互的 -p 模式下有值就直接用）。变量生效期间你的登录态还在，只是不被使用，取消变量就会回到原来的登录。还有一句写在排错表里、但值得提前记住的话：可达的基址本身不算凭据——只把 ANTHROPIC_BASE_URL 设好、凭据变量没设，Claude Code 一样会要求你登录。

配置写在哪里：shell 导出还是 settings 文件

官方建议第一次连接先用 shell 导出，验证通过之后再搬进 settings 文件。两者的边界差别很实在：

shell 里 export 出来的变量只对当前终端会话以及由它启动的程序有效。从 Dock 或开始菜单点开的编辑器读不到；后台会话的托管进程也不一定拿得到，官方明确说过，需要后台代理始终走网关的话就别只靠 shell。

要持久生效就写进 settings 文件的 env 块。~/.claude/settings.json 对所有项目生效，Windows 上路径是 %USERPROFILE%\.claude\settings.json；.claude/settings.local.json 只对当前项目生效，官方提醒如果是你手写创建的，要自己先加进 gitignore，免得把凭据提交上去。官方还有一句加粗级别的告诫：不要把凭据写进项目里那个会被提交的 .claude/settings.json。当 shell 导出与 settings 文件的 env 块设了同一个变量时，settings 文件里的值生效。

VS Code 扩展是另一套：网关变量要写在 VS Code 自己的用户设置里的 claudeCode.environmentVariables，因为扩展在启动前会先做一次凭据检查，写在 ~/.claude/settings.json 里的值能到达被拉起的进程，却到不了扩展自身的那次检查。

验证顺序：curl 在前，/status 在中，发消息在后

官方给的验证请求是直接对着基址后面的 /v1/messages 路径发一个只要一个 token 的 POST，带上 Authorization: Bearer、anthropic-version: 2023-06-01 和 content-type: application/json。这一步放在打开客户端之前做，好处是失败时能立刻判定是地址和凭据的问题，而不是客户端配置的问题。

判读规则官方也写了，而且有一条很容易被忽略：返回体以 {"id":"msg_ 开头并带 "content":[...] 字段，说明地址可达且凭据可用；返回一个「模型名不认识」的错误同样算验证通过，因为对方是先完成鉴权才拒绝模型名的，你不需要为了这个测试专门找一个可用模型名。返回 401 则是凭据被拒，先按上一节换一个变量。

接着启动 claude（要从设了导出的同一个 shell 里启动，否则继承不到），运行 /status 看 Status 标签页：Anthropic base URL 这一行应该显示你填的网关地址，这说明请求确实改道了；这一行压根不在，就说明变量没进到这个会话里；再看 Auth token 或 API key 行，它会指出当前用的是哪个变量或 apiKeyHelper，如果显示的是 Login method 加一个 claude.ai 账号，说明凭据没生效。最后发一条普通消息，收到正常回复才算这条链路真的通了。

硅基流动那边的错误码可以直接拿来判读上游侧的问题：401 是 API Key 没有正确设置；402 是账户欠费，充值后重试；403 是权限不够，官方点名最常见的原因是该模型需要实名认证；429 是触发速率限制，要按 message 判断是哪一类指标；503 与 504 是服务负载较高，对话类请求可以尝试改用流式输出。它的错误响应形如 {"code":20012,"message":"Model does not exist. Please check it carefully.","data":null}，message 字段是排错时最值钱的部分。速率限制这块的具体口径可以看硅基流动速率限制的机制说明，错误码的完整排查顺序见硅基流动常见报错排查。

还有一种结果最迷惑人：HTTP 状态是 200，但返回的不是 API 响应而是一段 HTML（常见于登录页或中间代理的错误页）。Claude Code 对这种情况的报错是 API returned an empty or malformed response (HTTP 200)，官方给的处理办法就是回到上面那条 curl 去看真实返回体。

模型名这一关

Claude Code 的 /model 选择器只列内置名单，网关侧的模型名不在其中就选不到。官方提供了一个开关：CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，开启后 Claude Code 会在启动时去查网关的 /v1/models 端点，把拿到的名字作为额外条目加进选择器，条目上标着 From gateway。这个开关默认是关的，官方给的理由值得一读：共享同一把 key 的网关，一旦开启就会把这把 key 能访问的所有模型展示给每一个人。想确认发现流程有没有跑起来，可以用 claude --debug 启动，然后到 ~/.claude/debug/<session-id>.txt 里找 [gatewayDiscovery] 开头的行，成功会记录缓存了多少个模型，404、超时和重定向也都记在那里。

发现流程还有一道筛子，很多人是撞上之后才知道的：官方文档写明，Claude Code 只保留 id 里包含 claude 或 anthropic 子串的条目（不区分大小写），带供应商前缀的 ID 也算通过，其余一律忽略。也就是说，命名里不带这两个词的模型即使网关如实返回了，也不会出现在选择器里。这条和上面那句「不支持路由到非 Claude 模型」是同一个方向上的两处设计，别指望靠开关绕过去。

硅基流动侧有一条命名规则会直接影响你往这里填什么：部分模型同时有免费版与收费版，免费版沿用原名称，收费版在名称前加 Pro/ 前缀。更细一层，DeepSeek R1 与 V3 是按支付方式区分命名的——Pro/ 版仅支持充值余额支付，非 Pro/ 版支持赠费余额和充值余额支付。也就是说前缀差一个词，走的钱包都不一样。免费版的速率限制是固定值，收费版的限制随账户用量级别变化；具体某个模型的限额是多少，官方的口径是去模型广场查，文档里没有给出一份固定的对照表。

上下文窗口是另一个坑：当模型 ID 不在 Claude Code 的内置名单里时，它假定的窗口大小可能与实际不符，官方给的对应变量是 CLAUDE_CODE_MAX_CONTEXT_TOKENS。硅基流动这边也有一条相关提醒——max_tokens 与上下文长度相等，但官方建议不要把它设成最大值，要给输入内容留出余量。

接上之后，哪些能力会跟着变

这部分是很多人配通之后才发现的，提前知道能省一轮排查。Claude Code 官方文档写明：

• 当 ANTHROPIC_BASE_URL 指向非一方主机时，MCP 的工具搜索默认被关闭；只有在你的代理确实会转发 tool_reference 块的前提下，才应该设 ENABLE_TOOL_SEARCH=true。
• Remote Control 在凭据变量激活时不可用，并且当 ANTHROPIC_BASE_URL 指向 api.anthropic.com 以外的主机时也会被禁用；语音听写依赖 claude.ai 身份，同样在凭据变量激活时不可用。
• fast mode 的可用性检查是直连 api.anthropic.com 的，不跟随 ANTHROPIC_BASE_URL。所以会出现推理请求正常、/fast 却报连接问题的组合。
• 如果上游拒绝 Claude Code 发出的某些字段，会以 400 的形式表现出来，报错里可能出现 context_management 或 Extra inputs are not permitted 这类字样；官方给的缓解手段是设 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1，它会抑制大部分预发布字段。
• 流式是硬要求。官方写明推理响应必须流式，缓冲完整响应再转发会让客户端卡住；keep-alive ping 也要转发，因为长时间思考期间只有 ping 在传，中间环节把它剥掉或缓冲，客户端就会把这段静默当成断流。

配不通的时候按什么顺序退

硅基流动官方给的通用排查步骤有四步，顺序本身就是有讲究的：先把错误码和 message 打印出来，再用 curl 复现，再换一个模型试，最后——如果开了代理，关掉代理再试。最后这条在国内环境里踩中的概率不低，很多「莫名其妙连不上」最后都归到这里。

Claude Code 侧的对应关系也可以照着退：地址没人应答会报连接被拒，主机名解析不了会报无法到达 API 服务器，这两类都回到那条 curl 上去看；curl 通了但客户端反复要求登录，官方说的原因是 CLI 自己没有凭据——可达的基址不算凭据，而且交互式会话里项目级 .claude/settings.json 的 env 块要在首次运行向导和信任提示之后才生效，所以凭据要放到更早被读到的地方，比如 shell 导出或 ~/.claude/settings.json；curl 正常却报证书或 TLS 错误，通常是运行时信任的 CA 与 curl 不一致，对应变量是 NODE_EXTRA_CA_CERTS。

最后再强调一次本文开头那句话：Anthropic 官方明确表示不支持通过网关把 Claude Code 路由到非 Claude 模型，硅基流动官方文档也没有给出面向 Claude Code 的接入指引。这不是「一定跑不起来」的意思，而是说这条路上出了问题，双方文档都没有承诺给你答案，排查成本要自己承担。如果你的目标只是把硅基流动的模型用起来，走它官方明文支持的 OpenAI 兼容层通常是更稳的路径，具体见硅基流动 API 接入方式；把凭据搬进 settings 文件之前，也顺手看一眼API Key 的安全管理，别把 key 提交进仓库。