openclaw devices

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

명령어

openclaw devices list

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

openclaw devices list
openclaw devices list --json

openclaw devices remove <deviceId>

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

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를 생략하면 OpenClaw이 가장 최근의 대기 중인 요청을 자동으로 승인합니다.

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

특정 역할에 대한 디바이스 토큰을 로테이션합니다(선택적으로 범위 업데이트).

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

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

특정 역할에 대한 디바이스 토큰을 취소합니다.

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

공통 옵션

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

참고: --url을 설정하면 CLI는 설정이나 환경 자격 증명으로 폴백하지 않습니다. --token 또는 --password를 명시적으로 전달하세요. 명시적 자격 증명이 누락되면 오류가 발생합니다.

참고 사항

• 토큰 로테이션은 새 토큰(민감)을 반환합니다. 시크릿으로 취급하세요.
• 이 명령어들은 operator.pairing(또는 operator.admin) 범위가 필요합니다.
• devices clear는 의도적으로 --yes로 게이트됩니다.
• 로컬 루프백에서 페어링 범위를 사용할 수 없는 경우(명시적 --url이 전달되지 않은 경우), list/approve는 로컬 페어링 폴백을 사용할 수 있습니다.

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

Control UI나 다른 클라이언트에서 AUTH_TOKEN_MISMATCH 또는 AUTH_DEVICE_TOKEN_MISMATCH로 계속 실패할 때 사용하세요.

1. 현재 게이트웨이 토큰 소스 확인:

openclaw config get gateway.auth.token

2. 페어링된 디바이스를 나열하고 영향받는 디바이스 ID 확인:

openclaw devices list

3. 영향받는 디바이스의 operator 토큰 로테이션:

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

4. 로테이션으로 충분하지 않은 경우, 오래된 페어링을 제거하고 다시 승인:

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

5. 현재 공유 토큰/비밀번호로 클라이언트 연결 재시도.

관련 문서:

• Dashboard auth troubleshooting
• Gateway troubleshooting