How to Configure Network Proxies in OpenClaw

BlueRock Security analyzed over 7,000 MCP servers in 2026 and found that 36.7% were potentially vulnerable to server-side request forgery (SSRF). One proof-of-concept attack against a cloud-hosted MCP server retrieved AWS credentials from the EC2 metadata endpoint, turning a single unprotected HTTP call into full account access.

OpenClaw agents make outbound HTTP and WebSocket calls constantly: fetching model responses, pulling data from APIs, and communicating with gateways. Without a proxy, every one of those calls goes directly to the internet. Any prompt injection or misconfigured skill could reach internal networks, cloud metadata services, or RFC1918 addresses.

OpenClaw's built-in network proxy solves this by routing all process-local HTTP and WebSocket traffic through an operator-managed forward proxy. You pick the proxy technology (Squid, mitmproxy, a corporate gateway, whatever fits your environment) and OpenClaw handles the plumbing. The proxy becomes your central enforcement point for egress control and SSRF protection.

When the proxy is enabled, three OpenClaw runtime processes route their outbound traffic through it: the gateway, the node, and local agent processes. According to the official proxy documentation, managed routing covers fetch, node:http, node:https, undici-backed clients, common WebSocket implementations, axios, got, and node-fetch. Raw net, tls, and http2 sockets bypass the proxy unless they inherit environment variables on their own.

When the proxy is active, OpenClaw also strips any existing proxy bypass lists from the process environment to prevent accidental routes to sensitive targets. This is an aggressive default designed to close the exact loopholes that SSRF attacks exploit.

OpenClaw uses a YAML configuration block to define proxy behavior. The official proxy documentation covers every field. Here is what a minimal working setup looks like:

proxy:
  enabled: true                    # Turn on managed proxy routing
  proxyUrl: http://127.0.0.1:3128  # Your proxy endpoint (HTTP or HTTPS)
  loopbackMode: gateway-only       # How local gateway traffic is handled
  tls:
    caFile: /etc/openclaw/proxy-ca.pem  # CA cert for HTTPS proxy verification

The proxyUrl field accepts both HTTP (http://proxy.example:3128) and HTTPS (https://proxy.corp.example:8443) schemes. HTTP means a plain TCP connection with HTTP proxy requests. HTTPS means a TLS-encrypted connection to the proxy endpoint itself, with certificate verification against the system trust store or the configured caFile.

You can set these values using the CLI instead of editing the config file directly:

openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw config set proxy.tls.caFile /path/to/ca.pem

For foreground runs, you can also pass the proxy URL as an environment variable:

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

The OPENCLAW_PROXY_URL environment variable acts as a fallback when proxy.proxyUrl is not set in the config file. If both exist, the config file takes precedence.

For installed services (systemd, launchd), place OPENCLAW_PROXY_URL in $OPENCLAW_STATE_DIR/.env or ~/.openclaw/.env, then reinstall the service so it picks up the new variable.

Container-targeted commands forward OPENCLAW_PROXY_URL into the container's child CLI automatically. One important caveat: the URL must be reachable from inside the container. A 127.0.0.1 in the proxy URL refers to the container itself, not the host. Container commands also reject loopback proxy URLs by default unless you explicitly override that behavior.

The loopbackMode setting controls how OpenClaw handles local gateway control-plane traffic. There are three options, and the right choice depends on your deployment topology.

gateway-only (default)

OpenClaw registers the gateway loopback authority in Proxyline's managed bypass policy for direct connections. Local gateway traffic skips the proxy entirely. This is the right choice for most single-machine deployments where the gateway and proxy run on the same host.

proxy

Local gateway traffic routes through the managed proxy. Use this mode when your proxy needs visibility into all traffic, including local control-plane calls. Remote proxies must provide special routing for this to work correctly.

block

OpenClaw denies loopback gateway control-plane connections before opening a socket. This is the most restrictive mode. Use it when you want to guarantee that no local loopback communication happens at all.

Beyond loopback control, OpenClaw ships with a default security denylist that blocks outbound connections to sensitive IP ranges. The list covers 29+ entries across IPv4 and IPv6:

• IPv4 loopback (127.0.0.0/8), localhost, and localhost.localdomain
• Unspecified addresses (0.0.0.0/8)
• All RFC1918 private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• Link-local addresses (169.254.0.0/16)
• Cloud metadata services (169.254.169.254, metadata.google.internal)
• Carrier-grade NAT space (100.64.0.0/10)
• Documentation and benchmarking ranges (192.0.2.0/24, 198.18.0.0/15, 198.51.100.0/24, 203.0.113.0/24)
• IPv4 multicast (224.0.0.0/4) and reserved space (240.0.0.0/4)
• IPv6 loopback (::1/128), link-local (fe80::/10), private (fc00::/7), and multicast (ff00::/8)
• NAT64 ranges with embedded IPv4 (64:ff9b::/96, 64:ff9b:1::/48)
• 6to4 and Teredo tunnels with embedded IPv4 (2002::/16, 2001::/32)

The cloud metadata entry is the one worth paying attention to. The 169.254.169.254 address is used by AWS, GCP, and Azure to serve instance credentials. Blocking it by default prevents the exact SSRF attack that BlueRock Security demonstrated: a crafted request to the metadata endpoint that leaks IAM credentials.

If your organization runs an HTTPS proxy (common in enterprises that inspect TLS traffic), OpenClaw needs a way to verify the proxy's certificate. The proxy.tls.caFile setting points to a PEM-encoded CA certificate file:

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

This CA file is scoped to proxy endpoint verification only. It does not affect destination TLS, MITM inspection, or client certificates. OpenClaw uses it strictly to validate the TLS handshake with the proxy itself.

For enterprises where a TLS inspection appliance re-signs all outbound certificates, you may also need to set NODE_EXTRA_CA_CERTS as a process-global CA trust override. This ensures that Node.js trusts the re-signed certificates across all HTTP clients, not just the proxy connection.

A few things to watch for with HTTPS proxies:

• The CA file path must be readable by the user running the OpenClaw process. Permission errors cause silent connection failures.
• If you rotate proxy certificates, restart OpenClaw processes to pick up the new CA file. There is no hot-reload mechanism for TLS configuration.
• In container deployments, mount the CA file into the container at a known path and reference that path in the config. The file must exist inside the container's filesystem, not on the host.

For deployments where the proxy handles egress filtering and you need a persistent destination for agent outputs, Fastio provides free workspaces with 50GB storage and MCP access at /mcp. Agents behind a proxy can write results to a shared workspace without opening additional egress rules beyond the Fastio domain.

Persist proxy-managed agent output in a shared workspace

generous storage, MCP endpoint at /mcp, and built-in semantic search. Add one domain to your proxy allowlist and start writing agent results to a workspace humans can access.

Start 14-Day Trial

OpenClaw includes a built-in validation command that tests proxy connectivity, denylist enforcement, and optional destination reachability. Run it from the same host, container, or service account that runs your OpenClaw instance:

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

For HTTPS proxies with a private CA:

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

You can also test specific destinations with --allowed-url and --denied-url flags to confirm that your proxy rules work as expected:

openclaw proxy validate --proxy-url http://127.0.0.1:3128 \
  --allowed-url https://api.openai.com \
  --denied-url http://169.254.169.254

Add --json for machine-readable output, which is useful for CI pipelines or infrastructure-as-code validation. The --apns-reachable flag tests Apple Push Notification Service connectivity if your deployment uses APNs.

For manual verification, curl works as a quick sanity check:

curl -x http://127.0.0.1:3128 https://example.com/
curl -x http://127.0.0.1:3128 http://127.0.0.1/

The first command should succeed (allowed destination). The second should fail (blocked loopback address). If the second command succeeds, your proxy is not enforcing the denylist and you need to check your proxy's access control rules.

Common issues and fixes

• Proxy unreachable: Confirm the proxy process is running and listening on the configured port. Check firewall rules between the OpenClaw host and the proxy.
• Certificate errors with HTTPS proxy: Verify that caFile points to the correct PEM file and that the file contains the proxy's CA chain, not the proxy's leaf certificate.
• IRC bypassing the proxy: IRC uses raw TCP/TLS sockets and does not route through the managed proxy. If direct egress is not approved for IRC, disable it with channels.irc.enabled=false.
• Container loopback rejection: Container-targeted commands reject loopback proxy URLs by default. Use the host's LAN IP or a Docker network address instead of 127.0.0.1.

Once your proxy is routing and filtering traffic, the next question is where agent output lands. Agents running behind a corporate proxy typically cannot write to arbitrary cloud services. You need a storage layer that fits within your egress allowlist.

Local filesystems work for single-machine setups, but they break down when multiple agents share results, when a human needs to review output, or when you need audit trails on file access. S3 buckets solve the durability problem but require IAM configuration and do not offer built-in semantic search or handoff workflows.

Fastio workspaces handle the coordination layer. Agents write files through the MCP server or REST API, humans review them in the web UI, and ownership transfers let you hand a completed workspace from an agent to a client or team member. Intelligence Mode auto-indexes uploaded files for semantic search and AI chat with citations, so the output is queryable the moment it lands.

The Business Trial includes 50GB storage, included credits, and 5 workspaces with no credit card and no expiration. For a proxy-managed deployment, you would add Fastio and mcp.fast.io to your proxy's allowlist and configure the agent's MCP endpoint to point at the Streamable HTTP endpoint. All file operations, workspace queries, and intelligence features route through that single domain.

Compared to wiring up S3 buckets, metadata databases, and a separate search index, a single workspace endpoint simplifies both your egress rules and your agent's output pipeline. The agent storage page has setup instructions, and the MCP skill reference covers the full tool surface.