Gateway

Gateway 노출 런북

이 런북은 광범위한 보안 지침을 원격 접근 및 메시징 노출을 위한 운영자 체크리스트로 구체화합니다.

노출 패턴 선택

워크플로를 충족하는 가장 제한적인 패턴을 우선 사용하세요.

패턴	권장 상황	필수 제어
local loopback + SSH 터널	개인 용도, 관리자 접근, 디버깅	`gateway.bind: "loopback"`을 유지하고 `127.0.0.1:18789`를 터널링
local loopback + Tailscale Serve	Control UI/WebSocket에 대한 개인 tailnet 접근	Gateway를 local loopback 전용으로 유지합니다. Tailscale ID 헤더는 다른 인증 경로가 아닌 Control UI WebSocket 표면만 인증합니다
Tailnet/LAN 바인딩	알려진 기기로 구성된 전용 사설 네트워크	Gateway 인증, 방화벽 허용 목록, 공개 포트 포워딩 금지
신뢰할 수 있는 역방향 프록시	Gateway 앞에 조직 SSO/OIDC를 배치하는 경우	`trusted-proxy` 인증, 엄격한 `trustedProxies`, 헤더 덮어쓰기/제거 규칙, 명시적인 허용 사용자
공용 인터넷	드물고 위험도가 높은 배포	ID 인식 프록시, TLS, 속도 제한, 엄격한 허용 목록, 샌드박스 처리된 비메인 세션

Gateway로 직접 공개 포트 포워딩하지 마세요. 공개 접근이 필요한 경우 Gateway 앞에 ID 인식 프록시를 배치하고, 해당 프록시가 Gateway로 연결되는 유일한 네트워크 경로가 되게 하세요.

사전 점검 인벤토리

바인딩, 프록시, Tailscale 또는 채널 정책을 변경하기 전에 다음 항목을 기록하세요.

Gateway 호스트, OS 사용자 및 상태 디렉터리(기본값 ~/.openclaw).
Gateway URL 및 바인딩 모드(gateway.bind, 기본 포트 18789).
인증 모드, 토큰/비밀번호 출처 또는 신뢰할 수 있는 프록시 ID 출처.
활성화된 모든 채널과 각 채널의 DM, 그룹 또는 Webhook 허용 여부.
로컬이 아닌 발신자가 접근할 수 있는 에이전트.
접근 가능한 각 에이전트의 도구 프로필, 샌드박스 모드 및 권한 상승 도구 정책.
해당 에이전트가 사용할 수 있는 외부 자격 증명.
~/.openclaw/openclaw.json 및 자격 증명의 백업 위치.

두 명 이상이 봇에 메시지를 보낼 수 있다면, 이를 사용자별 호스트 격리가 아니라 공유된 위임 도구 권한으로 취급하세요.

기준 점검

접근을 개방하기 전에 실행하세요.

bash

openclaw doctoropenclaw security auditopenclaw security audit --deepopenclaw health

치명적인 발견 사항을 먼저 해결하세요. 배포에 의도적이며 문서화된 경우에만 경고를 허용하세요. 각 checkId의 의미와 수정 키는 보안 감사 검사를 참조하세요.

원격 CLI 검증 시 자격 증명을 명시적으로 전달하세요.

bash

openclaw gateway probe --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

로컬 구성의 자격 증명이 명시적인 원격 URL에 적용된다고 가정하지 마세요.

최소 안전 기준

노출된 배포의 시작점으로 다음 구성을 사용하세요.

json5

{  gateway: {    bind: "loopback",    auth: {      mode: "token",      token: "replace-with-a-long-random-token",    },  },  session: {    dmScope: "per-channel-peer",  },  agents: {    defaults: {      sandbox: { mode: "non-main" },    },  },  tools: {    profile: "messaging",    exec: { security: "deny", ask: "always" },    elevated: { enabled: false },  },}

한 번에 하나의 제어만 완화하세요. 쓰기 기능이 있는 도구를 활성화하기 전에 특정 채널 허용 목록을 추가하거나, 원격 Control UI 트래픽을 허용하기 전에 역방향 프록시를 활성화하세요.

tools.exec.security: "deny"는 무해한 진단을 포함한 모든 실행 호출을 차단합니다. 진단이나 위험도가 낮은 명령이 필요한 경우 위협 모델에 부합하는 특정 발신자, 에이전트, 명령 및 승인 모드를 선택한 후에만 이를 완화하세요.

DM 및 그룹 노출

메시징 채널은 신뢰할 수 없는 입력 표면입니다. DM 또는 그룹을 허용하기 전에 다음을 수행하세요.

dmPolicy: "open"보다 dmPolicy: "pairing" 또는 엄격한 allowFrom 목록을 우선 사용하세요.
"*" 허용 목록을 광범위한 도구 접근과 함께 사용하지 마세요.
대화방이 엄격하게 통제되지 않는 한 그룹에서 멘션을 요구하세요.
여러 사람이 봇에 DM을 보낼 수 있는 경우 DM 세션이 컨텍스트를 공유하지 않도록 session.dmScope: "per-channel-peer"를 설정하세요. 다중 계정 채널에는 "per-account-channel-peer"를 사용하세요.
공유 채널은 최소한의 도구만 있고 개인 자격 증명은 없는 에이전트로 라우팅하세요.

페어링은 발신자가 봇을 트리거하도록 승인합니다. 그렇다고 해당 발신자가 별도의 호스트 보안 경계가 되는 것은 아닙니다.

역방향 프록시 점검

ID 인식 프록시의 경우:

프록시는 Gateway로 전달하기 전에 사용자를 인증해야 합니다.
방화벽 또는 네트워크 정책은 Gateway 포트에 대한 직접 접근을 차단해야 합니다.
gateway.trustedProxies에는 프록시 출발지 IP만 나열해야 합니다.
프록시는 클라이언트가 제공한 ID 및 전달 헤더를 제거하거나 덮어써야 합니다.
프록시가 둘 이상의 사용자 집단을 대상으로 서비스하는 경우 gateway.auth.trustedProxy.allowUsers를 설정하세요.
로컬 프로세스를 신뢰하고 프록시가 ID 헤더를 소유하는 동일 호스트 프록시에서만 gateway.auth.trustedProxy.allowLoopback을 사용하세요.

프록시를 변경한 후 openclaw security audit --deep을 실행하세요. 프록시가 인증 경계가 되므로 신뢰할 수 있는 프록시 관련 발견 사항은 중요한 신호입니다.

도구 및 샌드박스 검토

에이전트를 원격 발신자에게 노출하기 전에:

어떤 세션이 호스트에서 실행되고 어떤 세션이 샌드박스에서 실행되는지 확인하세요.
호스트 실행을 거부하거나 승인을 요구하세요.
신뢰할 수 있는 특정 발신자에게 필요한 경우가 아니면 권한 상승 도구를 비활성화하세요.
개방형 또는 반개방형 메시징 표면에서는 브라우저, 캔버스, Node, Cron, Gateway 및 세션 생성 도구를 사용하지 마세요.
바인드 마운트의 범위를 좁게 유지하고 자격 증명, 홈 디렉터리, Docker 소켓 및 시스템 경로를 피하세요.
신뢰 경계가 실질적으로 다른 경우 별도의 Gateway, OS 사용자 또는 호스트를 사용하세요.

원격 사용자를 완전히 신뢰할 수 없다면 격리는 프롬프트나 세션 레이블만이 아니라 별도의 배포를 통해 이루어져야 합니다.

변경 후 검증

각 노출 변경 후:

openclaw security audit --deep을 다시 실행합니다.
승인된 연결이 성공하는지 확인합니다.
승인되지 않은 발신자 또는 브라우저 세션이 거부되는지 확인합니다.
로그에서 비밀이 가려지는지 확인합니다.
DM/그룹 라우팅이 의도한 에이전트에만 도달하는지 확인합니다.
영향도가 높은 도구가 승인을 요청하거나 거부되는지 확인합니다.
수용한 잔여 경고를 문서화합니다.

현재 노출 변경 사항을 이해하기 전에는 다음 노출 변경으로 진행하지 마세요.

롤백 계획

Gateway가 과도하게 노출되었을 가능성이 있는 경우: