Gateway

Gateway는 OpenClaw의 WebSocket 서버입니다(채널, Node, 세션, 훅). 이 페이지의 하위 명령은 openclaw gateway … 아래에 있습니다.

# Gateway 실행

로컬 Gateway 프로세스를 실행합니다.

openclaw gateway

포그라운드 별칭:

openclaw gateway run

# 옵션

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> WebSocket 포트(기본값은 구성/env에서 가져오며, 일반적으로 18789).

"--bind

"--auth

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdG9rZW4gPHRva2Vu " type="string"> 토큰 재정의(프로세스에 대해 OPENCLAW_GATEWAY_TOKEN도 설정).

"--password

"--tailscale

--tailscale-reset-on-exitboolean

종료 시 Tailscale serve/funnel 구성을 초기화합니다.

--allow-unconfiguredboolean

구성에 gateway.mode=local이 없어도 Gateway 시작을 허용합니다. 임시/개발 부트스트랩에만 시작 가드를 우회하며, 구성 파일을 작성하거나 복구하지는 않습니다.

--devboolean

누락된 경우 개발 구성 + 워크스페이스를 생성합니다(BOOTSTRAP.md 건너뜀).

--resetboolean

개발 구성 + 자격 증명 + 세션 + 워크스페이스를 초기화합니다(--dev 필요).

--forceboolean

시작하기 전에 선택한 포트의 기존 리스너를 모두 종료합니다.

--verboseboolean

자세한 로그.

--cli-backend-logsboolean

콘솔에 CLI 백엔드 로그만 표시합니다(stdout/stderr도 활성화).

"--ws-log

--compactboolean

--ws-log compact의 별칭.

--raw-streamboolean

원시 모델 스트림 이벤트를 jsonl에 기록합니다.

# Gateway 재시작

openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --force

openclaw gateway restart --safe는 실행 중인 Gateway에 재시작 전에 활성 OpenClaw 작업을 사전 점검하도록 요청합니다. 대기 중인 작업, 답장 전달, 임베디드 실행 또는 작업 실행이 활성 상태이면 Gateway는 차단 요인을 보고하고, 중복된 안전 재시작 요청을 병합하며, 활성 작업이 모두 빠진 뒤 재시작합니다. 일반 restart는 호환성을 위해 기존 서비스 관리자 동작을 유지합니다. 즉시 재정의 경로를 명시적으로 원할 때만 --force를 사용하세요.

# 시작 프로파일링

• Gateway 시작 중 단계별 타이밍을 기록하려면 OPENCLAW_GATEWAY_STARTUP_TRACE=1을 설정하세요. 여기에는 단계별 eventLoopMax 지연 및 설치된 인덱스, 매니페스트 레지스트리, 시작 계획, 소유자 맵 작업에 대한 Plugin 조회 테이블 타이밍이 포함됩니다.
• 외부 QA 하네스를 위한 최선형 JSONL 시작 진단 타임라인을 작성하려면 OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>와 함께 OPENCLAW_DIAGNOSTICS=timeline을 설정하세요. 구성에서 diagnostics.flags: ["timeline"]로 플래그를 활성화할 수도 있습니다. 경로는 여전히 env로 제공됩니다. 이벤트 루프 샘플을 포함하려면 OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1을 추가하세요.
• Gateway 시작을 벤치마크하려면 pnpm test:startup:gateway -- --runs 5 --warmup 1을 실행하세요. 벤치마크는 첫 프로세스 출력, /healthz, /readyz, 시작 추적 타이밍, 이벤트 루프 지연, Plugin 조회 테이블 타이밍 세부 정보를 기록합니다.

# 실행 중인 Gateway 쿼리

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

# gateway health

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

HTTP /healthz 엔드포인트는 라이브니스 프로브입니다. 서버가 HTTP에 응답할 수 있으면 반환됩니다. HTTP /readyz 엔드포인트는 더 엄격하며, 시작 Plugin 사이드카, 채널 또는 구성된 훅이 아직 안정화 중이면 빨간 상태를 유지합니다. 로컬 또는 인증된 상세 준비 상태 응답에는 이벤트 루프 지연, 이벤트 루프 사용률, CPU 코어 비율, degraded 플래그가 포함된 eventLoop 진단 블록이 포함됩니다.

# gateway usage-cost

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

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

"--days

# gateway stability

실행 중인 Gateway에서 최근 진단 안정성 레코더를 가져옵니다.

openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --bundle latest
openclaw gateway stability --bundle latest --export
openclaw gateway stability --json

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tbGltaXQgPGxpbWl0 " type="number" default="25"> 포함할 최근 이벤트의 최대 수(최대 1000).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdHlwZSA8dHlwZQ " type="string"> payload.large 또는 diagnostic.memory.pressure 같은 진단 이벤트 유형으로 필터링합니다.

"--since-seq

--bundle [path]string

실행 중인 Gateway를 호출하는 대신 유지된 안정성 번들을 읽습니다. 상태 디렉터리 아래의 최신 번들에는 --bundle latest(또는 단순히 --bundle)를 사용하거나, 번들 JSON 경로를 직접 전달하세요.

--exportboolean

안정성 세부 정보를 출력하는 대신 공유 가능한 지원 진단 zip을 작성합니다.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tb3V0cHV0IDxwYXRo " type="string"> --export의 출력 경로.

# gateway diagnostics export

버그 보고서에 첨부하도록 설계된 로컬 진단 zip을 작성합니다. 개인정보 보호 모델 및 번들 내용은 진단 내보내기를 참조하세요.

openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json

"--log-lines

"--log-bytes

"--url

"--token

"--password

"--timeout

--no-stability-bundleboolean

유지된 안정성 번들 조회를 건너뜁니다.

--jsonboolean

작성된 경로, 크기, 매니페스트를 JSON으로 출력합니다.

내보내기에는 매니페스트, Markdown 요약, 구성 형태, 정리된 구성 세부 정보, 정리된 로그 요약, 정리된 Gateway 상태/상태 점검 스냅샷, 그리고 존재하는 경우 최신 안정성 번들이 포함됩니다.

이는 공유를 목적으로 합니다. 디버깅에 도움이 되는 운영 세부 정보를 유지합니다. 예를 들어 안전한 OpenClaw 로그 필드, 하위 시스템 이름, 상태 코드, 기간, 구성된 모드, 포트, Plugin ID, 제공자 ID, 비밀이 아닌 기능 설정, 수정 처리된 운영 로그 메시지가 포함됩니다. 채팅 텍스트, Webhook 본문, 도구 출력, 자격 증명, 쿠키, 계정/메시지 식별자, 프롬프트/지침 텍스트, 호스트 이름, 비밀 값은 생략하거나 수정 처리합니다. LogTape 스타일 메시지가 사용자/채팅/도구 페이로드 텍스트처럼 보이면, 내보내기는 메시지가 생략되었다는 사실과 해당 바이트 수만 유지합니다.

# gateway status

gateway status는 Gateway 서비스(launchd/systemd/schtasks)와 연결성/인증 기능의 선택적 프로브를 표시합니다.

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

"--url

"--token

"--password

"--timeout

--no-probeboolean

연결성 프로브를 건너뜁니다(서비스 전용 보기).

--deepboolean

시스템 수준 서비스도 스캔합니다.

--require-rpcboolean

기본 연결성 프로브를 읽기 프로브로 업그레이드하고 해당 읽기 프로브가 실패하면 0이 아닌 코드로 종료합니다. --no-probe와 함께 사용할 수 없습니다.

# gateway probe

gateway probe는 "모든 것을 디버그"하는 명령입니다. 항상 다음을 프로브합니다.

• 구성된 원격 Gateway(설정된 경우), 그리고
• 원격이 구성되어 있어도 localhost(loopback)를 프로브합니다.

--url을 전달하면 해당 명시적 대상이 둘보다 앞에 추가됩니다. 사람이 읽는 출력은 대상을 다음과 같이 표시합니다.

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

openclaw gateway probe
openclaw gateway probe --json

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

macOS 앱의 "Remote over SSH" 모드는 로컬 포트 포워드를 사용하여 원격 Gateway(loopback에만 바인딩되어 있을 수 있음)가 ws://127.0.0.1:<port>에서 도달 가능하게 만듭니다.

CLI에 해당하는 명령:

openclaw gateway probe --ssh user@gateway-host

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc3NoIDx0YXJnZXQ " type="string"> user@host 또는 user@host:port(포트 기본값은 22).

--ssh-autoboolean

해석된 발견 엔드포인트(local.과 구성된 광역 도메인, 있는 경우)에서 처음 발견된 Gateway 호스트를 SSH 대상으로 선택합니다. TXT 전용 힌트는 무시됩니다.

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

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

# gateway call <method>

저수준 RPC 헬퍼입니다.

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

"--params

"--url

"--token

"--password

"--timeout

--expect-finalboolean

주로 최종 페이로드 전에 중간 이벤트를 스트리밍하는 에이전트 스타일 RPC용입니다.

--jsonboolean

기계가 읽을 수 있는 JSON 출력입니다.

# Gateway 서비스 관리

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

# 래퍼로 설치

관리형 서비스가 다른 실행 파일을 통해 시작되어야 할 때 --wrapper를 사용하세요. 예를 들어 시크릿 관리자 shim 또는 run-as 헬퍼가 있습니다. 래퍼는 일반 Gateway 인자를 받고 최종적으로 해당 인자로 openclaw 또는 Node를 exec할 책임이 있습니다.

cat > ~/.local/bin/openclaw-doppler <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart

환경을 통해 래퍼를 설정할 수도 있습니다. gateway install은 경로가 실행 가능한 파일인지 검증하고, 래퍼를 서비스 ProgramArguments에 쓰며, 이후 강제 재설치, 업데이트, doctor 복구를 위해 서비스 환경에 OPENCLAW_WRAPPER를 유지합니다.

OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor

유지된 래퍼를 제거하려면 재설치하는 동안 OPENCLAW_WRAPPER를 비우세요.

OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw gateway restart

# Gateway 발견(Bonjour)

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

• 멀티캐스트 DNS-SD: local.
• 유니캐스트 DNS-SD(Wide-Area Bonjour): 도메인(예: openclaw.internal.)을 선택하고 split DNS + DNS 서버를 설정하세요. Bonjour를 참조하세요.

Bonjour 발견이 활성화된 Gateway(기본값)만 비컨을 광고합니다.

Wide-Area 발견 레코드에는 다음이 포함됩니다(TXT).

• role(Gateway 역할 힌트)
• transport(전송 힌트, 예: gateway)
• gatewayPort(WebSocket 포트, 일반적으로 18789)
• sshPort(선택 사항; 없으면 클라이언트는 기본 SSH 대상을 22로 설정)
• tailnetDns(사용 가능한 경우 MagicDNS 호스트 이름)
• gatewayTls / gatewayTlsSha256(TLS 활성화 + 인증서 지문)
• cliPath(wide-area 영역에 기록되는 원격 설치 힌트)

# gateway discover

openclaw gateway discover

"--timeout

--jsonboolean

기계가 읽을 수 있는 출력(스타일/스피너도 비활성화).

예:

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

# 관련 항목

• CLI 참조
• Gateway 런북