romtuck/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2e3e12f38b
openclaw/docs/start/pairing.md
Davendra Patel 2e3e12f38b docs: add pre-rendered diagram PNGs and update AGENTS.md with architecture overview 
Add 32 rendered PNG diagram images alongside existing Mermaid source
blocks (wrapped in collapsible details) across documentation pages.
Update AGENTS.md with architecture overview section and single-test
command. Update README hero banner to use rendered diagram.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-29 16:02:09 +05:30

3.4 KiB
Raw Blame History

summary read_when
Pairing overview: approve who can DM you + which nodes can join
Setting up DM access control
Pairing a new iOS/Android node
Reviewing Moltbot security posture

Pairing

“Pairing” is Moltbot’s explicit owner approval step. It is used in two places:

  1. DM pairing (who is allowed to talk to the bot)
  2. Node pairing (which devices/nodes are allowed to join the gateway network)

Pairing Flows

Diagram source (Mermaid) 
sequenceDiagram
    participant S as Sender / Device
    participant GW as Gateway
    participant O as Owner (CLI)

    Note over S,GW: DM Pairing Flow
    S->>GW: Send DM message
    GW->>GW: Unknown sender → generate 8-char code
    GW->>S: Reply with pairing code (expires 1hr)
    O->>GW: moltbot pairing list <channel>
    O->>GW: moltbot pairing approve <channel> <code>
    GW->>GW: Add sender to allowlist
    S->>GW: Next message → processed normally

    Note over S,GW: Node Device Pairing Flow
    S->>GW: WS connect (role: node, device identity)
    GW->>GW: New device → create pairing request
    O->>GW: moltbot devices approve <requestId>
    GW->>S: Device token issued
    S->>GW: Future connects use device token

Security context: Security

1) DM pairing (inbound chat access)

When a channel is configured with DM policy pairing, unknown senders get a short code and their message is not processed until you approve.

Default DM policies are documented in: Security

Pairing codes:

  • 8 characters, uppercase, no ambiguous chars (0O1I).
  • Expire after 1 hour. The bot only sends the pairing message when a new request is created (roughly once per hour per sender).
  • Pending DM pairing requests are capped at 3 per channel by default; additional requests are ignored until one expires or is approved.

Approve a sender

moltbot pairing list telegram
moltbot pairing approve telegram <CODE>

Supported channels: telegram, whatsapp, signal, imessage, discord, slack.

Where the state lives

Stored under ~/.clawdbot/credentials/:

  • Pending requests: <channel>-pairing.json
  • Approved allowlist store: <channel>-allowFrom.json

Treat these as sensitive (they gate access to your assistant).

2) Node device pairing (iOS/Android/macOS/headless nodes)

Nodes connect to the Gateway as devices with role: node. The Gateway creates a device pairing request that must be approved.

Approve a node device

moltbot devices list
moltbot devices approve <requestId>
moltbot devices reject <requestId>

Where the state lives

Stored under ~/.clawdbot/devices/:

  • pending.json (short-lived; pending requests expire)
  • paired.json (paired devices + tokens)

Notes

  • The legacy node.pair.* API (CLI: moltbot nodes pending/approve) is a separate gateway-owned pairing store. WS nodes still require device pairing.

Related docs