客户端接入

绝大多数支持「自定义 API 地址」的客户端都能直接接入——把地址换成 APIGOTO,密钥换成你的 API Key 即可。本页收录常见客户端的具体配置,以及那个最容易踩的 /v1 后缀问题。

先记住 Base URL 规则

APIGOTO 的兼容端点全部挂在 /v1 下。填 Base URL 时要不要带 /v1, 取决于客户端自己会不会拼——这是接入失败最常见的原因,没有之一。

客户端类型填这个为什么
OpenAI 官方 SDK、多数三方应用 https://www.apigoto.com/v1 它们把 Base URL 与 /chat/completions 直接拼接
Anthropic 官方 SDK、Claude Code https://www.apigoto.com SDK 内部自带 /v1/messages 前缀,再填就成了 /v1/v1/messages
🩺
怎么判断自己填错了

返回 404 或路径里出现重复的 v1,就是拼接问题。 返回 40001 则是鉴权头的问题,跟 Base URL 无关——见 鉴权与 API Key

命令行工具

Claude Code

用环境变量指向 APIGOTO,其余用法完全不变:

~/.zshrc
# 注意不带 /v1,Claude Code 自己会拼 /v1/messages
export ANTHROPIC_BASE_URL="https://www.apigoto.com"
# 必须用 AUTH_TOKEN(发 Authorization: Bearer),不是 ANTHROPIC_API_KEY
export ANTHROPIC_AUTH_TOKEN="sk-rouertcode-xxxxxxxx"
⚠️
别用 ANTHROPIC_API_KEY

那个变量会让客户端发 x-api-key 头,而网关的兼容端点只读 Authorization: Bearer,结果是稳定的 40001。 两个变量都设了也不行——按客户端实现,API_KEY 通常优先。 接入前先 unset ANTHROPIC_API_KEY

Codex CLI

Codex 走 /v1/responses,Base URL 带 /v1

shell
export OPENAI_BASE_URL="https://www.apigoto.com/v1"
export OPENAI_API_KEY="sk-rouertcode-xxxxxxxx"

若你的版本使用配置文件(~/.codex/config.toml)而非环境变量, 把其中的 base_url 改成同一个地址即可。

桌面 / Web 应用

Cherry Studio、LobeChat、NextChat、ChatBox、Open WebUI 这类应用都提供 「OpenAI 兼容」供应商配置,填法一致:

配置项填写
供应商类型OpenAI / OpenAI 兼容 / Custom
API 地址 / Base URLhttps://www.apigoto.com/v1
API Keysk-rouertcode-…
模型手动填 model_id,见 模型、准入与回退
💡
「获取模型列表」按钮点了没反应?

这些客户端拉取模型用的是 OpenAI 的 GET /v1/models, APIGOTO 的模型清单走的是平台接口 GET /api/v1/user/user/models,两者不通用。 手动把模型 ID 填进去即可,不影响正常对话。

Cursor

Settings → Models → OpenAI API Key 里打开 Override OpenAI Base URL, 填 https://www.apigoto.com/v1,密钥填 API Key,然后手动添加模型名。

⚠️
部分 IDE 的补全功能不走自定义地址

Cursor / Copilot 这类工具的行内补全常常是走官方专用通道的, 改 Base URL 只对聊天面板生效。这是客户端的设计,不是接入失败。

开发框架

langchain.py
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="claude-sonnet-5",
    base_url="https://www.apigoto.com/v1",
    api_key=os.environ["APIGOTO_API_KEY"],
)
print(llm.invoke("你好").content)

Dify / n8n / Coze 这类平台

在模型供应商里选 OpenAI-API-compatible, API endpoint 填 https://www.apigoto.com/v1, 再按平台要求补上模型的上下文长度与最大输出长度即可。

接入不通时的排查顺序

先用 curl 打通

客户端配置项多、报错信息糊。先按 快速开始 里的 curl 跑一次, 确认密钥和网络没问题,再回头调客户端。

看 HTTP 状态码分流

404 → Base URL 的 /v1 拼错了;401 → 鉴权头形式不对; 403 → 计费或准入门槛;429 → 限流;502/504 → 上游侧。

核对模型 ID

50201 no available upstream for this model 基本都是模型名写错。 去 模型列表核对。

查调用日志

后台的调用日志会记录每次请求的模型、协议、来源应用与错误码。 日志里没有记录说明请求根本没到网关——那是地址或网络问题。

🏷️
网关会自动识别来源应用

网关按 User-Agent 识别常见客户端(Claude Code、Codex CLI、Cursor、Trae、VSCode 等), 结果记进调用日志,方便你按应用维度对账。识别不出的记为 unknown不影响调用。走平台原生端点时可以用 Rc-App-Id 显式指定,见 协议与端点选择