openclaw-gateway: document and surface pairing-mode requirements

packages/adapters/openclaw-gateway/doc/ONBOARDING_AND_TEST_PLAN.md

@@ -250,6 +250,7 @@ POST /api/companies/$CLA_COMPANY_ID/invites
     "headers": { "x-openclaw-token": "<gateway-token>" },
     "role": "operator",
     "scopes": ["operator.admin"],
+    "disableDeviceAuth": true,
     "sessionKeyStrategy": "fixed",
     "sessionKey": "paperclip",
     "waitTimeoutMs": 120000
@@ -263,6 +264,9 @@ POST /api/companies/$CLA_COMPANY_ID/invites
 - `adapterConfig.url` uses `ws://` or `wss://`
 - `adapterConfig.headers.x-openclaw-token` exists and is not placeholder/too-short (`len >= 16`)
 - token hash matches the OpenClaw `gateway.auth.token` used for join
+- pairing mode is explicit:
+  - smoke/dev: `adapterConfig.disableDeviceAuth == true` (no interactive pairing gate)
+  - otherwise: stable `adapterConfig.devicePrivateKeyPem` is set so approvals persist across runs
 5. Claim API key with `claimSecret`.
 6. Save claimed token to OpenClaw expected file path (`~/.openclaw/workspace/paperclip-claimed-api-key.json`) and ensure `PAPERCLIP_API_KEY` + `PAPERCLIP_API_URL` are available for OpenClaw skill execution context.
   - Write compatibility JSON keys (`token` and `apiKey`) to avoid runtime parser mismatch.
@@ -318,6 +322,7 @@ Responsibilities:
 - Old OpenClaw agent cleanup.
 - Invite/join/approve/claim orchestration.
 - Gateway agent config/token preflight validation before connectivity or case execution.
+- Pairing-mode preflight (`disableDeviceAuth=true` for smoke/dev or stable `devicePrivateKeyPem`).
 - E2E case execution + assertions.
 - Final summary with run IDs, issue IDs, agent ID.
 

packages/adapters/openclaw-gateway/src/server/execute.ts

@@ -1074,15 +1074,23 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     const message = err instanceof Error ? err.message : String(err);
     const lower = message.toLowerCase();
     const timedOut = lower.includes("timeout");
+    const pairingRequired = lower.includes("pairing required");
+    const detailedMessage = pairingRequired
+      ? `${message}. Configure adapterConfig.disableDeviceAuth=true for smoke/dev, or set adapterConfig.devicePrivateKeyPem so pairing persists across runs.`
+      : message;
 
-    await ctx.onLog("stderr", `[openclaw-gateway] request failed: ${message}\n`);
+    await ctx.onLog("stderr", `[openclaw-gateway] request failed: ${detailedMessage}\n`);
 
     return {
       exitCode: 1,
       signal: null,
       timedOut,
-      errorMessage: message,
-      errorCode: timedOut ? "openclaw_gateway_timeout" : "openclaw_gateway_request_failed",
+      errorMessage: detailedMessage,
+      errorCode: timedOut
+        ? "openclaw_gateway_timeout"
+        : pairingRequired
+          ? "openclaw_gateway_pairing_required"
+          : "openclaw_gateway_request_failed",
       resultJson: asRecord(latestResultPayload),
     };
   } finally {