네트워크 프록시

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

프록시를 사용하는 이유

• 중앙 정책: 모든 애플리케이션 HTTP 호출 지점이 네트워크 규칙을 올바르게 처리하도록 의존하는 대신 하나의 이그레스 정책을 유지합니다.
• 연결 시점 검사: DNS 확인 후, 프록시가 업스트림 연결을 열기 직전에 대상을 평가합니다.
• DNS 리바인딩 방어: 애플리케이션 수준 DNS 검사와 실제 아웃바운드 연결 사이의 간격을 줄입니다.
• 더 넓은 JavaScript 적용 범위: 일반 fetch, node:http, node:https, WebSocket, axios, got, node-fetch 및 유사한 클라이언트를 같은 경로로 라우팅합니다.
• 감사 가능성: 이그레스 경계에서 허용 및 거부된 대상을 기록합니다.
• 운영 제어: OpenClaw를 다시 빌드하지 않고도 대상 규칙, 네트워크 세그먼테이션, 속도 제한 또는 아웃바운드 허용 목록을 적용합니다.

​

OpenClaw가 트래픽을 라우팅하는 방식

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

• Undici 디스패처 라우팅은 fetch, undici 기반 클라이언트, 자체 undici 디스패처를 제공하는 전송을 처리합니다.
• global-agent 라우팅은 http.request, https.request, http.get, https.get 위에 구성된 많은 라이브러리를 포함해 Node 코어 node:http 및 node:https 호출자를 처리합니다. 관리형 프록시 모드는 명시적 Node HTTP 에이전트가 운영자 프록시를 실수로 우회하지 않도록 해당 전역 에이전트를 강제합니다.

​

관련 프록시 용어

• proxy.enabled / proxy.proxyUrl: OpenClaw 런타임 이그레스를 위한 아웃바운드 포워드 프록시 라우팅입니다. 이 페이지는 해당 기능을 문서화합니다.
• gateway.auth.mode: "trusted-proxy": Gateway 액세스를 위한 인바운드 ID 인식 리버스 프록시 인증입니다. 신뢰할 수 있는 프록시 인증을 참조하세요.
• openclaw proxy: 개발 및 지원을 위한 로컬 디버그 프록시와 캡처 검사기입니다. openclaw proxy를 참조하세요.
• tools.web.fetch.useTrustedEnvProxy: 기본 엄격 DNS 고정 및 호스트 이름 정책을 유지하면서 운영자가 제어하는 HTTP(S) env 프록시가 DNS를 확인하도록 web_fetch에 대해 옵트인합니다. 웹 가져오기를 참조하세요.
• 채널 또는 공급자별 프록시 설정: 특정 전송에 대한 소유자별 재정의입니다. 목표가 런타임 전반의 중앙 이그레스 제어라면 관리형 네트워크 프록시를 선호하세요.

​

구성

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

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

​

Gateway Loopback 모드

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

• gateway-only(기본값): OpenClaw는 로컬 Gateway WebSocket 트래픽이 직접 연결할 수 있도록 활성 global-agent NO_PROXY 컨트롤러에 Gateway loopback 권한을 등록합니다. 활성 Gateway URL의 호스트와 포트가 등록되므로 사용자 지정 loopback Gateway 포트도 작동합니다.
• proxy: OpenClaw는 Gateway loopback NO_PROXY 권한을 등록하지 않으므로 로컬 Gateway 트래픽이 관리형 프록시를 통해 전송됩니다. 프록시가 원격이라면 OpenClaw 호스트의 loopback 서비스에 대해 프록시가 도달할 수 있는 호스트 이름, IP 또는 터널에 매핑하는 등의 특수 라우팅을 제공해야 합니다. 표준 원격 프록시는 127.0.0.1 및 localhost를 OpenClaw 호스트가 아니라 프록시 호스트에서 확인합니다.
• block: OpenClaw는 소켓을 열기 전에 loopback Gateway 제어 플레인 연결을 거부합니다.

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

​

프록시 요구 사항

• loopback 또는 신뢰할 수 있는 프라이빗 인터페이스에만 바인딩합니다.
• OpenClaw 프로세스, 호스트, 컨테이너 또는 서비스 계정만 사용할 수 있도록 액세스를 제한합니다.
• 대상을 직접 확인하고 DNS 확인 후 대상 IP를 차단합니다.
• 일반 HTTP 요청과 HTTPS CONNECT 터널 모두에 대해 연결 시점에 정책을 적용합니다.
• loopback, private, link-local, metadata, multicast, reserved 또는 documentation 범위에 대한 대상 기반 우회를 거부합니다.
• DNS 확인 경로를 완전히 신뢰하지 않는 한 호스트 이름 허용 목록은 피합니다.
• 요청 본문, 인증 헤더, 쿠키 또는 기타 비밀을 기록하지 않고 대상, 결정, 상태, 이유를 기록합니다.
• 프록시 정책을 버전 관리하에 두고 보안에 민감한 구성처럼 변경 사항을 검토합니다.

​

권장 차단 대상

​

검증

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

{
  "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/

openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway run

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

​

제한 사항

• 프록시는 프로세스 로컬 JavaScript HTTP 및 WebSocket 클라이언트에 대한 적용 범위를 개선하지만, OS 수준 네트워크 샌드박스는 아닙니다.
• Gateway 루프백 제어 평면 트래픽은 기본적으로 proxy.loopbackMode: "gateway-only"를 통해 직접 로컬 우회를 사용합니다. OpenClaw는 관리되는 global-agent NO_PROXY 컨트롤러에 활성 Gateway 루프백 권한을 등록하여 이 우회를 구현합니다. 운영자는 관리되는 프록시를 통해 Gateway 루프백 트래픽을 보내도록 proxy.loopbackMode: "proxy"를 설정하거나, 루프백 Gateway 연결을 거부하도록 proxy.loopbackMode: "block"을 설정할 수 있습니다. 원격 프록시 주의 사항은 Gateway 루프백 모드를 참조하세요.
• 원시 net, tls, http2 소켓, 네이티브 애드온, OpenClaw가 아닌 자식 프로세스는 프록시 환경 변수를 상속하고 준수하지 않는 한 Node 수준 프록시 라우팅을 우회할 수 있습니다. 포크된 OpenClaw 자식 CLI는 관리되는 프록시 URL과 proxy.loopbackMode 상태를 상속합니다.
• IRC는 운영자 관리 포워드 프록시 라우팅 외부의 원시 TCP/TLS 채널입니다. 모든 송신 트래픽이 해당 포워드 프록시를 통과해야 하는 배포에서는 직접 IRC 송신이 명시적으로 승인되지 않는 한 channels.irc.enabled=false를 설정하세요.
• 로컬 디버그 프록시는 진단 도구이며, 관리되는 프록시 모드가 활성화되어 있는 동안 프록시 요청 및 CONNECT 터널에 대한 직접 업스트림 포워딩은 기본적으로 비활성화됩니다. 승인된 로컬 진단에만 직접 포워딩을 활성화하세요.
• 사용자 로컬 WebUI와 로컬 모델 서버는 필요할 때 운영자 프록시 정책에서 허용 목록에 추가해야 합니다. OpenClaw는 이들을 위한 일반 로컬 네트워크 우회를 노출하지 않습니다.
• Gateway 제어 평면 프록시 우회는 의도적으로 localhost와 리터럴 루프백 IP URL로 제한됩니다. 로컬 직접 Gateway 제어 평면 연결에는 ws://127.0.0.1:18789, ws://[::1]:18789 또는 ws://localhost:18789를 사용하세요. 다른 호스트 이름은 일반 호스트 이름 기반 트래픽처럼 라우팅됩니다.
• OpenClaw는 사용자의 프록시 정책을 검사, 테스트 또는 인증하지 않습니다.
• 프록시 정책 변경은 보안에 민감한 운영 변경으로 취급하세요.