MoeRouter 文档 获取 API Key

确认成功与排错清单

配置好客户端之后,用四步确认链路真的通了。再按客户端列出最常见的问题和处理办法。

更新于 2026-11-15 阅读约 3 分钟

本页目录
  1. 四步确认
  2. 改了配置没生效
  3. 常见问题对照
  4. 反馈问题时带上什么

四步确认#

  1. 客户端能启动,显示的配置是对的。 配置文件语法正确;Claude Code 和 Codex 用 /status 看,Gemini CLI 看底栏。地址和模型应该是你填的那些。

  2. 最小请求成功。 发一句“只回复 OK,不要调用工具”。先排除工具调用和长上下文的干扰。

  3. 在 MoeRouter 的使用日志里能查到。 控制台 → 使用日志,按时间、Key 名称和模型核对。经过 Magpie、AstrLink 时,也看一下它们自己的记录。

  4. 再试真实的工作流。 流式输出、工具调用、长上下文分别试一次。

MoeRouter 使用日志
使用日志里是每次请求的时间、令牌、模型、输入和输出 token、费用、首字时间和耗时。红色的“错误”行点开能看到状态码。

第 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 时先打码。

↑↓ 选择Enter 打开可以直接粘贴报错原文