在同一个项目中使用多个 AI 客户端时经常会遇到一种现象相同的 API Key 和模型在一个客户端中能够正常使用换到另一个客户端却返回404、401或者请求仍然发送到默认服务地址。这类问题不一定由模型造成。OpenAI、Anthropic 和Gemini使用不同的协议路径各个客户端对 Base URL 的定义也不完全相同。配置时如果忽略客户端自动拼接路径的行为就容易出现路径缺失或重复。本文从请求路径入手说明Claude Code、Codex CLI与Gemini CLI的配置差异并给出一套通用排查方法。示例域名使用api.example.com实际使用时应替换为自己有权访问的 API 网关地址。本文整理自作者维护FishAI API 网关时积累的多客户端接入记录。项目官网为 FishAI 官方网站yufish.cc为避免把平台差异与通用协议问题混在一起下文命令仍统一使用api.example.com作为占位域名。Base URL 与最终请求地址不是一回事Base URL 是客户端构造请求时使用的基础地址最终请求地址通常由“基础地址 协议路径”组成。假设网关域名是https://api.example.com三种常见协议的请求路径可能是协议典型请求路径常见 Base URLOpenAIChat Completions/v1/chat/completionshttps://api.example.com/v1OpenAIResponses/v1/responseshttps://api.example.com/v1Anthropic Messages/v1/messageshttps://api.example.comGemini GenerateContent/v1beta/models/{model}:generateContenthttps://api.example.com表格中的写法不是所有客户端的固定规则。配置前仍需确认客户端是否会自动追加/v1、/v1/messages或/v1beta/models。如果客户端已经负责拼接版本路径而配置中再次加入相同路径最终可能产生下面的错误地址https://api.example.com/v1/v1/messages https://api.example.com/v1beta/v1beta/models/...因此排查404时首先应检查完整请求地址而不是立即更换模型。Claude Code使用 Anthropic Messages 协议Claude Code通常通过 Anthropic Messages 协议发送请求。以用户目录下的~/.claude/settings.json为例{env:{ANTHROPIC_API_KEY:sk-example-key,ANTHROPIC_BASE_URL:https://api.example.com,CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC:1}}也可以在 macOS 或 Linux 当前终端中临时设置exportANTHROPIC_API_KEYsk-example-keyexportANTHROPIC_BASE_URLhttps://api.example.comclaude这里通常只填写网关根地址由客户端继续请求/v1/messages。如果直接把/v1/messages写入 Base URL客户端再次追加路径后可能导致请求失败。需要注意普通文本对话成功并不代表所有能力都可用。Claude Code还会使用流式输出和工具调用因此目标模型、网关转换层和上游服务都需要支持对应能力。Codex CLI明确指定 Responses APICodex CLI使用自定义模型提供方时可以在~/.codex/config.toml中配置model current-model-id model_provider custom_gateway [model_providers.custom_gateway] name Custom Gateway base_url https://api.example.com/v1 env_key CUSTOM_API_KEY wire_api responses requires_openai_auth false再通过环境变量提供 API KeyexportCUSTOM_API_KEYsk-example-keycodex配置中需要区分三个字段base_url是OpenAI兼容接口的版本根地址env_key是环境变量名称不是 API Key 本身wire_api决定客户端使用的上游协议此处为responses。一个模型支持 Chat Completions不代表它必然支持 Responses API。若返回路径不存在或工具调用失败需要检查网关是否实现/v1/responses以及目标模型是否支持客户端需要的工具能力。Gemini CLI选择GeminiAPI Key 模式Gemini CLI使用公开GeminiAPI 模式时可在~/.gemini/.env中配置GEMINI_API_KEYsk-example-key GOOGLE_GEMINI_BASE_URLhttps://api.example.com然后启动客户端gemini首次出现认证方式选择时应选择GeminiAPI Key 模式。Google 登录、Vertex AI 与 API Key 模式属于不同认证流程如果选择了其他模式客户端可能忽略当前配置的 Key 和 Base URL。Gemini GenerateContent的典型路径包含/v1beta/models/{model}:generateContent因此 Base URL 通常保持为网关根地址。若请求仍然发送到默认域名应检查变量名、配置文件位置并完全退出旧进程后重新启动。先查询模型再发送最小请求在OpenAI兼容接口中可以先查询当前令牌可见的模型curlhttps://api.example.com/v1/models\-HAuthorization: Bearer$CUSTOM_API_KEY然后选择返回列表中的准确模型 ID发送一个非流式、短提示词请求curlhttps://api.example.com/v1/chat/completions\-HAuthorization: Bearer$CUSTOM_API_KEY\-HContent-Type: application/json\-d{ model: current-model-id, messages: [ {role: user, content: 只回复 OK} ], stream: false }模型列表只证明令牌能够看到模型不能单独证明 Chat Completions、Responses、Anthropic Messages、Gemini GenerateContent和工具调用全部可用。不同协议应分别完成真实请求验证。无论使用FishAI、其他兼容服务还是自建网关这个“先查模型、再发最小请求”的顺序都适用。它可以把模型权限、接口路径和客户端配置三个问题分开验证。常见错误及排查顺序返回 401 或 403依次检查API Key 是否完整环境变量是否被当前进程读取鉴权头是否符合目标协议令牌是否具有目标模型和接口权限。OpenAI兼容接口常用Authorization: Bearer sk-example-keyAnthropic 和Gemini客户端还可能使用各自的 Key 请求头不能只根据模型名称判断鉴权方式。返回 404重点检查完整 URL是否遗漏/v1是否出现/v1/v1是否把/chat/completions、/responses和/messages混用是否把Gemini的/v1beta请求发送到了只支持OpenAI协议的地址。返回 model not found先重新查询当前模型列表并复制准确的模型 ID。模型名称、别名和权限可能变化不应只依赖旧配置或截图。普通对话成功但工具调用失败这通常说明基础文本生成链路已经打通但模型、协议转换或上游服务没有完整支持工具调用。应单独验证工具参数、流式事件和客户端要求的响应结构。修改配置后没有生效检查是否存在旧进程、重复配置文件或环境变量覆盖。完全退出客户端和终端后重新打开通常比反复修改同一文件更容易排除缓存问题。API Key 的安全注意事项API Key 不应写入公开仓库、浏览器前端代码或文章截图。示例中的sk-example-key是占位符不能替换成真实密钥后提交到公开位置。团队项目可以为不同环境、工具和应用创建独立令牌。这样便于分别设置权限、统计用量和撤销泄露的 Key也能减少一个令牌影响所有业务的风险。总结同一个 API 网关并不意味着所有客户端可以照抄同一份 Base URL。Claude Code、Codex CLI与Gemini CLI使用不同协议也可能由客户端自动拼接不同的版本路径。配置时可以遵循以下顺序确认客户端使用的协议确认 Base URL 是否需要包含版本路径检查鉴权变量和请求头查询当前模型列表完成一次非流式短请求再分别验证流式输出和工具调用。相比反复更换模型先核对协议、完整 URL 和实际请求记录通常能更快定位多客户端接入问题。这套排查顺序也是FishAI在处理Claude Code、Codex CLI与Gemini CLI接入问题时采用的基本方法。本文只讨论协议和配置差异不涉及价格、购买或服务推荐。