网络代理

OpenClaw 可通过运维人员管理的正向代理路由运行时 HTTP 和 WebSocket 流量。这是一项可选的纵深防御措施：在网络边界实现集中式出站控制、更强的 SSRF 防护和目标审计能力。由于代理会在连接时（即 DNS 解析之后、打开上游连接之前）评估目标，因此也缩小了 DNS 重绑定攻击所依赖的时间窗口，即应用程序先前执行 DNS 检查与实际建立出站连接之间的间隔。统一的代理策略还为运维人员提供了一个集中位置，无需重新构建 OpenClaw 即可实施目标规则、网络分段、速率限制或出站允许列表。

OpenClaw 不会随附、下载、启动、配置或认证任何代理。你需要运行适合自身环境的代理技术；OpenClaw 会通过该代理路由自身的 HTTP 和 WebSocket 客户端。

配置

proxy:  proxyUrl: http://127.0.0.1:3128

也可以通过环境变量设置 URL：

OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run

proxy.proxyUrl 的优先级高于 OPENCLAW_PROXY_URL。配置 URL 后会启用托管代理路由；移除这两个 URL 即会将其禁用。

对于托管 Gateway 网关服务，应将 URL 存储在配置中，使其在重新安装后仍然保留，而不是依赖前台环境变量：

openclaw config set proxy.proxyUrl http://127.0.0.1:3128openclaw gateway install --forceopenclaw gateway start

OPENCLAW_PROXY_URL 环境变量回退最适合前台运行。若要将其用于已安装的服务，请将其放入服务的持久环境中（$OPENCLAW_STATE_DIR/.env，默认为 ~/.openclaw/.env），然后重新安装，以便 launchd/systemd/Scheduled Tasks 获取该变量。

使用私有 CA 的 HTTPS 代理端点

proxy:  proxyUrl: https://proxy.corp.example:8443  tls:    caFile: /etc/openclaw/proxy-ca.pem

proxy.tls.caFile 用于验证代理端点自身的 TLS 证书。它不是目标 MITM 信任设置、客户端证书，也不能替代代理的目标策略。仅当整个 Node 进程必须从启动时信任额外的 CA（例如，企业 TLS 检查系统对每个 HTTPS 目标证书重新签名）时，才应改用 NODE_EXTRA_CA_CERTS——该变量作用于整个进程，并且必须在 Node 启动前设置，因此 OpenClaw 无法像应用 proxy.tls.caFile 那样在运行期间应用它。对于 HTTPS 代理端点信任，优先使用 proxy.tls.caFile：其作用域仅限于托管代理路由，而非整个进程。

openclaw config set proxy.proxyUrl https://proxy.corp.example:8443openclaw config set proxy.tls.caFile /etc/openclaw/proxy-ca.pemopenclaw gateway run

路由工作原理

配置有效的代理 URL 后，受保护的运行时进程（openclaw gateway run、openclaw node run、openclaw agent --local）会通过代理路由普通 HTTP 和 WebSocket 出站流量：

OpenClaw 进程  fetch、node:http、node:https、WebSocket 客户端  -> 运维人员代理 -> 目标

在内部，OpenClaw 会安装 Proxyline 作为进程级路由运行时。它涵盖 fetch、基于 undici 的客户端、node:http/node:https、常见 WebSocket 客户端以及由辅助函数创建的 CONNECT 隧道，并会替换调用方提供的 Node HTTP agent，使显式 agent（包括 axios、got、node-fetch 以及类似的基于 Node agent 的客户端）无法在不引人注意的情况下绕过代理。

代理 URL 的方案描述的是从 OpenClaw 到代理的跃点，而不是到最终目标的跃点：

• http://proxy.example:3128 — 通过明文 TCP 连接到代理；OpenClaw 会发送 HTTP 代理请求，包括针对 HTTPS 目标的 CONNECT。
• https://proxy.example:8443 — OpenClaw 会与代理本身建立 TLS 连接（并验证代理的证书），然后在该会话内发送 HTTP 代理请求。

目标 TLS 与代理端点 TLS 相互独立：对于 HTTPS 目标，OpenClaw 始终要求代理建立 CONNECT 隧道，并通过该隧道启动目标 TLS。

代理处于活动状态时，OpenClaw 会清除 no_proxy/NO_PROXY。这些绕过列表基于目标；如果其中保留 localhost 或 127.0.0.1，SSRF 目标就能完全绕过代理。关闭时，OpenClaw 会恢复先前的代理环境并重置缓存的路由状态。

某些插件拥有自定义传输，即使进程级路由已启用，也需要单独接入代理。Telegram 的 Bot API 客户端使用自己的 HTTP/1 undici dispatcher，并单独遵循进程代理环境变量及 OPENCLAW_PROXY_URL 回退。

Gateway 网关 loopback 模式

本地 Gateway 网关控制平面客户端通常连接到 loopback WebSocket，例如 ws://127.0.0.1:18789。proxy.loopbackMode 控制此流量是否绕过托管代理：

proxy:  proxyUrl: http://127.0.0.1:3128  loopbackMode: gateway-only # gateway-only、proxy 或 block

配置 proxyUrl 或 OPENCLAW_PROXY_URL 会启用托管路由。仅在需要保留 URL 但不启用它的高级选择性退出场景中，才设置 proxy.enabled: false。

Gateway 网关控制平面绕过仅限于 localhost 和字面量 loopback IP URL——请使用 ws://127.0.0.1:18789、ws://[::1]:18789 或 ws://localhost:18789。其他主机名按普通流量进行路由。

容器

对于 openclaw --container ... 命令，设置 OPENCLAW_PROXY_URL 后，OpenClaw 会将其转发到以容器为目标的子 CLI。该 URL 必须能从容器内部访问——其中的 127.0.0.1 指容器本身，而不是主机。对于以容器为目标的命令，OpenClaw 会拒绝 loopback 代理 URL，除非设置 OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1 以显式覆盖此检查。

相关代理术语

• proxy.enabled / proxy.proxyUrl — 用于运行时出站流量的出站正向代理路由。即本页所述内容。
• gateway.auth.mode: "trusted-proxy" — 用于访问 Gateway 网关的入站身份感知反向代理身份验证。请参阅可信代理身份验证。
• openclaw proxy — 用于开发和支持的本地调试代理及流量捕获检查器。请参阅 openclaw proxy。
• tools.web.fetch.useTrustedEnvProxy — web_fetch 的选择性启用项，允许运维人员控制的 HTTP(S) 环境代理执行 DNS 解析，同时默认保持严格的 DNS 固定和主机名策略。请参阅 Web fetch。
• 渠道或提供商专用代理设置 — 针对单一传输的所有者专用覆盖。若要对整个运行时实施集中式出站控制，请优先使用托管网络代理。

验证代理

代理的目标策略才是真正的安全边界；OpenClaw 无法验证你的代理是否拦截了正确的目标。应将其配置为：

• 仅绑定到 loopback 或受信任的私有接口，并且只有 OpenClaw 进程/主机/容器/服务账号可以访问。
• 由代理自行解析目标，并在 DNS 解析后的连接时按 IP 拦截，包括明文 HTTP 和 HTTPS CONNECT 隧道。
• 拒绝针对 loopback、私有地址、链路本地地址、元数据地址、多播地址、保留地址和文档地址范围的目标绕过。
• 除非完全信任 DNS 解析路径，否则避免使用主机名允许列表。
• 记录目标、决策、状态和原因——绝不记录请求正文、授权标头、Cookie 或其他机密信息。
• 将策略纳入版本控制，并将策略变更作为安全敏感变更进行审查。

从运行 OpenClaw 的同一主机/容器/服务账号进行验证：

openclaw proxy validate --proxy-url http://127.0.0.1:3128

使用私有 CA 的 HTTPS 代理端点：

openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem

如果没有可用的配置、环境变量或 --proxy-url 值，该命令会报告配置问题；在更改配置之前，可传入 --proxy-url 进行一次性预检。

未提供 --allowed-url/--denied-url 时，默认检查为：https://example.com/ 必须成功，并且代理必须无法访问一个临时的 loopback 金丝雀服务器。发生传输失败时，或者收到不含该金丝雀单次运行令牌的非 2xx 响应时，loopback 检查通过；如果收到缺少令牌的 2xx 响应（表示金丝雀之外的某个服务意外成功响应），检查失败；尤其是当任何响应携带匹配令牌时，检查会失败，因为这证明代理确实转发了本应拒绝的 loopback 目标。自定义 --denied-url 目标没有此类金丝雀令牌，因此采用失败关闭策略：任何 HTTP 响应都视为目标可达（失败），而传输错误会报告为无法确定，而非已证实阻止，因为 OpenClaw 无法确认是代理拒绝了一个本来可达的源站，还是发生了其他错误。--apns-reachable 会发送一个刻意设置为无效的提供商令牌，因此 403 InvalidProviderToken 响应可视为隧道已到达 Apple 的证明。任何验证失败都会使该命令以 1 退出；文本和 JSON 输出中的代理 URL 凭据都会被脱敏。

{  "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 检查（公共请求应成功；loopback 和元数据请求应由代理本身阻止——仅凭 curl 无法像 openclaw proxy validate 的内置金丝雀那样，区分代理拒绝与源站不可达）：

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 自身的 SSRF 分类器位于 src/infra/net/ssrf.ts 和 packages/net-policy/src/ip.ts（BLOCKED_HOSTNAMES、BLOCKED_IPV4_SPECIAL_USE_RANGES、BLOCKED_IPV6_SPECIAL_USE_RANGES、RFC 2544 基准测试前缀，以及对 NAT64/6to4/Teredo/ISATAP/IPv4 映射形式中嵌入式 IPv4 的处理）——这些是有用的参考，但 OpenClaw 不会在你的外部代理中导出或强制执行这些规则。

请添加你的云提供商或网络平台文档中列出的任何其他元数据主机或保留范围。

限制

• 这是针对 JavaScript HTTP/WebSocket 客户端的进程级覆盖，而不是操作系统级网络沙箱。
• 原始 net、tls、http2 套接字、原生附加组件和非 OpenClaw 子进程可能绕过 Node 级路由，除非它们继承并遵循代理环境变量。派生的 OpenClaw 子 CLI 会继承托管代理 URL 和 proxy.loopbackMode 状态。
• 用户的本地 WebUI 和本地模型服务器不受通用本地网络绕过机制覆盖——如有需要，请在操作员代理策略中将其加入允许列表。唯一例外是内置 Ollama 记忆嵌入提供商受保护的直连路径，其范围仅限于配置的 baseUrl 所指向的、与主机处于同一设备的确切 loopback 源站；LAN、tailnet、私有网络和公共 Ollama 主机仍使用托管代理。
• 托管代理模式启用时，本地调试代理的直接上游转发（用于代理请求和 CONNECT 隧道）默认禁用；仅应为经批准的本地诊断启用。
• OpenClaw 不会检查、测试或认证你的代理策略。请将代理策略更改视为安全敏感的运维变更。