Gateway Device Pairing

Scope

• In-scope: pairing/triage Gateway device according to skill workflow, distinguish device pairing from channel pairing, verify operator permission before patch/restart.
• Out-of-scope: channel pairing or mutation runtime outside of scope pairing without approval.

Indexed Reference Map

• @[SKILL.md#L1-L108] Standard Frontmatter (name, description).
• @[SKILL.md#L6-L108] Device Pairing process for Gateway.
• @[SKILL.md#L8-L108] Target.
• @[SKILL.md#L14-L108] When to activate skill.
• @[SKILL.md#L21-L108] Distinguish between two types of pairing.
• @[SKILL.md#L32-L108] Standard SOP (diagnose → approve → verify).
• @[SKILL.md#L58-L108] Troubleshooting nhanh.
• @[SKILL.md#L81-L108] Guardrails are safe.
• @[references/runbook.md#L1-L104] Copy/paste sample command for each situation.

Target

Standardize the operation when Gateway denies access with error pairing required, so that future models do not confuse:

• Device pairing of Gateway auth
• Pairing theo channel (Telegram DM allowlist)

When to activate skills?

Use this skill when one of the following signs appears:

• Tool gateway error gateway closed (1008): pairing required
• openclaw status reports Gateway unreachable because pairing is required
• openclaw devices list returns pending request to approve

Distinguish between 2 types of pairing (required)

1. Gateway device pairing
   • Main command: openclaw devices list|approve
   • Effect: grant trust + token/scopes to CLI/device calling Gateway API.
2. Channel pairing (eg Telegram DM)
   • Main command: openclaw pairing list|approve
   • Effect: Control who can message bots in DM/group according to policy channel.

Conclusion: Gateway's pairing required error is not handled by openclaw pairing ... if pending is in devices.

Standard SOPs

Step 1 — Diagnose the correct layer

1. Run openclaw status.
2. If pairing required is present, run openclaw devices list --json.
3. If pending is empty, check the wrong profile/runtime (--dev, --profile, other node).

Step 2 — Approve device pending

1. Latest Approve:

   openclaw devices approve --latest --json

2. Or approve by request id:

   openclaw devices approve <requestId> --json

Step 3 — Verify required

1. openclaw devices list --json → the approved request is no longer in pending.
2. openclaw status → Gateway must switch to reachable.
3. Try a real Gateway command (e.g. gateway config.get) to confirm operation.

Troubleshooting nhanh

• devices list still reports pairing required but has JSON pending:
  • can still approve; Prioritize checking JSON output device.approvedScopes.
• Thực chiến (2026-03-27, Android local loopback): openclaw devices approve --latest có thể vẫn in gateway connect failed: pairing required ở bước đầu, sau đó chuyển sang Direct scope access failed; using local fallback. và vẫn Approved <deviceId> (<requestId>) thành công.
  • Không kết luận fail chỉ vì thấy dòng pairing required trong cùng lần approve.
  • Luôn verify hậu kiểm: openclaw status phải báo Gateway reachable (auth token) và thử openclaw logs --limit 30 --plain để xác nhận RPC đã dùng được.
• App reports unauthorized: gateway token missing (provide gateway auth token) on local route http://127.0.0.1:18789:
  • classify is pairing/auth, not TLS or gateway down.
  • The app reached the correct local gateway but was blocked at the auth layer before onboarding was completed.
  • devices list at this time may not be pending; Only when the app re-emit request is successful will the actual pending appear.
• Same-machine Android (gateway + app on same phone):
  • direct local route priority 127.0.0.1:18789, TLS OFF.
  • Do not prioritize qr/publicUrl/tailnet if the target only pairs locally on the machine itself.
• Pending request requires a wider scope than the current operator (eg operator.talk.secrets) and approval fails/does not appear:
  • check /data/adb/openclaw/home/.openclaw/devices/pending.json and paired.json to compare pending.scopes with approvedScopes/tokens.operator.scopes.
  • Formal remediation first: openclaw devices rotate --device <id> --role operator --scope ... to extend the token in the approved baseline.
  • Only consider patching local auth state backup-first when the command-level line is not enough.
• After approving, it's still unreachable:
  • mistakenly checked runtime/profile (openclaw --dev ... vs default).
  • Check the correct Gateway port (ws://127.0.0.1:18789 or port override).
• Need to recall old equipment:
  • Use openclaw devices remove|revoke|rotate according to role/scopes.

Guardrails are safe

• Do not approve strange requests without verifying displayName/clientId/platform.
• Do not reveal detailed tokens/scopes in public chat.
• Do not confuse pairing channel with pairing device when handling auth errors.
• After pairing successfully, perform config patch/restart/privileged actions.

Expected results

Later models can correctly identify the pairing required error, run the correct flow devices approve, verify and then safely operate the Gateway config.

Trigger Rules

• Positive: Activate when the user request matches gateway-device-pairing according to description: Standardize the Device Pairing process for Gateway (fix pairing required error), clearly distinguish it from channel pairing, and verify operator authority before patching/restarting config.
• Negative: Not enabled for requests outside scope or without the workflow/expertise of this skill.
• Escalation: If there is an external action/network write or sensitive operation, an approval checkpoint must be added before executing.

Error Handling

• If you don't see a pending request: clearly distinguish whether there is no real request or you are confusing device pairing with channel pairing.
• If approval fails due to operator permissions: stop at the verify role/permissions step instead of continuing to patch the config blindly.
• If pair is done but error persists: switch to triage config/runtime with evidence from devices pending/approve/status.

Output Contract

• Deliverable: target tracking result of gateway-device-pairing; Specify the artifact/path/steps performed (if any).
• Validation: reports PASS/FAIL status and main checks have been run.
• Failure mode: when there is an error, the root cause + proposed fix must be stated.