接入 Claude Code

一句话结论：Claude Code 走 Anthropic Messages 协议。 把 ANTHROPIC_BASE_URL 指向 ZiAI 根地址（不带 /v1），密钥放进 ANTHROPIC_AUTH_TOKEN（不是 ANTHROPIC_API_KEY），即可全部流量改走 ZiAI。

项目	值
协议	Anthropic Messages
端点	https://api.ziai.lol/v1/messages（客户端自行拼接）
ANTHROPIC_BASE_URL	https://api.ziai.lol —— 不带 /v1
密钥变量	ANTHROPIC_AUTH_TOKEN
配置文件	~/.claude/settings.json 的 env 块
生效方式	重启 Claude Code

两个变量发出的请求头完全不同

环境变量	实际发出的请求头	谁认这个格式
ANTHROPIC_API_KEY	x-api-key: sk-...	Anthropic 官方 API
ANTHROPIC_AUTH_TOKEN	Authorization: Bearer sk-...	网关 / 中转站普遍认这个

接 ZiAI 请用 ANTHROPIC_AUTH_TOKEN。只设 ANTHROPIC_API_KEY 时可能得到 401，且报错信息不会告诉你原因 —— 这是中转站接入最高频、最难自查的坑。

ZiAI 两种头都接受，但接中转站统一推荐 ANTHROPIC_AUTH_TOKEN，与主流网关的惯例一致。

前提：安装 Claude Code

macOS / Linux（推荐原生安装器）

curl -fsSL https://claude.ai/install.sh | bash

若提示需要把安装目录加入 PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

zsh 用户把 .bashrc 换成 .zshrc。

Windows

Windows 环境下需要用 Git Bash 安装 Claude Code；安装完成后，设置环境变量与日常使用仍在 PowerShell 或 CMD 中进行。

1. 安装 Node.js LTS（node --version 验证）

2. 安装 Git for Windows（git --version 验证）

3. 打开 PowerShell 安装：

   npm install -g @anthropic-ai/claude-code

4. 若提示需要加入 PATH：

   [Environment]::SetEnvironmentVariable('Path', ([Environment]::GetEnvironmentVariable('Path','User') + ";$HOME\.local\bin"), 'User')

不要使用 sudo npm install -g

官方明确警告不要用 sudo npm install -g 安装。 遇到权限问题请改用原生安装器，或把 npm 全局目录改到用户目录：

npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

验证安装：

claude --version

方式 A：用 CC-Switch 图形化配置 推荐

如果你同时还要接 Codex，或需要在 ZiAI 与官方账号之间来回切换，优先用 CC-Switch： 图形界面填 Base URL 与密钥，自动生成下面这份配置，还能一键切换、自动备份。

CC-Switch 的「自定义」供应商 JSON 就是：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "ANTHROPIC_BASE_URL": "https://api.ziai.lol",
    "ANTHROPIC_MODEL": "你的模型ID"
  }
}

下面的手动方式适合不想装第三方应用、或需要在服务器上无界面配置的场景。

方式 B：手动写 settings.json（推荐长期使用）

~/.claude/settings.json 里的 env 块由 Claude Code 启动时直接读取，无论用哪种方式启动都会生效，比 shell 环境变量更可靠。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.ziai.lol",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "ANTHROPIC_MODEL": "你的模型ID",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "你的模型ID",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "你的模型ID",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "你的轻量模型ID",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}

配置文件优先级

文件	适用范围
~/.claude/settings.json	你的所有项目（接 ZiAI 用这个）
.claude/settings.json	项目内所有人，可提交到版本库
.claude/settings.local.json	仅你自己、仅本项目（手工创建时记得加 gitignore）
托管设置（Managed）	组织内所有人，由管理员部署，用户与项目设置无法覆盖

让 /model 直接列出 ZiAI 的模型

设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 后，Claude Code 启动时会查询网关的模型列表， 把这些名称加入 /model 选择器，与内置条目一起显示（无描述时显示 From gateway）。 ZiAI 提供 /v1/models，因此可以直接用这个能力，不必逐个手填模型 ID。

确认是否生效：用 claude --debug 启动，在 ~/.claude/debug/{'{session-id}'}.txt 里找 [gatewayDiscovery] 行。

方式 C：只在当前终端临时生效

适合快速验证，不影响长期配置：

bash / zsh / Git Bash

export ANTHROPIC_BASE_URL="https://api.ziai.lol"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export ANTHROPIC_MODEL="你的模型ID"
claude

PowerShell

$env:ANTHROPIC_BASE_URL = "https://api.ziai.lol"
$env:ANTHROPIC_AUTH_TOKEN = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
$env:ANTHROPIC_MODEL = "你的模型ID"
claude

CMD

set ANTHROPIC_BASE_URL=https://api.ziai.lol
set ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
set ANTHROPIC_MODEL=你的模型ID
claude

环境变量速查

必填 / 常用

变量	作用
ANTHROPIC_BASE_URL	覆盖 API 端点，把请求路由到 ZiAI
ANTHROPIC_AUTH_TOKEN	作为 Authorization 头的值，自动加 Bearer 前缀
ANTHROPIC_API_KEY	作为 x-api-key 发送；设置后会覆盖你的 Claude 订阅
ANTHROPIC_MODEL	要使用的模型
ANTHROPIC_DEFAULT_SONNET_MODEL	sonnet 别名解析到的模型 ID
ANTHROPIC_DEFAULT_OPUS_MODEL	opus 别名解析到的模型 ID（Plan Mode 下 opusplan 也用它）
ANTHROPIC_DEFAULT_HAIKU_MODEL	haiku 别名解析到的模型 ID，也用于后台功能
ANTHROPIC_DEFAULT_MODEL	新会话默认启动的模型（需 v2.1.236+）
ANTHROPIC_CUSTOM_MODEL_OPTION	往 /model 选择器加一个自定义条目，适合网关专有模型 ID

ANTHROPIC_SMALL_FAST_MODEL 已弃用

旧教程常让你设 ANTHROPIC_SMALL_FAST_MODEL，该变量已弃用，请改用 ANTHROPIC_DEFAULT_HAIKU_MODEL。

网关兼容性开关（接中转站时最有用的一组）

Claude Code 官方为「通过 LLM 网关路由」准备了一批兼容开关。ZiAI 属于第三方网关，遇到奇怪报错时优先查这张表：

变量	什么时候设	解决什么
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1	想让 /model 自动列出网关模型	免去手填模型 ID
CLAUDE_CODE_DISABLE_ARTIFACT=1	每个请求都 400 Invalid schema for function 'Artifact'	网关严格校验工具 JSON Schema，拒收 Artifact 工具的 Unicode 属性转义
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1	报 Unexpected value(s) for the anthropic-beta header 或 Extra inputs are not permitted	去掉 anthropic-beta 头与 beta 工具字段（defer_loading、eager_input_streaming），保留标准字段
CLAUDE_CODE_DISABLE_THINKING=1	网关拒收 thinking 参数	从请求中完全省略 thinking
CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1	用网关自定义模型 ID，effort 不生效	即使 Claude Code 不认识该模型 ID 也发送 effort 参数
CLAUDE_CODE_MAX_CONTEXT_TOKENS	网关模型 ID 不被识别、压缩触发点不对	纠正 Claude Code 假定的上下文窗口
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1	未知模型 ID 导致过早自动压缩	跳过对不认识的模型 ID 的主动压缩
API_TIMEOUT_MS	网络慢或走代理，默认 10 分钟不够	调大 API 请求超时（毫秒）
API_FORCE_IDLE_TIMEOUT=0	慢网关在数据块之间暂停超过 5 分钟	关闭正文空闲超时（默认 5 分钟无字节即中止流式响应）
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1	流式失败后回退导致工具被重复执行	禁用非流式回退，让错误直接传播到重试层
CLAUDE_CODE_ATTRIBUTION_HEADER=0	网关按请求体做缓存、命中率异常低	省略系统提示开头的归属块（v2.1.181 前它在自定义 base URL 下含每请求令牌，会破坏上游前缀缓存）
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1	想关掉自动更新、遥测、错误上报等	减少非必要网络流量。注意：设为 0 或 false 同样会禁用，要恢复必须取消设置该变量

设置 ANTHROPIC_BASE_URL 的两个副作用

官方文档明确：

1. ANTHROPIC_BASE_URL 指向非第一方主机时，MCP 工具搜索默认被禁用。若你的网关会转发 tool_reference 块，可设 ENABLE_TOOL_SEARCH=true 恢复。
2. 从 v2.1.196 起，当它指向 api.anthropic.com 以外的主机时，Remote Control 被禁用（与 Bedrock、Google Cloud、Microsoft Foundry 上的行为一致）。

这两条不是故障，是设计行为。

验证

1. 确认变量已生效

   echo $ANTHROPIC_BASE_URL        # bash / zsh / Git Bash
   echo $ANTHROPIC_AUTH_TOKEN | cut -c1-6   # 只看前几位，避免泄露

   echo $env:ANTHROPIC_BASE_URL    # PowerShell

2. 直接打端点，确认 ZiAI 侧通

   curl https://api.ziai.lol/v1/messages \
     -H "content-type: application/json" \
     -H "x-api-key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "anthropic-version: 2023-06-01" \
     -d '{"model":"你的模型ID","max_tokens":64,"messages":[{"role":"user","content":"你好"}]}'

3. 启动 Claude Code

   cd /path/to/your/project
   claude

   进入后用 /status 查看当前接入点，用 /model 选择模型，发一句话确认能回复。

   待补插图Claude Code 接入 ZiAI 后首次对话成功

   终端里 claude 启动后显示模型名，并成功回复一句话；宽 1200，PNG

配置后不再消耗官方订阅额度

设置 ANTHROPIC_BASE_URL 后，所有模型（包括官方预设模型名）都会走 ZiAI，不再使用你的 Claude Pro / Max 订阅额度。 想切回官方：取消设置这些变量（unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN），或用 CC-Switch 切到官方供应商卡片。

Claude Code 专属常见问题

现象	原因	解决
401，密钥明明正确	用了 ANTHROPIC_API_KEY 而非 AUTH_TOKEN	改用 ANTHROPIC_AUTH_TOKEN
404 Not Found	ANTHROPIC_BASE_URL 多带了 /v1	去掉 /v1，只留根地址
每个请求都 400 Invalid schema for function 'Artifact'	网关严格校验工具 schema	设 CLAUDE_CODE_DISABLE_ARTIFACT=1
报 Unexpected value(s) for the anthropic-beta header	网关不接受 beta 头	设 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
报 Extra inputs are not permitted	网关不接受 beta 工具字段	同上
思考参数被拒	网关不支持 thinking	设 CLAUDE_CODE_DISABLE_THINKING=1
调 effort 无效果	网关模型 ID 不被识别	设 CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1
长任务在静默后中断	触发 5 分钟正文空闲超时	设 API_FORCE_IDLE_TIMEOUT=0，并适当调大 API_TIMEOUT_MS
工具被重复执行	流式失败后非流式回退	设 CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1
/model 里没有 ZiAI 的模型	未开启网关模型发现	设 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，或用 ANTHROPIC_CUSTOM_MODEL_OPTION
输出每个 token 一行、大量空 Thought 块	上游回传空 reasoning_content 占位	用 CC-Switch ≥ v3.20.3 走本地转换可修复
Windows 上 claude 命令找不到	PATH 未包含安装目录	把 $HOME\.local\bin 加入用户 PATH 后重开终端

更多按报错码分类的排查见常见报错速查。

下一步

• 接入 Codex —— 另一个终端 Agent，协议不同
• CC-Switch：添加 ZiAI 并切换 —— 图形化管理与多站切换
• 协议不匹配详解