From 24e9b23c4a78e0727782a84c70ac960c61327cde Mon Sep 17 00:00:00 2001 From: Suvin Nimnaka Date: Mon, 9 Feb 2026 20:57:27 +0530 Subject: [PATCH] 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> --- docs/channels/imessage.md | 39 +++++++++++++++----- docs/concepts/architecture.md | 48 ++++++++++++++++-------- docs/gateway/remote-gateway-readme.md | 53 ++++++++++++++++++--------- docs/gateway/security/index.md | 42 +++++++++++++-------- docs/start/openclaw.md | 33 ++++++++++------- 5 files changed, 144 insertions(+), 71 deletions(-) diff --git a/docs/channels/imessage.md b/docs/channels/imessage.md index c4fa867f1bb..296e5775f2c 100644 --- a/docs/channels/imessage.md +++ b/docs/channels/imessage.md @@ -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["Gateway host (Linux/VM)

openclaw gateway
channels.imessage.cliPath"] + Mac["Mac with Messages + imsg

Messages signed in
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): diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md index d8c7404b895..42017ab5e95 100644 --- a/docs/concepts/architecture.md +++ b/docs/concepts/architecture.md @@ -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
snapshot: presence + health + + Gateway-->>Client: event:presence + Gateway-->>Client: event:tick + + Client->>Gateway: req:agent + Gateway-->>Client: res:agent
ack {runId, status:"accepted"} + Gateway-->>Client: event:agent
(streaming) + Gateway-->>Client: res:agent
final {runId, status, summary} ``` ## Wire protocol (summary) diff --git a/docs/gateway/remote-gateway-readme.md b/docs/gateway/remote-gateway-readme.md index 0447a93b1b6..8fa9cd1f097 100644 --- a/docs/gateway/remote-gateway-readme.md +++ b/docs/gateway/remote-gateway-readme.md @@ -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 diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index d8df55b0a93..afb245ec708 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -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 diff --git a/docs/start/openclaw.md b/docs/start/openclaw.md index 27b45fc87e6..874a8d85c8e 100644 --- a/docs/start/openclaw.md +++ b/docs/start/openclaw.md @@ -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["Your Phone (personal)

Your WhatsApp
+1-555-YOU"] -- message --> B["Second Phone (assistant)

Assistant WA
+1-555-ASSIST"] + B -- linked via QR --> C["Your Mac (openclaw)

Pi agent"] ``` If you link your personal WhatsApp to OpenClaw, every message to you becomes “agent input”. That’s rarely what you want.