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

CLI commands

QR

openclaw qr

현재 Gateway 구성에서 모바일 페어링 QR과 설정 코드를 생성합니다.

bash
openclaw qropenclaw qr --setup-code-onlyopenclaw qr --jsonopenclaw qr --remoteopenclaw qr --url wss://gateway.example/ws

공식 OpenClaw iOS 및 Android 앱은 설정 코드 메타데이터가 일치하면 자동으로 연결됩니다. 요청이 대기 상태로 남아 있는 경우(예: 비공식 클라이언트이거나 메타데이터가 일치하지 않는 경우) 요청을 검토하고 승인하세요.

bash
openclaw devices listopenclaw devices approve <requestId>

옵션

  • --remote: gateway.remote.url을 우선 사용하며, 해당 URL이 설정되지 않은 경우 gateway.tailscale.mode=serve|funnel로 대체합니다. device-pair Plugin의 publicUrl은 무시합니다.
  • --url <url>: 페이로드에 사용되는 Gateway URL을 재정의합니다.
  • --public-url <url>: 페이로드에 사용되는 공개 URL을 재정의합니다.
  • --token <token>: 부트스트랩 흐름이 인증에 사용하는 Gateway 토큰을 재정의합니다.
  • --password <password>: 부트스트랩 흐름이 인증에 사용하는 Gateway 비밀번호를 재정의합니다.
  • --setup-code-only: 설정 코드만 출력합니다.
  • --no-ascii: ASCII QR 렌더링을 건너뜁니다.
  • --json: JSON을 출력합니다(setupCode, gatewayUrl, 선택적 gatewayUrls, auth, urlSource).

--token과 --password는 함께 사용할 수 없습니다.

설정 코드 내용

설정 코드에는 공유 Gateway 토큰/비밀번호가 아니라 불투명한 단기 bootstrapToken이 포함됩니다. 내장 부트스트랩 흐름은 다음을 발급합니다.

  • scopes: []가 지정된 기본 node 토큰
  • operator.approvals, operator.read, operator.talk.secrets, operator.write로 제한된 범위 한정 operator 인계 토큰

페어링 변경 범위와 operator.admin에는 여전히 별도로 승인된 운영자 페어링 또는 토큰 흐름이 필요합니다.

Gateway URL 확인

Tailscale/공개 ws:// Gateway URL에서는 모바일 페어링이 안전하게 실패하도록 차단됩니다. 이 경우 Tailscale Serve/Funnel 또는 wss:// Gateway URL을 사용하세요. 비공개 LAN 주소와 .local Bonjour 호스트는 일반 ws:// 연결로 계속 지원됩니다.

선택한 Gateway URL이 gateway.bind=lan에서 제공되는 경우 OpenClaw는 영구 tailscale serve status --json 경로도 확인합니다. 활성 Gateway의 루프백 포트를 프록시하는 모든 HTTPS Serve 루트가 대체 경로로 포함됩니다. QR 명령은 lan에만 이 대체 경로를 추가하며, custom과 tailnet은 명시적으로 공지된 경로를 유지합니다. 현재 iOS 클라이언트는 공지된 경로를 순서대로 탐색하고 처음 연결 가능한 경로를 저장합니다. 이전 클라이언트를 위한 레거시 url 필드는 변경되지 않습니다.

--remote를 사용하는 경우 gateway.remote.url 또는 gateway.tailscale.mode=serve|funnel 중 하나가 필요합니다.

인증 확인(--remote 미사용)

CLI 인증 재정의가 전달되지 않으면 로컬 Gateway 인증 SecretRef는 다음과 같이 확인됩니다.

조건 확인 결과
gateway.auth.mode="token"이거나, 우선 적용되는 비밀번호 소스가 없는 추론 모드 gateway.auth.token
gateway.auth.mode="password"이거나, 인증/환경에서 우선 적용되는 토큰이 없는 추론 모드 gateway.auth.password
gateway.auth.token과 gateway.auth.password가 모두 구성되어 있고(SecretRef 포함) gateway.auth.mode가 설정되지 않은 경우 실패하며 gateway.auth.mode를 명시적으로 설정해야 함

인증 확인(--remote)

실제로 활성화된 원격 자격 증명이 SecretRef로 구성되어 있고 --token과 --password가 모두 전달되지 않은 경우, 명령은 활성 Gateway 스냅샷에서 이를 확인합니다. Gateway를 사용할 수 없으면 명령이 즉시 실패합니다.

관련 항목

Was this useful?
On this page

On this page