ClawPanel + OpenClaw Gateway 一体化部署最终版（含微信插件与一键验收）-大脸猫

本文整理的部署方法，基于 GitHub 上 qingchencloud 相关项目的实际使用与本地运维过程做了收敛和固化，目标是形成一套更适合长期复用、迁移和重建的一体化方案。

相关项目链接：https://github.com/qingchencloud/clawpanel

这篇文章整理了一套可长期复用的 ClawPanel + OpenClaw Gateway Docker Compose 部署方案，重点解决容器重建后依赖丢失、微信插件链路不稳定、共享数据卷保留以及部署完成后缺少统一验收手段等问题。本文最终采用的是已经过当前环境反复验证的部署方式：ClawPanel 使用自定义 Dockerfile 构建，Gateway 保持 node:22-slim 基础镜像，并在容器启动时安装 OpenClaw CLI。

前言

这次整理的目标很直接：把 ClawPanel 和 OpenClaw Gateway 的 Docker Compose 部署方式收敛成一套更稳定、可复用、可迁移的长期方案。

重点不是“手动修好一次”，而是以后在重建容器、迁移环境、换机器时，仍然能尽量通过统一目录、共享持久化数据卷和一键验收脚本，把主要风险压低。

这次重点解决的几个问题包括：

Gateway 容器重建后依赖丢失
python3 缺失导致微信插件链路不稳定
ClawPanel 与 Gateway 的共享数据结构需要保留
部署完成后缺少一套明确的一键验收手段

最终目标不是“能跑一次”，而是以后尽量不用重复踩坑。

当前部署思路

建议将部署目录固定为 /opt/clawpanel-all-in-one/。

Dockerfile.clawpanel
docker-compose.yml
verify-openclaw.sh

这套方案的核心设计思路是：

clawpanel 继续使用自定义 Dockerfile 构建
gateway 保持 node:22-slim 基础镜像，在容器启动时安装 OpenClaw CLI
两者继续共享同一个 openclaw-data 卷
把微信插件安装、启用、扫码登录与验收流程单独写清楚

适用场景说明

已经具备 Docker / Docker Compose 运行环境
需要同时部署 ClawPanel 与 OpenClaw Gateway
希望保留 OpenClaw 的持久化数据、配置、插件状态与账号状态
需要继续使用 openclaw-weixin 微信插件
希望在后续重建、迁移或换机时减少重复手工补环境的操作

注意： 对于全新环境，微信插件首次安装、启用与扫码登录仍需要人工参与；一旦插件目录和登录状态已经进入持久化数据卷，后续重建和迁移就会省心很多。

部署流程说明

为了避免把首次安装和后续重建混在一起，本文实际分成两条流程：

首次安装流程：适用于全新环境，或者共享卷里还没有微信插件与登录状态的情况。你需要完成基础部署、安装微信插件、启用插件、扫码登录、然后再做验收。
后续重建 / 升级流程：适用于 openclaw-data 卷已经保留了配置、插件和登录状态的环境。此时通常只需要重建容器和镜像，再执行验收脚本确认状态。

如果你是第一次照着这篇文章操作，请优先走首次安装流程；如果你是在已有环境基础上删容器、删镜像、重新构建，那就重点看后续重建 / 升级流程。

微信插件首次安装

如果你是全新环境，或者共享卷里还没有现成的 openclaw-weixin 插件与登录状态，那么在完成基础容器部署前后，还需要把微信插件本体安装进去。

本文使用的是腾讯官方微信插件，当前本机环境中识别到的 npm 包信息如下：

@tencent-weixin/openclaw-weixin
插件 id：openclaw-weixin

官方 README 给出的标准链路是：安装插件、启用插件、扫码登录、然后重启网关。为了和本文这套 Docker 部署方式对齐，建议在 gateway 容器内执行这些动作。

1. 在 gateway 容器内安装插件

docker compose exec -T gateway openclaw plugins install "@tencent-weixin/openclaw-weixin"

这一步会把插件安装到 OpenClaw 当前数据目录下。由于本文中的 /root/.openclaw 已经通过 openclaw-data 卷持久化，因此后续重建容器时，这个插件目录也会一并保留下来。

2. 启用插件

docker compose exec -T gateway openclaw config set plugins.entries.openclaw-weixin.enabled true

如果插件是通过标准安装流程写入的，通常会带上相应安装记录；而如果你像当前环境一样曾经通过本地代码或手工放置方式引入插件，就可能看到 loaded without install/load-path provenance 这样的 warning。这个 warning 目前确认不影响使用，但从长期维护角度看，标准安装链路更干净。

docker compose exec gateway openclaw channels login --channel openclaw-weixin

终端中会出现二维码。使用手机微信扫码并确认授权后，登录信息会自动保存在持久化数据目录中。

4. 重启网关

docker compose restart gateway

重启完成后，再执行本文后面的验收脚本，确认 openclaw-weixin=ON 且 accounts=1/1。

首次安装与后续重建的区别

首次安装时，需要显式执行插件安装、启用和扫码登录
如果共享卷 openclaw-data 已经保留了插件目录与登录状态，后续重建通常只需要重新 docker compose up -d --build，不需要每次重新安装微信插件

最终版 Dockerfile.clawpanel

FROM node:22-slim
RUN apt-get update && apt-get install -y \
 python3 \
 git \
 ca-certificates \
 && rm -rf /var/lib/apt/lists/*
# 预装 OpenClaw CLI（使用国内镜像源加速）
RUN npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com

WORKDIR /app
RUN git clone https://github.com/qingchencloud/clawpanel.git . && \
 npm install

EXPOSE 1420

RUN npm run build

CMD ["npm", "run", "serve"]

这个容器主要用于 ClawPanel，本身已经具备 python3 等基础依赖，也预装了 OpenClaw CLI，便于后续在同一套共享数据卷上配合 Gateway 使用。

最终版 docker-compose.yml

services:
  clawpanel:
    build:
      context: .
      dockerfile: Dockerfile.clawpanel
    container_name: clawpanel
    restart: always
    ports:
      - "1420:1420"
    volumes:
      - openclaw-data:/root/.openclaw
    environment:
      - NODE_ENV=production

  gateway:
    image: node:22-slim
    container_name: openclaw-gateway
    restart: always
    ports:
      - "18789:18789"
    volumes:
      - openclaw-data:/root/.openclaw
    command: >
      sh -c "npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com &&
      openclaw init 2>/dev/null || true &&
      openclaw gateway start --foreground"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  openclaw-data:

这里保持 gateway 使用你当前环境里已经多次验证成功的运行模型：容器启动后先安装 OpenClaw CLI，再执行初始化和网关前台启动。虽然这种方式不像“构建期固化镜像”那样整齐，但在当前环境下更稳，也更符合这篇文章“实测可复现优先”的目标。

这份 Compose 的核心优化点

1. ClawPanel 与 Gateway 继续共享同一个 openclaw-data 卷

这一点非常重要，因为它保留了原本的核心设计：

ClawPanel 可以直接管理 Gateway
OpenClaw 配置、插件状态、账号状态都保存在同一份持久化数据中

2. 为什么这里继续使用 restart: always

当前版本保留了你已经多次验证成功的 restart: always 行为。对这套环境来说，优先级高于“理论上更优雅的长期运维习惯”。如果后续你希望进一步调整为 unless-stopped，建议在功能完全稳定后单独验证，而不是和 gateway 启动方式改造一起进行。

3. healthcheck 只保留最小必要形式

当前健康检查继续使用你已验证成功的简单探针：curl -f http://localhost:18789/health。另外，Docker Compose v2 已不再要求顶层 version 字段，因此正式定稿中可以省略这一行，避免出现 the attribute version is obsolete 的提示。

一键验收脚本 verify-openclaw.sh

verify-openclaw.sh 不是部署完成后自动生成的文件，请先在部署目录 /opt/clawpanel-all-in-one/ 中手动创建它，再写入下面的脚本内容。

cd /opt/clawpanel-all-in-one
touch verify-openclaw.sh

创建文件后，把下面脚本正文完整写入，再执行 chmod +x verify-openclaw.sh 赋予执行权限。

#!/usr/bin/env bash
set -euo pipefail

cd /opt/clawpanel-all-in-one

echo "==> [1/4] docker compose ps"
docker compose ps

echo
if docker compose ps | grep -Eq 'gateway.+(Restarting|unhealthy)'; then
  echo "❌ gateway 容器当前未稳定运行，请先执行：docker compose logs gateway --tail=200"
  exit 1
fi

echo "==> [2/4] gateway python3 version"
docker compose exec -T gateway python3 --version

echo
echo "==> [3/4] openclaw status (inside gateway container)"
STATUS_OUTPUT="$(docker compose exec -T gateway openclaw status || true)"
echo "$STATUS_OUTPUT"

echo
echo "==> [4/4] checks"

if ! echo "$STATUS_OUTPUT" | grep -q "State.*OK"; then
  echo "❌ Gateway 状态不是 OK"
  exit 1
fi

if ! echo "$STATUS_OUTPUT" | grep -q "openclaw-weixin.*ON"; then
  echo "❌ openclaw-weixin 未显示为 ON"
  exit 1
fi

if ! echo "$STATUS_OUTPUT" | grep -q "accounts.*1/1"; then
  echo "❌ 微信账号未显示为 1/1"
  exit 1
fi

echo "✅ 验收通过：Gateway / 微信插件 / 账号状态正常"

这个脚本的意义很直接：

不再靠肉眼瞎看
不再靠记忆确认“上次是不是好的”
每次部署后跑一遍，就知道 Gateway、依赖和微信插件状态是否正常

如果 gateway 容器处于 Restarting 或 unhealthy 状态，请先查看：

docker compose logs gateway --tail=200

验收脚本用于“确认成功”，不是替代日志的根因排障工具。

使用方式

首次安装流程

如果你是全新环境，请按这个顺序走：

准备部署目录中的 Dockerfile.clawpanel、docker-compose.yml 和 verify-openclaw.sh
执行 docker compose up -d --build 完成基础容器部署
在 gateway 容器内安装并启用 openclaw-weixin
执行微信扫码登录
重启 gateway
运行 ./verify-openclaw.sh 完成验收

后续重建 / 升级流程

如果你的 openclaw-data 卷已经保留了配置、插件和登录状态，那么后续重建通常只需要：

确认没有删除 openclaw-data 卷
删除旧容器和旧镜像
重新执行 docker compose up -d --build
运行 ./verify-openclaw.sh 检查 State=OK、openclaw-weixin=ON 与 accounts=1/1

如果升级后只是微信登录状态失效，通常不需要重装插件，而是重新扫码登录即可。

重建升级前检查清单

如果你准备删除旧容器和旧镜像，再按本文流程重建升级，建议先完成下面这些检查：

确认没有删除 openclaw-data 卷。绝对不要顺手执行 docker compose down -v 或 docker volume rm openclaw-data。
先执行 docker volume ls | grep openclaw-data，确认卷确实还在。
建议在动手前备份一次卷内容，至少为回滚留后路。
先记录当前状态，例如执行 docker compose exec -T gateway openclaw status，确认原环境中的 State=OK、openclaw-weixin=ON 与 accounts=1/1。
删除容器和镜像后，重新执行 docker compose up -d --build，再运行验收脚本确认升级结果。
如果升级后只是微信登录状态失效，优先重新扫码登录，不要第一时间就判定为插件安装失败。

一句话总结：可以删容器、删镜像，但不要删卷；可以重建升级，但要先验收、后下结论。

已知事项与现实边界

已确认达成的目标

ClawPanel 与 Gateway 继续共享同一个 openclaw-data 卷
微信插件的关键前置条件和持久化状态可随卷保留
部署后可以通过脚本进行一键验收
后续重建 / 升级流程已按当前环境的成功模型回退修订

已知非阻塞 warning

当前微信链路存在一条 warning：

loaded without install/load-path provenance

目前确认它不影响实际使用，属于可以后续再优化的来源登记类问题，不是当前部署链路的阻塞故障。

这套方案不能绝对保证什么

微信永远不掉登录
上游插件永远不变
OpenClaw 新版本永远不改行为
Docker、系统环境与周边组件未来永远不引入新变量

但至少这次定稿已经以你当前环境中反复验证成功的 gateway 启动方式为基线，避免继续把未经验证的“构建期优化方案”写成默认答案。

总结

如果你的目标是：

以后换地方部署也尽量一键搞定
OpenClaw 跟着 Docker 一起准备好
微信插件继续稳定可用
部署后能快速确认功能正常

那么这套 ClawPanel + OpenClaw Gateway 的 Compose 方案，已经足够作为当前环境下的长期复用版本。

以后核心动作就可以收敛成两步：

cd /opt/clawpanel-all-in-one
docker compose up -d --build
./verify-openclaw.sh

这才叫省心。

目录CONTENT

ClawPanel + OpenClaw Gateway 一体化部署最终版（含微信插件与一键验收）

前言

当前部署思路

适用场景说明

部署流程说明

微信插件首次安装

1. 在 gateway 容器内安装插件

2. 启用插件

4. 重启网关

首次安装与后续重建的区别

最终版 Dockerfile.clawpanel

最终版 docker-compose.yml

这份 Compose 的核心优化点

1. ClawPanel 与 Gateway 继续共享同一个 openclaw-data 卷

2. 为什么这里继续使用 restart: always

3. healthcheck 只保留最小必要形式

一键验收脚本 verify-openclaw.sh

使用方式

首次安装流程

后续重建 / 升级流程

重建升级前检查清单

已知事项与现实边界

已确认达成的目标

已知非阻塞 warning

这套方案不能绝对保证什么

总结

评论区

ClawPanel + OpenClaw Gateway 一体化部署最终版（含微信插件与一键验收）

前言

当前部署思路

适用场景说明

部署流程说明

微信插件首次安装

1. 在 gateway 容器内安装插件

2. 启用插件

3. 扫码登录微信

4. 重启网关

首次安装与后续重建的区别

最终版 Dockerfile.clawpanel

最终版 docker-compose.yml

这份 Compose 的核心优化点

1. ClawPanel 与 Gateway 继续共享同一个 openclaw-data 卷

2. 为什么这里继续使用 restart: always

3. healthcheck 只保留最小必要形式

一键验收脚本 verify-openclaw.sh

使用方式

首次安装流程

后续重建 / 升级流程

重建升级前检查清单

已知事项与现实边界

已确认达成的目标

已知非阻塞 warning

这套方案不能绝对保证什么

总结

评论区