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을 넘어 바인딩하는 것은 차단됩니다(안전 가드레일).
• lan, tailnet, custom은 현재 IPv4 전용 BYOH 경로를 통해 해석됩니다.
• 현재 이 경로에서는 IPv6 전용 BYOH가 기본 지원되지 않습니다. 호스트 자체가 IPv6 전용이면 IPv4 사이드카 또는 프록시를 사용하세요.
• SIGUSR1은 승인된 경우 프로세스 내 재시작을 트리거합니다(commands.restart는 기본적으로 활성화됨. 수동 재시작을 차단하려면 commands.restart: false를 설정하세요. 단, Gateway 도구/구성 적용/업데이트는 계속 허용됨).
• SIGINT/SIGTERM 핸들러는 Gateway 프로세스를 중지하지만, 사용자 지정 터미널 상태를 복원하지는 않습니다. CLI를 TUI 또는 raw 모드 입력으로 래핑하는 경우 종료 전에 터미널을 복원하세요.

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

• gateway status는 로컬 CLI 구성이 없거나 유효하지 않아도 진단을 위해 계속 사용할 수 있습니다.
• 기본 gateway status는 서비스 상태, WebSocket 연결, 핸드셰이크 시점에 보이는 auth 기능을 증명합니다. 읽기/쓰기/admin 작업을 증명하지는 않습니다.
• 진단 프로브는 최초 기기 auth에 대해 변경을 일으키지 않습니다. 기존 캐시된 기기 토큰이 있으면 재사용하지만, 상태를 확인하기 위해 새 CLI 기기 ID나 읽기 전용 기기 페어링 레코드를 만들지는 않습니다.
• gateway status는 가능한 경우 프로브 auth를 위해 구성된 auth SecretRefs를 해석합니다.
• 이 명령 경로에서 필수 auth SecretRef가 해석되지 않으면, gateway status --json은 프로브 연결/auth가 실패할 때 rpc.authWarning을 보고합니다. --token/--password를 명시적으로 전달하거나 먼저 비밀 소스를 해석하세요.
• 프로브가 성공하면, 미해석 auth-ref 경고는 오탐을 피하기 위해 억제됩니다.
• 프로브가 활성화된 경우 실행 중인 Gateway가 보고하면 JSON 출력에 gateway.version이 포함됩니다. 후속 핸드셰이크 프로브가 버전 메타데이터를 제공할 수 없으면 --require-rpc는 status.runtimeVersion RPC 페이로드로 대체할 수 있습니다.
• 수신 중인 서비스만으로는 부족하고 읽기 범위 RPC 호출도 정상이어야 하는 스크립트와 자동화에서는 --require-rpc를 사용하세요.
• --deep은 추가 launchd/systemd/schtasks 설치에 대한 최선 노력 스캔을 추가합니다. 여러 gateway 유사 서비스가 감지되면 사람이 읽는 출력은 정리 힌트를 출력하고 대부분의 설정에서는 머신당 하나의 gateway를 실행해야 한다고 경고합니다.
• --deep은 서비스 프로세스가 외부 supervisor 재시작을 위해 정상 종료된 경우 최근 Gateway supervisor 재시작 인계도 보고합니다.
• --deep은 plugin 인식 모드(pluginValidation: "full")에서 구성 검증을 실행하고, 구성된 plugin 매니페스트 경고(예: 누락된 채널 구성 메타데이터)를 표시해 설치 및 업데이트 스모크 점검에서 이를 잡을 수 있게 합니다. 기본 gateway status는 plugin 검증을 건너뛰는 빠른 읽기 전용 경로를 유지합니다.
• 사람이 읽는 출력에는 해석된 파일 로그 경로와 CLI-vs-service 구성 경로/유효성 스냅샷이 포함되어 프로필 또는 state-dir 드리프트를 진단하는 데 도움이 됩니다.

• Linux systemd 설치에서 서비스 auth 드리프트 점검은 unit의 Environment= 및 EnvironmentFile= 값을 모두 읽습니다(%h, 따옴표로 감싼 경로, 여러 파일, 선택적 - 파일 포함).
• 드리프트 점검은 병합된 런타임 env(서비스 명령 env 우선, 그다음 프로세스 env fallback)를 사용해 gateway.auth.token SecretRefs를 해석합니다.
• 토큰 auth가 실질적으로 활성 상태가 아니면(명시적 gateway.auth.mode가 password/none/trusted-proxy이거나, 모드가 설정되지 않았고 비밀번호가 우선될 수 있으며 어떤 토큰 후보도 우선될 수 없는 경우), 토큰 드리프트 점검은 구성 토큰 해석을 건너뜁니다.

• Reachable: yes는 하나 이상의 대상이 WebSocket 연결을 수락했다는 뜻입니다.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only는 프로브가 auth에 대해 증명할 수 있었던 것을 보고합니다. 도달 가능성과는 별개입니다.
• 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와 마찬가지로, 프로브는 기존 캐시된 기기 auth를 재사용하지만 최초 기기 ID나 페어링 상태를 만들지는 않습니다.
• 종료 코드는 프로브된 대상 중 도달 가능한 대상이 없을 때만 0이 아닙니다.

최상위:

• 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: 이 프로브 패스에 사용된 실제 discovery 예산/결과 수입니다.

대상별(targets[].connect):

• ok: 연결 + 성능 저하 분류 이후의 도달 가능성입니다.
• rpcOk: 전체 세부 RPC 성공입니다.
• scopeLimited: operator scope 누락으로 세부 RPC가 실패했습니다.

대상별(targets[].auth):

• role: 사용 가능한 경우 hello-ok에 보고된 auth 역할입니다.
• scopes: 사용 가능한 경우 hello-ok에 보고된 부여된 scopes입니다.
• capability: 해당 대상에 대해 표시된 auth 기능 분류입니다.

• ssh_tunnel_failed: SSH 터널 설정이 실패했습니다. 명령은 직접 프로브로 fallback했습니다.
• multiple_gateways: 서로 다른 gateway ID에 도달할 수 있었거나, OpenClaw가 도달 가능한 대상들이 같은 gateway임을 증명할 수 없었습니다. 같은 gateway를 가리키는 SSH 터널, proxy URL 또는 구성된 원격 URL은 이 경고를 발생시키지 않습니다.
• auth_secretref_unresolved: 실패한 대상에 대해 구성된 auth SecretRef를 해석할 수 없었습니다.
• probe_scope_limited: WebSocket 연결은 성공했지만 읽기 프로브가 누락된 operator.read로 인해 제한되었습니다.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --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 없이도 깔끔하게 다시 활성화합니다. Gateway가 다음 명시적 gateway start 전까지 다시 생성되지 않도록 KeepAlive와 RunAtLoad를 지속적으로 억제하려면 --disable을 전달하세요. 수동 중지가 재부팅이나 시스템 재시작 후에도 유지되어야 할 때 사용합니다.
• gateway restart --safe는 실행 중인 Gateway에 활성 작업을 사전 점검하고 활성 작업이 비워진 뒤 하나로 합쳐진 재시작을 예약하도록 요청합니다. 기본 안전 재시작은 구성된 gateway.reload.deferralTimeoutMs까지 활성 작업을 기다립니다(기본값 5분). 해당 예산이 만료되면 재시작이 강제됩니다. 절대 강제하지 않고 무기한 안전 대기를 하려면 gateway.reload.deferralTimeoutMs를 0으로 설정하세요. --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을 허용합니다.

• 토큰 인증에 토큰이 필요하고 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가 설정되지 않은 경우, 모드를 명시적으로 설정할 때까지 설치가 차단됩니다.