Network Proxy Configuration for OpenClaw Runtime

OpenClaw can send its runtime HTTP and WebSocket traffic through an operator-managed forward proxy. This serves as optional defense in depth: centralized egress control, enhanced SSRF protection, and network-boundary destination auditing. Since the proxy checks the destination at connect time, after DNS resolution and right before opening the upstream connection, it also reduces the window a DNS-rebinding attack exploits between an earlier app-level DNS check and the actual outbound connection. A unified proxy policy also gives operators a single spot to enforce destination rules, network segmentation, rate limits, or outbound allowlists without rebuilding OpenClaw.

OpenClaw does not provide, download, launch, configure, or validate any proxy. You run the proxy technology that suits your setup; OpenClaw directs its own HTTP and WebSocket clients through it.

Configuration

proxy:
  proxyUrl: http://127.0.0.1:3128

The URL can also be supplied via the environment:

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

proxy.proxyUrl overrides OPENCLAW_PROXY_URL. When a URL is set, managed proxy routing is enabled; clearing both URLs turns it off.

For managed gateway services, save the URL in config so it persists across reinstalls, rather than depending on the foreground env:

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

The OPENCLAW_PROXY_URL env fallback suits foreground runs best. To use it with an installed service, place it in the service's durable environment ($OPENCLAW_STATE_DIR/.env, default ~/.openclaw/.env), then reinstall so launchd/systemd/Scheduled Tasks picks it up. This variable is copied into the generated service environment instead of being tracked as a managed dotenv key, so systemd's restart-only managed dotenv refresh does not apply.

HTTPS proxy endpoint with a private CA

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

proxy.tls.caFile validates the TLS certificate of the proxy endpoint itself. 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 instead only when the entire Node process must trust an additional CA from startup (for example, an enterprise TLS-inspection system re-signing every HTTPS destination certificate), that variable is process-global and must be set before Node starts, so OpenClaw cannot apply it mid-run the way it applies proxy.tls.caFile. Prefer proxy.tls.caFile for HTTPS proxy endpoint trust: it is scoped to managed proxy routing instead of the whole process.

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

How routing works

With a valid proxy URL, protected runtime processes (openclaw gateway run, openclaw node run, openclaw agent --local) route normal HTTP and WebSocket egress through the proxy:

OpenClaw process
  fetch, node:http, node:https, WebSocket clients  -> operator proxy -> destination

Internally, OpenClaw installs Proxyline as the process-level routing runtime. It covers fetch, undici-backed clients, node:http/node:https, common WebSocket clients, and helper-created CONNECT tunnels, and it replaces caller-provided Node HTTP agents so explicit agents (including axios, got, node-fetch, and similar Node-agent-based clients) cannot silently bypass the proxy.

The proxy URL scheme describes the hop from OpenClaw to the proxy, not to the final destination:

• http://proxy.example:3128, plain TCP to the proxy; OpenClaw sends HTTP proxy requests, including CONNECT for HTTPS destinations.
• https://proxy.example:8443, OpenClaw opens TLS to the proxy itself (verifying the proxy's certificate), then sends HTTP proxy requests inside that session.

Destination TLS is independent of proxy-endpoint TLS: for an HTTPS destination, OpenClaw always asks the proxy for a CONNECT tunnel and starts destination TLS through that tunnel.

While the proxy is active, OpenClaw clears no_proxy/NO_PROXY. Those bypass lists are destination-based; leaving localhost or 127.0.0.1 there would let SSRF targets skip the proxy entirely. On shutdown, OpenClaw restores the prior proxy environment and resets cached routing state.

Some plugins own a custom transport that needs its own proxy wiring even with process-level routing active. Telegram's Bot API client uses its own HTTP/1 undici dispatcher and separately honors process proxy env plus the OPENCLAW_PROXY_URL fallback.

Gateway loopback mode

Local Gateway control-plane clients normally connect to a loopback WebSocket such as ws://127.0.0.1:18789. proxy.loopbackMode controls whether that traffic bypasses the managed proxy:

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

A configured proxyUrl or OPENCLAW_PROXY_URL enables managed routing. Set proxy.enabled: false only as an advanced opt-out that keeps the URL stored without activating it.

Gateway control-plane bypass applies only to localhost and literal loopback IP URLs, so stick with ws://127.0.0.1:18789, ws://[::1]:18789, or ws://localhost:18789. Any other hostname follows the same path as normal traffic.

Containers

When openclaw --container ... commands are issued, OpenClaw passes OPENCLAW_PROXY_URL along to the container-targeted child CLI if that value is set. That URL has to be reachable from within the container, since 127.0.0.1 points at the container itself, not the host. Loopback proxy URLs get rejected for container-targeted commands unless OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1 is set to explicitly override that behavior.

Related proxy terms

• proxy.enabled / proxy.proxyUrl, handles outbound forward-proxy routing for runtime egress. This page.
• gateway.auth.mode: "trusted-proxy", inbound identity-aware reverse-proxy authentication for Gateway access. Refer to Trusted proxy auth.
• openclaw proxy, local debug proxy and capture inspector for development and support. Refer to openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy, opt-in for web_fetch so an operator-controlled HTTP(S) env proxy can handle DNS resolution while strict DNS pinning and hostname policy stay on by default. Refer to Web fetch.
• Channel- or provider-specific proxy settings, owner-specific overrides for a single transport. Prefer the managed network proxy for centralized egress control across the runtime.

Validating the proxy

The proxy's destination policy is the real security boundary; OpenClaw can't confirm that your proxy blocks the right targets. Set it up to:

• Bind only to loopback or a private trusted interface, reachable solely by the OpenClaw process/host/container/service account.
• Resolve destinations itself and block by IP after DNS resolution, at connect time, for both plain HTTP and HTTPS CONNECT tunnels.
• Reject destination-based bypasses for loopback, private, link-local, metadata, multicast, reserved, and documentation ranges.
• Avoid hostname allowlists unless you fully trust the DNS resolution path.
• Log destination, decision, status, and reason, never request bodies, authorization headers, cookies, or other secrets.
• Keep the policy under version control and review changes as security-sensitive.

Validate from the same host/container/service account that runs OpenClaw:

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

With a private-CA HTTPS proxy endpoint:

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

If no config, environment, or --proxy-url value is available, the command reports a config problem; pass --proxy-url for a one-off preflight before changing config.

With no --allowed-url/--denied-url, the default checks are: https://example.com/ must succeed, and a temporary loopback canary server the proxy must not reach must be blocked. The loopback check passes on a transport failure, or on a non-2xx response that lacks the canary's per-run token; it fails on a 2xx response missing the token (an unexpected success from something other than the canary) and, especially, on any response carrying the matching token, since that proves the proxy actually forwarded a loopback destination it should have denied. Custom --denied-url targets have no such canary token, so they are fail-closed: any HTTP response counts as reachable (fail), and a transport error is reported as inconclusive rather than proven-blocked, because OpenClaw cannot confirm your proxy denied a reachable origin versus something else going wrong. --apns-reachable sends an intentionally invalid provider token, so a 403 InvalidProviderToken response counts as proof the tunnel reached Apple. The command exits 1 on any validation failure; proxy URL credentials are redacted from both 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 }
  ]
}

Manual curl check (the public request should succeed; the loopback and metadata requests should be blocked by the proxy itself, curl alone cannot distinguish a proxy denial from an unreachable origin the way openclaw proxy validate's built-in canary can):

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/

Recommended blocked destinations

Starting denylist for any forward proxy, firewall, or egress policy. OpenClaw's own SSRF classifier lives in src/infra/net/ssrf.ts and packages/net-policy/src/ip.ts (BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, the RFC 2544 benchmark prefix, and embedded-IPv4 handling for NAT64/6to4/Teredo/ISATAP/IPv4-mapped forms), useful references, but OpenClaw does not export or enforce these rules in your external proxy.

Include any extra metadata hosts or reserved ranges that your cloud provider or network platform documents.

Limits

• This coverage applies at the process level for JavaScript HTTP/WebSocket clients, not as an OS-level network sandbox.
• Raw net, tls, http2 sockets, native addons, and non-OpenClaw child processes may bypass Node-level routing unless they inherit and respect proxy environment variables. Forked OpenClaw child CLIs inherit the managed proxy URL and proxy.loopbackMode state.
• User local WebUIs and local model servers are not covered by a general local-network bypass, allowlist them in the operator proxy policy if needed. The exception is the bundled Ollama memory embedding provider's guarded direct path, scoped to the exact host-local loopback origin from its configured baseUrl; LAN, tailnet, private-network, and public Ollama hosts still use the managed proxy.
• The local debug proxy's direct upstream forwarding (for proxy requests and CONNECT tunnels) is disabled by default while managed proxy mode is active; enable it only for approved local diagnostics.
• OpenClaw does not inspect, test, or certify your proxy policy. Treat proxy policy changes as security-sensitive operational changes.