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：隔離的 sandbox 容器，僅綁定 localhost
縱深防禦：4 層安全架構
一行指令設定：幾分鐘內完成部署
Systemd 整合：開機自動啟動並強化安全

需求

作業系統：Debian 11+ 或 Ubuntu 20.04+
存取權限：root 或 sudo 權限
網路：網際網路連線（安裝套件用）
Ansible：2.14+（快速開始腳本會自動安裝）

安裝內容

Ansible playbook 會安裝並設定：

Tailscale（mesh VPN，用於安全遠端存取）
UFW 防火牆（僅 SSH + Tailscale 連接埠）
Docker CE + Compose V2（用於 agent sandbox）
Node.js 24 + pnpm（runtime 相依套件；Node 22 LTS，目前 22.16+，仍受支援）
OpenClaw（主機式安裝，非容器化）
Systemd 服務（開機自啟動，含安全強化）

閘道直接在主機上執行（不在 Docker 中），但 agent sandbox 使用 Docker 進行隔離。詳情請見 Sandboxing。

安裝後設定

安裝完成後，切換到 openclaw 使用者：

sudo -i -u openclaw

安裝後腳本會引導你完成：

設定精靈：設定 OpenClaw 參數
供應商登入：連接 WhatsApp/Telegram/Discord/Signal
閘道測試：驗證安裝
Tailscale 設定：連接到 VPN mesh

常用指令

# 檢查服務狀態
sudo systemctl status openclaw

# 即時檢視日誌
sudo journalctl -u openclaw -f

# 重啟閘道
sudo systemctl restart openclaw

# 供應商登入（以 openclaw 使用者執行）
sudo -i -u openclaw
openclaw channels login

安全架構

4 層防禦

防火牆（UFW）：僅公開 SSH（22）+ Tailscale（41641/udp）
VPN（Tailscale）：閘道僅透過 VPN mesh 可存取
Docker 隔離：DOCKER-USER iptables chain 阻止外部連接埠暴露
Systemd 強化：NoNewPrivileges、PrivateTmp、非特權使用者

驗證

測試外部攻擊面：

nmap -p- YOUR_SERVER_IP

應只顯示連接埠 22（SSH）開啟。所有其他服務（閘道、Docker）都已鎖定。

Docker 用途

Docker 是為了 agent sandbox（隔離的工具執行）而安裝，不是用來執行閘道本身。閘道僅綁定 localhost，透過 Tailscale VPN 存取。

詳情請見 Multi-Agent Sandbox & Tools。

手動安裝

如果你偏好手動控制而非自動化：

# 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 collection
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 安裝程式會設定 OpenClaw 為手動更新。標準更新流程請見更新。

重新執行 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 sandbox 問題

# 驗證 Docker 執行中
sudo systemctl status docker

# 檢查 sandbox 映像
sudo docker images | grep openclaw-sandbox

# 如果缺少則建置 sandbox 映像
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh

供應商登入失敗

確認以 openclaw 使用者身分執行：

sudo -i -u openclaw
openclaw channels login

進階設定

詳細安全架構和疑難排解：