Claude Code 接入
把 Claude Code 指向 JuCode 的 Anthropic 兼容端点。
Claude Code 接第三方网关靠两个环境变量:一个改地址,一个给凭证。凭证变量有两个候选,
选 ANTHROPIC_AUTH_TOKEN。
原因不是 JuCode 只认某一个头——两个头它都认(见认证)——
而是 Claude Code 这一侧的行为不同:ANTHROPIC_AUTH_TOKEN 设上就立即生效,
ANTHROPIC_API_KEY 在交互式会话里要你手动批准一次才会接管,而且一旦拒绝过就会被
静默忽略,不再提示。设了却毫无反应,又没有任何提示,这种状态很难自己发现。
安装
npm install -g @anthropic-ai/claude-code配置
准备 API Key
在 jucode.cn 控制台创建一把 Key,形如 sk-juc- 加 43 位字符。
完整值只在创建时显示一次。
设置两个变量
export ANTHROPIC_BASE_URL="https://api.jucode.cn/anthropic"
export ANTHROPIC_AUTH_TOKEN="sk-juc-..."写进 ~/.zshrc 或 ~/.bashrc 可以持久化。
Base URL 填到 /anthropic 为止
不要加 /v1。Claude Code 会自己在后面拼 /v1/messages,最终打到
https://api.jucode.cn/anthropic/v1/messages。
别把 Key 写进项目的 .claude/settings.json
那个文件是要提交进版本库的。用 ~/.claude/settings.json,或者项目内的
.claude/settings.local.json(手动创建的话记得先加进 gitignore)。
还有一个更隐蔽的原因:项目级设置文件的 env 块要在首次运行向导和目录信任提示之后
才生效。首次接入时把变量放在 shell export 或 ~/.claude/settings.json 里,否则
Claude Code 会先弹登录界面。
验证
先用 curl 打一发
绕开 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":"."}]}'响应体以 {"id":"msg_ 开头就说明通了。即使返回的是模型名不存在的错误,也说明地址
和凭证都对——网关是先认证再校验模型的,所以这一步不需要先找到一个真实可用的模型名。
在 Claude Code 里确认
从同一个 shell 启动 claude,发一条消息,然后运行 /status。Status 标签页里看两行:
Anthropic base URL:应显示https://api.jucode.cn/anthropic。这一行只有在设了 base URL 时才出现,没有就说明变量没进到这个会话。Auth token:应点名ANTHROPIC_AUTH_TOKEN。如果看到的是Login method加一个 claude.ai 账号,说明凭证变量没生效,当前用的还是你保存的登录。
选模型
优先级从高到低:会话中的 /model、启动时的 --model、ANTHROPIC_MODEL 环境变量、
设置文件里的 model 字段。
export ANTHROPIC_MODEL="claude-sonnet-5"sonnet、opus、haiku 这些别名解析到哪个具体模型,由下面四个变量控制:
| 变量 | 控制 |
|---|---|
ANTHROPIC_DEFAULT_OPUS_MODEL | opus 别名 |
ANTHROPIC_DEFAULT_SONNET_MODEL | sonnet 别名 |
ANTHROPIC_DEFAULT_HAIKU_MODEL | haiku 别名,以及后台小任务 |
ANTHROPIC_DEFAULT_FABLE_MODEL | fable 别名 |
ANTHROPIC_SMALL_FAST_MODEL 已弃用
官方文档现在明确写着它由 ANTHROPIC_DEFAULT_HAIKU_MODEL 取代。网上不少接入教程仍在
用旧名字,照抄的话后台小任务会落到你没指定的模型上。
自定义 base URL 下模型名不做校验
指向非官方地址时,Claude Code 会把你给的任何字符串原样发出去,不在启动时检查。打错字
不会立刻报错,而是在第一个请求时变成 There's an issue with the selected model。
可用模型名以 GET https://api.jucode.cn/v1/models 为准,别照抄官方模型列表。
/model 里的 Default 选项会解析成 Claude Code 内置的档位默认名,那个名字在 JuCode
上不一定存在。想让别名稳定落到 JuCode 的真实模型上,就把上面四个变量设死。
两条执行路径
JuCode 的 Anthropic 端点内部有原生和桥接两条路径,取决于该模型路由到了哪家上游,
你无法从外部预知。走桥接路径时 thinking、cache_control、top_k 等 Anthropic
专有字段会被静默丢弃,不报错。
Claude Code 依赖扩展思考和 prompt 缓存,所以这一点会直接影响体验。细节见 SDK 迁移。
另外,/anthropic/v1/messages 是网关上唯一保留上游 429 的端点(其他端点会把上游
429 映射成 503),就是为了让 Anthropic 系客户端内建的退避逻辑正常工作。
排查
凭证不以 sk-juc- 开头,被网关当成 OAuth JWT 解析后失败了。
最常见的原因不是 Key 打错,而是变量根本没生效:Claude Code 退回用你保存的 claude.ai
登录令牌,把它发到了 JuCode。跑 /status 确认 Auth token 那一行点名的是
ANTHROPIC_AUTH_TOKEN。
missing credentials 是网关没读到任何凭证,通常是 Bearer 前缀的大小写或空格写错了
——但走 Claude Code 的话这个头是它自己拼的,基本只会出现在你手动 curl 时。
invalid api key 是 Key 不存在或已被吊销。检查复制时有没有带上尾部换行。完整的 401
分支见认证。
交互式会话里这个变量需要一次性批准才会接管,而之前拒绝过的 Key 会被直接忽略,不再
弹提示。到 /config 里打开 Use custom API key,或者干脆改用
ANTHROPIC_AUTH_TOKEN——它不需要批准。
网关凭证变量和已保存的 claude.ai 登录同时存在。请求会用变量,但残留的登录可能导致
意外的认证行为。要用 JuCode 就跑 /logout 清掉登录;要用登录就 unset 变量。
先列出这把 Key 能调的模型:
curl https://api.jucode.cn/v1/models \
-H "Authorization: Bearer $JUCODE_API_KEY"不同 Key 看到的列表可能不同——Key 上可以配模型组白名单。确认名字后,用
ANTHROPIC_MODEL 或 ANTHROPIC_DEFAULT_* 系列变量钉住,别依赖 /model 的 Default。
说明请求压根没走 JuCode。跑 /status:如果没有 Anthropic base URL 这一行,
ANTHROPIC_BASE_URL 就没进到这个会话,请求发去了 api.anthropic.com,记在你的
claude.ai 账号上。
最常见的原因是变量只写在项目的 .claude/settings.json 里——那个 env 块在首次运行
向导和信任提示之后才生效。把它挪到 shell export 或 ~/.claude/settings.json。
想直接确认 JuCode 这边的额度:
curl https://api.jucode.cn/v1/open/balance \
-H "Authorization: Bearer $JUCODE_API_KEY"详见开放 API。