Gateway는 OpenClaw의 WebSocket 서버입니다(채널, 노드, 세션, 훅). 이 페이지의 하위 명령은Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw gateway … 아래에 있습니다.
Bonjour 검색
로컬 mDNS + 광역 DNS-SD 설정.
검색 개요
OpenClaw가 Gateway를 알리고 찾는 방식.
구성
최상위 Gateway 구성 키.
Gateway 실행
로컬 Gateway 프로세스를 실행합니다.시작 동작
시작 동작
- 기본적으로 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 입력으로 감싸는 경우 종료 전에 터미널을 복원하세요.
옵션
WebSocket 포트(기본값은 구성/env에서 가져오며, 보통
18789).리스너 바인드 모드.
인증 모드 재정의.
토큰 재정의(프로세스에
OPENCLAW_GATEWAY_TOKEN도 설정).비밀번호 재정의.
파일에서 Gateway 비밀번호를 읽습니다.
Tailscale을 통해 Gateway를 노출합니다.
종료 시 Tailscale serve/funnel 구성을 재설정합니다.
구성에
gateway.mode=local이 없어도 Gateway 시작을 허용합니다. 임시/개발 부트스트랩 전용으로 시작 가드를 우회하며, 구성 파일을 작성하거나 복구하지 않습니다.없으면 개발 구성 + 워크스페이스를 생성합니다(BOOTSTRAP.md 건너뜀).
개발 구성 + 자격 증명 + 세션 + 워크스페이스를 재설정합니다(
--dev 필요).시작 전에 선택한 포트의 기존 리스너를 종료합니다.
자세한 로그.
콘솔에 CLI 백엔드 로그만 표시합니다(stdout/stderr 활성화 포함).
Websocket 로그 스타일.
--ws-log compact의 별칭.원시 모델 스트림 이벤트를 jsonl에 기록합니다.
원시 스트림 jsonl 경로.
Gateway 재시작
openclaw gateway restart --safe는 실행 중인 Gateway에 재시작 전에 활성 OpenClaw 작업을 사전 점검하도록 요청합니다. 대기 중인 작업, 응답 전달, 임베디드 실행 또는 태스크 실행이 활성 상태이면 Gateway가 차단 요소를 보고하고, 중복 안전 재시작 요청을 병합하며, 활성 작업이 비워진 뒤 재시작합니다. 일반 restart는 호환성을 위해 기존 서비스 관리자 동작을 유지합니다. 즉시 재정의 경로를 명시적으로 원하는 경우에만 --force를 사용하세요.
openclaw gateway restart --safe --skip-deferral은 --safe와 동일한 OpenClaw 인식 조율 재시작을 실행하지만, 활성 작업 지연 게이트를 우회하여 차단 요소가 보고되더라도 Gateway가 즉시 재시작을 내보내도록 합니다. 멈춘 태스크 실행으로 지연이 고정되어 --safe만으로는 무기한 대기할 때 운영자 탈출구로 사용하세요. --skip-deferral에는 --safe가 필요합니다.
시작 프로파일링
- Gateway 시작 중 단계별
eventLoopMax지연 및 설치된 인덱스, 매니페스트 레지스트리, 시작 계획, 소유자 맵 작업에 대한 Plugin 조회 테이블 타이밍을 포함한 단계 타이밍을 기록하려면OPENCLAW_GATEWAY_STARTUP_TRACE=1을 설정하세요. - 외부 QA 하네스용 최선 노력 JSONL 시작 진단 타임라인을 작성하려면
OPENCLAW_DIAGNOSTICS=timeline을OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>와 함께 설정하세요. 구성에서diagnostics.flags: ["timeline"]으로 플래그를 활성화할 수도 있으며, 경로는 여전히 env로 제공됩니다. 이벤트 루프 샘플을 포함하려면OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1을 추가하세요. - Gateway 시작을 벤치마크하려면
pnpm test:startup:gateway -- --runs 5 --warmup 1을 실행하세요. 벤치마크는 첫 프로세스 출력,/healthz,/readyz, 시작 추적 타이밍, 이벤트 루프 지연, Plugin 조회 테이블 타이밍 세부 정보를 기록합니다.
실행 중인 Gateway 쿼리
모든 쿼리 명령은 WebSocket RPC를 사용합니다.- 출력 모드
- 공유 옵션
- 기본값: 사람이 읽기 쉬운 형식(TTY에서 색상 표시).
--json: 기계가 읽기 쉬운 JSON(스타일링/스피너 없음).--no-color(또는NO_COLOR=1): 사람용 레이아웃은 유지하면서 ANSI를 비활성화합니다.
--url을 설정하면 CLI는 구성 또는 환경 자격 증명으로 폴백하지 않습니다. --token 또는 --password를 명시적으로 전달하세요. 명시적 자격 증명이 없으면 오류입니다.gateway health
/healthz 엔드포인트는 생존성 프로브입니다. 서버가 HTTP에 응답할 수 있으면 반환합니다. HTTP /readyz 엔드포인트는 더 엄격하며 시작 Plugin 사이드카, 채널 또는 구성된 훅이 아직 안정화되는 중이면 빨간색 상태를 유지합니다. 로컬 또는 인증된 상세 준비 상태 응답에는 이벤트 루프 지연, 이벤트 루프 사용률, CPU 코어 비율, degraded 플래그가 포함된 eventLoop 진단 블록이 포함됩니다.
gateway usage-cost
세션 로그에서 사용 비용 요약을 가져옵니다.
포함할 일수.
gateway stability
실행 중인 Gateway에서 최근 진단 안정성 레코더를 가져옵니다.
포함할 최근 이벤트의 최대 수(최대
1000).payload.large 또는 diagnostic.memory.pressure 같은 진단 이벤트 유형으로 필터링합니다.진단 시퀀스 번호 이후의 이벤트만 포함합니다.
실행 중인 Gateway를 호출하지 않고 영구 저장된 안정성 번들을 읽습니다. 상태 디렉터리 아래의 최신 번들은
--bundle latest(또는 그냥 --bundle)를 사용하거나, 번들 JSON 경로를 직접 전달하세요.안정성 세부 정보를 출력하는 대신 공유 가능한 지원 진단 zip을 작성합니다.
--export의 출력 경로.개인정보 및 번들 동작
개인정보 및 번들 동작
- 기록은 이벤트 이름, 개수, 바이트 크기, 메모리 측정값, 큐/세션 상태, 채널/Plugin 이름, 수정된 세션 요약 같은 운영 메타데이터를 유지합니다. 채팅 텍스트, Webhook 본문, 도구 출력, 원시 요청 또는 응답 본문, 토큰, 쿠키, 비밀 값, 호스트 이름 또는 원시 세션 ID는 유지하지 않습니다. 레코더를 완전히 비활성화하려면
diagnostics.enabled: false를 설정하세요. - 치명적인 Gateway 종료, 종료 제한 시간, 재시작 시작 실패 시, 레코더에 이벤트가 있으면 OpenClaw는 동일한 진단 스냅샷을
~/.openclaw/logs/stability/openclaw-stability-*.json에 작성합니다. 최신 번들은openclaw gateway stability --bundle latest로 검사하세요.--limit,--type,--since-seq도 번들 출력에 적용됩니다.
gateway diagnostics export
버그 보고서에 첨부하도록 설계된 로컬 진단 zip을 작성합니다. 개인정보 모델과 번들 내용은 진단 내보내기를 참조하세요.
출력 zip 경로. 기본값은 상태 디렉터리 아래의 지원 내보내기입니다.
포함할 정제된 로그 라인의 최대 수.
검사할 최대 로그 바이트 수.
상태 스냅샷용 Gateway WebSocket URL.
상태 스냅샷용 Gateway 토큰.
상태 스냅샷용 Gateway 비밀번호.
상태/헬스 스냅샷 제한 시간.
영구 저장된 안정성 번들 조회를 건너뜁니다.
작성된 경로, 크기, 매니페스트를 JSON으로 출력합니다.
gateway status
gateway status는 Gateway 서비스(launchd/systemd/schtasks)와 연결성/인증 기능의 선택적 프로브를 표시합니다.
명시적인 프로브 대상을 추가합니다. 구성된 원격 대상과 localhost도 계속 프로브됩니다.
프로브에 사용할 토큰 인증입니다.
프로브에 사용할 비밀번호 인증입니다.
프로브 제한 시간입니다.
연결성 프로브를 건너뜁니다(서비스 전용 보기).
시스템 수준 서비스도 스캔합니다.
기본 연결성 프로브를 읽기 프로브로 승격하고, 해당 읽기 프로브가 실패하면 0이 아닌 코드로 종료합니다.
--no-probe와 함께 사용할 수 없습니다.상태 의미
상태 의미
- 로컬 CLI 구성이 없거나 유효하지 않은 경우에도 진단을 위해
gateway status를 계속 사용할 수 있습니다. - 기본
gateway status는 서비스 상태, WebSocket 연결, 핸드셰이크 시점에 보이는 인증 기능을 증명합니다. 읽기/쓰기/관리 작업은 증명하지 않습니다. - 진단 프로브는 최초 장치 인증에서 변경을 만들지 않습니다. 기존 캐시된 장치 토큰이 있으면 재사용하지만, 상태 확인만을 위해 새 CLI 장치 ID나 읽기 전용 장치 페어링 레코드를 만들지는 않습니다.
gateway status는 가능한 경우 프로브 인증을 위해 구성된 인증 SecretRef를 해석합니다.- 이 명령 경로에서 필수 인증 SecretRef가 해석되지 않고 프로브 연결성/인증이 실패하면,
gateway status --json은rpc.authWarning을 보고합니다.--token/--password를 명시적으로 전달하거나 먼저 비밀 소스를 해석하세요. - 프로브가 성공하면, 잘못된 양성을 피하기 위해 해석되지 않은 인증 참조 경고는 숨겨집니다.
- 수신 중인 서비스만으로 충분하지 않고 읽기 범위 RPC 호출도 정상이어야 하는 스크립트와 자동화에서는
--require-rpc를 사용하세요. --deep은 추가 launchd/systemd/schtasks 설치에 대한 최선 노력 스캔을 추가합니다. Gateway와 유사한 서비스가 여러 개 감지되면, 사람용 출력은 정리 힌트를 출력하고 대부분의 설정에서는 머신당 하나의 Gateway만 실행해야 한다고 경고합니다.- 또한
--deep은 서비스 프로세스가 외부 supervisor 재시작을 위해 정상 종료된 경우 최근 Gateway supervisor 재시작 인계를 보고합니다. --deep은 Plugin 인식 모드(pluginValidation: "full")로 구성 검증을 실행하고, 설치 및 업데이트 스모크 검사가 이를 포착할 수 있도록 구성된 Plugin 매니페스트 경고(예: 누락된 채널 구성 메타데이터)를 표시합니다. 기본gateway status는 Plugin 검증을 건너뛰는 빠른 읽기 전용 경로를 유지합니다.- 사람용 출력에는 프로필 또는 상태 디렉터리 드리프트를 진단하는 데 도움이 되도록 해석된 파일 로그 경로와 CLI 대비 서비스 구성 경로/유효성 스냅샷이 포함됩니다.
Linux systemd 인증 드리프트 검사
Linux systemd 인증 드리프트 검사
- Linux systemd 설치에서는 서비스 인증 드리프트 검사가 유닛에서
Environment=및EnvironmentFile=값(%h, 인용된 경로, 여러 파일, 선택적-파일 포함)을 모두 읽습니다. - 드리프트 검사는 병합된 런타임 환경(먼저 서비스 명령 환경, 그다음 프로세스 환경 폴백)을 사용하여
gateway.auth.tokenSecretRef를 해석합니다. - 토큰 인증이 실질적으로 활성화되어 있지 않으면(명시적
gateway.auth.mode가password/none/trusted-proxy이거나, 모드가 설정되지 않았고 비밀번호가 우선될 수 있으며 토큰 후보가 우선될 수 없는 경우), 토큰 드리프트 검사는 구성 토큰 해석을 건너뜁니다.
gateway probe
gateway probe는 “모든 것을 디버그”하는 명령입니다. 항상 다음을 프로브합니다.
- 구성된 원격 Gateway(설정된 경우), 그리고
- 원격이 구성되어 있더라도 localhost(loopback).
--url을 전달하면 해당 명시적 대상이 둘보다 앞에 추가됩니다. 사람용 출력은 대상을 다음과 같이 표시합니다.
URL (explicit)Remote (configured)또는Remote (configured, inactive)Local loopback
여러 Gateway에 연결할 수 있으면 모두 출력합니다. 격리된 프로필/포트(예: 구조 봇)를 사용할 때는 여러 Gateway가 지원되지만, 대부분의 설치는 여전히 단일 Gateway를 실행합니다.
해석
해석
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가 제한됨을 의미합니다. 이는 전체 실패가 아니라 저하된 도달 가능성으로 보고됩니다.Connect: ok이후Read probe: failed는 Gateway가 WebSocket 연결을 수락했지만, 후속 읽기 진단이 시간 초과되었거나 실패했다는 뜻입니다. 이 역시 도달 불가능한 Gateway가 아니라 저하된 도달 가능성입니다.gateway status와 마찬가지로, 프로브는 기존 캐시된 장치 인증을 재사용하지만 최초 장치 ID나 페어링 상태를 만들지는 않습니다.- 종료 코드는 프로브된 대상 중 도달 가능한 대상이 없을 때만 0이 아닙니다.
JSON 출력
JSON 출력
최상위:
ok: 하나 이상의 대상에 도달할 수 있습니다.degraded: 하나 이상의 대상이 연결을 수락했지만 전체 세부 RPC 진단을 완료하지 못했습니다.capability: 도달 가능한 대상 전체에서 확인된 최상 기능(read_only,write_capable,admin_capable,pairing_pending,connected_no_operator_scope또는unknown)입니다.primaryTargetId: 다음 순서에서 활성 승자로 간주할 최적 대상: 명시적 URL, SSH 터널, 구성된 원격, local loopback.warnings[]:code,message, 선택적targetIds가 포함된 최선 노력 경고 레코드입니다.network: 현재 구성과 호스트 네트워킹에서 파생된 local loopback/tailnet URL 힌트입니다.discovery.timeoutMs및discovery.count: 이 프로브 패스에 사용된 실제 발견 예산/결과 수입니다.
targets[].connect):ok: 연결 이후 도달 가능성과 저하 분류입니다.rpcOk: 전체 세부 RPC 성공 여부입니다.scopeLimited: 누락된 operator 범위로 인해 세부 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 앱의 “SSH를 통한 원격” 모드는 로컬 포트 포워드를 사용하여 원격 Gateway(loopback에만 바인딩되어 있을 수 있음)를ws://127.0.0.1:<port>에서 도달 가능하게 만듭니다.
CLI 동등 명령:
user@host 또는 user@host:port입니다(포트 기본값은 22).ID 파일입니다.
해석된 발견 엔드포인트(
local.과 구성된 광역 도메인이 있는 경우 해당 도메인)에서 처음 발견된 Gateway 호스트를 SSH 대상으로 선택합니다. TXT 전용 힌트는 무시됩니다.gateway.remote.sshTargetgateway.remote.sshIdentity
gateway call <method>
저수준 RPC 헬퍼입니다.
매개변수용 JSON 객체 문자열입니다.
Gateway WebSocket URL입니다.
Gateway 토큰입니다.
Gateway 비밀번호입니다.
제한 시간 예산입니다.
주로 최종 페이로드 전에 중간 이벤트를 스트리밍하는 에이전트 스타일 RPC를 위한 옵션입니다.
머신이 읽을 수 있는 JSON 출력입니다.
--params는 유효한 JSON이어야 합니다.Gateway 서비스 관리
래퍼로 설치
관리형 서비스가 다른 실행 파일을 통해 시작해야 하는 경우--wrapper를 사용하세요. 예를 들어
비밀 관리자 shim이나 다른 사용자로 실행하는 헬퍼가 이에 해당합니다. 래퍼는 일반 Gateway 인수를 받으며,
궁극적으로 해당 인수로 openclaw 또는 Node를 exec해야 합니다.
gateway install은 경로가
실행 가능한 파일인지 검증하고, 래퍼를 서비스 ProgramArguments에 쓰며, 이후 강제 재설치, 업데이트, doctor
복구를 위해 서비스 환경에 OPENCLAW_WRAPPER를 유지합니다.
OPENCLAW_WRAPPER를 비우세요.
명령 옵션
명령 옵션
gateway status:--url,--token,--password,--timeout,--no-probe,--require-rpc,--deep,--jsongateway install:--port,--runtime <node|bun>,--token,--wrapper <path>,--force,--jsongateway restart:--safe,--skip-deferral,--force,--wait <duration>,--jsongateway uninstall|start:--jsongateway stop:--disable,--json
수명 주기 동작
수명 주기 동작
- 관리형 서비스를 다시 시작하려면
gateway restart를 사용하세요. 재시작 대체 수단으로gateway stop과gateway start를 연결하지 마세요. - macOS에서
gateway stop은 기본적으로launchctl bootout을 사용하며, 이는 비활성화를 영구 적용하지 않고 현재 부팅 세션에서 LaunchAgent를 제거합니다. 향후 충돌에 대한 KeepAlive 자동 복구는 계속 활성 상태로 유지되며,gateway start는 수동launchctl enable없이도 깔끔하게 다시 활성화됩니다. KeepAlive와 RunAtLoad를 영구적으로 억제하여 다음 명시적gateway start까지 gateway가 다시 생성되지 않게 하려면--disable을 전달하세요. 수동 중지가 재부팅 또는 시스템 재시작 후에도 유지되어야 할 때 사용하세요. gateway restart --safe는 실행 중인 Gateway에 활성 OpenClaw 작업을 사전 확인하고, 답장 전달, 임베디드 실행, 작업 실행이 모두 비워질 때까지 재시작을 지연하도록 요청합니다.--safe는--force또는--wait와 함께 사용할 수 없습니다.gateway restart --wait 30s는 해당 재시작에 대해 구성된 재시작 드레인 예산을 재정의합니다. 단위 없는 숫자는 밀리초이며,s,m,h같은 단위가 허용됩니다.--wait 0은 무기한 대기합니다.gateway restart --safe --skip-deferral은 OpenClaw 인식 안전 재시작을 실행하지만, 차단 요소가 보고되더라도 Gateway가 즉시 재시작을 내보내도록 지연 게이트를 우회합니다. 멈춘 작업 실행 지연을 위한 운영자 탈출구이며,--safe가 필요합니다.gateway restart --force는 활성 작업 드레인을 건너뛰고 즉시 다시 시작합니다. 운영자가 나열된 작업 차단 요소를 이미 검토했고 지금 gateway를 복구하려는 경우 사용하세요.- 수명 주기 명령은 스크립팅을 위해
--json을 허용합니다.
설치 시 인증 및 SecretRefs
설치 시 인증 및 SecretRefs
- 토큰 인증에 토큰이 필요하고
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가 설정되지 않은 경우, 모드가 명시적으로 설정될 때까지 설치가 차단됩니다.
gateway 검색(Bonjour)
gateway discover는 Gateway 비콘(_openclaw-gw._tcp)을 스캔합니다.
- 멀티캐스트 DNS-SD:
local. - 유니캐스트 DNS-SD(Wide-Area Bonjour): 도메인(예:
openclaw.internal.)을 선택하고 분할 DNS와 DNS 서버를 설정하세요. Bonjour를 참조하세요.
role(gateway 역할 힌트)transport(전송 힌트, 예:gateway)gatewayPort(WebSocket 포트, 일반적으로18789)sshPort(전체 검색 모드 전용. 없을 때 클라이언트는 SSH 대상을 기본값22로 설정)tailnetDns(사용 가능한 경우 MagicDNS 호스트 이름)gatewayTls/gatewayTlsSha256(TLS 활성화 + 인증서 지문)cliPath(전체 검색 모드 전용)
gateway discover
명령별 제한 시간(찾아보기/확인).
기계 판독 가능 출력(스타일/스피너도 비활성화).
- CLI는
local.과, 활성화된 경우 구성된 광역 도메인을 함께 스캔합니다. - JSON 출력의
wsUrl은lanHost또는tailnetDns같은 TXT 전용 힌트가 아니라 확인된 서비스 엔드포인트에서 파생됩니다. local.mDNS 및 광역 DNS-SD에서sshPort와cliPath는discovery.mdns.mode가full일 때만 게시됩니다.