四步确认#
-
客户端能启动,显示的配置是对的。 配置文件语法正确;Claude Code 和 Codex 用
/status看,Gemini CLI 看底栏。地址和模型应该是你填的那些。 -
最小请求成功。 发一句“只回复 OK,不要调用工具”。先排除工具调用和长上下文的干扰。
-
在 MoeRouter 的使用日志里能查到。 控制台 → 使用日志,按时间、Key 名称和模型核对。经过 Magpie、AstrLink 时,也看一下它们自己的记录。
-
再试真实的工作流。 流式输出、工具调用、长上下文分别试一次。

第 3 步很重要:客户端显示“成功”,不代表请求走的是 MoeRouter。日志里查不到,说明客户端实际连的是别的地址,多半是旧配置或环境变量还在起作用。
改了配置没生效#
这是最常见的一类问题,原因几乎总是下面之一:
- 客户端没有重启。 命令行工具要开新的终端窗口;桌面应用要完全退出再打开,macOS 上是 ⌘Q,关窗口不算。
- 有多个工具在管理同一个客户端。 CC Switch、Magpie、AstrLink 和手动编辑改的是同一批文件,以最后写入的为准。只留一个管理者。
- 环境变量盖过了配置文件。 系统环境变量、项目里的
.env、shell 启动脚本里的export,优先级通常比配置文件高。用env | grep -i -E 'anthropic|openai|gemini|moerouter'看看当前终端里有什么。 - 改错了文件。 项目目录里的配置会盖过用户目录里的。
常见问题对照#
| 现象 | 先检查 | 怎么办 |
|---|---|---|
| 401,认证失败 | Key 是否完整;有没有把 MoeRouter Key 和 Magpie、AstrLink 的本地令牌混用 | 用对应链路的凭据;改完开新会话 |
| 403,余额或额度不足 | 账户余额;这个 Key 自己的额度 | 充值,或调高 Key 的额度 |
| 404,路径不对 | /v1、/v1beta 有没有多加或少加 |
对照接口地址表 |
| 404,模型不能通过这个接口调用 | 模型是否支持客户端用的接口 | 换模型,见接口与协议 |
| 模型不存在 | 模型 ID 是否拼对;Key 的分组里有没有它;Key 是否开了模型限制 | 从模型广场复制 ID;核对分组 |
| Codex 多轮之后报 400 | 模型能否接续上一轮的推理内容 | 换 gpt-6.1-sol 或 gpt-6-astra,开新会话 |
| Gemini CLI 提示必须设置 GEMINI_API_KEY | 当前目录是否受信任 | 交互式运行一次 gemini 选 Trust folder,或改用环境变量 |
| Gemini CLI 提示 Invalid auth method | settings.json 是否选了 gemini-api-key |
按 Gemini CLI 教程补上 |
| Claude Desktop 菜单里没有 GPT 等模型 | 是否用了直连 | 直连只显示 Claude 模型,改用 CC Switch 模型映射 |
| CC Switch 的供应商显示“需要路由” | 是否开启了路由模式 | Claude Desktop 页 → 路由 → 开始路由 |
| Claude Desktop 报 Host Claude Code binary not available | 能否访问 downloads.claude.ai |
解决网络后重启 Claude Desktop |
本地 connection refused |
Magpie、AstrLink、CC Switch 是否在运行;端口有没有变 | 打开对应的软件,复制界面上显示的当前地址 |
| 配置总被改回去 | 是否有多个工具在管理同一个客户端 | 只留一个 |
| 429 | 并发、线路繁忙 | 按 Retry-After 等待,不要高频重放 |
| 503,提示几秒后重试 | 线路在休息 | 等提示里的秒数再试 |
| 长请求中途断开,或 524 | 是否用了非流式请求 | 改用流式输出 |
| 5xx | 是 MoeRouter 还是本地网关先报的错 | 记下时间、模型和 request id 联系我们 |
每个错误码的详细说明在报错对照表。
反馈问题时带上什么#
加 QQ 群 124786532 联系我们。带上下面这些,能省掉好几轮来回:
- 出错的大致时间;
- 模型名、你用的客户端和版本;
- 报错原文。提示末尾的
request id最有用; - 走的是直连,还是经过了 CC Switch 路由、Magpie、AstrLink。
不要发 API Key。 截图里有 Key 时先打码。