客户端接入 - GPT-Load

绝大多数客户端只要改两处：把地址指向 GPT-Load，把密钥换成访问密钥。

通用规则§

不管什么客户端，要改的都是这两样：

接口地址——改成 http://127.0.0.1:3001（加不加 /v1 取决于客户端的习惯，见下面各例）
密钥——换成管理台里创建的访问密钥，不是上游服务商的密钥

认证方式按客户端原本的习惯来，网关都认：Authorization: Bearer、x-api-key、x-goog-api-key，以及 Gemini 的 key 查询参数。

模型名要对得上

请求里的模型名，必须在这把访问密钥能用的某个分组里已经开放。提示模型不存在时，先去分组的模型标签页确认，见分组与渠道。

让管理台生成配置§

不用自己拼——管理台首页可以直接生成各客户端的接入参数：选一把访问密钥，选目标客户端，配置片段就出来了，复制即可。

管理台首页的一键生成配置区域，显示访问密钥、客户端列表和配置片段 — FIG. 1 — 一键生成配置选密钥与客户端

OpenAI SDK§

官方 SDK 只改两行：

Python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:3001/v1",   # 改这行
    api_key="你的访问密钥",          # 改这行
)

resp = client.chat.completions.create(
    model="你的模型名",
    messages=[{"role": "user", "content": "你好"}],
)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:3001/v1",
  apiKey: "你的访问密钥",
});

环境变量方式同样可行：设置 OPENAI_BASE_URL 与 OPENAI_API_KEY，代码就完全不用动。

Anthropic SDK§

Python

from anthropic import Anthropic

client = Anthropic(
    base_url="http://127.0.0.1:3001",   # 注意：不带 /v1
    api_key="你的访问密钥",
)

Anthropic 客户端走 /v1/messages，SDK 会自己拼上这段路径，所以 base_url 填到根即可。

Claude Code§

用环境变量指向网关：

终端里设置后再启动

export ANTHROPIC_BASE_URL="http://127.0.0.1:3001"
export ANTHROPIC_AUTH_TOKEN="你的访问密钥"
export ANTHROPIC_MODEL="YOUR_MODEL"
export ANTHROPIC_CUSTOM_MODEL_OPTION="$ANTHROPIC_MODEL"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"

claude

将 YOUR_MODEL 替换为这把访问密钥可用的模型 ID，并在同一 Shell 中启动或重启 Claude Code。该模型会用于启动，也会加入 /model 的自定义选项；自动发现仅额外列出 ID 含 claude 或 anthropic 的模型（不区分大小写）。

要长期生效就写进 shell 配置文件。这把访问密钥需要勾选 Anthropic Messages 协议。

Codex CLI§

管理台首页选择 Codex 后会生成配置文件和环境变量。模型发现只返回当前访问密钥可用、且具有 Responses 生成路由的模型；下面是文本接入示例。

~/.codex/config.toml

model = "YOUR_MODEL"
model_provider = "gpt-load"

[model_providers.gpt-load]
name = "OpenAI"
base_url = "http://127.0.0.1:3001/v1"
model_catalog_url = "http://127.0.0.1:3001/v1/models"
env_key = "GPT_LOAD_API_KEY"
wire_api = "responses"
supports_websockets = true

[features]
api_key_model_discovery = true

在启动客户端的环境中设置

export GPT_LOAD_API_KEY="YOUR_ACCESS_KEY"

将 YOUR_MODEL 替换为已开放的模型，合并配置后重新启动客户端。模型发现参数需客户端支持；以当前管理台生成的配置为准。

可在模型页选择 Codex 展示的模型并排序，操作见 Codex 模型目录。

会话内切换思考等级

使用支持该功能的 Codex CLI 时，可用以下命令启用会话内思考等级更新。所选模型也需支持 configuration_update；GPT-Load 会保留更新及原有缓存语义，能否命中缓存仍由上游决定。

启用客户端实验功能

codex --enable reasoning_effort_override

此开关由客户端版本决定；模型目录中的等级展示不代表模型支持会话内更新。

Codex 实时语音：客户端配置、直连与中继部署 →

Codex 要的是 Responses，不是 Chat Completions

这把访问密钥必须勾选 OpenAI Responses 协议。 Codex 用的是 Responses 接口，只勾了 Chat Completions 会被直接拒绝—— 路由检查里会看到 protocol_filtered。

别和订阅账号搞混

这里说的是把 Codex 客户端接到网关。如果你想接的是「Codex 订阅账号作为上游」，那是另一件事，见订阅账号。

Gemini CLI§

环境变量方式

export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:3001"
export GEMINI_API_KEY="你的访问密钥"

Gemini 客户端走 /v1beta/models/…，访问密钥需要勾选 Gemini 协议。

桌面客户端§

Cherry Studio、NextChat、Open WebUI、Cline 这类图形客户端，通常在设置里有「自定义 API 地址」和「API Key」两个输入框，填法一致：

API 地址：http://127.0.0.1:3001/v1
API Key：你的访问密钥
模型：填分组里开放的模型名；有些客户端支持点「获取模型列表」自动拉取

具体到某个客户端的截图步骤，用管理台的一键生成更快—— 它会给出那个客户端对应的准确字段。

CC Switch 的余额查询可使用通用模板和访问密钥，Base URL 填网关根地址或 /v1 均可。返回的是访问密钥总成本限额的美元估算余额，不是上游账户余额；周期限额不参与，没有总限额时 total 和 balance 均为 0。

接不上时§

按这个顺序排查，多数问题在前两步就能定位：

先用 curl 验证网关本身——排除客户端配置问题：

最小验证

curl http://127.0.0.1:3001/v1/chat/completions \
  -H "Authorization: Bearer 你的访问密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"你的模型名","messages":[{"role":"user","content":"hi"}]}'

curl 通了但客户端不通——多半是地址末尾的 /v1 多了或少了，或者协议没在访问密钥里勾选
提示模型不存在——去分组的模型标签页确认该模型已开放
请求发出去但失败——用监控与排障里的请求日志看具体原因，路由检查能展示候选分组和当前可用凭据数量