> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ansible

使用 **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** 将 OpenClaw 部署到生产服务器，这是一个采用安全优先架构的自动化安装程序。

<Info>
  [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) 仓库是 Ansible 部署的唯一可信来源。本页面仅作快速概览。
</Info>

## 前置条件

| Requirement | Details                    |
| ----------- | -------------------------- |
| 操作系统        | Debian 11+ 或 Ubuntu 20.04+ |
| 访问权限        | Root 或 sudo 权限             |
| 网络          | 用于安装软件包的互联网连接              |
| Ansible     | 2.14+（由快速入门脚本自动安装）         |

## 你将获得什么

* 防火墙优先的安全性：UFW + Docker 隔离（仅可通过 SSH + Tailscale 访问）
* 用于远程访问的 Tailscale VPN，无需公开暴露服务
* 使用 Docker 创建仅绑定到 localhost 的隔离沙箱容器
* 带有加固措施的 Systemd 集成，开机自动启动
* 一条命令完成设置

## 快速开始

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash
```

## 将安装什么

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.22.3+, 24.15+, or 25.9+; Node 26 is recommended)
5. OpenClaw, installed host-based, not containerized
6. A systemd service with security hardening

<Note>
  网关直接运行在主机上，而不是在 Docker 中。Agent 沙箱化是
  可选的；本指南安装 Docker，因为它是默认的沙箱
  后端。有关其他后端，请参见 [Sandboxing](/gateway/sandboxing)。
</Note>

## 安装后设置

<Steps>
  <Step title="切换到 openclaw 用户">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo -i -u openclaw
    ```
  </Step>

  <Step title="运行引导向导">
    安装后脚本会引导你完成 OpenClaw 的配置。
  </Step>

  <Step title="连接消息渠道">
    登录 WhatsApp、Telegram、Discord 或 Signal：

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw channels login --channel <name>
    ```
  </Step>

  <Step title="验证安装">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo systemctl status openclaw
    sudo journalctl -u openclaw -f
    ```
  </Step>

  <Step title="连接到 Tailscale">
    加入你的 VPN mesh，以便安全远程访问。
  </Step>
</Steps>

### 快速命令

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 检查服务状态
sudo systemctl status openclaw

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

# 重启网关
sudo systemctl restart openclaw

# 渠道登录（以 openclaw 用户身份运行）
sudo -i -u openclaw
openclaw channels login --channel <name>
```

## 安全架构

四层防御模型：

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

验证你的外部攻击面：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
nmap -p- YOUR_SERVER_IP
```

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

Docker 安装用于 agent 沙盒（隔离的工具执行），而不是用于运行网关。有关沙盒配置，请参见 [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools)。

## 手动安装

<Steps>
  <Step title="安装前置依赖">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo apt update && sudo apt install -y ansible git
    ```
  </Step>

  <Step title="克隆仓库">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    git clone https://github.com/openclaw/openclaw-ansible.git
    cd openclaw-ansible
    ```
  </Step>

  <Step title="安装 Ansible collections">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    ansible-galaxy collection install -r requirements.yml
    ```
  </Step>

  <Step title="运行 playbook">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    ./run-playbook.sh
    ```

    或者直接运行 playbook，然后手动运行安装脚本：

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    ansible-playbook playbook.yml --ask-become-pass
    # 然后运行：/tmp/openclaw-setup.sh
    ```
  </Step>
</Steps>

## 更新

Ansible 安装程序会为手动更新设置 OpenClaw；有关标准流程，请参阅[更新](/install/updating)。

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
cd openclaw-ansible
./run-playbook.sh
```

这具有幂等性，可以安全地多次运行。

## 故障排查

<AccordionGroup>
  <Accordion title="防火墙阻止了我的连接">
    * 先通过 Tailscale VPN 连接；按设计，网关只能通过这种方式访问。
    * SSH（22 端口）始终允许。
  </Accordion>

  <Accordion title="服务无法启动">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    # 检查日志
    sudo journalctl -u openclaw -n 100

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

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

  <Accordion title="Docker 沙盒问题">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    # 验证 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
    ```
  </Accordion>

  <Accordion title="频道登录失败">
    请确保你正在以 `openclaw` 用户身份运行：

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo -i -u openclaw
    openclaw channels login --channel <name>
    ```
  </Accordion>
</AccordionGroup>

## 高级配置

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

* [安全架构](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md)
* [技术细节](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md)
* [故障排查指南](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md)

## 相关内容

* [openclaw-ansible](https://github.com/openclaw/openclaw-ansible): 完整部署指南
* [Docker](/install/docker): 容器化网关设置
* [Sandboxing](/gateway/sandboxing): 代理沙盒配置
* [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools): 按代理隔离