Claude Code Manual

凭证与接入 XAI Router

Claude Code 支持多种登录方式。接入 XAI Router 只需要两个环境变量:API 地址和你的 Key。

三种凭证

方式怎么用谁来计费
Claude 订阅账号启动后按提示在浏览器登录,或运行 /login你的 Claude 订阅
Anthropic API Key环境变量 ANTHROPIC_API_KEYAnthropic 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"' >> ~/.zshrc

Windows(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 指向证书文件。