换完「中转 / 第三方接入」后，常见第一反应是盯着客户端红字：401、404、卡住、空回复。
本文只做一件事：把「改 Base URL」变成可复现清单。偏实操清单。
适用场景
- 客户端或脚本支持「自定义接口 / OpenAI 兼容」
- 已拿到 Base URL、API Key、可用模型名
- 目标：先让最小请求跑通，再放回日常客户端
免责声明
下文涉及中转 / 第三方接入 / Base URL，非官方说明，含个人服务与排错经验；字段名以客户端为准。方法可独立复现。勿公开暴露完整 Key。
1. 改之前：记下「原三件套」
动手前原样抄下当前能用的配置：
- 原 Base URL（有没有
/v1、末尾有没有/） - 原 API Key（公开场合只记前后几位对照，勿贴全码）
- 原模型名（客户端里实际填写的那一串）
另记：客户端名与版本、是否开代理 / VPN。改错最怕回退不了——多半记不清原来多了斜杠还是少了 /v1。
2. 通用步骤：找到自定义接口并保存
逻辑各家差不多：
- 打开设置 / Preferences / API / Provider
- 找到 自定义 Base URL / Custom Endpoint / OpenAI Compatible
- 填入服务方给的 Base URL（先按文档原样填，勿先加减
/v1） - 粘贴 API Key，检查首尾空格与换行
- 选择或填写该接入方清单内的模型名
- 保存 / Apply；部分工具需完全退出再开
原则：一次只改一类变量：Base URL → 模型名 → 代理/超时/并发。混着改，401 时分不清哪一刀。
3. 最小自测：先 curl，再放回客户端
客户端 UI 常吞错误细节，建议先终端做最小请求。
占位符示例（替换 YOUR_BASE / YOUR_KEY / model-name；勿公开真实域名或 Key）：
curl -sS -D - -o /tmp/llm_body.json \
"YOUR_BASE/v1/chat/completions" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "model-name",
"messages": [{"role":"user","content":"ping"}],
"max_tokens": 16
}'
只看：状态码、是否有内容、耗时是否异常长。
curl 通、客户端不通 → 多半自动拼路径、缓存旧 Key、或忽略模型名。
curl 不通 → 别反复点客户端，按下表对照。
文档有的给根地址、有的已带
/v1；客户端是否自动补/v1不一致——404 重灾区。
4. 报错速查表
| 现象 | 先查这两条 |
|---|---|
| 401 | ① Key 是否整段、有无空格/换行、是否过期或贴错环境；② Base URL 与鉴权头是否匹配（如是否需要 Bearer） |
| 404 | ① 多写或少写 /v1、末尾斜杠与客户端自动拼接冲突；② 路径是否误写成非 /chat/completions |
| 超时/转圈 | ① DNS、系统代理、公司防火墙；② 用 curl 区分「连不上」还是「连上了但首字极慢」 |
| 429 | ① 多窗口/多 Agent/重试风暴导致并发打满；② 控制台额度或速率触顶，先降并发 |
| 空回复 | ① 模型名近似写错或已下线别名；② max_tokens 过小，或客户端覆盖了系统提示 |
补充：流式中断可先关 stream；偶发成败优先查是否多套 Base URL / 多 Key 混用。
5. 多客户端注意点（原则性）
CLI / Agent 类（如 Claude Code）
配置常在环境变量或项目文件；改完确认当前 shell / 工作区读到新值。Agent 自动重试会放大 429/超时——先单次手动请求，再开 Agent。
IDE 内嵌对话（如 Cursor）
除全局 Base URL，可能还有「按模型覆盖」；改一处不等于处处生效。同时开官方与自定义通道时，确认当前会话实际走哪条。
其他 OpenAI 兼容客户端
核对三件事：是否自动追加 /v1、Authorization 格式、模型名自由输入还是下拉映射。脚本用环境变量注入 Key，勿写入可分享仓库。
共性：调试期只留一套配置，跑通再复制。
6. 安全与回滚
Key 当密码（不发群、不截全码）；能设日限额就设；改前保留原三件套以便回滚；重要自动化与个人试验通道尽量隔离。
7. 结尾
若已按清单走完：用掘金站内私信发「报错截图 + 客户端名」（Key 打码、注明 curl 通/不通），我按步骤帮你对到哪一环。文内不留站外联系方式；方法可自行复现。
（非官方、含个人服务经验；第三方接入请自行评估可用性与合规。）
