网络代理

​

为什么使用代理

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

​

OpenClaw 如何路由流量

OpenClaw 进程
  fetch                  -> 运维管理的过滤代理 -> 公共互联网
  node:http and https    -> 运维管理的过滤代理 -> 公共互联网
  WebSocket clients      -> 运维管理的过滤代理 -> 公共互联网

• http://proxy.example:3128：OpenClaw 到正向代理建立普通 TCP 连接，并发送 HTTP 代理请求，其中包括针对 HTTPS 目标的 CONNECT。
• https://proxy.example:8443：OpenClaw 到代理端点建立 TLS 连接，验证代理证书，然后在该 TLS 会话中发送 HTTP 代理请求。

​

相关代理术语

• 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

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

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 会在 Proxyline 的受管绕过策略中注册 Gateway 回环权限，以便本地 Gateway WebSocket 流量可以直接连接。自定义的 Gateway 回环端口也可正常工作，因为当前活动 Gateway URL 的主机和端口会被注册。捆绑的浏览器插件还可以为 OpenClaw 启动的受管浏览器注册精确的本地 CDP 就绪和 DevTools WebSocket 端点，而捆绑的 Ollama 记忆嵌入提供程序则可以为精确配置的主机本地回环嵌入来源使用其自身更窄的受保护直连路径。
• proxy：OpenClaw 不会注册 Gateway 或 Ollama 的回环绕过，因此这类回环流量会通过受管代理发送。如果代理是远程的，它必须为 OpenClaw 主机的回环服务提供特殊路由，例如将其映射到代理可达的主机名、IP 或隧道。标准远程代理会从代理主机而不是从 OpenClaw 主机解析 127.0.0.1 和 localhost。
• block：OpenClaw 会在打开 socket 之前拒绝 Gateway 回环控制平面连接和受保护的 Ollama 主机本地嵌入回环连接。

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

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

{
  "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/

​

Proxy CA trust

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

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

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

​

限制

• 代理可扩大进程本地 JavaScript HTTP 和 WebSocket 客户端的覆盖范围，但它不是操作系统级的网络沙箱。
• Gateway 回环控制平面流量默认通过 proxy.loopbackMode: "gateway-only" 直接本地绕过。OpenClaw 通过在 Proxyline 的受管绕过策略中注册活动的 Gateway 回环权限来实现该绕过。运维人员可以将 proxy.loopbackMode 设置为 "proxy"，让 Gateway 回环流量通过受管代理；也可以设置为 "block"，拒绝回环 Gateway 连接。有关远程代理注意事项，请参见 Gateway Loopback Mode。
• 原始 net、tls 和 http2 套接字、原生 addon，以及非 OpenClaw 子进程可能会绕过 Node 级代理路由，除非它们继承并遵守代理环境变量。fork 出来的 OpenClaw 子 CLI 会继承受管代理 URL 和 proxy.loopbackMode 状态。
• IRC 是位于运维人员管理的前向代理路由之外的原始 TCP/TLS 通道。在要求所有出站流量都经过该前向代理的部署中，除非已明确批准直接 IRC 出站，否则请设置 channels.irc.enabled=false。
• 本地调试代理是诊断工具，其针对代理请求和 CONNECT 隧道的直接上游转发在受管代理模式处于活动状态时默认禁用；仅在获得批准的本地诊断中才启用直接转发。
• 当需要时，应在运维人员代理策略中将用户本地 WebUI 和本地模型服务器加入允许列表；OpenClaw 不为它们暴露通用的本地网络绕过。捆绑的 Ollama 内存嵌入提供程序范围更窄：它仅能对由配置的 baseUrl 派生出的、精确的主机本地回环嵌入源使用受保护的直接路径，以便在受管代理无法到达主机回环时，主机本地嵌入仍可正常工作。LAN、tailnet、私有网络和公网的 Ollama 嵌入主机仍使用受管代理路径。proxy.loopbackMode: "proxy" 会将此 Ollama 回环流量通过受管代理发送，而 proxy.loopbackMode: "block" 会在建立连接之前将其拒绝。
• Gateway 控制平面代理绕过有意仅限于 localhost 和字面量回环 IP URL。对本地直连 Gateway 控制平面连接，请使用 ws://127.0.0.1:18789、ws://[::1]:18789 或 ws://localhost:18789；其他主机名会像普通基于主机名的流量一样进行路由。
• OpenClaw 不会检查、测试或认证你的代理策略。
• 请将代理策略更改视为安全敏感的运维变更。