romtuck/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d9851627b2
openclaw/docs/start/pairing.md
Davendra Patel d9851627b2 docs: add 29 inline Mermaid diagrams across documentation 
Add visual Mermaid diagrams to supplement existing text descriptions
throughout docs/. Diagrams cover architecture, message flows, agent
lifecycle, routing, queue modes, security layers, plugin discovery,
tool groups, session lifecycle, and onboarding flows. No existing
content removed or altered.

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

3.3 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)
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