Managing Node Access with Gateway-Owned Pairing

I’ve spent way too many hours manually managing keys and access lists across different devices. It’s frustrating when you just want a node to join your network without jumping through hoops or editing hidden config files on every single machine.

I prefer a setup where the central hub decides who is in and who is out. Gateway-owned pairing does exactly this by making the Gateway the source of truth for your nodes.

What You’ll Need

• A Gateway with an active WS endpoint.
• The openclaw CLI or the macOS app.
• A node configured with the node role.
• Access to the Gateway state directory (usually ~/.openclaw).

Quick Start

I find this workflow works best because it keeps the security logic on the Gateway while letting you use any UI as a frontend. Here is how to get a node paired in 5 minutes:

1. Request Pairing: Your node connects to the Gateway WS and calls node.pair.request.
2. View Requests: Check the list of devices waiting for access.

   openclaw nodes pending

3. Approve Access: Grant the request using the ID from the previous step.

   openclaw nodes approve <requestId>

4. Verify Connection: The node receives a fresh token and reconnects. You can verify the status here:

   openclaw nodes status

If you need to organize your list, I recommend renaming your nodes immediately:

openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

How It Works

The Gateway handles the heavy lifting. When a node asks to join, the Gateway creates a pending request and emits a node.pair.requested event. You then have a window to approve or reject it.

I should mention that tokens are sensitive. The Gateway stores them in ~/.openclaw/nodes/paired.json. If you ever change your OPENCLAW_STATE_DIR environment variable, this folder moves with it.

The macOS app can sometimes skip the manual click. If a request is marked as silent and the app can verify an SSH connection to the gateway host using your current user, it handles the approval automatically.

API Surface

If you are building your own tools, you will use these methods and events:

Methods

• node.pair.request: Creates or reuses a pending request.
• node.pair.list: Shows both pending and paired nodes.
• node.pair.approve: Issues a fresh token and approves the node.
• node.pair.reject: Denies the request.
• node.pair.verify: Checks a { nodeId, token } pair.

Events

• node.pair.requested: Sent when a new request arrives.
• node.pair.resolved: Sent when a request is approved, rejected, or expires.

Troubleshooting

• Request Expired: Pending requests only last for 5 minutes. If you wait too long, the node must call node.pair.request again.
• Gateway Offline: The transport is stateless. If the Gateway is down, no pairing can happen.
• Token Issues: Approval always generates a fresh token. If a node re-pairs, the old token is rotated and will no longer work.
• Remote Mode: If your Gateway is in remote mode, pairing happens against the remote Gateway’s store rather than your local machine.

Still having trouble? Check the AI Setup Assistant for help.

What’s Next

• Gateway Protocol API
• CLI Reference