我把反复踩过的 AI API 配置坑，整理成了 80 多篇中文教程

sleep alone130

329人浏览 · 2026-08-12 19:41:54

sleep alone130 · 2026-08-12 19:41:54 发布

最开始，我并没有打算做一个教程库。

只是每换一个 AI 工具，我都要重新找一遍配置方法：Cherry Studio 的 API 地址填到哪里，Codex CLI 为什么读不到 Key，Claude Code 应该使用哪一种协议，Cursor 明明连接成功了，Agent 功能为什么还是不能正常工作。

更麻烦的是，搜索出来的答案经常只有一句“填入 Base URL 和 API Key 即可”。真正开始配置后，问题才刚刚出现。

有人把完整接口地址填进 Base URL，客户端又自动拼接了一遍路径，最后得到 404；有人看到接口返回 401，就不断更换 Key，其实问题是认证头没有按工具要求发送；还有人只测试了一次普通对话，就以为所有能力都兼容，等到使用流式输出、工具调用或 Embedding 时才发现不是一回事。

这些问题我自己遇到过，也反复帮别人排查过。回答得多了以后，我发现真正缺少的不是又一篇“复制这段配置”的文章，而是一套能重复使用的判断方法。

于是，我开始把零散笔记整理成文档。

一开始只有 Codex CLI、Claude Code、Cursor、Cherry Studio 等几个常用工具。后来逐渐加入 Chatbox、Dify、Ollama、Open WebUI、LangChain、LlamaIndex、Apifox 和 Postman。再往后，文档扩展到聊天客户端、AI 编程工具、本地模型、自部署知识库、自动化工作流、SDK、Agent 框架以及 API 测试。

现在，这个仓库已经整理了 80 多篇中文文档，覆盖 70 多款工具、平台和开发框架。

但我认为最有价值的并不是数量，而是整理过程中逐渐形成的几条规则。

第一，先确认协议，再填写地址。

“支持自定义 API”并不是一个足够准确的结论。不同工具可能需要 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages。一个接口能完成普通聊天，不代表它一定能支持 Codex CLI，也不代表工具调用、图片输入和 Embedding 都能工作。

因此，每篇教程都应该先回答三个问题：这个工具需要什么协议，Base URL 应该填写到哪一级，模型 ID 从哪里确认。把这三个问题弄清楚，很多 404 和“连接成功但无法使用”的问题会自然消失。

第二，不要一上来就测试复杂任务。

我现在更习惯按固定顺序验证：

1. 先确认客户端或命令行工具能够读取配置；
2. 再请求模型列表，或者发送最小文本请求；
3. 确认普通非流式响应正常；
4. 然后测试 SSE 流式输出；
5. 最后再测试工具调用、长上下文、图片或知识库。

如果第一步都没有通过，就没有必要反复修改 Agent 提示词。如果普通文本正常而流式失败，排查范围也会立刻缩小。

第三，状态码不是答案，但它能告诉我们先查哪里。

401 通常先检查 Key、认证头和环境变量是否生效；404 优先检查 Base URL、请求路径和接口协议；429 要看限流、并发和重试策略；5xx 则需要区分偶发故障、请求超时和负载问题。

遇到错误后立刻换 Key、换模型、换客户端，往往会把一个变量变成四个变量，最后更难定位。

第四，配置教程必须写清楚边界。

例如，某个编辑器允许填写自定义模型，并不等于它的全部内置功能都会走这个接口；某个服务兼容 Chat Completions，也不意味着 Responses API 的事件格式完全一致；本地部署的服务能够监听局域网地址，也不代表应该直接暴露到公网。

教程如果只写“成功截图”，读者很容易把一次成功理解成完整兼容。因此，我后来会在文档里单独写首次验证、安全提醒、已知限制和常见错误，而不是只给一段配置。

整理这些内容之后，我自己查问题的方式也变了。