连接指南

AI API Relay 使用教程

将 OpenAI、Claude、Grok 模型接入你常用的 AI 工具。先判断协议，再选择配置写入方式。

OpenAI 兼容 Chat Completions / Responses

https://apiserver.aiapirelay.com/v1

Anthropic 原生 Claude Code

https://apiserver.aiapirelay.com

最容易出错的一点

OpenAI 兼容客户端填写带 /v1 的地址；Claude Code 的 ANTHROPIC_BASE_URL 使用不带 /v1 的根地址。

1
创建 Key
在 AI API Relay 控制台创建并保管 API Key。
2
选择配置方式
CC Switch、Codex++，或手动填写 Base URL。
3
选择目标工具
Claude Code、Codex、OpenClaw、WorkBuddy，或直接调用 API。
4
发送最小请求
先用一个短问题验证连接，再开始正式任务。

配置方式

先决定如何写入配置

下面三项解决的是“怎样把地址、Key 和模型写进目标工具”，并不负责执行 AI 任务。

配置方式	适合场景	平台	写入目标
CC Switch	图形化管理多个供应商	Windows / macOS / Linux	Claude Code、Codex CLI、OpenClaw
Codex++	集中管理 Codex Desktop 供应商	Windows / macOS	Codex Desktop
手动 Base URL	完全控制配置或直接开发调用	视目标工具而定	全部目标工具与 SDK

角色边界

CC Switch 和 Codex++ 是配置管理工具；WorkBuddy 是会实际调用模型完成任务的 AI 工具。

配置管理器 · Windows / macOS / Linux

使用 CC Switch 写入配置

CC Switch 管理多个供应商，并把配置写入 Claude Code、Codex CLI 或 OpenClaw。

下载 CC Switch

CC Switch 供应商管理主界面 — CC Switch 官方仓库中文主界面截图

安装并打开
从 Releases 下载对应系统版本。首次打开后选择要管理的目标工具标签。
添加自定义供应商
点击右上角添加按钮，选择自定义配置，名称可填 AI API Relay。
填写协议地址
Claude Code 填根地址；Codex CLI 和 OpenClaw 填带 /v1 的 OpenAI 兼容地址。
保存并启用
填写 API Key 与需要的模型 ID，保存后将该供应商设为当前使用。
重启目标工具
若目标进程已经运行，请完全退出再打开，避免它继续使用启动时读取的旧配置。

验证方式

在目标 AI 工具里发送“仅回复 OK”。请求成功即表示 CC Switch 写入的配置已被目标工具读取。

配置管理器 · Windows / macOS

使用 Codex++ 管理 Codex Desktop

Codex++ 是供应商配置与启动管理工具，目标客户端是 Codex Desktop。

下载 Codex++

Linux 暂不可用

Codex++ 当前官方发布 Windows 和 macOS 安装包，没有官方 Linux 客户端。

进入供应商管理
安装并打开 Codex++，新建供应商，选择“纯 API”模式。
选择 Responses
协议选择 Responses，Base URL 填 https://apiserver.aiapirelay.com/v1。
填写凭据与模型
输入 API Key 和中转站提供的模型 ID，然后运行 Provider Doctor 或模型测试。
激活配置
测试通过后保存并启用，再通过 Codex++ 的入口启动 Codex Desktop。

不是独立 AI 工具

Codex++ 修改和管理 Codex 配置；真正发起请求、执行任务的是 Codex Desktop。

配置方式

手动配置 Base URL

无需额外管理器，直接使用目标工具提供的环境变量、配置文件或自定义模型界面。

Claude CodeAnthropic 原生https://apiserver.aiapirelay.com

其他兼容工具OpenAI 兼容https://apiserver.aiapirelay.com/v1

手动方式适合需要审阅每一项配置、自动化部署，或使用 Python、Node.js、cURL 直接调用的场景。下面的目标工具章节给出可直接修改的示例。

本地配置工具

生成你的连接配置

先选择写入配置的方式，再选择实际使用模型的 AI 工具或调用方式。

配置方式 CC Switch 和 Codex++ 负责管理、写入配置，并不是 AI 客户端。

目标 AI 工具

操作系统

Windows macOS Linux

模型 ID

API Key

仅在当前页面内存中使用，刷新后清除，不会上传。

请输入 API Key

目标 AI 工具 · Windows / macOS / Linux

Claude Code

Claude Code 使用 Anthropic 原生协议。设置两个环境变量后，在同一终端启动 claude。

Windows PowerShell

PowerShell

$env:ANTHROPIC_BASE_URL = 'https://apiserver.aiapirelay.com'
$env:ANTHROPIC_AUTH_TOKEN = 'YOUR_API_KEY'
claude

macOS / Linux

Shell

export ANTHROPIC_BASE_URL='https://apiserver.aiapirelay.com'
export ANTHROPIC_AUTH_TOKEN='YOUR_API_KEY'
claude

会话范围

上面的变量只对当前终端会话生效。要长期使用，请写入你信任的系统凭据方案，不要把真实 Key 提交到代码仓库。

目标 AI 工具

Codex CLI 与 Codex Desktop

两者共享用户级 Codex 配置。自定义供应商必须写到用户目录的 ~/.codex/config.toml。

Codex CLIWindows / macOS / Linux

Codex DesktopWindows / macOS

1A. Codex CLI：在启动终端设置 Key

Windows PowerShell

$env:AI_API_RELAY_KEY = 'YOUR_API_KEY'

macOS / Linux Shell

export AI_API_RELAY_KEY='YOUR_API_KEY'

1B. Codex Desktop：写入 GUI 会话可读取的 Key

Windows PowerShell · 用户环境

setx.exe AI_API_RELAY_KEY 'YOUR_API_KEY'

macOS · 当前登录会话

launchctl setenv AI_API_RELAY_KEY 'YOUR_API_KEY'

Windows 会持久化 Key

setx.exe 会将 Key 以明文写入当前用户的 HKCU\Environment。不再使用时，请运行 [Environment]::SetEnvironmentVariable('AI_API_RELAY_KEY', $null, 'User') 删除。

2. 编辑用户级配置

TOML · ~/.codex/config.toml

model = "YOUR_MODEL_ID"
model_provider = "ai_api_relay"

[model_providers.ai_api_relay]
name = "AI API Relay"
base_url = "https://apiserver.aiapirelay.com/v1"
env_key = "AI_API_RELAY_KEY"
wire_api = "responses"

不要写到项目级配置

项目目录中的 .codex/config.toml 会忽略 Provider 与凭据相关字段。请使用用户级 ~/.codex/config.toml。

保存后，从设置 Key 的同一终端启动 Codex CLI。Codex Desktop 必须完全退出并重新打开；macOS 重新登录后如环境变量失效，请再次运行 launchctl setenv。参考 Codex 高级配置文档。

目标 AI 工具 · Windows / macOS / Linux

OpenClaw

OpenClaw 是实际运行 Agent 的工具。AI API Relay 作为自定义 OpenAI 兼容供应商加入其模型配置。

OpenClaw 官网

安装

macOS / Linux

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

Windows PowerShell

powershell -c "irm https://openclaw.ai/install.ps1 | iex"

配置自定义供应商

JSON5 · ~/.openclaw/openclaw.json

{
  agents: {
    defaults: { model: { primary: "ai-api-relay/YOUR_MODEL_ID" } },
  },
  models: {
    mode: "merge",
    providers: {
      "ai-api-relay": {
        baseUrl: "https://apiserver.aiapirelay.com/v1",
        apiKey: "YOUR_API_KEY",
        api: "openai-completions",
        models: [{ id: "YOUR_MODEL_ID", name: "YOUR_MODEL_ID" }],
      },
    },
  },
}

保存后重启 OpenClaw Gateway，再在模型列表中选择 ai-api-relay/YOUR_MODEL_ID。

目标 AI 工具 · Windows / macOS

WorkBuddy

WorkBuddy 是腾讯提供的 AI Agent 工作工具，通过“自定义模型”界面直接连接中转站。

下载 WorkBuddy

Linux 暂不可用

WorkBuddy 当前提供 Windows 和 macOS 客户端，没有官方 Linux 客户端。

打开模型设置
进入“设置 → 模型”，点击“添加模型”，供应商选择“自定义 / Custom”。
填写连接信息
URL 填 https://apiserver.aiapirelay.com/v1，再输入 API Key 与模型 ID。
保持自定义协议关闭
让 WorkBuddy 自动在 Base URL 后补全 /chat/completions。
保存并测试
选择新模型，发送一个短问题确认响应。

与 Codex++ 的区别

WorkBuddy 自己执行 AI 任务；Codex++ 只管理并写入 Codex 的供应商配置。

直接 API 调用

Python、Node.js 与 cURL

下面都使用 OpenAI 兼容的 Chat Completions 接口。将占位符替换为控制台中的 Key 和模型 ID。

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://apiserver.aiapirelay.com/v1",
)

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "请回复：连接成功"}],
)
print(response.choices[0].message.content)

Node.js

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://apiserver.aiapirelay.com/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_ID",
  messages: [{ role: "user", content: "请回复：连接成功" }],
});
console.log(response.choices[0].message.content);

cURL

Shell

curl 'https://apiserver.aiapirelay.com/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "请回复：连接成功"}]
  }'

故障排查

先看状态码，再看协议

遇到连接问题时，从最小请求开始，不要同时修改地址、模型与客户端配置。

401 Unauthorized / 未授权

确认 Key 完整、没有多余空格，并使用 Authorization: Bearer ...。Claude Code 使用 ANTHROPIC_AUTH_TOKEN。

404 Not Found

OpenAI 兼容客户端的 Base URL 应包含 /v1；不要把完整的 /chat/completions 路径重复填进会自动补路径的客户端。

MODEL model not found

模型 ID 必须与中转站控制台显示的标识完全一致，区分大小写，不要使用展示名称代替 ID。

协议 Responses 与 Chat Completions 不匹配

Codex 自定义供应商使用 wire_api = "responses"；OpenClaw 和常规 SDK 示例使用 Chat Completions。

缓存修改后仍使用旧地址

完全退出目标 AI 工具及其后台进程，再从已设置环境变量的终端重新启动。仅刷新窗口可能不会重新读取配置。

最小验证清单

Base URL 与目标协议匹配 Key 没有被引号或空格截断模型 ID 来自中转站控制台目标工具已完全重启