Magpie 使用小妙招与疑难杂症

curl -fsSL https://usemagpie.ai/install.sh | sh

连不上网关

连不上本机网关

若 Agent 报 502 或路由页空白，多半是系统代理截走了指向本机的请求。

现象

Agent 报 502、连不上；路由页空白；网关进程其实仍在运行。

原因

Codex 等即使目标是 127.0.0.1，仍可能走 HTTP_PROXY 或系统代理。只在 NO_PROXY 写 127.* 对 Codex 不够，需写完整的 127.0.0.1。Clash 一类客户端若不把回环放行，请求会被代理吞掉。

做法

• 在 NO_PROXY（及同类变量）中写入 127.0.0.1，不要只靠通配。
• 在 Clash 规则最前加 DIRECT：IP-CIDR,127.0.0.0/8,DIRECT,no-resolve，以及 ::1/128。

来源：@yetone · 官方文档同结论

模型列表空

Codex 里看不到 Magpie 模型

接线改的是配置；已打开的会话不会自动重读模型列表。

现象

已在 Magpie Agents 中接上 Codex，但会话里 /model 仍只有 ChatGPT。

原因

当前 Codex 进程沿用旧配置。需要退出后用 codex resume 回到会话，才会载入新模型列表。

做法

Agents 接好 Codex → 退出当前进程 → codex resume 再开。

来源：@yetone

账号打错号

多账号故障转移打到不支持的号

先标明每个账号能服务哪些模型，再让组内自动切换。

现象

挂了多个订阅账号，故障转移却打到根本没有该模型的号上，白白失败一次。

原因

未限制账号的模型范围时，转移可能落到无法处理该请求的账号。

做法

用 account-models 或界面里的「全部模型」勾选，标明每个账号可服务的模型。故障转移时只会发给能处理该模型的账号。

来源：@yetone

智能不出组

智能路由不会调用组外模型

智能策略只在当前组的成员里分配；想用到的模型，先放进组。

现象

开了智能策略，却期待它自动使用组里没有的模型；或以为意图分类器会直接回答用户。

原因

智能路由只在当前组成员中分配。意图分类器只做判断，不负责作答；真正作答的仍是组内被选中的模型。

做法

把可能用到的模型加入组；把意图当作分流条件，而不是额外的回答引擎。

来源：@yetone

意图不跨组

意图规则不能跳到另一组

意图命中后，是在本组内重排成员，不会改掉客户端已选定的组。

现象

想用意图规则跳到另一个路由组，怎么配置都不顺。

原因

客户端槽位与路由组是绑定的。意图只在本组内重排，不能跨组硬跳。

做法

把可能用到的模型收进同一组，用意图在组内分流。需要整组切换时，改 Agent 所选的 group/…，或换方案。

来源：@Gollumgulu（社区复盘）

日志脱敏

密钥与个人信息脱敏

可在设置中开启本地脱敏，降低路由日志泄露风险。

现象

担心路由日志或调试输出中出现 API Key 或个人敏感信息。

原因

调试与路由记录可能包含敏感字符串。

做法

打开设置 → 隐私，按需开启脱敏。

来源：@yetone

过早压缩

长对话被提前压缩

Codex 默认约在 272K 附近触发压缩；Magpie 可改为走完整上下文窗口。

现象

上下文还没到模型上限，Codex 侧已经开始压缩，细节丢失。

原因

默认压缩阈值早于完整窗口。

做法

设置 → 长对话 → 完整窗口（或同等选项）。

来源：@yetone

积分歇半小时

WorkBuddy 积分耗尽后会等待再切换

一号积分耗尽后，约等待 30 分钟再自动切到下一号，给恢复留出时间。

现象

WorkBuddy 多号池里，一号积分用尽后似乎没有立刻换号。

原因

这是预期行为：先等待约 30 分钟，再切到下一号，避免过早切换带来连锁影响。

做法

按这个节奏预期即可；不要把「立刻换号」当成故障。

来源：@yetone

模型满载

偶发「模型满载」

可能只是落到了当时满载的那一号，不一定是 Magpie 本身出问题。

现象

经 Magpie 使用 ChatGPT 时偶发「模型满载」，换账号后又恢复正常。

原因

账号间切换时，可能落到当时满载的账号。

做法

临时用「只切换 Codex 的登录」把会话固定在可用账号上，再观察。

来源：@yetone

意图分类器

用意图判断模型做分流

规则条件可选「意图」，并指定一个小而快的分类模型；分类失败则该条规则不命中。

现象

想按「简单问答 / 写测试」等类型分流，但不确定规则条件怎么写。

原因

需要单独的分类模型做判断；它只负责分类，不负责回答。

做法

在组规则中选择意图条件，挂上分类器模型。细节以官网意图路由说明为准。

来源：@yetone

换 Agent 接力

在同一会话里换 Agent 继续

不必从头复述上下文；会话页提供「换 Agent 继续」。

现象

同一任务想从 Claude 接到 Codex（或反过来），又不想重新说明背景。

原因

各 Agent 进程彼此独立；需要显式交接当前会话。

做法

打开会话页 → 换 Agent 继续。

来源：@yetone

WSL 连不上

WSL 访问不到 Windows 上的网关

WSL 与 Windows 不是同一套回环。自 v0.1.1483 起，Windows 版可监听 WSL 网卡。

现象

Magpie 跑在 Windows，Agent 在 WSL 里，访问 127.0.0.1:3425 失败。

原因

子系统里的 127.0.0.1 指向 WSL 自身，不是宿主机。

做法

升级到支持版本，按应用提示打开对 WSL 网卡的监听。

来源：@yetone

统一资源库

用资源库统一管理 skills 与 MCP

把各 Agent 分散的 skills、MCP 收到一处，减少重复配置。

现象

各 Agent 各自安装一套 skills、MCP，难以同步。

原因

多端独立配置容易漂移。

做法

在应用中打开资源库相关入口，按说明统一管理。

来源：@yetone

网关须常开

网关需要保持运行

请求经本机网关转发；托盘或 daemon 不在，端口就无人监听。

现象

关闭 Magpie 窗口或托盘后，Agent 立刻连不上。

原因

本机网关进程退出后，没有服务继续监听端口。

做法

走 Magpie 路由时保持 tray 或 daemon 在运行；不要当成「配完就能关」。

来源：@brave16821

勿叠 CC Switch

不要与 CC Switch 同时改路由

两套工具都会改 Agent 的 base URL 与模型配置；同时开启会互相干扰。

现象

两边都在改配置，行为异常、难以排查。

原因

两者作用于同一层配置，会互相覆盖。

做法

选定一条链路：用 Magpie 就关掉 CC Switch 的路由或劫持；反之亦然。

来源：@Jason_Young1231

一键导入

New API 一键加入 Magpie

官方 import 深链可打开 Magpie 并预填供应商；New API 后台可加按钮生成该链接。

现象

自建 New API 或中转时，每次在 Magpie 里手填 URL 和 Key 很繁琐。

原因

缺少从中转后台直达 Magpie 的入口。

做法

在中转后台添加「Add to magpie」按钮。密钥放在 # 片段中，避免写入服务器日志。说明见 官方 import。

来源：@yetone

会话亲和

会话中途换模型时的亲和

组可以尽量让同一会话留在同一成员上；具体开关以当前版本文档为准。

社区有人问：长会话中途换模型，会不会丢掉 prompt cache 或亲和？公开帖见 @xeon_roam。此处不转述未核对到的作者回复；请以 Magpie 文档中路由组的 stays / auto 说明为准。