Documentation Index

Fetch the complete documentation index at: https://docs.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。
• 渠道或提供商专用代理设置：特定传输协议的 owner 专用覆盖。当目标是在整个运行时集中控制出口流量时，优先使用托管网络代理。

​

配置

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

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

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 客户端的覆盖范围，但它不是 OS 级网络沙箱。
• 原始 net、tls 和 http2 套接字、原生插件以及子进程可能绕过 Node 级代理路由，除非它们继承并遵守代理环境变量。
• IRC 是一个原始 TCP/TLS 渠道，位于操作员管理的正向代理路由之外。在要求所有出站流量都经过该正向代理的部署中，除非已明确批准直接 IRC 出站流量，否则请设置 channels.irc.enabled=false。
• 本地调试代理是诊断工具；在托管代理模式处于活动状态时，默认禁用其对代理请求和 CONNECT 隧道的直接上游转发；仅为已批准的本地诊断启用直接转发。
• 需要时，应在操作员代理策略中允许用户本地 WebUI 和本地模型服务器；OpenClaw 不会为它们公开通用的本地网络绕过机制。
• Gateway 网关控制平面的代理绕过有意限制为 localhost 和字面量回环 IP URL。请使用 ws://127.0.0.1:18789、ws://[::1]:18789 或 ws://localhost:18789 进行本地直连 Gateway 网关控制平面连接；其他主机名会像普通基于主机名的流量一样路由。
• OpenClaw 不会检查、测试或认证你的代理策略。
• 将代理策略更改视为安全敏感的运维更改。