romtuck/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add 29 inline Mermaid diagrams across documentation

Browse Source 
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>
This commit is contained in:
Davendra Patel 2026-01-29 10:58:42 +05:30
parent 34291321b4
commit d9851627b2
25 changed files with 672 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@ -52,6 +52,41 @@ moltbot onboard --install-daemon
The wizard installs the Gateway daemon (launchd/systemd user service) so it stays running.
Legacy note: `clawdbot` remains available as a compatibility shim.
```mermaid
graph LR
subgraph Channels [Messaging Channels]
WA[WhatsApp]
TG[Telegram]
SL[Slack]
DC[Discord]
SIG[Signal]
IM[iMessage]
WC[WebChat]
MORE[+ more]
end
GW[Gateway\nWebSocket + HTTP\nControl Plane]
subgraph Agent [AI Agent]
RT[Runtime\npi-agent-core]
SK[Skills]
MEM[Memory]
end
subgraph Tools [Agent Tools]
EXEC[Shell / FS]
BR[Browser]
MSG[Messaging]
CRON[Cron / Automation]
end
Channels -->|inbound| GW
GW -->|route + queue| Agent
Agent -->|tool calls| Tools
Agent -->|reply| GW
GW -->|outbound| Channels
```
## Quick start (TL;DR)
Runtime: **Node ≥22**.

21
docs/automation/cron-jobs.md
View File

@ -15,6 +15,27 @@ the right time, and can optionally deliver output back to a chat.
If you want *“run this every morning”* or *“poke the agent in 20 minutes”*,
cron is the mechanism.
```mermaid
flowchart TD
subgraph MainSession [Main Session Job]
MS1[Schedule Triggers] --> MS2[Enqueue System Event]
MS2 --> MS3{Wake Mode?}
MS3 -->|next-heartbeat| MS4[Wait for Next Heartbeat]
MS3 -->|now| MS5[Immediate Heartbeat]
MS4 --> MS6[Run in Main Session Context]
MS5 --> MS6
end
subgraph IsolatedSession [Isolated Session Job]
IS1[Schedule Triggers] --> IS2[Create Fresh Session\ncron:jobId]
IS2 --> IS3[Run Dedicated Agent Turn]
IS3 --> IS4[Post Summary to Main]
IS4 --> IS5{Deliver?}
IS5 -->|Yes| IS6[Send to Channel Target]
IS5 -->|No| IS7[Internal Only]
end
```
## TL;DR
- Cron runs **inside the Gateway** (not inside the model).
- Jobs persist under `~/.clawdbot/cron/` so restarts don’t lose schedules.

29
docs/automation/webhook.md
View File

@ -9,6 +9,35 @@ read_when:
Gateway can expose a small HTTP webhook endpoint for external triggers.
```mermaid
sequenceDiagram
participant EXT as External System
participant WH as Gateway /hooks
participant AUTH as Auth Check
participant GW as Gateway Core
EXT->>WH: POST /hooks/wake or /hooks/agent
WH->>AUTH: Verify token (Bearer / header / query)
alt Token valid
AUTH->>WH: OK
alt /hooks/wake
WH->>GW: Enqueue system event
GW->>GW: Trigger heartbeat (if mode=now)
WH-->>EXT: 200 OK
else /hooks/agent
WH->>GW: Start isolated agent run
GW->>GW: Post summary to main session
GW->>GW: Deliver to channel (if configured)
WH-->>EXT: 202 Accepted
else /hooks/<name> (mapped)
WH->>GW: Resolve mapping → wake or agent
WH-->>EXT: 200/202
end
else Token invalid
AUTH-->>EXT: 401 Unauthorized
end
```
## Enable
```json5

19
docs/broadcast-groups.md
View File

@ -17,6 +17,25 @@ Broadcast Groups enable multiple agents to process and respond to the same messa
Current scope: **WhatsApp only** (web channel).
```mermaid
flowchart TD
MSG[Incoming Message] --> ALLOW{Channel Allowlist\n+ Group Activation?}
ALLOW -->|Blocked| DROP[Ignored]
ALLOW -->|Allowed| BC{Peer in\nBroadcast Config?}
BC -->|No| NORMAL[Normal Routing\nSingle agent via bindings]
BC -->|Yes| AGENTS[Get Agent List\nfor this peer]
AGENTS --> STRAT{Strategy?}
STRAT -->|parallel| PAR[Run All Agents\nSimultaneously]
STRAT -->|sequential| SEQ[Run Agents\nIn Order]
PAR --> ISO1[Agent A\nIsolated Session]
PAR --> ISO2[Agent B\nIsolated Session]
PAR --> ISO3[Agent C\nIsolated Session]
SEQ --> ISO1
ISO1 --> |done| ISO2
ISO2 --> |done| ISO3
ISO1 & ISO2 & ISO3 --> DELIVER[Deliver Replies\nto Same Chat]
```
Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when Moltbot would normally reply (for example: on mention, depending on your group settings).
## Use Cases

51
docs/concepts/agent-loop.md
View File

@ -13,6 +13,22 @@ In Moltbot, a loop is a single, serialized run per session that emits lifecycle
as the model thinks, calls tools, and streams output. This doc explains how that authentic loop is
wired end-to-end.
```mermaid
stateDiagram-v2
[*] --> Intake: Inbound message / RPC
Intake --> ContextAssembly: Resolve session + workspace
ContextAssembly --> PromptBuild: Load skills, bootstrap files
PromptBuild --> ModelInference: System prompt + history
ModelInference --> ToolExecution: Tool calls returned
ToolExecution --> ModelInference: Tool results fed back
ModelInference --> Streaming: Assistant text deltas
Streaming --> Persistence: Final reply assembled
Persistence --> [*]: Session updated + reply delivered
ModelInference --> Compaction: Context limit hit
Compaction --> ModelInference: Retry with compacted context
```
## Entry points
- Gateway RPC: `agent` and `agent.wait`.
- CLI: `agent` command.
@ -80,6 +96,41 @@ These run inside the agent loop or gateway pipeline:
See [Plugins](/plugin#plugin-hooks) for the hook API and registration details.
```mermaid
sequenceDiagram
participant GW as Gateway
participant HOOK as Plugin Hooks
participant AGENT as Agent Runtime
participant MODEL as Model API
participant TOOL as Tool Execution
GW->>HOOK: gateway_start
Note over GW: Gateway initializes
GW->>HOOK: message_received
GW->>HOOK: session_start
GW->>HOOK: before_agent_start
GW->>AGENT: Start agent run
AGENT->>MODEL: Send prompt + context
loop Tool Loop
MODEL->>AGENT: Tool call request
AGENT->>HOOK: before_tool_call
AGENT->>TOOL: Execute tool
TOOL->>AGENT: Tool result
AGENT->>HOOK: after_tool_call
AGENT->>HOOK: tool_result_persist
AGENT->>MODEL: Feed result back
end
MODEL->>AGENT: Final assistant reply
AGENT->>HOOK: agent_end
GW->>HOOK: message_sending
Note over GW: Deliver reply
GW->>HOOK: message_sent
GW->>HOOK: session_end
```
## Streaming + partial replies
- Assistant deltas are streamed from pi-agent-core and emitted as `assistant` events.
- Block streaming can emit partial replies either on `text_end` or `message_end`.

35
docs/concepts/agent-workspace.md
View File

@ -9,6 +9,41 @@ read_when:
The workspace is the agent's home. It is the only working directory used for
file tools and for workspace context. Keep it private and treat it as memory.
```mermaid
graph TD
subgraph Workspace ["Agent Workspace (~/clawd)"]
AGENTS[AGENTS.md\nOperating instructions]
SOUL[SOUL.md\nPersona + tone]
USER[USER.md\nUser profile]
IDENTITY[IDENTITY.md\nAgent name + emoji]
TOOLS[TOOLS.md\nTool notes]
HEARTBEAT[HEARTBEAT.md\nHeartbeat checklist]
BOOT[BOOT.md\nStartup checklist]
BOOTSTRAP[BOOTSTRAP.md\nFirst-run ritual]
subgraph MemoryDir [memory/]
DAILY[YYYY-MM-DD.md\nDaily logs]
end
MEMORY_MD[MEMORY.md\nLong-term memory]
subgraph SkillsDir [skills/]
SKILL[Custom skills]
end
subgraph CanvasDir [canvas/]
CANVAS_HTML[index.html\nCanvas UI]
end
end
subgraph StateDir ["State Directory (~/.clawdbot)"]
CONFIG[moltbot.json\nConfiguration]
CREDS[credentials/\nOAuth, API keys]
SESSIONS[agents/agentId/sessions/\nTranscripts + metadata]
MANAGED_SKILLS[skills/\nManaged skills]
end
```
This is separate from `~/.clawdbot/`, which stores config, credentials, and
sessions.

39
docs/concepts/architecture.md
View File

@ -21,6 +21,45 @@ Last updated: 2026-01-22
## Components and flows
```mermaid
graph TD
subgraph Channels
WA[WhatsApp/Baileys]
TG[Telegram/grammY]
SL[Slack]
DC[Discord]
SIG[Signal]
IM[iMessage]
WC[WebChat]
end
subgraph Clients
CLI[CLI]
MAC[macOS App]
WEB[Web UI]
AUTO[Automations]
end
subgraph Nodes
MACOS_N[macOS Node]
IOS_N[iOS Node]
AND_N[Android Node]
HEAD_N[Headless Node]
end
GW[Gateway\nWebSocket Server\n127.0.0.1:18789]
WA & TG & SL & DC & SIG & IM & WC --> GW
CLI & MAC & WEB & AUTO -->|WS: role=operator| GW
MACOS_N & IOS_N & AND_N & HEAD_N -->|WS: role=node| GW
GW --> AGENT[Agent Runtime\npi-agent-core]
AGENT --> TOOLS[Tools\nbrowser, exec, canvas,\nmessage, cron, nodes]
CANVAS[Canvas Host\n:18793]
GW -.-> CANVAS
```
### Gateway (daemon)
- Maintains provider connections.
- Exposes a typed WS API (requests, responses, server‑push events).

30
docs/concepts/channel-routing.md
View File

@ -51,6 +51,23 @@ Routing picks **one agent** for each inbound message:
The matched agent determines which workspace and session store are used.
```mermaid
flowchart TD
MSG[Inbound Message] --> P1{Exact Peer Match?}
P1 -->|Yes| FOUND[Agent Found]
P1 -->|No| P2{Guild Match?\nDiscord guildId}
P2 -->|Yes| FOUND
P2 -->|No| P3{Team Match?\nSlack teamId}
P3 -->|Yes| FOUND
P3 -->|No| P4{Account Match?\naccountId}
P4 -->|Yes| FOUND
P4 -->|No| P5{Channel Match?\nany account}
P5 -->|Yes| FOUND
P5 -->|No| P6[Default Agent\nagents.list default\nor first entry\nor 'main']
P6 --> FOUND
FOUND --> WS[Workspace + Session Store]
```
## Broadcast groups (run multiple agents)
Broadcast groups let you run **multiple agents** for the same peer **when Moltbot would normally reply** (for example: in WhatsApp groups, after mention/activation gating).
@ -69,6 +86,19 @@ Config:
See: [Broadcast Groups](/broadcast-groups).
```mermaid
flowchart TD
MSG[Inbound Message\nfrom peer] --> BC{Peer in\nBroadcast Config?}
BC -->|Yes| MULTI[Broadcast:\nAll listed agents process\nisolated sessions each]
BC -->|No| BIND{Peer in\nBindings?}
BIND -->|Yes| SINGLE[Normal Routing:\nOne matched agent]
BIND -->|No| DEFAULT[Default Agent\nfallback routing]
MULTI --> REPLY_M[Multiple Replies\nfrom each agent]
SINGLE --> REPLY_S[Single Reply]
DEFAULT --> REPLY_S
```
## Config overview
- `agents.list`: named agent definitions (workspace, model, etc.).

16
docs/concepts/compaction.md
View File

@ -8,6 +8,22 @@ read_when:
Every model has a **context window** (max tokens it can see). Long-running chats accumulate messages and tool results; once the window is tight, Moltbot **compacts** older history to stay within limits.
```mermaid
flowchart TD
A[Session Messages Accumulate] --> B{Near Context Limit?}
B -->|No| C[Continue Normally]
B -->|Yes| D{Memory Flush Enabled?}
D -->|Yes| E[Silent Memory Flush Turn\nWrite durable notes to disk]
D -->|No| F[Skip Flush]
E --> F
F --> G[Auto-Compaction Triggered]
G --> H[Summarize Older Messages]
H --> I[Store Compaction Summary\nin Session JSONL]
I --> J[Keep Recent Messages Intact]
J --> K[Retry Original Request\nwith Compacted Context]
K --> C
```
## What compaction is
Compaction **summarizes older conversation** into a compact summary entry and keeps recent messages intact. The summary is stored in the session history, so future requests use:
- The compaction summary

28
docs/concepts/memory.md
View File

@ -9,6 +9,34 @@ read_when:
Moltbot memory is **plain Markdown in the agent workspace**. The files are the
source of truth; the model only "remembers" what gets written to disk.
```mermaid
flowchart TD
subgraph WorkspaceFiles [Workspace Memory Files]
MEM_MD[MEMORY.md\nCurated long-term]
DAILY[memory/YYYY-MM-DD.md\nDaily logs]
end
subgraph VectorIndex [Vector Memory Search]
EMB[Embedding Provider\nOpenAI / Gemini / Local]
IDX[SQLite Index\n~/.clawdbot/memory/agentId.sqlite]
BM25[BM25 Full-Text\nKeyword matching]
end
subgraph FlushCycle [Pre-Compaction Flush]
NEAR[Session Nears Limit] --> FLUSH[Silent Memory Flush Turn]
FLUSH --> WRITE[Write Notes to Disk]
WRITE --> COMPACT[Compaction Proceeds]
end
MEM_MD --> EMB
DAILY --> EMB
EMB --> IDX
IDX --> SEARCH[memory_search Tool]
BM25 --> SEARCH
MEM_MD --> READ[memory_get Tool]
DAILY --> READ
```
Memory search tools are provided by the active memory plugin (default:
`memory-core`). Disable memory plugins with `plugins.slots.memory = "none"`.

24
docs/concepts/messages.md
View File

@ -20,6 +20,30 @@ Inbound message
-> outbound replies (channel limits + chunking)
```
```mermaid
flowchart TD
A[Inbound Message] --> B{Dedupe Cache}
B -->|Duplicate| DROP[Drop]
B -->|New| C{Debounce Window}
C -->|Batched| D[Combined Message]
C -->|Single| D
D --> E[Routing / Bindings]
E --> F[Session Key Resolution]
F --> G{Run Active?}
G -->|No| H[Start Agent Run]
G -->|Yes| I{Queue Mode}
I -->|steer| J[Inject into Current Run]
I -->|followup| K[Queue for Next Turn]
I -->|collect| L[Coalesce into Single Followup]
H --> M[Streaming + Tools]
J --> M
K --> M
L --> M
M --> N[Outbound Reply]
N --> O[Channel Chunking + Limits]
O --> P[Delivered]
```
Key knobs live in configuration:
- `messages.*` for prefixes, queueing, and group behavior.
- `agents.defaults.*` for block streaming and chunking defaults.

19
docs/concepts/model-failover.md
View File

@ -13,6 +13,25 @@ Moltbot handles failures in two stages:
This doc explains the runtime rules and the data that backs them.
```mermaid
flowchart TD
REQ[Agent Run Request] --> PROF[Select Auth Profile\nSession-pinned or round-robin]
PROF --> CALL[API Call to Provider]
CALL --> OK{Success?}
OK -->|Yes| DONE[Run Completes]
OK -->|No| ERR{Error Type?}
ERR -->|Rate limit / Auth| CD[Cooldown Profile\nExponential: 1m → 5m → 25m → 1hr]
ERR -->|Billing / Credits| DIS[Disable Profile\n5hr → 24hr backoff]
ERR -->|Format / Invalid| CD
CD --> NEXT{More Profiles\nfor Provider?}
DIS --> NEXT
NEXT -->|Yes| PROF
NEXT -->|No| FB{Model Fallbacks\nConfigured?}
FB -->|Yes| SWITCH[Switch to Next Model\nin fallbacks list]
FB -->|No| FAIL[Run Fails]
SWITCH --> PROF
```
## Auth storage (keys + OAuth)
Moltbot uses **auth profiles** for both API keys and OAuth tokens.

26
docs/concepts/multi-agent.md
View File

@ -9,7 +9,31 @@ status: active
Goal: multiple *isolated* agents (separate workspace + `agentDir` + sessions), plus multiple channel accounts (e.g. two WhatsApps) in one running Gateway. Inbound is routed to an agent via bindings.
## What is “one agent”?
```mermaid
graph TD
GW[Gateway Process] --> A1[Agent: home]
GW --> A2[Agent: work]
subgraph Agent_home [Agent 'home']
W1[Workspace\n~/clawd-home]
S1[Sessions\n~/.clawdbot/agents/home/sessions]
AP1[Auth Profiles\n~/.clawdbot/agents/home/agent/auth-profiles.json]
SK1[Skills\n~/clawd-home/skills/]
end
subgraph Agent_work [Agent 'work']
W2[Workspace\n~/clawd-work]
S2[Sessions\n~/.clawdbot/agents/work/sessions]
AP2[Auth Profiles\n~/.clawdbot/agents/work/agent/auth-profiles.json]
SK2[Skills\n~/clawd-work/skills/]
end
B1[Binding: WhatsApp personal] --> A1
B2[Binding: WhatsApp biz] --> A2
B3[Binding: Telegram] --> A2
```
## What is "one agent"?
An **agent** is a fully scoped brain with its own:

42
docs/concepts/queue.md
View File

@ -7,6 +7,27 @@ read_when:
We serialize inbound auto-reply runs (all channels) through a tiny in-process queue to prevent multiple agent runs from colliding, while still allowing safe parallelism across sessions.
```mermaid
flowchart LR
subgraph SessionLanes [Session Lanes\none run per session]
SL1[session:agent:main:main]
SL2[session:agent:main:telegram:group:123]
SL3[session:agent:work:main]
end
subgraph GlobalLanes [Global Lanes]
ML[Main Lane\nconcurrency: 4]
SAL[Subagent Lane\nconcurrency: 8]
CL[Cron Lane]
end
SL1 --> ML
SL2 --> ML
SL3 --> ML
SAL -.->|parallel| ML
CL -.->|parallel| ML
```
## Why
- Auto-reply runs can be expensive (LLM calls) and can collide when multiple inbound messages arrive close together.
- Serializing avoids competing for shared resources (session files, logs, CLI stdin) and reduces the chance of upstream rate limits.
@ -27,6 +48,27 @@ Inbound messages can steer the current run, wait for a followup turn, or do both
- `interrupt` (legacy): abort the active run for that session, then run the newest message.
- `queue` (legacy alias): same as `steer`.
```mermaid
stateDiagram-v2
[*] --> Idle: No active run
Idle --> Running: Message arrives
Running --> Steer: steer mode\ninject into run
Running --> Followup: followup mode\nqueue for next turn
Running --> Collect: collect mode\ncoalesce messages
Running --> Interrupt: interrupt mode\nabort + run newest
Steer --> Running: Tool boundary reached
Followup --> Idle: Current run ends
Followup --> Running: Followup turn starts
Collect --> Idle: Current run ends
Collect --> Running: Single combined turn
Interrupt --> Running: New run starts
Running --> SteerBacklog: steer-backlog mode
SteerBacklog --> Running: Steer now + preserve for followup
```
Steer-backlog means you can get a followup response after the steered run, so
streaming surfaces can look like duplicates. Prefer `collect`/`steer` if you want
one response per inbound message.

15
docs/concepts/session.md
View File

@ -7,6 +7,21 @@ read_when:
Moltbot treats **one direct-chat session per agent** as primary. Direct chats collapse to `agent:<agentId>:<mainKey>` (default `main`), while group/channel chats get their own keys. `session.mainKey` is honored.
```mermaid
flowchart TD
CREATE[Session Created\nNew inbound message] --> LOAD[Load Session\nfrom sessions.json + JSONL]
LOAD --> EXEC[Execute Agent Run\nStreaming + tools]
EXEC --> UPDATE[Update Session\nAppend to JSONL transcript]
UPDATE --> CHECK{Near Context Limit?}
CHECK -->|No| WAIT[Wait for Next Message]
CHECK -->|Yes| COMPACT[Auto-Compaction\nSummarize + retain recent]
COMPACT --> WAIT
WAIT --> RESET{Reset Triggered?}
RESET -->|Daily reset / idle / /new| ARCHIVE[Archive Session\nFresh session ID]
RESET -->|No| LOAD
ARCHIVE --> CREATE
```
Use `session.dmScope` to control how **direct messages** are grouped:
- `main` (default): all DMs share the main session for continuity.
- `per-peer`: isolate by sender id across channels.

23
docs/concepts/streaming.md
View File

@ -13,6 +13,29 @@ Moltbot has two separate “streaming” layers:
There is **no real token streaming** to external channel messages today. Telegram draft streaming is the only partial-stream surface.
```mermaid
flowchart TD
MODEL[Model Output\ntext_delta events] --> BS{Block Streaming\nEnabled?}
BS -->|Off| FINAL[Wait for Final Reply]
BS -->|On| BREAK{Break Mode?}
BREAK -->|text_end| CHUNK1[Chunker Emits\nas Buffer Grows]
BREAK -->|message_end| CHUNK2[Chunker Flushes\nat message_end]
CHUNK1 --> COAL{Coalesce?}
CHUNK2 --> COAL
COAL -->|Yes| MERGE[Merge Consecutive Chunks\nidle-gap based]
COAL -->|No| SEND[Channel Send]
MERGE --> SEND
FINAL --> SEND
SEND --> LIMIT{Channel Limits}
LIMIT --> SPLIT[Split by textChunkLimit\npreserve code fences]
SPLIT --> DELIVER[Delivered to Channel]
MODEL --> TG{Telegram?}
TG -->|Yes| DRAFT[Draft Bubble\nsendMessageDraft]
DRAFT --> TGFINAL[Final: Normal Message]
TG -->|No| BS
```
## Block streaming (channel messages)
Block streaming sends assistant output in coarse chunks as it becomes available.

23
docs/gateway/index.md
View File

@ -9,6 +9,20 @@ Last updated: 2025-12-09
## What it is
- The always-on process that owns the single Baileys/Telegram connection and the control/event plane.
```mermaid
stateDiagram-v2
[*] --> NotInstalled
NotInstalled --> Installing: moltbot gateway install
Installing --> Installed: LaunchAgent / systemd unit created
Installed --> Running: Service starts
Running --> Running: Config hot-reload\nSIGUSR1 in-process restart
Running --> Stopped: moltbot gateway stop\nSIGTERM
Stopped --> Running: moltbot gateway restart\nService supervisor
Running --> Error: Fatal error
Error --> Running: Supervisor auto-restart\nRestartSec=5
```
- Replaces the legacy `gateway` command. CLI entry point: `moltbot gateway`.
- Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.
@ -22,6 +36,15 @@ moltbot gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch
```
```mermaid
flowchart LR
WATCH[File Watcher\n~/.clawdbot/moltbot.json] --> DEBOUNCE[Debounce]
DEBOUNCE --> ANALYZE{Analyze Changes}
ANALYZE -->|Safe changes\nthresholds, toggles| HOT[Hot Apply\nNo restart needed]
ANALYZE -->|Critical changes\nport, auth, channels| RESTART[In-Process Restart\nSIGUSR1]
ANALYZE -->|reload.mode=off| IGNORE[Ignored]
```
- Config hot reload watches `~/.clawdbot/moltbot.json` (or `CLAWDBOT_CONFIG_PATH`).
- Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical).
- Hot reload uses in-process restart via **SIGUSR1** when needed.

25
docs/gateway/protocol.md
View File

@ -18,6 +18,31 @@ handshake time.
- WebSocket, text frames with JSON payloads.
- First frame **must** be a `connect` request.
```mermaid
sequenceDiagram
participant C as Client
participant G as Gateway
G->>C: event: connect.challenge {nonce, ts}
C->>G: req: connect {protocol, client, role, scopes, auth, device}
alt Valid credentials + device
G->>C: res: hello-ok {protocol, snapshot, policy}
Note over G,C: Includes presence + health snapshot
opt New device
G->>C: hello-ok.auth {deviceToken, role, scopes}
end
else Invalid
G->>C: res: error
G--xC: Socket closed
end
loop Normal operation
C->>G: req {method, params}
G->>C: res {ok, payload}
G->>C: event {presence, tick, agent, ...}
end
```
## Handshake (connect)
Gateway → Client (pre-connect challenge):

28
docs/gateway/security/index.md
View File

@ -35,6 +35,34 @@ Moltbot is both a product and an experiment: you’re wiring frontier-model beha
Start with the smallest access that still works, then widen it as you gain confidence.
```mermaid
graph TD
subgraph Layer1 [Layer 1: Inbound Access Control]
DM[DM Policy\npairing / allowlist / open / disabled]
GP[Group Policy\nallowlist + mention gating]
AL[Allowlists\nper-channel sender lists]
end
subgraph Layer2 [Layer 2: Tool & Execution Scope]
TP[Tool Policy\nallow / deny lists]
SB[Sandboxing\nDocker isolation]
EL[Elevated Mode\nhost exec gating]
BR[Browser Control\nprofile isolation]
end
subgraph Layer3 [Layer 3: Model & Prompt]
MI[Model Choice\ninstruction-hardened models]
SP[System Prompt\nsafety rules + persona]
PI[Prompt Injection\nresistance varies by model]
end
INBOUND[Inbound Message] --> Layer1
Layer1 -->|Authorized| Layer2
Layer1 -->|Blocked| REJECT[Rejected]
Layer2 -->|Scoped| Layer3
Layer3 --> AGENT[Agent Executes]
```
### What the audit checks (high level)
- **Inbound access** (DM policies, group policies, allowlists): can strangers trigger the bot?

19
docs/install/index.md
View File

@ -9,6 +9,25 @@ read_when:
Use the installer unless you have a reason not to. It sets up the CLI and runs onboarding.
```mermaid
flowchart TD
START[Install Moltbot] --> OS{Operating System?}
OS -->|macOS| MAC[macOS]
OS -->|Linux| LINUX[Linux]
OS -->|Windows| WIN[Windows WSL2]
MAC --> METHOD{Install Method?}
LINUX --> METHOD
WIN --> WSL[Install WSL2 First] --> METHOD
METHOD -->|Installer Script| CURL["curl -fsSL https://molt.bot/install.sh | bash"]
METHOD -->|npm Global| NPM[npm install -g moltbot@latest]
METHOD -->|From Source| GIT[git clone + pnpm install + pnpm build]
METHOD -->|Docker| DOCKER[Docker container]
METHOD -->|Nix| NIX[Nix flake]
CURL --> ONBOARD[moltbot onboard --install-daemon]
NPM --> ONBOARD
GIT --> ONBOARD
```
## Quick install (recommended)
```bash

23
docs/plugin.md
View File

@ -112,6 +112,29 @@ manifest.
If multiple plugins resolve to the same id, the first match in the order above
wins and lower-precedence copies are ignored.
```mermaid
flowchart TD
A[Plugin Discovery] --> B[1. Config Paths\nplugins.load.paths]
B --> C[2. Workspace Extensions\nworkspace/.clawdbot/extensions/]
C --> D[3. Global Extensions\n~/.clawdbot/extensions/]
D --> E[4. Bundled Extensions\nmoltbot/extensions/\ndisabled by default]
E --> F{Duplicate ID?}
F -->|Yes| G[First Match Wins\nlower-precedence ignored]
F -->|No| H[Load Plugin]
H --> I{plugins.allow / deny?}
I -->|Denied| J[Skip Plugin]
I -->|Allowed| K[Register Plugin]
K --> L[Gateway RPC Methods]
K --> M[Agent Tools]
K --> N[CLI Commands]
K --> O[Background Services]
K --> P[Skills]
K --> Q[Plugin Hooks]
```
### Package packs
A plugin directory may include a `package.json` with `moltbot.extensions`:

13
docs/start/getting-started.md
View File

@ -9,6 +9,19 @@ read_when:
Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible.
```mermaid
flowchart TD
A[Install Moltbot\nnpm install -g moltbot] --> B[Run Onboarding Wizard\nmoltbot onboard --install-daemon]
B --> C[Model Auth\nOAuth or API Key]
C --> D[Gateway Settings\nport, bind, token]
D --> E[Channel Setup\nWhatsApp / Telegram / etc.]
E --> F[Pairing Defaults\nSecure DM access]
F --> G[Workspace Bootstrap\nAGENTS.md, SOUL.md, etc.]
G --> H[Install Daemon\nlaunchd / systemd]
H --> I[Gateway Running\nAlways-on service]
I --> J[Send First Message\nmoltbot agent --message 'Hello']
```
Fastest chat: open the Control UI (no channel setup needed). Run `moltbot dashboard`
and chat in the browser, or open `http://127.0.0.1:18789/` on the gateway host.
Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui).

23
docs/start/pairing.md
View File

@ -14,6 +14,29 @@ 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)
```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](/gateway/security)
## 1) DM pairing (inbound chat access)

18
docs/tools/browser.md
View File

@ -321,6 +321,24 @@ High-level flow:
This design keeps the agent on a stable, deterministic interface while letting
you swap local/remote browsers and profiles.
```mermaid
flowchart TD
AGENT[Agent Tool Call\nbrowser action] --> TARGET{Target?}
TARGET -->|sandbox| SB[Sandbox Browser\nDocker container]
TARGET -->|host| LOCAL{Local Browser\nRunning?}
TARGET -->|node| NODE[Node Host\nProxy to remote browser]
LOCAL -->|No| START[Launch Chromium\nvia CDP on loopback]
LOCAL -->|Yes| CDP[Connect via CDP]
START --> CDP
CDP --> PW{Playwright\nAvailable?}
PW -->|Yes| ACTIONS[Full Actions\nclick/type/snapshot/PDF]
PW -->|No| BASIC[Basic Only\nARIA snapshot + screenshot]
ACTIONS --> RESULT[Return to Agent\nsnapshot / screenshot / action result]
BASIC --> RESULT
NODE --> RESULT
SB --> RESULT
```
## CLI quick reference
All commands accept `--browser-profile <name>` to target a specific profile.

49
docs/tools/index.md
View File

@ -11,6 +11,55 @@ Moltbot exposes **first-class agent tools** for browser, canvas, nodes, and cron
These replace the old `moltbot-*` skills: the tools are typed, no shelling,
and the agent should rely on them directly.
```mermaid
graph LR
subgraph Runtime [group:runtime]
EXEC[exec]
BASH[bash]
PROC[process]
end
subgraph FS [group:fs]
READ[read]
WRITE[write]
EDIT[edit]
PATCH[apply_patch]
end
subgraph Sessions [group:sessions]
SL[sessions_list]
SH[sessions_history]
SS[sessions_send]
SP[sessions_spawn]
SST[session_status]
end
subgraph Web [group:web]
WS[web_search]
WF[web_fetch]
end
subgraph UI [group:ui]
BROWSER[browser]
CANVAS[canvas]
end
subgraph Automation [group:automation]
CRON[cron]
GATEWAY[gateway]
end
subgraph Messaging [group:messaging]
MSG[message]
end
subgraph Other
NODES[nodes]
IMAGE[image]
AGENTS_LIST[agents_list]
end
```
## Disabling tools
You can globally allow/deny tools via `tools.allow` / `tools.deny` in `moltbot.json`