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