Ansible 安装

将 OpenClaw 部署到生产服务器的推荐方式是使用 openclaw-ansible —— 一套安全优先的自动化安装工具。

快速开始

一条命令搞定：

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

📦 完整指南：github.com/openclaw/openclaw-ansible

openclaw-ansible 仓库是 Ansible 部署的权威来源。本页只是快速概览。

你会得到什么

🔒 防火墙优先的安全策略：UFW + Docker 隔离（仅 SSH + Tailscale 可访问）
🔐 Tailscale VPN：安全的远程访问，无需对外暴露服务
🐳 Docker：隔离的沙箱容器，仅绑定 localhost
🛡️ 纵深防御：四层安全架构
🚀 一条命令部署：几分钟内完成全部部署
🔧 Systemd 集成：开机自启，带安全加固

系统要求

操作系统：Debian 11+ 或 Ubuntu 20.04+
权限：root 或 sudo 权限
网络：需要联网以安装软件包
Ansible：2.14+（快速安装脚本会自动安装）

安装内容

Ansible playbook 会安装和配置以下组件：

Tailscale（网状 VPN，用于安全远程访问）
UFW 防火墙（仅允许 SSH + Tailscale 端口）
Docker CE + Compose V2（用于 Agent 沙箱）
Node.js 24 + pnpm（运行时依赖；Node 22 LTS，目前 22.16+，仍兼容支持）
OpenClaw（主机方式运行，非容器化）
Systemd 服务（开机自启，带安全加固）

注意：网关直接运行在主机上（不在 Docker 中），但 Agent 沙箱使用 Docker 进行隔离。详见沙箱。

安装后配置

安装完成后，切换到 openclaw 用户：

sudo -i -u openclaw

安装后脚本会引导你完成：

引导向导：配置 OpenClaw 设置
渠道登录：连接 WhatsApp/Telegram/Discord/Signal
网关测试：验证安装
Tailscale 配置：接入你的 VPN 网络

常用命令

# 查看服务状态
sudo systemctl status openclaw

# 查看实时日志
sudo journalctl -u openclaw -f

# 重启网关
sudo systemctl restart openclaw

# 渠道登录（需切换到 openclaw 用户）
sudo -i -u openclaw
openclaw channels login

安全架构

四层防御

防火墙（UFW）：仅对外暴露 SSH (22) + Tailscale (41641/udp)
VPN（Tailscale）：网关仅通过 VPN 网络可达
Docker 隔离：DOCKER-USER iptables 链阻止外部端口暴露
Systemd 加固：NoNewPrivileges、PrivateTmp、非特权用户

验证

测试外部攻击面：

nmap -p- YOUR_SERVER_IP

应该只有 22 端口（SSH）开放。所有其他服务（网关、Docker）都被锁定。

Docker 用途说明

Docker 用于 Agent 沙箱（隔离的工具执行），不用于运行网关本身。网关仅绑定 localhost，通过 Tailscale VPN 访问。

参阅多 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

# 或者直接运行（之后手动执行 /tmp/openclaw-setup.sh）
# ansible-playbook playbook.yml --ask-become-pass

更新 OpenClaw

Ansible 安装方式默认采用手动更新。标准更新流程请参阅更新。

如需重新运行 Ansible playbook（例如修改配置后）：

cd openclaw-ansible
./run-playbook.sh

注意：这是幂等的，可以安全地多次运行。

排错

防火墙阻断了连接

如果被锁在外面：

先确认能否通过 Tailscale VPN 访问
SSH 访问（22 端口）始终允许
网关设计上只能通过 Tailscale 访问

服务无法启动

# 查看日志
sudo journalctl -u openclaw -n 100

# 检查权限
sudo ls -la /opt/openclaw

# 手动测试启动
sudo -i -u openclaw
cd ~/openclaw
pnpm start

Docker 沙箱问题

# 检查 Docker 是否运行
sudo systemctl status docker

# 检查沙箱镜像
sudo docker images | grep openclaw-sandbox

# 如果镜像缺失，构建一下
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh

渠道登录失败

确保你以 openclaw 用户身份运行：

sudo -i -u openclaw
openclaw channels login

高级配置

更详细的安全架构和排错信息：