OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

기기

openclaw devices

기기 페어링 요청과 기기 범위 토큰을 관리합니다.

공통 옵션

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

명령

openclaw devices list

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

bash
openclaw devices listopenclaw devices list --json

이미 페어링된 기기에 대기 중인 요청이 있으면 출력에서 요청된 액세스를 기기의 현재 승인된 액세스 옆에 표시하므로, 페어링이 손실된 것처럼 보이지 않고 범위/역할 업그레이드를 확인할 수 있습니다.

페어링된 기기의 표시 이름에는 다음 우선순위가 적용됩니다. 운영자 레이블(devices rename의 operatorLabel), 클라이언트 displayName, clientId, deviceId 순입니다.

openclaw devices approve [requestId] [--latest]

정확한 requestId로 대기 중인 페어링 요청을 승인합니다. requestId를 생략하거나 --latest를 전달하면 가장 최근의 대기 중 요청을 미리 보기만 하고 종료합니다(코드 1). 승인하려면 정확한 요청 ID로 다시 실행하세요.

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

승인 동작:

  • 기기가 이미 페어링되어 있고 더 넓은 범위나 역할을 요청하면 OpenClaw는 기존 승인을 유지하고 새로운 대기 중 업그레이드 요청을 생성합니다. 승인하기 전에 openclaw devices list에서 Requested와 Approved를 비교하거나 --latest로 미리 보세요.
  • node 역할 또는 기타 비운영자 역할을 승인하려면 operator.admin이 필요합니다. 운영자 기기 승인에는 operator.pairing이면 충분하지만, 요청된 운영자 범위가 호출자 자신의 범위 내에 있는 경우에만 가능합니다. 운영자 범위를 참조하세요.
  • gateway.nodes.pairing.autoApproveCidrs가 구성되어 있으면 일치하는 클라이언트 IP에서 처음 요청된 role: node는 이 목록에 나타나기 전에 자동 승인될 수 있습니다. 기본적으로 비활성화되어 있으며 운영자/브라우저 클라이언트 또는 업그레이드 요청에는 절대 적용되지 않습니다.
  • gateway.nodes.pairing.sshVerify(기본적으로 활성화)는 Gateway가 SSH를 통해 Node 호스트의 기기 키를 확인하면 처음 요청된 role: node를 자동 승인합니다. 따라서 요청이 나타난 직후 승인됨 상태로 전환될 수 있습니다. SSH 확인을 비활성화하려면 sshVerify: false를 설정하세요. 이는 autoApproveCidrs와 독립적이므로 수동 전용 페어링을 사용하려면 해당 설정도 해제하세요.

openclaw devices reject <requestId>

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

bash
openclaw devices reject <requestId>

openclaw devices remove <deviceId>

페어링된 기기 항목 하나를 제거합니다.

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

페어링된 기기 토큰으로 인증한 호출자는 자신의 기기 항목만 제거할 수 있습니다. 다른 기기를 제거하려면 operator.admin이 필요합니다.

openclaw devices rename --device <id> --name <label>

페어링된 기기에 운영자 레이블을 지정합니다. 레이블은 소유자 측 상태입니다. 페어링 복구 및 역할 재승인 후에도 유지되며 안정적인 deviceId를 변경하지 않습니다.

bash
openclaw devices rename --device <deviceId> --name "Kitchen Mac"openclaw devices rename --device <deviceId> --name "Kitchen Mac" --json
  • --name은 필수이며, 앞뒤 공백을 제거한 후 비어 있지 않아야 하고 최대 64자로 제한됩니다.
  • 표시 화면(CLI 목록, Control UI 인벤토리)은 클라이언트가 보고한 표시 이름보다 운영자 레이블을 우선합니다.
  • 관리자가 아닌 페어링된 기기 호출자는 자신의 기기 이름만 변경할 수 있습니다. 다른 기기의 이름을 변경하려면 operator.admin이 필요합니다.

openclaw devices clear --yes [--pending]

페어링된 기기를 일괄 삭제합니다. --yes가 있어야 실행됩니다.

bash
openclaw devices clear --yesopenclaw devices clear --yes --pendingopenclaw devices clear --yes --pending --json

--pending은 대기 중인 모든 페어링 요청도 거부합니다.

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

역할에 대한 기기 토큰을 교체하고, 선택적으로 해당 범위를 업데이트합니다.

bash
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
  • 대상 역할은 해당 기기의 승인된 페어링 계약에 이미 존재해야 합니다. 교체를 통해 승인되지 않은 새로운 역할을 발급할 수 없습니다.
  • --scope를 생략하면 이후 재연결 시 저장된 토큰에 캐시된 승인 범위를 재사용합니다. 명시적인 --scope 값을 전달하면 향후 캐시된 토큰으로 재연결할 때 사용할 저장된 범위 집합을 대체합니다.
  • 관리자가 아닌 페어링된 기기 호출자는 자신의 기기 토큰만 교체할 수 있으며, 대상 범위 집합은 호출자 자신의 운영자 범위 내에 있어야 합니다. 교체를 통해 호출자가 이미 보유한 것보다 더 넓은 토큰을 발급하거나 유지할 수 없습니다.

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

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

역할에 대한 기기 토큰을 폐기합니다.

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

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

참고

  • 이러한 명령에는 operator.pairing(또는 operator.admin) 범위가 필요합니다. 비운영자 기기 역할에는 항상 operator.admin이 필요합니다. 운영자 범위를 참조하세요.
  • 토큰 교체와 폐기는 기기의 승인된 페어링 역할 집합과 범위 기준선 내에서만 수행됩니다. 관련 없이 남은 캐시 토큰 항목은 토큰 관리 대상을 부여하지 않습니다.
  • 페어링된 기기 토큰 세션에서 기기 간 관리(remove, rename, rotate, revoke)는 호출자에게 operator.admin이 없는 한 자신의 기기로만 제한됩니다.
  • 토큰 교체는 새로운 토큰(민감 정보)을 반환합니다. 비밀 정보처럼 취급하세요.
  • local loopback에서 페어링 범위를 사용할 수 없고 명시적인 --url이 전달되지 않은 경우, list/approve는 로컬 페어링 상태를 대신 사용할 수 있습니다.

토큰 불일치 복구 체크리스트

Control UI 또는 기타 클라이언트가 AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH 또는 AUTH_SCOPE_MISMATCH 오류로 계속 실패할 때 사용하세요.

  1. 현재 Gateway 토큰 출처를 확인합니다.

    bash
    openclaw config get gateway.auth.token

  2. 페어링된 기기를 나열하고 영향을 받는 기기 ID를 식별합니다.

    bash
    openclaw devices list

  3. 영향을 받는 기기의 운영자 토큰을 교체합니다.

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

  4. 교체로 충분하지 않으면 오래된 페어링을 제거하고 다시 승인합니다.

    bash
    openclaw devices remove <deviceId>openclaw devices listopenclaw devices approve <requestId>

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

참고:

  • 일반적인 재연결 인증 우선순위: 명시적인 공유 토큰/비밀번호, 명시적인 deviceToken, 저장된 기기 토큰, 부트스트랩 토큰 순입니다.
  • 신뢰할 수 있는 AUTH_TOKEN_MISMATCH 복구에서는 제한된 한 번의 재시도를 위해 공유 토큰과 저장된 기기 토큰을 일시적으로 함께 전송할 수 있습니다.
  • AUTH_SCOPE_MISMATCH는 기기 토큰이 인식되었지만 요청된 범위 집합을 포함하지 않는다는 의미입니다. 공유 Gateway 인증을 변경하기 전에 페어링/범위 승인 계약을 수정하세요.

관련 문서:

Paperclip / openclaw_gateway 최초 실행 승인

openclaw_gateway 어댑터를 통해 연결하는 Paperclip 에이전트는 다른 모든 새 클라이언트와 동일한 최초 실행 기기 페어링 승인을 거칩니다. Paperclip에서 openclaw_gateway_pairing_required를 보고하면 대기 중인 기기를 승인하고 다시 시도하세요.

bash
openclaw devices approve --latest

미리 보기에는 정확한 openclaw devices approve <requestId> 명령이 출력됩니다. 세부 정보를 확인한 다음 요청 ID와 함께 해당 명령을 다시 실행하여 승인하세요. 원격 Gateway 또는 명시적인 자격 증명을 사용하는 경우 미리 보기 및 승인 시 동일한 옵션을 전달하세요.

bash
openclaw devices approve --latest --url <gateway-ws-url> --token <gateway-token>

다시 시작할 때마다 재승인하지 않으려면 매번 새로운 임시 기기 ID를 생성하도록 두는 대신 Paperclip에 영구 adapterConfig.devicePrivateKeyPem을 구성하세요.

json
{  "adapterConfig": {    "devicePrivateKeyPem": "<ed25519-private-key-pkcs8-pem>"  }}

승인이 계속 실패하면 먼저 openclaw devices list를 실행하여 대기 중인 요청이 있는지 확인하세요.

관련 문서

Was this useful?
On this page

On this page