API 用户配置文档

Claude Code 接入步骤 ​

安装 Claude Code ​

如果尚未安装 Claude Code，先确认本机已安装 Node.js 18 或更新版本：

bash
node -v
npm -v

国内网络建议先把 npm 仓库切到国内镜像：

bash
npm config set registry https://registry.npmmirror.com

全局安装 Claude Code：

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

确认安装结果：

bash
claude --version

后续升级：

bash
claude update

模型网关自动发现能力依赖较新版本，建议保持 Claude Code 在最新版。

Claude Code 官方对 LLM Gateway 的要求：

  • 网关需要提供 Anthropic Messages 风格接口：/v1/messages。
  • 完整兼容时还应提供：/v1/messages/count_tokens。
  • 网关需要正确处理 anthropic-version、anthropic-beta 等请求头。
  • 使用 ANTHROPIC_AUTH_TOKEN 时，Claude Code 会把该值作为 Authorization: Bearer ... 发送。

当前接入建议先使用普通对话和流式输出能力。若客户端依赖 token 预估、特殊 beta 功能、扩展 thinking 或复杂工具调用，需要单独验证。

方式 1：临时环境变量 ​

适合一次性测试。

bash
export ANTHROPIC_BASE_URL="https://api.aiqizhilian.tech"
export ANTHROPIC_AUTH_TOKEN="<你的 API Key>"
export ANTHROPIC_MODEL="claude-sonnet-4-6"

claude

启动后在 Claude Code 内执行：

text
/status

查看当前是否走的是本 API 网关。

也可以使用：

text
/model

如果 /model 能看到来自网关的 Claude 模型，说明模型发现可用。若没有显示，可按 常见问题 手动指定模型。

方式 2：持久化配置（推荐） ​

适合长期使用。编辑用户级配置文件：

text
~/.claude/settings.json

示例：

json
{
  "model": "claude-sonnet-4-6",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aiqizhilian.tech",
    "ANTHROPIC_AUTH_TOKEN": "<你的 API Key>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-7",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "ENABLE_TOOL_SEARCH": "0"
  }
}

写入后建议把文件权限收紧到只有自己可读，避免同机其他用户拿到 Key：

bash
chmod 600 ~/.claude/settings.json

字段说明：

  • 顶层 model：Claude Code 启动时默认使用的模型。
  • env.ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN：Claude Code 启动子进程时注入的环境变量，构成本次会话的网关地址与凭证。
  • env.ANTHROPIC_DEFAULT_*_MODEL：Claude Code 在后台任务（摘要、commit message 生成、agent compaction 等）会依据模型档位自动选择对应模型。如果不设这几个变量，Claude Code 会默认去找 claude-haiku-*、claude-sonnet-*、claude-opus-* 命名规则的模型，可能与网关上的实际模型名不匹配，导致后台功能静默失败。
  • env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1：关闭 Claude Code 的实验性 beta 功能，避免对第三方网关协议尚未完整覆盖的能力（如 prompt cache 高级模式、新版 tool 协议）导致请求失败。
  • env.ENABLE_TOOL_SEARCH=0：关闭 Claude Code 内置的工具搜索，减少首字延迟和上下文占用。如有强需求可改回 1。

如果只希望在某个项目内生效，可把同样配置写入该项目下的：

text
.claude/settings.local.json

不要提交 settings.local.json

项目内本地配置适合保存个人 API Key，不建议提交到 Git。建议加入 .gitignore。

方式 3：启动时指定模型 ​

bash
claude --model claude-sonnet-4-6

适合临时切换模型测试。

连通性预检 ​

在配置 Claude Code 前，可先用 curl 验证 API Key 和 /v1/messages 是否可用：

bash
curl https://api.aiqizhilian.tech/v1/messages \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 256,
    "messages": [
      {
        "role": "user",
        "content": "用一句话介绍你自己。"
      }
    ]
  }'

正常响应：

json
{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 20
  }
}

流式预检：

bash
curl https://api.aiqizhilian.tech/v1/messages \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 256,
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "用三句话介绍东京。"
      }
    ]
  }'

流式响应使用 SSE，按 event: 和 data: 行增量读取。

推荐模型 ​

Model建议用途
claude-sonnet-4-6日常代码、长文本、分析、通用任务
claude-opus-4-7更复杂的推理、方案设计、高质量写作
claude-haiku-4-5-20251001后台任务（摘要、commit message、agent compaction）