BandwagonHost 部署 Openclaw AI Agent

本文將詳細介紹如何在 Debian 12 伺服器上，從零開始構建一個安全、穩固的 OpenClaw AI Agent 環境。我們將涵蓋系統初始化、Docker 環境構建、服務編排以及與 Telegram 的集成。

1. 伺服器初始化

在開始安裝 Docker 之前，需要對新裝的 Debian 12 伺服器進行一系列的初始化配置。

1.1 系統更新與基礎工具安裝

首先，我們需要確保所有的系統軟件包都是最新的，以修補已知的安全漏洞。

# 更新软件包列表并升级所有已安装的包
sudo apt update && sudo apt upgrade -y

接下來，安裝一系列在部署過程中必不可少的基礎工具：

curl & wget: 用於從網絡下載安裝腳本。
git: 用於拉取代碼倉庫。
htop & net-tools: 系統監控工具。

sudo apt install -y curl wget git nano ca-certificates gnupg lsb-release htop net-tools ufw

1.2 創建非 Root 用戶

出於安全考慮，絕對不建議直接以 root 用戶身份運行 Docker 容器。我們將創建一個名為 sysadmin 的普通用戶，並賦予其 sudo 權限。

# 创建用户 (-m 创建主目录, -s 指定 shell)
useradd -m -s /bin/bash sysadmin

# 设置密码
passwd sysadmin

# 将用户加入 sudo 组
usermod -aG sudo sysadmin

操作提示：完成此步後，建議註銷 root，使用新用戶 sysadmin 登錄系統進行後續操作。

1.3 防火牆 (UFW) 策略配置

為了最大程度減少暴露，我們需要配置 UFW 防火牆。OpenClaw 默認監聽 18789 (Gateway) 和 18790 (Bridge) 端口。

# 默认拒绝所有传入，允许所有传出
sudo ufw default deny incoming
sudo ufw default allow outgoing

# 允许 SSH (非常重要！否则会断连)
sudo ufw allow 22/tcp

# 允许 HTTP/HTTPS (用于后续反向代理)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 启用防火墙
sudo ufw enable

安全提示：在生產環境中，建議不要直接開放 18789 端口，而是通過 Nginx 或 Caddy 配置反向代理（參考教程），並通過 443 端口訪問。

2. Docker 引擎與 Compose 插件部署

為了確保對最新容器特性的支持，建議使用 Docker 官方倉庫進行安裝。

2.1 清理舊版本與配置倉庫

如果系統預裝了舊版的 docker，先進行清理，然後配置官方 GPG 密鑰。

# 清理旧版本
sudo apt-get remove docker.io docker-doc docker-compose podman-docker containerd runc

# 创建密钥目录
sudo install -m 0755 -d /etc/apt/keyrings

# 下载官方 GPG 密钥
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 写入软件源
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

2.2 安裝並驗證 Docker

安裝 Docker Engine 及最新的 Compose 插件：

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

配置權限並啟動服務：

# 启动并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 将当前用户加入 docker 组 (免 sudo 执行)
sudo usermod -aG docker $USER
newgrp docker

# 验证安装
docker run hello-world

如果終端輸出了 "Hello from Docker!"，說明環境準備就緒。

3. OpenClaw 部署架構設計

我們將所有文件集中管理在 ~/openclaw-deploy 目錄下。

3.1 目錄結構規劃

mkdir -p ~/openclaw-deploy
cd ~/openclaw-deploy
mkdir -p config workspace

config/: 存儲 Agent 的記憶和配置。
workspace/: Agent 的工作枱，生成的文件存放於此。

3.2 環境變量配置 (.env)

.env 文件是系統的中樞神經。創建並編輯該文件：

nano .env

填入以下配置（請務必修改 Token 和 API Key）：

# =========================================
# OpenClaw 核心配置
# =========================================
OPENCLAW_IMAGE=coollabsio/openclaw:latest

# 网关安全令牌 (必须修改的一项！)
# 生成命令: openssl rand -hex 32
OPENCLAW_GATEWAY_TOKEN=请填入您的64位随机十六进制字符串

OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_BIND=lan

# =========================================
# AI 模型提供商 (LLM Providers)
# =========================================
# 示例：使用 Anthropic
ANTHROPIC_API_KEY=sk-ant-api03-...
# 或者 OpenAI
# OPENAI_API_KEY=sk-...

# =========================================
# 渠道配置：Telegram 集成
# =========================================
# 通过 @BotFather 获取
TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIjkLmnOpqRsTuVwXyZ
TELEGRAM_DM_POLICY=pairing
# TELEGRAM_ALLOWED_USERS=你的TelegramID

3.3 核心編排文件 (docker-compose.yml)

我們需要一個增強版的 Compose 文件來確保服務高可用。

nano docker-compose.yml

寫入以下內容：

services:
  # 服务一：OpenClaw Gateway (核心网关)
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE:-coollabsio/openclaw:latest}
    container_name: openclaw-gateway
    restart: unless-stopped
  
    env_file:
      - .env
  
    environment:
      - HOME=/home/node
      - TERM=xterm-256color
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT:-18789}
      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND:-lan}
    
    volumes:
      - ./config:/home/node/.openclaw
      - ./workspace:/home/node/.openclaw/workspace

    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"

    init: true

    healthcheck:
      test: curl --fail http://localhost:18789/health || exit 1
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s

  # 服务二：OpenClaw CLI (管理工具)
  openclaw-cli:
    image: ${OPENCLAW_IMAGE:-coollabsio/openclaw:latest}
    container_name: openclaw-cli
    env_file:
      - .env
    volumes:
      - ./config:/home/node/.openclaw
      - ./workspace:/home/node/.openclaw/workspace
    entrypoint: ["tail", "-f", "/dev/null"]
    init: true

4. 啟動服務與狀態驗證

4.1 啟動

在 ~/openclaw-deploy 目錄下執行：

# 拉取镜像并后台启动
docker compose pull
docker compose up -d

4.2 驗證與權限修復

查看日誌確認服務是否正常啟動：

docker compose logs -f openclaw-gateway

如果遇到 Permission denied 錯誤，說明容器內 node 用戶無法寫入掛載目錄，需修復權限：

sudo chown -R 1000:1000 config workspace
docker compose restart

5. 連接 Telegram 神經系統

OpenClaw 默認啟用了配對模式 (Pairing Protocol) 以防止未授權訪問。

發起對話：在 Telegram 中向你的 Bot 發送 /start。
獲取配對碼：Bot 會回復一個 6-8 位的代碼，例如 X7Z-9Q2。
授權配對：回到伺服器終端，執行以下命令批准請求：

# 替换 <CODE> 为你的配对码
docker compose exec openclaw-cli node dist/index.js pairing approve telegram X7Z-9Q2

當終端顯示 Approved telegram sender... 時，恭喜你，你的專屬 AI Agent 已經上線了！現在開始你有什麼問題統統都可以請教它了。

6. 進階：瀏覽器自動化

要讓 Agent 具備「上網」能力，我們可以添加一個無頭瀏覽器服務。

修改 docker-compose.yml，添加 browser 服務：

  browser:
    image: kasmweb/chrome:1.14.0
    container_name: openclaw-browser
    restart: unless-stopped
    ports:
      - "9222:9222"
    environment:
      - VNC_PW=password
    shm_size: "2gb"

同時在 openclaw-gateway 的環境變量中添加： - BROWSER_CDP_URL=http://browser:9222

重啟服務後，你就可以命令 Agent：「打開 Hacker News，總結頭條新聞」。

7. 運維與維護

數據備份

創建一個簡單的備份腳本 backup.sh：

#!/bin/bash
BACKUP_DIR="/home/sysadmin/backups"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/openclaw_backup_$DATE.tar.gz -C /home/sysadmin/openclaw-deploy config workspace
# 删除 7 天前的备份
find $BACKUP_DIR -name "openclaw_backup_*.tar.gz" -mtime +7 -delete

通過 crontab -e 設置每日備份： 0 3 * * * /bin/bash /home/sysadmin/openclaw-deploy/backup.sh

版本更新

cd ~/openclaw-deploy
docker compose pull
docker compose up -d
docker image prune -f