Files

T

mwandJunie a28a4a049b docs: bump OpenClaw node version to 2026.3.28 and align remote maintenance docs

- Update OpenClaw version references from 2026.3.13 to 2026.3.28 in README.md, docs/OPENCLAW_ARCHITECTURE.md, and gateway_plugins.txt.
- Remove outdated MacOS maintenance instructions (log rotation, credential syncing) from remote luca project.
- Redirect remote luca documentation to explicitly refer back to the mw-macbook-pro repository for MacOS-specific routines.
- Updated CHANGELOG to reflect version bump and cross-repo document alignments.
- Removed completed implementation plan.

Co-authored-by: Junie <junie@jetbrains.com>

2026-03-30 17:08:57 +02:00

3.5 KiB

Raw Blame History

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.

3.5 KiB Raw Blame History