Network proxy

OpenClaw can route runtime HTTP and WebSocket traffic through an operator-managed forward proxy. This is optional defense in depth for deployments that want central egress control, stronger SSRF protection, and better network auditability.

OpenClaw does not ship, download, start, configure, or certify a proxy. You run the proxy technology that fits your environment, and OpenClaw routes normal process-local HTTP and WebSocket clients through it.

Why use a proxy

A proxy gives operators one network control point for outbound HTTP and WebSocket traffic. That can be useful even outside SSRF hardening:

• Central policy: maintain one egress policy instead of relying on every application HTTP call site to get network rules right.
• Connect-time checks: evaluate the destination after DNS resolution and immediately before the proxy opens the upstream connection.
• DNS rebinding defense: reduce the gap between an application-level DNS check and the actual outbound connection.
• Broader JavaScript coverage: route ordinary fetch, node:http, node:https, WebSocket, axios, got, node-fetch, and similar clients through the same path.
• Auditability: log allowed and denied destinations at the egress boundary.
• Operational control: enforce destination rules, network segmentation, rate limits, or outbound allowlists without rebuilding OpenClaw.

Proxy routing is a process-level guardrail for normal HTTP and WebSocket egress. It gives operators a fail-closed path for routing supported JavaScript HTTP clients through their own filtering proxy, but it is not an OS-level network sandbox and does not make OpenClaw certify the proxy's destination policy.

How OpenClaw routes traffic

When proxy.enabled=true and a proxy URL is configured, protected runtime processes such as openclaw gateway run, openclaw node run, and openclaw agent --local route normal HTTP and WebSocket egress through the configured proxy:

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

The public contract is the routing behavior, not the internal Node hooks used to implement it. OpenClaw Gateway control-plane WebSocket clients use a narrow direct path for local loopback Gateway RPC traffic when the Gateway URL uses localhost or a literal loopback IP such as 127.0.0.1 or [::1]. That control-plane path must be able to reach loopback Gateways even when the operator proxy blocks loopback destinations. Normal runtime HTTP and WebSocket requests still use the configured proxy.

Internally, OpenClaw installs Proxyline as the process-level routing runtime for this feature. Proxyline covers fetch, undici-backed clients, Node core node:http / node:https callers, common WebSocket clients, and helper-created CONNECT tunnels. Managed proxy mode replaces caller-provided Node HTTP agents so explicit agents do not accidentally bypass the operator proxy.

Some plugins own custom transports that need explicit proxy wiring even when process-level routing exists. For example, Telegram's Bot API transport uses its own HTTP/1 undici dispatcher and therefore honors process proxy env plus the managed OPENCLAW_PROXY_URL fallback in that owner-specific transport path.

The proxy URL itself can use either http:// or https://. These schemes describe the connection from OpenClaw to the proxy endpoint:

• http://proxy.example:3128: OpenClaw opens a plain TCP connection to the forward proxy and sends HTTP proxy requests, including CONNECT for HTTPS destinations.
• https://proxy.example:8443: OpenClaw opens TLS to the proxy endpoint, verifies the proxy certificate, and then sends HTTP proxy requests inside that TLS session.

Destination HTTPS is separate from proxy endpoint TLS. For an HTTPS destination, OpenClaw still asks the proxy for an HTTP CONNECT tunnel and then starts destination TLS through that tunnel.

While the proxy is active, OpenClaw clears no_proxy and NO_PROXY. Those bypass lists are destination-based, so leaving localhost or 127.0.0.1 there would let high-risk SSRF targets skip the filtering proxy.

On shutdown, OpenClaw restores the previous proxy environment and resets cached process routing state.

Related proxy terms

• proxy.enabled / proxy.proxyUrl: outbound forward-proxy routing for OpenClaw runtime egress. This page documents that feature.
• gateway.auth.mode: "trusted-proxy": inbound identity-aware reverse-proxy authentication for Gateway access. See Trusted proxy auth.
• openclaw proxy: local debug proxy and capture inspector for development and support. See openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy: opt-in for web_fetch to let an operator-controlled HTTP(S) env proxy resolve DNS while keeping default strict DNS pinning and hostname policy. See Web fetch.
• Channel or provider-specific proxy settings: owner-specific overrides for a particular transport. Prefer the managed network proxy when the goal is central egress control across the runtime.

Configuration

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

For an HTTPS proxy endpoint with a private proxy CA:

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

You can also provide the URL through the environment, while keeping proxy.enabled=true in config:

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

proxy.proxyUrl takes precedence over OPENCLAW_PROXY_URL.

Gateway Loopback Mode

Local Gateway control-plane clients usually connect to a loopback WebSocket such as ws://127.0.0.1:18789. Use proxy.loopbackMode to choose how that traffic behaves while the managed proxy is active:

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

• gateway-only (default): OpenClaw registers the Gateway loopback authority in Proxyline's managed bypass policy so local Gateway WebSocket traffic can connect directly. Custom loopback Gateway ports work because the active Gateway URL's host and port are registered.
• proxy: OpenClaw does not register a Gateway loopback bypass, so local Gateway traffic is sent through the managed proxy. If the proxy is remote, it must provide special routing for the OpenClaw host's loopback service, such as mapping it to a proxy-reachable hostname, IP, or tunnel. Standard remote proxies resolve 127.0.0.1 and localhost from the proxy host, not from the OpenClaw host.
• block: OpenClaw denies loopback Gateway control-plane connections before opening a socket.

If enabled=true but no valid proxy URL is configured, protected commands fail startup instead of falling back to direct network access.

For managed gateway services started with openclaw gateway start, prefer storing the URL in config:

openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway install --force
openclaw gateway start

The environment fallback is best for foreground runs. If you use it with an installed service, put OPENCLAW_PROXY_URL in the service durable environment, such as $OPENCLAW_STATE_DIR/.env or ~/.openclaw/.env, then reinstall the service so launchd, systemd, or Scheduled Tasks starts the gateway with that value.

For openclaw --container ... commands, OpenClaw forwards OPENCLAW_PROXY_URL into the container-targeted child CLI when it is set. The URL must be reachable from inside the container; 127.0.0.1 refers to the container itself, not the host. OpenClaw rejects loopback proxy URLs for container-targeted commands unless you explicitly override that safety check.

Proxy Requirements

The proxy policy is the security boundary. OpenClaw cannot verify that the proxy blocks the right targets.

Configure the proxy to:

• Bind only to loopback or a private trusted interface.
• Restrict access so only the OpenClaw process, host, container, or service account can use it.
• Resolve destinations itself and block destination IPs after DNS resolution.
• Apply policy at connect time for both plain HTTP requests and HTTPS CONNECT tunnels.
• Reject destination-based bypasses for loopback, private, link-local, metadata, multicast, reserved, or documentation ranges.
• Avoid hostname allowlists unless you fully trust the DNS resolution path.
• Log destination, decision, status, and reason without logging request bodies, authorization headers, cookies, or other secrets.
• Keep proxy policy under version control and review changes like security-sensitive configuration.

Recommended blocked destinations

Use this denylist as the starting point for any forward proxy, firewall, or egress policy.

OpenClaw application-level classifier logic lives in src/infra/net/ssrf.ts and src/shared/net/ip.ts. The relevant parity hooks are BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, RFC2544_BENCHMARK_PREFIX, and the embedded IPv4 sentinel handling for NAT64, 6to4, Teredo, ISATAP, and IPv4-mapped forms. Those files are useful references when maintaining an external proxy policy, but OpenClaw does not automatically export or enforce those rules in your proxy.

If your cloud provider or network platform documents additional metadata hosts or reserved ranges, add those too.

Validation

Validate the proxy from the same host, container, or service account that runs OpenClaw:

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

For an HTTPS proxy endpoint signed by a private CA:

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

By default, when no custom destinations are provided, the command checks that https://example.com/ succeeds and starts a temporary loopback canary that the proxy must not reach. The default denied check passes when the proxy returns a non-2xx denial response or blocks the canary with a transport failure; it fails if a successful response reaches the canary. If no proxy is enabled and configured, validation reports a config problem; use --proxy-url for a one-off preflight before changing config. Use --allowed-url and --denied-url to test deployment-specific expectations. Add --apns-reachable to also verify direct APNs HTTP/2 delivery can open a CONNECT tunnel through the proxy and receive a sandbox APNs response; the probe uses an intentionally invalid provider token, so 403 InvalidProviderToken is expected and counts as reachable. Custom denied destinations are fail-closed: any HTTP response means the destination was reachable through the proxy, and any transport error is reported as inconclusive because OpenClaw cannot prove the proxy blocked a reachable origin. On validation failure, the command exits with code 1.

Use --json for automation. The JSON output contains the overall result, the effective proxy config source, any config errors, and each destination check. Proxy URL credentials are redacted in text and JSON output:

{
  "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
    }
  ]
}

You can also validate manually with curl:

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/

The public request should succeed. The loopback and metadata requests should be blocked by the proxy. For openclaw proxy validate, the built-in loopback canary can distinguish a proxy denial from a reachable origin. Custom --denied-url checks do not have that canary, so treat both HTTP responses and ambiguous transport failures as validation failures unless your proxy exposes a deployment-specific denial signal you can verify separately.

Proxy CA trust

Use managed proxy.tls.caFile when the proxy endpoint itself uses a certificate signed by a private CA:

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

That CA is used for TLS verification of the proxy endpoint. It is not a destination MITM trust setting, a client certificate, or a replacement for the proxy's destination policy.

Use NODE_EXTRA_CA_CERTS only when the whole Node process must trust an additional CA from process startup, such as when an enterprise TLS inspection system re-signs destination certificates for every HTTPS client in the process. NODE_EXTRA_CA_CERTS is process-global and must be present before Node starts. Prefer proxy.tls.caFile for HTTPS proxy endpoint trust because it is scoped to managed proxy routing.

Then enable OpenClaw proxy routing:

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

or set:

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

Limits

• The proxy improves coverage for process-local JavaScript HTTP and WebSocket clients, but it is not an OS-level network sandbox.
• Gateway loopback control-plane traffic defaults to direct local bypass through proxy.loopbackMode: "gateway-only". OpenClaw implements that bypass by registering the active Gateway loopback authority in Proxyline's managed bypass policy. Operators can set proxy.loopbackMode: "proxy" to send Gateway loopback traffic through the managed proxy, or proxy.loopbackMode: "block" to deny loopback Gateway connections. See Gateway Loopback Mode for the remote-proxy caveat.
• Raw net, tls, and http2 sockets, native addons, and non-OpenClaw child processes may bypass Node-level proxy routing unless they inherit and respect proxy environment variables. Forked OpenClaw child CLIs inherit the managed proxy URL and proxy.loopbackMode state.
• IRC is a raw TCP/TLS channel outside operator-managed forward proxy routing. In deployments that require all egress through that forward proxy, set channels.irc.enabled=false unless direct IRC egress is explicitly approved.
• The local debug proxy is diagnostic tooling and its direct upstream forwarding for proxy requests and CONNECT tunnels is disabled by default while managed proxy mode is active; enable direct forwarding only for approved local diagnostics.
• User local WebUIs and local model servers should be allowlisted in the operator proxy policy when needed; OpenClaw does not expose a general local-network bypass for them.
• Gateway control-plane proxy bypass is intentionally limited to localhost and literal loopback IP URLs. Use ws://127.0.0.1:18789, ws://[::1]:18789, or ws://localhost:18789 for local direct Gateway control-plane connections; other hostnames route like ordinary hostname-based traffic.
• OpenClaw does not inspect, test, or certify your proxy policy.
• Treat proxy policy changes as security-sensitive operational changes.