mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-15 17:56:05 +00:00
f7d7148cf0
Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green. Closes #100141
226 lines
6.6 KiB
Markdown
226 lines
6.6 KiB
Markdown
---
|
|
summary: "Automated, hardened OpenClaw installation with Ansible, Tailscale VPN, and firewall isolation"
|
|
read_when:
|
|
- You want automated server deployment with security hardening
|
|
- You need firewall-isolated setup with VPN access
|
|
- You're deploying to remote Debian/Ubuntu servers
|
|
title: "Ansible"
|
|
---
|
|
|
|
Deploy OpenClaw to production servers with **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)**, an automated installer with a security-first architecture.
|
|
|
|
<Info>
|
|
The [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) repo is the source of truth for Ansible deployment. This page is a quick overview.
|
|
</Info>
|
|
|
|
## 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 reachable)
|
|
- Tailscale VPN for remote access without exposing services publicly
|
|
- Docker for isolated sandbox containers with localhost-only bindings
|
|
- Systemd integration with hardening, auto-starting on boot
|
|
- One-command setup
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash
|
|
```
|
|
|
|
## What gets installed
|
|
|
|
1. Tailscale (mesh VPN for secure remote access)
|
|
2. UFW firewall (SSH + Tailscale ports only)
|
|
3. Docker CE + Compose V2 (default agent sandbox backend)
|
|
4. Node.js and pnpm (OpenClaw requires Node 22.19+ or 23.11+; Node 24 is recommended)
|
|
5. OpenClaw, installed host-based, not containerized
|
|
6. A systemd service with security hardening
|
|
|
|
<Note>
|
|
The gateway runs directly on the host, not in Docker. Agent sandboxing is
|
|
optional; this playbook installs Docker because it is the default sandbox
|
|
backend. See [Sandboxing](/gateway/sandboxing) for other backends.
|
|
</Note>
|
|
|
|
## Post-install setup
|
|
|
|
<Steps>
|
|
<Step title="Switch to the openclaw user">
|
|
```bash
|
|
sudo -i -u openclaw
|
|
```
|
|
</Step>
|
|
<Step title="Run the onboarding wizard">
|
|
The post-install script guides you through configuring OpenClaw.
|
|
</Step>
|
|
<Step title="Connect messaging channels">
|
|
Log in to WhatsApp, Telegram, Discord, or Signal:
|
|
```bash
|
|
openclaw channels login --channel <name>
|
|
```
|
|
</Step>
|
|
<Step title="Verify the installation">
|
|
```bash
|
|
sudo systemctl status openclaw
|
|
sudo journalctl -u openclaw -f
|
|
```
|
|
</Step>
|
|
<Step title="Connect to Tailscale">
|
|
Join your VPN mesh for secure remote access.
|
|
</Step>
|
|
</Steps>
|
|
|
|
### Quick commands
|
|
|
|
```bash
|
|
# Check service status
|
|
sudo systemctl status openclaw
|
|
|
|
# View live logs
|
|
sudo journalctl -u openclaw -f
|
|
|
|
# Restart gateway
|
|
sudo systemctl restart openclaw
|
|
|
|
# Channel login (run as openclaw user)
|
|
sudo -i -u openclaw
|
|
openclaw channels login --channel <name>
|
|
```
|
|
|
|
## Security architecture
|
|
|
|
Four-layer defense model:
|
|
|
|
1. Firewall (UFW): only SSH (22) and Tailscale (41641/udp) exposed publicly
|
|
2. VPN (Tailscale): gateway reachable only via the VPN mesh
|
|
3. Docker isolation: `DOCKER-USER` iptables chain prevents external port exposure
|
|
4. Systemd hardening: `NoNewPrivileges`, `PrivateTmp`, unprivileged user
|
|
|
|
Verify your external attack surface:
|
|
|
|
```bash
|
|
nmap -p- YOUR_SERVER_IP
|
|
```
|
|
|
|
Only port 22 (SSH) should be open. Gateway and Docker stay locked down.
|
|
|
|
Docker is installed for agent sandboxes (isolated tool execution), not for running the gateway. See [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) for sandbox configuration.
|
|
|
|
## Manual installation
|
|
|
|
<Steps>
|
|
<Step title="Install prerequisites">
|
|
```bash
|
|
sudo apt update && sudo apt install -y ansible git
|
|
```
|
|
</Step>
|
|
<Step title="Clone the repository">
|
|
```bash
|
|
git clone https://github.com/openclaw/openclaw-ansible.git
|
|
cd openclaw-ansible
|
|
```
|
|
</Step>
|
|
<Step title="Install Ansible collections">
|
|
```bash
|
|
ansible-galaxy collection install -r requirements.yml
|
|
```
|
|
</Step>
|
|
<Step title="Run the playbook">
|
|
```bash
|
|
./run-playbook.sh
|
|
```
|
|
|
|
Or run the playbook directly and then run the setup script manually:
|
|
```bash
|
|
ansible-playbook playbook.yml --ask-become-pass
|
|
# Then run: /tmp/openclaw-setup.sh
|
|
```
|
|
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Updating
|
|
|
|
The Ansible installer sets up OpenClaw for manual updates; see [Updating](/install/updating) for the standard flow.
|
|
|
|
To re-run the playbook (for example, after configuration changes):
|
|
|
|
```bash
|
|
cd openclaw-ansible
|
|
./run-playbook.sh
|
|
```
|
|
|
|
This is idempotent and safe to run multiple times.
|
|
|
|
## Troubleshooting
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Firewall blocks my connection">
|
|
- Connect via Tailscale VPN first; the gateway is only reachable that way by design.
|
|
- SSH (port 22) is always allowed.
|
|
|
|
</Accordion>
|
|
<Accordion title="Service will not start">
|
|
```bash
|
|
# Check logs
|
|
sudo journalctl -u openclaw -n 100
|
|
|
|
# Verify permissions
|
|
sudo ls -la /opt/openclaw
|
|
|
|
# Test manual start
|
|
sudo -i -u openclaw
|
|
cd ~/openclaw
|
|
openclaw gateway run
|
|
```
|
|
|
|
</Accordion>
|
|
<Accordion title="Docker sandbox issues">
|
|
```bash
|
|
# Verify Docker is running
|
|
sudo systemctl status docker
|
|
|
|
# Check sandbox image
|
|
sudo docker images | grep openclaw-sandbox
|
|
|
|
# Build the sandbox image if missing (requires a source checkout)
|
|
cd /opt/openclaw/openclaw
|
|
sudo -u openclaw ./scripts/sandbox-setup.sh
|
|
# For npm installs without a source checkout, see
|
|
# https://docs.openclaw.ai/gateway/sandboxing#images-and-setup
|
|
```
|
|
|
|
</Accordion>
|
|
<Accordion title="Channel login fails">
|
|
Make sure you are running as the `openclaw` user:
|
|
```bash
|
|
sudo -i -u openclaw
|
|
openclaw channels login --channel <name>
|
|
```
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## Advanced configuration
|
|
|
|
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)
|
|
- [Troubleshooting Guide](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md)
|
|
|
|
## 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 and Tools](/tools/multi-agent-sandbox-tools): per-agent isolation
|