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: Handled natively by /Applications/OpenClaw.app
• Command: ssh -N -L 18789:127.0.0.1:18789 -p 2222 root@100.64.0.39
• How it works:
  1. The MacBook Companion App 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:127.0.0.1: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 port (18789).

C. Layer 3: WebSocket Node Connection

• Service: OpenClaw.app Mac Companion App
• How it works:
  1. The node process runs embedded within the Companion App.
  2. It uses the provided SSH tunnel transparently based on the settings in ~/.openclaw/openclaw.json.
  3. It authenticates using the stored remote token.

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.

5. Maintenance Delegation

Note: Specific maintenance and configuration tasks associated with this Mac node—including credentials rotation for tools running here, app updates (OpenClaw.app), tunnel configuration, and Mac-based logs (newsyslog)—are explicitly delegated to this project repository (mw-macbook-pro) and the remote operator logged in via ssh MWsatwareAG@100.64.0.12. These responsibilities have been intentionally removed from the Manjaro server's maintenance purview to ensure proper separation of concerns.

6. Companion App Configuration (UI Settings)

The macOS OpenClaw Companion App must be configured with specific settings in the "General" tab:

• Target Mode: Remote (another host)
• Transport Protocol: SSH tunnel
• SSH Target: root@100.64.0.39:2222 (Tailscale IP of Luca, port 2222 bypassing host into Docker)
• Gateway Token: Must be populated with the shared token.

Feature Approvals: The following UI toggles must be Enabled for full capability:

• Allow Canvas: For displaying agent outputs.
• Allow Camera: For agent visual inputs.
• Enable Peekaboo Bridge: Critical for native UI automation and vision extraction.
• Enable debug tools: Essential for local troubleshooting.

7. VLM Prompting Strategy (Qwen 3.5 9B / Qwen-VL)

When utilizing Vision Language Models (VLMs) like Qwen 3.5 9B via the gateway to analyze Mac UIs (e.g., screenshots gathered from Peekaboo), the following strategies are required to mitigate hallucinations:

1. Structured, Specificity-First Prompting: Request explicit, format-constrained outputs (e.g., "List every interactive element with its Type, Visible Text, and State") rather than generic descriptions.
2. Visual Prompts (Image Overlays): Ground the VLM's attention using bounding boxes or numbered circles over key UI regions before inference.
3. Contextual Grounding & Negative Constraints: Explicitly instruct the model to avoid guessing or inferring hidden functionality. Model must only describe physically visible elements.
4. Chain-of-Thought (CoT) Visual Reasoning: Require the model to spatially scan the image (e.g., top to bottom) before answering.
5. Few-Shot Examples: Provide example image-answer pairs demonstrating the exact desired structure to establish patterns and dramatically reduce hallucinated elements.