Gateway CLI

Gateway는 OpenClaw의 WebSocket 서버입니다 (채널, 노드, 세션, 훅).

이 페이지의 서브명령은 openclaw gateway … 아래에 있습니다.

관련 문서:

Gateway 실행

로컬 Gateway 프로세스 실행:

openclaw gateway

포그라운드 별칭:

openclaw gateway run

참고사항:

  • 기본적으로 Gateway는 ~/.openclaw/openclaw.json에 gateway.mode=local이 설정되지 않으면 시작을 거부합니다. 임시/개발 실행을 위해 --allow-unconfigured를 사용하세요.
  • 인증 없이 루프백 이상으로 바인딩하는 것은 차단됩니다 (안전 가드레일).
  • SIGUSR1은 승인된 경우 프로세스 내 재시작을 트리거합니다 (commands.restart 활성화 또는 gateway 도구/config apply/update 사용).
  • SIGINT/SIGTERM 핸들러는 gateway 프로세스를 중지하지만, 커스텀 터미널 상태를 복원하지는 않습니다. TUI 또는 raw-mode 입력으로 CLI를 래핑하는 경우 종료 전에 터미널을 복원하세요.

옵션

  • --port <port>: WebSocket 포트 (기본값은 config/env에서; 일반적으로 18789).
  • --bind <loopback|lan|tailnet|auto|custom>: 리스너 바인드 모드.
  • --auth <token|password>: 인증 모드 재정의.
  • --token <token>: 토큰 재정의 (프로세스의 OPENCLAW_GATEWAY_TOKEN도 설정).
  • --password <password>: 비밀번호 재정의 (프로세스의 OPENCLAW_GATEWAY_PASSWORD도 설정).
  • --tailscale <off|serve|funnel>: Tailscale을 통해 Gateway 노출.
  • --tailscale-reset-on-exit: 종료 시 Tailscale serve/funnel 구성 리셋.
  • --allow-unconfigured: config에 gateway.mode=local 없이 gateway 시작 허용.
  • --dev: 누락된 경우 dev config + workspace 생성 (BOOTSTRAP.md 건너뜀).
  • --reset: dev config + credentials + sessions + workspace 리셋 (--dev 필요).
  • --force: 시작 전에 선택된 포트의 기존 리스너 종료.
  • --verbose: 상세 로그.
  • --claude-cli-logs: 콘솔에 claude-cli 로그만 표시 (및 stdout/stderr 활성화).
  • --ws-log <auto|full|compact>: websocket 로그 스타일 (기본값 auto).
  • --compact: --ws-log compact의 별칭.
  • --raw-stream: 원시 모델 스트림 이벤트를 jsonl로 로깅.
  • --raw-stream-path <path>: 원시 스트림 jsonl 경로.

실행 중인 Gateway 쿼리

모든 쿼리 명령은 WebSocket RPC를 사용합니다.

출력 모드:

  • 기본값: 사람이 읽을 수 있는 형식 (TTY에서 색상 표시).
  • --json: 기계 판독 가능한 JSON (스타일/스피너 없음).
  • --no-color (또는 NO_COLOR=1): 사람 레이아웃을 유지하면서 ANSI 비활성화.

공유 옵션 (지원되는 경우):

  • --url <url>: Gateway WebSocket URL.
  • --token <token>: Gateway 토큰.
  • --password <password>: Gateway 비밀번호.
  • --timeout <ms>: 타임아웃/예산 (명령마다 다름).
  • --expect-final: "final" 응답 대기 (에이전트 호출).

gateway health

openclaw gateway health --url ws://127.0.0.1:18789

gateway status

gateway status는 Gateway 서비스(launchd/systemd/schtasks)와 선택적 RPC 조사를 표시합니다.

openclaw gateway status
openclaw gateway status --json

옵션:

  • --url <url>: 조사 URL 재정의.
  • --token <token>: 조사를 위한 토큰 인증.
  • --password <password>: 조사를 위한 비밀번호 인증.
  • --timeout <ms>: 조사 타임아웃 (기본값 10000).
  • --no-probe: RPC 조사 건너뜀 (서비스 전용 보기).
  • --deep: 시스템 수준 서비스도 스캔.

gateway probe

gateway probe는 "모든 것 디버그" 명령입니다. 항상 다음을 조사합니다:

  • 구성된 원격 gateway (설정된 경우), 그리고
  • localhost (루프백) 원격이 구성된 경우에도.

여러 gateway에 접근할 수 있는 경우 모두 출력합니다. 격리된 프로필/포트를 사용할 때 여러 gateway가 지원됩니다 (예: 복구 봇), 하지만 대부분의 설치는 여전히 단일 gateway를 실행합니다.

openclaw gateway probe
openclaw gateway probe --json

SSH를 통한 원격 (Mac 앱 패리티)

macOS 앱 "Remote over SSH" 모드는 로컬 포트 포워드를 사용하여 원격 gateway(루프백에만 바인드될 수 있음)를 ws://127.0.0.1:<port>에서 접근 가능하게 만듭니다.

CLI 동등:

openclaw gateway probe --ssh user@gateway-host

옵션:

  • --ssh <target>: user@host 또는 user@host:port (포트 기본값은 22).
  • --ssh-identity <path>: identity 파일.
  • --ssh-auto: 디스커버리된 첫 번째 gateway 호스트를 SSH 대상으로 선택 (LAN/WAB 전용).

구성 (선택 사항, 기본값으로 사용):

  • gateway.remote.sshTarget
  • gateway.remote.sshIdentity

gateway call <method>

저수준 RPC 헬퍼.

openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'

Gateway 서비스 관리

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

참고사항:

  • gateway install은 --port, --runtime, --token, --force, --json을 지원합니다.
  • 라이프사이클 명령은 스크립팅을 위해 --json을 허용합니다.

Gateway 디스커버리 (Bonjour)

gateway discover는 Gateway 비콘(_openclaw-gw._tcp)을 스캔합니다.

  • Multicast DNS-SD: local.
  • Unicast DNS-SD (Wide-Area Bonjour): 도메인 선택 (예: openclaw.internal.) 및 분할 DNS + DNS 서버 설정; /gateway/bonjour 참조

Bonjour 디스커버리가 활성화된 gateway만 비콘을 광고합니다 (기본값).

Wide-Area 디스커버리 레코드에는 다음이 포함됩니다 (TXT):

  • role (gateway 역할 힌트)
  • transport (전송 힌트, 예: gateway)
  • gatewayPort (WebSocket 포트, 일반적으로 18789)
  • sshPort (SSH 포트; 없으면 22가 기본값)
  • tailnetDns (MagicDNS 호스트명, 사용 가능한 경우)
  • gatewayTls / gatewayTlsSha256 (TLS 활성화 + 인증서 지문)
  • cliPath (원격 설치를 위한 선택적 힌트)

gateway discover

openclaw gateway discover

옵션:

  • --timeout <ms>: 명령당 타임아웃 (browse/resolve); 기본값 2000.
  • --json: 기계 판독 가능한 출력 (스타일/스피너도 비활성화).

예시:

openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
← 문서로 돌아가기