完成标准

先确认走通，再按现象排障

不要只看「配置已保存」。按「端点 → 客户端 → 控制台记录」三层确认。Codex 报 capacity、Claude 多写 /v1、Gemini 未信任目录、Harness 填成 Responses、CC Switch 没点启用，优先看对应教程页。

验证配置

下面这张清单用来判断「是不是已经接到本站」。工具专属问题，回到对应教程。

使用隐藏输入测试 Key，/v1/models 返回 200 完全退出并重启客户端，且新建了会话客户端能完成一句最小回答控制台“使用记录”出现对应密钥和模型

Terminal

read -s GEILI_KEY
curl -sS https://sub.geiliapi.com/v1/models \
  -H "Authorization: Bearer $GEILI_KEY"
unset GEILI_KEY

到 API Key: 提示时用鼠标右键粘贴；只出现一个 * 说明 Ctrl+V 没有粘贴成功。

PowerShell

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$secure = Read-Host "API Key" -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
$key = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr) -replace '[\x00-\x1F\x7F\s]', ''
[Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
if ($key.Length -lt 20) { "只读到 $($key.Length) 个字符：这个窗口里 Ctrl+V 不会粘贴，请用鼠标右键粘贴 Key 后重新运行。" } else { Invoke-RestMethod https://sub.geiliapi.com/v1/models -Headers @{Authorization="Bearer $key"} }

最小请求也会产生少量用量。建议只让客户端“回复 OK”，确认后到“使用记录”核对，不要用长上下文作为第一次测试。

常见故障排查

先记录完整报错、发生时间、HTTP 状态码、Request ID / Cloudflare Ray ID，再按下面顺序处理。不要截图或发送完整 API Key。

首先处理：Selected model is at capacity. Please try a different model.

这通常是 OpenAI 上游模型容量不足，不是本机 JSON、API Key 格式或提示词写错。OpenAI 的公开状态记录中曾出现同一报错同时影响多个模型；Plus 或 Pro 订阅也不代表永远不会遇到容量波动。它一般是随机、短时出现。

先在当前会话发送“继续”，让客户端重新发起请求。
仍然失败就新建会话，再重新发送或 dispatch 当前任务，避免旧会话持续命中同一条失败链路。
如果你的本站账号有 Pro 分组权限，可临时切换到 Pro 分组；成功出字后再切回原分组。这里的“Pro 分组”是本站路由分组，不等同于 ChatGPT Pro 订阅。
切换到另一款当前可用模型，稍后再切回原模型。

若多个会话、多个模型和不同分组持续出现同一错误，请记录发生时间和 Request ID，并查看 OpenAI Status；状态页正常但本站仍持续失败时，再联系本站支持排查路由。

4xx

先检查客户端、请求与账号

优先自查

4xx 通常表示请求已经到达入口，但请求格式、鉴权、路径、载荷、频率或账号条件不满足。先按“处理方式”修正；最小请求仍可稳定复现时，再带证据联系支持。

状态码	常见含义	处理方式
`400`Bad Request	JSON 语法、字段名、模型名或参数组合不符合目标接口要求。	先用最小请求重试；检查逗号、引号、字段拼写和客户端所用协议。
`401`Unauthorized	没有携带 API Key、Bearer 头格式错误，或客户端实际读取了另一把 Key。	用隐藏输入命令验证同一把 Key，并确认 `Authorization: Bearer <KEY>`。
`403`Forbidden	凭据已识别但被拒绝，常见于 Key 被禁用或过期、分组无权限、额度条件或 IP 限制。	到控制台核对 Key 状态、余额、分组、模型权限和 IP 白名单；无效 Key 也可能返回 401。
`404`Not Found	Base URL 或接口路径错误，或所选协议没有该接口。	Codex / Grok CLI / DeepSeek Harness 使用 `/v1` Base URL；Claude、Gemini 使用文档给出的根地址。GPT Image 2 与 Grok 生图生视频必须打 `https://image-direct.geiliapi.com/v1`，并使用对应分组 Key，见 GPT Image 2 生图与 Grok 生图 / 生视频。
`413`Payload Too Large	文字、图片、附件或历史上下文超过入口或模型可接收的大小。	新建会话，减少图片和附件，压缩上下文；最小请求也返回 413 时记录 Ray ID 联系支持。
`429`Rate Limit	请求过快、并发过高、账号或上游限流、队列拥堵，也可能是可用额度不足。	指数退避后重试，降低并发并检查余额；持续发生时提供时间、模型、分组和 Request ID。

5xx / Cloudflare

服务端、网关或上游异常

可以联系支持

这类错误通常不是用户请求格式造成。先间隔数十秒重试一次或临时切换模型；持续出现时请携带发生时间、模型、Request ID / Ray ID 和 Key 前后各 4 位联系支持。

状态码	常见含义	处理方式
`500`Internal Server Error	本站应用或内部依赖处理请求时发生未预期错误。	重试一次；持续出现时联系支持，不要反复提交可能扣费的同一任务。
`502`Bad Gateway	网关没有收到有效上游响应，可能是本站路由、上游连接或模型服务异常。	临时切换模型；持续出现时联系支持。
`503`Service Unavailable	服务维护、过载、排队，或当前没有可用上游路由。	稍后重试或切换模型；持续出现时联系支持。
`504`Gateway Timeout	网关等待应用或模型推理响应超时，长上下文和复杂任务更容易触发。	减少上下文后重试或切换模型，并把请求发生时间提供给支持。
`522`Connection Timed Out	Cloudflare 无法与本站源站建立连接，可能是源站不可达、过载或网络故障。	保存 Cloudflare Ray ID 并联系支持。
`524`A Timeout Occurred	Cloudflare 已连接本站源站，但源站在等待窗口内没有返回 HTTP 响应。	生图或生视频请改走 `https://image-direct.geiliapi.com/v1`，见 GPT Image 2 生图与 Grok 生图 / 生视频。其它请求保存 Ray ID、发生时间和模型后联系支持；它不是“无法连接源站”，不要与 522 混淆。

401 / INVALID_API_KEY 的进一步定位

先用上方隐藏输入命令测试同一把 Key。
确认 Key 的平台分组与客户端一致。
Codex 直连方案中，requires_openai_auth = true 会忽略 env_key；改为 false 或使用一键工具。
Grok CLI 若已 grok login，官方会话会覆盖 Key；执行 grok logout 后再设 XAI_API_KEY。
若手工 models=200，但客户端请求没有出现在控制台，说明客户端未加载新 Provider。完全退出后重启并新建会话。

Codex 仍请求 api.openai.com

Provider 没有加载，或 CC Switch 回退到了 OpenAI Official。确认配置位于用户级 ~/.codex/config.toml，不是项目目录；CC Switch 中点“启用”，排障期间关闭自动故障转移。

配置改了但没有生效

CLI、VS Code 扩展和桌面 App 都可能在启动时读取配置。完全退出相关进程后重开，随后新建任务；旧会话可能保留启动时选定的 Provider。

Gemini 提示 Please set an Auth method / Invalid auth method selected

重新运行一键工具，确认 ~/.gemini/settings.json 中 "selectedType": "gemini-api-key"。
确认 ~/.gemini/.env 同时包含 GEMINI_API_KEY 与 GOOGLE_GEMINI_BASE_URL。
首次进入项目目录时选择信任该目录；未信任目录时，Gemini CLI 不会加载用户级 .gemini/.env。
完全退出 Gemini CLI 后重新打开，不要只在旧会话内重试。

DeepSeek Harness 拉不到模型或请求被拒

必须添加自定义 provider，不要只用官方 DeepSeek 卡片。
Base URL 必须是 https://sub.geiliapi.com/v1，协议选 openai-completions。
若网关拒绝请求，在 provider 上设置 compat.supportsDeveloperRole: false 与 compat.maxTokensField: max_tokens。

Windows 脚本出现中文乱码 / UnexpectedToken

这是旧版一键脚本的编码兼容问题，不是 API Key 或用户操作错误。Windows 自带的 PowerShell 5.1 会把没有 UTF-8 BOM 的旧脚本按系统 ANSI 编码读取，中文损坏后可能连带引号和语句解析失败。

执行 Remove-Item "$env:TEMP\geili-config.ps1" -ErrorAction SilentlyContinue 删除旧下载文件。
回到创建密钥的一键配置，重新复制带版本号的 Windows 命令并完整执行。
若仍有问题，执行 Get-Content "$env:TEMP\geili-config.ps1" -TotalCount 3，截图开头三行和完整报错；不要发送 API Key。

当前脚本已按 UTF-8 with BOM 发布，并在 Windows PowerShell 5.1 与 PowerShell 7 两条执行路径中验证。

验证 Key 时提示「指定的值含有无效的控制字符」

这是粘贴没成功，不是 Key 错。在 Windows PowerShell 的隐藏输入（Read-Host -AsSecureString）里按 Ctrl+V，旧版控制台不会粘贴剪贴板，而是塞进一个控制字符（0x16）。典型特征：API Key: 后面只出现一个 *，随后 Invoke-RestMethod 报「参数名: value」。

重新运行验证命令，到 API Key: 提示时用鼠标右键点击窗口粘贴（或标题栏菜单「编辑 → 粘贴」），应出现一长串 *。
也可以改用 Windows Terminal，它的 Ctrl+V 能正常粘贴。
当前教程里的验证命令和一键脚本都会剔除控制字符，读到的字符太少时直接提示重新粘贴，不会再拿坏值去请求。

Windows 一键配置还没出现选项就失败

先确认窗口标题里有 PowerShell，不要在 cmd 里粘贴。系统自带的 Windows PowerShell 5.1 还常见这三类启动失败：

A parameter cannot be found that matches parameter name 'OutFile'：旧教程用了 irm ... -OutFile。请改用创建密钥页现在的 Invoke-WebRequest -UseBasicParsing 命令。
The underlying connection was closed 或 SSL/TLS：先执行 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12，或直接复制现网那整段命令。
Internet Explorer 引擎 / first-launch：旧的 irm 可能去调 IE。必须带 -UseBasicParsing。

另外，旧命令用分号 ; 连接下载和执行：下载失败时仍会去跑 TEMP 里上次留下的坏文件。新命令会在下载失败时直接停住。

Windows 找不到命令

关闭并重新打开 PowerShell / VS Code；运行 node -v、npm -v 与客户端的 --version。若 npm 全局目录未进入 PATH，优先重新安装 Node.js LTS。

CC Switch 显示代理接管

这是本地路由模式，不是错误。live Base URL 指向 127.0.0.1，库存配置仍保存本站地址。以当前 Provider、供应商绿色状态和请求计数为准。