查看“︁BandwagonHost 部署 Openclaw AI Agent”︁的源代码


本文将详细介绍如何在 Debian 12 服务器上，从零开始构建一个安全、稳固的 OpenClaw AI Agent 环境。我们将涵盖系统初始化、Docker 环境构建、服务编排以及与 Telegram 的集成。

== 1. 服务器初始化 ==
在开始安装 Docker 之前，需要对新装的 Debian 12 服务器进行一系列的初始化配置。

=== 1.1 系统更新与基础工具安装 ===
首先，我们需要确保所有的系统软件包都是最新的，以修补已知的安全漏洞。
 # 更新软件包列表并升级所有已安装的包
 sudo apt update && sudo apt upgrade -y</code>
接下来，安装一系列在部署过程中必不可少的基础工具：

* 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 容器。我们将创建一个名为 <code>sysadmin</code> 的普通用户，并赋予其 sudo 权限。
 # 创建用户 (-m 创建主目录, -s 指定 shell)
 useradd -m -s /bin/bash sysadmin
 
 # 设置密码
 passwd sysadmin
 
 # 将用户加入 sudo 组
 usermod -aG sudo sysadmin</code>
<blockquote>操作提示：完成此步后，建议注销 root，使用新用户 <code>sysadmin</code> 登录系统进行后续操作。</blockquote>

=== 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</code>
安全提示：在生产环境中，建议不要直接开放 18789 端口，而是通过 Nginx 或 Caddy 配置反向代理（[https://md5.pw/index.php?title=%E5%A6%82%E4%BD%95%E6%90%AD%E5%BB%BANginx_Proxy_Manager%E5%B9%B6%E4%BD%BF%E7%94%A8%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86%E5%92%8C%E8%BF%9C%E7%A8%8B%E6%A1%8C%E9%9D%A2%E5%8A%A0%E9%80%9F 参考教程]），并通过 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 <nowiki>https://download.docker.com/linux/debian/gpg</nowiki> -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] <nowiki>https://download.docker.com/linux/debian</nowiki> \
   $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
   sudo tee /etc/apt/sources.list.d/docker.list > /dev/null</code>

=== 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'''</code>
配置权限并启动服务：
 # 启动并设置开机自启
 sudo systemctl start docker
 sudo systemctl enable docker
 
 # 将当前用户加入 docker 组 (免 sudo 执行)
 sudo usermod -aG docker $USER
 newgrp docker
 
 # 验证安装
 docker run hello-world</code>
如果终端输出了 "Hello from Docker!"，说明环境准备就绪。

== 3. OpenClaw 部署架构设计 ==
我们将所有文件集中管理在 <code>~/openclaw-deploy</code> 目录下。

=== 3.1 目录结构规划 ===
 mkdir -p ~/openclaw-deploy
 cd ~/openclaw-deploy
 mkdir -p config workspace</code>

* config/: 存储 Agent 的记忆和配置。
* workspace/: Agent 的工作台，生成的文件存放于此。

=== 3.2 环境变量配置 (.env) ===
<code>.env</code> 文件是系统的中枢神经。创建并编辑该文件：
 nano .env</code>
填入以下配置（请务必修改 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</code>
写入以下内容：
 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 <nowiki>http://localhost:18789/health</nowiki> || 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</code>

== 4. 启动服务与状态验证 ==

=== 4.1 启动 ===
在 <code>~/openclaw-deploy</code> 目录下执行：
 # 拉取镜像并后台启动
 '''docker''' compose pull
 docker compose up -d</code>

=== 4.2 验证与权限修复 ===
查看日志确认服务是否正常启动：
 '''docker compose logs -f openclaw-gateway'''</code>
如果遇到 <code>Permission denied</code> 错误，说明容器内 node 用户无法写入挂载目录，需修复权限：
 '''sudo''' chown -R 1000:1000 config workspace
 '''docker''' compose restart</code>

== 5. 连接 Telegram 神经系统 ==
OpenClaw 默认启用了配对模式 (Pairing Protocol) 以防止未授权访问。

# 发起对话：在 Telegram 中向你的 Bot 发送 <code>/start</code>。
# 获取配对码：Bot 会回复一个 6-8 位的代码，例如 <code>X7Z-9Q2</code>。
# 授权配对：回到服务器终端，执行以下命令批准请求：

 # 替换 <nowiki><CODE> 为你的配对码</nowiki>
 docker compose exec openclaw-cli '''node''' '''dist'''/index.js pairing approve telegram X7Z-9Q2</code>
当终端显示 <code>Approved telegram sender...</code> 时，恭喜你，你的专属 AI Agent 已经上线了！现在开始你有什么问题统统都可以请教它了。
[[File:999.png|center|thumb|822x822px]]

== 6. 进阶：浏览器自动化 ==
要让 Agent 具备“上网”能力，我们可以添加一个无头浏览器服务。

修改 <code>docker-compose.yml</code>，添加 <code>browser</code> 服务：
   browser:
     image: kasmweb/chrome:1.14.0
     container_name: openclaw-browser
     restart: unless-stopped
     ports:
       - "9222:9222"
     environment:
       - VNC_PW=password
     shm_size: "2gb"</code>
同时在  <code>openclaw-gateway</code> 的环境变量中添加： 
<code>- BROWSER_CDP_URL=<nowiki>http://browser:9222</nowiki></code>

重启服务后，你就可以命令 Agent：“打开 Hacker News，总结头条新闻”。

== 7. 运维与维护 ==

=== 数据备份 ===
创建一个简单的备份脚本 <code>backup.sh</code>：
 #!/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</code>
通过 <code>crontab -e</code> 设置每日备份： <code>0 3 * * * /bin/bash /home/sysadmin/openclaw-deploy/backup.sh</code>

=== 版本更新 ===
 cd ~/openclaw-deploy
 docker compose pull
 docker compose up -d
 docker image prune -f</code>