Skip to content
OpenClaw Docs

Ansible

使用 openclaw-ansible 將 OpenClaw 部署到生產伺服器——這是一個採用安全優先架構的自動安裝程式。

先決條件

Section titled “先決條件”
需求詳細資訊
作業系統Debian 11+ 或 Ubuntu 20.04+
存取權限Root 或 sudo 權限
網路用於安裝套件的網際網路連線
Ansible2.14+ (會由快速入門腳本自動安裝)

安裝內容

Section titled “安裝內容”
  • 防火牆優先的安全機制 — UFW + Docker 隔離 (僅開放 SSH + Tailscale 存取)
  • Tailscale VPN — 安全的遠端存取，無需公開暴露服務
  • Docker — 隔離的沙箱容器，僅綁定 localhost
  • 縱深防禦 — 4 層安全架構
  • Systemd 整合 — 開機自動啟動並進行安全強化
  • 單一指令設定 — 幾分鐘內完成完整部署

快速入門

Section titled “快速入門”

單一指令安裝：

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

安裝項目

Section titled “安裝項目”

此 Ansible playbook 會安裝並設定：

  1. Tailscale — 用於安全遠端存取的網狀 VPN
  2. UFW 防火牆 — 僅開放 SSH + Tailscale 連接埠
  3. Docker CE + Compose V2 — 用於預設的 Agent 沙箱後端
  4. Node.js 24 + pnpm — 運行時相依套件（Node 22 LTS，目前為 22.19+，仍受支援）
  5. OpenClaw — 基於主機，而非容器化
  6. Systemd 服務 — 開機自動啟動並進行安全強化

安裝後設定

Section titled “安裝後設定”

  1. 切換到 openclaw 使用者

    bash sudo -i -u openclaw

  2. 執行上線精靈

    安裝後腳本會引導您完成 OpenClaw 的設定。

  3. 連結訊息服務提供商

    登入 WhatsApp、Telegram、Discord 或 Signal： bash openclaw channels login

  4. 驗證安裝

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

  5. 連線至 Tailscale

    加入您的 VPN 網狀網路以進行安全的遠端存取。

快速指令

Section titled “快速指令”
Terminal window
# Check service status
sudo systemctl status openclaw


# View live logs
sudo journalctl -u openclaw -f


# Restart gateway
sudo systemctl restart openclaw


# Provider login (run as openclaw user)
sudo -i -u openclaw
openclaw channels login

安全架構

Section titled “安全架構”

此部署使用 4 層防禦模型：

  1. 防火牆 (UFW) — 僅公開 SSH (22) + Tailscale (41641/udp)
  2. VPN (Tailscale) — 閘道僅可透過 VPN 網狀網路存取
  3. Docker 隔離 — DOCKER-USER iptables 鏈可防止外部連接埠暴露
  4. Systemd 加固 — NoNewPrivileges、PrivateTmp、非特權使用者

若要驗證您的外部攻擊面：

Terminal window
nmap -p- YOUR_SERVER_IP

僅應開放連接埠 22 (SSH)。所有其他服務 (閘道、Docker) 均已鎖定。

安裝 Docker 是為了代理沙盒 (隔離工具執行)，而非用於執行閘道本身。請參閱 Multi-Agent Sandbox and Tools 以了解沙盒設定。

手動安裝

Section titled “手動安裝”

如果您偏好對自動化進行手動控制：

  1. 安裝先決條件

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

  2. 複製儲存庫

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

  3. 安裝 Ansible collections

    Terminal window
    ansible-galaxy collection install -r requirements.yml

  4. 執行 playbook

    Terminal window
    ./run-playbook.sh

    或者，直接執行然後手動執行設定腳本：

    /tmp/openclaw-setup.sh
    ansible-playbook playbook.yml --ask-become-pass

更新

Section titled “更新”

Ansible 安裝程式會將 OpenClaw 設定為手動更新。請參閱 Updating 以了解標準更新流程。

若要重新執行 Ansible playbook (例如，進行設定變更)：

Terminal window
cd openclaw-ansible
./run-playbook.sh

這是等冪 的，且可安全地多次執行。

疑難排解

Section titled “疑難排解”
防火牆阻擋我的連線
  • 請確保您能先透過 Tailscale VPN 存取
  • SSH 存取 (連接埠 22) 始終允許
  • 依設計，閘道僅能透過 Tailscale 存取
服務無法啟動
Terminal window
# 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
Docker sandbox issues
Terminal window
# Verify Docker is running
sudo systemctl status docker


# Check sandbox image
sudo docker images | grep openclaw-sandbox


# Build sandbox image if missing (requires 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
供應商登入失敗

請確保您正以 openclaw 使用者身分執行：

Terminal window
sudo -i -u openclaw
openclaw channels login

進階設定

Section titled “進階設定”

如需詳細的安全架構與疑難排解資訊，請參閱 openclaw-ansible 儲存庫：

相關

Section titled “相關”