配置 AI 工具前的检查清单
很多 AI 工具配置失败，不是因为模型不可用，而是因为几个基础字段没有对齐：key 填错位置、base_url 多了或少了 /v1、模型名不是平台真实 id、工具实际调用的 endpoint 和你以为的不一样。
这篇不是某个工具的完整教程，而是一份配置前后的检查清单。你可以配 Codex、Claude Code、OpenAI-compatible 客户端、LiteLLM、one-api、New API 或公司内部网关时都照着过一遍。
如果你还不确定“OpenAI-compatible API”到底兼容什么，可以先看 /zh/posts/what-is-openai-compatible-api。
先确认你在配置哪一层
同一个 AI 请求通常会经过几层：
- 本地工具：比如 Codex、Claude Code、编辑器插件、脚本。
- SDK 或客户端：比如 OpenAI SDK、Anthropic SDK、LangChain、LiteLLM。
- 网关或中转：比如团队 API 网关、AI 中转站、反向代理。
- 上游模型平台：比如 OpenAI、Anthropic、Google、其他模型服务。
配置时最怕把不同层的字段混在一起。一个常见例子是：工具要求填 base_url，你却填了完整的 /v1/chat/completions；或者工具要求 Anthropic endpoint，你却填了 OpenAI-compatible endpoint。
先写下三句话：
- 这个工具最终要调用哪类 API：OpenAI、Anthropic，还是平台自己的格式？
- 中间是否有网关或中转？
- key 是上游平台 key、中转站 key，还是公司内部网关 key？
这三句话不清楚，后面的错误码很容易误判。
key：确认来源、权限和存放位置
API key 最少检查四件事：
- 来源：key 来自官方平台、中转站，还是团队内部网关。
- 权限：是否允许调用目标模型，是否开启了 Responses、Chat Completions、Embeddings 等能力。
- 额度：是否有余额、订阅、项目 quota 或团队 quota。
- 存放位置：是否被工具真实读取，而不是只写在你以为会生效的
.env里。
不要把 key 写进仓库。更稳的做法是放在用户目录、系统凭据管理器、CI secret 或部署平台 secret 中。对于本地命令行工具，独立 key 文件比把密钥塞进项目 .env 更容易避免误提交。
日志里也不要打印完整 key。最低限度只保留前后几位，例如：
sk-proj-abc...xyz
如果你在排查 401，可以先验证“工具读到的 key 是哪一个”，但不要把完整值贴进 issue、群聊或截图。
base_url：只填服务根地址，不要随手拼完整路径
base_url 是 AI 工具配置里最容易出错的字段。
OpenAI-compatible API 常见地址长这样：
https://api.example.com/v1
但有些工具会自己拼 /v1，这时你应该填：
https://api.example.com
也有些中转平台会把 OpenAI 和 Anthropic 分成两个入口：
https://relay.example.com/v1
https://anthropic.relay.example.com
不要根据经验硬猜。检查工具文档里 base_url 的语义：
- 它是“API 根地址”还是“完整 endpoint”？
- 它是否要求包含
/v1？ - 它是否会自动追加
/chat/completions、/responses或/messages？ - 它是否支持 Anthropic 的
/v1/messages，还是只支持 OpenAI-compatible？
一个实用办法是用最小请求验证，而不是直接让 coding agent 改代码。先发一句 “hello”，确认网络、认证、endpoint 都通，再开始真实任务。
model：使用平台后台里的真实模型 id
模型名不是营销名称，也不一定是网页上展示的名称。配置里要填的是平台接受的 model id。
不要把这些概念混在一起：
- 模型系列：
GPT、Claude、Gemini。 - 产品名称：聊天产品、IDE 插件、订阅套餐。
- API model id：请求体里的
model字段。 - 中转站别名：中转平台自己映射出来的模型名。
如果你通过中转站调用模型，尤其要看中转站后台实际暴露的模型列表。它可能使用上游原名，也可能使用别名。别名不一定支持所有 endpoint，也不一定有同样的上下文长度、工具调用或视觉能力。
模型配置建议按用途分层：
- 默认聊天：稳定、便宜、延迟低。
- 代码修改：上下文较长，工具调用稳定。
- 复杂重构：推理能力更强，但成本和延迟可接受。
- 批量任务：便宜、可重试、输出格式稳定。
如果你在配置 coding agent，可以继续看 /zh/posts/choose-model-for-coding-agent。
endpoint：确认工具实际调用的接口
很多配置看起来都叫“OpenAI 兼容”，但实际 endpoint 不一样：
/v1/chat/completions/v1/responses/v1/completions/v1/embeddings/v1/images- Anthropic 风格的
/v1/messages
一个服务兼容 Chat Completions，不代表它兼容 Responses。一个模型能聊天，不代表它能做 embeddings。一个中转支持 Claude，不代表它能用 OpenAI SDK 直接请求。
排查时不要只看 base_url，要看最终请求路径。能打开 debug 日志的话，至少确认：
- 请求方法是
POST还是别的。 - 最终 URL 是什么。
- 请求体里的
model是什么。 - 返回的错误来自网关还是上游。
如果日志会包含 prompt、用户数据或 key，先做脱敏再共享。
代理和网络：区分本机代理、工具代理和服务端代理
代理问题常常伪装成认证或上游错误。
先分清三个位置：
- 本机代理：你的终端是否设置了
HTTP_PROXY、HTTPS_PROXY、ALL_PROXY。 - 工具代理：AI 工具自己是否有 proxy 配置。
- 服务端代理：公司网关或中转站到上游是否还要走代理。
本机能访问网页，不代表命令行工具能访问 API。浏览器可能走系统代理，终端可能没有；终端设置了代理，GUI 应用可能没有；公司网络能访问中转站，不代表中转站能访问上游。
最小检查顺序：
- 本机能否 DNS 解析目标域名。
- 本机能否建立 HTTPS 连接。
- 代理是否需要认证。
- 工具是否继承终端环境变量。
- 中转或网关是否能访问上游。
遇到 429 或 500 时，也不要忽略网络层。超时、连接复用失败、代理限流，都可能被包装成不直观的错误。常见错误码排查可以看 /zh/posts/debug-ai-api-401-429-500。
日志：打开，但先脱敏
调 AI API 时，日志要足够细，但不能裸奔。
建议记录：
- trace id 或 request id。
- 时间、工具版本、配置 profile。
- base_url 的域名和路径，但不要带 key。
- endpoint、model、状态码、错误类型。
- 输入输出 token 数，如果平台返回了 usage。
- 是否命中缓存、是否重试、重试了几次。
不要记录：
- 完整 API key。
- 用户隐私数据。
- 长 prompt 原文。
- 业务数据库内容。
- 可复现生产身份的 cookie、session、JWT。
如果必须临时打开详细日志，最好只对一个最小请求打开，并在排查结束后关闭。给别人看日志前，先搜索 sk-、Bearer、Authorization、cookie、session、token 这些关键词。
最小验证顺序
我通常按这个顺序验证：
- 用最小请求调用一个便宜模型，只让它返回一句话。
- 换成目标模型，仍然只返回一句话。
- 打开工具调用、文件读取或 agent 模式前，再跑一次短任务。
- 用一条真实但低风险的任务测试上下文长度和输出稳定性。
- 最后再放到真实项目或生产任务里。
不要一上来就让 agent 改几十个文件。配置没稳定前，复杂任务会把认证、模型、上下文、工具权限、网络和代码错误混在一起。
最后检查表
- key 是否来自正确平台，且没有放进仓库。
- key 是否有目标模型和目标 endpoint 的权限。
base_url是否按工具要求包含或不包含/v1。model是否是平台接受的真实 id。- endpoint 是否与工具协议匹配：Responses、Chat Completions、Messages 等。
- 本机代理、工具代理、服务端代理是否分清。
- 日志是否能定位请求，同时已经脱敏。
- 是否跑过最小 smoke test。
配置 AI 工具的核心不是记住某个示例，而是把 key、base_url、model、endpoint、代理、日志这几条线拆开。线拆清楚，后面的 401、429、500 才能判断到底是哪一层在出问题。