外接兼容与 Base URL 说明

本页是 UseGoodAI 外接兼容的总入口，用来统一判断第三方客户端、Agent 工具、配置切换器和自定义 OpenAI-compatible 客户端应该走哪种接入方式。

核心结论：支持 Responses 的客户端，优先按 Responses 接入；只有普通 OpenAI-compatible 客户端需要手动配置时，才走兼容模式并填写 https://api.usegoodai.com/v1。

如果后台、客户端教程或 CC Switch 已经生成配置，直接使用生成内容，不要自己额外补 /v1，也不要把 /chat/completions、/responses 手动拼进 Base URL。

适用场景

以下情况建议先看本页，再看对应客户端教程：

• 第三方客户端要求填写 Base URL、API Key、Model。
• Codex、Hermes、OpenClaw 等 Agent / CLI 工具需要接入 UseGoodAI。
• Cherry Studio、Open WebUI、LibreChat 等普通 OpenAI-compatible 客户端需要手动配置。
• JetBrains、Trae、无限画布等客户端需要配置自定义 OpenAI-compatible provider。
• 使用 CC Switch 管理多个客户端配置，不确定该用已有配置模板还是自定义地址。
• 客户端报错、后台没有调用记录，或不确定当前请求走的是 Responses 还是普通兼容模式。

接入前先确认

开始配置前，先确认这几项：

项目	需要确认什么
配置来源	是后台生成配置、配置工具生成内容，还是客户端里手动填写
接入协议	客户端是否明确支持 Responses；不支持时再看是否支持 OpenAI-compatible
Base URL	生成配置按生成内容；普通 OpenAI-compatible 手动配置才填 /v1 地址
API Key	使用 UseGoodAI 后台创建的 Key，不要混用其它站点或旧配置
模型名	以 UseGoodAI 后台当前分组显示的可用模型为准

如果这些信息对不上，常见结果是：

• 客户端能保存配置，但发送消息失败。
• 后台没有调用记录，说明请求可能没有打到 UseGoodAI。
• 报 401 Unauthorized、404 Not Found、405 Method Not Allowed 或连接失败。
• 模型列表为空，或填了模型名但实际不可用。

按接入类型填写

接入类型	优先协议	Base URL / 地址写法	说明
后台生成配置	按后台生成配置	按后台生成配置	直接复制生成结果，不要手动改地址或补 /v1
CC Switch / 配置工具	按工具生成内容	按工具生成内容	只使用明确来自 UseGoodAI 后台或当前教程的配置；不要套用其它站点的配置模板
支持 Responses 的客户端	Responses	按后台生成配置	Codex 等支持 Responses 的工具优先走 Responses，不要降级成普通兼容模式
普通 OpenAI-compatible 客户端	OpenAI-compatible / Chat Completions	https://api.usegoodai.com/v1	适合 Cherry Studio、Open WebUI、LibreChat 等只能手动填 OpenAI-compatible 地址的客户端
客户端要求完整接口地址	按客户端说明	按客户端说明填写完整路径	这不是常规 Base URL 场景，只有客户端明确要求完整接口时才这样填

判断方法

能用后台生成配置，就先用后台生成配置；客户端明确支持 Responses，就优先 Responses；只有客户端只提供普通 OpenAI-compatible 手动配置入口时，才填写 https://api.usegoodai.com/v1。

通用接入流程

第一步：优先获取生成配置

先看 UseGoodAI 后台或当前客户端教程是否提供生成配置。生成配置通常已经包含正确的协议、地址和必要字段，复制后不要再手动补 /v1。

如果使用 CC Switch，只使用明确来自 UseGoodAI 后台或当前教程的配置。不要照搬其它站点的配置模板，也不要在现成模板基础上随意改地址。

第二步：确认客户端是否支持 Responses

如果客户端支持 Responses，并且当前教程或后台配置也按 Responses 提供，优先走 Responses。

Responses 和普通 OpenAI-compatible 不是同一个接入层。支持 Responses 的工具通常会使用 /v1/responses，请求体和输出结构也不同；不要只因为看到 OpenAI-compatible 字样，就把它改成普通 /v1 兼容模式。

第三步：普通兼容客户端再手动填 /v1

只有客户端要求你手动填写 OpenAI-compatible Base URL 时，才填写：

https://api.usegoodai.com/v1

这类客户端通常会自己在 Base URL 后面拼接 /chat/completions、/models 等路径，所以不要把完整接口路径写进 Base URL。

第四步：填写 API Key 和模型名

API Key 从 UseGoodAI 后台复制。模型名以后台当前分组显示的可用模型为准，不要照抄其它教程里的模型名。

如果客户端允许手动添加模型，建议先填一个后台明确可用的模型；确认能正常调用后，再增加其它模型。

第五步：发送测试并看后台记录

配置完成后，在客户端发送一句简单测试，例如：

你好，请回复一句话。

如果后台出现调用记录，说明请求已经到达 UseGoodAI。后续问题再按模型、分组、客户端功能继续排查。

如果后台没有记录，优先检查客户端当前配置是否真的生效、CC Switch 是否已应用到目标客户端、Base URL 是否填在正确位置。

常见错误

所有场景都填 https://api.usegoodai.com/v1

不要这样理解。https://api.usegoodai.com/v1 只适合普通 OpenAI-compatible 客户端手动配置。

后台生成配置、CC Switch 等配置工具和 Responses 接入都应按生成内容填写。

把完整接口写进 Base URL

普通客户端的 Base URL 不要写成：

https://api.usegoodai.com/v1/chat/completions

也不要自己猜成：

https://api.usegoodai.com/v1/responses

除非客户端明确要求填写完整接口地址，否则 Base URL 只填到对应根地址。普通 OpenAI-compatible 手动配置时填到 /v1 即可。

支持 Responses 却改成普通兼容模式

Codex 这类支持 Responses 的工具，优先使用后台生成的 Responses 配置。改成普通 OpenAI-compatible 兼容模式后，可能导致协议字段、工具调用、上下文状态或输出解析不符合客户端预期。

后台生成配置后又手动补 /v1

生成配置已经包含当前接入方式需要的地址。复制后再额外补 /v1，可能会变成重复路径或错误路径。

CC Switch 里只有其它站点配置模板

不同站点的协议、Base URL、模型名和请求处理可能不同。接 UseGoodAI 时不要套用其它站点的配置模板；按目标客户端是否支持 Responses 或普通 OpenAI-compatible 来配置。

客户端报错但后台没有记录

这通常说明请求没有真正发到 UseGoodAI。优先检查：

• 当前客户端是否正在使用你刚保存的配置。
• CC Switch 是否已经切换并应用到目标客户端。
• Base URL 是否填在 API 地址位置，而不是后台页面地址或其它配置项。
• 终端环境变量、旧配置文件或客户端缓存是否覆盖了新配置。

401 Unauthorized

优先检查 API Key 是否复制完整、是否仍有效、是否来自 UseGoodAI 后台。也要确认客户端没有被旧 OAuth 登录状态或旧环境变量覆盖。

更多排查见 报错与踩坑。

扩展页面怎么选

页面	适合谁
外接兼容与 Base URL 说明	不确定 Base URL、协议和 /v1 怎么填
Responses 与兼容模式	想理解 Responses 和 Chat Completions 的区别
User-Agent 说明	客户端要求填写或排查 UA 时
生图 API	自己写脚本或接口调用图片生成
Codex 进阶用法	Codex 已跑通，想学习高级工作流
Codex 周边工具	想了解 Git、ripgrep、MCPHub、Superpowers 等工具

连接失败或路径错误

如果报连接失败、404、405，优先检查是否把 Base URL 和完整接口路径混在一起填写。

更多排查见 报错与踩坑。