Network proxy

Network proxy 문서는 OpenClaw 공식 문서(security/network-proxy)를 한국어로 정리한 가이드입니다. How to route OpenClaw runtime HTTP and WebSocket traffic through an operator-managed filtering proxy 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

How to route OpenClaw runtime HTTP and WebSocket traffic through an operator-managed filtering proxy

한국어 가이드 범위: security/network-proxy 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

구성
HTTPS proxy endpoint with a private CA
How routing works
Gateway loopback mode
Containers
Related proxy terms
Validating the proxy
Recommended blocked destinations
Limits

상세 내용

본문

OpenClaw can route runtime HTTP and WebSocket traffic through an operator-managed forward proxy. This is optional defense in depth: central egress control, stronger SSRF protection, and destination auditability at the network boundary. Because the proxy evaluates the destination at connect time, after DNS resolution and immediately before it opens the upstream connection, it also narrows the gap a DNS-rebinding attack relies on between an earlier application-level DNS check and the actual outbound connection. A single proxy policy also gives operators one place to enforce destination rules, network segmentation, rate limits, or outbound allowlists without rebuilding OpenClaw.

구성

You can also set the URL through the environment:

Key	Type	Default	Notes
`proxy.proxyUrl`	string	unset	`http://` or `https://` forward proxy URL. Credentials embedded in the URL are treated as sensitive and redacted from snapshots/logs.
`proxy.tls.caFile`	string	unset	CA bundle for verifying an `https://` proxy endpoint signed by a private CA.
`proxy.loopbackMode`	`gateway-only` \| `proxy` \| `block`	`gateway-only`	Controls loopback bypass behavior; see below.

proxy:
  proxyUrl: http://127.0.0.1:3128

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

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

HTTPS proxy endpoint with a private CA

proxy.tls.caFile verifies the proxy endpoint's own TLS certificate. It is not a destination MITM trust setting, a client certificate, or a substitute 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 (예를 들어, 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.

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

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:

주요 항목:

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.

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

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:

Mode	Behavior
`gateway-only` (default)	OpenClaw registers the active Gateway loopback authority as a direct-connect exception, so local Gateway WebSocket traffic connects without the proxy. Custom loopback ports work because the exception targets the exact configured host/port. The bundled browser plugin registers the same kind of exception for the exact local CDP readiness and DevTools WebSocket URLs of OpenClaw-launched managed browsers; the bundled Ollama memory embedding provider has a narrower guarded direct path for its exact configured host-local loopback embedding origin.
`proxy`	No loopback exceptions are registered; Gateway and Ollama loopback traffic goes through the proxy. A remote proxy must be able to route back to the OpenClaw host's loopback service (for example via a reachable hostname, IP, or tunnel) — a standard remote proxy resolves `127.0.0.1`/`localhost` against itself, not against the OpenClaw host.
`block`	OpenClaw denies Gateway loopback control-plane connections and guarded Ollama loopback embedding connections before opening a socket.

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

Containers

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 there refers to the container itself, not the host. OpenClaw rejects loopback proxy URLs for container-targeted commands unless you set OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1 to explicitly override that check.

주요 항목:

proxy.enabled / proxy.proxyUrl — outbound forward-proxy routing for runtime egress. This page.
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 strict DNS pinning and hostname policy by default. See Web fetch.
Channel- or provider-specific proxy settings — owner-specific overrides for one transport. Prefer the managed network proxy for central egress control across the runtime.

Validating the proxy

The proxy's destination policy is the actual security boundary; OpenClaw cannot verify that your proxy blocks the right targets. Configure it to:

주요 항목:

Bind only to loopback or a private trusted interface, reachable only 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.

Flag	Purpose
`--proxy-url <url>`	Validate this URL instead of resolving config/env.
`--proxy-ca-file <path>`	CA bundle for an HTTPS proxy endpoint.
`--allowed-url <url>`	Destination expected to succeed (repeatable).
`--denied-url <url>`	Destination expected to be blocked (repeatable).
`--apns-reachable`	Also verify the proxy can tunnel a direct sandbox APNs HTTP/2 probe.
`--apns-authority <url>`	Override the APNs authority probed with `--apns-reachable`.
`--timeout-ms <ms>`	Per-request timeout.
`--json`	Machine-readable output.

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/

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.

Range or host	Why to block
`127.0.0.0/8`, `localhost`, `localhost.localdomain`	IPv4 loopback
`::1/128`	IPv6 loopback
`0.0.0.0/8`, `::/128`	Unspecified / this-network addresses
`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`	RFC 1918 private networks
`169.254.0.0/16`, `fe80::/10`	Link-local, including common cloud metadata paths
`169.254.169.254`, `metadata.google.internal`	Cloud metadata services
`100.64.0.0/10`	Carrier-grade NAT shared address space
`198.18.0.0/15`, `2001:2::/48`	Benchmarking ranges
`192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32`	Special-use and documentation ranges
`224.0.0.0/4`, `ff00::/8`	Multicast
`240.0.0.0/4`	Reserved IPv4
`fc00::/7`, `fec0::/10`	IPv6 local/private ranges
`100::/64`, `2001:20::/28`	IPv6 discard and ORCHIDv2 ranges
`64:ff9b::/96`, `64:ff9b:1::/48`	NAT64 prefixes with embedded IPv4
`2002::/16`, `2001::/32`	6to4 and Teredo with embedded IPv4
`::/96`, `::ffff:0:0/96`	IPv4-compatible and IPv4-mapped IPv6

Limits

주요 항목:

This is process-level coverage for JavaScript HTTP/WebSocket clients, not 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.

Surface	Managed proxy status
`fetch`, `node:http`, `node:https`, common WebSocket clients	Routed through managed proxy hooks when configured.
APNs direct HTTP/2	Routed through the APNs managed `CONNECT` helper.
Gateway control-plane loopback	Direct only for the exact configured local loopback Gateway URL.
Debug proxy upstream forwarding	Disabled while managed proxy mode is active unless explicitly enabled for local diagnostics.
IRC	Raw TCP/TLS; not proxied by managed HTTP proxy mode. Set `channels.irc.enabled: false` if your deployment requires all egress through the forward proxy.
Other raw `net`, `tls`, or `http2` client calls	Must be classified by the raw socket guard before landing.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/security/network-proxy
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

proxy:
  proxyUrl: http://127.0.0.1:3128

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

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

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

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

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

Network proxy

핵심 요약

How to route OpenClaw runtime HTTP and WebSocket traffic through an operator-managed filtering proxy

한국어 가이드 범위: security/network-proxy 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

구성
HTTPS proxy endpoint with a private CA
How routing works
Gateway loopback mode
Containers
Related proxy terms
Validating the proxy
Recommended blocked destinations
Limits

상세 내용

본문

구성

You can also set the URL through the environment:

Key	Type	Default	Notes
`proxy.proxyUrl`	string	unset	`http://` or `https://` forward proxy URL. Credentials embedded in the URL are treated as sensitive and redacted from snapshots/logs.
`proxy.tls.caFile`	string	unset	CA bundle for verifying an `https://` proxy endpoint signed by a private CA.
`proxy.loopbackMode`	`gateway-only` \| `proxy` \| `block`	`gateway-only`	Controls loopback bypass behavior; see below.

proxy:
  proxyUrl: http://127.0.0.1:3128

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

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

HTTPS proxy endpoint with a private CA

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

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:

주요 항목:

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.

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

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:

Mode	Behavior
`gateway-only` (default)	OpenClaw registers the active Gateway loopback authority as a direct-connect exception, so local Gateway WebSocket traffic connects without the proxy. Custom loopback ports work because the exception targets the exact configured host/port. The bundled browser plugin registers the same kind of exception for the exact local CDP readiness and DevTools WebSocket URLs of OpenClaw-launched managed browsers; the bundled Ollama memory embedding provider has a narrower guarded direct path for its exact configured host-local loopback embedding origin.
`proxy`	No loopback exceptions are registered; Gateway and Ollama loopback traffic goes through the proxy. A remote proxy must be able to route back to the OpenClaw host's loopback service (for example via a reachable hostname, IP, or tunnel) — a standard remote proxy resolves `127.0.0.1`/`localhost` against itself, not against the OpenClaw host.
`block`	OpenClaw denies Gateway loopback control-plane connections and guarded Ollama loopback embedding connections before opening a socket.

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

Containers

주요 항목:

proxy.enabled / proxy.proxyUrl — outbound forward-proxy routing for runtime egress. This page.
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 strict DNS pinning and hostname policy by default. See Web fetch.
Channel- or provider-specific proxy settings — owner-specific overrides for one transport. Prefer the managed network proxy for central egress control across the runtime.

Validating the proxy

The proxy's destination policy is the actual security boundary; OpenClaw cannot verify that your proxy blocks the right targets. Configure it to:

주요 항목:

Bind only to loopback or a private trusted interface, reachable only 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.

Flag	Purpose
`--proxy-url <url>`	Validate this URL instead of resolving config/env.
`--proxy-ca-file <path>`	CA bundle for an HTTPS proxy endpoint.
`--allowed-url <url>`	Destination expected to succeed (repeatable).
`--denied-url <url>`	Destination expected to be blocked (repeatable).
`--apns-reachable`	Also verify the proxy can tunnel a direct sandbox APNs HTTP/2 probe.
`--apns-authority <url>`	Override the APNs authority probed with `--apns-reachable`.
`--timeout-ms <ms>`	Per-request timeout.
`--json`	Machine-readable output.

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/

Recommended blocked destinations

Range or host	Why to block
`127.0.0.0/8`, `localhost`, `localhost.localdomain`	IPv4 loopback
`::1/128`	IPv6 loopback
`0.0.0.0/8`, `::/128`	Unspecified / this-network addresses
`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`	RFC 1918 private networks
`169.254.0.0/16`, `fe80::/10`	Link-local, including common cloud metadata paths
`169.254.169.254`, `metadata.google.internal`	Cloud metadata services
`100.64.0.0/10`	Carrier-grade NAT shared address space
`198.18.0.0/15`, `2001:2::/48`	Benchmarking ranges
`192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32`	Special-use and documentation ranges
`224.0.0.0/4`, `ff00::/8`	Multicast
`240.0.0.0/4`	Reserved IPv4
`fc00::/7`, `fec0::/10`	IPv6 local/private ranges
`100::/64`, `2001:20::/28`	IPv6 discard and ORCHIDv2 ranges
`64:ff9b::/96`, `64:ff9b:1::/48`	NAT64 prefixes with embedded IPv4
`2002::/16`, `2001::/32`	6to4 and Teredo with embedded IPv4
`::/96`, `::ffff:0:0/96`	IPv4-compatible and IPv4-mapped IPv6

Limits

주요 항목:

This is process-level coverage for JavaScript HTTP/WebSocket clients, not 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.

Surface	Managed proxy status
`fetch`, `node:http`, `node:https`, common WebSocket clients	Routed through managed proxy hooks when configured.
APNs direct HTTP/2	Routed through the APNs managed `CONNECT` helper.
Gateway control-plane loopback	Direct only for the exact configured local loopback Gateway URL.
Debug proxy upstream forwarding	Disabled while managed proxy mode is active unless explicitly enabled for local diagnostics.
IRC	Raw TCP/TLS; not proxied by managed HTTP proxy mode. Set `channels.irc.enabled: false` if your deployment requires all egress through the forward proxy.
Other raw `net`, `tls`, or `http2` client calls	Must be classified by the raw socket guard before landing.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/security/network-proxy
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

proxy:
  proxyUrl: http://127.0.0.1:3128

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

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

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

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

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

Network proxy

핵심 요약

문서 구성

상세 내용

본문

구성

HTTPS proxy endpoint with a private CA

How routing works

Gateway loopback mode

Containers

Validating the proxy

Recommended blocked destinations

Limits

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Network proxy

핵심 요약

문서 구성

상세 내용

본문

구성

HTTPS proxy endpoint with a private CA

How routing works

Gateway loopback mode

Containers

Validating the proxy

Recommended blocked destinations

Limits

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Network proxy

핵심 요약

문서 구성

상세 내용

본문

구성

HTTPS proxy endpoint with a private CA

How routing works

Gateway loopback mode

Containers

Related proxy terms

Validating the proxy

Recommended blocked destinations

Limits

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Network proxy

핵심 요약

문서 구성

상세 내용

본문

구성

HTTPS proxy endpoint with a private CA

How routing works

Gateway loopback mode

Containers

Related proxy terms

Validating the proxy

Recommended blocked destinations

Limits

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드