OpenClaw Gateway Pairing Required Error: Here's Why It Happens

You set up your OpenClaw gateway, deployed your agent, and hit a wall: "Gateway pairing required." The agent refuses to connect. Nothing in the logs explains why it's suddenly broken after working fine. Here's the complete picture of what's happening — and the exact commands to resolve it immediately.

What the Pairing Required Error Actually Means

OpenClaw's gateway requires every connecting device or agent to go through an explicit authorization step before establishing a persistent connection. This is intentional security design — the gateway won't accept connections from unknown sources.

The pairing required error fires when:

• A new device is connecting to the gateway for the first time
• A previously approved device's identifier has changed (common in containers)
• The gateway's pairing database was reset or the data directory was deleted
• You're running a second agent instance that the gateway hasn't seen before

The device attempting to connect generates a pairing request that sits in a pending queue on the gateway. Nothing happens automatically — an administrator has to approve it.

The Fix: Two Commands

On the machine running the gateway, run:

openclaw devices approve

This shows the pending pairing requests with device identifiers and timestamps. Select the request from the device you're trying to connect and confirm approval.

If you want to see the current state before approving:

openclaw pairing list

This shows all approved and pending pairings. Pending requests show with a status of "awaiting approval." You can approve directly from this view as well.

Once you approve, the connecting device automatically retries its connection and establishes the pairing. No restart required on either side — the connection happens within seconds of approval.

Why Gateway Pairing Exists

Understanding the security model prevents future confusion.

The OpenClaw gateway is the central routing point for all agent communication. Every message from every channel flows through it. An unauthorized agent connecting to your gateway could intercept messages, impersonate approved agents, or inject malicious responses into your channels.

The pairing system is the first line of defense. Only explicitly approved devices can connect. This matters especially when your gateway is exposed to the public internet — which is required for channels like Telegram, WhatsApp, and Slack to reach your agents.

Here's what we've seen consistently: builders who disable pairing on internet-facing gateways end up with unauthorized connections within days. The pairing friction is small. The alternative is a gateway that accepts connections from anywhere.

Managing Pairings Long-Term

As your deployment grows, pairing management becomes part of your regular maintenance.

View all current pairings:

openclaw pairing list

Revoke a specific device:

openclaw devices revoke [device-id]

Block a device from requesting future pairings:

openclaw devices block [device-id]

Clean up stale pairings from decommissioned devices regularly. A pairing list with 50 entries from devices that no longer exist is both a security risk and a diagnostic headache when something breaks.

Docker and Container-Specific Issues

Docker setups are where the recurring pairing error appears most often. Here's why.

OpenClaw generates a unique device identifier on first run and stores it in the data directory (typically ~/.openclaw). When you restart a Docker container without persisting this directory, a new identifier is generated. The gateway sees it as a brand-new, unpaired device — even though it's "the same" agent from your perspective.

Fix it by persisting the data directory as a Docker volume:

docker run -v /host/path/openclaw-data:/root/.openclaw your-openclaw-image

Or in docker-compose:

services:
  openclaw:
    image: your-openclaw-image
    volumes:
      - openclaw-data:/root/.openclaw

volumes:
  openclaw-data:

With the data directory persisted, the device identifier survives container restarts. The gateway recognizes it on reconnect and doesn't require re-approval.

Common Mistakes With Pairing

Running approve on the wrong machine. The most common mistake. The approve command must run where the gateway is running — not on the device requesting the connection.

Not persisting the data directory in Docker. Every container restart generates a new device ID and triggers a new pairing request. The fix is a volume mount, not repeated approvals.

Approving without verifying the device ID. In shared environments, pending pairing requests might come from unexpected sources. Always verify the device identifier in the pending request matches what you expect before approving.

Clearing the gateway's data directory as a troubleshooting step. This resets all approved pairings and forces every connected device to re-pair. It looks like a clean slate but causes cascading reconnection failures across all your agents simultaneously.

Frequently Asked Questions

What does 'gateway pairing required' mean in OpenClaw?

A device or agent is attempting to connect to your OpenClaw gateway but hasn't been authorized yet. The gateway requires explicit approval for every new connection. Run openclaw devices approve to see the pending request and approve it.

How do I approve a device pairing request in OpenClaw?

Run openclaw devices approve from the CLI on the machine running the gateway. This shows all pending requests with device identifiers. Select the request to approve and confirm. The device connection establishes automatically within seconds.

Why does the pairing required error keep coming back?

Recurring pairing errors usually mean the device identifier is changing between sessions — common with Docker containers that regenerate IDs on restart. Ensure the device's ~/.openclaw directory is persisted across restarts via a volume mount.

Can I disable gateway pairing requirements?

Yes. Set pairingRequired: false in your gateway.yaml. This removes the approval step. Only do this in secure, trusted network environments — disabling pairing on an internet-facing gateway creates a significant security risk.

How long does a gateway pairing last?

Gateway pairings persist indefinitely once approved — they don't expire on a schedule. A pairing is invalidated only when the gateway's pairing records are reset, the device's data directory is deleted, or you explicitly revoke it via openclaw devices revoke.

What happens if I reject a pairing request?

Rejected devices receive a 403 Forbidden response and cannot connect. The device can attempt pairing again, which generates a new pending request. You can deny and block a device entirely using openclaw devices block with the device identifier.