Gateway 운영
기준일: 2026-06-06
난이도: 고급
공식 기준: Gateway runbook, Health checks, Diagnostics export, Gateway exposure runbook
OpenClaw의 핵심은 Gateway 프로세스입니다. 메시징, node, agent runtime, dashboard가 모두 여기에 기대기 때문에 운영자는 상태 확인과 노출 범위를 명확히 알아야 합니다.
핵심 개념
| 항목 | 설명 |
|---|---|
| gateway status/health | 프로세스, 포트, provider, channel 상태 확인 |
| dashboard | 로컬 Control UI |
| diagnostics bundle | 버그 리포트와 복구용 증거 묶음 |
| remote access | SSH tunnel, tailnet, trusted proxy 등으로 외부 접근 |
| exposure checklist | loopback 밖으로 열기 전 보안 점검 |
| bind/auth mode | gateway.bind와 gateway.auth.mode의 조합으로 노출 범위 결정 |
선택 기준
- 개인 로컬 사용은 loopback Gateway로 시작합니다.
- 휴대폰/외부 채널에서 쓰려면 remote access와 pairing을 같이 설계합니다.
- 공인 인터넷에 노출하기 전 trusted proxy, auth, operator scope, rollback 계획을 확인합니다.
- 장애 분석은 logs보다 먼저
status,health,doctor로 좁힙니다.
노출 전 보안 매트릭스
| 상황 | 권장 설정 | 피해야 할 설정 |
|---|---|---|
| 로컬 개인 사용 | gateway.bind: "loopback", token/password auth 유지 |
auth.mode: "none"을 습관적으로 켜는 것 |
| LAN 접근 | gateway.bind: "lan", auth.mode: "token" 또는 "password" |
비밀번호 없는 LAN 노출 |
| Tailscale | gateway.bind: "tailnet", auth.allowTailscale: true 검토 |
tailnet이라고 webhook/token 검토를 생략 |
| 공개 reverse proxy | auth.mode: "trusted-proxy", trustedProxies, user header 제한 |
임의 proxy에서 user header를 신뢰 |
| webhook/hook 사용 | 별도 hooks.token과 payload 검증 |
Gateway auth token과 hook token을 무분별하게 재사용 |
비loopback 바인드는 인증이 전제입니다. 공식 설정 기준에서 Gateway 포트 기본값은 18789이고, 우선순위는 --port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789입니다. 외부 노출 전에는 바인드 주소, 인증 모드, token/password 저장 위치, trusted proxy IP, rollback 명령을 한 번에 기록합니다.
실습
openclaw status
openclaw gateway status
openclaw health
openclaw doctor
openclaw logs
현재 Gateway 설정에서 노출 관련 값을 확인합니다.
openclaw config get gateway
openclaw gateway status --json
진단 묶음 준비:
OpenClaw gateway 장애를 보고하기 위한 diagnostics checklist를 만들어줘.
포함할 명령, 숨겨야 할 secret, 재현 단계, channel/provider 상태를 구분해줘.
도구에 입력할 프롬프트
내 OpenClaw Gateway를 외부에서 접근 가능하게 만들기 전에 보안 점검표를 작성해줘.
loopback 유지, SSH tunnel, tailnet, trusted proxy, rollback 중 어떤 경로가 맞는지 비교해줘.
체크리스트
- Gateway가 어떤 주소와 포트에서 듣는지 확인했다.
- dashboard와 remote access를 같은 보안 수준으로 취급한다.
- non-loopback bind에는 token/password/trusted-proxy 중 하나를 적용했다.
- trusted proxy를 쓴다면 신뢰할 proxy 주소와 user header를 제한했다.
- hook/webhook token을 Gateway operator token과 분리했다.
- diagnostics bundle에서 secret이 노출되지 않게 한다.
- 외부 노출 전 rollback과 접근 차단 절차를 정했다.
다음 단계
- 설치 가이드에서 daemon/onboarding 상태를 확인합니다.
- 접근 제어와 라우팅에서 sender와 operator 범위를 제한합니다.