Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw devices
디바이스 페어링 요청과 디바이스 범위 토큰을 관리합니다.
명령
openclaw devices list
보류 중인 페어링 요청과 페어링된 디바이스를 나열합니다.
openclaw devices remove <deviceId>
페어링된 디바이스 항목 하나를 제거합니다.
페어링된 디바이스 토큰으로 인증된 경우, 관리자가 아닌 호출자는
자신의 디바이스 항목만 제거할 수 있습니다. 다른 디바이스를
제거하려면 operator.admin이 필요합니다.
openclaw devices clear --yes [--pending]
페어링된 디바이스를 일괄로 지웁니다.
openclaw devices approve [requestId] [--latest]
정확한 requestId로 보류 중인 디바이스 페어링 요청을 승인합니다. requestId가
생략되었거나 --latest가 전달되면, OpenClaw는 선택된 보류 중인 요청만
출력하고 종료합니다. 세부 정보를 확인한 뒤 정확한 요청 ID로 승인을
다시 실행하세요.
디바이스가 변경된 인증 세부 정보(역할, 스코프 또는 공개 키)로 페어링을 다시 시도하면, OpenClaw는 이전 보류 항목을 대체하고 새
requestId를 발급합니다. 현재 ID를 사용하려면 승인 직전에 openclaw devices list를 실행하세요.openclaw devices list의
Requested 및 Approved 열을 검토하거나 openclaw devices approve --latest를
사용하세요.
Gateway가 gateway.nodes.pairing.autoApproveCidrs로 명시적으로 구성된 경우,
일치하는 클라이언트 IP에서 오는 최초 role: node 요청은 이 목록에 나타나기
전에 승인될 수 있습니다. 이 정책은 기본적으로 비활성화되어 있으며
운영자/브라우저 클라이언트나 업그레이드 요청에는 절대 적용되지 않습니다.
openclaw devices reject <requestId>
보류 중인 디바이스 페어링 요청을 거부합니다.
openclaw devices rotate --device <id> --role <role> [--scope <scope...>]
특정 역할의 디바이스 토큰을 교체합니다(선택적으로 스코프 업데이트).
대상 역할은 해당 디바이스의 승인된 페어링 계약에 이미 존재해야 합니다.
교체로 승인되지 않은 새 역할을 만들 수는 없습니다.
--scope를 생략하면, 저장된 교체 토큰으로 나중에 다시 연결할 때 해당
토큰의 캐시된 승인 스코프를 재사용합니다. 명시적인 --scope 값을 전달하면,
해당 값이 향후 캐시 토큰 재연결에 사용할 저장된 스코프 집합이 됩니다.
관리자가 아닌 페어링된 디바이스 호출자는 자신의 디바이스 토큰만
교체할 수 있습니다. 대상 토큰 스코프 집합은 호출자 세션 자신의 운영자
스코프 안에 있어야 합니다. 교체로 호출자가 이미 가진 것보다 더 넓은
운영자 토큰을 만들거나 보존할 수는 없습니다.
openclaw devices revoke --device <id> --role <role>
특정 역할의 디바이스 토큰을 폐기합니다.
관리자가 아닌 페어링된 디바이스 호출자는 자신의 디바이스 토큰만
폐기할 수 있습니다. 다른 디바이스의 토큰을 폐기하려면 operator.admin이
필요합니다. 대상 토큰 스코프 집합도 호출자 세션 자신의 운영자 스코프
안에 맞아야 합니다. 페어링 전용 호출자는 관리자/쓰기 운영자 토큰을
폐기할 수 없습니다.
공통 옵션
--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로 계속 실패할 때 사용하세요.
- 현재 게이트웨이 토큰 소스를 확인합니다.
- 페어링된 디바이스를 나열하고 영향을 받은 디바이스 ID를 식별합니다.
- 영향을 받은 디바이스의 운영자 토큰을 교체합니다.
- 교체만으로 충분하지 않으면 오래된 페어링을 제거하고 다시 승인합니다.
- 현재 공유 토큰/비밀번호로 클라이언트 연결을 다시 시도합니다.
- 일반적인 재연결 인증 우선순위는 명시적인 공유 토큰/비밀번호가 먼저이고, 그다음 명시적인
deviceToken, 저장된 디바이스 토큰, 부트스트랩 토큰 순입니다. - 신뢰할 수 있는
AUTH_TOKEN_MISMATCH복구는 하나의 제한된 재시도를 위해 공유 토큰과 저장된 디바이스 토큰을 함께 임시로 보낼 수 있습니다. AUTH_SCOPE_MISMATCH는 디바이스 토큰이 인식되었지만 요청된 스코프 집합을 포함하지 않는다는 뜻입니다. 공유 Gateway 인증을 변경하기 전에 페어링/스코프 승인 계약을 수정하세요.