网络代理

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

为什么使用代理

• 集中策略：维护一套出站策略，而不是依赖每个应用 HTTP 调用点都正确处理网络规则。
• 连接时检查：在 DNS 解析之后、代理打开上游连接之前立即评估目标。
• DNS 重绑定防御：缩小应用级 DNS 检查与实际出站连接之间的间隙。
• 更广泛的 JavaScript 覆盖：通过同一路径路由普通的 fetch、node:http、node:https、WebSocket、axios、got、node-fetch 以及类似客户端。
• 可审计性：在出站边界记录允许和拒绝的目标。
• 运维控制：无需重建 OpenClaw 即可强制执行目标规则、网络分段、速率限制或出站允许列表。

​

OpenClaw 如何路由流量

OpenClaw process
  fetch                  -> operator-managed filtering proxy -> public internet
  node:http and https    -> operator-managed filtering proxy -> public internet
  WebSocket clients      -> operator-managed filtering proxy -> public internet

• Undici dispatcher 路由覆盖 fetch、基于 undici 的客户端，以及提供自身 undici dispatcher 的传输。
• global-agent 路由覆盖 Node 核心 node:http 和 node:https 调用方，包括许多基于 http.request、https.request、http.get 和 https.get 分层构建的库。托管代理模式会强制使用该全局 agent，因此显式 Node HTTP agent 不会意外绕过运维人员的代理。

​

相关代理术语

• proxy.enabled / proxy.proxyUrl：OpenClaw 运行时出站流量的出站正向代理路由。此页面记录该功能。
• gateway.auth.mode: "trusted-proxy"：用于 Gateway 网关访问的入站身份感知反向代理认证。请参阅 受信任代理认证。
• openclaw proxy：用于开发和支持的本地调试代理与捕获检查器。请参阅 openclaw proxy。
• tools.web.fetch.useTrustedEnvProxy：为 web_fetch 选择启用，让运维人员控制的 HTTP(S) 环境代理解析 DNS，同时保留默认的严格 DNS 固定和主机名策略。请参阅 Web fetch。
• 渠道或提供商专属代理设置：特定传输的所有者专属覆盖。当目标是在整个运行时集中控制出站流量时，优先使用托管网络代理。

​

配置

proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128

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

​

Gateway 网关回环模式

proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128
  loopbackMode: gateway-only # gateway-only, proxy, or block

• gateway-only（默认）：OpenClaw 会在活动的 global-agent NO_PROXY 控制器中注册 Gateway 网关回环 authority，因此本地 Gateway 网关 WebSocket 流量可以直接连接。自定义回环 Gateway 网关端口可用，因为活动 Gateway 网关 URL 的主机和端口会被注册。
• proxy：OpenClaw 不会注册 Gateway 网关回环 NO_PROXY authority，因此本地 Gateway 网关流量会发送到托管代理。如果代理是远程的，它必须为 OpenClaw 主机的回环服务提供特殊路由，例如将其映射到代理可访问的主机名、IP 或隧道。标准远程代理会从代理主机解析 127.0.0.1 和 localhost，而不是从 OpenClaw 主机解析。
• block：OpenClaw 会在打开套接字之前拒绝回环 Gateway 网关控制平面连接。

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 进程、主机、容器或服务账户可以使用它。
• 自行解析目标，并在 DNS 解析后阻止目标 IP。
• 在连接时对普通 HTTP 请求和 HTTPS CONNECT 隧道都应用策略。
• 拒绝基于目标的绕过，覆盖回环、私有、链路本地、元数据、多播、保留或文档范围。
• 避免使用主机名允许列表，除非你完全信任 DNS 解析路径。
• 记录目标、决策、状态和原因，但不记录请求正文、授权标头、cookie 或其他秘密。
• 将代理策略置于版本控制下，并像审查安全敏感配置一样审查更改。

​

建议阻止的目标

​

验证

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

{
  "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 -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 config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway run

proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128

​

限制

• 该代理提升了对进程本地 JavaScript HTTP 和 WebSocket 客户端的覆盖范围，但它不是操作系统级网络沙箱。
• Gateway 网关环回控制平面流量默认通过 proxy.loopbackMode: "gateway-only" 直接本地绕过。OpenClaw 通过在托管的 global-agent NO_PROXY 控制器中注册活动 Gateway 网关环回 authority 来实现该绕过。操作员可以设置 proxy.loopbackMode: "proxy"，通过托管代理发送 Gateway 网关环回流量；或设置 proxy.loopbackMode: "block"，拒绝环回 Gateway 网关连接。有关远程代理注意事项，请参阅 Gateway 网关环回模式。
• 原始 net、tls 和 http2 套接字、原生插件以及非 OpenClaw 子进程可能绕过 Node 级代理路由，除非它们继承并遵守代理环境变量。派生的 OpenClaw 子 CLI 会继承托管代理 URL 和 proxy.loopbackMode 状态。
• IRC 是操作员管理的正向代理路由之外的原始 TCP/TLS 渠道。在要求所有出站流量都通过该正向代理的部署中，除非明确批准直接 IRC 出站，否则请设置 channels.irc.enabled=false。
• 本地调试代理是诊断工具；托管代理模式处于活动状态时，它针对代理请求和 CONNECT 隧道的直接上游转发默认禁用；仅为已批准的本地诊断启用直接转发。
• 需要时，应在操作员代理策略中允许用户本地 WebUI 和本地模型服务器；OpenClaw 不会为它们暴露通用本地网络绕过。
• Gateway 网关控制平面代理绕过有意仅限于 localhost 和字面量环回 IP URL。对于本地直接 Gateway 网关控制平面连接，请使用 ws://127.0.0.1:18789、ws://[::1]:18789 或 ws://localhost:18789；其他主机名会像普通基于主机名的流量一样路由。
• OpenClaw 不会检查、测试或认证你的代理策略。
• 将代理策略更改视为安全敏感的运维更改。