OpenClaw Gateway CLI 사용법: 로컬 서버 실행 및 설정 가이드

Gateway CLI 개요

Gateway는 OpenClaw의 WebSocket 서버로, 채널, Node.js, 세션 및 webhook을 관리하는 핵심 역할을 수행합니다. 이 페이지에서 다루는 모든 하위 명령어는 openclaw gateway 명령어를 통해 실행할 수 있습니다.

Gateway 서비스 시작하기

이 명령어를 사용하면 로컬 환경에서 OpenClaw Gateway 서버를 즉시 실행할 수 있습니다. 서버가 정상적으로 시작되면 JSON 형식의 로그를 통해 상태를 확인할 수 있습니다.

터미널에서 다음 명령어를 입력하여 Gateway를 시작하세요.

openclaw gateway start

특정 포트나 설정을 지정해야 하는 경우, CLI 플래그를 사용하여 서버 환경을 조정할 수 있습니다.

openclaw gateway start --port 8080 --config ./config.yaml

Gateway 상태 확인하기

현재 실행 중인 Gateway의 연결 상태나 활성화된 세션 정보를 확인하고 싶을 때 이 명령어를 사용합니다. 시스템이 Docker 컨테이너 내부에서 동작 중인지, 아니면 직접 Node.js 프로세스로 실행 중인지에 관계없이 동일한 정보를 제공합니다.

현재 활성화된 Gateway의 상태를 조회하려면 아래 명령어를 실행하세요.

openclaw gateway status

상세한 디버깅 정보가 필요하다면 상세 모드 플래그를 추가하여 더 많은 데이터를 확인하세요.

openclaw gateway status --verbose

Gateway 로그 확인하기

Gateway에서 발생하는 모든 이벤트와 API 호출 기록을 실시간으로 추적할 수 있습니다. 문제 해결이나 트래픽 모니터링이 필요할 때 매우 유용하게 사용할 수 있습니다.

실시간 로그 스트림을 확인하려면 다음 명령어를 사용하세요.

openclaw gateway logs

특정 시간대의 로그만 필터링하거나 파일로 저장하고 싶다면 npm 환경에서 제공하는 표준 출력 리다이렉션을 활용할 수 있습니다.

openclaw gateway logs --follow > gateway.log

Gateway 설정 검증하기

설정 파일에 오류가 없는지 미리 확인하는 것은 서비스 중단을 방지하는 가장 좋은 방법입니다. pnpm이나 GitHub 액션을 통해 배포하기 전, 이 명령어로 설정을 검증하는 습관을 들이는 것이 좋습니다.

현재 설정 파일의 유효성을 검사하려면 다음 명령어를 실행하세요.

openclaw gateway validate

검증 결과는 JSON 형태로 출력되며, 설정 오류가 발견될 경우 구체적인 위치와 원인을 알려줍니다.

openclaw gateway validate --config ./config.yaml

Gateway 실행하기

로컬 환경에서 Gateway 프로세스를 실행하려면 다음 명령어를 사용하세요.

openclaw gateway

포그라운드에서 실행하기 위한 별칭은 다음과 같습니다.

openclaw gateway run

참고 사항은 다음과 같습니다.

기본적으로 Gateway는 ~/.openclaw/openclaw.json 파일에 gateway.mode=local이 설정되어 있지 않으면 실행을 거부합니다. 임시 실행이나 개발 환경에서는 --allow-unconfigured 옵션을 사용하세요.
openclaw onboard --mode local 및 openclaw setup 명령은 gateway.mode=local을 자동으로 기록합니다. 만약 파일은 존재하지만 gateway.mode 설정이 누락되었다면, 이를 암묵적으로 로컬 모드로 간주하지 않고 설정이 손상된 것으로 판단하여 복구하도록 안내합니다.
파일이 존재하는데 gateway.mode가 누락된 경우, Gateway는 이를 의심스러운 설정 손상으로 간주하며 사용자를 대신해 로컬 모드를 “추측”하여 실행하지 않습니다.
인증 없이 루프백(loopback) 외부로 바인딩하는 것은 안전상의 이유로 차단됩니다.
SIGUSR1 신호는 권한이 부여된 경우 프로세스 내부 재시작을 트리거합니다. (commands.restart는 기본적으로 활성화되어 있습니다. 수동 재시작을 차단하려면 commands.restart: false로 설정하세요. 단, Gateway 도구, 설정 적용 및 업데이트는 계속 허용됩니다.)
SIGINT/SIGTERM 핸들러는 Gateway 프로세스를 중지하지만, 사용자 지정 터미널 상태를 복원하지는 않습니다. 만약 CLI를 TUI나 raw-mode 입력으로 래핑했다면, 종료 전에 터미널을 직접 복원해야 합니다.

옵션

Gateway 실행 시 사용할 수 있는 다양한 옵션들을 통해 동작을 세밀하게 제어할 수 있습니다.

--port <port>: WebSocket 포트를 지정합니다 (기본값은 설정/환경 변수에서 가져오며, 보통 18789입니다).
--bind <loopback|lan|tailnet|auto|custom>: 리스너 바인드 모드를 설정합니다.
--auth <token|password>: 인증 모드를 재정의합니다.
--token <token>: 토큰을 재정의합니다 (프로세스에 OPENCLAW_GATEWAY_TOKEN 환경 변수도 설정합니다).
--password <password>: 비밀번호를 재정의합니다. 주의: 인라인 비밀번호는 로컬 프로세스 목록에 노출될 수 있습니다.
--password-file <path>: 파일에서 Gateway 비밀번호를 읽어옵니다.
--tailscale <off|serve|funnel>: Tailscale을 통해 Gateway를 노출합니다.
--tailscale-reset-on-exit: 종료 시 Tailscale serve/funnel 설정을 초기화합니다.
--allow-unconfigured: 설정 파일에 gateway.mode=local 없이도 Gateway를 시작할 수 있게 합니다. 이는 임시/개발용 부트스트랩을 위한 시작 가드 우회용이며, 설정 파일을 작성하거나 복구하지는 않습니다.
--dev: 설정 파일이 없을 경우 개발용 설정 및 작업 공간을 생성합니다 (BOOTSTRAP.md 단계를 건너뜁니다).
--reset: 개발용 설정, 자격 증명, 세션 및 작업 공간을 초기화합니다 (--dev 옵션이 필요합니다).
--force: 시작 전 선택한 포트에서 실행 중인 기존 리스너를 강제로 종료합니다.
--verbose: 상세 로그를 출력합니다.
--cli-backend-logs: 콘솔에 CLI 백엔드 로그만 표시합니다 (stdout/stderr 활성화).
--ws-log <auto|full|compact>: WebSocket 로그 스타일을 설정합니다 (기본값은 auto).
--compact: --ws-log compact의 별칭입니다.
--raw-stream: 원시 모델 스트림 이벤트를 JSON 형식으로 기록합니다.
--raw-stream-path <path>: 원시 스트림 JSON 파일 경로를 지정합니다.

시작 프로파일링 관련 정보입니다.

OPENCLAW_GATEWAY_STARTUP_TRACE=1을 설정하여 Gateway 시작 중 단계별 타이밍을 기록할 수 있습니다.
pnpm test:startup:gateway -- --runs 5 --warmup 1을 실행하여 Gateway 시작 성능을 벤치마킹하세요. 이 벤치마크는 첫 번째 프로세스 출력, /healthz, /readyz 및 시작 추적 타이밍을 기록합니다.

실행 중인 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)” 응답(에이전트 호출)을 기다립니다.

참고: --url을 설정하면 CLI는 설정 파일이나 환경 변수의 자격 증명으로 대체하지 않습니다. --token 또는 --password를 명시적으로 전달하세요. 자격 증명을 명시하지 않으면 오류가 발생합니다.

gateway health

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

HTTP /healthz 엔드포인트는 라이브니스 프로브(liveness probe)로, 서버가 HTTP 응답을 할 수 있게 되면 즉시 반환됩니다. HTTP /readyz 엔드포인트는 더 엄격하며, 시작 시 필요한 사이드카, 채널 또는 설정된 훅(hook)이 아직 준비 중일 때는 계속 빨간색 상태를 유지합니다.

gateway usage-cost

세션 로그에서 사용 비용 요약을 가져옵니다.

openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json

옵션:

--days <days>: 포함할 일수 (기본값 30).

gateway status

gateway status는 Gateway 서비스(launchd/systemd/schtasks) 상태와 연결성/인증 기능에 대한 선택적 프로브 결과를 보여줍니다.

openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc

옵션:

--url <url>: 명시적인 프로브 대상을 추가합니다. 설정된 원격 대상과 로컬호스트도 여전히 프로브됩니다.
--token <token>: 프로브를 위한 토큰 인증.
--password <password>: 프로브를 위한 비밀번호 인증.
--timeout <ms>: 프로브 타임아웃 (기본값 10000).
--no-probe: 연결성 프로브를 건너뜁니다 (서비스 전용 뷰).
--deep: 시스템 수준 서비스까지 스캔합니다.
--require-rpc: 기본 연결성 프로브를 읽기 프로브로 업그레이드하며, 읽기 프로브 실패 시 0이 아닌 값을 반환합니다. --no-probe와 함께 사용할 수 없습니다.

참고:

gateway status는 로컬 CLI 설정이 없거나 유효하지 않은 경우에도 진단을 위해 사용할 수 있습니다.
기본 gateway status는 서비스 상태, WebSocket 연결, 핸드셰이크 시점에 확인 가능한 인증 기능을 증명합니다. 읽기/쓰기/관리 작업까지 증명하지는 않습니다.
gateway status는 가능할 때 프로브 인증을 위해 설정된 인증 SecretRefs를 확인합니다.
이 명령어 경로에서 필수 인증 SecretRefs가 확인되지 않으면, gateway status --json은 프로브 연결/인증 실패 시 rpc.authWarning을 보고합니다. --token/--password를 명시적으로 전달하거나 먼저 비밀 소스를 확인하세요.
프로브가 성공하면, 확인되지 않은 인증 참조 경고는 오탐을 방지하기 위해 억제됩니다.
리스닝 서비스만으로는 부족하고 읽기 범위의 RPC 호출도 정상인지 확인해야 하는 스크립트나 자동화 작업에서는 --require-rpc를 사용하세요.
--deep은 추가적인 launchd/systemd/schtasks 설치를 최선을 다해 스캔합니다. 여러 개의 Gateway 유사 서비스가 감지되면, 사람이 읽기 쉬운 출력에 정리 힌트가 표시되며 대부분의 설정은 머신당 하나의 Gateway를 실행해야 한다고 경고합니다.
사람이 읽기 쉬운 출력에는 확인된 파일 로그 경로와 CLI 대 서비스 설정 경로/유효성 스냅샷이 포함되어 프로필이나 상태 디렉토리의 차이를 진단하는 데 도움을 줍니다.
Linux systemd 설치의 경우, 서비스 인증 드리프트 체크는 유닛에서 Environment= 및 EnvironmentFile= 값을 모두 읽습니다 (%h, 인용된 경로, 여러 파일 및 선택적 - 파일 포함).
드리프트 체크는 병합된 런타임 환경(서비스 명령어 환경 우선, 그 다음 프로세스 환경)을 사용하여 gateway.auth.token SecretRefs를 확인합니다.
토큰 인증이 효과적으로 활성화되지 않은 경우(gateway.auth.mode가 password/none/trusted-proxy로 명시되었거나, 모드가 설정되지 않아 비밀번호가 우선하고 토큰 후보가 없는 경우), 토큰 드리프트 체크는 설정 토큰 확인을 건너뜁니다.

gateway probe

gateway probe는 “모든 것을 디버깅”하는 명령어입니다. 항상 다음을 프로브합니다:

설정된 원격 Gateway (설정된 경우), 그리고
로컬호스트(루프백) (원격이 설정되어 있어도 프로브함).

--url을 전달하면 해당 명시적 대상이 둘 다보다 먼저 추가됩니다. 사람이 읽기 쉬운 출력에는 대상을 다음과 같이 라벨링합니다:

URL (explicit)
Remote (configured) 또는 Remote (configured, inactive)
Local loopback

여러 Gateway에 도달할 수 있는 경우, 모두 출력합니다. 여러 Gateway는 격리된 프로필/포트를 사용할 때(예: 구조용 봇) 지원되지만, 대부분의 설치는 단일 Gateway를 실행합니다.

openclaw gateway probe
openclaw gateway probe --json

해석:

Reachable: yes: 적어도 하나의 대상이 WebSocket 연결을 수락했음을 의미합니다.
Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only: 프로브가 인증에 대해 증명할 수 있는 내용을 보고합니다. 이는 도달 가능성과는 별개입니다.
Read probe: ok: 읽기 범위 세부 RPC 호출(health/status/system-presence/config.get)도 성공했음을 의미합니다.
Read probe: limited - missing scope: operator.read: 연결은 성공했으나 읽기 범위 RPC가 제한되었음을 의미합니다. 이는 완전한 실패가 아닌 degraded(성능 저하) 도달 가능성으로 보고됩니다.
종료 코드는 프로브된 대상에 도달할 수 없는 경우에만 0이 아닌 값이 됩니다.

JSON 참고 (--json):

최상위 레벨:
- ok: 적어도 하나의 대상에 도달 가능.
- degraded: 적어도 하나의 대상에서 범위 제한 세부 RPC 발생.
- capability: 도달 가능한 대상들에서 확인된 최상의 기능(read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope, 또는 unknown).
- primaryTargetId: 다음 순서로 활성 승자로 간주할 최상의 대상: 명시적 URL, SSH 터널, 설정된 원격, 로컬 루프백.
- warnings[]: code, message 및 선택적 targetIds를 포함한 최선의 경고 기록.
- network: 현재 설정 및 호스트 네트워킹에서 파생된 로컬 루프백/Tailnet URL 힌트.
- discovery.timeoutMs 및 discovery.count: 이번 프로브 패스에 사용된 실제 검색 예산/결과 수.
대상별 (targets[].connect):
- ok: 연결 후 도달 가능성 + 성능 저하 분류.
- rpcOk: 전체 세부 RPC 성공.
- scopeLimited: 운영자 범위 누락으로 인한 세부 RPC 실패.
대상별 (targets[].auth):
- role: 사용 가능한 경우 hello-ok에서 보고된 인증 역할.
- scopes: 사용 가능한 경우 hello-ok에서 보고된 부여된 범위.
- capability: 해당 대상에 대해 표면화된 인증 기능 분류.

공통 경고 코드:

ssh_tunnel_failed: SSH 터널 설정 실패; 명령어가 직접 프로브로 대체되었습니다.
multiple_gateways: 둘 이상의 대상에 도달 가능; 구조용 봇과 같이 의도적으로 격리된 프로필을 실행하는 경우가 아니면 드문 상황입니다.
auth_secretref_unresolved: 실패한 대상에 대해 설정된 인증 SecretRef를 확인할 수 없습니다.
probe_scope_limited: WebSocket 연결은 성공했으나 읽기 프로브가 operator.read 누락으로 제한되었습니다.

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>: ID 파일.
--ssh-auto: 확인된 검색 엔드포인트(local. 및 설정된 광역 도메인)에서 SSH 대상으로 발견된 첫 번째 Gateway 호스트를 선택합니다. TXT 전용 힌트는 무시됩니다.

설정 (선택 사항, 기본값으로 사용):

gateway.remote.sshTarget
gateway.remote.sshIdentity

gateway call <method>

저수준 RPC 도우미입니다.

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

옵션:

--params <json>: 매개변수를 위한 JSON 객체 문자열 (기본값 {}).
--url <url>
--token <token>
--password <password>
--timeout <ms>
--expect-final
--json

참고:

--params는 유효한 JSON이어야 합니다.
--expect-final은 주로 최종 페이로드 이전에 중간 이벤트를 스트리밍하는 에이전트 스타일 RPC를 위한 것입니다.

AI Setup Assistant

Gateway 서비스 관리하기

OpenClaw Gateway 서비스를 효율적으로 관리하면 시스템의 안정성을 유지하고 원활한 API 통신을 보장할 수 있습니다. 아래의 CLI 명령어를 사용하여 서비스를 제어해 보세요.

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

Gateway 명령어 옵션

각 명령어는 특정 상황에 맞춰 세부 설정을 조정할 수 있는 다양한 옵션을 제공합니다. 필요한 경우 JSON 형식으로 결과를 출력하여 스크립트 작업에 활용할 수 있습니다.

gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
gateway install: --port, --runtime <node|bun>, --token, --force, --json
gateway uninstall|start|stop|restart: --json

Gateway 서비스 설정 및 주의사항

서비스를 설치하거나 구성할 때 다음 지침을 따르면 보안과 안정성을 모두 챙길 수 있습니다. 특히 Node.js 환경이나 기타 런타임 설정 시 아래 내용을 참고하세요.

gateway install 명령어는 --port, --runtime, --token, --force, --json 옵션을 지원합니다.
토큰 인증이 필요하고 gateway.auth.token이 SecretRef로 관리되는 경우, gateway install은 해당 SecretRef가 해결 가능한지 확인하지만, 해결된 토큰을 서비스 환경 메타데이터에 영구적으로 저장하지는 않습니다.
토큰 인증이 필요한데 구성된 토큰 SecretRef를 확인할 수 없는 경우, 설치는 실패하며 일반 텍스트로 된 대체 값을 저장하지 않습니다.
gateway run에서 비밀번호 인증을 사용할 때는 인라인 --password 대신 OPENCLAW_GATEWAY_PASSWORD, --password-file 또는 SecretRef 기반의 gateway.auth.password를 사용하는 것을 권장합니다.
추론된 인증 모드에서 셸 전용 OPENCLAW_GATEWAY_PASSWORD는 설치 시 요구되는 토큰 조건을 완화하지 않습니다. 관리형 서비스를 설치할 때는 영구적인 구성(gateway.auth.password 또는 구성 env)을 사용하세요.
gateway.auth.token과 gateway.auth.password가 모두 구성되어 있고 gateway.auth.mode가 설정되지 않은 경우, 모드가 명시적으로 설정될 때까지 설치가 차단됩니다.
모든 수명 주기 명령어는 스크립트 작성을 위해 --json 옵션을 허용합니다.

AI Setup Assistant

Gateway 검색 (Bonjour)

OpenClaw를 사용하면 Gateway 비콘(_openclaw-gw._tcp)을 스캔하여 네트워크 내의 Gateway를 쉽게 찾을 수 있습니다.

Multicast DNS-SD: local. 도메인을 사용합니다.
Unicast DNS-SD (Wide-Area Bonjour): 특정 도메인(예: openclaw.internal.)을 선택하고 split DNS와 DNS 서버를 설정해야 합니다. 자세한 내용은 /gateway/bonjour 문서를 확인해 주세요.

기본적으로 Bonjour 검색 기능이 활성화된 Gateway만 비콘을 광고합니다.

Wide-Area 검색 레코드에는 다음과 같은 TXT 정보가 포함됩니다.

role (Gateway 역할 힌트)
transport (전송 방식 힌트, 예: gateway)
gatewayPort (WebSocket 포트, 일반적으로 18789)
sshPort (선택 사항; 값이 없으면 클라이언트는 기본적으로 22번 포트를 SSH 대상으로 사용합니다)
tailnetDns (사용 가능한 경우 MagicDNS 호스트 이름)
gatewayTls / gatewayTlsSha256 (TLS 활성화 여부 및 인증서 지문)
cliPath (Wide-Area 영역에 기록된 원격 설치 힌트)

gateway discover 명령어 사용하기

OpenClaw의 CLI를 통해 네트워크상의 Gateway를 검색하는 방법은 매우 간단합니다. 아래 명령어를 터미널에 입력하여 실행해 보세요.

openclaw gateway discover

옵션은 다음과 같습니다.

--timeout <ms>: 명령별 타임아웃(검색/확인) 시간입니다. 기본값은 2000입니다.
--json: 기계가 읽을 수 있는 JSON 형식으로 출력합니다 (스타일 및 스피너 기능은 비활성화됩니다).

사용 예시는 다음과 같습니다.

openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'

참고 사항:

CLI는 local. 도메인과 설정된 Wide-Area 도메인을 모두 스캔합니다.
JSON 출력의 wsUrl은 TXT 힌트(lanHost나 tailnetDns 등)가 아닌, 확인된 서비스 엔드포인트에서 파생됩니다.
local. mDNS 환경에서 sshPort와 cliPath는 discovery.mdns.mode가 full로 설정된 경우에만 브로드캐스트됩니다. Wide-Area DNS-SD는 항상 cliPath를 기록하며, sshPort는 여전히 선택 사항입니다.

AI Setup Assistant

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.