게이트웨이 CLI

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

이 페이지의 하위 명령어들은 openclaw gateway … 아래에 있습니다.

관련 문서:

• /gateway/bonjour
• /gateway/discovery
• /gateway/configuration

게이트웨이 실행

로컬 게이트웨이 프로세스를 실행합니다:

openclaw gateway

포그라운드 별칭:

openclaw gateway run

참고:

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

옵션

• --port <port>: WebSocket 포트 (기본값은 config/env에서 가져옴; 보통 18789).
• --bind <loopback|lan|tailnet|auto|custom>: 리스너 바인드 모드.
• --auth <token|password>: 인증 모드 오버라이드.
• --token <token>: 토큰 오버라이드 (프로세스에 OPENCLAW_GATEWAY_TOKEN도 설정).
• --password <password>: 비밀번호 오버라이드. 경고: 인라인 비밀번호는 로컬 프로세스 목록에 노출될 수 있습니다.
• --password-file <path>: 파일에서 게이트웨이 비밀번호 읽기.
• --tailscale <off|serve|funnel>: Tailscale을 통해 게이트웨이 노출.
• --tailscale-reset-on-exit: 종료 시 Tailscale serve/funnel 설정 초기화.
• --allow-unconfigured: 설정에 gateway.mode=local 없이 게이트웨이 시작 허용.
• --dev: 누락된 경우 개발 설정 + 워크스페이스 생성 (BOOTSTRAP.md 건너뜀).
• --reset: 개발 설정 + 자격 증명 + 세션 + 워크스페이스 초기화 (--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 경로.

실행 중인 게이트웨이 조회

모든 조회 명령어는 WebSocket RPC를 사용합니다.

출력 모드:

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

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

• --url <url>: 게이트웨이 WebSocket URL.
• --token <token>: 게이트웨이 토큰.
• --password <password>: 게이트웨이 비밀번호.
• --timeout <ms>: 타임아웃/예산 (명령어에 따라 다름).
• --expect-final: “최종” 응답 대기 (에이전트 호출).

참고: --url을 설정하면 CLI는 설정이나 환경 자격 증명으로 자동 폴백하지 않습니다. --token 또는 --password를 명시적으로 포함하세요. 명시적 자격 증명이 누락되면 오류가 발생합니다.

gateway health

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

gateway status

gateway status는 게이트웨이 서비스(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 status는 가능한 경우 구성된 인증 SecretRef를 점검 인증에 해석합니다.
• 필요한 인증 SecretRef가 이 명령어 경로에서 해석되지 않은 경우, 점검 인증이 실패할 수 있습니다; --token/--password를 명시적으로 전달하거나 시크릿 소스를 먼저 해석하세요.
• Linux systemd 설치에서 서비스 인증 드리프트 검사는 유닛에서 Environment=과 EnvironmentFile= 값을 모두 읽습니다(%h, 따옴표 경로, 여러 파일, 선택적 - 파일 포함).

gateway probe

gateway probe는 “모든 것을 디버그하는” 명령어입니다. 항상 다음을 점검합니다:

• 구성된 원격 게이트웨이(설정된 경우), 그리고
• 원격이 구성되어 있어도 localhost(루프백)를 점검합니다.

여러 게이트웨이에 접근 가능한 경우, 모두 출력합니다. 격리된 프로필/포트(예: 구조 봇)를 사용할 때 여러 게이트웨이가 지원되지만, 대부분의 설치에서는 단일 게이트웨이를 실행합니다.

openclaw gateway probe
openclaw gateway probe --json

SSH를 통한 원격 (Mac 앱 동등)

macOS 앱 “SSH를 통한 원격” 모드는 로컬 포트 포워드를 사용하여 원격 게이트웨이(루프백에만 바인딩되어 있을 수 있음)를 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>: ID 파일.
• --ssh-auto: 발견된 첫 번째 게이트웨이 호스트를 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}'

게이트웨이 서비스 관리

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

참고:

• gateway install은 --port, --runtime, --token, --force, --json을 지원합니다.
• 토큰 인증에 토큰이 필요하고 gateway.auth.token이 SecretRef로 관리되는 경우, gateway install은 SecretRef가 해석 가능한지 유효성 검사하지만 해석된 토큰을 서비스 환경 메타데이터에 저장하지 않습니다.
• 토큰 인증에 토큰이 필요하고 구성된 토큰 SecretRef가 해석되지 않은 경우, install은 폴백 평문을 저장하는 대신 닫힌 상태로 실패합니다.
• gateway run에서 비밀번호 인증의 경우, 인라인 --password보다 OPENCLAW_GATEWAY_PASSWORD, --password-file 또는 SecretRef 기반 gateway.auth.password를 사용하는 것이 좋습니다.
• 추론된 인증 모드에서 셸 전용 OPENCLAW_GATEWAY_PASSWORD/CLAWDBOT_GATEWAY_PASSWORD는 install 토큰 요구 사항을 완화하지 않습니다; 관리 서비스를 설치할 때는 지속적인 설정(gateway.auth.password 또는 config env)을 사용하세요.
• gateway.auth.token과 gateway.auth.password가 모두 구성되어 있고 gateway.auth.mode가 설정되지 않은 경우, 모드가 명시적으로 설정될 때까지 install이 차단됩니다.
• 생명주기 명령어는 스크립팅을 위해 --json을 지원합니다.

게이트웨이 디스커버리 (Bonjour)

gateway discover는 게이트웨이 비콘(_openclaw-gw._tcp)을 검색합니다.

• 멀티캐스트 DNS-SD: local.
• 유니캐스트 DNS-SD (광역 Bonjour): 도메인을 선택하고(예: openclaw.internal.) 분할 DNS + DNS 서버를 설정합니다; /gateway/bonjour 참조

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

광역 디스커버리 레코드에 포함되는 항목 (TXT):

• role (게이트웨이 역할 힌트)
• 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'