English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

CLI commands

기기

openclaw devices

디바이스 페어링 요청과 디바이스 범위 토큰을 관리합니다.

명령

openclaw devices list

대기 중인 페어링 요청과 페어링된 디바이스를 나열합니다.

openclaw devices list
openclaw devices list --json

대기 중인 요청 출력은 디바이스가 이미 페어링된 경우, 요청된 접근 권한을 디바이스의 현재 승인된 접근 권한 옆에 표시합니다. 이를 통해 페어링이 손실된 것처럼 보이지 않고 범위/역할 업그레이드가 명확해집니다.

openclaw devices remove <deviceId>

페어링된 디바이스 항목 하나를 제거합니다.

페어링된 디바이스 토큰으로 인증된 경우, 관리자가 아닌 호출자는 자신의 디바이스 항목만 제거할 수 있습니다. 다른 디바이스를 제거하려면 operator.admin이 필요합니다.

openclaw devices remove <deviceId>
openclaw devices remove <deviceId> --json

openclaw devices clear --yes [--pending]

페어링된 디바이스를 일괄 삭제합니다.

openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json

openclaw devices approve [requestId] [--latest]

정확한 requestId로 대기 중인 디바이스 페어링 요청을 승인합니다. requestId가 생략되었거나 --latest가 전달되면, OpenClaw는 선택된 대기 중 요청만 출력하고 종료합니다. 세부 정보를 확인한 뒤 정확한 요청 ID로 승인을 다시 실행하세요.

디바이스가 이미 페어링되어 있고 더 넓은 범위나 더 넓은 역할을 요청하는 경우, OpenClaw는 기존 승인을 유지하고 새 대기 중 업그레이드 요청을 생성합니다. openclaw devices list의 Requested 및 Approved 열을 검토하거나, 승인 전에 openclaw devices approve --latest를 사용하여 정확한 업그레이드를 미리 확인하세요.

Gateway가 gateway.nodes.pairing.autoApproveCidrs로 명시적으로 구성된 경우, 일치하는 클라이언트 IP에서 들어오는 최초 role: node 요청은 이 목록에 표시되기 전에 승인될 수 있습니다. 이 정책은 기본적으로 비활성화되어 있으며, 운영자/브라우저 클라이언트나 업그레이드 요청에는 절대 적용되지 않습니다.

openclaw devices approve
openclaw devices approve <requestId>
openclaw devices approve --latest

openclaw devices reject <requestId>

대기 중인 디바이스 페어링 요청을 거부합니다.

openclaw devices reject <requestId>

openclaw devices rotate --device <id> --role <role> [--scope <scope...>]

특정 역할의 디바이스 토큰을 교체합니다(선택적으로 범위 업데이트). 대상 역할은 해당 디바이스의 승인된 페어링 계약에 이미 존재해야 합니다. 교체로 승인되지 않은 새 역할을 발급할 수 없습니다. --scope를 생략하면, 저장된 교체 토큰으로 나중에 다시 연결할 때 해당 토큰의 캐시된 승인 범위를 재사용합니다. 명시적인 --scope 값을 전달하면, 해당 값들이 향후 캐시 토큰 재연결을 위한 저장된 범위 세트가 됩니다. 관리자가 아닌 페어링된 디바이스 호출자는 자신의 디바이스 토큰만 교체할 수 있습니다. 대상 토큰 범위 세트는 호출자 세션 자체의 운영자 범위 안에 머물러야 합니다. 교체로 호출자가 이미 가진 것보다 더 넓은 운영자 토큰을 발급하거나 보존할 수 없습니다.

openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write

교체 메타데이터를 JSON으로 반환합니다. 호출자가 해당 디바이스 토큰으로 인증된 상태에서 자신의 토큰을 교체하는 경우, 클라이언트가 다시 연결하기 전에 저장할 수 있도록 응답에 대체 토큰도 포함됩니다. 공유/관리자 교체는 전달자 토큰을 다시 출력하지 않습니다.

openclaw devices revoke --device <id> --role <role>

특정 역할의 디바이스 토큰을 폐기합니다.

관리자가 아닌 페어링된 디바이스 호출자는 자신의 디바이스 토큰만 폐기할 수 있습니다. 다른 디바이스의 토큰을 폐기하려면 operator.admin이 필요합니다. 대상 토큰 범위 세트도 호출자 세션 자체의 운영자 범위 안에 맞아야 합니다. 페어링 전용 호출자는 관리자/쓰기 운영자 토큰을 폐기할 수 없습니다.

openclaw devices revoke --device <deviceId> --role node

폐기 결과를 JSON으로 반환합니다.

공통 옵션

  • --url <url>: Gateway WebSocket URL(구성된 경우 기본값은 gateway.remote.url).
  • --token <token>: Gateway 토큰(필요한 경우).
  • --password <password>: Gateway 비밀번호(비밀번호 인증).
  • --timeout <ms>: RPC 타임아웃.
  • --json: JSON 출력(스크립팅에 권장).

참고

  • 토큰 교체는 새 토큰(민감 정보)을 반환합니다. 비밀처럼 취급하세요.
  • 이 명령에는 operator.pairing(또는 operator.admin) 범위가 필요합니다. 일부 승인은 대상 디바이스가 발급하거나 상속할 운영자 범위를 호출자가 보유해야 합니다. 운영자 범위를 참조하세요.
  • gateway.nodes.pairing.autoApproveCidrs는 새 Node 디바이스 페어링에만 적용되는 옵트인 Gateway 정책입니다. CLI 승인 권한을 변경하지 않습니다.
  • 토큰 교체와 폐기는 해당 디바이스의 승인된 페어링 역할 세트와 승인된 범위 기준선 안에 머뭅니다. 잘못 남은 캐시 토큰 항목은 토큰 관리 대상을 부여하지 않습니다.
  • 페어링된 디바이스 토큰 세션에서 디바이스 간 관리는 관리자 전용입니다. 호출자에게 operator.admin이 없으면 remove, rotate, revoke는 자기 자신에게만 적용됩니다.
  • 토큰 변경도 호출자 범위 안에 제한됩니다. 페어링 전용 세션은 현재 operator.admin 또는 operator.write를 가진 토큰을 교체하거나 폐기할 수 없습니다.
  • devices clear는 의도적으로 --yes로 보호됩니다.
  • local loopback에서 페어링 범위를 사용할 수 없는 경우(그리고 명시적 --url이 전달되지 않은 경우), list/approve는 로컬 페어링 대체 경로를 사용할 수 있습니다.
  • devices approve는 토큰을 발급하기 전에 명시적인 요청 ID가 필요합니다. requestId를 생략하거나 --latest를 전달하면 가장 최근의 대기 중 요청만 미리 보여줍니다.

토큰 드리프트 복구 체크리스트

제어 UI 또는 다른 클라이언트가 AUTH_TOKEN_MISMATCH 또는 AUTH_DEVICE_TOKEN_MISMATCH로 계속 실패할 때 사용하세요.

  1. 현재 Gateway 토큰 소스를 확인합니다.
openclaw config get gateway.auth.token
  1. 페어링된 디바이스를 나열하고 영향을 받는 디바이스 ID를 식별합니다.
openclaw devices list
  1. 영향을 받는 디바이스의 운영자 토큰을 교체합니다.
openclaw devices rotate --device <deviceId> --role operator
  1. 교체로 충분하지 않으면 오래된 페어링을 제거하고 다시 승인합니다.
openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>
  1. 현재 공유 토큰/비밀번호로 클라이언트 연결을 다시 시도합니다.

참고:

  • 일반 재연결 인증 우선순위는 명시적 공유 토큰/비밀번호가 먼저이고, 그다음 명시적 deviceToken, 저장된 디바이스 토큰, 부트스트랩 토큰 순입니다.
  • 신뢰할 수 있는 AUTH_TOKEN_MISMATCH 복구는 한 번의 제한된 재시도 동안 공유 토큰과 저장된 디바이스 토큰을 함께 임시로 보낼 수 있습니다.

관련:

관련