CLI commands
기기
openclaw devices
디바이스 페어링 요청과 디바이스 범위 토큰을 관리합니다.
명령
openclaw devices list
보류 중인 페어링 요청과 페어링된 디바이스를 나열합니다.
openclaw devices listopenclaw devices list --json보류 중인 요청 출력은 디바이스가 이미 페어링된 경우 디바이스의 현재 승인된 액세스 옆에 요청된 액세스를 표시합니다. 이렇게 하면 페어링이 손실된 것처럼 보이는 대신 스코프/역할 업그레이드가 명확해집니다.
openclaw devices remove <deviceId>
페어링된 디바이스 항목 하나를 제거합니다.
페어링된 디바이스 토큰으로 인증된 경우, 관리자가 아닌 호출자는
자신의 디바이스 항목만 제거할 수 있습니다. 다른 디바이스를
제거하려면 operator.admin이 필요합니다.
openclaw devices remove <deviceId>openclaw devices remove <deviceId> --jsonopenclaw devices clear --yes [--pending]
페어링된 디바이스를 일괄로 지웁니다.
openclaw devices clear --yesopenclaw devices clear --yes --pendingopenclaw devices clear --yes --pending --jsonopenclaw 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 approveopenclaw devices approve <requestId>openclaw devices approve --latestopenclaw 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는 새 노드 디바이스 페어링에만 적용되는 선택형 Gateway 정책입니다. CLI 승인 권한은 변경하지 않습니다.- 토큰 교체와 폐기는 해당 디바이스의 승인된 페어링 역할 집합과 승인된 스코프 기준선 안에 머뭅니다. 잘못 남아 있는 캐시 토큰 항목은 토큰 관리 대상을 부여하지 않습니다.
- 페어링된 디바이스 토큰 세션의 경우, 디바이스 간 관리는 관리자 전용입니다.
호출자에게
operator.admin이 없는 한remove,rotate,revoke는 자신에게만 적용됩니다. - 토큰 변경도 호출자 스코프 안에 제한됩니다. 페어링 전용 세션은 현재
operator.admin또는operator.write를 포함하는 토큰을 교체하거나 폐기할 수 없습니다. devices clear는 의도적으로--yes로 보호됩니다.- local loopback에서 페어링 스코프를 사용할 수 없는 경우(그리고 명시적인
--url이 전달되지 않은 경우), list/approve는 로컬 페어링 대체 경로를 사용할 수 있습니다. devices approve는 토큰을 만들기 전에 명시적인 요청 ID가 필요합니다.requestId를 생략하거나--latest를 전달하면 최신 보류 요청을 미리 보기만 합니다.
토큰 드리프트 복구 체크리스트
Control UI 또는 다른 클라이언트가 AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH 또는 AUTH_SCOPE_MISMATCH로 계속 실패할 때 사용하세요.
- 현재 게이트웨이 토큰 소스를 확인합니다.
openclaw config get gateway.auth.token- 페어링된 디바이스를 나열하고 영향을 받은 디바이스 ID를 식별합니다.
openclaw devices list- 영향을 받은 디바이스의 운영자 토큰을 교체합니다.
openclaw devices rotate --device <deviceId> --role operator- 교체만으로 충분하지 않으면 오래된 페어링을 제거하고 다시 승인합니다.
openclaw devices remove <deviceId>openclaw devices listopenclaw devices approve <requestId>- 현재 공유 토큰/비밀번호로 클라이언트 연결을 다시 시도합니다.
참고:
- 일반적인 재연결 인증 우선순위는 명시적인 공유 토큰/비밀번호가 먼저이고, 그다음 명시적인
deviceToken, 저장된 디바이스 토큰, 부트스트랩 토큰 순입니다. - 신뢰할 수 있는
AUTH_TOKEN_MISMATCH복구는 하나의 제한된 재시도를 위해 공유 토큰과 저장된 디바이스 토큰을 함께 임시로 보낼 수 있습니다. AUTH_SCOPE_MISMATCH는 디바이스 토큰이 인식되었지만 요청된 스코프 집합을 포함하지 않는다는 뜻입니다. 공유 Gateway 인증을 변경하기 전에 페어링/스코프 승인 계약을 수정하세요.
관련 항목: