openclaw devices로 기기 페어링 및 토큰 관리하기

여러 기기를 관리하다 보면 페어링 요청을 승인하거나 기기별 토큰을 관리하는 일이 꽤 번거로울 때가 있죠. 특히 보안을 유지하면서도 각 기기의 권한을 세밀하게 조정해야 할 때는 더 그렇습니다. openclaw devices 명령어를 사용하면 이런 복잡한 과정을 터미널에서 깔끔하게 처리할 수 있어요.

`openclaw devices`

기기 페어링 요청과 기기 범위(device-scoped) 토큰을 관리합니다.

명령어 (Commands)

`openclaw devices list`

대기 중인 페어링 요청과 페어링된 기기 목록을 확인합니다.

openclaw devices list
openclaw devices list --json

대기 중인 요청 출력에는 요청된 role과 scope가 포함되어 있어, 승인하기 전에 내용을 꼼꼼히 검토할 수 있습니다.

`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로 승인을 다시 실행하세요.

참고: 기기가 인증 정보(role/scopes/public key)를 변경하여 페어링을 재시도하면, OpenClaw는 이전 대기 항목을 대체하고 새로운 requestId를 발급합니다. 승인 직전에 openclaw devices list를 실행해서 현재 ID를 확인하는 것이 좋습니다.

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...>]`

특정 role에 대한 기기 토큰을 교체합니다(선택적으로 scope 업데이트 가능). 대상 role은 해당 기기의 승인된 페어링 계약에 이미 존재해야 합니다. 교체(rotation)를 통해 승인되지 않은 새로운 role을 생성할 수는 없습니다.

--scope를 생략하면, 나중에 저장된 교체 토큰으로 다시 연결할 때 해당 토큰의 캐시된 승인 scope를 재사용합니다. 명시적으로 --scope 값을 전달하면, 해당 값들이 향후 캐시 토큰 재연결을 위해 저장된 scope 세트가 됩니다.

관리자가 아닌 페어링 기기 호출자는 자신의 기기 토큰만 교체할 수 있습니다. 또한, 명시적인 --scope 값은 호출자 세션의 operator scope 범위 내에 있어야 합니다. 교체 작업으로 호출자가 이미 가진 것보다 더 넓은 권한의 operator 토큰을 생성할 수는 없습니다.

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

새로운 토큰 페이로드를 JSON으로 반환합니다.

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

특정 role에 대한 기기 토큰을 취소합니다.

관리자가 아닌 페어링 기기 호출자는 자신의 기기 토큰만 취소할 수 있습니다. 다른 기기의 토큰을 취소하려면 operator.admin 권한이 필요합니다.

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

취소 결과를 JSON으로 반환합니다.

공통 옵션 (Common options)

--url <url>: Gateway WebSocket URL (설정된 경우 기본값은 gateway.remote.url입니다).
--token <token>: Gateway 토큰 (필요한 경우).
--password <password>: Gateway 비밀번호 (비밀번호 인증 시).
--timeout <ms>: RPC 타임아웃.
--json: JSON 출력 (스크립트 작업 시 권장).

참고: --url을 설정하면 CLI는 설정 파일이나 환경 변수의 인증 정보를 사용하지 않습니다. --token이나 --password를 명시적으로 전달하세요. 명시적인 인증 정보가 없으면 에러가 발생합니다.

참고 사항 (Notes)

토큰 교체(rotation)는 민감한 정보인 새 토큰을 반환합니다. 비밀번호처럼 안전하게 취급하세요.
이 명령어들을 실행하려면 operator.pairing (또는 operator.admin) scope가 필요합니다.
토큰 교체는 해당 기기에 대해 승인된 페어링 role 세트와 승인된 scope 기준점 내에서만 이루어집니다. 잘못된 캐시 토큰 항목이 있다고 해서 새로운 교체 대상 권한이 부여되지는 않습니다.
페어링된 기기 토큰 세션의 경우, 다른 기기를 관리하는 것은 관리자 전용입니다. 호출자에게 operator.admin 권한이 없다면 remove, rotate, revoke는 본인 기기에 대해서만 가능합니다.
devices clear는 의도치 않은 삭제를 방지하기 위해 --yes 옵션이 반드시 필요합니다.
로컬 루프백에서 페어링 scope를 사용할 수 없고 명시적인 --url이 전달되지 않은 경우, list/approve 명령어는 로컬 페어링 폴백(fallback)을 사용할 수 있습니다.
devices approve는 토큰을 생성하기 전에 명시적인 요청 ID가 필요합니다. requestId를 생략하거나 --latest를 전달하면 가장 최근의 대기 요청을 미리 보기만 합니다.

토큰 드리프트 복구 체크리스트 (Token drift recovery checklist)

Control UI나 다른 클라이언트에서 AUTH_TOKEN_MISMATCH 또는 AUTH_DEVICE_TOKEN_MISMATCH 에러가 계속 발생할 때 이 절차를 따르세요.

현재 Gateway 토큰 소스를 확인합니다.

openclaw config get gateway.auth.token

페어링된 기기 목록을 확인하고 문제가 발생한 기기 ID를 찾습니다.

openclaw devices list

해당 기기의 operator 토큰을 교체합니다.

openclaw devices rotate --device <deviceId> --role operator

토큰 교체로 해결되지 않으면, 오래된 페어링 정보를 제거하고 다시 승인합니다.

openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>

현재 공유된 토큰/비밀번호로 클라이언트 연결을 다시 시도합니다.

참고 사항:

일반적인 재연결 인증 우선순위는 명시적 공유 토큰/비밀번호가 첫 번째이며, 그다음은 명시적 deviceToken, 저장된 기기 토큰, 마지막으로 부트스트랩 토큰 순입니다.
신뢰할 수 있는 AUTH_TOKEN_MISMATCH 복구 시에는 한 번의 제한된 재시도를 위해 공유 토큰과 저장된 기기 토큰을 일시적으로 함께 보낼 수 있습니다.

다음 단계

도움이 필요하신가요? AI Setup Assistant에게 물어보세요!

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.