文档 · 指南

Agent 没走 magpie 怎么办

magpie 接入一个 Agent 时，会记下自己在它的配置里设了什么。之后 Agent 页一直对照两件事：配置还是不是 magpie 设的样子，以及配置没问题时，Agent 最近的请求有没有真的到达 magpie 网关。对不上时，Agent 页上它那一行会标出来，说明原因，并给出修复按钮：多数情况是 重新应用（状态行上叫 重新接入），地址不通或经代理时是 如何修复。下面按 magpie 给出的五种提示逐一说明。

不算问题的两种情况：在 Agent 自己的模型选择器里从一个 magpie 模型换到另一个 magpie 模型，magpie 不会提示；你自己手写了一个叫 magpie 的供应商，那是你的配置，magpie 也不会标出或覆盖。

“已不经过 magpie：配置已变更”

模型还是 magpie 的，但配置里把请求送到 magpie 的那部分（比如网关地址）被改掉了，常见于手动编辑配置、Agent 自己更新后改写了配置，或另一个工具改过它。

1. 点 重新应用magpie 把它设过的内容再写一遍，并更新记录。之后提示消失。
2. 重启 Agent多数 Agent 只在启动时读取配置，已经开着的要重开一次。

“已在 magpie 之外换掉 {model}”

magpie 设的是某个 magpie 模型，现在配置里换成了 Agent 自己的模型，也就是不经过 magpie 的那种。提示里会说这个字段现在是什么、magpie 当初设的是什么。这时有两个选择：

• 重新应用：把 magpie 设的模型放回去，和它一起设过的其他字段（比如推理强度）也一并放回。
• 保留当前设置：这是你有意的改动。magpie 忘掉它之前设的内容，保留你现在的配置，不再提示。这一项只在这种情况下出现在行菜单里。

“最近绕过了 magpie，重新应用后请重启”

配置是对的，但 Agent 在 magpie 设好之后被用过，而它的请求一个都没到 magpie。最常见的原因是这个 Agent 在 magpie 改配置之前就开着，还在用旧配置运行；也可能是配置文件之外的东西（比如环境变量）覆盖了它。提示里写得更具体：

• 最后一次请求发到了别的主机，而不是 magpie：它在 magpie 设置之前就启动了，还在用旧配置。
• 某个时间连不上 magpie：那时 magpie 没在运行，所以它拿不到 magpie 的模型。
• 在某个时间被用过，但没有请求到达 magpie。

修法都是退出并重新打开这个 Agent。需要的话先点 重新应用，它会更新记录，之前的使用就不再算数。

“已设好，但它连 magpie 用的地址没有回应”

配置没问题，但 Agent 连 magpie 用的不是本机回环地址（127.0.0.1），而那个地址没有回应，同时 magpie 自己在本机是正常的。这通常是 WSL 里的 Agent，或者你自己做的端口转发。magpie 会在后台从本机去试这个地址。

WSL 里的 Agent 连的是 magpie 为 WSL 监听的地址却没有回应时，是 Windows 防火墙挡住了 WSL。Windows 弹窗时允许 magpie，或在管理员 PowerShell 里运行（-Program 是 magpie.exe 的实际路径，提示里会给出完整命令）：

New-NetFirewallRule -DisplayName 'magpie (WSL)' -Direction Inbound -Action Allow -Profile Any -InterfaceAlias 'vEthernet (WSL*)' -Program '…\magpie.exe'

WSL 的网络属于“公用”网络，只勾“专用”网络的规则不起作用。在 Windows 11 上，也可以在 .wslconfig 里改用镜像网络，WSL 就能直接用 127.0.0.1 连 magpie：

# %UserProfile%\.wslconfig
[wsl2]
networkingMode=mirrored

在 WSL 的 NAT 网络下，Windows 的地址只有在有东西监听时才连得上：要么 magpie 自己开着 设置 › 网络与共享 › 局域网共享（这时它监听所有地址，其他电脑要用网关密钥），要么是你自己的转发（netsh interface portproxy，Windows 重启后可能要重新设置）。在这里能连上而 WSL 仍连不上时，就是防火墙，放行 WSL 网络的网关端口（默认 3425）。

如果是 WSL 发行版连 Windows 的地址变了，提示里会说新地址，按钮变成 改用 {url}，点一下 magpie 就把 Agent 指到新地址。不在 WSL 时，是之前把地址转发给 magpie 的东西没在监听了：重新启动它，或把 Agent 直接指向 magpie 的本机地址。

“经代理连 magpie，但这个代理没把它的请求转给 magpie”

这是 Codex 的情况。Codex 发给 magpie 的请求会先经过环境变量或系统设置里的代理，而这个代理没有把请求转回 magpie，结果每一轮都是 502 Bad Gateway，换哪个模型都一样。magpie 会按 Codex 的方式检查它走哪个代理（终端里的 Codex 看终端环境，ChatGPT 应用里的 Codex 看登录 shell 的环境），提示里写明代理地址和它是在哪里设置的。修法任选一种：

• 让代理对 127.0.0.1 直连：给 127.0.0.0/8 加一条 DIRECT 规则，或者用规则模式而不是全局模式。
• 代理来自 *_PROXY 环境变量时，在设置它的地方把 127.0.0.1 加进 NO_PROXY。
• Windows 上，在系统代理设置的“请勿对以下列条目开头的地址使用代理服务器”里加 127.0.0.1（只写 127.* 对 Codex 不够）。
• macOS 和 Linux 上，在 shell 配置里加 NO_PROXY，终端里的 Codex 和 ChatGPT 应用里的 Codex 都会读到：

# ~/.zshrc
export NO_PROXY=127.0.0.1

改完之后退出并重新打开 Codex。

断开 magpie

一时修不好，或者你就是不想让这个 Agent 走 magpie，可以在行菜单里选 断开 magpie（还原配置）：magpie 把 Agent 的配置放回接入之前的样子，并忘掉它设过的内容。之后想再接入，在 Agent 页重新设置即可。

常见问题

为什么我在 Agent 里换了模型，magpie 提示配置被改？

你换到的是不经过 magpie 的模型。想保留就选 保留当前设置，想回到 magpie 就点 重新应用。在 Agent 里从一个 magpie 模型换到另一个 magpie 模型不会提示。

重新应用之后还是提示绕过了 magpie？

这个 Agent 在 magpie 设置之前就开着，还在用旧配置。退出并重新打开它，新请求到达 magpie 后提示就会消失。

WSL 里的 Agent 连不上 magpie 怎么办？

多半是 Windows 防火墙挡住了 WSL：在弹窗里允许 magpie，或在管理员 PowerShell 里运行提示给出的 New-NetFirewallRule 命令。Windows 11 上也可以在 .wslconfig 里设 networkingMode=mirrored。

Codex 每轮都 502，提示代理没转给 magpie？

Codex 发给 magpie 的请求被代理接走了。让代理对 127.0.0.1 直连，或把 127.0.0.1 加进 NO_PROXY，然后重开 Codex。

相关页面：Codex 接入 DeepSeek、Kimi、GLM、Claude 等第三方模型、远程 magpie。遇到报错？见 常见错误排查，或到 Discord 提问。