OpenClaw devices approve: Authorize New Devices the Right Way

Every device that connects to your OpenClaw gateway starts in a holding state. It can see the gateway. It cannot talk to your agents. That gap is intentional — it gives you a moment to verify the device before it gets access to your entire agent system. The openclaw devices approve command is how you close that gap deliberately, not accidentally.

How Device Approval Works

When a new device connects to the gateway — a developer's laptop, a production server, a mobile client — it sends a registration request containing a device fingerprint. The gateway stores this fingerprint and marks the device as pending. Messages from pending devices are queued, not processed.

This design protects you from two scenarios. First, it prevents devices that connect due to misconfigured or stolen gateway credentials from immediately triggering agent actions. Second, it gives you an audit trail — you can see exactly which devices attempted to connect before you decided to approve them.

As of early 2025, OpenClaw's device approval system stores state in the gateway's local database. This means approvals survive gateway restarts automatically. You don't need to re-approve devices every time the gateway restarts — unless you've set an explicit TTL.

Finding Pending Devices

You need the device ID before you can approve it. Get the full list of pending devices:

openclaw pairing list --status pending

This returns a table showing device ID, connection time, last seen timestamp, and any metadata the device sent during registration (hostname, OS, client version). Use this information to verify the device is one you expect before approving.

Sound familiar? This is the same command you'd use after running openclaw channels add to verify channel status. The pairing list is your single view of everything waiting for action in your gateway.

If the list is empty and you're expecting a pending device, it either never connected or connected to the wrong gateway endpoint. Check the device's logs for the gateway URL it used — a single character typo in the URL means the connection went nowhere.

Running devices approve

With the device ID in hand, approve it:

openclaw devices approve --id abc123def

The gateway immediately moves the device from pending to approved. Any queued messages from that device are processed in order. The device doesn't need to reconnect — the approval takes effect for the current session.

Approving Multiple Devices

Pass multiple IDs in one command:

openclaw devices approve --id abc123 def456 ghi789

This approves all three atomically. If one ID doesn't exist, the command reports an error for that ID but still processes the others. Check the output carefully when approving in bulk.

Setting an Approval Expiry

For temporary access — a contractor's device, a staging runner — set a TTL at approval time:

openclaw devices approve --id abc123def --ttl 72h

After 72 hours, the device returns to pending. It can still connect but cannot interact with agents until re-approved. This is the correct pattern for any device you don't own permanently.

Revoking Approval

Approved the wrong device? Or need to cut off a device that's behaving unexpectedly? Revoke it:

openclaw devices revoke --id abc123def

This immediately terminates the device's session and removes its authorization. If the device tries to reconnect, it returns to pending. The revocation is logged with a timestamp in the gateway audit log — useful for incident response if you need to show when access was removed.

Here's where most people stop. They revoke the device but don't check whether it reconnected. A device with valid gateway credentials can always attempt to reconnect. After revoking, run:

openclaw pairing list --status pending

If the revoked device reappears, it's still trying to connect. Block it at the network level or rotate your gateway credentials to prevent re-connection attempts.

Security Considerations for Device Approval

Device approval is a meaningful security control — but only if you treat it as one. Here's what that looks like in practice.

• Review device metadata before approving — The hostname, OS version, and client version a device reports during registration can help you identify unexpected devices. A device claiming to be a Linux server when you're approving a macOS developer laptop is worth a second look.
• Set TTLs on non-permanent devices — Contractor laptops, temporary CI runners, and staging environments should never have indefinite approval. Use --ttl every time for these categories.
• Audit the approval log regularly — Run openclaw audit --type device_approval to see a history of all approvals and revocations. Unexplained approvals are a red flag.
• Disable auto-approval in gateway.yaml — If auto_approve_devices: true is set, every device that connects is instantly approved with no human review. This is off by default — confirm it stays off in production.
• Pair device approval with network controls — Approval controls which devices can interact with agents. Network controls determine which devices can even reach the gateway. Both layers together are more effective than either alone.

Frequently Asked Questions

What does openclaw devices approve do?

The command grants a pending device permission to interact with the OpenClaw gateway and send messages to agents. Until approved, the device can connect but is blocked from agent access. Approval persists across gateway restarts by default.

How do I find the device ID to approve?

Run openclaw pairing list --status pending. Each pending device shows a device ID — a short alphanumeric code generated at first connection. Pass that ID to openclaw devices approve --id [device-id].

Can I approve multiple devices at once?

Yes. Pass multiple device IDs separated by spaces after --id. Alternatively, use --all to approve every pending device at once — but this is not recommended in production environments where unknown devices may be in the pending queue.

What happens if I approve the wrong device?

Revoke it immediately with openclaw devices revoke --id [device-id]. This disconnects the device and removes its authorization. It returns to pending if it tries to reconnect, requiring explicit re-approval before it can access your agents again.

Does device approval expire?

By default, approvals do not expire. Set an expiry at approval time using --ttl 72h or configure device_approval_ttl globally in gateway.yaml. This is the correct approach for temporary contractor access or short-lived test devices.

Why is my device not showing as pending after connecting?

The gateway may have auto-approval enabled. Check gateway.yaml for auto_approve_devices: true — if set, devices skip pending automatically. Also verify the device is connecting to the correct gateway URL; a wrong endpoint means the connection never reaches your gateway.