接入 Claude Code

xmAI 原生兼容 Anthropic Messages API（/v1/messages），可作为 Claude Code CLI 的自定义上游。只需两个环境变量即可接入，无需改动 Claude Code 本身。

前置要求

• 已在 XmAI 控制台 注册账号并充值 / 拥有免费额度
• 已在 API Keys 页面创建一把 API Key（形如 sk-xxx...）
• 已安装 Claude Code CLI

配置方式

Claude Code 通过两个环境变量识别自定义上游：

变量	值	说明
ANTHROPIC_BASE_URL	https://api.xmai.sg	xmAI 网关根地址（不带 /v1 后缀，Claude Code 自动拼接）
ANTHROPIC_AUTH_TOKEN	sk-你的 xmAI Key	发送 Authorization: Bearer <token> 头，与 xmAI 认证一致

为何不用 ANTHROPIC_API_KEY

ANTHROPIC_API_KEY 会发送 x-api-key 头（Anthropic 官方风格）；xmAI 采用 OpenAI 风格 Bearer 认证，必须使用 ANTHROPIC_AUTH_TOKEN，两者只能二选一。

方式 A：settings.json 持久化（推荐）

在 ~/.claude/settings.json（全局）或项目根目录 .claude/settings.json 添加：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.xmai.sg",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-xmai-key"
  }
}

保存后重启 Claude Code 即可生效。

方式 B：当前会话临时

macOS / Linux / Git Bash

export ANTHROPIC_BASE_URL="https://api.xmai.sg"
export ANTHROPIC_AUTH_TOKEN="sk-your-xmai-key"
claude

Windows PowerShell

$env:ANTHROPIC_BASE_URL = "https://api.xmai.sg"
$env:ANTHROPIC_AUTH_TOKEN = "sk-your-xmai-key"
claude

Windows CMD

set ANTHROPIC_BASE_URL=https://api.xmai.sg
set ANTHROPIC_AUTH_TOKEN=sk-your-xmai-key
claude

方式 C：永久写入 Shell 配置

把方式 B 的 export 两行加到 ~/.bashrc / ~/.zshrc（Linux/macOS），或在 Windows 环境变量面板中设置用户变量。

模型路由（必读）

Claude Code 默认请求的 model ID 与 xmAI 已上架的 model ID 不完全一致，必须通过环境变量显式映射，否则会收到 404 model not found。

xmAI 目前上架的 Claude 模型

xmAI model ID	对应官方模型	上下文	最大输出 tokens
claude-opus-4-6	Claude Opus 4.6	1M (beta)	32K
claude-sonnet-4-6	Claude Sonnet 4.6	1M (beta)	64K
claude-3-5-sonnet-20241022	Claude Sonnet 3.5 (v2)	200K	8K
claude-3-5-haiku-20241022	Claude Haiku 3.5	200K	8K

以 /v1/models 实时返回为准。

1M 上下文说明： Opus 4.6 / Sonnet 4.6 的 1M context 为 Anthropic beta 特性，需在请求头携带 anthropic-beta: context-1m-2025-08-07；不带该 header 时默认为 200K。Claude Code 主流版本暂未自动注入该 header，长对话若需 1M 请自行通过 Proxy 注入或等待 Claude Code 原生支持。

Claude 4.7 系列尚未上架；如需新模型请在 Admin → 模型管理 提交接入请求。

Claude Code 推荐映射

在 ~/.claude/settings.json 显式指定：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.xmai.sg",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-xmai-key",
    "ANTHROPIC_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-3-5-haiku-20241022"
  }
}

变量	用途	推荐值
ANTHROPIC_MODEL	会话主模型（代码生成、多步推理）	claude-opus-4-6 或 claude-sonnet-4-6
ANTHROPIC_DEFAULT_OPUS_MODEL	opus 别名解析到的模型 ID	claude-opus-4-6
ANTHROPIC_DEFAULT_SONNET_MODEL	sonnet 别名解析到的模型 ID	claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL	haiku 别名解析到的模型 ID	claude-3-5-haiku-20241022

ANTHROPIC_SMALL_FAST_MODEL 已废弃

旧版 Claude Code 使用 ANTHROPIC_SMALL_FAST_MODEL 指定快速/低成本模型。该变量已被 ANTHROPIC_DEFAULT_HAIKU_MODEL 替代。若同时设置两者，新变量优先。

只设 BASE_URL + AUTH_TOKEN 不设 MODEL 将导致 Claude Code 请求 claude-opus-4-7 等未上架 ID 报 404。

模型 ID 与定价详见 模型列表。

验证接入

启动 Claude Code 后发一条测试消息：

/doctor

或直接让 Claude 回答一句话。然后：

1. 登录 XmAI 控制台 → 请求日志 查看是否有新记录
2. 或在 Dashboard 的 本日消费 卡片观察 credits 变化

看到新请求即接入成功。

高级配置

禁用非必要流量

通过 xmAI 等第三方代理使用时，Claude Code 仍会向 Anthropic 服务器发送遥测、自动更新检查、错误报告和反馈调查。可通过以下变量全部禁用：

{
  "env": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

在 ~/.claude/settings.json 中与其他变量一起添加即可。Claude Code 功能不受影响，仅关闭后台流量。

路由到非 Claude 模型

ANTHROPIC_DEFAULT_*_MODEL 变量接受上游支持的任意模型 ID，不限于 Claude 模型。若 xmAI 已上架其他 provider 的模型（如 Gemini、DeepSeek），可将 Claude Code 的模型槽位路由到这些模型：

{
  "env": {
    "ANTHROPIC_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gemini-2.5-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gemini-2.5-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-2.5-flash"
  }
}

功能兼容性

Claude Code 的高级功能（extended thinking、adaptive reasoning、effort levels）依赖模型 ID 匹配已知 Anthropic 模式。路由到非 Claude 模型时，这些功能可能不可用或被静默忽略。

所有可用模型 ID 见 模型列表。

常见问题

连接失败 / 证书错误

系统代理干扰： 若设置了 http_proxy / https_proxy，代理可能拦截 xmAI 流量。排除 xmAI 域名：

export NO_PROXY="api.xmai.sg"

自签名证书： 企业内网若走了自有证书链，导入 CA：

export NODE_EXTRA_CA_CERTS=/path/to/your-ca-chain.pem

切回 Anthropic 官方

删除 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN 两个环境变量（或从 settings.json 的 env 字段中移除），Claude Code 会自动回落到官方认证流程。

认证失败（401 / 403）

• 确认 Key 未被禁用 / 过期：API Keys 页面检查状态
• 确认使用的是 ANTHROPIC_AUTH_TOKEN 而非 ANTHROPIC_API_KEY
• 确认 ANTHROPIC_BASE_URL 没有多余的 /v1 后缀

账户余额不足

xmAI 按 token 实时扣费，余额不足会返回 402 或 insufficient_balance 错误。前往 钱包页面 补充额度，或开启自动充值。

相关链接

• Messages API 参考 — Anthropic 兼容 API 文档
• Chat Completions API — OpenAI 兼容 API 文档
• 模型列表 — 所有可用模型与价格
• 错误码 — 错误处理指南
• 常见问题 — FAQ
• OpenCode — 开源 Claude Code 替代
• OpenAI Codex CLI — OpenAI 官方终端 coding agent
• Gemini CLI — 局限与变通方案
• OpenAI 兼容工具 — 通用 OpenAI 兼容指南