diff --git a/docs/cli/devices.md b/docs/cli/devices.md
index fa0d53a2401..d69ec9e73be 100644
--- a/docs/cli/devices.md
+++ b/docs/cli/devices.md
@@ -101,6 +101,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 9de259a7ef4..2cce81812da 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -57,6 +57,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.