网络出口（Egress） · MagicFrog Docs

agent run 如何触达网络——direct、frp 反向隧道与 client-proxy 三种模式，以及失败即关闭（fail-closed）的会话作用域。

每个 agent run 的网络流量都经由为该会话选定的 egress 模式离开。三种模式是 direct、frp 与 client-proxy。

egress 以会话为作用域：模式绑定到会话，切换模式是显式的生命周期变更，失败绝不静默降级。

egress 模式

模式	传输	适用场景
`direct`	执行机器的既有路由（无隧道）。	有公网 IP 或网络本身可达的机器。
`frp`	frp 反向隧道。	位于 NAT 后、需要入站可达性的已登记设备。
`client-proxy`	SOCKS5，以选定客户端作为网络出口。	浏览器等应当使用某个特定客户端网络的工具。

模式如何选定

默认规则：机器有公网 IP 时用 direct；配置了 frp 服务时用 frp；指定了中继客户端时用 client-proxy；都不满足时回落 direct（出站总能工作；入站走登记通道）。

模式也可以由配置固定：

MAGICFROG_EGRESS_MODE=client_proxy   # or "direct" (default when unset)
MAGICFROG_CLIENT_ID=<client id>      # defaults to the computer id
MAGICFROG_FRPS_ADDR=127.0.0.1
MAGICFROG_FRPS_PORT=7000
MAGICFROG_FRPS_TOKEN=<token>

隧道端点在健康之后以 socks5://<frps host>:<remotePort> 发布。

失败即关闭的会话作用域

切换是显式的生命周期变更，有四条硬规则：

切换前系统先校验目标客户端在线且已授权；校验不过，会话保持原状。
切换成功后，会话绑定新的出口；浏览器会话随新出口重建。
切换失败（隧道建立失败、客户端离线、未授权）时，会话进入失败态——绝不回落 direct，失败会带原因显式报出。
已失败的会话没有原地恢复：回到 direct 的唯一途径是销毁并重建会话，绝不静默迁移。

浏览器会话绑定

浏览器会话在创建时绑定模式。client_proxy 会话的浏览器全程走指定代理；显式 direct 会话的浏览器直连——那是配置定的模式，不是回落。切换中或已失败时，浏览器拒绝绑定：没有稳定的出口，就不会有新的浏览器会话。

如果隧道在会话中途断掉，浏览器保持已失效的代理设置：连接会失败，浏览器绝不会自行绕过代理直连。

切换 egress

切换是显式的生命周期变更，经 PATCH /v1/runs/{runId}/egress 驱动：

请求：{ "mode": "direct" | "client_proxy", "clientId": "..." }——模式为 client_proxy 时 clientId 必填（否则 400）。
错误是类型化且显式呈现的：400 缺少 clientId，403 未授权，410 客户端离线（失败即关闭，无回落），504 隧道建立超时。

被拒绝的切换请求不影响健康的会话。切换一旦提交，任何失败都会显式报出——绝不退回旧出口。

吊销时效

吊销一个客户端的 egress grant 在 5 秒内生效：该会话进入失败态，每一条经该代理路由的连接都被主动终止，不是放着等它自己超时。