mirror of
https://github.com/moltbot/moltbot.git
synced 2026-03-07 22:44:16 +00:00
Replace text diagrams with mermaid (#7165)
* Replace text diagrams with mermaid * Fix review comments * Remove newlines * docs: fix mermaid prep blockers (#7165) --------- Co-authored-by: Sebastian <19554889+sebslight@users.noreply.github.com>
This commit is contained in:
Suvin Nimnaka
@@ -172,16 +172,35 @@ If the Gateway runs on a Linux host/VM but iMessage must run on a Mac, Tailscale
|
||||
|
||||
Architecture:
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐ SSH (imsg rpc) ┌──────────────────────────┐
|
||||
│ Gateway host (Linux/VM) │──────────────────────────────────▶│ Mac with Messages + imsg │
|
||||
│ - openclaw gateway │ SCP (attachments) │ - Messages signed in │
|
||||
│ - channels.imessage.cliPath │◀──────────────────────────────────│ - Remote Login enabled │
|
||||
└──────────────────────────────┘ └──────────────────────────┘
|
||||
▲
|
||||
│ Tailscale tailnet (hostname or 100.x.y.z)
|
||||
▼
|
||||
user@gateway-host
|
||||
```mermaid
|
||||
%%{init: {
|
||||
'theme': 'base',
|
||||
'themeVariables': {
|
||||
'primaryColor': '#ffffff',
|
||||
'primaryTextColor': '#000000',
|
||||
'primaryBorderColor': '#000000',
|
||||
'lineColor': '#000000',
|
||||
'secondaryColor': '#f9f9fb',
|
||||
'tertiaryColor': '#ffffff',
|
||||
'clusterBkg': '#f9f9fb',
|
||||
'clusterBorder': '#000000',
|
||||
'nodeBorder': '#000000',
|
||||
'mainBkg': '#ffffff',
|
||||
'edgeLabelBackground': '#ffffff'
|
||||
}
|
||||
}}%%
|
||||
flowchart TB
|
||||
subgraph T[" "]
|
||||
subgraph Tailscale[" "]
|
||||
direction LR
|
||||
Gateway["<b>Gateway host (Linux/VM)<br></b><br>openclaw gateway<br>channels.imessage.cliPath"]
|
||||
Mac["<b>Mac with Messages + imsg<br></b><br>Messages signed in<br>Remote Login enabled"]
|
||||
end
|
||||
Gateway -- SSH (imsg rpc) --> Mac
|
||||
Mac -- SCP (attachments) --> Gateway
|
||||
direction BT
|
||||
User["user@gateway-host"] -- "Tailscale tailnet (hostname or 100.x.y.z)" --> Gateway
|
||||
end
|
||||
```
|
||||
|
||||
Concrete config example (Tailscale hostname):
|
||||
|
||||
@@ -55,21 +55,39 @@ Protocol details:
|
||||
|
||||
## Connection lifecycle (single client)
|
||||
|
||||
```
|
||||
Client Gateway
|
||||
| |
|
||||
|---- req:connect -------->|
|
||||
|<------ res (ok) ---------| (or res error + close)
|
||||
| (payload=hello-ok carries snapshot: presence + health)
|
||||
| |
|
||||
|<------ event:presence ---|
|
||||
|<------ event:tick -------|
|
||||
| |
|
||||
|------- req:agent ------->|
|
||||
|<------ res:agent --------| (ack: {runId,status:"accepted"})
|
||||
|<------ event:agent ------| (streaming)
|
||||
|<------ res:agent --------| (final: {runId,status,summary})
|
||||
| |
|
||||
```mermaid
|
||||
%%{init: {
|
||||
'theme': 'base',
|
||||
'themeVariables': {
|
||||
'primaryColor': '#ffffff',
|
||||
'primaryTextColor': '#000000',
|
||||
'primaryBorderColor': '#000000',
|
||||
'lineColor': '#000000',
|
||||
'secondaryColor': '#f9f9fb',
|
||||
'tertiaryColor': '#ffffff',
|
||||
'clusterBkg': '#f9f9fb',
|
||||
'clusterBorder': '#000000',
|
||||
'nodeBorder': '#000000',
|
||||
'mainBkg': '#ffffff',
|
||||
'edgeLabelBackground': '#ffffff'
|
||||
}
|
||||
}}%%
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant Gateway
|
||||
|
||||
Client->>Gateway: req:connect
|
||||
Gateway-->>Client: res (ok)
|
||||
Note right of Gateway: or res error + close
|
||||
Note left of Client: payload=hello-ok<br>snapshot: presence + health
|
||||
|
||||
Gateway-->>Client: event:presence
|
||||
Gateway-->>Client: event:tick
|
||||
|
||||
Client->>Gateway: req:agent
|
||||
Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
|
||||
Gateway-->>Client: event:agent<br>(streaming)
|
||||
Gateway-->>Client: res:agent<br>final {runId, status, summary}
|
||||
```
|
||||
|
||||
## Wire protocol (summary)
|
||||
|
||||
@@ -10,24 +10,41 @@ OpenClaw.app uses SSH tunneling to connect to a remote gateway. This guide shows
|
||||
|
||||
## Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Client Machine │
|
||||
│ │
|
||||
│ OpenClaw.app ──► ws://127.0.0.1:18789 (local port) │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ SSH Tunnel ────────────────────────────────────────────────│
|
||||
│ │ │
|
||||
└─────────────────────┼──────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Remote Machine │
|
||||
│ │
|
||||
│ Gateway WebSocket ──► ws://127.0.0.1:18789 ──► │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```mermaid
|
||||
%%{init: {
|
||||
'theme': 'base',
|
||||
'themeVariables': {
|
||||
'primaryColor': '#ffffff',
|
||||
'primaryTextColor': '#000000',
|
||||
'primaryBorderColor': '#000000',
|
||||
'lineColor': '#000000',
|
||||
'secondaryColor': '#f9f9fb',
|
||||
'tertiaryColor': '#ffffff',
|
||||
'clusterBkg': '#f9f9fb',
|
||||
'clusterBorder': '#000000',
|
||||
'nodeBorder': '#000000',
|
||||
'mainBkg': '#ffffff',
|
||||
'edgeLabelBackground': '#ffffff'
|
||||
}
|
||||
}}%%
|
||||
flowchart TB
|
||||
subgraph Client["Client Machine"]
|
||||
direction TB
|
||||
A["OpenClaw.app"]
|
||||
B["ws://127.0.0.1:18789\n(local port)"]
|
||||
T["SSH Tunnel"]
|
||||
|
||||
A --> B
|
||||
B --> T
|
||||
end
|
||||
subgraph Remote["Remote Machine"]
|
||||
direction TB
|
||||
C["Gateway WebSocket"]
|
||||
D["ws://127.0.0.1:18789"]
|
||||
|
||||
C --> D
|
||||
end
|
||||
T --> C
|
||||
```
|
||||
|
||||
## Quick Setup
|
||||
|
||||
@@ -797,21 +797,33 @@ Commit the updated `.secrets.baseline` once it reflects the intended state.
|
||||
|
||||
## The Trust Hierarchy
|
||||
|
||||
```
|
||||
Owner (Peter)
|
||||
│ Full trust
|
||||
▼
|
||||
AI (Clawd)
|
||||
│ Trust but verify
|
||||
▼
|
||||
Friends in allowlist
|
||||
│ Limited trust
|
||||
▼
|
||||
Strangers
|
||||
│ No trust
|
||||
▼
|
||||
Mario asking for find ~
|
||||
│ Definitely no trust 😏
|
||||
```mermaid
|
||||
%%{init: {
|
||||
'theme': 'base',
|
||||
'themeVariables': {
|
||||
'primaryColor': '#ffffff',
|
||||
'primaryTextColor': '#000000',
|
||||
'primaryBorderColor': '#000000',
|
||||
'lineColor': '#000000',
|
||||
'secondaryColor': '#f9f9fb',
|
||||
'tertiaryColor': '#ffffff',
|
||||
'clusterBkg': '#f9f9fb',
|
||||
'clusterBorder': '#000000',
|
||||
'nodeBorder': '#000000',
|
||||
'mainBkg': '#ffffff',
|
||||
'edgeLabelBackground': '#ffffff'
|
||||
}
|
||||
}}%%
|
||||
flowchart TB
|
||||
A["Owner (Peter)"] -- Full trust --> B["AI (Clawd)"]
|
||||
B -- Trust but verify --> C["Friends in allowlist"]
|
||||
C -- Limited trust --> D["Strangers"]
|
||||
D -- No trust --> E["Mario asking for find ~"]
|
||||
E -- Definitely no trust 😏 --> F[" "]
|
||||
|
||||
%% The transparent box is needed to show the bottom-most label correctly
|
||||
F:::Class_transparent_box
|
||||
classDef Class_transparent_box fill:transparent, stroke:transparent
|
||||
```
|
||||
|
||||
## Reporting Security Issues
|
||||
|
||||
@@ -33,19 +33,26 @@ Start conservative:
|
||||
|
||||
You want this:
|
||||
|
||||
```
|
||||
Your Phone (personal) Second Phone (assistant)
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ Your WhatsApp │ ──────▶ │ Assistant WA │
|
||||
│ +1-555-YOU │ message │ +1-555-ASSIST │
|
||||
└─────────────────┘ └────────┬────────┘
|
||||
│ linked via QR
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Your Mac │
|
||||
│ (openclaw) │
|
||||
│ Pi agent │
|
||||
└─────────────────┘
|
||||
```mermaid
|
||||
%%{init: {
|
||||
'theme': 'base',
|
||||
'themeVariables': {
|
||||
'primaryColor': '#ffffff',
|
||||
'primaryTextColor': '#000000',
|
||||
'primaryBorderColor': '#000000',
|
||||
'lineColor': '#000000',
|
||||
'secondaryColor': '#f9f9fb',
|
||||
'tertiaryColor': '#ffffff',
|
||||
'clusterBkg': '#f9f9fb',
|
||||
'clusterBorder': '#000000',
|
||||
'nodeBorder': '#000000',
|
||||
'mainBkg': '#ffffff',
|
||||
'edgeLabelBackground': '#ffffff'
|
||||
}
|
||||
}}%%
|
||||
flowchart TB
|
||||
A["<b>Your Phone (personal)<br></b><br>Your WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Second Phone (assistant)<br></b><br>Assistant WA<br>+1-555-ASSIST"]
|
||||
B -- linked via QR --> C["<b>Your Mac (openclaw)<br></b><br>Pi agent"]
|
||||
```
|
||||
|
||||
If you link your personal WhatsApp to OpenClaw, every message to you becomes “agent input”. That’s rarely what you want.
|
||||
|
||||
Reference in New Issue
Block a user