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

docs: remove Mermaid source blocks, keep diagram images only

Browse Source
This commit is contained in:
Davendra Patel 2026-01-29 16:14:12 +05:30
parent 2e3e12f38b
commit 7579008543
25 changed files with 2 additions and 817 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
README.md
View File

@ -1,7 +1,7 @@
# 🦞 Moltbot — Personal AI Assistant # 🦞 Moltbot — Personal AI Assistant
<p align="center"> <p align="center">
<img src="/images/diagrams/30-hero-banner.png" alt="Moltbot — Your AI Agent, Everywhere You Message" width="800"> <img src="https://raw.githubusercontent.com/davendra/moltbot/main/docs/images/diagrams/30-hero-banner.png" alt="Moltbot — Your AI Agent, Everywhere You Message" width="800">
</p> </p>
<p align="center"> <p align="center">
@ -52,47 +52,7 @@ moltbot onboard --install-daemon
The wizard installs the Gateway daemon (launchd/systemd user service) so it stays running. The wizard installs the Gateway daemon (launchd/systemd user service) so it stays running.
Legacy note: `clawdbot` remains available as a compatibility shim. Legacy note: `clawdbot` remains available as a compatibility shim.
![Moltbot Architecture Overview](/images/diagrams/27-readme-architecture.png) ![Moltbot Architecture Overview](https://raw.githubusercontent.com/davendra/moltbot/main/docs/images/diagrams/27-readme-architecture.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## Quick start (TL;DR) ## Quick start (TL;DR)

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

@ -17,32 +17,6 @@ cron is the mechanism.
![Cron Job Execution Paths](/images/diagrams/09-cron-jobs.png) ![Cron Job Execution Paths](/images/diagrams/09-cron-jobs.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## TL;DR ## TL;DR
- Cron runs **inside the Gateway** (not inside the model). - Cron runs **inside the Gateway** (not inside the model).
- Jobs persist under `~/.clawdbot/cron/` so restarts don’t lose schedules. - Jobs persist under `~/.clawdbot/cron/` so restarts don’t lose schedules.

34
docs/automation/webhook.md
View File

@ -11,40 +11,6 @@ Gateway can expose a small HTTP webhook endpoint for external triggers.
![Webhook Processing Flow](/images/diagrams/10-webhook.png) ![Webhook Processing Flow](/images/diagrams/10-webhook.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## Enable ## Enable
```json5 ```json5

24
docs/broadcast-groups.md
View File

@ -19,30 +19,6 @@ Current scope: **WhatsApp only** (web channel).
![Broadcast Group Flow](/images/diagrams/14-broadcast.png) ![Broadcast Group Flow](/images/diagrams/14-broadcast.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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]
```
</details>
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). 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 ## Use Cases

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

@ -15,27 +15,6 @@ wired end-to-end.
![Agent Loop Lifecycle](/images/diagrams/02-agent-loop.png) ![Agent Loop Lifecycle](/images/diagrams/02-agent-loop.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## Entry points ## Entry points
- Gateway RPC: `agent` and `agent.wait`. - Gateway RPC: `agent` and `agent.wait`.
- CLI: `agent` command. - CLI: `agent` command.
@ -105,46 +84,6 @@ See [Plugins](/plugin#plugin-hooks) for the hook API and registration details.
![Plugin Hooks Lifecycle](/images/diagrams/20-plugin-hooks.png) ![Plugin Hooks Lifecycle](/images/diagrams/20-plugin-hooks.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## Streaming + partial replies ## Streaming + partial replies
- Assistant deltas are streamed from pi-agent-core and emitted as `assistant` events. - 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`. - Block streaming can emit partial replies either on `text_end` or `message_end`.

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

@ -11,46 +11,6 @@ file tools and for workspace context. Keep it private and treat it as memory.
![Agent Workspace Structure](/images/diagrams/26-workspace.png) ![Agent Workspace Structure](/images/diagrams/26-workspace.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
This is separate from `~/.clawdbot/`, which stores config, credentials, and This is separate from `~/.clawdbot/`, which stores config, credentials, and
sessions. sessions.

44
docs/concepts/architecture.md
View File

@ -23,50 +23,6 @@ Last updated: 2026-01-22
![Architecture Overview](/images/diagrams/01-architecture.png) ![Architecture Overview](/images/diagrams/01-architecture.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
### Gateway (daemon) ### Gateway (daemon)
- Maintains provider connections. - Maintains provider connections.
- Exposes a typed WS API (requests, responses, server‑push events). - Exposes a typed WS API (requests, responses, server‑push events).

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

@ -53,28 +53,6 @@ The matched agent determines which workspace and session store are used.
![Channel Routing Priority Cascade](/images/diagrams/05-channel-routing.png) ![Channel Routing Priority Cascade](/images/diagrams/05-channel-routing.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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]
```
</details>
## Broadcast groups (run multiple agents) ## 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). 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).
@ -95,24 +73,6 @@ See: [Broadcast Groups](/broadcast-groups).
![Broadcast vs Normal Routing](/images/diagrams/29-broadcast-vs-normal.png) ![Broadcast vs Normal Routing](/images/diagrams/29-broadcast-vs-normal.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## Config overview ## Config overview
- `agents.list`: named agent definitions (workspace, model, etc.). - `agents.list`: named agent definitions (workspace, model, etc.).

21
docs/concepts/compaction.md
View File

@ -10,27 +10,6 @@ Every model has a **context window** (max tokens it can see). Long-running chats
![Context Compaction Flow](/images/diagrams/11-compaction.png) ![Context Compaction Flow](/images/diagrams/11-compaction.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## What compaction is ## 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: 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 - The compaction summary

33
docs/concepts/memory.md
View File

@ -11,39 +11,6 @@ source of truth; the model only "remembers" what gets written to disk.
![Memory Organization](/images/diagrams/12-memory.png) ![Memory Organization](/images/diagrams/12-memory.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
Memory search tools are provided by the active memory plugin (default: Memory search tools are provided by the active memory plugin (default:
`memory-core`). Disable memory plugins with `plugins.slots.memory = "none"`. `memory-core`). Disable memory plugins with `plugins.slots.memory = "none"`.

29
docs/concepts/messages.md
View File

@ -22,35 +22,6 @@ Inbound message
![Message Processing Flow](/images/diagrams/03-message-flow.png) ![Message Processing Flow](/images/diagrams/03-message-flow.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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]
```
</details>
Key knobs live in configuration: Key knobs live in configuration:
- `messages.*` for prefixes, queueing, and group behavior. - `messages.*` for prefixes, queueing, and group behavior.
- `agents.defaults.*` for block streaming and chunking defaults. - `agents.defaults.*` for block streaming and chunking defaults.

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

@ -15,30 +15,6 @@ This doc explains the runtime rules and the data that backs them.
![Model Failover Decision Tree](/images/diagrams/17-model-failover.png) ![Model Failover Decision Tree](/images/diagrams/17-model-failover.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## Auth storage (keys + OAuth) ## Auth storage (keys + OAuth)
Moltbot uses **auth profiles** for both API keys and OAuth tokens. Moltbot uses **auth profiles** for both API keys and OAuth tokens.

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

@ -11,35 +11,6 @@ Goal: multiple *isolated* agents (separate workspace + `agentDir` + sessions), p
![Multi-Agent Isolation](/images/diagrams/06-multi-agent.png) ![Multi-Agent Isolation](/images/diagrams/06-multi-agent.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## What is "one agent"? ## What is "one agent"?
An **agent** is a fully scoped brain with its own: An **agent** is a fully scoped brain with its own:

52
docs/concepts/queue.md
View File

@ -9,32 +9,6 @@ We serialize inbound auto-reply runs (all channels) through a tiny in-process qu
![Lane-Aware FIFO Queue](/images/diagrams/07-queue-lanes.png) ![Lane-Aware FIFO Queue](/images/diagrams/07-queue-lanes.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## Why ## Why
- Auto-reply runs can be expensive (LLM calls) and can collide when multiple inbound messages arrive close together. - 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. - Serializing avoids competing for shared resources (session files, logs, CLI stdin) and reduces the chance of upstream rate limits.
@ -57,32 +31,6 @@ Inbound messages can steer the current run, wait for a followup turn, or do both
![Queue Modes State Machine](/images/diagrams/08-queue-modes.png) ![Queue Modes State Machine](/images/diagrams/08-queue-modes.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
Steer-backlog means you can get a followup response after the steered run, so 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 streaming surfaces can look like duplicates. Prefer `collect`/`steer` if you want
one response per inbound message. one response per inbound message.

20
docs/concepts/session.md
View File

@ -9,26 +9,6 @@ Moltbot treats **one direct-chat session per agent** as primary. Direct chats co
![Session Lifecycle](/images/diagrams/28-session-lifecycle.png) ![Session Lifecycle](/images/diagrams/28-session-lifecycle.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
Use `session.dmScope` to control how **direct messages** are grouped: Use `session.dmScope` to control how **direct messages** are grouped:
- `main` (default): all DMs share the main session for continuity. - `main` (default): all DMs share the main session for continuity.
- `per-peer`: isolate by sender id across channels. - `per-peer`: isolate by sender id across channels.

28
docs/concepts/streaming.md
View File

@ -15,34 +15,6 @@ There is **no real token streaming** to external channel messages today. Telegra
![Streaming Delivery Paths](/images/diagrams/13-streaming.png) ![Streaming Delivery Paths](/images/diagrams/13-streaming.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## Block streaming (channel messages) ## Block streaming (channel messages)
Block streaming sends assistant output in coarse chunks as it becomes available. Block streaming sends assistant output in coarse chunks as it becomes available.

32
docs/gateway/index.md
View File

@ -12,24 +12,6 @@ Last updated: 2025-12-09
![Gateway Lifecycle States](/images/diagrams/23-gateway-lifecycle.png) ![Gateway Lifecycle States](/images/diagrams/23-gateway-lifecycle.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
- Replaces the legacy `gateway` command. CLI entry point: `moltbot gateway`. - Replaces the legacy `gateway` command. CLI entry point: `moltbot gateway`.
- Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it. - Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.
@ -45,20 +27,6 @@ pnpm gateway:watch
``` ```
![Config Hot-Reload](/images/diagrams/24-hot-reload.png) ![Config Hot-Reload](/images/diagrams/24-hot-reload.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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]
```
</details>
- Config hot reload watches `~/.clawdbot/moltbot.json` (or `CLAWDBOT_CONFIG_PATH`). - Config hot reload watches `~/.clawdbot/moltbot.json` (or `CLAWDBOT_CONFIG_PATH`).
- Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical). - Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical).
- Hot reload uses in-process restart via **SIGUSR1** when needed. - Hot reload uses in-process restart via **SIGUSR1** when needed.

30
docs/gateway/protocol.md
View File

@ -20,36 +20,6 @@ handshake time.
![Gateway WebSocket Protocol](/images/diagrams/04-ws-protocol.png) ![Gateway WebSocket Protocol](/images/diagrams/04-ws-protocol.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## Handshake (connect) ## Handshake (connect)
Gateway → Client (pre-connect challenge): Gateway → Client (pre-connect challenge):

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

@ -39,39 +39,6 @@ Start with the smallest access that still works, then widen it as you gain confi
![Three-Layer Security Model](/images/diagrams/15-security.png) ![Three-Layer Security Model](/images/diagrams/15-security.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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]
```
</details>
### What the audit checks (high level) ### What the audit checks (high level)
- **Inbound access** (DM policies, group policies, allowlists): can strangers trigger the bot? - **Inbound access** (DM policies, group policies, allowlists): can strangers trigger the bot?

24
docs/install/index.md
View File

@ -11,30 +11,6 @@ Use the installer unless you have a reason not to. It sets up the CLI and runs o
![Installation Decision Tree](/images/diagrams/25-install.png) ![Installation Decision Tree](/images/diagrams/25-install.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## Quick install (recommended) ## Quick install (recommended)
```bash ```bash

28
docs/plugin.md
View File

@ -114,34 +114,6 @@ wins and lower-precedence copies are ignored.
![Plugin Discovery Precedence](/images/diagrams/19-plugin-discovery.png) ![Plugin Discovery Precedence](/images/diagrams/19-plugin-discovery.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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]
```
</details>
### Package packs ### Package packs
A plugin directory may include a `package.json` with `moltbot.extensions`: A plugin directory may include a `package.json` with `moltbot.extensions`:

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

@ -13,24 +13,6 @@ Goal: go from **zero** → **first working chat** (with sane defaults) as quickl
![Getting Started: Onboarding Wizard](/images/diagrams/22-onboarding.png) ![Getting Started: Onboarding Wizard](/images/diagrams/22-onboarding.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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']
```
</details>
Fastest chat: open the Control UI (no channel setup needed). Run `moltbot dashboard` 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. 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). Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui).

28
docs/start/pairing.md
View File

@ -16,34 +16,6 @@ It is used in two places:
![Pairing Flows](/images/diagrams/16-pairing.png) ![Pairing Flows](/images/diagrams/16-pairing.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
Security context: [Security](/gateway/security) Security context: [Security](/gateway/security)
## 1) DM pairing (inbound chat access) ## 1) DM pairing (inbound chat access)

23
docs/tools/browser.md
View File

@ -323,29 +323,6 @@ you swap local/remote browsers and profiles.
![Browser Automation Flow](/images/diagrams/21-browser.png) ![Browser Automation Flow](/images/diagrams/21-browser.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## CLI quick reference ## CLI quick reference
All commands accept `--browser-profile <name>` to target a specific profile. All commands accept `--browser-profile <name>` to target a specific profile.

54
docs/tools/index.md
View File

@ -13,60 +13,6 @@ and the agent should rely on them directly.
![Tool Groups](/images/diagrams/18-tool-groups.png) ![Tool Groups](/images/diagrams/18-tool-groups.png)
<details>
<summary>Diagram source (Mermaid)</summary>
```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
```
</details>
## Disabling tools ## Disabling tools
You can globally allow/deny tools via `tools.allow` / `tools.deny` in `moltbot.json` You can globally allow/deny tools via `tools.allow` / `tools.deny` in `moltbot.json`