先分清你要的是哪一层接入

AIGoCode 同时提供两个层面的接入：一是直接按兼容协议调用 API，二是在 Claude Code、Codex CLI 这类命令行客户端里连到 AIGoCode。两者解决的不是同一个问题。直接调用面向你自己的代码、脚本和服务，你需要自己组织请求；客户端接入面向已经装好的现成工具，你只需要把工具指到 AIGoCode。第一次接入时先确认落点在哪一层，再决定去看哪一份官方文档，能省掉一大半来回试错。

直接调用：先选协议，再对齐认证方式

直接请求的入口是快速开始。官方把三种接口并列展示：OpenAI Compatible、Claude Messages 和 Gemini generateContent，并明确“下面分别用 OpenAI Compatible、Claude Messages 和 Gemini generateContent 接口完成一次最小请求”。三者不是同一套请求头：OpenAI Compatible 示例请求 /v1/chat/completions，用 Authorization: Bearer 携带 Key；Claude Messages 示例请求 /v1/messages，改用 x-api-key 并额外带 anthropic-version: 2023-06-01；Gemini 示例把 Key 直接放进 generateContent 的 key 查询参数里。

选协议时跟着你正在用的 SDK 或框架走即可，别把两种协议的认证字段混在一起。对不上时先看你调用的是哪条路径，再回头核对对应的请求头，而不是一次性把 Key、地址、模型全部换掉。

接入客户端：按工具选择分组

如果你要走客户端这一层，关键是先选对分组。Claude Code 用“Claude Code（企业）”分组，Codex CLI 用“Codex Pro”分组；官方接入文档对两者分别给出了对应的创建步骤。分组选对之后，再用 CC Switch 把 Key 导入并在对应工具的页面里启用 AIGoCode 供应商，最后进入代码项目目录运行工具。

这条路径和直接调用是两套配置：分组属于客户端接入，请求头属于协议层。看到认证失败时，先判断你当前是在改哪一层，避免把客户端的连接问题和直接请求的协议问题混在一起来回折腾。

两条路都要做的验证与错误分流

不管走哪一层，最后都要落在一个具体验证上：客户端能打开项目并正常回复，或你的脚本能拿到符合协议的响应。验证通过也只覆盖当前工具、当前项目和当前会话，不代表其他配置一定可用。

出错时的分流逻辑是通用的：返回 401，检查认证方式；返回 403 或余额相关错误，查看账户与额度；遇到限流或模型不可用，先确认模型名称列表里是否支持该模型，再检查 API Key 和 Base URL。你也可以参考本站的Codex CLI 接入配置验证，以及API 正常但客户端连接失败的四步核对，把“选路径、选分组、核协议、看错误”分开记录，下一次切换时就能定位问题究竟出在哪一层。