diff --git a/docs/install/ansible.md b/docs/install/ansible.md index 6da78ed45bf..84ed56c5d03 100644 --- a/docs/install/ansible.md +++ b/docs/install/ansible.md @@ -9,7 +9,29 @@ title: "Ansible" # Ansible Installation -The recommended way to deploy OpenClaw to production servers is via **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** β€” an automated installer with security-first architecture. +Deploy OpenClaw to production servers with **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** -- an automated installer with security-first architecture. + + +The [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) repo is the source of truth for Ansible deployment. This page is a quick overview. + + +## Prerequisites + +| Requirement | Details | +| ----------- | --------------------------------------------------------- | +| **OS** | Debian 11+ or Ubuntu 20.04+ | +| **Access** | Root or sudo privileges | +| **Network** | Internet connection for package installation | +| **Ansible** | 2.14+ (installed automatically by the quick-start script) | + +## What You Get + +- **Firewall-first security** -- UFW + Docker isolation (only SSH + Tailscale accessible) +- **Tailscale VPN** -- secure remote access without exposing services publicly +- **Docker** -- isolated sandbox containers, localhost-only bindings +- **Defense in depth** -- 4-layer security architecture +- **Systemd integration** -- auto-start on boot with hardening +- **One-command setup** -- complete deployment in minutes ## Quick Start @@ -19,55 +41,50 @@ One-command install: curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash ``` -> **πŸ“¦ Full guide: [github.com/openclaw/openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** -> -> The openclaw-ansible repo is the source of truth for Ansible deployment. This page is a quick overview. - -## What You Get - -- **Firewall-first security**: UFW + Docker isolation (only SSH + Tailscale accessible) -- **Tailscale VPN**: Secure remote access without exposing services publicly -- **Docker**: Isolated sandbox containers, localhost-only bindings -- **Defense in depth**: 4-layer security architecture -- **One-command setup**: Complete deployment in minutes -- **Systemd integration**: Auto-start on boot with hardening - -## Requirements - -- **OS**: Debian 11+ or Ubuntu 20.04+ -- **Access**: Root or sudo privileges -- **Network**: Internet connection for package installation -- **Ansible**: 2.14+ (installed automatically by quick-start script) - ## What Gets Installed The Ansible playbook installs and configures: -1. **Tailscale** (mesh VPN for secure remote access) -2. **UFW firewall** (SSH + Tailscale ports only) -3. **Docker CE + Compose V2** (for agent sandboxes) -4. **Node.js 24 + pnpm** (runtime dependencies; Node 22 LTS, currently `22.16+`, remains supported for compatibility) -5. **OpenClaw** (host-based, not containerized) -6. **Systemd service** (auto-start with security hardening) +1. **Tailscale** -- mesh VPN for secure remote access +2. **UFW firewall** -- SSH + Tailscale ports only +3. **Docker CE + Compose V2** -- for agent sandboxes +4. **Node.js 24 + pnpm** -- runtime dependencies (Node 22 LTS, currently `22.16+`, remains supported) +5. **OpenClaw** -- host-based, not containerized +6. **Systemd service** -- auto-start with security hardening -Note: The gateway runs **directly on the host** (not in Docker), but agent sandboxes use Docker for isolation. See [Sandboxing](/gateway/sandboxing) for details. + +The gateway runs directly on the host (not in Docker), but agent sandboxes use Docker for isolation. See [Sandboxing](/gateway/sandboxing) for details. + ## Post-Install Setup -After installation completes, switch to the openclaw user: + + + ```bash + sudo -i -u openclaw + ``` + + + The post-install script guides you through configuring OpenClaw settings. + + + Log in to WhatsApp, Telegram, Discord, or Signal: + ```bash + openclaw channels login + ``` + + + ```bash + sudo systemctl status openclaw + sudo journalctl -u openclaw -f + ``` + + + Join your VPN mesh for secure remote access. + + -```bash -sudo -i -u openclaw -``` - -The post-install script will guide you through: - -1. **Onboarding wizard**: Configure OpenClaw settings -2. **Provider login**: Connect WhatsApp/Telegram/Discord/Signal -3. **Gateway testing**: Verify the installation -4. **Tailscale setup**: Connect to your VPN mesh - -### Quick commands +### Quick Commands ```bash # Check service status @@ -86,115 +103,120 @@ openclaw channels login ## Security Architecture -### 4-Layer Defense +The deployment uses a 4-layer defense model: -1. **Firewall (UFW)**: Only SSH (22) + Tailscale (41641/udp) exposed publicly -2. **VPN (Tailscale)**: Gateway accessible only via VPN mesh -3. **Docker Isolation**: DOCKER-USER iptables chain prevents external port exposure -4. **Systemd Hardening**: NoNewPrivileges, PrivateTmp, unprivileged user +1. **Firewall (UFW)** -- only SSH (22) + Tailscale (41641/udp) exposed publicly +2. **VPN (Tailscale)** -- gateway accessible only via VPN mesh +3. **Docker isolation** -- DOCKER-USER iptables chain prevents external port exposure +4. **Systemd hardening** -- NoNewPrivileges, PrivateTmp, unprivileged user -### Verification - -Test external attack surface: +To verify your external attack surface: ```bash nmap -p- YOUR_SERVER_IP ``` -Should show **only port 22** (SSH) open. All other services (gateway, Docker) are locked down. +Only port 22 (SSH) should be open. All other services (gateway, Docker) are locked down. -### Docker Availability - -Docker is installed for **agent sandboxes** (isolated tool execution), not for running the gateway itself. The gateway binds to localhost only and is accessible via Tailscale VPN. - -See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for sandbox configuration. +Docker is installed for agent sandboxes (isolated tool execution), not for running the gateway itself. See [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) for sandbox configuration. ## Manual Installation If you prefer manual control over the automation: -```bash -# 1. Install prerequisites -sudo apt update && sudo apt install -y ansible git + + + ```bash + sudo apt update && sudo apt install -y ansible git + ``` + + + ```bash + git clone https://github.com/openclaw/openclaw-ansible.git + cd openclaw-ansible + ``` + + + ```bash + ansible-galaxy collection install -r requirements.yml + ``` + + + ```bash + ./run-playbook.sh + ``` -# 2. Clone repository -git clone https://github.com/openclaw/openclaw-ansible.git -cd openclaw-ansible + Alternatively, run directly and then manually execute the setup script afterward: + ```bash + ansible-playbook playbook.yml --ask-become-pass + # Then run: /tmp/openclaw-setup.sh + ``` -# 3. Install Ansible collections -ansible-galaxy collection install -r requirements.yml + + -# 4. Run playbook -./run-playbook.sh - -# Or run directly (then manually execute /tmp/openclaw-setup.sh after) -# ansible-playbook playbook.yml --ask-become-pass -``` - -## Updating OpenClaw +## Updating The Ansible installer sets up OpenClaw for manual updates. See [Updating](/install/updating) for the standard update flow. -To re-run the Ansible playbook (e.g., for configuration changes): +To re-run the Ansible playbook (for example, for configuration changes): ```bash cd openclaw-ansible ./run-playbook.sh ``` -Note: This is idempotent and safe to run multiple times. +This is idempotent and safe to run multiple times. ## Troubleshooting -### Firewall blocks my connection + + + - Ensure you can access via Tailscale VPN first + - SSH access (port 22) is always allowed + - The gateway is only accessible via Tailscale by design + + + ```bash + # Check logs + sudo journalctl -u openclaw -n 100 -If you're locked out: + # Verify permissions + sudo ls -la /opt/openclaw -- Ensure you can access via Tailscale VPN first -- SSH access (port 22) is always allowed -- The gateway is **only** accessible via Tailscale by design + # Test manual start + sudo -i -u openclaw + cd ~/openclaw + openclaw gateway run + ``` -### Service will not start + + + ```bash + # Verify Docker is running + sudo systemctl status docker -```bash -# Check logs -sudo journalctl -u openclaw -n 100 + # Check sandbox image + sudo docker images | grep openclaw-sandbox -# Verify permissions -sudo ls -la /opt/openclaw + # Build sandbox image if missing + cd /opt/openclaw/openclaw + sudo -u openclaw ./scripts/sandbox-setup.sh + ``` -# Test manual start -sudo -i -u openclaw -cd ~/openclaw -openclaw gateway run -``` - -### Docker sandbox issues - -```bash -# Verify Docker is running -sudo systemctl status docker - -# Check sandbox image -sudo docker images | grep openclaw-sandbox - -# Build sandbox image if missing -cd /opt/openclaw/openclaw -sudo -u openclaw ./scripts/sandbox-setup.sh -``` - -### Provider login fails - -Make sure you're running as the `openclaw` user: - -```bash -sudo -i -u openclaw -openclaw channels login -``` + + + Make sure you are running as the `openclaw` user: + ```bash + sudo -i -u openclaw + openclaw channels login + ``` + + ## Advanced Configuration -For detailed security architecture and troubleshooting: +For detailed security architecture and troubleshooting, see the openclaw-ansible repo: - [Security Architecture](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md) - [Technical Details](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md) @@ -202,7 +224,7 @@ For detailed security architecture and troubleshooting: ## Related -- [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) β€” full deployment guide -- [Docker](/install/docker) β€” containerized gateway setup -- [Sandboxing](/gateway/sandboxing) β€” agent sandbox configuration -- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) β€” per-agent isolation +- [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) -- full deployment guide +- [Docker](/install/docker) -- containerized gateway setup +- [Sandboxing](/gateway/sandboxing) -- agent sandbox configuration +- [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) -- per-agent isolation diff --git a/docs/install/bun.md b/docs/install/bun.md index 5cbe76ce3ac..080479fc6b0 100644 --- a/docs/install/bun.md +++ b/docs/install/bun.md @@ -6,49 +6,45 @@ read_when: title: "Bun (Experimental)" --- -# Bun (experimental) +# Bun (Experimental) -Goal: run this repo with **Bun** (optional, not recommended for WhatsApp/Telegram) -without diverging from pnpm workflows. + +Bun is **not recommended for gateway runtime** (known issues with WhatsApp and Telegram). Use Node for production. + -⚠️ **Not recommended for Gateway runtime** (WhatsApp/Telegram bugs). Use Node for production. - -## Status - -- Bun is an optional local runtime for running TypeScript directly (`bun run …`, `bun --watch …`). -- `pnpm` is the default for builds and remains fully supported (and used by some docs tooling). -- Bun cannot use `pnpm-lock.yaml` and will ignore it. +Bun is an optional local runtime for running TypeScript directly (`bun run ...`, `bun --watch ...`). The default package manager remains `pnpm`, which is fully supported and used by docs tooling. Bun cannot use `pnpm-lock.yaml` and will ignore it. ## Install -Default: + + + ```sh + bun install + ``` -```sh -bun install -``` + `bun.lock` / `bun.lockb` are gitignored, so there is no repo churn. To skip lockfile writes entirely: -Note: `bun.lock`/`bun.lockb` are gitignored, so there’s no repo churn either way. If you want _no lockfile writes_: + ```sh + bun install --no-save + ``` -```sh -bun install --no-save -``` + + + ```sh + bun run build + bun run vitest run + ``` + + -## Build / Test (Bun) +## Lifecycle Scripts -```sh -bun run build -bun run vitest run -``` +Bun blocks dependency lifecycle scripts unless explicitly trusted. For this repo, the commonly blocked scripts are not required: -## Bun lifecycle scripts (blocked by default) +- `@whiskeysockets/baileys` `preinstall` -- checks Node major >= 20 (OpenClaw defaults to Node 24 and still supports Node 22 LTS, currently `22.16+`) +- `protobufjs` `postinstall` -- emits warnings about incompatible version schemes (no build artifacts) -Bun may block dependency lifecycle scripts unless explicitly trusted (`bun pm untrusted` / `bun pm trust`). -For this repo, the commonly blocked scripts are not required: - -- `@whiskeysockets/baileys` `preinstall`: checks Node major >= 20 (OpenClaw defaults to Node 24 and still supports Node 22 LTS, currently `22.16+`). -- `protobufjs` `postinstall`: emits warnings about incompatible version schemes (no build artifacts). - -If you hit a real runtime issue that requires these scripts, trust them explicitly: +If you hit a runtime issue that requires these scripts, trust them explicitly: ```sh bun pm trust @whiskeysockets/baileys protobufjs @@ -56,4 +52,4 @@ bun pm trust @whiskeysockets/baileys protobufjs ## Caveats -- Some scripts still hardcode pnpm (e.g. `docs:build`, `ui:*`, `protocol:check`). Run those via pnpm for now. +Some scripts still hardcode pnpm (for example `docs:build`, `ui:*`, `protocol:check`). Run those via pnpm for now. diff --git a/docs/install/nix.md b/docs/install/nix.md index 24b02b5b4fe..371cee007a2 100644 --- a/docs/install/nix.md +++ b/docs/install/nix.md @@ -9,78 +9,81 @@ title: "Nix" # Nix Installation -The recommended way to run OpenClaw with Nix is via **[nix-openclaw](https://github.com/openclaw/nix-openclaw)** β€” a batteries-included Home Manager module. +Install OpenClaw declaratively with **[nix-openclaw](https://github.com/openclaw/nix-openclaw)** -- a batteries-included Home Manager module. -## Quick Start + +The [nix-openclaw](https://github.com/openclaw/nix-openclaw) repo is the source of truth for Nix installation. This page is a quick overview. + -Paste this to your AI agent (Claude, Cursor, etc.): +## What You Get -```text -I want to set up nix-openclaw on my Mac. -Repository: github:openclaw/nix-openclaw - -What I need you to do: -1. Check if Determinate Nix is installed (if not, install it) -2. Create a local flake at ~/code/openclaw-local using templates/agent-first/flake.nix -3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot) -4. Set up secrets (bot token, model provider API key) - plain files at ~/.secrets/ is fine -5. Fill in the template placeholders and run home-manager switch -6. Verify: launchd running, bot responds to messages - -Reference the nix-openclaw README for module options. -``` - -> **πŸ“¦ Full guide: [github.com/openclaw/nix-openclaw](https://github.com/openclaw/nix-openclaw)** -> -> The nix-openclaw repo is the source of truth for Nix installation. This page is just a quick overview. - -## What you get - -- Gateway + macOS app + tools (whisper, spotify, cameras) β€” all pinned +- Gateway + macOS app + tools (whisper, spotify, cameras) -- all pinned - Launchd service that survives reboots - Plugin system with declarative config - Instant rollback: `home-manager switch --rollback` ---- +## Quick Start + + + + If Nix is not already installed, follow the [Determinate Nix installer](https://github.com/DeterminateSystems/nix-installer) instructions. + + + Use the agent-first template from the nix-openclaw repo: + ```bash + mkdir -p ~/code/openclaw-local + # Copy templates/agent-first/flake.nix from the nix-openclaw repo + ``` + + + Set up your messaging bot token and model provider API key. Plain files at `~/.secrets/` work fine. + + + ```bash + home-manager switch + ``` + + + Confirm the launchd service is running and your bot responds to messages. + + + +See the [nix-openclaw README](https://github.com/openclaw/nix-openclaw) for full module options and examples. ## Nix Mode Runtime Behavior -When `OPENCLAW_NIX_MODE=1` is set (automatic with nix-openclaw): +When `OPENCLAW_NIX_MODE=1` is set (automatic with nix-openclaw), OpenClaw enters a deterministic mode that disables auto-install flows. -OpenClaw supports a **Nix mode** that makes configuration deterministic and disables auto-install flows. -Enable it by exporting: +You can also set it manually: ```bash -OPENCLAW_NIX_MODE=1 +export OPENCLAW_NIX_MODE=1 ``` -On macOS, the GUI app does not automatically inherit shell env vars. You can -also enable Nix mode via defaults: +On macOS, the GUI app does not automatically inherit shell environment variables. Enable Nix mode via defaults instead: ```bash defaults write ai.openclaw.mac openclaw.nixMode -bool true ``` -### Config + state paths - -OpenClaw reads JSON5 config from `OPENCLAW_CONFIG_PATH` and stores mutable data in `OPENCLAW_STATE_DIR`. -When needed, you can also set `OPENCLAW_HOME` to control the base home directory used for internal path resolution. - -- `OPENCLAW_HOME` (default precedence: `HOME` / `USERPROFILE` / `os.homedir()`) -- `OPENCLAW_STATE_DIR` (default: `~/.openclaw`) -- `OPENCLAW_CONFIG_PATH` (default: `$OPENCLAW_STATE_DIR/openclaw.json`) - -When running under Nix, set these explicitly to Nix-managed locations so runtime state and config -stay out of the immutable store. - -### Runtime behavior in Nix mode +### What changes in Nix mode - Auto-install and self-mutation flows are disabled - Missing dependencies surface Nix-specific remediation messages -- UI surfaces a read-only Nix mode banner when present +- UI surfaces a read-only Nix mode banner + +### Config and state paths + +OpenClaw reads JSON5 config from `OPENCLAW_CONFIG_PATH` and stores mutable data in `OPENCLAW_STATE_DIR`. When running under Nix, set these explicitly to Nix-managed locations so runtime state and config stay out of the immutable store. + +| Variable | Default | +| ---------------------- | --------------------------------------- | +| `OPENCLAW_HOME` | `HOME` / `USERPROFILE` / `os.homedir()` | +| `OPENCLAW_STATE_DIR` | `~/.openclaw` | +| `OPENCLAW_CONFIG_PATH` | `$OPENCLAW_STATE_DIR/openclaw.json` | ## Related -- [nix-openclaw](https://github.com/openclaw/nix-openclaw) β€” full setup guide -- [Wizard](/start/wizard) β€” non-Nix CLI setup -- [Docker](/install/docker) β€” containerized setup +- [nix-openclaw](https://github.com/openclaw/nix-openclaw) -- full setup guide +- [Wizard](/start/wizard) -- non-Nix CLI setup +- [Docker](/install/docker) -- containerized setup