Devices

기준일: 2026-07-26
공식 기준: Devices

Devices 문서는 OpenClaw 공식 문서(cli/devices)를 한국어로 정리한 가이드입니다. CLI reference for openclaw devices (device pairing + token rotation/revocation) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

CLI reference for openclaw devices (device pairing + token rotation/revocation)

한국어 가이드 범위: cli/devices 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Common options
• 명령
• 참고
• Token drift recovery checklist
• Paperclip / openclaw_gateway first-run approval
• 관련 문서

상세 내용

openclaw devices

Manage device pairing requests and device-scoped tokens.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Common options

When you set --url, the CLI does not fall back to config or environment credentials. Pass --token or --password explicitly, or the command errors.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• --url <url>: Gateway WebSocket URL (defaults to gateway.remote.url when configured)
• --token <token>: Gateway token (if required)
• --password <password>: Gateway password (password auth)
• --timeout <ms>: RPC timeout
• --json: JSON output (recommended for scripting)

명령

이 섹션의 세부 항목은 공식 문서 명령를 참고하세요.

openclaw devices list

List pending pairing requests and paired devices.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw devices list
openclaw devices list --json

openclaw devices approve [requestId] [--latest]

Approve a pending pairing request by exact requestId. Omitting requestId, or passing --latest, only previews the newest pending request and exits (code 1); rerun with the exact request ID to approve.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• If the device is already paired and requests broader scopes or role, OpenClaw keeps the existing approval and creates a new pending upgrade request. Compare Requested vs Approved in openclaw devices list, or preview with --latest, before approving.
• Approving a node role or other non-operator role requires operator.admin. operator.pairing is enough for operator-device approvals, but only when the requested operator scopes stay within the caller's own scopes. See Operator scopes.
• If gateway.nodes.pairing.autoApproveCidrs is configured, first-time role: node requests from matching client IPs can be auto-approved before they appear in this list. Disabled by default; never applies to operator/browser clients or upgrade requests.
• gateway.nodes.pairing.sshVerify (on by default) auto-approves first-time role: node requests when the gateway verifies the device key over SSH to the node host. Requests may therefore resolve to approved shortly after appearing. Set sshVerify: false to disable SSH verification; this is independent of autoApproveCidrs, so unset that too for manual-only pairing.

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

openclaw devices reject

openclaw devices reject <requestId>

openclaw devices remove

A caller authenticated with a paired device token can remove only its own device entry. Removing another device requires operator.admin.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

openclaw devices rename --device --name

Assign an operator label to a paired device. Labels are owner-side state: they survive pairing repairs and role re-approvals, and they do not change the stable deviceId.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• --name is required, trimmed, non-empty, and capped at 64 characters.
• Display surfaces (CLI list, Control UI inventory) prefer the operator label over the client-reported display name.
• A non-admin paired-device caller can rename only its own device. Renaming another device requires operator.admin.

openclaw devices rename --device <deviceId> --name "Kitchen Mac"
openclaw devices rename --device <deviceId> --name "Kitchen Mac" --json

openclaw devices clear --yes [--pending]

Clear paired devices in bulk. Gated by --yes.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json

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

Rotate a device token for a role, optionally updating its scopes.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• The target role must already exist in that device's approved pairing contract; rotation cannot mint a new unapproved role.
• Omitting --scope reuses the stored token's cached approved scopes on later reconnects. Passing explicit --scope values replaces the stored scope set for future cached-token reconnects.
• A non-admin paired-device caller can rotate only its own device token, and the target scope set must stay within the caller's own operator scopes; rotation cannot mint or preserve a broader token than the caller already has.

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

openclaw devices revoke --device --role

A non-admin paired-device caller can revoke only its own device token. Revoking another device's token requires operator.admin. The target scope set must also fit within the caller's own operator scopes; pairing-only callers cannot revoke admin/write operator tokens.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

참고

주요 항목:

• These commands require operator.pairing (or operator.admin) scope. Non-operator device roles always require operator.admin; see Operator scopes.
• Token rotation and revocation stay inside the device's approved pairing role set and scope baseline. A stray cached token entry does not grant a token-management target.
• For paired-device token sessions, cross-device management (remove, rename, rotate, revoke) is self-only unless the caller has operator.admin.
• Token rotation returns a new token (sensitive) — treat it like a secret.
• If pairing scope is unavailable on local loopback and no explicit --url is passed, list/approve can fall back to local pairing state.

Token drift recovery checklist

Use this when Control UI or other clients keep failing with AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH, or AUTH_SCOPE_MISMATCH.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Normal reconnect auth precedence: explicit shared token/password first, then explicit deviceToken, then stored device token, then bootstrap token.
• Trusted AUTH_TOKEN_MISMATCH recovery can temporarily send both the shared token and the stored device token together for one bounded retry.
• AUTH_SCOPE_MISMATCH means the device token was recognized but does not carry the requested scope set; fix the pairing/scope approval contract before changing shared gateway auth.
• Dashboard auth troubleshooting
• Gateway troubleshooting

openclaw config get gateway.auth.token

openclaw devices list

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

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

Paperclip / openclaw_gateway first-run approval

Paperclip agents connecting through the openclaw_gateway adapter go through the same first-run device pairing approval as any other new client. If Paperclip reports openclaw_gateway_pairing_required, approve the pending device and retry.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw devices approve --latest

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

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

관련 문서

주요 항목:

• CLI reference
• Nodes

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/cli/devices
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw devices list
openclaw devices list --json

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

openclaw devices reject <requestId>

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

openclaw devices rename --device <deviceId> --name "Kitchen Mac"
openclaw devices rename --device <deviceId> --name "Kitchen Mac" --json

openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json

관련 링크

• 공식 원문: cli/devices
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.