在AI编程工具中使用自定义API

本文演示如何在 Claude Code、Codex、Gemini CLI 中接入自定义 API（例如你自己的中转服务）。

将文中的 https://your-relay.example.com 和 cr_xxxxxxxxxx 替换为你的实际地址与密钥。

Claude Code

1. 安装 Claude Code
   # 1) 安装 Node.js LTS（任选其一）
   winget install OpenJS.NodeJS.LTS
   # 或 choco install nodejs
   
   # 2) 安装 Claude Code
   npm install -g @anthropic-ai/claude-code
   
   # 3) 验证
   claude --version

   # 1) 安装 Node.js（示例：Homebrew）
   brew install node
   
   # 2) 安装 Claude Code
   npm install -g @anthropic-ai/claude-code
   
   # 3) 验证
   claude --version

   # 1) 安装 Node.js（Ubuntu/Debian 示例）
   curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
   sudo apt-get install -y nodejs
   
   # 2) 安装 Claude Code
   npm install -g @anthropic-ai/claude-code
   
   # 3) 验证
   claude --version

2. 配置自定义 API（两种方式）
   建议先清理冲突环境变量（如 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL），避免覆盖配置文件中的值。

   1. 编辑或新增 settings.json，新增或修改其中的 env 字段。

   • Windows：%USERPROFILE%\\.claude\\settings.json
   • macOS：~/.claude/settings.json
   • Linux：~/.claude/settings.json

   {
     "env": {
       "ANTHROPIC_AUTH_TOKEN": "cr_xxxxxxxxxx",
       "ANTHROPIC_BASE_URL": "https://your-relay.example.com",
       "API_TIMEOUT_MS": "3000000",
       "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
     }
   }

   2. 再编辑或新增 .claude.json，新增 hasCompletedOnboarding 参数。

   • Windows：%USERPROFILE%\\.claude.json
   • macOS：~/.claude.json
   • Linux：~/.claude.json

   {
     "hasCompletedOnboarding": true
   }

   3. 注意：请将 cr_xxxxxxxxxx 替换为真实 API Key。环境变量 ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_BASE_URL 的优先级高于配置文件。

   1. 安装 cc-switch（按系统选择一种方式）。

      • Windows：从 cc-switch Releases 下载并安装。
      • macOS：使用 Homebrew 安装（命令见下一步）。
      • Linux：从 cc-switch Releases 下载并安装。

   2. 如果你是 macOS，执行以下命令安装 cc-switch。

   brew tap farion1231/ccswitch
   brew install --cask cc-switch
   brew upgrade --cask cc-switch

   3. 打开 cc-switch，点击右上角 + 新增供应商。
   4. 供应商选择 自定义API，填写你的 Base URL 与 API Key。
   5. 模型名称填写为 gpt-5.3-codex。
   6. 启用配置后，确认 .claude.json 包含以下内容。
      • Windows：%USERPROFILE%\\.claude.json
      • macOS：~/.claude.json
      • Linux：~/.claude.json

   {
     "hasCompletedOnboarding": true
   }

3. 启动并验证

   claude

   如果能正常进入 CLI 并完成一次对话，说明配置已生效。

Codex

1. 安装 Codex
   # 1) 安装 Node.js LTS
   winget install OpenJS.NodeJS.LTS
   
   # 2) 安装 Codex
   npm install -g @openai/codex
   
   # 3) 验证
   codex --version

   # 方式一：npm
   npm install -g @openai/codex
   
   # 方式二：Homebrew
   brew install --cask codex
   
   # 验证
   codex --version

   # 1) 安装 Node.js（示例）
   curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
   sudo apt-get install -y nodejs
   
   # 2) 安装 Codex
   npm install -g @openai/codex
   
   # 3) 验证
   codex --version

2. 配置自定义 API
   在 %USERPROFILE%\.codex\config.toml 写入：

   model_provider = "crs"
   model = "gpt-5.1-codex-max"
   model_reasoning_effort = "high"
   disable_response_storage = true
   preferred_auth_method = "apikey"
   
   [model_providers.crs]
   name = "crs"
   base_url = "https://your-relay.example.com/openai"
   wire_api = "responses"
   requires_openai_auth = true

   然后在 %USERPROFILE%\.codex\auth.json 写入：

   {
     "OPENAI_API_KEY": null
   }

   💡 将 OPENAI_API_KEY 保持为 null，并设置环境变量 CRS_OAI_KEY 为你的 API 密钥（例如 cr_xxxxxxxxxx）。

   在 ~/.codex/config.toml 写入：

   model_provider = "crs"
   model = "gpt-5.1-codex-max"
   model_reasoning_effort = "high"
   disable_response_storage = true
   preferred_auth_method = "apikey"
   
   [model_providers.crs]
   name = "crs"
   base_url = "https://your-relay.example.com/openai"
   wire_api = "responses"
   requires_openai_auth = true

   然后在 ~/.codex/auth.json 写入：

   {
     "OPENAI_API_KEY": null
   }

   💡 将 OPENAI_API_KEY 保持为 null，并设置环境变量 CRS_OAI_KEY 为你的 API 密钥（例如 cr_xxxxxxxxxx）。

   在 ~/.codex/config.toml 写入：

   model_provider = "crs"
   model = "gpt-5.1-codex-max"
   model_reasoning_effort = "high"
   disable_response_storage = true
   preferred_auth_method = "apikey"
   
   [model_providers.crs]
   name = "crs"
   base_url = "https://your-relay.example.com/openai"
   wire_api = "responses"
   requires_openai_auth = true

   然后在 ~/.codex/auth.json 写入：

   {
     "OPENAI_API_KEY": null
   }

   💡 将 OPENAI_API_KEY 保持为 null，并设置环境变量 CRS_OAI_KEY 为你的 API 密钥（例如 cr_xxxxxxxxxx）。

3. 启动并验证
   # 提醒：将示例值改为你的真实 CRS API Key（格式如 cr_xxxxxxxxxx）
   $env:CRS_OAI_KEY = "cr_xxxxxxxxxx"
   codex -c model_provider="crs"

   # 提醒：将示例值改为你的真实 CRS API Key（格式如 cr_xxxxxxxxxx）
   export CRS_OAI_KEY="cr_xxxxxxxxxx"
   codex -c model_provider="crs"

   # 提醒：将示例值改为你的真实 CRS API Key（格式如 cr_xxxxxxxxxx）
   export CRS_OAI_KEY="cr_xxxxxxxxxx"
   codex -c model_provider="crs"

   若命令能进入交互界面并成功响应，说明配置可用。

Gemini Cli

1. 安装 Gemini CLI
   # 1) 安装 Node.js LTS
   winget install OpenJS.NodeJS.LTS
   
   # 2) 安装 Gemini CLI
   npm install -g @google/gemini-cli
   
   # 3) 验证
   gemini --version

   # 方式一：npm
   npm install -g @google/gemini-cli
   
   # 方式二：Homebrew
   brew install gemini-cli
   
   # 验证
   gemini --version

   # 通过 npm 安装
   npm install -g @google/gemini-cli
   
   # 验证
   gemini --version

2. 配置自定义 API
   推荐方式（Code Assist 兼容）：

   $env:CODE_ASSIST_ENDPOINT = "https://your-relay.example.com/gemini"
   $env:GOOGLE_CLOUD_ACCESS_TOKEN = "cr_xxxxxxxxxx"
   $env:GOOGLE_GENAI_USE_GCA = "true"
   $env:GEMINI_MODEL = "gemini-2.5-pro"

   备用方式（Gemini API 兼容）：

   $env:GOOGLE_GEMINI_BASE_URL = "https://your-relay.example.com/gemini"
   $env:GEMINI_API_KEY = "cr_xxxxxxxxxx"
   $env:GEMINI_MODEL = "gemini-2.5-pro"

   推荐方式（Code Assist 兼容）：

   export CODE_ASSIST_ENDPOINT="https://your-relay.example.com/gemini"
   export GOOGLE_CLOUD_ACCESS_TOKEN="cr_xxxxxxxxxx"
   export GOOGLE_GENAI_USE_GCA="true"
   export GEMINI_MODEL="gemini-2.5-pro"

   备用方式（Gemini API 兼容）：

   export GOOGLE_GEMINI_BASE_URL="https://your-relay.example.com/gemini"
   export GEMINI_API_KEY="cr_xxxxxxxxxx"
   export GEMINI_MODEL="gemini-2.5-pro"

   推荐方式（Code Assist 兼容）：

   export CODE_ASSIST_ENDPOINT="https://your-relay.example.com/gemini"
   export GOOGLE_CLOUD_ACCESS_TOKEN="cr_xxxxxxxxxx"
   export GOOGLE_GENAI_USE_GCA="true"
   export GEMINI_MODEL="gemini-2.5-pro"

   备用方式（Gemini API 兼容）：

   export GOOGLE_GEMINI_BASE_URL="https://your-relay.example.com/gemini"
   export GEMINI_API_KEY="cr_xxxxxxxxxx"
   export GEMINI_MODEL="gemini-2.5-pro"

3. 启动并验证

   gemini

   如果首次启动进入认证流程，按你所选方案完成认证即可。

常见问题

先执行 npm config get prefix，确认全局安装目录；然后把该目录加入 PATH，重开 PowerShell。

检查 %USERPROFILE%\.claude\settings.json 是否为合法 JSON，并确认没有遗留 ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL 环境变量覆盖配置。

以当前用户放开执行策略：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser。

如果你通过 Nginx 反向代理，请在 http 块启用 underscores_in_headers on;，避免下划线请求头被丢弃。

如果遇到 {"error":{"message":"No available OpenAI accounts support the requested model: gpt-5.3-codex"}}，直接发送 继续，即可继续生成。

优先改用用户目录前缀安装，不建议长期使用 sudo npm -g。也可改用 Homebrew 安装 CLI。

zsh 用户改 ~/.zshrc，bash 用户改 ~/.bash_profile 或 ~/.bashrc，保存后 source 对应文件。

优先检查 ~/.claude/settings.json 与 ~/.claude.json 是否存在且格式正确；同时确认未设置会覆盖配置文件的 ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL。

检查 ~/.codex/config.toml 的 base_url 是否包含正确前缀（例如 /openai），并确认当前终端已设置 CRS_OAI_KEY 后再执行 codex -c model_provider=\"crs\"。

如果遇到 {"error":{"message":"No available OpenAI accounts support the requested model: gpt-5.3-codex"}}，直接发送 继续，即可继续生成。

gemini-cli 需要较新的 Node（官方文档要求 Node.js 20+）。先 node -v，不足则升级后重装。

确认 npm 全局 bin 目录（如 ~/.npm-global/bin）已加入 PATH，然后重新打开终端。

优先检查服务器连通性、反向代理配置和防火墙；必要时用 curl 先验证中转地址可达。

如果历史认证缓存影响流程，删除 ~/.gemini/settings.json 后重新执行 gemini。

如果遇到 {"error":{"message":"No available OpenAI accounts support the requested model: gpt-5.3-codex"}}，直接发送 继续，即可继续生成。

参考资料

• Claude Relay Service README
• pincc.ai Claude Code 安装
• MiniMax Claude Code（含 cc-switch）
• OpenAI Codex CLI README
• Google Gemini CLI README