diff --git a/01-HOST-AND-NETWORK.md b/01-HOST-AND-NETWORK.md index 3a1172e..69eae05 100755 --- a/01-HOST-AND-NETWORK.md +++ b/01-HOST-AND-NETWORK.md @@ -11,7 +11,7 @@ The triad uses a minimum of two machines (PAI + OpenClaw), but the full pattern | Role | Variable | OS | Purpose | |------|----------|----|---------| | **PAI workstation** | `{PAI-machine}` | macOS | My home. Runs Claude Code, all PAI infrastructure, orchestrates everything. | -| **OpenClaw host** | `{OpenClaw-machine}` | Ubuntu 24.04 | Dedicated to `{OpenClaw-agent}`. All compute reserved for the GPT agent. | +| **OpenClaw host** | `{OpenClaw-machine}` | macOS | Dedicated to `{OpenClaw-agent}`. All compute reserved for the GPT agent. | | **Services host** | `{services-machine}` | Linux (VM or bare-metal) | Docker services: reverse proxy, file sharing, fleet dashboard. Services evolve — document current stack in VARIABLES.md. | | **Worker node** | `{worker-machine}` | macOS | Parallel delegation target. Receives compute jobs from `{PAI-machine}`. | | **Hypervisor** | `{hypervisor-machine}` | Proxmox (optional) | Hosts `{services-machine}` as a VM. Only needed if you virtualize. | @@ -131,7 +131,7 @@ Syncthing provides real-time, peer-to-peer file synchronization over LAN. I use | Folder Name | Path on Hub | Synced With | Direction | Purpose | |------------|-------------|-------------|-----------|---------| -| `PAI-{OpenClaw-suffix}` | `~/{Sync-OpenClaw-dir}` | `{OpenClaw-machine}` | Bidirectional | File exchange + soul docs | +| `PAI-orphu` | `~/PAI-orphu` | `{OpenClaw-machine}` | Bidirectional | File exchange + soul docs | | `PAI-{worker-suffix}` | `~/{Sync-worker-dir}` | `{worker-machine}` | Bidirectional | Job dispatch + output retrieval | | `PAI-{services-suffix}` | `~/{Sync-services-dir}` | `{services-machine}` | Bidirectional | Service config exchange | | `PAI` | `~/PAI` | `{services-machine}` | Send only | Framework backup (read-only mirror) | @@ -170,47 +170,17 @@ systemctl --user start syncthing ## OpenClaw Machine — Platform-Specific Configuration -`{OpenClaw-machine}` runs Ubuntu 24.04 dedicated to `{OpenClaw-agent}`. A few Linux-specific settings ensure reliable headless operation: +`{OpenClaw-machine}` runs macOS dedicated to `{OpenClaw-agent}`. -**macOS alternative:** If `{OpenClaw-machine}` runs macOS instead of Linux, the concepts are identical but tooling differs: use Homebrew instead of apt, launchd instead of systemd, and `brew services` instead of `systemctl`. The guide documents the Linux path as it's more common for dedicated agent hosts, but macOS works equally well. +### Gateway Access -### Prevent Lid-Close Suspend +The OpenClaw gateway is configured for loopback-only access to preserve the security boundary. -If using a laptop as the OpenClaw host, disable suspend on lid close: +- **Bind:** `127.0.0.1` +- **Port:** `18790` +- **Dashboard:** `http://127.0.0.1:18790/` -``` -# /etc/systemd/logind.conf -HandleLidSwitch=ignore -HandleLidSwitchExternalPower=ignore -HandleLidSwitchDocked=ignore -``` - -Then: `sudo systemctl restart systemd-logind` - -### Network (Headless Ethernet) - -For a headless server installation, you may prefer systemd-networkd + netplan. If running Ubuntu Desktop, NetworkManager works fine — skip this section. Example netplan config: - -```yaml -# /etc/netplan/01-ethernet.yaml -network: - version: 2 - renderer: networkd - ethernets: - {ethernet-interface}: - dhcp4: true - # Or static: - # addresses: [{OpenClaw-LAN-IP}/24] - # routes: - # - to: default - # via: {gateway-IP} -``` - -Apply: `sudo netplan apply` - -### Disk Encryption - -Consider LUKS full-disk encryption for the OpenClaw machine, especially if it's a repurposed laptop. This protects `{OpenClaw-agent}`'s data at rest if the machine is lost or stolen. +Access from `{PAI-machine}` is typically brokered via the agentic communication layer or SSH tunneling if manual dashboard access is required. --- diff --git a/04-BACKUP-AND-RECOVERY.md b/04-BACKUP-AND-RECOVERY.md index 349481c..2360914 100755 --- a/04-BACKUP-AND-RECOVERY.md +++ b/04-BACKUP-AND-RECOVERY.md @@ -377,34 +377,29 @@ Four scenarios, ordered by likelihood. Each includes the steps to get back to op ## OpenClaw Backup Specifics -`{OpenClaw-agent}`'s state is spread across several locations on `{OpenClaw-machine}`. My backup script captures all of them into a single timestamped archive: +`{OpenClaw-agent}`'s state is backed up using the native `openclaw backup` command. This captures everything required to restore the agent's state into a single timestamped archive. -### What the Backup Script Captures +### What is Captured -| Component | Path | Why It Matters | -|-----------|------|---------------| -| OpenClaw configuration | `{OpenClaw-config-dir}` | Agent settings, gateway config, API keys | -| systemd service files | `~/.config/systemd/user/` | Service definitions for gateway, bot, tasks | -| SSH authorized keys | `~/.ssh/authorized_keys` | Allows `{PAI-machine}` to connect | -| Soul documents | `{soul-docs-dir}` | Agent identity, personality, behavioral rules | -| Scheduled tasks | Crontab or systemd timers | Recurring jobs the agent runs | +The `openclaw backup create` command includes: +- **Workspace:** `{OpenClaw-workspace-dir}` (usually `~/clawd`) +- **State:** `{OpenClaw-config-dir}` (usually `~/.openclaw`) containing credentials, sessions, and configuration. -### Archive Format +### LaunchAgent Configuration (macOS) -``` -openclaw-backup-YYYY-MM-DD-HHMMSS.tar.gz -``` +The backup is scheduled via a user LaunchAgent: + +- **Label:** `com.ccfleet.openclaw-backup` +- **Schedule:** Sunday at 03:15 weekly. +- **Command:** `openclaw backup create --output ~/Backups --verify` -### Where It Goes +### Retention -The archive is written to `{Sync-OpenClaw-dir}/backups/` on `{OpenClaw-machine}`. Because `{Sync-OpenClaw-dir}` is a bidirectional Syncthing folder, the archive automatically syncs to `{PAI-machine}`. This means I always have a copy of `{OpenClaw-agent}`'s backup on my own machine, even if `{OpenClaw-machine}` dies. +The LaunchAgent also handles cleanup, deleting any `*.tar.gz` files in `~/Backups` older than 28 days. -### When to Run +### Syncing -- **Before any OpenClaw update** (new version, config change) -- **Before any OS change** (system update, package upgrade) -- **Periodically** via cron or systemd timer (daily recommended) -- **Before hardware changes** (moving to new machine, disk swap) +The `~/Backups` directory should be configured as a Syncthing folder (or nested within one) to ensure distributed copies exist across the triad. --- diff --git a/05-COMMUNICATION-PROTOCOLS.md b/05-COMMUNICATION-PROTOCOLS.md index 991c784..944c167 100755 --- a/05-COMMUNICATION-PROTOCOLS.md +++ b/05-COMMUNICATION-PROTOCOLS.md @@ -55,15 +55,19 @@ When `{principal}` is away from the terminal, I can still reach them. I send a m ### Channel 3: `{principal}` to `{OpenClaw-agent}` (Mobile via Telegram) -This channel is independent of me. `{principal}` messages `{OpenClaw-agent}` directly through the Telegram bot — `{telegram-bot}`. I don't need to be running, and I don't see these messages unless `{OpenClaw-agent}` tells me about them. +This channel is independent of me. `{principal}` messages `{OpenClaw-agent}` directly through the Telegram bot. Access is restricted via a pairing/allowlist policy to ensure only authorized operators can trigger the agent. **How it works:** -- `{principal}` opens Telegram and messages `{telegram-bot}` -- `{OpenClaw-agent}` receives the message through its Telegram bot integration -- `{OpenClaw-agent}` processes it and responds directly in the Telegram chat +- `{principal}` opens Telegram and messages the bot. +- `{OpenClaw-agent}` verifies the sender ID against the allowlist (`groupAllowFrom` / `dmPolicy=pairing`). +- `{OpenClaw-agent}` processes it and responds directly in the Telegram chat. **Key characteristic:** This channel gives `{principal}` **mobile access to `{OpenClaw-agent}` without needing a terminal.** It's the phone-in-pocket interface to the triad. +**Heartbeat:** +- The agent is configured to send a **heartbeat every 60 minutes**. +- Heartbeats are delivered to the primary Telegram group (e.g., topic 8) using model `{Heartbeat-model}`. + **Primary uses:** - `{principal}` querying `{OpenClaw-agent}` from their phone - Quick checks ("What's the server status?") @@ -74,24 +78,24 @@ This channel is independent of me. `{principal}` messages `{OpenClaw-agent}` dir ### Channel 4: File Exchange (Syncthing) -Some things don't fit through a WebSocket message — large files, images, datasets, configuration archives. For these, I use the bidirectional Syncthing folder `{Sync-OpenClaw-dir}`. +Some things don't fit through a WebSocket message — large files, images, datasets, configuration archives. For these, I use the bidirectional Syncthing folder `~/PAI-orphu`. **How it works:** -- I write a file to `{Sync-OpenClaw-dir}` on `{PAI-machine}` -- Syncthing detects the change and pushes it to `{OpenClaw-machine}` -- `{OpenClaw-agent}` finds the file in its local copy of the shared folder -- The reverse works identically for files `{OpenClaw-agent}` sends to me +- I write a file to `~/PAI-orphu` on `{PAI-machine}`. +- Syncthing detects the change and pushes it to `{OpenClaw-machine}`. +- `{OpenClaw-agent}` finds the file in its local copy of the shared folder. +- The reverse works identically for files `{OpenClaw-agent}` sends to me. **Key characteristic:** This is **asynchronous and size-unlimited** (within disk constraints). Near-instant on LAN, slight delay over Tailscale. Files persist until explicitly cleaned up. -**Structured directories within `{Sync-OpenClaw-dir}`:** +**Structured directories within `~/PAI-orphu`:** | Directory | Purpose | Direction | |-----------|---------|-----------| -| `to-{OpenClaw-agent-lowercase}/` | Files I send to `{OpenClaw-agent}` | `{PAI-agent}` -> `{OpenClaw-agent}` | -| `from-{OpenClaw-agent-lowercase}/` | Files `{OpenClaw-agent}` sends to me | `{OpenClaw-agent}` -> `{PAI-agent}` | -| `backups/` | OpenClaw backup archives | `{OpenClaw-agent}` -> `{PAI-agent}` | -| `shared/` | Shared reference materials | Bidirectional | +| `to-orphu/` | Files I send to `{OpenClaw-agent}` | `{PAI-agent}` -> `{OpenClaw-agent}` | +| `from-orphu/` | Files `{OpenClaw-agent}` sends to me | `{OpenClaw-agent}` -> `{PAI-agent}` | +| `clawd/backups/` | OpenClaw backup archives | `{OpenClaw-agent}` -> `{PAI-agent}` | +| `clawd/shared/` | Shared reference materials | Bidirectional | **Primary uses:** - Sending large artifacts (generated files, images, datasets) diff --git a/07-OPENCLAW-APPENDIX.md b/07-OPENCLAW-APPENDIX.md index c2a978d..d7603a7 100755 --- a/07-OPENCLAW-APPENDIX.md +++ b/07-OPENCLAW-APPENDIX.md @@ -6,48 +6,42 @@ ## Section 1: Machine Preparation -`{OpenClaw-machine}` should be a dedicated Linux host. A repurposed laptop works well — all compute goes to `{OpenClaw-agent}`. +`{OpenClaw-machine}` should be a dedicated host. A repurposed macOS machine (e.g., ccmini4) works well — all compute goes to `{OpenClaw-agent}`. -**Base OS:** Ubuntu 24.04 LTS (server or desktop, headless operation either way) +**Base OS:** macOS (latest stable) **Post-install essentials:** -```bash -sudo apt update && sudo apt upgrade -y -sudo apt install -y git curl wget build-essential \ - openssh-server ufw jq htop tmux fontconfig ripgrep -``` +- Homebrew +- Xcode Command Line Tools +- git, curl, ripgrep, jq, tmux -**Node.js (via nvm):** +**Node.js (via nvm or brew):** ```bash -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash -source ~/.bashrc -nvm install 22 # Pin to OpenClaw's recommended Node major version +brew install nvm +nvm install 25 # Pin to current working version ``` **pnpm (required — OpenClaw uses pnpm, not npm):** ```bash -corepack enable -corepack prepare pnpm@latest --activate -# If the repo specifies a packageManager version, match it +brew install pnpm ``` **Headless configuration:** -- Disable lid-close suspend (see 01-HOST-AND-NETWORK.md) +- Disable sleep on lid close / system sleep - Configure static IP or DHCP reservation -- Enable SSH: `sudo systemctl enable ssh` -- Configure firewall: `sudo ufw allow ssh && sudo ufw enable` +- Enable SSH: System Settings → General → Sharing → Remote Login --- ## Section 2: OpenClaw Installation -OpenClaw is installed from source, not as a global npm package: +OpenClaw is installed from source: ```bash cd ~ git clone https://github.com/openclaw/openclaw.git {OpenClaw-install-dir} cd {OpenClaw-install-dir} -git checkout v{OpenClaw-version} # Use latest stable tag +git checkout v2026.3.13 # Current stable pnpm install pnpm build ``` @@ -164,15 +158,13 @@ Telegram gives `{principal}` mobile access to `{OpenClaw-agent}` independent of ## Section 6: Local Embeddings -For semantic search and memory, `{OpenClaw-agent}` can run embeddings locally instead of calling a cloud API. +For semantic search and memory, `{OpenClaw-agent}` can run embeddings locally or use a cloud API. -**Setup:** -- OpenClaw supports local embedding models via node-llama-cpp -- Configure in `{OpenClaw-config-dir}/openclaw.json`: set embeddings provider to `local` and specify the model (e.g., a GGUF-quantized embedding model) -- Models download on first use — this can take time. If interrupted, clear any `.ipull` files in the model cache directory and restart the gateway -- Model cache location: typically within `{OpenClaw-config-dir}/` or a system-level cache directory +**Current Configuration:** +- The triad is currently configured to use **Gemini** embeddings for memory search. +- Local embedding models (via node-llama-cpp) may be present in `~/.node-llama-cpp/` but are currently secondary to the Gemini backend. -**Provider evolution:** The embedding backend may change between OpenClaw versions. Check `{OpenClaw-config-dir}/openclaw.json` under the `memorySearch` key for the current provider configuration. Options include node-llama-cpp (local GGUF models), Gemini/memory-core (Google API), or cloud embedding providers. +**Provider evolution:** The embedding backend may change between OpenClaw versions. Check `{OpenClaw-config-dir}/openclaw.json` under the `memorySearch` key for the current provider configuration. **Benefits:** - No API costs for embeddings diff --git a/VARIABLES.md b/VARIABLES.md index fd8b41f..49c89a2 100755 --- a/VARIABLES.md +++ b/VARIABLES.md @@ -49,7 +49,7 @@ Variables use `{Title-Case-Hyphenated}` format. If you see one in any guide file | `{worker-LAN-IP}` | Worker machine LAN address | `10.x.x.x` | | `{hypervisor-LAN-IP}` | Hypervisor LAN address | `10.x.x.x` | | `{LAN-subnet}` | Network subnet (CIDR) | `10.x.x.0/24` | -| `{gateway-port}` | OpenClaw gateway port | `18789` | +| `{gateway-port}` | OpenClaw gateway port | `18790` | --- @@ -143,7 +143,7 @@ Variables use `{Title-Case-Hyphenated}` format. If you see one in any guide file | `{PAI-version}` | PAI framework version | `4.0.3` | | `{Algorithm-version}` | Algorithm version | `v3.5.0` | | `{PAI-repo}` | PAI source repository | `github.com/danielmiessler/PAI` | -| `{OpenClaw-version}` | OpenClaw version tag | Date-based (e.g., `2026.3.13`) | +| `{OpenClaw-version}` | OpenClaw version tag | `2026.3.13` | ---