# 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.