OpenAI 兼容客户端通用教程：API 地址、密钥与模型名

注意：本文默认讨论文本聊天类 OpenAI-compatible / Chat Completions 接入；图片、语音、Embedding、工具调用、Responses API 等能力要单独看客户端和平台文档。

很多 AI 客户端都支持“自定义 OpenAI API 地址”。比如 Chatbox、Cherry Studio、一些 VS Code 插件、Dify、n8n、Coze 这类工具，虽然界面不一样，但底层配置思路非常接近：填 API 地址、填 API Key、填模型名。

这篇文章不是某一个软件的逐按钮教程，而是一篇通用指南。看完后，你再去配置具体客户端时，就能知道每个输入框到底是什么意思，也能在报错时快速判断问题出在哪里。

本文以147AI的API 接口文档的快速上手流程为例：先在控制台创建令牌，再从模型广场复制模型名，然后根据客户端要求填写https://147ai.com、https://147ai.com/v1或完整接口路径。

哪些工具适合看这篇

只要你的工具里出现下面这些词，就大概率适用：

• OpenAI Compatible
• Custom OpenAI
• API Host
• Base URL
• OpenAI API Key
• Model ID
• 自定义模型供应商
• OpenAI 兼容接口

常见场景包括：

• Chatbox 这类桌面聊天客户端
• Cherry Studio 这类多模型客户端
• Dify、n8n、Coze 这类工作流平台
• 一些支持 OpenAI Base URL 的 IDE 插件
• 自己写的 OpenAI SDK 脚本

如果工具明确写的是 Anthropic、Gemini、Claude 原生接口，那就不要直接套这篇，要看对应协议文档。

开始前准备

配置前先准备好四样东西：

• 第三方 API 账号余额大于 0
• API Key / 令牌
• 模型广场复制的完整模型名
• 模型详情页显示的 API 端点

以 147API 为例，文档里的基础流程是：

注册用户 → 充值余额 → 创建令牌 → 选择模型分组 → 设置额度/期限 → 完成创建

三个必填项：地址、密钥、模型

OpenAI 兼容客户端的配置可以记成一句话：Base 跟文档，Key 跟控制台，模型跟广场。

不要把这三项混在一起。Key 不是模型名，模型名也不是分组名，Base URL 更不是完整的聊天问题。

第一步：填写 API 地址

API 地址不能只记一个固定答案。你需要先判断当前工具使用的是哪种接口格式：OpenAI 原生格式、OpenAI 兼容格式，还是 Anthropic、Gemini 这类厂商原生格式。

OpenAI 原生格式通常以https://api.openai.com/v1为基础。很多第三方 API 平台为了降低接入成本，会兼容 OpenAI 的请求格式，让你把官方地址替换成第三方地址。常见写法有：

https://147ai.com https://147ai.com/v1 https://147ai.com/v1/chat/completions

第一种场景是客户端会自动补全路径。比如 Cherry Studio、Chatbox 这类普通用户使用的 AI 客户端，通常只需要填写 Base URL、API Key 和模型名。你填：

https://147ai.com/v1

客户端会在实际请求时自动补上 /chat/completions 等它自己需要的接口路径。至于Responses API、Embedding、图片、语音等能力，要看该客户端是否支持。普通用户不需要自己写 HTTP 请求，这也是 OpenAI 兼容格式的价值：同一套配置方式可以接很多模型，使用门槛更低。

第二种场景是不会自动补全路径。比如后端服务、curl、Postman、Python/Node HTTP 客户端，你就是在直接发 HTTP 请求。这时只填https://147ai.com/v1通常不够，需要写完整接口地址。例如 OpenAI 兼容聊天接口一般写：

https://147ai.com/v1/chat/completions

对应的curl示例是：

curlhttps://147ai.com/v1/chat/completions\-H"Authorization: Bearer sk-xxxxxxxx"\-H"Content-Type: application/json"\-d'{ "model": "从模型广场复制的模型名", "messages": [ { "role": "user", "content": "你好，回复 OK" } ] }'

Anthropic 原生格式要单独看。Claude 相关工具或 Claude 原生接口常见的是/v1/messages，请求体、Header 和 OpenAI 的/v1/chat/completions不完全一样。也就是说，一个网关支持 OpenAI 兼容，不代表你就能把 Claude Code、Claude 原生 SDK 的请求直接照搬过去。

各大厂也常提供 OpenAI 兼容入口。比如一些 Google、国内大模型平台或多模型网关，会在文档里写“OpenAI Compatible”“自定义 OpenAI”“OpenAI 兼容接口”。这种兼容能让 Cherry Studio、Dify、n8n、普通 OpenAI SDK 更容易接入，但最终仍要看模型详情页：它要求你填 Base URL、完整 Endpoint，还是厂商原生接口。

判断方法可以按这个顺序：

1. 先看工具类型：普通 AI 客户端多半填 Base URL，后端 HTTP 客户端多半写完整接口地址。
2. 再看协议类型：OpenAI 兼容、Anthropic 原生、Gemini 原生不要混用。
3. 最后看模型详情页：以页面标注的 API 端点、模型名和请求格式为准。

如果你不确定，普通客户端可以先从https://147ai.com/v1开始测试；如果你在写curl或后端 HTTP 请求，就优先使用完整接口地址。

第二步：填写 API Key

把控制台生成的sk-...粘贴到 API Key 输入框。

注意几个细节：

• 不要多复制空格
• 不要只复制 Key 的前几位
• 不要把 Key 填到模型输入框
• 不要把多个 Key 放在同一个输入框里

如果客户端支持“隐藏密钥”或“本地加密保存”，建议打开。公司或团队场景里，最好给每个工具单独创建限额令牌，方便后续撤销和统计费用。

第三步：填写模型名

模型名一定从模型广场复制。不要用文章里的示例名当成最终配置，也不要把模型展示标题当成模型 ID。

新手建议这样做：

1. 先选一个轻量模型。
2. 复制完整模型名。
3. 在客户端里手动添加模型。
4. 发送短问题测试。
5. 成功后再换正式模型。

如果客户端有“自动拉取模型列表”功能，可以先试；如果拉取失败，就手动填模型名。

第四步：发送最小测试

如果客户端提供 Verify / Check / 测试连接按钮，先点击测试；如果没有，就用短问题测试返回，并到 147API 控制台查看调用记录、余额变化或日志确认。

工作流平台怎么理解

Dify、n8n、Coze 这类平台和桌面客户端不一样，它们通常不是只提供聊天框，而是把模型放进工作流节点里。但配置思路仍然一样。

你通常会在“模型供应商”或“LLM Provider”里看到：

• OpenAI
• OpenAI Compatible
• Custom Model Provider
• 自定义 API

配置时仍然填：

• Base URL
• API Key
• Model

区别在于，工作流平台还会让你设置：

• 最大 token
• temperature
• 超时时间
• 重试次数
• 输入输出变量

这些参数通常不是鉴权或 Base URL 问题，但设置不合理也会导致请求失败。排查时先用默认参数和短输入测通，再逐步调整 max token、超时、流式输出等设置。
工作流平台还要确认当前节点或模型供应商是否支持自定义 Base URL / OpenAI Compatible；如果内置节点不支持，可以考虑 HTTP Request、自定义供应商或对应插件。

多模态能力不要混测

147API 文档里把 OpenAI、Anthropic、Google、豆包、图片、音频、视频等接口分开展示。这说明不同能力可能走不同接口、不同请求体、不同分组。

所以不要这样测试：

• 在纯文本聊天客户端里测试图片编辑
• 在普通 OpenAI Chat 配置里测试 TTS
• 在不支持视频接口的软件里测试视频生成

更稳的做法是：

1. 先确认该客户端支持什么能力。
2. 再看文档中该能力属于哪个接口。
3. 最后确认令牌分组是否支持该模型或能力。

文本聊天跑通，不代表图片、音频、视频也会自动跑通。

常见问题与排查

Q1：401 或 403

认证失败。检查：

1. Key 是否完整。
2. Key 是否填错位置。
3. 账户余额是否大于 0。
4. 令牌分组是否支持该模型。
5. 客户端是否保存了旧 Key。

Q2：404

通常是地址路径不对。尝试在这几种写法之间切换：

https://147ai.com https://147ai.com/v1 https://147ai.com/v1/chat/completions

但不要盲目乱试。最好回模型详情页看端点，再结合客户端输入框说明判断。

Q3：模型不存在

去模型广场复制完整模型名。不要手写，不要改大小写，不要漏掉中横线。

Q4：能回复文本，但图片或语音不行

这通常不是 Key 的问题，而是接口能力不匹配。看客户端是否支持对应能力，再看文档里该能力的接口格式。

Q5：同一个 Key 在 A 软件能用，B 软件不能用

多数是 Base URL 填法不同。A 软件可能要求/v1，B 软件可能自动拼接路径，导致你多填了一层。

把两个软件的配置项截图放在一起比对，重点看 API 地址和模型名。

Q6：回答慢或经常失败

可能原因包括：

• 模型较慢
• 分组资源不稳定
• 网络代理问题
• 上下文太长
• 客户端超时设置太短

先用短问题测试，再逐步加长输入。

推荐的使用习惯

每个工具单独建 Key

不要所有软件共用一个 Key。更建议：

• Chatbox 一个 Key
• Cherry Studio 一个 Key
• Dify 一个 Key
• n8n 一个 Key
• 测试脚本一个 Key

这样能看清费用，也方便出问题时单独停用。

先测试轻量模型

配置阶段只看链路是否通，不看最终效果。先用低成本模型测通，再切换高质量模型。

记录可用配置

建议把可公开的信息记下来：

Base URL: https://147ai.com/v1 Model: 从模型广场复制的模型名 Client: Chatbox / Cherry Studio / Dify

不要记录真实 Key。需要记录时只写前几位和用途，例如sk-abc... / Chatbox 测试用。

总结

OpenAI 兼容客户端看起来很多，但底层配置都绕不开三件事：API 地址、API Key、模型名。只要这三项来源清楚，大多数客户端都能按同一套方法接入。

遇到问题时也按这个顺序排查：先看 Key，再看 Base URL，最后看模型名和分组。文本聊天跑通后，再去测试多模态、工作流和复杂开发任务。