Claude Code Manual
凭证与接入 XAI Router
Claude Code 支持多种登录方式。接入 XAI Router 只需要两个环境变量:API 地址和你的 Key。
三种凭证
| 方式 | 怎么用 | 谁来计费 |
|---|---|---|
| Claude 订阅账号 | 启动后按提示在浏览器登录,或运行 /login | 你的 Claude 订阅 |
| Anthropic API Key | 环境变量 ANTHROPIC_API_KEY | Anthropic Console 账户 |
| API 网关凭证 | 环境变量 ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN | 网关账户,例如 XAI Router |
同时存在多种凭证时,Claude Code 按固定顺序选择:ANTHROPIC_AUTH_TOKEN 优先于 ANTHROPIC_API_KEY,两者都优先于浏览器登录的订阅账号。启动时如果同时发现两种凭证来源,会给出警告;想改用网关凭证,可以运行 /logout 清掉已保存的登录。
两个容易踩的坑:
- 只设置
ANTHROPIC_BASE_URL、不设置凭证:如果你之前登录过订阅账号,请求会经过新地址,但仍然使用订阅账号计费。接入 XAI Router 时两个变量都要设置。 - 残留的旧变量:以前设置过
ANTHROPIC_API_KEY,现在又设置了ANTHROPIC_AUTH_TOKEN,生效的是后者。排查问题时记得检查有没有残留的变量。
获取 Key
在 m.xairouter.com 注册账号,系统会把 API Key 发到注册邮箱。Key 等同于你的钱包,不要截图、外发或提交到代码仓库。
方式一:环境变量
适合你已经习惯用环境变量管理 Key 的情况。
macOS / Linux(zsh 写入 ~/.zshrc,bash 写入 ~/.bashrc):
echo 'export ANTHROPIC_BASE_URL="https://api.xairouter.com"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="sk-你的Key"' >> ~/.zshrcWindows(PowerShell):
setx ANTHROPIC_BASE_URL "https://api.xairouter.com"
setx ANTHROPIC_AUTH_TOKEN "sk-你的Key"设置后重新打开终端。注意:只写在 shell 里的变量不一定能传给后台运行的会话(claude agents、--bg 启动的后台会话),需要后台会话也走 XAI Router 时,请用下面的方式二。检查 Key 的长度(不会把 Key 显示出来):
echo ${#ANTHROPIC_AUTH_TOKEN}$env:ANTHROPIC_AUTH_TOKEN.Length方式二:settings.json
把变量写进 Claude Code 自己的配置文件 ~/.claude/settings.json(Windows 为 %USERPROFILE%\.claude\settings.json)的 env 中,只对 Claude Code 生效,也不受终端类型影响:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.xairouter.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
},
"permissions": {
"defaultMode": "default"
}
}permissions.defaultMode 让每次会话都从“手动审批”模式开始,原因见权限与安全。同一个变量既在 shell 里设置、又写在 settings.json 的 env 里时,以 settings.json 里的为准。
这个文件里有明文 Key:只在个人电脑上这样做,不要把它分享出去,也不要把含 Key 的配置放进项目仓库的 .claude/settings.json。
验证
claude设置了 ANTHROPIC_AUTH_TOKEN 后,Claude Code 不会再要求浏览器登录。进入后输入 /status(打开设置界面的 Status 页),确认两行:Anthropic base URL 显示 https://api.xairouter.com,并且有一行 Auth token 或 API key 指向你设置的变量,而不是 Login method 指向某个 Claude 账号。再随便问一句,比如“你好,用一句话介绍你自己”,能正常回复即接入成功。
想在打开 Claude Code 之前先确认地址和 Key 可用,可以直接发一个只返回一个 token 的请求(先在当前终端里设置好上面两个变量):
curl -sS -w '\n%{http_code}\n' -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-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'返回以 {"id":"msg_ 开头的 JSON 说明地址和 Key 都正常;返回 401 说明 Key 有问题。
选择模型
- 会话中输入
/model,从列表里选择。 - 启动时指定:
claude --model claude-sonnet-5-5。 - 用环境变量
ANTHROPIC_MODEL设置默认模型;--model和/model的优先级比它高。
XAI Router 上可用的 Claude 模型见模型页,例如 claude-opus-5-5、claude-sonnet-5-5、claude-haiku-5-5、claude-fable-5-2。接入网关时,建议直接写完整的模型名。
Claude Code 还有 opus、sonnet、haiku、fable 这几个别名。官方文档说明,在 Anthropic API 上它们分别指向 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.2,别名会随官方版本更新而变化。想固定别名对应的模型,可以用 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL、ANTHROPIC_DEFAULT_FABLE_MODEL 指定完整模型名,例如:
{
"env": {
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5"
}
}新模型需要较新的 Claude Code 版本:官方文档标注 Opus 5.5 需要 v2.1.280 及以上,Sonnet 5.5 需要 v2.1.284 及以上,Haiku 5.5 需要 v2.1.293 及以上,Fable 5.2 需要 v2.1.321 及以上。版本太旧时请求会失败,运行 claude update 即可。
在 /model 选择器里如果没有看到你想用的模型名,直接输入完整模型名即可,例如 /model claude-opus-5-5。
接入网关后不可用的功能
按官方文档,只要设置了 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 或 apiKeyHelper,下面这些依赖 claude.ai 账号的功能就不可用:
- Remote Control(远程控制)和语音输入。Remote Control 在
ANTHROPIC_BASE_URL指向非 Anthropic 地址时也会被关闭。 - 桌面 App 不读取
ANTHROPIC_BASE_URL和settings.json,它的网关地址在自己的第三方推理配置里设置,本手册不涉及。 - VS Code 扩展:把变量写进 VS Code 用户设置的
claudeCode.environmentVariables。 - 云端会话和 Slack 不走你设置的网关。
本手册以终端为主,上面几项只在你使用对应入口时需要留意。
网络受限时
如果你的网络访问 Anthropic 官方服务不稳定,可以设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1,关闭自动更新、遥测、错误上报等非必要的网络请求,只保留模型调用。代价是不会再自动更新,需要定期手动运行 claude update。
公司网络需要代理时,设置 HTTPS_PROXY;如果代理使用公司自签的证书,再设置 NODE_EXTRA_CA_CERTS 指向证书文件。