Appearance
OpenClaw 支持将运行时 HTTP 和 WebSocket 流量通过操作者管理的转发代理路由，用于加强 SSRF 防御、DNS 重绑定防护和集中出口控制。关键操作：在配置中设置 proxy.enabled=true 与 proxy.proxyUrl，或通过 OPENCLAW_PROXY_URL 环境变量指定；使用 openclaw proxy validate --proxy-url 验证代理可达性和阻断规则；注意代理不覆盖原始 net/tls/http2 套接字及 IRC 通道，网关控制面默认绕过代理（可通过 proxy.loopbackMode 调整）。
OpenClaw 网络代理配置与验证
OpenClaw 可以将运行时的 HTTP 和 WebSocket 流量路由到操作者管理的转发代理。这是一个可选的深度防御手段，适用于需要集中出口控制、更强 SSRF 防护和更好网络审计能力的部署。
OpenClaw 自身不提供、下载、启动、配置或认证代理。你需要运行适合自己环境的代理技术，OpenClaw 会将进程内的普通 HTTP、HTTPS 和 WebSocket 客户端通过该代理转发。
为什么使用代理
代理为操作者提供了出站 HTTP 和 WebSocket 流量的单一网络控制点。即使不强化 SSRF，它也有以下价值：
- 集中策略：维护一个统一的出口策略，而不是依赖每个应用 HTTP 调用点自己遵守网络规则。
- 连接时检查：在 DNS 解析之后、代理打开上游连接之前，对目标进行评估。
- DNS 重绑定防御：缩小应用层 DNS 检查与实际出站连接之间的时间差。
- 更广的 JavaScript 覆盖：将普通的
fetch、node:http、node:https、WebSocket、axios、got、node-fetch 等客户端路由到同一个路径。 - 可审计性：在出口边界记录允许和拒绝的目标。
- 运营控制：在不重新构建 OpenClaw 的前提下执行目标规则、网络分段、速率限制或出站白名单。
代理路由是进程级别的普通 HTTP 和 WebSocket 出口护栏。它让操作者可以通过自己的过滤代理路由受支持的 JavaScript HTTP 客户端，从而实现故障-关闭路径，但它不是操作系统级别的网络沙箱，也不会让 OpenClaw 认证代理的目标策略。
OpenClaw 如何路由流量
当 proxy.enabled=true 且配置了代理 URL 时，受保护的运行时进程（如 openclaw gateway run、openclaw node run、openclaw agent --local）会将普通 HTTP、HTTPS 和 WebSocket 出口流量通过配置的代理路由：
text
OpenClaw 进程
fetch -> 操作者管理的过滤代理 -> 公网
node:http 和 https -> 操作者管理的过滤代理 -> 公网
WebSocket 客户端 -> 操作者管理的过滤代理 -> 公网公开契约是路由行为，而不是用于实现路由的内部 Node 钩子。当网关 URL 使用 localhost 或字面回环 IP（如 127.0.0.1、[::1]）时，OpenClaw Gateway 的控制面 WebSocket 客户端会使用一条狭窄的直接路径用于本地回环网关 RPC 流量。该控制面路径必须能够到达回环网关，即使操作者代理阻止了回环目标。普通的运行时 HTTP 和 WebSocket 请求仍然使用配置的代理。
内部上，OpenClaw 使用 Proxyline 作为进程级路由运行时。Proxyline 覆盖了 fetch、基于 undici 的客户端、Node 核心的 node:http/node:https 调用方、常见 WebSocket 客户端以及助手创建的 CONNECT 隧道。托管代理模式会替换调用方提供的 Node HTTP 代理，以防止显式代理意外绕过操作者代理。
某些插件拥有自定义传输，这些传输即使存在进程级路由也需要显式代理连接。例如，Telegram 的 Bot API 传输使用自己的 HTTP/1 undici 调度器，因此会遵守进程代理环境变量以及该特定传输路径中的托管 OPENCLAW_PROXY_URL 回退。
代理 URL 本身可以使用 http:// 或 https://。这些方案描述的是从 OpenClaw 到代理端点的连接方式：
http://proxy.example:3128：OpenClaw 打开到转发代理的普通 TCP 连接，发送 HTTP 代理请求（包括针对 HTTPS 目标的CONNECT请求）。https://proxy.example:8443：OpenClaw 打开到代理端点的 TLS，验证代理证书，然后在 TLS 会话内发送 HTTP 代理请求。
目标 HTTPS 与代理端点 TLS 是分开的。对于 HTTPS 目标，OpenClaw 仍向代理请求 HTTP CONNECT 隧道，然后通过该隧道启动目标 TLS。
当代理激活时，OpenClaw 会清除 no_proxy 和 NO_PROXY。这些绕过列表是基于目标的，如果保留 localhost 或 127.0.0.1，则高风险 SSRF 目标可能跳过过滤代理。
关闭时，OpenClaw 会恢复之前的代理环境并重置缓存的进程级路由状态。
相关代理术语
proxy.enabled/proxy.proxyUrl：OpenClaw 运行时出口的转发代理路由。本文档介绍此功能。gateway.auth.mode: "trusted-proxy"：入站身份感知反向代理认证，用于 Gateway 访问。参见 Trusted proxy auth。openclaw proxy：本地调试代理和捕获检查器，用于开发和支持。参见 openclaw proxy。tools.web.fetch.useTrustedEnvProxy：可选的开关，让web_fetch使用操作者控制的 HTTP(S) 环境代理进行 DNS 解析，同时保留默认的严格 DNS 固定和主机名策略。参见 Web fetch。- 渠道或提供者特定的代理设置：特定传输的所有者覆盖。当目标是运行时集中出口控制时，优先使用托管网络代理。
配置
yaml
proxy:
enabled: true
proxyUrl: http://127.0.0.1:3128对于使用私有代理 CA 的 HTTPS 代理端点：
yaml
proxy:
enabled: true
proxyUrl: https://proxy.corp.example:8443
tls:
caFile: /etc/openclaw/proxy-ca.pem你也可以通过环境变量提供 URL，同时保持配置中的 proxy.enabled=true：
bash
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway runproxy.proxyUrl 优先于 OPENCLAW_PROXY_URL。
网关回环模式
本地网关控制面客户端通常连接到回环 WebSocket，例如 ws://127.0.0.1:18789。使用 proxy.loopbackMode 选择在托管代理激活时此类流量的行为：
yaml
proxy:
enabled: true
proxyUrl: http://127.0.0.1:3128
loopbackMode: gateway-only # gateway-only, proxy, 或 blockgateway-only（默认）：OpenClaw 将网关回环 authority 注册到 Proxyline 的托管绕过策略中，因此本地网关 WebSocket 流量可以直接连接。自定义回环网关端口也能工作，因为活动网关 URL 的 host 和端口都会被注册。proxy：OpenClaw 不注册网关回环绕过，因此本地网关流量会通过托管代理发送。如果代理是远程的，它必须为 OpenClaw 主机的回环服务提供特殊路由，比如映射到代理可访问的主机名、IP 或隧道。标准远程代理从代理主机解析127.0.0.1和localhost，而不是从 OpenClaw 主机解析。block：OpenClaw 在打开 socket 之前就拒绝回环网关控制面连接。
如果 enabled=true 但没有有效的代理 URL，受保护的命令会在启动时失败，而不是回退到直接网络访问。
对于通过 openclaw gateway start 启动的托管网关服务，建议将 URL 存储在配置中：
bash
openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway install --force
openclaw gateway start环境变量回退最适合前台运行。如果用于已安装的服务，请将 OPENCLAW_PROXY_URL 放入服务持久化环境中，例如 $OPENCLAW_STATE_DIR/.env 或 ~/.openclaw/.env，然后重新安装服务，以便 launchd、systemd 或 Scheduled Tasks 使用该值启动网关。
对于 openclaw --container ... 命令，当设置了 OPENCLAW_PROXY_URL 时，OpenClaw 会将其转发给容器目标子 CLI。该 URL 必须从容器内部可达；127.0.0.1 指的是容器自身，而不是主机。对于容器目标命令，OpenClaw 会拒绝回环代理 URL，除非你显式覆盖这一安全检查。
代理要求
代理策略是安全边界。OpenClaw 无法验证代理是否阻止了正确的目标。
将代理配置为：
- 仅绑定到回环或私有可信接口。
- 限制访问，只有 OpenClaw 进程、主机、容器或服务账号可以使用它。
- 自行解析目标，并在 DNS 解析后阻止目标 IP。
- 在连接时对普通 HTTP 请求和 HTTPS
CONNECT隧道应用策略。 - 拒绝针对回环、私有、链路本地、元数据、多播、保留或文档范围的目标绕过。
- 除非你完全信任 DNS 解析路径，否则避免使用主机名白名单。
- 记录目标、决定、状态和原因，但不记录请求体、认证头、cookie 或其他机密。
- 将代理策略置于版本控制下，并按安全敏感配置审查更改。
推荐的阻止目标
使用以下阻止列表作为任何转发代理、防火墙或出口策略的起点。OpenClaw 应用层分类逻辑位于 src/infra/net/ssrf.ts 和 src/shared/net/ip.ts。相关的对等钩子是 BLOCKED_HOSTNAMES、BLOCKED_IPV4_SPECIAL_USE_RANGES、BLOCKED_IPV6_SPECIAL_USE_RANGES、RFC2544_BENCHMARK_PREFIX 以及处理 NAT64、6to4、Teredo、ISATAP 和 IPv4 映射形式的嵌入式 IPv4 哨兵。这些文件在维护外部代理策略时是很有用的参考，但 OpenClaw 不会自动将那些规则导出或强制应用于你的代理。
| 范围或主机 | 为什么要阻止 |
|---|---|
127.0.0.0/8, localhost, localhost.localdomain | IPv4 回环 |
::1/128 | IPv6 回环 |
0.0.0.0/8, ::/128 | 未指定和本地网络地址 |
10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 | RFC1918 私有网络 |
169.254.0.0/16, fe80::/10 | 链路本地地址和常见云元数据路径 |
169.254.169.254, metadata.google.internal | 云元数据服务 |
100.64.0.0/10 | 运营商级 NAT 共享地址空间 |
198.18.0.0/15, 2001:2::/48 | 基准测试范围 |
192.0.0.0/24, 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32 | 特殊用途和文档范围 |
224.0.0.0/4, ff00::/8 | 多播 |
240.0.0.0/4 | 保留 IPv4 |
fc00::/7, fec0::/10 | IPv6 本地/私有范围 |
100::/64, 2001:20::/28 | IPv6 丢弃和 ORCHIDv2 范围 |
64:ff9b::/96, 64:ff9b:1::/48 | 包含嵌入式 IPv4 的 NAT64 前缀 |
2002::/16, 2001::/32 | 6to4 和包含嵌入式 IPv4 的 Teredo |
::/96, ::ffff:0:0/96 | IPv4 兼容和 IPv4 映射的 IPv6 |
如果你的云提供者或网络平台记录了额外的元数据主机或保留范围，请一并添加。
验证
从运行 OpenClaw 的同一主机、容器或服务账号验证代理：
bash
openclaw proxy validate --proxy-url http://127.0.0.1:3128对于使用私有 CA 签名的 HTTPS 代理端点：
bash
openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem默认情况下，当未提供自定义目标时，该命令会检查 https://example.com/ 是否成功，并启动一个代理必须无法到达的临时回环 Canary。当代理返回非 2xx 的拒绝响应或通过传输失败阻止 Canary 时，默认拒绝检查通过；如果成功响应到达 Canary，则检查失败。如果未启用且未配置代理，验证会报告配置问题；对于更改配置前的一次性预检，可使用 --proxy-url 参数。使用 --allowed-url 和 --denied-url 测试部署特定的期望。添加 --apns-reachable 还可验证直接 APNs HTTP/2 传递能否通过代理打开 CONNECT 隧道并接收到沙箱 APNs 响应；探针使用故意无效的提供者令牌，因此 403 InvalidProviderToken 是预期的且视为可达。自定义拒绝目标是故障-关闭的：任何 HTTP 响应都意味着该目标通过代理可达，任何传输错误都报告为不确定，因为 OpenClaw 无法证明代理阻止了一个本来可达的源。验证失败时，命令退出码为 1。
使用 --json 进行自动化。JSON 输出包含整体结果、有效的代理配置源、任何配置错误以及每个目标检查。代理 URL 凭据在文本和 JSON 输出中都会被编辑。
json
{
"ok": true,
"config": {
"enabled": true,
"proxyUrl": "http://127.0.0.1:3128/",
"source": "override",
"errors": []
},
"checks": [
{
"kind": "allowed",
"url": "https://example.com/",
"ok": true,
"status": 200
},
{
"kind": "apns",
"url": "https://api.sandbox.push.apple.com",
"ok": true,
"status": 403
}
]
}你也可以使用 curl 手动验证：
bash
curl -x http://127.0.0.1:3128 https://example.com/
curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/对公网的请求应成功。回环和元数据请求应被代理阻止。对于 openclaw proxy validate，内置的回环 Canary 可以区分代理拒绝与可达源。自定义 --denied-url 检查没有那种 Canary，因此请将 HTTP 响应和模糊的传输失败都视为验证失败，除非你的代理暴露了可单独验证的部署特定拒绝信号。
代理 CA 信任
当代理端点本身使用私有 CA 签名的证书时，使用托管的 proxy.tls.caFile：
yaml
proxy:
enabled: true
proxyUrl: https://proxy.corp.example:8443
tls:
caFile: /etc/openclaw/proxy-ca.pem该 CA 用于代理端点的 TLS 验证。它不是目标 MITM 信任设置、客户端证书或代理目标策略的替代品。
仅当整个 Node 进程从启动时就需要信任额外的 CA 时才使用 NODE_EXTRA_CA_CERTS，例如企业 TLS 检查系统为进程中的每个 HTTPS 客户端重新签署目标证书时。NODE_EXTRA_CA_CERTS 是进程全局的，并且必须在 Node 启动前设置。对于 HTTPS 代理端点信任，优先使用 proxy.tls.caFile，因为它仅限于托管代理路由。
然后启用 OpenClaw 代理路由：
bash
openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl https://proxy.corp.example:8443
openclaw config set proxy.tls.caFile /etc/openclaw/proxy-ca.pem
openclaw gateway run或设置：
yaml
proxy:
enabled: true
proxyUrl: https://proxy.corp.example:8443
tls:
caFile: /etc/openclaw/proxy-ca.pem限制
- 代理提高了对进程内 JavaScript HTTP 和 WebSocket 客户端的覆盖范围，但它不是操作系统级别的网络沙箱。
- 网关回环控制面流量默认通过
proxy.loopbackMode: "gateway-only"直接本地绕过。OpenClaw 通过将活动网关回环 authority 注册到 Proxyline 的托管绕过策略来实现该绕过。操作者可以设置proxy.loopbackMode: "proxy"将网关回环流量发送到托管代理，或设置proxy.loopbackMode: "block"拒绝回环网关连接。远程代理的注意事项请参见 网关回环模式。 - 原始
net、tls和http2套接字、原生插件以及非 OpenClaw 的子进程可能绕过 Node 级代理路由，除非它们继承并遵守代理环境变量。分叉的 OpenClaw 子 CLI 会继承托管代理 URL 和proxy.loopbackMode状态。 - IRC 是原始 TCP/TLS 通道，不在操作者管理的转发代理路由范围内。在要求所有出口都通过该转发代理的部署中，除非明确批准直接 IRC 出口，否则应设置
channels.irc.enabled=false。 - 本地调试代理是诊断工具，在托管代理模式激活时，默认禁用其对代理请求和 CONNECT 隧道的直接上游转发；仅在批准用于本地诊断时才启用直接转发。
- 用户本地 WebUI 和本地模型服务器应在操作者代理策略中设入白名单；OpenClaw 不会为它们暴露通用的本地网络绕过。
- 网关控制面代理绕过有意限制为
localhost和字面回环 IP URL。对于本地直接网关控制面连接，请使用ws://127.0.0.1:18789、ws://[::1]:18789或ws://localhost:18789；其他主机名会像普通基于主机名的流量一样路由。 - OpenClaw 不会检查、测试或认证你的代理策略。
- 将代理策略更改视为安全敏感的操作变更。
| 表面 | 托管代理状态 |
|---|---|
fetch, node:http, node:https, 常见 WebSocket 客户端 | 配置后通过托管代理钩子路由。 |
| APNs 直接 HTTP/2 | 通过 APNs 托管的 CONNECT 助手路由。 |
| 网关控制面回环 | 仅对配置的本地回环网关 URL 直接连接。 |
| 调试代理上游转发 | 托管代理模式激活时禁用，除非为本地诊断显式启用。 |
| IRC | 原始 TCP/TLS；不由托管 HTTP 代理模式代理。除非直接 IRC 出口获得批准，否则禁用。 |
其他原始 net、tls 或 http2 客户端调用 | 在落地前必须由原始 socket 守卫分类。 |
常见问题
配置了代理但 OpenClaw 仍然直连公网怎么办？
首先确认 proxy.enabled=true 且 proxy.proxyUrl 有效。使用 openclaw config get proxy 检查当前配置。然后用 openclaw proxy validate --proxy-url <你的代理URL> 验证代理本身工作正常。注意：原始 net、tls、http2 套接字和 IRC 通道不会通过托管代理，请检查是否属于这些情况。
如何让网关控制面流量也走代理？
设置 proxy.loopbackMode: "proxy"。但需要注意，如果代理是远程的，它必须能够路由到 OpenClaw 主机的回环服务（例如通过映射主机名）。默认 gateway-only 模式会让本地回环网关直接连接，不经过代理。
使用 HTTPS 代理端点时提示证书错误怎么办？
如果是私有 CA 签名的证书，配置 proxy.tls.caFile 指向 CA 证书文件。例如 proxy.tls.caFile: /etc/openclaw/proxy-ca.pem。如果是企业 TLS 检查系统，可能需要 NODE_EXTRA_CA_CERTS，但推荐优先使用 proxy.tls.caFile。