跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Ansible 安装

使用 openclaw-ansible 将 OpenClaw 部署到生产服务器 —— 这是一个采用安全优先架构的自动化安装器。
openclaw-ansible 仓库是 Ansible 部署的事实来源。本页是快速概览。

​
前提条件

要求详情
操作系统Debian 11+ 或 Ubuntu 20.04+
访问权限root 或 sudo 权限
网络用于安装软件包的互联网连接
Ansible2.14+（由快速开始脚本自动安装）

​
你将获得

  • 防火墙优先的安全性 —— UFW + Docker 隔离（仅 SSH + Tailscale 可访问）
  • Tailscale VPN —— 无需公开暴露服务即可安全远程访问
  • Docker —— 隔离的沙箱容器，仅限 localhost 绑定
  • 纵深防御 —— 4 层安全架构
  • Systemd 集成 —— 开机自动启动并启用加固
  • 一条命令完成设置 —— 数分钟内完成部署

​
快速开始

一条命令安装： 
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash

​
会安装什么

Ansible playbook 会安装并配置：
  1. Tailscale —— 用于安全远程访问的网状 VPN
  2. UFW 防火墙 —— 仅开放 SSH + Tailscale 端口
  3. Docker CE + Compose V2 —— 用于默认的智能体沙箱后端
  4. Node.js 24 + pnpm —— 运行时依赖（Node 22 LTS，目前为 22.14+，仍受支持）
  5. OpenClaw —— 基于主机运行，不容器化
  6. Systemd 服务 —— 启用安全加固并自动启动
Gateway 网关直接在主机上运行（不在 Docker 中）。智能体沙箱隔离是可选的；此 playbook 会安装 Docker，因为它是默认沙箱后端。详情和其他后端请参阅沙箱隔离。

​
安装后设置

1

切换到 openclaw 用户

sudo -i -u openclaw
2

运行新手引导向导

安装后脚本会引导你配置 OpenClaw 设置。
3

连接消息提供商

登录 WhatsApp、Telegram、Discord 或 Signal：
openclaw channels login
4

验证安装

sudo systemctl status openclaw
sudo journalctl -u openclaw -f
5

连接到 Tailscale

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

​
快速命令

# 检查服务状态
sudo systemctl status openclaw

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

# 重启 Gateway 网关
sudo systemctl restart openclaw

# 提供商登录（以 openclaw 用户运行）
sudo -i -u openclaw
openclaw channels login

​
安全架构

该部署使用 4 层防御模型：
  1. 防火墙（UFW） —— 仅公开暴露 SSH（22）+ Tailscale（41641/udp）
  2. VPN（Tailscale） —— Gateway 网关只能通过 VPN 网状网络访问
  3. Docker 隔离 —— DOCKER-USER iptables 链防止外部端口暴露
  4. Systemd 加固 —— NoNewPrivileges、PrivateTmp、非特权用户
要验证你的外部攻击面： 
nmap -p- YOUR_SERVER_IP
只有端口 22（SSH）应处于开放状态。所有其他服务（Gateway 网关、Docker）都会被锁定。 Docker 是为智能体沙箱（隔离工具执行）安装的，不用于运行 Gateway 网关本身。有关沙箱配置，请参阅多智能体沙箱和工具。

​
手动安装

如果你希望手动控制自动化过程：
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
或者，直接运行，然后手动执行设置脚本：
ansible-playbook playbook.yml --ask-become-pass
# 然后运行：/tmp/openclaw-setup.sh

​
更新

Ansible 安装器会将 OpenClaw 设置为手动更新模式。标准更新流程请参阅更新。 要重新运行 Ansible playbook（例如用于配置变更）： 
cd openclaw-ansible
./run-playbook.sh
这是幂等的，可以安全地多次运行。

​
故障排除

  • 确保你可以先通过 Tailscale VPN 访问
  • SSH 访问（端口 22）始终允许
  • Gateway 网关按设计只能通过 Tailscale 访问
# 检查日志
sudo journalctl -u openclaw -n 100

# 验证权限
sudo ls -la /opt/openclaw

# 测试手动启动
sudo -i -u openclaw
cd ~/openclaw
openclaw gateway run

# 验证 Docker 正在运行
sudo systemctl status docker

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

# 如果缺失则构建沙箱镜像（需要源码检出）
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh
# 对于没有源码检出的 npm 安装，请参阅
# https://docs.openclaw.ai/gateway/sandboxing#images-and-setup
确保你正以 openclaw 用户运行：
sudo -i -u openclaw
openclaw channels login

​
高级配置

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

​
相关