Gate.AI Claude Code CLI 网关接入设置

Gate.AI 支持将 Claude Code CLI 连接至兼容 Anthropic 协议的网关，开发者可通过 Gate.AI API Key 和支持的 Claude 模型 ID，在终端环境下运行 AI 编程工作流。此功能适用于希望通过 Gate.AI 路由 Claude Code 请求，而非仅使用 Anthropic 官方通道的开发者。本文档将详细介绍 Gate.AI Claude Code CLI 的接入流程、接口验证、模型配置及常见问题排查，不涉及 Claude Desktop、Cursor 或 Codex 的配置。

内容依据：Gate.AI 官方文档及 Claude Code 文档，截止 2026年6月。

前置条件

• 已注册 Gate.AI 账号，并拥有 API Key 及充足余额。
• 可在 macOS、Linux 或 WSL 环境访问 Claude Code CLI。

完成本指南后你将获得哪些能力？

完成 gate.ai claude code 设置后，你可以在项目目录下启动 Claude Code，并通过 https://api.gate.ai/anthropic 路由 Claude Code 请求。

本指南涵盖推荐的用户级 settings.json 配置、接口连通性测试，以及 401、404、认证冲突、超时、npm 安装等常见问题的解决方法。

• 如需更广泛的 API 网关集成，请参考 Gate.AI API 集成指南。
• 如需 IDE 相关配置，请参考 Gate.AI Cursor 配置指南。

步骤一：创建 Gate.AI API Key

请先创建 Gate.AI Key，因为 Claude Code 需依赖该密钥后续配置 Base URL 和模型。

操作方法：

1. 登录 Gate.AI。
2. 进入 Dashboard → API Keys。
3. 新建 API Key。
4. 复制以 sk-or-v1- 开头的密钥。
5. 确认账户余额充足。

请勿将真实密钥粘贴至公开仓库、问题追踪、共享截图或已提交的项目文件中。

步骤二：检测网关连通性

在安装或配置 Claude Code 之前，先测试 Anthropic 兼容接口，以便将密钥或网络问题与 CLI 配置问题区分开。

将 YOUR_GATEAI_API_KEY 替换为你的真实 Gate.AI 密钥：

export GATEAI_API_KEY="YOUR_GATEAI_API_KEY"
curl -s -o /dev/null -w "%{http_code}" \
  -H "x-api-key: $GATEAI_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"anthropic/claude-sonnet-4.6","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
  https://api.gate.ai/anthropic/v1/messages

你应看到如下结果之一：

关键要点：Claude Code 需使用兼容 Anthropic 协议的 Gate.AI 路由，而非通用的 https://api.gate.ai/v1 路径。

步骤三：安装 Claude Code CLI

在 Gate.AI 网关测试通过后再安装 Claude Code CLI，后续仅需本地 CLI 配置。

推荐安装方式（macOS、Linux 或 WSL）：

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

npm 方式安装：

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

安装后，验证命令可用性：

claude --version

如终端提示 command not found: claude，请重启终端并确认安装目录已加入 PATH。

步骤四：配置 Claude Code 相关设置

在 ~/.claude/settings.json 中配置 Gate.AI 的 Anthropic Base URL、API Key 和模型 ID。

如需所有项目均统一使用 Gate.AI Claude Code，可采用用户级设置：

mkdir -p ~/.claude
cat > ~/.claude/settings.json <<'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.gate.ai/anthropic",
    "ANTHROPIC_API_KEY": "YOUR_GATEAI_API_KEY",
    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-4.6"
  },
  "includeCoAuthoredBy": false
}
EOF

随后清理可能与 Gate.AI API Key 冲突的旧 Anthropic 或代理会话：

claude /logout 2>/dev/null || true
unset ANTHROPIC_AUTH_TOKEN

建议统一存储凭证。如 ~/.zshrc、~/.bashrc 或其他 shell 配置文件中仍有 ANTHROPIC_AUTH_TOKEN 或重复的 ANTHROPIC_API_KEY，请注释重复项并重启终端。

步骤五：在项目中验证 Claude Code

在你希望使用 AI 编程辅助的项目目录下启动 Claude Code。

运行：

cd YOUR_PROJECT_DIRECTORY
claude

Claude Code 启动后，执行：

Plain / status

请确认 Base URL 为 https://api.gate.ai/anthropic，认证方式为 ANTHROPIC_API_KEY。随后可发送测试提示：

In one sentence, describe this repository.

如返回正常结果且无认证、路由或模型错误，说明 Claude Code 已通过 Gate.AI 成功请求。

正确配置应是什么样？一览表

以下表格可用于快速核查 gate.ai claude code 配置：

最常见错误是将 Claude Code 配置 URL 与原始 API 请求 URL 混用。Claude Code 应使用 Base URL，curl 验证则需完整 /v1/messages 路径。

哪些 Base URL 是错误的？

错误的 Base URL 通常会导致 404 错误或请求路由至错误协议。

Claude Code 需使用 Anthropic 路径，OpenAI 路径仅供 OpenAI 兼容工具使用。

Claude Code 无法正常工作？排查清单

• 症状：Claude Code 显示 Auth conflict: Both a token and an API key are set
  • 原因：ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 均被激活
  • 解决：运行 claude /logout，取消设置 ANTHROPIC_AUTH_TOKEN，仅保留 ANTHROPIC_API_KEY
• 症状：Claude Code 返回 401 或认证失败
  • 原因：Gate.AI 密钥错误、过期、未导出或被其他 shell 配置覆盖
  • 解决：重新从 Dashboard → API Keys 复制密钥，并用 echo $ANTHROPIC_API_KEY 确认当前值
• 症状：Claude Code 返回 404
  • 原因：Base URL 使用了 OpenAI 路由或完整请求路径
  • 解决：将 Claude Code 设置为 https://api.gate.ai/anthropic，勿用 /openai/v1、/v1 或 /anthropic/v1/messages
• 症状：接口测试超时
  • 原因：本地网络、DNS、代理或防火墙阻断请求
  • 解决：尝试更换网络、检查 DNS，并在更改 Claude Code 设置前重试 curl
• 症状：npm 安装出现 ETIMEDOUT 或 ECONNRESET
  • 原因：npm 源连接不稳定，与 Gate.AI 网关无关
  • 解决：使用镜像源重试：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

如 npm 安装出现权限错误，请配置用户级 npm prefix，避免使用不安全的提权安装。

后续可配置或集成的内容

完成 Gate.AI Claude Code 配置后，可进一步拓展开发者工作流：

• 参考 Gate.AI API 集成指南，连接 OpenAI 兼容 SDK 及标准 API 工作流。
• 如团队需在 Cursor 中使用 Gate.AI 模型，可参考 Gate.AI Cursor 配置指南。
• 检查 Gate.AI 当前模型目录后，为 Sonnet、Opus 或 Haiku 等不同档位添加明确模型 ID。

常见问题解答

Claude Code 可以用 https://api.gate.ai/openai/v1 吗？
不能。Claude Code 必须使用兼容 Anthropic 协议的 Gate.AI Base URL：https://api.gate.ai/anthropic。OpenAI 路径仅供 OpenAI 风格工具、SDK 和接口使用。

为什么 /models 返回 200，但 Claude Code 仍然失败？
模型列表接口返回 200 并不能证明当前密钥适用于 Claude Code。请务必用兼容 Anthropic 的 /anthropic/v1/messages 进行 curl 检查，因为该测试会发送带认证的消息请求。

Gate.AI API Key 应存于 shell 变量还是 settings.json？
建议二选一，避免重复。对于本地稳定配置，用户级 ~/.claude/settings.json 更易于审计；临时会话可用 shell 变量。

Claude Code 可以将模型设置为 auto 吗？
建议先使用明确的 Gate.AI 模型 ID，如 anthropic/claude-sonnet-4.6。如 Gate.AI 已开启自动路由且你的环境支持，可测试 auto，如遇路由错误请切回明确模型 ID。