From e7232e3b3a6cb8cdcc8fc17cba1a405393b1c422 Mon Sep 17 00:00:00 2001
From: choiking <samsamuels1927@gmail.com>
Date: Tue, 17 Mar 2026 10:02:23 +0800
Subject: [PATCH] docs: explain Paperclip gateway pairing approval

---
 docs/cli/devices.md    | 33 +++++++++++++++++++++++++++++++++
 docs/web/control-ui.md |  7 +++++++
 2 files changed, 40 insertions(+)

diff --git a/docs/cli/devices.md b/docs/cli/devices.md
index f73f30dfa1d..f97eb6f503c 100644
--- a/docs/cli/devices.md
+++ b/docs/cli/devices.md
@@ -93,6 +93,39 @@ Pass `--token` or `--password` explicitly. Missing explicit credentials is an er
 - `devices clear` is intentionally gated by `--yes`.
 - If pairing scope is unavailable on local loopback (and no explicit `--url` is passed), list/approve can use a local pairing fallback.
 
+## Paperclip / `openclaw_gateway` first-run approval
+
+When a new Paperclip agent connects through the `openclaw_gateway` adapter for the
+first time, the Gateway may require a one-time **device pairing approval** before
+runs can succeed. If Paperclip shows an error like
+`openclaw_gateway_pairing_required`, approve the pending device and retry.
+
+Typical local setup:
+
+```bash
+openclaw devices approve --latest
+```
+
+If the gateway is remote or requires explicit credentials, pass them directly:
+
+```bash
+openclaw devices approve --latest --url <gateway-ws-url> --token <gateway-token>
+```
+
+To avoid re-approving after restarts, keep a persistent device key in the
+Paperclip adapter config instead of generating a new ephemeral identity each run:
+
+```json
+{
+  "adapterConfig": {
+    "devicePrivateKeyPem": "<your-ed25519-private-key-in-pkcs8-pem>"
+  }
+}
+```
+
+If approval keeps failing, run `openclaw devices list` first to confirm a pending
+request exists.
+
 ## Token drift recovery checklist
 
 Use this when Control UI or other clients keep failing with `AUTH_TOKEN_MISMATCH` or `AUTH_DEVICE_TOKEN_MISMATCH`.
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index d35b245d814..2d84bdcec83 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -53,6 +53,13 @@ Once approved, the device is remembered and won't require re-approval unless
 you revoke it with `openclaw devices revoke --device <id> --role <role>`. See
 [Devices CLI](/cli/devices) for token rotation and revocation.
 
+If you are connecting a Paperclip agent through the `openclaw_gateway` adapter,
+the same first-run approval may be required. After the initial connection attempt,
+run `openclaw devices approve --latest`, or use explicit `--url` / `--token`
+flags for a remote gateway. To keep approvals stable across restarts, configure a
+persistent `adapterConfig.devicePrivateKeyPem` in Paperclip instead of letting it
+generate a new ephemeral device identity each run.
+
 **Notes:**
 
 - Local connections (`127.0.0.1`) are auto-approved.