文档 · 帮助
常见错误排查：401、429、502、504 等
magpie 网关的报错会说明出了什么问题。这一页列出常见的报错、原因和解决办法。
每个请求都列在 magpie 的 路由 页上：发给了哪个供应商、哪个账号，每次尝试的结果。在请求上点 复制报告，就能拿到求助需要的信息。
401 和 403：密钥或登录被拒
来自厂商。供应商拒绝了 magpie 发送的密钥或登录。magpie 会暂停这个密钥或账号，改用下一个，所以只有全都不行时你才会看到报错。登录过期时报错会直接说明，比如 “the ChatGPT sign-in has expired — sign in again”。
- 解决：在 ＋ 添加供应商 里重新登录（或
magpie accounts add <provider>），或者给供应商换一个新密钥。
来自 magpie 自己。以下情况 magpie 会直接回 403，什么都不发出去：
| 报错 | 原因 | 解决 |
|---|---|---|
| model disabled | 你在 magpie 里关掉了这个模型。 | 在它的供应商里重新打开。 |
| model not allowed for the gateway key | 这个网关密钥限定了可用的模型。 | 用 magpie gateway-key models <id> 查看或修改。 |
| magpie doesn’t answer the web page … | 有网页在浏览器里调用网关。 | 把它加到 设置 › 网络与共享 › 网页，并发送网关密钥。 |
429 与暂停使用
429 表示供应商额度用完、余额不足或在限流。magpie 会暂停被拒的密钥或账号，把请求交给下一个账号、路由组里的下一个成员，或供应商的 备用。供应商那一行会显示 暂停使用 · {why} · {time} 恢复。
| 被拒原因 | 暂停多久 |
|---|---|
| 额度用完，给出了重置时间 | 到重置为止 |
| 限流，带 Retry-After | 到那时为止 |
| 余额不足 | 30 分钟；再被拒依次为 2 小时、8 小时、1 天、3 天、1 周 |
| ChatGPT 账号额度用完 | 到拒绝时给出的重置时间；没有就等整个窗口刷新；都不知道就 5 小时 |
| 其他失败 | 1 分钟，重复时翻倍，最多 10 分钟（限流最多 30 分钟） |
- 现在就再试。立即重试 会结束暂停：下一个请求会再次使用它。再被拒绝时，会照常再次暂停。
- 限制暂停时长。
magpie provider rest-cap <id> 4h设置一个供应商最长暂停多久；off让它在原因不明的失败后不暂停。 - 限额很快恢复的中转站。在供应商编辑器的 高级 里取消勾选 额度用完或被限流时暂停它：之后 429 不再暂停它，下一个请求照常发给它。
- 不要只靠一个。再加一个账号或备用模型，一个用完不会让 Agent 停下来。
magpie accounts显示每个账号用掉了多少额度。
暂停状态在重启后保留，退出 magpie 不会让暂停中的账号提前回来。
502：供应商没有正常回应
502 表示 magpie 没从供应商拿到 API 回复。供应商名称后面的内容说明是哪种情况：
- “didn’t answer: …”连接失败：域名解析不了、连接被拒、代理没开。这台电脑完全没有网络时，magpie 能识别出来，不会暂停任何供应商。
- “… not an API reply”供应商回应了，但回的是网页（登录页、Cloudflare 验证页）、空内容，或不是 JSON 的内容。通常是 Base URL 指向了网站而不是 API：对照厂商文档检查，看看是否需要以
/v1结尾。 - OpenCode：“… which is no error, not an API reply”。OpenCode 的网关有时会回一个只含模型名的 400。同样的请求几秒后就能成功，所以 magpie 把它当作 502：在请求的等待时间内重试，或换路由组的下一个成员，不暂停任何账号。它和携带特别多工具定义的请求有关。
502、503、504、529 和 Cloudflare 的 520 到 524 都算作“忙”：magpie 会先重试或换路由组的下一个成员，然后才把错误交给 Agent。
504：没有及时回应
- “<provider>: no first token in Ns”。路由组给每个成员一个开始回复的时限（首字耗时）。这个成员超时了，于是换了下一个。慢模型可以在组里调大它。
- “no member of the group answered within its Ns budget”。在组的时限内试过了每个成员，都没有回应。
- “magpie held this request for … without routing it to any provider”。请求在 magpie 内部等待过久，被停下而不是一直挂着。重新发送；如果还出现，在 路由 页这个请求上点 复制报告，发出来。
找不到模型（404）
报错是 magpie knows no model “…”，常带有 did you mean …? 和你的供应商 id 列表。
- 按 magpie 的方式命名。用
provider/model（和magpie models列出的一样）、路由组的 id 或名称，或者不带前缀的模型 id。 - “… is switched off in Magpie, so … is not served”。供应商或路由组被关掉了。在供应商页或路由页重新打开。
- 还没有供应商。报错会说 “add a provider in magpie first”。
Agent 里看不到模型
- 重启 Agent。大多数 Agent 只在启动时读取配置。改动后 magpie 会在 Agent 那一行提示，比如 Codex 启动时生成模型列表。Codex 应用还有一个常驻的 app-server，按提示重启它。
- 确认 magpie 提供这个模型。
magpie models列出所有可选模型。你关掉的模型，或所在供应商被关掉的模型，不会列出。 - Claude Code。
/model会列出标着 “via magpie” 的模型。如果 shell 里设置了CLAUDE_CODE_USE_BEDROCK或CLAUDE_CODE_USE_VERTEX，Claude Code 会连到那个云而不是 magpie；把它从 shell 配置文件里去掉。
3425 端口被占用
网关监听 127.0.0.1:3425。要换端口，打开 设置 › 网络与共享 › 网关地址。这里只设置端口（1024 到 65535），magpie 接入过的 Agent 会一起改过去。
| magpie 的提示 | 解决 |
|---|---|
| 端口 … 已被其他程序占用，请换一个 | 换一个空闲端口。 |
| 另一个 magpie 正在 … 提供网关：请在那边设端口，或先退出它 | 运行了两个 magpie，退出一个。 |
| 端口 … 被其他程序占用（可能是 magpie web）：magpie 每隔几秒会再试一次 | 找到占用端口的程序，或把网关换到别的端口。 |
| MAGPIE_ADDR=… 设置了网关的完整地址 | 取消或修改 MAGPIE_ADDR。 |
WSL 里的 Agent
在 Windows 上，magpie 会在正在运行的 WSL 发行版里查找 Claude Code、Codex、OpenCode、Kimi Code、Qwen Code 等 Agent。找到的每个都在 Agent 页有自己的一行，magpie 像在 Windows 上一样配置它。magpie 不会启动已停止的发行版。
- 没有列出 Agent。先启动发行版，并确认 设置 › 常规 › 检测 WSL 中的 Agent 已打开。
- 连不上 magpie。在 WSL 默认的 NAT 网络下，magpie 还会在 Windows 的 WSL 网络地址上提供网关，使用单独的密钥，并把这个地址写进 Agent 的配置。镜像网络模式下，Agent 和 Windows 上一样用
127.0.0.1。是否放行仍由 Windows 防火墙决定：WSL 网络属于“公用”网络，连接被拦时请在那里允许 magpie。 - 改动没生效。WSL 里的 Agent 启动时读取配置：在那边重启它。
从局域网里的其他电脑使用
默认情况下网关只回应本机。要让其他电脑使用：设置 › 网络与共享 › 局域网共享。另一台电脑需要发送 网关 页 网关密钥 里的密钥。
- “magpie isn’t shared on the local network”。在运行 magpie 的电脑上打开共享。
- 401。没带密钥，或密钥已关闭、已过期。以
Authorization: Bearer <key>或x-api-key发送一个启用的网关密钥。 - 某个模型 403。这个密钥限定了可用的模型：
magpie gateway-key models <id>。
不要把端口暴露到公网；在电脑之间用 VPN。完整的设置，包括连接另一台 magpie，见 远程 magpie。
已迁移到插件的订阅无法使用
Command Code、Cursor、Devin、Factory、Grok、Kiro、Xiaomi MiMo、Qoder、WorkBuddy、ZCode 和 Zed 已不再内置于 magpie，各自由一个功能相同的社区插件提供。之前添加的账号还需要迁移到插件，迁移之前它们无法使用。
- 解决：供应商列表上方会有一行提示“… 的内置订阅已下线，它的账号还没迁移到插件”。点 迁移到插件：magpie 会安装插件并逐个检查账号。迁移会保留你的账号、模型和 Agent 设置。magpie 也会自动迁移，在 插件 页安装插件同样会迁移。
迁移后的报错来自插件：登录、模型和请求都由插件处理。
常见问题
供应商明明正常，magpie 为什么回 502？
供应商回的不是 API 回复，比如网页或空内容。通常是 Base URL 指向了厂商的网站而不是 API。
429 之后为什么某个账号一直不用？
magpie 会暂停它，直到厂商给出的重置时间；没有给出时暂停一段时间。供应商那一行会显示何时恢复，点“立即重试”可以结束暂停。
“magpie knows no model” 是什么意思？
没有供应商提供这个名字的模型。按 magpie models 列出的 provider/model 命名，或重新打开它的供应商。
怎么修改 magpie 的端口？
设置 › 网络与共享 › 网关地址。magpie 接入过的 Agent 会一起改过去。
WSL 里的 Agent 能用 Windows 上的 magpie 吗？
能。magpie 会在运行中的 WSL 发行版里找到 Agent，并给每个配置一个能连上的地址。NAT 网络下需要 Windows 防火墙放行 WSL 的连接。
能从局域网里的其他电脑用 magpie 吗？
能。打开 设置 › 网络与共享 › 局域网共享，另一台电脑发送网关密钥即可。不要把端口暴露到公网。
还没解决？在路由页复制这个请求的报告，到 Discord 提问。