diff --git a/docs/channels/imessage.md b/docs/channels/imessage.md index c4fa867f1bb..fc11b5c05dd 100644 --- a/docs/channels/imessage.md +++ b/docs/channels/imessage.md @@ -172,17 +172,38 @@ If the Gateway runs on a Linux host/VM but iMessage must run on a Mac, Tailscale Architecture: +

+```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 ``` -┌──────────────────────────────┐ 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 -``` +

Concrete config example (Tailscale hostname): diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md index d8c7404b895..d9965f2dea8 100644 --- a/docs/concepts/architecture.md +++ b/docs/concepts/architecture.md @@ -55,22 +55,42 @@ Protocol details: ## Connection lifecycle (single client) +

+```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} ``` -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}) - | | -``` +

## Wire protocol (summary) diff --git a/docs/gateway/remote-gateway-readme.md b/docs/gateway/remote-gateway-readme.md index 0447a93b1b6..0640c1fc971 100644 --- a/docs/gateway/remote-gateway-readme.md +++ b/docs/gateway/remote-gateway-readme.md @@ -10,25 +10,44 @@ OpenClaw.app uses SSH tunneling to connect to a remote gateway. This guide shows ## Overview +

+```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 ``` -┌─────────────────────────────────────────────────────────────┐ -│ Client Machine │ -│ │ -│ OpenClaw.app ──► ws://127.0.0.1:18789 (local port) │ -│ │ │ -│ ▼ │ -│ SSH Tunnel ────────────────────────────────────────────────│ -│ │ │ -└─────────────────────┼──────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ Remote Machine │ -│ │ -│ Gateway WebSocket ──► ws://127.0.0.1:18789 ──► │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` +

## Quick Setup diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index d8df55b0a93..904b536b9cd 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -797,22 +797,35 @@ Commit the updated `.secrets.baseline` once it reflects the intended state. ## The Trust Hierarchy +

+```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[" "] + + F:::Class_transparent_box + classDef Class_transparent_box fill:transparent, stroke:transparent ``` -Owner (Peter) - │ Full trust - ▼ -AI (Clawd) - │ Trust but verify - ▼ -Friends in allowlist - │ Limited trust - ▼ -Strangers - │ No trust - ▼ -Mario asking for find ~ - │ Definitely no trust 😏 -``` +

## Reporting Security Issues diff --git a/docs/start/openclaw.md b/docs/start/openclaw.md index 27b45fc87e6..4518a9fdca4 100644 --- a/docs/start/openclaw.md +++ b/docs/start/openclaw.md @@ -33,20 +33,29 @@ Start conservative: You want this: +

+```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"] ``` -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 │ - └─────────────────┘ -``` +

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