네트워크 프록시

​

프록시를 사용하는 이유

• 중앙 정책: 모든 애플리케이션 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

• http://proxy.example:3128: OpenClaw은 포워드 프록시에 일반 TCP 연결을 열고, HTTPS 대상에 대한 CONNECT를 포함한 HTTP 프록시 요청을 보냅니다.
• https://proxy.example:8443: OpenClaw은 프록시 엔드포인트에 TLS를 열고, 프록시 인증서를 검증한 다음, 해당 TLS 세션 안에서 HTTP 프록시 요청을 보냅니다.

​

관련 프록시 용어

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

​

구성

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

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

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

​

Gateway Loopback Mode

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

• gateway-only(기본값): OpenClaw은 로컬 Gateway WebSocket 트래픽이 직접 연결될 수 있도록 Proxyline의 관리형 우회 정책에 Gateway 루프백 권한을 등록합니다. 활성 Gateway URL의 호스트와 포트가 등록되므로 사용자 지정 루프백 Gateway 포트가 동작합니다. 번들 브라우저 Plugin은 OpenClaw이 시작한 관리형 브라우저에 대해 정확한 로컬 CDP 준비 상태 및 DevTools WebSocket 엔드포인트도 등록할 수 있으며, 번들 Ollama 메모리 임베딩 제공자는 정확히 구성된 호스트 로컬 루프백 임베딩 원점에 대해 자체적으로 더 좁은 보호된 직접 경로를 사용할 수 있습니다.
• proxy: OpenClaw은 Gateway 또는 Ollama 루프백 우회를 등록하지 않으므로 해당 루프백 트래픽이 관리형 프록시를 통해 전송됩니다. 프록시가 원격인 경우 OpenClaw 호스트의 루프백 서비스에 대해, 프록시에서 도달 가능한 호스트 이름, IP 또는 터널에 매핑하는 것과 같은 특수 라우팅을 제공해야 합니다. 표준 원격 프록시는 127.0.0.1 및 localhost를 OpenClaw 호스트가 아니라 프록시 호스트에서 확인합니다.
• block: OpenClaw은 소켓을 열기 전에 Gateway 루프백 제어 평면 연결과 보호된 Ollama 호스트 로컬 임베딩 루프백 연결을 거부합니다.

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

​

프록시 요구 사항

• 루프백 또는 비공개 신뢰 인터페이스에만 바인딩합니다.
• OpenClaw 프로세스, 호스트, 컨테이너 또는 서비스 계정만 사용할 수 있도록 액세스를 제한합니다.
• 대상 자체를 확인하고 DNS 확인 후 대상 IP를 차단합니다.
• 일반 HTTP 요청과 HTTPS CONNECT 터널 모두에 대해 연결 시점에 정책을 적용합니다.
• 루프백, 비공개, 링크 로컬, 메타데이터, 멀티캐스트, 예약 또는 문서화 범위에 대한 대상 기반 우회를 거부합니다.
• DNS 확인 경로를 완전히 신뢰하지 않는 한 호스트 이름 허용 목록을 피합니다.
• 요청 본문, 권한 부여 헤더, 쿠키 또는 기타 비밀을 기록하지 않고 대상, 결정, 상태 및 이유를 기록합니다.
• 프록시 정책을 버전 관리에 두고 보안에 민감한 구성처럼 변경 사항을 검토합니다.

​

권장 차단 대상

​

검증

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/

​

프록시 CA 신뢰

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

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

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

​

제한 사항

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