Ansible

使用 openclaw-ansible 将 OpenClaw 部署到生产服务器，这是一个采用安全优先架构的自动化安装程序。

前提条件¶

你将获得¶

• 防火墙优先的安全策略：UFW + Docker 隔离（仅 SSH 和 Tailscale 可访问）
• Tailscale VPN 用于远程访问，无需将服务公网暴露
• Docker 用于隔离沙箱容器，仅绑定 localhost
• 集成 systemd，包含安全加固，开机自动启动
• 一条命令完成安装

快速开始¶

curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash

安装内容¶

1. Tailscale（用于安全远程访问的网状 VPN）
2. UFW 防火墙（仅 SSH + Tailscale 端口）
3. Docker CE + Compose V2（默认的 Agent 沙箱后端）
4. Node.js 和 pnpm（OpenClaw 需要 Node 24.16+ 或 26.1+；建议使用 Node 26）
5. OpenClaw：安装在宿主机上，而非容器化
6. 带有安全加固的 systemd 服务

安装后设置¶

1. 切换到 openclaw 用户

sudo -i -u openclaw

2. 运行初始化向导

安装后脚本会引导你完成 OpenClaw 的配置。

3. 连接消息渠道

登录 WhatsApp、Telegram、Discord 或 Signal：

openclaw channels login --channel <name>

4. 验证安装

sudo systemctl status openclaw
sudo journalctl -u openclaw -f

5. 连接到 Tailscale

加入你的 VPN 网状网络，以实现安全远程访问。

快速命令¶

# Check service status
sudo systemctl status openclaw

# View live logs
sudo journalctl -u openclaw -f

# Restart gateway (run as openclaw user)
openclaw gateway restart

# Channel login (run as openclaw user)
sudo -i -u openclaw
openclaw channels login --channel <name>

openclaw gateway restart 会记录受管重启意图。对于系统级服务，请按照它打印出的确切 sudo systemctl restart <unit> 命令执行。

安全架构¶

四层防御模型：

1. 防火墙（UFW）：公网仅暴露 SSH（22）和 Tailscale（41641/udp）
2. VPN（Tailscale）：网关只能通过 VPN 网状网络访问
3. Docker 隔离：DOCKER-USER iptables 链可防止外部端口暴露
4. systemd 加固：NoNewPrivileges、PrivateTmp、非特权用户

验证你的外部攻击面：

nmap -p- YOUR_SERVER_IP

只有 22 端口（SSH）应保持开放。网关和 Docker 保持锁定。

安装 Docker 是为了提供 Agent 沙箱（隔离的工具执行环境），而不是为了运行网关。沙箱配置请参阅 多 Agent 沙箱与工具。

手动安装¶

1. 安装前置依赖

sudo apt update && sudo apt install -y ansible git

2. 克隆仓库

git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible

3. 安装 Ansible Collections

ansible-galaxy collection install -r requirements.yml

4. 运行 Playbook

./run-playbook.sh

或者直接运行 playbook，然后手动运行设置脚本：

ansible-playbook playbook.yml --ask-become-pass
# Then run: /tmp/openclaw-setup.sh

更新¶

Ansible 安装程序会将 OpenClaw 配置为手动更新；标准流程请参阅 更新。

重新运行 playbook（例如在配置更改后）：

cd openclaw-ansible
./run-playbook.sh

该操作是幂等的，可安全地多次运行。

故障排查¶

# 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

# 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

sudo -i -u openclaw
openclaw channels login --channel <name>

高级配置¶

有关详细的安全架构与故障排查，请参阅 openclaw-ansible 仓库：

• 安全架构
• 技术细节
• 故障排查指南

相关文档¶

• openclaw-ansible：完整部署指南
• Docker：容器化网关设置
• 沙箱：Agent 沙箱配置
• 多 Agent 沙箱与工具：按 Agent 隔离