forked from Selig/openclaw-skill
Initial commit: OpenClaw Skill Collection
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
This commit is contained in:
141
openclaw-knowhow-skill/docs/infrastructure/platforms/android.md
Normal file
141
openclaw-knowhow-skill/docs/infrastructure/platforms/android.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Android App
|
||||
|
||||
# Android App (Node)
|
||||
|
||||
## Support snapshot
|
||||
|
||||
* Role: companion node app (Android does not host the Gateway).
|
||||
* Gateway required: yes (run it on macOS, Linux, or Windows via WSL2).
|
||||
* Install: [Getting Started](/start/getting-started) + [Pairing](/gateway/pairing).
|
||||
* Gateway: [Runbook](/gateway) + [Configuration](/gateway/configuration).
|
||||
* Protocols: [Gateway protocol](/gateway/protocol) (nodes + control plane).
|
||||
|
||||
## System control
|
||||
|
||||
System control (launchd/systemd) lives on the Gateway host. See [Gateway](/gateway).
|
||||
|
||||
## Connection Runbook
|
||||
|
||||
Android node app ⇄ (mDNS/NSD + WebSocket) ⇄ **Gateway**
|
||||
|
||||
Android connects directly to the Gateway WebSocket (default `ws://<host>:18789`) and uses Gateway-owned pairing.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
* You can run the Gateway on the "master" machine.
|
||||
* Android device/emulator can reach the gateway WebSocket:
|
||||
* Same LAN with mDNS/NSD, **or**
|
||||
* Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or**
|
||||
* Manual gateway host/port (fallback)
|
||||
* You can run the CLI (`openclaw`) on the gateway machine (or via SSH).
|
||||
|
||||
### 1) Start the Gateway
|
||||
|
||||
```bash
|
||||
openclaw gateway --port 18789 --verbose
|
||||
```
|
||||
|
||||
Confirm in logs you see something like:
|
||||
|
||||
* `listening on ws://0.0.0.0:18789`
|
||||
|
||||
For tailnet-only setups (recommended for Vienna ⇄ London), bind the gateway to the tailnet IP:
|
||||
|
||||
* Set `gateway.bind: "tailnet"` in `~/.openclaw/openclaw.json` on the gateway host.
|
||||
* Restart the Gateway / macOS menubar app.
|
||||
|
||||
### 2) Verify discovery (optional)
|
||||
|
||||
From the gateway machine:
|
||||
|
||||
```bash
|
||||
dns-sd -B _openclaw-gw._tcp local.
|
||||
```
|
||||
|
||||
More debugging notes: [Bonjour](/gateway/bonjour).
|
||||
|
||||
#### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
|
||||
|
||||
Android NSD/mDNS discovery won't cross networks. If your Android node and the gateway are on different networks but connected via Tailscale, use Wide-Area Bonjour / unicast DNS-SD instead:
|
||||
|
||||
1. Set up a DNS-SD zone (example `openclaw.internal.`) on the gateway host and publish `_openclaw-gw._tcp` records.
|
||||
2. Configure Tailscale split DNS for your chosen domain pointing at that DNS server.
|
||||
|
||||
Details and example CoreDNS config: [Bonjour](/gateway/bonjour).
|
||||
|
||||
### 3) Connect from Android
|
||||
|
||||
In the Android app:
|
||||
|
||||
* The app keeps its gateway connection alive via a **foreground service** (persistent notification).
|
||||
* Open **Settings**.
|
||||
* Under **Discovered Gateways**, select your gateway and hit **Connect**.
|
||||
* If mDNS is blocked, use **Advanced → Manual Gateway** (host + port) and **Connect (Manual)**.
|
||||
|
||||
After the first successful pairing, Android auto-reconnects on launch:
|
||||
|
||||
* Manual endpoint (if enabled), otherwise
|
||||
* The last discovered gateway (best-effort).
|
||||
|
||||
### 4) Approve pairing (CLI)
|
||||
|
||||
On the gateway machine:
|
||||
|
||||
```bash
|
||||
openclaw nodes pending
|
||||
openclaw nodes approve <requestId>
|
||||
```
|
||||
|
||||
Pairing details: [Gateway pairing](/gateway/pairing).
|
||||
|
||||
### 5) Verify the node is connected
|
||||
|
||||
* Via nodes status:
|
||||
```bash
|
||||
openclaw nodes status
|
||||
```
|
||||
* Via Gateway:
|
||||
```bash
|
||||
openclaw gateway call node.list --params "{}"
|
||||
```
|
||||
|
||||
### 6) Chat + history
|
||||
|
||||
The Android node's Chat sheet uses the gateway's **primary session key** (`main`), so history and replies are shared with WebChat and other clients:
|
||||
|
||||
* History: `chat.history`
|
||||
* Send: `chat.send`
|
||||
* Push updates (best-effort): `chat.subscribe` → `event:"chat"`
|
||||
|
||||
### 7) Canvas + camera
|
||||
|
||||
#### Gateway Canvas Host (recommended for web content)
|
||||
|
||||
If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point the node at the Gateway canvas host.
|
||||
|
||||
Note: nodes use the standalone canvas host on `canvasHost.port` (default `18793`).
|
||||
|
||||
1. Create `~/.openclaw/workspace/canvas/index.html` on the gateway host.
|
||||
|
||||
2. Navigate the node to it (LAN):
|
||||
|
||||
```bash
|
||||
openclaw nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__openclaw__/canvas/"}'
|
||||
```
|
||||
|
||||
Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__openclaw__/canvas/`.
|
||||
|
||||
This server injects a live-reload client into HTML and reloads on file changes.
|
||||
The A2UI host lives at `http://<gateway-host>:18793/__openclaw__/a2ui/`.
|
||||
|
||||
Canvas commands (foreground only):
|
||||
|
||||
* `canvas.eval`, `canvas.snapshot`, `canvas.navigate` (use `{"url":""}` or `{"url":"/"}` to return to the default scaffold). `canvas.snapshot` returns `{ format, base64 }` (default `format="jpeg"`).
|
||||
* A2UI: `canvas.a2ui.push`, `canvas.a2ui.reset` (`canvas.a2ui.pushJSONL` legacy alias)
|
||||
|
||||
Camera commands (foreground only; permission-gated):
|
||||
|
||||
* `camera.snap` (jpg)
|
||||
* `camera.clip` (mp4)
|
||||
|
||||
See [Camera node](/nodes/camera) for parameters and CLI helpers.
|
||||
112
openclaw-knowhow-skill/docs/infrastructure/platforms/exe-dev.md
Normal file
112
openclaw-knowhow-skill/docs/infrastructure/platforms/exe-dev.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# exe.dev
|
||||
|
||||
Goal: OpenClaw Gateway running on an exe.dev VM, reachable from your laptop via: `https://<vm-name>.exe.xyz`
|
||||
|
||||
This page assumes exe.dev's default **exeuntu** image. If you picked a different distro, map packages accordingly.
|
||||
|
||||
## Beginner quick path
|
||||
|
||||
1. [https://exe.new/openclaw](https://exe.new/openclaw)
|
||||
2. Fill in your auth key/token as needed
|
||||
3. Click on "Agent" next to your VM, and wait...
|
||||
4. ???
|
||||
5. Profit
|
||||
|
||||
## What you need
|
||||
|
||||
* exe.dev account
|
||||
* `ssh exe.dev` access to [exe.dev](https://exe.dev) virtual machines (optional)
|
||||
|
||||
## Automated Install with Shelley
|
||||
|
||||
Shelley, [exe.dev](https://exe.dev)'s agent, can install OpenClaw instantly with our prompt. The prompt used is as below:
|
||||
|
||||
```
|
||||
Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-interactive and accept-risk flags for openclaw onboarding. Add the supplied auth or token as needed. Configure nginx to forward from the default port 18789 to the root location on the default enabled site config, making sure to enable Websocket support. Pairing is done by "openclaw devices list" and "openclaw device approve <request id>". Make sure the dashboard shows that OpenClaw's health is OK. exe.dev handles forwarding from port 8000 to port 80/443 and HTTPS for us, so the final "reachable" should be <vm-name>.exe.xyz, without port specification.
|
||||
```
|
||||
|
||||
## Manual installation
|
||||
|
||||
### 1) Create the VM
|
||||
|
||||
From your device:
|
||||
|
||||
```bash
|
||||
ssh exe.dev new
|
||||
```
|
||||
|
||||
Then connect:
|
||||
|
||||
```bash
|
||||
ssh <vm-name>.exe.xyz
|
||||
```
|
||||
|
||||
Tip: keep this VM **stateful**. OpenClaw stores state under `~/.openclaw/` and `~/.openclaw/workspace/`.
|
||||
|
||||
### 2) Install prerequisites (on the VM)
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y git curl jq ca-certificates openssl
|
||||
```
|
||||
|
||||
### 3) Install OpenClaw
|
||||
|
||||
Run the OpenClaw install script:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
### 4) Setup nginx to proxy OpenClaw to port 8000
|
||||
|
||||
Edit `/etc/nginx/sites-enabled/default` with
|
||||
|
||||
```
|
||||
server {
|
||||
listen 80 default_server;
|
||||
listen [::]:80 default_server;
|
||||
listen 8000;
|
||||
listen [::]:8000;
|
||||
|
||||
server_name _;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:18789;
|
||||
proxy_http_version 1.1;
|
||||
|
||||
# WebSocket support
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
|
||||
# Standard proxy headers
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# Timeout settings for long-lived connections
|
||||
proxy_read_timeout 86400s;
|
||||
proxy_send_timeout 86400s;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5) Access OpenClaw and grant privileges
|
||||
|
||||
Access `https://<vm-name>.exe.xyz/?token=YOUR-TOKEN-FROM-TERMINAL` (see the Control UI output from onboarding). Approve devices with `openclaw devices list` and `openclaw devices approve <requestId>`. When in doubt, use Shelley from your browser!
|
||||
|
||||
## Remote Access
|
||||
|
||||
Remote access is handled by [exe.dev](https://exe.dev)'s authentication. By default, HTTP traffic from port 8000 is forwarded to `https://<vm-name>.exe.xyz` with email auth.
|
||||
|
||||
## Updating
|
||||
|
||||
```bash
|
||||
npm i -g openclaw@latest
|
||||
openclaw doctor
|
||||
openclaw gateway restart
|
||||
openclaw health
|
||||
```
|
||||
|
||||
Guide: [Updating](/install/updating)
|
||||
56
openclaw-knowhow-skill/docs/infrastructure/platforms/fly.md
Normal file
56
openclaw-knowhow-skill/docs/infrastructure/platforms/fly.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# OpenClaw on Fly.io
|
||||
|
||||
## Overview
|
||||
|
||||
This guide enables deploying OpenClaw Gateway on Fly.io with persistent storage, automatic HTTPS, and multi-channel access (Discord, Telegram, etc.).
|
||||
|
||||
## Key Requirements
|
||||
|
||||
- flyctl CLI installation
|
||||
- Fly.io account (free tier eligible)
|
||||
- API credentials (Anthropic, OpenAI, etc.)
|
||||
- Channel tokens (Discord bot token, etc.)
|
||||
|
||||
## Core Setup Steps
|
||||
|
||||
### 1) App & Volume Creation
|
||||
|
||||
Clone the repository, create a Fly app, and establish a 1GB persistent volume in your preferred region (London, Virginia, or San Jose).
|
||||
|
||||
### 2) Configuration
|
||||
|
||||
The `fly.toml` file requires:
|
||||
|
||||
- `--bind lan` flag to expose the gateway to Fly's proxy
|
||||
- `--allow-unconfigured` to launch without initial config
|
||||
- Port 3000 binding for health checks
|
||||
- Minimum 2GB RAM allocation (512MB insufficient)
|
||||
|
||||
### 3) Security Setup
|
||||
|
||||
Set secrets via command line for gateway tokens, API keys, and channel credentials. Prefer env vars over config file for all API keys and tokens.
|
||||
|
||||
### 4) Deployment & Config
|
||||
|
||||
Deploy using `fly deploy`, then SSH into the machine to create `/data/openclaw.json` with agent, authentication, and channel bindings.
|
||||
|
||||
## Access Methods
|
||||
|
||||
- **Control UI**: Browser at `https://my-openclaw.fly.dev/`
|
||||
- **SSH Console**: `fly ssh console`
|
||||
- **Logs**: `fly logs` for monitoring
|
||||
|
||||
## Private Deployment Option
|
||||
|
||||
Use `fly.private.toml` for hardened deployments without public IP exposure, ideal for outbound-only use cases or webhook delivery via ngrok/Tailscale tunnels.
|
||||
|
||||
## Troubleshooting Highlights
|
||||
|
||||
- **Binding issues**: Ensure `--bind lan` in process command
|
||||
- **Memory errors**: Increase to 2GB minimum
|
||||
- **Lock file problems**: Remove `/data/gateway.*.lock`
|
||||
- **State persistence**: Verify `OPENCLAW_STATE_DIR=/data` configuration
|
||||
|
||||
## Estimated Cost
|
||||
|
||||
$10-15 monthly with recommended specifications.
|
||||
30
openclaw-knowhow-skill/docs/infrastructure/platforms/gcp.md
Normal file
30
openclaw-knowhow-skill/docs/infrastructure/platforms/gcp.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# OpenClaw on GCP Compute Engine
|
||||
|
||||
## Overview
|
||||
|
||||
This guide establishes a persistent OpenClaw Gateway on Google Cloud's Compute Engine using Docker, designed for reliable 24/7 operation at approximately $5-12 monthly.
|
||||
|
||||
## Key Setup Steps
|
||||
|
||||
The deployment process involves:
|
||||
|
||||
1. **GCP Project Configuration** - Create a project and enable the Compute Engine API
|
||||
2. **VM Provisioning** - Deploy a Debian 12 instance (e2-small recommended with 2 vCPU, 2GB RAM)
|
||||
3. **Docker Installation** - Set up containerization on the host system
|
||||
4. **Repository Cloning** - Obtain the OpenClaw codebase
|
||||
5. **Persistent Directories** - Create `~/.openclaw` and workspace folders for state preservation
|
||||
6. **Environment Configuration** - Define `.env` with tokens and credentials
|
||||
7. **Binary Baking** - Embed required tools (gog, goplaces, wacli) in the Docker image at build time
|
||||
8. **Container Launch** - Start the gateway service
|
||||
|
||||
## Critical Architecture Decision
|
||||
|
||||
Installing binaries inside a running container is a trap. Anything installed at runtime will be lost on restart. All external dependencies must be embedded during image construction via the Dockerfile.
|
||||
|
||||
## Access Method
|
||||
|
||||
The guide recommends SSH port forwarding rather than direct exposure: keep the Gateway loopback-only on the VM; access via SSH tunnel.
|
||||
|
||||
## State Persistence
|
||||
|
||||
Long-lived data (configurations, tokens, workspace artifacts) survives container restarts through host volume mounts, while the container itself remains ephemeral and rebuilable.
|
||||
@@ -0,0 +1,39 @@
|
||||
# OpenClaw on Hetzner: Production Docker VPS Setup
|
||||
|
||||
## Overview
|
||||
|
||||
This guide enables deploying OpenClaw Gateway on a Hetzner VPS using Docker, with persistent state and reliable restart behavior. The setup costs approximately $5/month and maintains 24/7 availability.
|
||||
|
||||
## Key Architecture Points
|
||||
|
||||
The deployment model separates ephemeral and durable components:
|
||||
|
||||
**Ephemeral (rebuilt on restart):**
|
||||
- Docker container and Node runtime
|
||||
- OS packages and external binaries
|
||||
|
||||
**Persistent (survives restarts):**
|
||||
- Gateway configuration at `/home/node/.openclaw/`
|
||||
- Model authentication profiles
|
||||
- Skill configurations
|
||||
- Agent workspace artifacts
|
||||
- WhatsApp session data
|
||||
- Gmail keyring (password-protected)
|
||||
|
||||
## Critical Setup Requirement
|
||||
|
||||
External binaries must be baked into the image during Docker build, not installed at runtime. Installing binaries in a running container causes data loss on restart. The Dockerfile should include all required CLI tools (gog, goplaces, wacli, etc.) via curl and tar extraction to `/usr/local/bin/`.
|
||||
|
||||
## Access Pattern
|
||||
|
||||
The Gateway runs on port 18789 bound to `127.0.0.1` for security. Access from your laptop requires an SSH tunnel:
|
||||
|
||||
```bash
|
||||
ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
|
||||
```
|
||||
|
||||
Then connect to `http://127.0.0.1:18789/` with your gateway token.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You'll need root SSH access, Docker/Docker Compose, model credentials, and about 20 minutes to complete the deployment.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Platforms
|
||||
|
||||
OpenClaw core is written in TypeScript. **Node is the recommended runtime**.
|
||||
Bun is not recommended for the Gateway (WhatsApp/Telegram bugs).
|
||||
|
||||
Companion apps exist for macOS (menu bar app) and mobile nodes (iOS/Android). Windows and
|
||||
Linux companion apps are planned, but the Gateway is fully supported today.
|
||||
Native companion apps for Windows are also planned; the Gateway is recommended via WSL2.
|
||||
|
||||
## Choose your OS
|
||||
|
||||
* macOS: [macOS](/platforms/macos)
|
||||
* iOS: [iOS](/platforms/ios)
|
||||
* Android: [Android](/platforms/android)
|
||||
* Windows: [Windows](/platforms/windows)
|
||||
* Linux: [Linux](/platforms/linux)
|
||||
|
||||
## VPS & hosting
|
||||
|
||||
* VPS hub: [VPS hosting](/vps)
|
||||
* Fly.io: [Fly.io](/platforms/fly)
|
||||
* Hetzner (Docker): [Hetzner](/platforms/hetzner)
|
||||
* GCP (Compute Engine): [GCP](/platforms/gcp)
|
||||
* exe.dev (VM + HTTPS proxy): [exe.dev](/platforms/exe-dev)
|
||||
|
||||
## Common links
|
||||
|
||||
* Install guide: [Getting Started](/start/getting-started)
|
||||
* Gateway runbook: [Gateway](/gateway)
|
||||
* Gateway configuration: [Configuration](/gateway/configuration)
|
||||
* Service status: `openclaw gateway status`
|
||||
|
||||
## Gateway service install (CLI)
|
||||
|
||||
Use one of these (all supported):
|
||||
|
||||
* Wizard (recommended): `openclaw onboard --install-daemon`
|
||||
* Direct: `openclaw gateway install`
|
||||
* Configure flow: `openclaw configure` → select **Gateway service**
|
||||
* Repair/migrate: `openclaw doctor` (offers to install or fix the service)
|
||||
|
||||
The service target depends on OS:
|
||||
|
||||
* macOS: LaunchAgent (`bot.molt.gateway` or `bot.molt.<profile>`; legacy `com.openclaw.*`)
|
||||
* Linux/WSL2: systemd user service (`openclaw-gateway[-<profile>].service`)
|
||||
38
openclaw-knowhow-skill/docs/infrastructure/platforms/ios.md
Normal file
38
openclaw-knowhow-skill/docs/infrastructure/platforms/ios.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# iOS App (Node)
|
||||
|
||||
## Overview
|
||||
|
||||
The iOS app connects to a Gateway via WebSocket, exposing node capabilities including Canvas rendering, screen snapshots, camera capture, location access, and voice features.
|
||||
|
||||
## Key Requirements
|
||||
|
||||
A Gateway must run on a separate device (macOS, Linux, or Windows via WSL2). Connection options include same-network Bonjour discovery, Tailnet via DNS-SD, or manual host/port entry.
|
||||
|
||||
## Setup Process
|
||||
|
||||
Users start the Gateway on port 18789, select it in iOS Settings, then approve the pairing request via command line. The `openclaw nodes status` command verifies successful connection.
|
||||
|
||||
## Discovery Methods
|
||||
|
||||
The system supports three connection approaches:
|
||||
|
||||
- **Bonjour**: Advertises `_openclaw-gw._tcp` on `local.` for LAN environments
|
||||
- **Tailnet**: Uses unicast DNS-SD for cross-network scenarios
|
||||
- **Manual**: Configuration as a fallback
|
||||
|
||||
## Canvas Functionality
|
||||
|
||||
The iOS node uses WKWebView for rendering. Users can navigate to URLs, execute JavaScript through `canvas.eval`, and capture snapshots using the node invocation system.
|
||||
|
||||
## Voice Capabilities
|
||||
|
||||
Voice wake and talk mode options appear in Settings, though background audio suspension may limit reliability when the app isn't active.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common issues include:
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` - Requires foreground app status
|
||||
- Missing canvas host configuration
|
||||
- Pairing prompts not appearing
|
||||
- Reconnection failures after reinstall due to cleared Keychain tokens
|
||||
@@ -0,0 +1,39 @@
|
||||
# Linux App
|
||||
|
||||
## Overview
|
||||
|
||||
OpenClaw's Gateway operates on Linux systems, with Node.js as the preferred runtime environment. Bun is not recommended for the Gateway (WhatsApp/Telegram bugs).
|
||||
|
||||
## Quick Start for VPS Users
|
||||
|
||||
The beginner pathway involves four primary steps:
|
||||
|
||||
1. Installing Node 22 or later
|
||||
2. Installing the OpenClaw package globally via npm
|
||||
3. Running the onboard command with daemon installation
|
||||
4. Establishing an SSH tunnel to access the interface locally
|
||||
|
||||
## Installation Options
|
||||
|
||||
Multiple installation approaches are available:
|
||||
|
||||
- Standard setup procedures
|
||||
- Experimental Bun support
|
||||
- Nix package manager integration
|
||||
- Containerized Docker deployment
|
||||
|
||||
## Service Management
|
||||
|
||||
OpenClaw implements systemd user services by default, though system-wide services suit shared or persistent server environments. The installation process offers three command variations for establishing the Gateway service, along with diagnostic and repair capabilities through the doctor command.
|
||||
|
||||
### Gateway service install options
|
||||
|
||||
- `openclaw onboard --install-daemon`
|
||||
- `openclaw gateway install`
|
||||
- `openclaw configure` (select Gateway service when prompted)
|
||||
|
||||
Use `openclaw doctor` to diagnose or repair installations.
|
||||
|
||||
## Configuration
|
||||
|
||||
A minimal systemd service unit requires specifying the Gateway startup command with port configuration, restart policies, and user-level enablement through systemctl commands.
|
||||
@@ -0,0 +1,29 @@
|
||||
# Gateway on macOS
|
||||
|
||||
## Overview
|
||||
|
||||
The OpenClaw macOS application has evolved to work with an external `openclaw` CLI installation rather than bundling its own runtime. The app manages Gateway operations through launchd services.
|
||||
|
||||
## Key Requirements
|
||||
|
||||
To use local mode, you must have Node 22+ on the Mac, then install `openclaw` globally via npm. The application provides an **Install CLI** button that automates this setup.
|
||||
|
||||
## LaunchAgent Configuration
|
||||
|
||||
The system uses launchd to maintain Gateway persistence:
|
||||
|
||||
- **Service Label**: `bot.molt.gateway` (or `bot.molt.<profile>` for custom profiles)
|
||||
- **Configuration Path**: `~/Library/LaunchAgents/bot.molt.gateway.plist`
|
||||
- **Manager**: The macOS app handles installation and updates in Local mode; the CLI also supports installation via `openclaw gateway install`
|
||||
|
||||
## Operational Behavior
|
||||
|
||||
App quit does **not** stop the gateway (launchd keeps it alive). If a Gateway instance already runs on your configured port, the application attaches to it instead of launching a new process. The "OpenClaw Active" toggle controls LaunchAgent activation.
|
||||
|
||||
## Logging and Diagnostics
|
||||
|
||||
Gateway output appears at `/tmp/openclaw/openclaw-gateway.log`. Version compatibility between the app and gateway CLI is verified automatically—mismatches require updating the global CLI installation.
|
||||
|
||||
## Verification Commands
|
||||
|
||||
Test your setup using provided smoke-check commands to validate Gateway functionality on port 18999.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Canvas
|
||||
|
||||
## Overview
|
||||
|
||||
The Canvas feature in OpenClaw is a lightweight visual workspace for HTML/CSS/JS, A2UI, and small interactive UI surfaces embedded in the macOS app using `WKWebView`.
|
||||
|
||||
## Key Storage & Access
|
||||
|
||||
Canvas files are stored in `~/Library/Application Support/OpenClaw/canvas/<session>/` and served through a custom `openclaw-canvas://` URL scheme that prevents directory traversal attacks.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
The agent can control Canvas through several operations:
|
||||
|
||||
- Display or hide the panel
|
||||
- Navigate to local paths or external URLs
|
||||
- Execute JavaScript commands
|
||||
- Generate snapshot images
|
||||
|
||||
## A2UI Integration
|
||||
|
||||
The system supports A2UI v0.8 server-to-client messages including `surfaceUpdate`, `dataModelUpdate`, and `deleteSurface`. The newer `createSurface` (v0.9) remains unsupported.
|
||||
|
||||
## Agent Triggering
|
||||
|
||||
Canvas content can initiate new agent runs using deep links formatted as `openclaw://agent?message=<text>`, with confirmation prompts unless a valid key is supplied.
|
||||
|
||||
## Security Features
|
||||
|
||||
Canvas scheme blocks directory traversal; files must live under the session root. External URLs require explicit navigation permissions.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Gateway Lifecycle on macOS
|
||||
|
||||
## Overview
|
||||
|
||||
The macOS application manages the Gateway through launchd rather than spawning it as a child process. It attempts to connect to an existing Gateway on the configured port; if unavailable, it enables the launchd service via the `openclaw` CLI.
|
||||
|
||||
## Default Behavior
|
||||
|
||||
The system installs a per-user LaunchAgent labeled `bot.molt.gateway` (or `bot.molt.<profile>` for named profiles). When Local mode is active, the app ensures this agent is loaded and starts the Gateway as needed. Log files are directed to the launchd gateway log path, accessible through Debug Settings.
|
||||
|
||||
Key management commands include:
|
||||
|
||||
```bash
|
||||
launchctl kickstart -k gui/$UID/bot.molt.gateway
|
||||
launchctl bootout gui/$UID/bot.molt.gateway
|
||||
```
|
||||
|
||||
## Development Builds
|
||||
|
||||
Unsigned development builds use `scripts/restart-mac.sh --no-sign` for rapid iteration. This prevents launchd from referencing an unsigned binary by creating `~/.openclaw/disable-launchagent`. Signed builds automatically clear this override.
|
||||
|
||||
## Connection Modes
|
||||
|
||||
**Attach-only mode** forces the app to skip launchd management entirely using the `--attach-only` flag, connecting only to already-running Gateways.
|
||||
|
||||
**Remote mode** bypasses local Gateway startup, instead establishing an SSH tunnel to a remote host.
|
||||
|
||||
## Design Rationale
|
||||
|
||||
The launchd approach provides:
|
||||
|
||||
- Automatic login startup
|
||||
- Built-in restart capabilities
|
||||
- Consistent logging and supervision patterns
|
||||
@@ -0,0 +1,75 @@
|
||||
# macOS Dev Setup
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The following tools are required:
|
||||
|
||||
1. **Xcode 26.2+**: Necessary for Swift development
|
||||
2. **Node.js 22+ & pnpm**: Required for the gateway, CLI, and packaging scripts
|
||||
|
||||
## 1. Install Dependencies
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## 2. Build and Package the App
|
||||
|
||||
To build the macOS app and package it into `dist/OpenClaw.app`, run:
|
||||
|
||||
```bash
|
||||
./scripts/package-mac-app.sh
|
||||
```
|
||||
|
||||
If you don't have an Apple Developer ID certificate, the script will automatically use ad-hoc signing instead.
|
||||
|
||||
For additional configuration options, see the apps/macos/README.md file in the repository.
|
||||
|
||||
> Ad-hoc signed apps may trigger security prompts. Immediate crashes with "Abort trap 6" are addressed in troubleshooting.
|
||||
|
||||
## 3. Install the CLI
|
||||
|
||||
The app requires a global `openclaw` CLI installation for background task management.
|
||||
|
||||
**To install:**
|
||||
|
||||
1. Open the OpenClaw app
|
||||
2. Navigate to the **General** settings tab
|
||||
3. Click **"Install CLI"**
|
||||
|
||||
Or manually install:
|
||||
|
||||
```bash
|
||||
npm install -g openclaw@<version>
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Fails: Toolchain or SDK Mismatch
|
||||
|
||||
Verify your toolchain versions:
|
||||
|
||||
```bash
|
||||
xcodebuild -version
|
||||
xcrun swift --version
|
||||
```
|
||||
|
||||
Update macOS and Xcode if versions don't align.
|
||||
|
||||
### App Crashes on Permission Grant
|
||||
|
||||
Reset TCC permissions:
|
||||
|
||||
```bash
|
||||
tccutil reset All bot.molt.mac.debug
|
||||
```
|
||||
|
||||
### Gateway "Starting..." Indefinitely
|
||||
|
||||
Check for zombie processes:
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw gateway stop
|
||||
lsof -nP -iTCP:18789 -sTCP:LISTEN
|
||||
```
|
||||
@@ -0,0 +1,42 @@
|
||||
# Health Checks on macOS
|
||||
|
||||
## Overview
|
||||
|
||||
This documentation explains monitoring linked channel health through the macOS menu bar application, including status indicators, settings, and diagnostic procedures.
|
||||
|
||||
## Key Features
|
||||
|
||||
### Status Indicator
|
||||
|
||||
The menu bar displays a colored dot reflecting channel health:
|
||||
|
||||
- **Green**: linked + socket opened recently
|
||||
- **Orange**: connecting/retrying
|
||||
- **Red**: logged out or probe failed
|
||||
|
||||
A secondary line shows authentication age or failure details.
|
||||
|
||||
### Settings Interface
|
||||
|
||||
The Health card within Settings displays:
|
||||
|
||||
- Linked authentication age
|
||||
- Session storage information
|
||||
- Last check timestamp
|
||||
|
||||
Users can manually trigger checks and access logs through dedicated buttons.
|
||||
|
||||
### Diagnostic Process
|
||||
|
||||
The system executes `openclaw health --json` approximately every 60 seconds and on-demand. This probe loads creds and reports status without sending messages, maintaining separate caches for successful and failed snapshots.
|
||||
|
||||
## Alternative Approaches
|
||||
|
||||
For additional troubleshooting, reference the Gateway health section. Recommended CLI commands include:
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw status --deep
|
||||
```
|
||||
|
||||
Review log files at `/tmp/openclaw/openclaw-*.log` for connection-related events.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Menu Bar Icon States
|
||||
|
||||
Author: steipete | Updated: 2025-12-06 | Scope: macOS app (`apps/macos`)
|
||||
|
||||
## Icon States
|
||||
|
||||
- **Idle:** Normal icon animation (blink, occasional wiggle).
|
||||
- **Paused:** Status item uses `appearsDisabled`; no motion.
|
||||
- **Voice trigger (big ears):** Voice wake detector calls `AppState.triggerVoiceEars(ttl: nil)` when the wake word is heard, keeping `earBoostActive=true` while the utterance is captured. Ears scale up (1.9x), get circular ear holes for readability, then drop via `stopVoiceEars()` after 1s of silence. Only fired from the in-app voice pipeline.
|
||||
- **Working (agent running):** `AppState.isWorking=true` drives a "tail/leg scurry" micro-motion: faster leg wiggle and slight offset while work is in-flight. Currently toggled around WebChat agent runs; add the same toggle around other long tasks when you wire them.
|
||||
|
||||
## Wiring Points
|
||||
|
||||
- **Voice wake:** Runtime/tester call `AppState.triggerVoiceEars(ttl: nil)` on trigger and `stopVoiceEars()` after 1s of silence to match the capture window.
|
||||
- **Agent activity:** Set `AppStateStore.shared.setWorking(true/false)` around work spans (already done in WebChat agent call). Keep spans short and reset in `defer` blocks to avoid stuck animations.
|
||||
|
||||
## Shapes & Sizes
|
||||
|
||||
- Base icon drawn in `CritterIconRenderer.makeIcon(blink:legWiggle:earWiggle:earScale:earHoles:)`.
|
||||
- Ear scale defaults to `1.0`; voice boost sets `earScale=1.9` and toggles `earHoles=true` without changing overall frame (18x18 pt template image rendered into a 36x36 px Retina backing store).
|
||||
- Scurry uses leg wiggle up to ~1.0 with a small horizontal jiggle; it's additive to any existing idle wiggle.
|
||||
|
||||
## Behavioral Notes
|
||||
|
||||
- No external CLI/broker toggle for ears/working; keep it internal to the app's own signals to avoid accidental flapping.
|
||||
- Keep TTLs short (<10s) so the icon returns to baseline quickly if a job hangs.
|
||||
@@ -0,0 +1,49 @@
|
||||
# macOS Logging
|
||||
|
||||
## Rolling Diagnostics File Log (Debug Pane)
|
||||
|
||||
OpenClaw routes macOS app logs through swift-log (unified logging by default) and can write a local, rotating file log to disk when you need a durable capture.
|
||||
|
||||
- **Verbosity**: Debug pane -> Logs -> App logging -> Verbosity
|
||||
- **Enable**: Debug pane -> Logs -> App logging -> "Write rolling diagnostics log (JSONL)"
|
||||
- **Location**: `~/Library/Logs/OpenClaw/diagnostics.jsonl` (rotates automatically; old files are suffixed with `.1`, `.2`, ...)
|
||||
- **Clear**: Debug pane -> Logs -> App logging -> "Clear"
|
||||
|
||||
### Notes
|
||||
|
||||
- This is **off by default**. Enable only while actively debugging.
|
||||
- Treat the file as sensitive; don't share it without review.
|
||||
|
||||
## Unified Logging Private Data on macOS
|
||||
|
||||
Unified logging redacts most payloads unless a subsystem opts into `privacy -off`. This is controlled by a plist in `/Library/Preferences/Logging/Subsystems/` keyed by the subsystem name. Only new log entries pick up the flag, so enable it before reproducing an issue.
|
||||
|
||||
## Enable for OpenClaw (`bot.molt`)
|
||||
|
||||
Write the plist to a temp file first, then install it atomically as root:
|
||||
|
||||
```bash
|
||||
cat <<'EOF' >/tmp/bot.molt.plist
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>DEFAULT-OPTIONS</key>
|
||||
<dict>
|
||||
<key>Enable-Private-Data</key>
|
||||
<true/>
|
||||
</dict>
|
||||
</dict>
|
||||
</plist>
|
||||
EOF
|
||||
sudo install -m 644 -o root -g wheel /tmp/bot.molt.plist /Library/Preferences/Logging/Subsystems/bot.molt.plist
|
||||
```
|
||||
|
||||
- No reboot is required; logd notices the file quickly, but only new log lines will include private payloads.
|
||||
- View the richer output with the existing helper, e.g. `./scripts/clawlog.sh --category WebChat --last 5m`.
|
||||
|
||||
## Disable After Debugging
|
||||
|
||||
- Remove the override: `sudo rm /Library/Preferences/Logging/Subsystems/bot.molt.plist`
|
||||
- Optionally run `sudo log config --reload` to force logd to drop the override immediately.
|
||||
- Remember this surface can include phone numbers and message bodies; keep the plist in place only while you actively need the extra detail.
|
||||
@@ -0,0 +1,53 @@
|
||||
# Menu Bar Status Logic
|
||||
|
||||
## Overview
|
||||
|
||||
This page documents how OpenClaw displays agent work state through menu bar indicators and status messaging.
|
||||
|
||||
## Key Display Features
|
||||
|
||||
The system surfaces current agent activity via:
|
||||
|
||||
- Menu bar icon reflecting work state
|
||||
- Status row showing session and activity information
|
||||
- Health status (visible only when idle)
|
||||
- Device list from paired nodes
|
||||
- Usage metrics when available from providers
|
||||
|
||||
## Session Management
|
||||
|
||||
Sessions receive events containing a `runId` and `sessionKey`. The "main" session takes priority—when active, it immediately displays in the menu. If main is idle, the most recently active non-main session appears instead, preventing constant switching during transitions.
|
||||
|
||||
## Activity Indicators
|
||||
|
||||
Two activity types generate status updates:
|
||||
|
||||
**Jobs** represent high-level command execution with states: started, streaming, done, or error.
|
||||
|
||||
**Tools** show operational phases (start/result) with associated metadata and arguments.
|
||||
|
||||
## Visual States
|
||||
|
||||
The icon system includes four states:
|
||||
|
||||
- **Idle**: Normal display
|
||||
- **Working main**: Full badge animation
|
||||
- **Working other**: Muted badge
|
||||
- **Overridden**: Debug mode
|
||||
|
||||
Activity kinds map to glyphs:
|
||||
|
||||
| Kind | Glyph |
|
||||
|------|-------|
|
||||
| exec | terminal |
|
||||
| read | document |
|
||||
| write | pencil |
|
||||
| edit | notepad |
|
||||
| attach | paperclip |
|
||||
| others | wrench |
|
||||
|
||||
## Status Labels
|
||||
|
||||
Active work displays as: `<Session role> - <activity label>` (e.g., "Main - exec: pnpm test").
|
||||
|
||||
The system labels activities by extracting command first lines, shortened file paths, and inferred change types from diffs.
|
||||
@@ -0,0 +1,50 @@
|
||||
# Peekaboo Bridge
|
||||
|
||||
## Overview
|
||||
|
||||
OpenClaw.app can function as a **PeekabooBridge host**, enabling UI automation through the `peekaboo` CLI while leveraging existing macOS app permissions.
|
||||
|
||||
## Key Capabilities
|
||||
|
||||
The system operates as a thin broker where:
|
||||
|
||||
- OpenClaw.app acts as the hosting service
|
||||
- The `peekaboo` command-line tool serves as the client interface
|
||||
- Visual overlays remain within Peekaboo.app rather than OpenClaw
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
To activate this feature, navigate to **Settings -> Enable Peekaboo Bridge** within the macOS application. Once enabled, OpenClaw initiates a local UNIX socket server; disabling it stops the host and causes `peekaboo` to revert to alternative available hosts.
|
||||
|
||||
## Host Discovery Sequence
|
||||
|
||||
Peekaboo clients attempt connection in this order:
|
||||
|
||||
1. Peekaboo.app (full user experience)
|
||||
2. Claude.app (if present)
|
||||
3. OpenClaw.app (broker alternative)
|
||||
|
||||
Check active hosts using:
|
||||
|
||||
```bash
|
||||
peekaboo bridge status --verbose
|
||||
```
|
||||
|
||||
Override socket path with:
|
||||
|
||||
```bash
|
||||
export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock
|
||||
```
|
||||
|
||||
## Security Features
|
||||
|
||||
The bridge validates caller code signatures; an allowlist of TeamIDs is enforced. Request timeouts are approximately 10 seconds. Missing permissions trigger error messages rather than prompting system dialogs.
|
||||
|
||||
## Snapshot Management
|
||||
|
||||
Snapshots exist temporarily in memory with automatic expiration. Re-capture snapshots when extended retention is needed.
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **Authorization errors**: Ensure proper code signing or enable `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` in debug mode
|
||||
- **No hosts detected**: Launch either Peekaboo.app or OpenClaw.app and verify permission grants
|
||||
@@ -0,0 +1,48 @@
|
||||
# macOS Permissions
|
||||
|
||||
## Overview
|
||||
|
||||
This documentation addresses macOS permission management through TCC (Transparency, Consent, and Control), explaining why permission grants can be unstable and how to resolve issues.
|
||||
|
||||
## Permission Stability Issues
|
||||
|
||||
TCC associates a permission grant with the app's code signature, bundle identifier, and on-disk path. Any changes to these elements cause macOS to treat the application as new, potentially removing previously granted permissions.
|
||||
|
||||
## Requirements for Reliable Permissions
|
||||
|
||||
- Applications must run from a consistent location
|
||||
- Bundle identifiers should remain unchanged
|
||||
- Apps must be properly signed (not ad-hoc signed)
|
||||
- Code signatures must be consistent across rebuilds using real Apple certificates
|
||||
|
||||
## Why Ad-Hoc Signing Fails
|
||||
|
||||
Ad-hoc signatures create new identities with each build, causing macOS to forget previous permission grants and potentially hiding permission prompts entirely.
|
||||
|
||||
## Troubleshooting Steps
|
||||
|
||||
The recovery process involves:
|
||||
|
||||
1. Quitting the app
|
||||
2. Removing it from System Settings privacy controls
|
||||
3. Relaunching it
|
||||
4. Re-granting permissions
|
||||
|
||||
### Using tccutil
|
||||
|
||||
Reset specific permission entries by bundle identifier:
|
||||
|
||||
```bash
|
||||
tccutil reset All bot.molt.mac.debug
|
||||
```
|
||||
|
||||
Or reset specific services:
|
||||
|
||||
```bash
|
||||
tccutil reset Accessibility bot.molt.mac.debug
|
||||
tccutil reset ScreenCapture bot.molt.mac.debug
|
||||
```
|
||||
|
||||
## Testing Recommendation
|
||||
|
||||
For permission testing, developers should use real certificates rather than ad-hoc signatures. Ad-hoc builds are acceptable for casual local testing where permissions aren't critical.
|
||||
@@ -0,0 +1,47 @@
|
||||
# macOS Release
|
||||
|
||||
## Overview
|
||||
|
||||
This page documents the process for releasing OpenClaw on macOS using Sparkle auto-updates. Release builds require Developer ID signing, packaging, and appcast publication.
|
||||
|
||||
## Key Requirements
|
||||
|
||||
The following prerequisites are required:
|
||||
|
||||
- A Developer ID Application certificate must be installed
|
||||
- The Sparkle private key path needs configuration via `SPARKLE_PRIVATE_KEY_FILE`
|
||||
- Notary credentials are required for Gatekeeper-safe distribution
|
||||
- `pnpm` dependencies must be installed
|
||||
- Sparkle tools are automatically fetched through SwiftPM
|
||||
|
||||
## Build Process
|
||||
|
||||
Developers should use specific scripts depending on their needs:
|
||||
|
||||
- `scripts/package-mac-app.sh` handles local and development packaging
|
||||
- `scripts/package-mac-dist.sh` creates release artifacts including zip files, disk images, and notarization
|
||||
|
||||
### Build Parameters
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `APP_BUILD` | Must be numeric + monotonic for Sparkle compare |
|
||||
| `APP_VERSION` | Semantic version string |
|
||||
| Architecture | Target CPU architecture specification |
|
||||
|
||||
## Appcast and Publishing
|
||||
|
||||
After building, generate appcast entries using:
|
||||
|
||||
```bash
|
||||
scripts/make_appcast.sh
|
||||
```
|
||||
|
||||
This creates formatted HTML release notes from the changelog.
|
||||
|
||||
### Final Steps
|
||||
|
||||
1. Upload assets to GitHub releases
|
||||
2. Verify that the appcast URL functions correctly
|
||||
3. Confirm package URLs are accessible
|
||||
4. Test the update flow end-to-end
|
||||
@@ -0,0 +1,53 @@
|
||||
# Remote Control
|
||||
|
||||
## Overview
|
||||
|
||||
OpenClaw's remote control capabilities allow a macOS app to function as a controller for an OpenClaw gateway on another host via SSH.
|
||||
|
||||
## Key Operational Modes
|
||||
|
||||
The system supports three operational approaches:
|
||||
|
||||
1. **Local execution** on the macOS device
|
||||
2. **Remote over SSH** (default) with port forwarding
|
||||
3. **Remote direct** using WebSocket connections without SSH tunneling
|
||||
|
||||
## Transport Options
|
||||
|
||||
Two transport mechanisms are available:
|
||||
|
||||
- **SSH tunneling**: Masks the client as localhost
|
||||
- **Direct WebSocket**: Exposes the actual client IP
|
||||
|
||||
## Setup Requirements
|
||||
|
||||
### Remote Host Requirements
|
||||
|
||||
- Node.js, pnpm, and the OpenClaw CLI installed
|
||||
- Accessible on the system PATH
|
||||
- SSH should use key-based authentication
|
||||
- Tailscale IPs recommended for reliable off-network access
|
||||
|
||||
### macOS App Configuration
|
||||
|
||||
1. Select transport type
|
||||
2. Specify the SSH target
|
||||
3. Optionally provide gateway URLs and identity file paths
|
||||
4. Use "Test remote" feature to validate connectivity
|
||||
|
||||
## Web Chat Integration
|
||||
|
||||
Web Chat operates through the same SSH tunnel or direct gateway connection depending on the selected transport method.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Use loopback bindings with either SSH or Tailscale for secure connections
|
||||
- Implement token/password authentication when binding to non-loopback interfaces
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common issues include:
|
||||
|
||||
- **Exit code 127**: PATH configuration problems
|
||||
- **SSH connectivity failures**: Check key authentication and host accessibility
|
||||
- **Port forwarding mismatches**: Verify WebSocket connection ports match configuration
|
||||
@@ -0,0 +1,35 @@
|
||||
# macOS Signing
|
||||
|
||||
## Overview
|
||||
|
||||
The macOS signing process for OpenClaw is automated through build scripts that handle code signing, bundle identification, and metadata injection.
|
||||
|
||||
## Key Components
|
||||
|
||||
**Main Script**: `scripts/package-mac-app.sh` orchestrates the packaging and signing workflow, requiring Node 22+ for TypeScript and Control UI builds.
|
||||
|
||||
**Signing Identity**: The process reads the `SIGN_IDENTITY` environment variable. Developers can configure a persistent signing certificate by exporting this value in their shell configuration.
|
||||
|
||||
## Core Functionality
|
||||
|
||||
The packaging script performs several tasks:
|
||||
|
||||
1. Establishes a stable debug bundle identifier (`ai.openclaw.mac.debug`)
|
||||
2. Updates Info.plist with the bundle identifier
|
||||
3. Invokes `codesign-mac-app.sh` to sign binaries and the app bundle
|
||||
4. Implements timestamping for Developer ID signatures (configurable via `CODESIGN_TIMESTAMP`)
|
||||
5. Injects build metadata (`OpenClawBuildTimestamp` and `OpenClawGitCommit`)
|
||||
6. Validates Team ID consistency across all Mach-O files
|
||||
|
||||
## Signing Options
|
||||
|
||||
| Option | Configuration |
|
||||
|--------|---------------|
|
||||
| Auto-selection | Run script without environment variables |
|
||||
| Production certificates | `SIGN_IDENTITY="Developer ID Application: Name"` |
|
||||
| Ad-hoc signing | `ALLOW_ADHOC_SIGNING=1` or `SIGN_IDENTITY="-"` |
|
||||
| Offline builds | `CODESIGN_TIMESTAMP=off` |
|
||||
|
||||
## Important Caveat
|
||||
|
||||
Ad-hoc signatures automatically disable the Hardened Runtime to prevent framework loading failures. This approach compromises TCC permission persistence between rebuilds.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Skills (macOS)
|
||||
|
||||
## Overview
|
||||
|
||||
The macOS application surfaces OpenClaw skills through a gateway rather than parsing them locally.
|
||||
|
||||
## Key Components
|
||||
|
||||
### Data Source
|
||||
|
||||
The system retrieves skill information via `skills.status` from the gateway, which provides all skills plus eligibility and missing requirements. Requirements come from the `metadata.openclaw.requires` field in skill markdown files.
|
||||
|
||||
### Installation Process
|
||||
|
||||
The `metadata.openclaw.install` property specifies available installation methods:
|
||||
|
||||
- brew
|
||||
- node
|
||||
- go
|
||||
- uv
|
||||
|
||||
When users initiate installation, the app invokes `skills.install` on the gateway host. The gateway prioritizes a single installer:
|
||||
|
||||
1. Prefers brew when available
|
||||
2. Otherwise uses the node package manager specified in `skills.install`
|
||||
3. Falls back to npm as the default
|
||||
|
||||
### Credential Management
|
||||
|
||||
API keys and environment variables are stored locally at `~/.openclaw/openclaw.json` under the `skills.entries.<skillKey>` path.
|
||||
|
||||
Configuration updates use the `skills.update` endpoint to modify:
|
||||
|
||||
- Enabled status
|
||||
- API keys
|
||||
- Environment settings
|
||||
|
||||
### Remote Configuration
|
||||
|
||||
Installation and configuration changes occur on the gateway host rather than the local machine, maintaining centralized management of skill deployment.
|
||||
@@ -0,0 +1,58 @@
|
||||
# Voice Overlay
|
||||
|
||||
## Overview
|
||||
|
||||
This documentation describes the macOS voice overlay lifecycle, designed to manage interactions between wake-word detection and push-to-talk functionality.
|
||||
|
||||
## Key Design Principle
|
||||
|
||||
The system ensures predictable behavior when wake-word and push-to-talk overlap. If the overlay is already visible from wake-word and the user presses the hotkey, the hotkey session *adopts* the existing text instead of resetting it.
|
||||
|
||||
## Core Implementation (as of Dec 9, 2025)
|
||||
|
||||
The architecture uses three main components:
|
||||
|
||||
### 1. VoiceSessionCoordinator
|
||||
|
||||
Acts as a single-session owner managing token-based API calls:
|
||||
|
||||
- `beginWakeCapture`
|
||||
- `beginPushToTalk`
|
||||
- `endCapture`
|
||||
|
||||
### 2. VoiceSession
|
||||
|
||||
Model carrying session metadata including:
|
||||
|
||||
- Token
|
||||
- Source (wakeWord | pushToTalk)
|
||||
- Committed/volatile text
|
||||
- Chime flags
|
||||
- Timers (auto-send, idle)
|
||||
|
||||
### 3. VoiceSessionPublisher
|
||||
|
||||
SwiftUI integration that mirrors the active session into SwiftUI without direct singleton mutations.
|
||||
|
||||
## Behavior Details
|
||||
|
||||
- **Wake-word alone**: Auto-sends on silence
|
||||
- **Push-to-talk**: Sends immediately upon release, can wait up to 1.5s for a final transcript before falling back to the current text
|
||||
|
||||
## Debugging Support
|
||||
|
||||
Stream logs using:
|
||||
|
||||
```bash
|
||||
sudo log stream --predicate 'subsystem == "bot.molt" AND category CONTAINS "voicewake"'
|
||||
```
|
||||
|
||||
## Migration Path
|
||||
|
||||
Implementation follows five sequential steps:
|
||||
|
||||
1. Add core components
|
||||
2. Wire VoiceSessionCoordinator
|
||||
3. Integrate VoiceSession model
|
||||
4. Connect VoiceSessionPublisher to SwiftUI
|
||||
5. Integration testing for session adoption and cooldown behavior
|
||||
@@ -0,0 +1,54 @@
|
||||
# Voice Wake & Push-to-Talk
|
||||
|
||||
## Overview
|
||||
|
||||
The Voice Wake feature operates in two modes: wake-word (always-on with trigger detection) and push-to-talk (immediate capture via right Option key hold).
|
||||
|
||||
## Key Operating Modes
|
||||
|
||||
### Wake-word Mode
|
||||
|
||||
Functions as the default, with the speech recognizer continuously listening for specified trigger tokens. Upon detection, it:
|
||||
|
||||
1. Initiates capture
|
||||
2. Displays an overlay with partial transcription
|
||||
3. Automatically sends after detecting silence
|
||||
|
||||
### Push-to-talk Mode
|
||||
|
||||
Activates immediately when users hold the right Option key—no trigger word necessary. The overlay remains visible during the hold and processes the audio after release.
|
||||
|
||||
## Technical Architecture
|
||||
|
||||
### VoiceWakeRuntime
|
||||
|
||||
Manages the speech recognizer, requiring approximately 0.55 seconds of meaningful pause between trigger word and command.
|
||||
|
||||
### Silence Detection
|
||||
|
||||
- 2.0-second windows during active speech
|
||||
- 5.0-second windows if only the trigger was detected
|
||||
- Hard 120-second limit per session
|
||||
|
||||
### Overlay Implementation
|
||||
|
||||
Uses `VoiceWakeOverlayController` with committed and volatile text states. A critical improvement prevents the "sticky overlay" failure mode where manual dismissal could halt listening—the runtime no longer blocks on overlay visibility, and closing the overlay triggers automatic restart.
|
||||
|
||||
## User Configuration
|
||||
|
||||
Available settings include:
|
||||
|
||||
- Toggle Voice Wake on/off
|
||||
- Enable push-to-talk (Cmd+Fn hold, macOS 26+)
|
||||
- Language selection
|
||||
- Microphone selection with persistent preferences
|
||||
- Customizable audio cues (Glass sound by default, or any NSSound-compatible file)
|
||||
|
||||
## Message Routing
|
||||
|
||||
Transcripts forward to the active gateway using the app's configured local or remote mode, with replies delivered to the previously-used primary provider:
|
||||
|
||||
- WhatsApp
|
||||
- Telegram
|
||||
- Discord
|
||||
- WebChat
|
||||
@@ -0,0 +1,48 @@
|
||||
# WebChat
|
||||
|
||||
## Overview
|
||||
|
||||
The macOS menu bar application integrates WebChat as a native SwiftUI component, connecting to the Gateway with support for both local and remote operation modes.
|
||||
|
||||
## Key Features
|
||||
|
||||
### Connection Modes
|
||||
|
||||
- **Local mode**: Links directly to the local Gateway WebSocket
|
||||
- **Remote mode**: Tunnels the Gateway control port through SSH
|
||||
|
||||
### Session Management
|
||||
|
||||
The app defaults to the main session for the selected agent (with a session switcher for other sessions). Onboarding operates through a separate dedicated session.
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Data Plane
|
||||
|
||||
The system uses Gateway WebSocket methods:
|
||||
|
||||
- `chat.history`
|
||||
- `chat.send`
|
||||
- `chat.abort`
|
||||
- `chat.inject`
|
||||
|
||||
Corresponding events for:
|
||||
|
||||
- Chat
|
||||
- Agent
|
||||
- Presence
|
||||
- Tick
|
||||
- Health monitoring
|
||||
|
||||
### Launch Options
|
||||
|
||||
Access through multiple methods:
|
||||
|
||||
- Lobster menu -> "Open Chat"
|
||||
- Testing launch: `dist/OpenClaw.app/Contents/MacOS/OpenClaw --webchat`
|
||||
- Logging via `./scripts/clawlog.sh` (subsystem `bot.molt`, WebChatSwiftUI category)
|
||||
|
||||
## Security & Constraints
|
||||
|
||||
- Remote mode restricts forwarding to the Gateway WebSocket control port only
|
||||
- The interface is optimized for chat sessions (not a full browser sandbox)
|
||||
@@ -0,0 +1,49 @@
|
||||
# macOS IPC
|
||||
|
||||
## Overview
|
||||
|
||||
OpenClaw's macOS architecture uses a local Unix socket connecting a node host service to the macOS app for execution approvals and system commands. A debug CLI tool (`openclaw-mac`) supports discovery and connection checks.
|
||||
|
||||
## Key Architecture Components
|
||||
|
||||
### Primary Goal
|
||||
|
||||
Maintain a single GUI app instance that handles all TCC-related operations while minimizing the automation surface area.
|
||||
|
||||
### System Layers
|
||||
|
||||
The system operates through three main layers:
|
||||
|
||||
#### 1. Gateway + Node Transport
|
||||
|
||||
The application runs the Gateway locally and connects as a node, executing agent actions via `node.invoke` for commands like `system.run` and `system.notify`.
|
||||
|
||||
#### 2. IPC Layer
|
||||
|
||||
A headless node service connects to the Gateway WebSocket, forwarding `system.run` requests to the macOS app through a local Unix socket with security measures:
|
||||
|
||||
- Tokens
|
||||
- HMAC validation
|
||||
- TTL
|
||||
|
||||
#### 3. UI Automation
|
||||
|
||||
PeekabooBridge operates on a separate socket (`bridge.sock`), following a preference hierarchy:
|
||||
|
||||
1. Peekaboo.app
|
||||
2. Claude.app
|
||||
3. OpenClaw.app
|
||||
4. Local execution
|
||||
|
||||
## Security Considerations
|
||||
|
||||
Protection mechanisms include:
|
||||
|
||||
- Socket permissions set to `0600`
|
||||
- Peer UID verification checks
|
||||
- HMAC-based challenge/response protocols
|
||||
- Short time-to-live values on tokens
|
||||
- TeamID matching requirements for privileged operations
|
||||
- Signed bundle ID stability across rebuilds
|
||||
|
||||
Communication remains entirely local without exposed network sockets.
|
||||
273
openclaw-knowhow-skill/docs/infrastructure/platforms/macos-vm.md
Normal file
273
openclaw-knowhow-skill/docs/infrastructure/platforms/macos-vm.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# macOS VMs
|
||||
|
||||
# OpenClaw on macOS VMs (Sandboxing)
|
||||
|
||||
## Recommended default (most users)
|
||||
|
||||
* **Small Linux VPS** for an always-on Gateway and low cost. See [VPS hosting](/vps).
|
||||
* **Dedicated hardware** (Mac mini or Linux box) if you want full control and a **residential IP** for browser automation. Many sites block data center IPs, so local browsing often works better.
|
||||
* **Hybrid:** keep the Gateway on a cheap VPS, and connect your Mac as a **node** when you need browser/UI automation. See [Nodes](/nodes) and [Gateway remote](/gateway/remote).
|
||||
|
||||
Use a macOS VM when you specifically need macOS-only capabilities (iMessage/BlueBubbles) or want strict isolation from your daily Mac.
|
||||
|
||||
## macOS VM options
|
||||
|
||||
### Local VM on your Apple Silicon Mac (Lume)
|
||||
|
||||
Run OpenClaw in a sandboxed macOS VM on your existing Apple Silicon Mac using [Lume](https://cua.ai/docs/lume).
|
||||
|
||||
This gives you:
|
||||
|
||||
* Full macOS environment in isolation (your host stays clean)
|
||||
* iMessage support via BlueBubbles (impossible on Linux/Windows)
|
||||
* Instant reset by cloning VMs
|
||||
* No extra hardware or cloud costs
|
||||
|
||||
### Hosted Mac providers (cloud)
|
||||
|
||||
If you want macOS in the cloud, hosted Mac providers work too:
|
||||
|
||||
* [MacStadium](https://www.macstadium.com/) (hosted Macs)
|
||||
* Other hosted Mac vendors also work; follow their VM + SSH docs
|
||||
|
||||
Once you have SSH access to a macOS VM, continue at step 6 below.
|
||||
|
||||
---
|
||||
|
||||
## Quick path (Lume, experienced users)
|
||||
|
||||
1. Install Lume
|
||||
2. `lume create openclaw --os macos --ipsw latest`
|
||||
3. Complete Setup Assistant, enable Remote Login (SSH)
|
||||
4. `lume run openclaw --no-display`
|
||||
5. SSH in, install OpenClaw, configure channels
|
||||
6. Done
|
||||
|
||||
---
|
||||
|
||||
## What you need (Lume)
|
||||
|
||||
* Apple Silicon Mac (M1/M2/M3/M4)
|
||||
* macOS Sequoia or later on the host
|
||||
* ~60 GB free disk space per VM
|
||||
* ~20 minutes
|
||||
|
||||
---
|
||||
|
||||
## 1) Install Lume
|
||||
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
|
||||
```
|
||||
|
||||
If `~/.local/bin` isn't in your PATH:
|
||||
|
||||
```bash
|
||||
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
|
||||
```
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
lume --version
|
||||
```
|
||||
|
||||
Docs: [Lume Installation](https://cua.ai/docs/lume/guide/getting-started/installation)
|
||||
|
||||
---
|
||||
|
||||
## 2) Create the macOS VM
|
||||
|
||||
```bash
|
||||
lume create openclaw --os macos --ipsw latest
|
||||
```
|
||||
|
||||
This downloads macOS and creates the VM. A VNC window opens automatically.
|
||||
|
||||
Note: The download can take a while depending on your connection.
|
||||
|
||||
---
|
||||
|
||||
## 3) Complete Setup Assistant
|
||||
|
||||
In the VNC window:
|
||||
|
||||
1. Select language and region
|
||||
2. Skip Apple ID (or sign in if you want iMessage later)
|
||||
3. Create a user account (remember the username and password)
|
||||
4. Skip all optional features
|
||||
|
||||
After setup completes, enable SSH:
|
||||
|
||||
1. Open System Settings → General → Sharing
|
||||
2. Enable "Remote Login"
|
||||
|
||||
---
|
||||
|
||||
## 4) Get the VM's IP address
|
||||
|
||||
```bash
|
||||
lume get openclaw
|
||||
```
|
||||
|
||||
Look for the IP address (usually `192.168.64.x`).
|
||||
|
||||
---
|
||||
|
||||
## 5) SSH into the VM
|
||||
|
||||
```bash
|
||||
ssh youruser@192.168.64.X
|
||||
```
|
||||
|
||||
Replace `youruser` with the account you created, and the IP with your VM's IP.
|
||||
|
||||
---
|
||||
|
||||
## 6) Install OpenClaw
|
||||
|
||||
Inside the VM:
|
||||
|
||||
```bash
|
||||
npm install -g openclaw@latest
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
Follow the onboarding prompts to set up your model provider (Anthropic, OpenAI, etc.).
|
||||
|
||||
---
|
||||
|
||||
## 7) Configure channels
|
||||
|
||||
Edit the config file:
|
||||
|
||||
```bash
|
||||
nano ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
Add your channels:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"whatsapp": {
|
||||
"dmPolicy": "allowlist",
|
||||
"allowFrom": ["+15551234567"]
|
||||
},
|
||||
"telegram": {
|
||||
"botToken": "YOUR_BOT_TOKEN"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then login to WhatsApp (scan QR):
|
||||
|
||||
```bash
|
||||
openclaw channels login
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8) Run the VM headlessly
|
||||
|
||||
Stop the VM and restart without display:
|
||||
|
||||
```bash
|
||||
lume stop openclaw
|
||||
lume run openclaw --no-display
|
||||
```
|
||||
|
||||
The VM runs in the background. OpenClaw's daemon keeps the gateway running.
|
||||
|
||||
To check status:
|
||||
|
||||
```bash
|
||||
ssh youruser@192.168.64.X "openclaw status"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bonus: iMessage integration
|
||||
|
||||
This is the killer feature of running on macOS. Use [BlueBubbles](https://bluebubbles.app) to add iMessage to OpenClaw.
|
||||
|
||||
Inside the VM:
|
||||
|
||||
1. Download BlueBubbles from bluebubbles.app
|
||||
2. Sign in with your Apple ID
|
||||
3. Enable the Web API and set a password
|
||||
4. Point BlueBubbles webhooks at your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`)
|
||||
|
||||
Add to your OpenClaw config:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"bluebubbles": {
|
||||
"serverUrl": "http://localhost:1234",
|
||||
"password": "your-api-password",
|
||||
"webhookPath": "/bluebubbles-webhook"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Restart the gateway. Now your agent can send and receive iMessages.
|
||||
|
||||
Full setup details: [BlueBubbles channel](/channels/bluebubbles)
|
||||
|
||||
---
|
||||
|
||||
## Save a golden image
|
||||
|
||||
Before customizing further, snapshot your clean state:
|
||||
|
||||
```bash
|
||||
lume stop openclaw
|
||||
lume clone openclaw openclaw-golden
|
||||
```
|
||||
|
||||
Reset anytime:
|
||||
|
||||
```bash
|
||||
lume stop openclaw && lume delete openclaw
|
||||
lume clone openclaw-golden openclaw
|
||||
lume run openclaw --no-display
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running 24/7
|
||||
|
||||
Keep the VM running by:
|
||||
|
||||
* Keeping your Mac plugged in
|
||||
* Disabling sleep in System Settings → Energy Saver
|
||||
* Using `caffeinate` if needed
|
||||
|
||||
For true always-on, consider a dedicated Mac mini or a small VPS. See [VPS hosting](/vps).
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
| ------------------------ | ---------------------------------------------------------------------------------- |
|
||||
| Can't SSH into VM | Check "Remote Login" is enabled in VM's System Settings |
|
||||
| VM IP not showing | Wait for VM to fully boot, run `lume get openclaw` again |
|
||||
| Lume command not found | Add `~/.local/bin` to your PATH |
|
||||
| WhatsApp QR not scanning | Ensure you're logged into the VM (not host) when running `openclaw channels login` |
|
||||
|
||||
---
|
||||
|
||||
## Related docs
|
||||
|
||||
* [VPS hosting](/vps)
|
||||
* [Nodes](/nodes)
|
||||
* [Gateway remote](/gateway/remote)
|
||||
* [BlueBubbles channel](/channels/bluebubbles)
|
||||
* [Lume Quickstart](https://cua.ai/docs/lume/guide/getting-started/quickstart)
|
||||
* [Lume CLI Reference](https://cua.ai/docs/lume/reference/cli-reference)
|
||||
* [Unattended VM Setup](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup) (advanced)
|
||||
* [Docker Sandboxing](/install/docker) (alternative isolation approach)
|
||||
@@ -0,0 +1,48 @@
|
||||
# macOS App
|
||||
|
||||
## Overview
|
||||
|
||||
The macOS companion application serves as a menu-bar interface for OpenClaw, managing permissions and exposing system capabilities. It owns permissions, manages/attaches to the Gateway locally and provides access to macOS-specific tools.
|
||||
|
||||
## Core Functionality
|
||||
|
||||
Key responsibilities include:
|
||||
|
||||
- Native notifications and menu-bar status display
|
||||
- TCC prompt management (Notifications, Accessibility, Screen Recording, etc.)
|
||||
- Gateway connection handling (local or remote)
|
||||
- macOS tool exposure (Canvas, Camera, Screen Recording, system execution)
|
||||
|
||||
## Operating Modes
|
||||
|
||||
The app supports two configurations:
|
||||
|
||||
1. **Local mode** (default): Attaches to running local Gateway; enables launchd service if needed
|
||||
2. **Remote mode**: Connects via SSH/Tailscale; starts node host service for remote Gateway access
|
||||
|
||||
## Node Capabilities
|
||||
|
||||
Common command categories available through the macOS node:
|
||||
|
||||
- Canvas operations (`canvas.present`, `canvas.navigate`, etc.)
|
||||
- Camera functions (`camera.snap`, `camera.clip`)
|
||||
- Screen recording (`screen.record`)
|
||||
- System commands (`system.run`, `system.notify`)
|
||||
|
||||
## Security Features
|
||||
|
||||
**Exec approvals** control `system.run` execution through a local configuration file. The system uses pattern-matching for allowlists and stores settings in `~/.openclaw/exec-approvals.json`.
|
||||
|
||||
## Deep Link Integration
|
||||
|
||||
The app registers `openclaw://` URLs for triggering agent requests with optional parameters like message content and session keys.
|
||||
|
||||
## Development
|
||||
|
||||
Building requires:
|
||||
|
||||
```bash
|
||||
cd apps/macos && swift build
|
||||
```
|
||||
|
||||
Packaging via provided scripts.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Windows (WSL2)
|
||||
|
||||
## Overview
|
||||
|
||||
The documentation recommends deploying OpenClaw on Windows through WSL2 (Ubuntu preferred) rather than natively, as this approach maintains consistent runtime behavior and improves compatibility with essential tooling and skills.
|
||||
|
||||
## Installation Path
|
||||
|
||||
Users should begin by establishing WSL2 with a single command, then follow the Linux-based Getting Started guide within the WSL environment. The process involves:
|
||||
|
||||
1. Cloning the repository
|
||||
2. Installing dependencies via pnpm
|
||||
3. Building the application
|
||||
4. Running the onboarding workflow
|
||||
|
||||
## Gateway Setup
|
||||
|
||||
The Gateway service installs through several command options:
|
||||
|
||||
- `openclaw onboard --install-daemon`
|
||||
- `openclaw gateway install`
|
||||
- `openclaw configure` (selecting Gateway service when prompted)
|
||||
|
||||
Users can diagnose or repair installations using `openclaw doctor`.
|
||||
|
||||
## Network Configuration
|
||||
|
||||
A key technical consideration: WSL operates on its own virtual network separate from Windows. To enable other machines accessing services within WSL (like the Gateway), administrators must configure port forwarding using PowerShell commands that map Windows ports to the current WSL IP address. This requires reapplication after each WSL restart, though automated Scheduled Tasks can handle this.
|
||||
|
||||
## Current Limitations
|
||||
|
||||
A Windows companion app does not yet exist, though community contributions toward this feature are welcomed.
|
||||
Reference in New Issue
Block a user