OpenClaw Pairing List: Manage Paired Clients and Access Tokens

Your OpenClaw gateway is only as secure as the clients you've paired with it. A laptop you sold, a phone you wiped, a VM you deleted — if you paired them and never revoked the token, they still technically have access. The pairing list is your audit tool. Run it monthly. Revoke anything unfamiliar. This takes 30 seconds and closes a real attack surface.

What Pairing Means in OpenClaw

Pairing is the process by which a client device establishes a trusted relationship with an OpenClaw gateway. During pairing, the gateway issues a long-lived token to the client. All subsequent API calls from that client use the token for authentication.

Pairing is separate from the gateway's master token (set in gateway.yaml). The master token is for administrative API access. Pairing tokens are for client devices — Claude Code instances, mobile apps, custom scripts — that need to interact with the agent.

The Pairing List Command

View all paired clients:

openclaw pairing list

Example output:

Paired Clients (3)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ID          NAME              LAST SEEN        STATUS
  ──────────  ────────────────  ───────────────  ──────
  cl_a3f2c18  MacBook Pro       2m ago           active
  cl_b7d4e91  iPhone 15 Pro     14h ago          active
  cl_c2a8f04  Dev VM            47d ago          stale
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For more detail on a specific client:

openclaw pairing list --client cl_c2a8f04

Client: Dev VM (cl_c2a8f04)
  Status:       stale (47 days since last connection)
  Token:        cl_c2a8f04_••••••••••••••••
  Paired:       2024-12-17T11:42:09Z
  Last seen:    2025-01-16T08:33:21Z
  IP (last):    192.168.1.105
  Requests:     847 total

Pair a New Client

Pairing a new client requires generating a time-limited pairing code on the gateway, then entering it on the client device.

On the gateway:

openclaw pairing generate

Output:

Pairing Code: OCL-7F3A-K9PM
Expires in:   5 minutes
Gateway URL:  https://your-gateway.example.com

On the client device (within 5 minutes):

openclaw pair https://your-gateway.example.com OCL-7F3A-K9PM --name "My Laptop"

After successful pairing, the new client appears in openclaw pairing list immediately.

Revoking Client Access

Revocation is immediate — the token is invalidated the moment the command completes:

openclaw pairing revoke cl_c2a8f04

Output:

Revoked: Dev VM (cl_c2a8f04)
Token invalidated. The client cannot reconnect until re-paired.

The gateway does not need to restart. The revoked client receives an authentication error on its next API call and must re-pair to regain access.

To revoke all stale clients at once (not seen in 30+ days):

openclaw pairing revoke --stale

This is the cleanest way to do a periodic security audit — run it monthly, confirm the list of stale clients in the prompt, and revoke them all in one step.

Renaming Clients

If a client was paired with a generic name, rename it:

openclaw pairing rename cl_b7d4e91 "iPhone 15 Pro"

Names are purely for display — they don't affect authentication. But they make monthly audits much faster. A pairing list with named clients takes 10 seconds to audit. An unnamed list requires cross-referencing IP addresses and timestamps to identify each entry.

Security Best Practices

• Audit monthly — run openclaw pairing list once a month and revoke anything stale or unrecognized
• Name every client — use descriptive names at pairing time; rename immediately if you forgot
• Revoke before decommissioning devices — when you sell, wipe, or retire a device, revoke its pairing first
• Use short code TTL for high-security setups — reduce pairing.code_ttl in gateway.yaml from 5 minutes to 2 minutes in sensitive environments
• Revoke after suspected compromise — if you suspect unauthorized access, revoke all tokens with openclaw pairing revoke --all and re-pair legitimate devices

Common Mistakes

• Never auditing the pairing list — tokens don't expire; without regular audits, stale clients accumulate indefinitely
• Pairing without naming — generic IDs make auditing hard; always use --name when pairing
• Confusing pairing tokens with the master gateway token — these are different credentials for different purposes
• Not revoking before discarding a device — the device's token remains valid even after a factory reset if not explicitly revoked

Frequently Asked Questions

What does openclaw pairing list show?

The pairing list shows all clients currently paired with your OpenClaw gateway: client name, pairing token (masked), last seen timestamp, IP address, and pairing status. Use it to audit which devices have access and identify stale or unauthorized pairings.

How do I revoke a paired client in OpenClaw?

Run: openclaw pairing revoke [client-id]. Find the client ID from the pairing list output. After revoking, the client's token becomes invalid and it cannot reconnect until re-paired. The gateway does not need to restart — revocation takes effect immediately.

How do I pair a new client with my OpenClaw gateway?

Generate a pairing code: openclaw pairing generate. This creates a time-limited code (default 5 minutes) that the client uses to pair. On the client device, run: openclaw pair [gateway-url] [code]. Once paired, the client appears in openclaw pairing list.

Can I rename a paired client in OpenClaw?

Yes. Run: openclaw pairing rename [client-id] [new-name]. Client names are display-only labels stored locally on the gateway. They don't affect authentication — the pairing token is the actual credential. Rename clients to make the pairing list easier to audit.

How long do OpenClaw pairing tokens last?

Active pairing tokens do not expire by default. Once paired, a client stays paired until you manually revoke it with openclaw pairing revoke. The initial pairing code (used during the pairing ceremony) expires after 5 minutes by default — this is configurable in gateway.yaml under pairing.code_ttl.

How many clients can I pair with one OpenClaw gateway?

There is no hard limit in the software. Practical limits depend on your hardware and how many concurrent connections the gateway handles. Most users pair 1-5 clients. The pairing list is the authoritative source — audit it regularly and revoke clients you no longer use.