排障手册

终端或客户端报错时，按下面顺序排查。每次只改一项，便于定位问题。

先记住各工具最容易填错的地址

同一个网关，不同工具的地址要求并不完全一样。排障前先把这一层分清楚，能省掉很多时间。

工具	正确地址	最常见填错方式
Claude Code	`https://xiaolan.ainb.plus`	误写成 `https://xiaolan.ainb.plus/v1`
Gemini CLI	`https://xiaolan.ainb.plus`	误写成 `https://xiaolan.ainb.plus/v1`
Cherry Studio	`https://xiaolan.ainb.plus`	误写成 `https://xiaolan.ainb.plus/v1`
Codex / OpenAI SDK / 大多数 OpenAI 兼容工具	`https://xiaolan.ainb.plus/v1`	误写成根地址 `https://xiaolan.ainb.plus`

连第一步该查地址还是查 Key 都不确定时，先对照这一张表。

先判断卡在哪一层

很多问题不是“工具坏了”，而是卡在不同层级。先判断层级，再动手改配置，速度会快很多。

层级	典型现象	先看哪里
安装层	`node`、`npm`、`git`、`claude`、`codex` 命令不存在	先回 Node 安装 / macOS Node 安装
配置层	命令能启动，但鉴权失败、地址错误、模型列表为空	Base URL、API Key、模型名、配置文件
网关层	curl 直接返回 401 / 404 / 429 / 503	Key 状态、余额、分组、模型权限、当前负载
模型层	页面能打开、请求能发出，但回答慢或效果不对	当前模型、上下文大小、是否换轻量模型验证

先把问题归类清楚，通常就能知道该先改命令环境、先改配置，还是先回控制台查 Key 和模型。

步骤 0：确认全局设施状态

先确认是否为全局可用性问题：

官方状态探针：看看小蓝中转站网关当前是否大面积故障。
模型广场：确认目标模型是否处于维护中或暂时下线。

步骤 1：HTTP 状态码

遇到报错，先看返回的状态码：

已经看到了明确的 401、404、429 这类状态码时，说明请求通常已经成功发到了网关。这个时候继续重装 Node.js、Git 或客户端，收益往往不大，优先查 Key、模型名、分组和余额更直接。

❌ 400 Bad Request

模型名拼写错误。请从模型广场复制完整名称。
这把 Key 的权限组不包含这个模型。
请求内容格式不符合接口要求。
工具和网关协议不匹配，例如本应走 OpenAI 兼容，却写成了别的协议路径。

🚫 401 Unauthorized

你的 API Key 填错了，或者没带 sk- 前缀。
这把 Key 已被禁用，或触发控制台额度上限。
当前终端根本没有读到你刚写入的环境变量。

🚧 403 Forbidden

通常是被网关安全策略拦截：

你的请求 Header 不规范。
遇到了严格的风控阻断。

🔎 404 Not Found / Model Not Found

模型名不存在。
模型名来自旧教程或官方示例，不是模型广场里的名称。
当前 Key 看不到这个模型。
地址层已经写错，例如 Claude Code / Gemini CLI / Cherry Studio 手动补了 /v1，或 Codex 少了 /v1。

处理方式：回模型广场复制完整模型名。

🚦 429 Too Many Requests

请求太密集。
当前 Key 或模型触发频率限制。
自动化脚本并发过高。

处理方式：降低并发、加重试间隔、先换轻量模型验证。

⏳ 503 / 504 / 响应极慢

模型后端可能处于高负载状态。
先换轻量模型确认网络和 Key 正常。
清理无关上下文，减少单次请求体积。

步骤 2：环境连通性自检 (Ping)

Claude Code、Gemini CLI 这类终端工具一直连不上时，打开一个新的终端窗口，输入以下命令进行最小化验证：

先把 MODEL 替换成你在模型广场复制的一个轻量模型名：

bash

MODEL="替换成模型广场里的轻量模型名"

curl -X POST https://xiaolan.ainb.plus/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的专属Key" \
  -d "{\"model\":\"$MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}"

如果能收到带回复的 JSON，说明小蓝中转站网关、Key 和网络连通性正常。继续检查本地工具配置。

curl 也失败：先解决网关、Key、模型或网络问题
curl 成功，客户端失败：说明问题更可能在本地工具配置，而不是小蓝中转站本身

先用最小请求证明链路通不通，通常比反复重装客户端更快。

步骤 3：本地环境自检

终端工具先查基础环境：

bash

node -v
npm -v
git --version
npm config get registry

期望：

node 有版本号
npm 有版本号
git 有版本号
npm registry 是 https://registry.npmmirror.com/

缺 Node 或 Git 时，按系统回 Windows Node 安装、macOS Node 安装或 Linux Node 安装补环境。

现在连工具都还没装上时，不要急着排接口。先把安装入口和基础命令理顺：

Windows Node.js：优先 nodejs.cn/download
Windows Git：优先 winget install --id Git.Git -e --source winget
macOS Git：优先 xcode-select --install
CC-Switch：优先 https://ccswitch.ai/zh/
Cherry Studio：优先 https://docs.cherry-ai.com/cherry-studio/download

步骤 4：工具配置自检

Claude Code

bash

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

Claude Code 这里应看到根地址 https://xiaolan.ainb.plus，不是 /v1 地址。

还想再确认一层时，可以继续看：

bash

echo $CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY
echo $ANTHROPIC_MODEL

常见判断：

ANTHROPIC_BASE_URL 正确，但还是连不上：继续看 ANTHROPIC_AUTH_TOKEN
地址和 Key 都正确，但 /model 列表空：继续看分组和模型权限
模型能看到，但当前回复不对：继续看 ANTHROPIC_MODEL 或当前会话实际选中的模型

Codex

Codex 优先检查本地配置文件和 Key 环境变量，不先看 OPENAI_BASE_URL：

bash

cat ~/.codex/config.toml
echo $小蓝中转站_API_KEY

重点确认：

base_url = "https://xiaolan.ainb.plus/v1"
wire_api = "responses"
env_key = "小蓝中转站_API_KEY"
当前终端里 小蓝中转站_API_KEY 真的有值

以前用过官方登录时，~/.codex/auth.json 可能已经存在。
但当前这套小蓝中转站接法主要看的不是它，而是 config.toml 和 小蓝中转站_API_KEY。

怀疑当前项目覆盖了用户级配置时，再检查一次：

bash

cat ./.codex/config.toml

项目目录里如果有另一份 .codex/config.toml，它可能会覆盖主目录里的默认值。

Gemini CLI

bash

echo $GOOGLE_GEMINI_BASE_URL
echo $GEMINI_API_KEY
echo $GEMINI_MODEL

Gemini CLI 这里应看到根地址 https://xiaolan.ainb.plus，不要手动补 /v1。当前版本会自己继续拼接 /v1beta/models/... 这类 Gemini API 路径。

如果地址和 Key 都正确，但当前模型不像你刚配置的那个，可以继续试两步：

bash

gemini --model 从模型广场复制的模型名

进入 Gemini CLI 后再输入：

txt

/model

如果临时指定模型能生效，而平时默认值不生效，优先检查当前目录里是不是还有额外的 .gemini 配置覆盖掉了默认设置。

如果 Gemini CLI 还没安装完成，先决定你要用哪种方式：

临时试用：npx @google/gemini-cli
长期使用：npm install -g @google/gemini-cli
官方仓库：https://github.com/google-gemini/gemini-cli

Windows PowerShell 把 $变量名 换成 $env:变量名。

OpenCode

bash

cat ~/.config/opencode/opencode.json
echo $小蓝中转站_API_KEY
opencode auth list

优先检查：

provider 里是否写了 baseURL = "https://xiaolan.ainb.plus/v1"
model / small_model 前缀是否和 Provider 名一致
你现在走的是环境变量方案，还是 /connect 保存的认证方案

走的是 /connect 路线时，opencode auth list 比盯着旧的 OPENAI_API_KEY 变量更直接。

Cherry Studio

先回到服务商设置页看这几项：

服务商类型是否是 OpenAI 兼容
API 地址是否是 https://xiaolan.ainb.plus
保存后有没有点过 Check
模型列表有没有重新拉取

Cherry Studio 官方当前会自己继续拼接 OpenAI 兼容路径，所以它的 API 地址栏更适合填根地址 https://xiaolan.ainb.plus，不是 https://xiaolan.ainb.plus/v1。

已经拉到了模型列表，但发消息时还是报模型不存在，就先看两件事：

当前新对话实际选中的，是不是刚配置的小蓝中转站服务商
当前下拉框里选中的，是不是刚拉下来的那个模型

步骤 5：缩小问题范围

按这个顺序换：

换轻量模型。
换一把新 Key。
换一个新终端窗口。
换手机热点。
换客户端。

每次只换一项。一次改太多，定位不了问题。

连“安装失败”和“配置失败”都分不清时，先把问题拆开：

先确认工具有没有装上：claude --version / codex --version / gemini --version
再确认环境变量或配置文件有没有写对
最后再测网关、Key 和模型

先把“命令能启动”解决，再去查接口问题，速度会快很多。

联系支持

带上以下信息，前往售前与售后支持：

遇到报错的工具名称（比如：Alma 或 Claude Code）。
终端里完整的报错日志原文。
你的本地配置截图（务必打码掩盖你的完整 Key 字符串）。
最小 curl 测试结果。
你使用的模型名。

排障手册 ​

先记住各工具最容易填错的地址 ​

先判断卡在哪一层 ​

步骤 0：确认全局设施状态 ​

步骤 1：HTTP 状态码 ​

❌ 400 Bad Request ​

🚫 401 Unauthorized ​

🚧 403 Forbidden ​

🔎 404 Not Found / Model Not Found ​

🚦 429 Too Many Requests ​

⏳ 503 / 504 / 响应极慢 ​

步骤 2：环境连通性自检 (Ping) ​

步骤 3：本地环境自检 ​

步骤 4：工具配置自检 ​

Claude Code ​

Codex ​

Gemini CLI ​

OpenCode ​

Cherry Studio ​

步骤 5：缩小问题范围 ​

联系支持 ​

排障手册

先记住各工具最容易填错的地址

先判断卡在哪一层

步骤 0：确认全局设施状态

步骤 1：HTTP 状态码

❌ 400 Bad Request

🚫 401 Unauthorized

🚧 403 Forbidden

🔎 404 Not Found / Model Not Found

🚦 429 Too Many Requests

⏳ 503 / 504 / 响应极慢

步骤 2：环境连通性自检 (Ping)

步骤 3：本地环境自检

步骤 4：工具配置自检

Claude Code

Codex

Gemini CLI

OpenCode

Cherry Studio

步骤 5：缩小问题范围

联系支持