mw-macbook-pro/docs/OPENCLAW_ARCHITECTURE.md

OpenClaw Architecture: satware AG MacBook Pro Node

Hub-and-Spoke System

The satware AG MacBook Pro operates as a Remote Tool Node in a hub-and-spoke configuration, where the Hub (Gateway) resides inside a Docker container on the "Luca" Manjaro server.

1. Connection Chain (The "Extreme Details")

The connection from this MacBook to the gateway uses a multi-layered tunnel to ensure secure communications over the Tailscale network while bypassing various Docker isolation barriers.

A. Layer 1: Tailscale Mesh (IP: 100.64.0.x)

The underlying transport is the Tailscale mesh network. This MacBook (100.64.0.12) sees the Luca server at 100.64.0.39.

B. Layer 2: SSH Tunnel (Container Entry)

• Service: ai.openclaw.ssh-tunnel.plist
• Command: ssh -N -L 18789:172.18.0.2:18789 root@100.64.0.39 -p 2222
• How it works:
  1. The MacBook initiates an SSH connection to port 2222 on Luca's Tailscale IP. Port 2222 is the SSH server running inside the agent-zero Docker container.
  2. The -L 18789:172.18.0.2:18789 switch creates a local loopback listener on this MacBook (127.0.0.1:18789).
  3. Traffic sent to 127.0.0.1:18789 is forwarded through the encrypted SSH tunnel directly to the container's internal IP and port (172.18.0.2:18789).
  4. Since the SSH server is inside the container, 172.18.0.2 is the container's internal interface IP, which the OpenClaw gateway is listening on.

C. Layer 3: WebSocket Node Connection

• Service: ai.openclaw.node.plist
• Command: openclaw node run --host 127.0.0.1 --port 18789
• How it works:
  1. The node process starts on the MacBook.
  2. It connects to ws://127.0.0.1:18789. Because of the SSH tunnel above, this connects it to the remote gateway on Luca.
  3. It authenticates using the OPENCLAW_GATEWAY_TOKEN provided in the environment variables.

2. Component Layout

Component	Role	Runtime	Host
Gateway Hub	Primary agent orchestrator	Node.js (inside Docker)	Luca (Manjaro)
Node Runner	Secondary tool executor	Node.js (native)	MacBook Pro
Llama Server	LLM Inference (122B Qwen)	ROCm / HIP	evox2-js (AMD Strix Halo)

3. Permissions and Sandboxing

• Gateway Sandbox: Disabled (mode: off) inside the agent-zero container. The container is the security boundary.
• Node Permissions: The MacBook Node requires full disk access, accessibility, and screen recording permissions granted to the Node.js binary (located at /usr/local/opt/node/bin/node or cellar equivalent).
• Executive Approvals: Controlled on the Gateway side in openclaw-data/exec-approvals.json. The MacBook node is currently granted a set of allowed commands (see status in README).

4. Why 127.0.0.1?

The MacBook's node configures the gateway URL as ws://127.0.0.1:18789 because OpenClaw's security policy prohibits sending operator/node tokens over unencrypted (ws://) connections to remote IP addresses. However, 127.0.0.1 is considered "local" and always trusted. The SSH tunnel transparently wraps the local connection in encryption for its journey over the network.