OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

Gateway

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

Bonjour 검색

로컬 mDNS + 광역 DNS-SD 설정.
검색 개요

OpenClaw가 Gateway를 알리고 찾는 방법.
구성

최상위 Gateway 구성 키.

Gateway 실행

bash
openclaw gatewayopenclaw gateway run   # 동일한 명시적 형식
시작 동작
  • ~/.openclaw/openclaw.json에 gateway.mode=local이 설정되어 있지 않으면 시작을 거부합니다. 임시/개발 실행에는 --allow-unconfigured를 사용하세요. 이 플래그는 구성을 기록하거나 복구하지 않고 보호 검사를 우회합니다.
  • openclaw onboard --mode local과 openclaw setup은 gateway.mode=local을 기록합니다. 구성 파일은 있지만 gateway.mode가 없으면 손상되었거나 덮어써진 구성으로 간주하며, Gateway는 사용자를 대신해 local이라고 추측하지 않고 시작을 거부합니다. 온보딩을 다시 실행하거나, 키를 수동으로 설정하거나, --allow-unconfigured를 전달하세요.
  • 인증 없이 루프백 외부에 바인딩하는 것은 차단됩니다.
  • 현재 --bind 값 lan, tailnet, custom은 IPv4 전용 경로를 통해 해석됩니다. IPv6 전용 자체 호스트 설정에서는 Gateway 앞에 IPv4 사이드카나 프록시가 필요합니다.
  • 권한이 있으면 SIGUSR1이 프로세스 내 재시작을 트리거합니다. commands.restart(기본값: 활성화)는 외부에서 전송된 SIGUSR1을 제어합니다. false로 설정하면 gateway restart 명령, Gateway 도구, 구성 적용/업데이트를 통한 재시작은 계속 허용하면서 수동 OS 신호 재시작을 차단합니다.
  • SIGINT/SIGTERM은 프로세스를 중지하지만 사용자 지정 터미널 상태를 복원하지 않습니다. CLI를 TUI나 원시 모드 입력으로 감싸는 경우 종료 전에 터미널을 직접 복원하세요.

옵션

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> WebSocket 포트(구성/환경의 기본값, 일반적으로 18789).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tYmluZCA8bW9kZQ " type="string"> 바인딩 모드: loopback(기본값), lan, tailnet, auto, custom.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdG9rZW4gPHRva2Vu " type="string"> connect.params.auth.token의 공유 토큰. OPENCLAW_GATEWAY_TOKEN이 설정되어 있으면 해당 값이 기본값입니다.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tYXV0aCA8bW9kZQ " type="string"> 인증 모드: none, token, password, trusted-proxy.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcGFzc3dvcmQgPHBhc3N3b3Jk " type="string"> --auth password의 비밀번호.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdGFpbHNjYWxlIDxtb2Rl " type="string"> Tailscale 노출 방식: off, serve, funnel.

--tailscale-reset-on-exitboolean

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

--allow-unconfiguredboolean

gateway.mode=local을 강제하지 않고 시작합니다. 임시/개발 부트스트랩 전용이며, 구성을 저장하거나 복구하지 않습니다.

--devboolean

개발용 구성과 작업 공간이 없으면 생성합니다(BOOTSTRAP.md는 건너뜀).

--resetboolean

개발용 구성, 자격 증명, 세션, 작업 공간을 초기화합니다. --dev가 필요합니다.

--forceboolean

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

--verboseboolean

stdout/stderr에 상세 로그를 출력합니다.

--cli-backend-logsboolean

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

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0td3MtbG9nIDxzdHlsZQ " type="string" default="auto"> WebSocket 로그 형식: auto, full, compact.

--compactboolean

--ws-log compact의 별칭입니다.

--raw-streamboolean

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

--claude-cli-logs는 더 이상 사용되지 않는 --cli-backend-logs의 별칭입니다.

--bind custom의 경우 gateway.customBindHost를 IPv4 주소로 설정하세요. 127.0.0.1 또는 0.0.0.0 이외의 주소를 사용하면 동일 호스트 클라이언트를 위해 같은 포트의 127.0.0.1도 필요합니다. 어느 한 리스너라도 바인딩할 수 없으면 시작에 실패합니다. 와일드카드 0.0.0.0은 별도의 필수 별칭을 추가하지 않습니다. IPv6 전용 자체 호스트 설정에서는 Gateway 앞에 IPv4 사이드카나 프록시가 필요합니다.

Gateway 재시작

bash
openclaw gateway restartopenclaw gateway restart --safeopenclaw gateway restart --safe --skip-deferralopenclaw gateway restart --forceopenclaw gateway restart --wait 30s

--safe는 실행 중인 Gateway에 활성 작업을 사전 점검하고 해당 작업이 모두 소진된 후 하나로 병합된 재시작을 예약하도록 요청합니다. 대기 시간은 gateway.reload.deferralTimeoutMs(기본값: 5분/300000)로 제한되며, 제한 시간이 만료되면 재시작이 강제됩니다. 강제하지 않고 무기한 대기하려면(주기적으로 아직 대기 중이라는 경고 표시) deferralTimeoutMs: 0으로 설정하세요. --safe는 --force 또는 --wait와 함께 사용할 수 없습니다.

--skip-deferral은 안전한 재시작에서 활성 작업 지연 게이트를 우회하므로, 보고된 차단 요소가 있어도 Gateway가 즉시 재시작됩니다. --safe가 필요합니다. 폭주 작업으로 지연이 멈춘 경우 사용하세요.

--wait <duration>은 일반(비안전) 재시작의 작업 소진 제한 시간을 재정의합니다. 단위 없는 밀리초 또는 단위 접미사 ms, s, m, h, d를 사용할 수 있습니다(예: 30s, 5m, 1h30m). --wait 0은 무기한 대기합니다. --force 또는 --safe와 함께 사용할 수 없습니다.

--force는 활성 작업 소진을 건너뛰고 즉시 재시작합니다. 플래그 없는 일반 restart는 기존 서비스 관리자 재시작 동작을 유지합니다.

Gateway 프로파일링

  • OPENCLAW_GATEWAY_STARTUP_TRACE=1은 시작 중 단계별 타이밍을 기록합니다. 여기에는 단계별 eventLoopMax 지연과 Plugin 조회 테이블 타이밍(설치된 인덱스, 매니페스트 레지스트리, 시작 계획, 소유자 맵 작업)이 포함됩니다.
  • OPENCLAW_GATEWAY_RESTART_TRACE=1은 재시작 범위의 restart trace: 행을 기록합니다. 신호 처리, 활성 작업 소진, 종료 단계, 다음 시작, 준비 타이밍, 메모리 지표가 포함됩니다.
  • OPENCLAW_DIAGNOSTICS=timeline과 OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>를 함께 사용하면 외부 QA 하네스를 위한 최선형 JSONL 시작 진단 타임라인을 기록합니다(구성의 diagnostics.flags: ["timeline"]과 동일하며, 경로는 계속 환경 변수로만 지정할 수 있음). 이벤트 루프 샘플을 포함하려면 OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1을 추가하세요.
  • pnpm build 후 pnpm test:startup:gateway -- --runs 5 --warmup 1을 실행하면 빌드된 CLI 진입점을 기준으로 Gateway 시작을 벤치마크합니다. 최초 프로세스 출력, /healthz, /readyz, 시작 추적 타이밍, 이벤트 루프 지연, Plugin 조회 테이블 타이밍을 측정합니다.
  • pnpm build 후 pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5를 실행하면 macOS 또는 Linux에서 프로세스 내 재시작을 벤치마크합니다(Windows에서는 지원되지 않으며 재시작에 SIGUSR1이 필요함). SIGUSR1을 사용하고 자식 프로세스에서 두 추적을 모두 활성화하며, 다음 /healthz, 다음 /readyz, 중단 시간, 준비 타이밍, CPU, RSS, 재시작 추적 지표를 기록합니다.
  • /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" 응답을 기다립니다(에이전트 호출).

gateway health

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

/healthz는 생존 상태 프로브로, 서버가 HTTP에 응답할 수 있게 되는 즉시 반환합니다. /readyz는 더 엄격하며 시작 Plugin 사이드카, 채널 또는 구성된 훅이 아직 안정화 중이면 준비되지 않은 상태로 유지됩니다. 로컬 또는 인증된 상세 /readyz 응답에는 eventLoop 진단 블록(지연, 사용률, CPU 코어 비율, degraded 플래그)이 포함됩니다.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> 이 포트의 로컬 루프백 Gateway를 대상으로 지정합니다. 이 호출에서 OPENCLAW_GATEWAY_URL과 OPENCLAW_GATEWAY_PORT를 재정의합니다.

gateway usage-cost

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

bash
openclaw gateway usage-costopenclaw gateway usage-cost --days 7openclaw gateway usage-cost --agent work --jsonopenclaw gateway usage-cost --all-agentsopenclaw gateway usage-cost --json
"--days
"--agent
--all-agentsboolean

구성된 모든 에이전트를 통합합니다. --agent와 함께 사용할 수 없습니다.

gateway stability

실행 중인 Gateway에서 최근 진단 안정성 기록을 가져옵니다.

bash
openclaw gateway stabilityopenclaw gateway stability --type payload.largeopenclaw gateway stability --bundle latestopenclaw gateway stability --bundle latest --exportopenclaw 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의 출력 경로.

개인정보 보호 및 번들 동작
  • 기록에는 이벤트 이름, 횟수, 바이트 크기, 메모리 측정값, 대기열/세션 상태, 승인 ID, 채널/Plugin 이름, 수정 처리된 세션 요약 등의 운영 메타데이터가 유지됩니다. 채팅 텍스트, Webhook 본문, 도구 출력, 원시 요청/응답 본문, 토큰, 쿠키, 비밀 값, 호스트 이름, 원시 세션 ID는 제외됩니다. 기록기를 완전히 비활성화하려면 diagnostics.enabled: false를 설정하세요.
  • 치명적인 Gateway 종료, 종료 시간 초과, 재시작 시작 실패가 발생하면 기록기에 이벤트가 있는 경우 동일한 진단 스냅샷을 ~/.openclaw/logs/stability/openclaw-stability-*.json에 기록합니다. openclaw gateway stability --bundle latest로 최신 번들을 확인하세요. --limit, --type, --since-seq는 번들 출력에도 적용됩니다.

gateway diagnostics export

버그 보고용으로 설계된 로컬 진단 ZIP 파일을 기록합니다. 개인정보 보호 모델과 번들 내용은 진단 내보내기를 참조하세요.

bash
openclaw gateway diagnostics exportopenclaw gateway diagnostics export --output openclaw-diagnostics.zipopenclaw gateway diagnostics export --json
"--log-lines
"--log-bytes
"--url
"--token
"--password
"--timeout
--no-stability-bundleboolean

저장된 안정성 번들 조회를 건너뜁니다.

--jsonboolean

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

내보내기에는 manifest.json(파일 목록), summary.md(Markdown 요약), diagnostics.json(최상위 구성/로그/검색/안정성/상태/상태 점검 요약), config/sanitized.json, status/gateway-status.json, health/gateway-health.json, logs/openclaw-sanitized.jsonl이 포함되며, 번들이 존재하는 경우 stability/latest.json도 포함됩니다.

이 내보내기는 공유할 수 있도록 설계되었습니다. 디버깅에 유용한 운영 세부 정보(안전한 로그 필드, 하위 시스템 이름, 상태 코드, 소요 시간, 구성된 모드, 포트, Plugin/제공자 ID, 비밀이 아닌 기능 설정, 민감 정보가 제거된 운영 로그 메시지)는 유지하고, 채팅 텍스트, Webhook 본문, 도구 출력, 자격 증명, 쿠키, 계정/메시지 식별자, 프롬프트/지침 텍스트, 호스트 이름 및 비밀 값은 생략하거나 민감 정보를 제거합니다. 로그 메시지가 사용자/채팅/도구 페이로드 텍스트처럼 보이는 경우(예: "사용자가 말함", "채팅 텍스트", "도구 출력", "Webhook 본문"), 내보내기에는 메시지가 생략되었다는 사실과 해당 바이트 수만 유지됩니다.

gateway status

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

bash
openclaw gateway statusopenclaw gateway status --jsonopenclaw gateway status --require-rpc
"--url
"--token
"--password
"--timeout
--no-probeboolean

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

--deepboolean

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

--require-rpcboolean

연결 프로브를 읽기 프로브로 강화하고 실패하면 0이 아닌 값으로 종료합니다. --no-probe와 함께 사용할 수 없습니다.

상태 의미
  • 로컬 CLI 구성이 없거나 잘못된 경우에도 진단에 계속 사용할 수 있습니다.
  • 기본 출력은 서비스 상태, WebSocket 연결, 핸드셰이크 시점에 확인 가능한 인증 기능을 입증하며, 읽기/쓰기/관리자 작업을 입증하지는 않습니다.
  • 최초 장치 인증을 변경하지 않는 방식으로 프로브합니다. 기존에 캐시된 장치 토큰이 있으면 재사용하지만, 상태를 확인하기 위해 새로운 CLI 장치 ID나 읽기 전용 페어링 레코드를 생성하지 않습니다.
  • 가능한 경우 프로브 인증을 위해 구성된 인증 SecretRef를 확인합니다. 필수 SecretRef를 확인할 수 없고 프로브 연결/인증이 실패하면 --json은 rpc.authWarning을 보고합니다. --token/--password를 명시적으로 전달하거나 비밀 소스를 수정하십시오. 프로브가 성공하면 확인되지 않은 인증 경고는 표시되지 않습니다.
  • 실행 중인 Gateway가 버전을 보고하면 JSON 출력에 gateway.version이 포함됩니다. 핸드셰이크 프로브가 버전 메타데이터를 제공할 수 없는 경우 --require-rpc는 status.runtimeVersion RPC 페이로드를 대신 사용할 수 있습니다.
  • 수신 대기 중인 서비스만으로 충분하지 않고 읽기 범위 RPC도 정상이어야 하는 스크립트/자동화에서는 --require-rpc를 사용하십시오.
  • --deep은 추가 launchd/systemd/schtasks 설치를 검색합니다. Gateway와 유사한 서비스가 여러 개 발견되면 사람이 읽는 출력에 정리 힌트(일반적으로 시스템당 Gateway 하나 실행)를 표시하고, 해당하는 경우 최근 감독자 재시작 인계도 보고합니다.
  • --deep은 Plugin 인식 모드(pluginValidation: "full")에서 구성 유효성 검사도 실행하고 Plugin 매니페스트 경고(예: 누락된 채널 구성 메타데이터)를 표시합니다. 기본 gateway status는 Plugin 유효성 검사를 건너뛰는 빠른 읽기 전용 경로를 유지합니다.
  • 사람이 읽는 출력에는 확인된 파일 로그 경로와 CLI 및 서비스의 구성 경로/유효성이 포함되어 프로필 또는 상태 디렉터리 불일치를 진단하는 데 도움이 됩니다.
Linux systemd 인증 불일치 검사
  • 서비스 인증 불일치 검사는 유닛의 Environment=와 EnvironmentFile=을 모두 읽습니다(%h, 따옴표로 묶인 경로, 여러 파일, 선택적 - 파일 포함).
  • 병합된 런타임 환경(서비스 명령 환경 우선, 이후 프로세스 환경 대체)을 사용하여 gateway.auth.token SecretRef를 확인합니다.
  • 토큰 인증이 실질적으로 활성 상태가 아닌 경우(gateway.auth.mode가 명시적으로 password/none/trusted-proxy이거나, 모드가 설정되지 않았고 비밀번호가 우선할 수 있으며 우선 가능한 토큰 후보가 없는 경우) 토큰 불일치 검사는 구성 토큰 확인을 건너뜁니다.

gateway probe

"모든 항목 디버깅" 명령입니다. 항상 다음을 프로브합니다.

  • 구성된 원격 Gateway(설정된 경우)
  • localhost(local loopback), 원격 대상이 구성되어 있어도 프로브함

--url을 전달하면 해당 명시적 대상이 두 대상보다 앞에 추가됩니다. 사람이 읽는 출력에서는 대상을 URL (명시적), 원격 (구성됨) / 원격 (구성됨, 비활성), local loopback으로 표시합니다.

bash
openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --port 18789

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> local loopback 프로브 대상과 SSH 터널 원격 포트에 이 포트를 사용합니다. --url이 없으면 구성된 Gateway 환경 URL, 환경 포트 또는 원격 대상 대신 local loopback 대상만 선택합니다.

해석
  • 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는 WebSocket은 연결되었지만 후속 읽기 진단 시간이 초과되거나 실패했음을 의미합니다. 이 역시 연결 불가가 아니라 성능 저하 상태입니다.
  • gateway status와 마찬가지로 프로브는 기존에 캐시된 장치 인증을 재사용하지만 최초 장치 ID나 페어링 상태를 생성하지 않습니다.
  • 프로브한 대상 중 연결 가능한 대상이 하나도 없을 때만 종료 코드가 0이 아닙니다.
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): 가능한 경우 hello-ok에 보고된 role과 scopes, 그리고 표시된 capability 분류입니다.

일반적인 경고 코드
  • ssh_tunnel_failed: SSH 터널 설정에 실패하여 명령이 직접 프로브로 대체되었습니다.
  • multiple_gateways: 서로 다른 Gateway ID에 연결할 수 있었거나, OpenClaw가 연결 가능한 대상이 동일한 Gateway인지 입증할 수 없었습니다. 동일한 Gateway를 가리키는 SSH 터널, 프록시 URL 또는 구성된 원격 URL은 이 경고를 발생시키지 않습니다.
  • auth_secretref_unresolved: 실패한 대상에 대해 구성된 인증 SecretRef를 확인할 수 없습니다.
  • probe_scope_limited: WebSocket 연결은 성공했지만 operator.read 누락으로 읽기 프로브가 제한되었습니다.
  • local_tls_runtime_unavailable: 로컬 Gateway TLS가 활성화되어 있지만 OpenClaw가 로컬 인증서 지문을 불러올 수 없습니다.

SSH를 통한 원격 연결(Mac 앱과 동일)

macOS 앱의 "Remote over SSH" 모드는 로컬 포트 전달을 사용하여 루프백 전용 원격 Gateway에 ws://127.0.0.1:<port>로 연결할 수 있도록 합니다.

CLI에서 동일한 명령:

bash
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 도우미입니다.

bash
openclaw gateway call statusopenclaw gateway call logs.tail --params '{"limit": 200}'
"--params
"--url
"--token
"--password
"--timeout
--expect-finalboolean

최종 페이로드 전에 중간 이벤트를 스트리밍하는 에이전트 유형 RPC에 주로 사용됩니다.

--jsonboolean

기계 판독 가능한 JSON 출력입니다.

Gateway 서비스 관리

bash
openclaw gateway installopenclaw gateway startopenclaw gateway stopopenclaw gateway restartopenclaw gateway uninstall

래퍼를 사용하여 설치

관리 서비스가 다른 실행 파일을 통해 시작되어야 할 때는 --wrapper를 사용합니다. 예를 들어 비밀 관리자 심 또는 다른 사용자로 실행하기 위한 도우미를 사용할 수 있습니다. 래퍼는 일반 Gateway 인수를 전달받으며, 최종적으로 해당 인수를 사용해 openclaw 또는 Node를 exec하는 역할을 담당합니다.

bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'#!/usr/bin/env bashset -euo pipefailexec doppler run --project my-project --config production -- openclaw "$@"EOFchmod +x ~/.local/bin/openclaw-doppler openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --forceopenclaw gateway restart

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

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

영구 저장된 래퍼를 제거하려면 재설치할 때 OPENCLAW_WRAPPER를 비우십시오.

bash
OPENCLAW_WRAPPER= openclaw gateway install --forceopenclaw gateway restart
명령 옵션
  • gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
  • gateway install: --port, --runtime <node|bun> (기본값: node), --token, --wrapper <path>, --force, --json
  • gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
  • gateway uninstall|start: --json
  • gateway 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을 전달하십시오. 수동 중지 상태를 재부팅 후에도 유지해야 할 때 사용합니다.
  • 수명 주기 명령은 스크립팅을 위한 --json을 지원합니다.
설치 시 인증 및 SecretRef
  • 토큰 인증에 토큰이 필요하고 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(광역 Bonjour): 도메인(예: openclaw.internal.)을 선택하고 분할 DNS와 DNS 서버를 설정하십시오. Bonjour를 참조하십시오.

Bonjour 검색이 활성화된 Gateway(기본값)만 비콘을 알립니다.

모든 비콘의 TXT 힌트: role(Gateway 역할 힌트), transport(전송 힌트, 예: gateway), gatewayPort(WebSocket 포트, 일반적으로 18789), tailnetDns(사용 가능한 경우 MagicDNS 호스트 이름), gatewayTls / gatewayTlsSha256(TLS 활성화 여부 및 인증서 지문). sshPort와 cliPath는 전체 검색 모드에서만 게시됩니다(discovery.mdns.mode: "full"; 기본값은 "minimal"이며 이 항목들을 생략합니다. 이 경우 클라이언트는 SSH 대상의 기본 포트로 22를 사용합니다).

gateway discover

bash
openclaw gateway discover
"--timeout
--jsonboolean

머신 판독 가능 출력(스타일 및 스피너도 비활성화).

예시:

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

관련 항목

Was this useful?
On this page

On this page