76 lines
5.3 KiB
Markdown
76 lines
5.3 KiB
Markdown
# 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.
|