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.
네트워크 프록시
OpenClaw는 런타임 HTTP 및 WebSocket 트래픽을 운영자가 관리하는 포워드 프록시를 통해 라우팅할 수 있습니다. 이는 중앙 집중식 이그레스 제어, 더 강력한 SSRF 보호, 더 나은 네트워크 감사 가능성을 원하는 배포를 위한 선택적 심층 방어입니다. OpenClaw는 프록시를 제공, 다운로드, 시작, 구성 또는 인증하지 않습니다. 사용자는 환경에 맞는 프록시 기술을 실행하고, OpenClaw는 일반적인 프로세스 로컬 HTTP 및 WebSocket 클라이언트를 해당 프록시를 통해 라우팅합니다.프록시를 사용하는 이유
프록시는 운영자에게 아웃바운드 HTTP 및 WebSocket 트래픽에 대한 단일 네트워크 제어 지점을 제공합니다. 이는 SSRF 강화 외에도 유용할 수 있습니다.- 중앙 정책: 모든 애플리케이션 HTTP 호출 위치가 네트워크 규칙을 올바르게 처리하도록 의존하는 대신 하나의 이그레스 정책을 유지합니다.
- 연결 시점 검사: DNS 확인 후, 프록시가 업스트림 연결을 열기 직전에 대상을 평가합니다.
- DNS 리바인딩 방어: 애플리케이션 수준 DNS 검사와 실제 아웃바운드 연결 사이의 간격을 줄입니다.
- 더 넓은 JavaScript 적용 범위: 일반적인
fetch,node:http,node:https, WebSocket, axios, got, node-fetch 및 유사 클라이언트를 동일한 경로로 라우팅합니다. - 감사 가능성: 이그레스 경계에서 허용 및 거부된 대상을 기록합니다.
- 운영 제어: OpenClaw를 다시 빌드하지 않고도 대상 규칙, 네트워크 세분화, 속도 제한 또는 아웃바운드 허용 목록을 적용합니다.
OpenClaw가 트래픽을 라우팅하는 방식
proxy.enabled=true이고 프록시 URL이 구성되어 있으면 openclaw gateway run, openclaw node run, openclaw agent --local 같은 보호된 런타임 프로세스는 일반 HTTP 및 WebSocket 이그레스를 구성된 프록시를 통해 라우팅합니다.
localhost 또는 127.0.0.1이나 [::1] 같은 리터럴 루프백 IP를 사용하는 경우 local loopback Gateway RPC 트래픽에 대해 좁은 직접 경로를 사용합니다. 해당 제어 플레인 경로는 운영자 프록시가 루프백 대상을 차단하더라도 루프백 Gateway에 도달할 수 있어야 합니다. 일반 런타임 HTTP 및 WebSocket 요청은 계속 구성된 프록시를 사용합니다.
내부적으로 OpenClaw는 이 기능에 두 가지 프로세스 수준 라우팅 훅을 사용합니다.
- Undici 디스패처 라우팅은
fetch, undici 기반 클라이언트, 자체 undici 디스패처를 제공하는 전송을 포함합니다. global-agent라우팅은http.request,https.request,http.get,https.get위에 계층화된 많은 라이브러리를 포함해 Node 코어node:http및node:https호출자를 포함합니다. 관리형 프록시 모드는 명시적 Node HTTP 에이전트가 실수로 운영자 프록시를 우회하지 않도록 해당 전역 에이전트를 강제합니다.
OPENCLAW_PROXY_URL 폴백을 따릅니다.
프록시 URL 자체는 http://를 사용해야 합니다. HTTPS 대상은 여전히 HTTP CONNECT를 통해 프록시에서 지원됩니다. 이는 OpenClaw가 http://127.0.0.1:3128 같은 일반 HTTP 포워드 프록시 리스너를 기대한다는 뜻일 뿐입니다.
프록시가 활성화되어 있는 동안 OpenClaw는 no_proxy, NO_PROXY, GLOBAL_AGENT_NO_PROXY를 지웁니다. 이러한 우회 목록은 대상 기반이므로, 거기에 localhost 또는 127.0.0.1이 남아 있으면 고위험 SSRF 대상이 필터링 프록시를 건너뛸 수 있습니다.
종료 시 OpenClaw는 이전 프록시 환경을 복원하고 캐시된 프로세스 라우팅 상태를 재설정합니다.
관련 프록시 용어
proxy.enabled/proxy.proxyUrl: OpenClaw 런타임 이그레스를 위한 아웃바운드 포워드 프록시 라우팅입니다. 이 페이지는 해당 기능을 문서화합니다.gateway.auth.mode: "trusted-proxy": Gateway 접근을 위한 인바운드 ID 인식 리버스 프록시 인증입니다. 신뢰할 수 있는 프록시 인증을 참조하세요.openclaw proxy: 개발 및 지원을 위한 로컬 디버그 프록시 및 캡처 검사기입니다. openclaw proxy를 참조하세요.- 채널 또는 프로바이더별 프록시 설정: 특정 전송을 위한 소유자별 재정의입니다. 목표가 런타임 전반의 중앙 이그레스 제어라면 관리형 네트워크 프록시를 선호하세요.
구성
proxy.enabled=true를 유지하면서 환경을 통해 URL을 제공할 수도 있습니다.
proxy.proxyUrl은 OPENCLAW_PROXY_URL보다 우선합니다.
enabled=true이지만 유효한 프록시 URL이 구성되어 있지 않으면, 보호된 명령은 직접 네트워크 접근으로 폴백하는 대신 시작에 실패합니다.
openclaw gateway start로 시작되는 관리형 Gateway 서비스의 경우 URL을 구성에 저장하는 것이 좋습니다.
OPENCLAW_PROXY_URL을 $OPENCLAW_STATE_DIR/.env 또는 ~/.openclaw/.env 같은 서비스의 지속 환경에 넣은 다음, launchd, systemd 또는 Scheduled Tasks가 해당 값으로 Gateway를 시작하도록 서비스를 다시 설치하세요.
openclaw --container ... 명령의 경우, OpenClaw는 OPENCLAW_PROXY_URL이 설정되어 있으면 컨테이너 대상 자식 CLI로 전달합니다. URL은 컨테이너 내부에서 접근 가능해야 합니다. 127.0.0.1은 호스트가 아니라 컨테이너 자체를 가리킵니다. OpenClaw는 사용자가 해당 안전 검사를 명시적으로 재정의하지 않는 한 컨테이너 대상 명령에 대해 루프백 프록시 URL을 거부합니다.
프록시 요구 사항
프록시 정책이 보안 경계입니다. OpenClaw는 프록시가 올바른 대상을 차단하는지 확인할 수 없습니다. 프록시를 다음과 같이 구성하세요.- 루프백 또는 신뢰할 수 있는 비공개 인터페이스에만 바인딩합니다.
- OpenClaw 프로세스, 호스트, 컨테이너 또는 서비스 계정만 사용할 수 있도록 접근을 제한합니다.
- 대상을 직접 확인하고 DNS 확인 후 대상 IP를 차단합니다.
- 일반 HTTP 요청과 HTTPS
CONNECT터널 모두에 대해 연결 시점에 정책을 적용합니다. - 루프백, 비공개, 링크 로컬, 메타데이터, 멀티캐스트, 예약 또는 문서화 범위에 대한 대상 기반 우회를 거부합니다.
- DNS 확인 경로를 완전히 신뢰하지 않는 한 호스트 이름 허용 목록을 피합니다.
- 요청 본문, 인증 헤더, 쿠키 또는 기타 비밀을 기록하지 않고 대상, 결정, 상태, 이유를 기록합니다.
- 프록시 정책을 버전 관리하에 두고 보안에 민감한 구성처럼 변경 사항을 검토합니다.
권장 차단 대상
모든 포워드 프록시, 방화벽 또는 이그레스 정책의 시작점으로 이 거부 목록을 사용하세요. OpenClaw 애플리케이션 수준 분류기 로직은src/infra/net/ssrf.ts 및 src/shared/net/ip.ts에 있습니다. 관련 패리티 훅은 BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, RFC2544_BENCHMARK_PREFIX, 그리고 NAT64, 6to4, Teredo, ISATAP 및 IPv4 매핑 형식을 위한 포함된 IPv4 센티널 처리입니다. 이러한 파일은 외부 프록시 정책을 유지 관리할 때 유용한 참조이지만, OpenClaw는 해당 규칙을 사용자 프록시에 자동으로 내보내거나 적용하지 않습니다.
| 범위 또는 호스트 | 차단 이유 |
|---|---|
127.0.0.0/8, localhost, localhost.localdomain | IPv4 루프백 |
::1/128 | IPv6 루프백 |
0.0.0.0/8, ::/128 | 지정되지 않은 주소 및 이 네트워크 주소 |
10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 | RFC1918 비공개 네트워크 |
169.254.0.0/16, fe80::/10 | 링크 로컬 주소 및 일반적인 클라우드 메타데이터 경로 |
169.254.169.254, metadata.google.internal | 클라우드 메타데이터 서비스 |
100.64.0.0/10 | 캐리어급 NAT 공유 주소 공간 |
198.18.0.0/15, 2001:2::/48 | 벤치마킹 범위 |
192.0.0.0/24, 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32 | 특수 용도 및 문서화 범위 |
224.0.0.0/4, ff00::/8 | 멀티캐스트 |
240.0.0.0/4 | 예약된 IPv4 |
fc00::/7, fec0::/10 | IPv6 로컬/비공개 범위 |
100::/64, 2001:20::/28 | IPv6 폐기 및 ORCHIDv2 범위 |
64:ff9b::/96, 64:ff9b:1::/48 | 포함된 IPv4가 있는 NAT64 접두사 |
2002::/16, 2001::/32 | 포함된 IPv4가 있는 6to4 및 Teredo |
::/96, ::ffff:0:0/96 | IPv4 호환 및 IPv4 매핑 IPv6 |
검증
OpenClaw를 실행하는 동일한 호스트, 컨테이너 또는 서비스 계정에서 프록시를 검증하세요.제한 사항
- 프록시는 프로세스 로컬 JavaScript HTTP 및 WebSocket 클라이언트에 대한 적용 범위를 개선하지만, OS 수준 네트워크 샌드박스는 아닙니다.
- 원시
net,tls,http2소켓, 네이티브 애드온 및 자식 프로세스는 프록시 환경 변수를 상속하고 준수하지 않는 한 Node 수준 프록시 라우팅을 우회할 수 있습니다. - 사용자 로컬 WebUI 및 로컬 모델 서버는 필요한 경우 운영자 프록시 정책에서 허용 목록에 추가해야 합니다. OpenClaw는 이를 위한 일반적인 로컬 네트워크 우회를 노출하지 않습니다.
- Gateway 제어 플레인 프록시 우회는 의도적으로
localhost와 리터럴 루프백 IP URL로 제한됩니다. 로컬 직접 Gateway 제어 플레인 연결에는ws://127.0.0.1:18789,ws://[::1]:18789또는ws://localhost:18789를 사용하세요. 다른 호스트 이름은 일반적인 호스트 이름 기반 트래픽처럼 라우팅됩니다. - OpenClaw는 사용자의 프록시 정책을 검사, 테스트 또는 인증하지 않습니다.
- 프록시 정책 변경을 보안에 민감한 운영 변경으로 취급하세요.