clawpanel/docs/docker-deploy.md

ClawPanel Docker 部署指南

本文介绍如何用 Docker 部署 ClawPanel Web 版，通过浏览器远程管理 OpenClaw。

ClawPanel 有 Win/Mac 桌面客户端，但 Linux 没有桌面版。Docker 部署让你在任何有 Docker 的机器上一键跑起 ClawPanel Web 管理面板。

---

目录

• 架构说明
• 方式一：快速启动
• 方式二：Docker Compose（推荐）
• 方式三：自定义 Dockerfile
• 配置与数据
• 连接 Gateway
• Nginx 反向代理
• 常用命令
• 更新升级
• 常见问题

---

架构说明

浏览器 ──HTTP──▶ ClawPanel Web 容器 (:1420)
                        │
                        ├── /__api/*   读写 ~/.openclaw/ 配置
                        ├── /ws        WebSocket 代理 → Gateway
                        └── 管理 Gateway 进程
                              │
                              ▼
              OpenClaw Gateway (容器内或宿主机, :18789)

ClawPanel Web 版 = Vite 开发服务器 + dev-api.js 后端中间件，在容器内提供完整管理功能。

---

方式一：快速启动

最简单的方式，一条命令搞定：

docker run -d \
  --name clawpanel \
  --restart unless-stopped \
  -p 1420:1420 \
  -v clawpanel-data:/root/.openclaw \
  node:22-slim \
  sh -c "\
    apt-get update && apt-get install -y git && \
    npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com && \
    openclaw init 2>/dev/null || true && \
    git clone https://github.com/qingchencloud/clawpanel.git /app && \
    cd /app && npm install && \
    npx vite --port 1420 --host 0.0.0.0"

访问 http://服务器IP:1420 即可使用。

⚠️ 这种方式每次重建容器都要重新 clone + npm install，适合快速体验。生产环境推荐使用 Compose 或自定义镜像。

---

方式二：Docker Compose（推荐）

创建 docker-compose.yml：

version: '3.8'

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

  gateway:
    image: node:22-slim
    container_name: openclaw-gateway
    restart: unless-stopped
    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:

同目录下创建 Dockerfile.clawpanel：

FROM node:22-slim

RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*

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

EXPOSE 1420

CMD ["npx", "vite", "--port", "1420", "--host", "0.0.0.0"]

启动：

docker compose up -d

这样 ClawPanel 和 Gateway 共享同一个 openclaw-data 卷，ClawPanel 可以直接管理 Gateway。

---

方式三：自定义 Dockerfile

如果只需要 ClawPanel Web（Gateway 在宿主机或其他地方运行）：

FROM node:22-slim

RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*

# 安装 OpenClaw CLI（ClawPanel 需要读写配置）
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

CMD ["npx", "vite", "--port", "1420", "--host", "0.0.0.0"]

构建并运行：

docker build -t clawpanel .
docker run -d \
  --name clawpanel \
  --restart unless-stopped \
  -p 1420:1420 \
  -v ~/.openclaw:/root/.openclaw \
  clawpanel

---

配置与数据

数据目录

ClawPanel 的所有数据都存储在 ~/.openclaw/ 目录中：

文件/目录	说明
openclaw.json	主配置文件（模型、Gateway、Agent 设置）
mcp.json	MCP 服务器配置
logs/	Gateway 日志
backups/	配置备份
agents/	Agent 数据（记忆、工作区）
devices/	设备配对信息

持久化

使用 Docker Volume 或 Bind Mount 持久化数据：

# Docker Volume（推荐）
-v clawpanel-data:/root/.openclaw

# Bind Mount（方便直接查看文件）
-v ~/.openclaw:/root/.openclaw

初始配置

首次启动如果没有 openclaw.json，可以先在容器内初始化：

docker exec -it clawpanel openclaw init

或者将已有配置挂载进去。

---

连接 Gateway

场景一：Gateway 在同一个 Compose 中

使用上面的 Compose 配置，ClawPanel 和 Gateway 共享数据卷，ClawPanel 自动通过本地回环连接 Gateway。

场景二：Gateway 在宿主机

如果 Gateway 运行在宿主机（不在 Docker 中），ClawPanel 容器需要访问宿主机网络：

docker run -d \
  --name clawpanel \
  --network host \
  -v ~/.openclaw:/root/.openclaw \
  clawpanel

使用 --network host 后，容器共享宿主机网络，ClawPanel 可以直接连接 127.0.0.1:18789。

场景三：Gateway 在远程服务器

修改 openclaw.json 中的 Gateway 端口配置，或在 ClawPanel 面板中设置 Gateway 地址。

---

Nginx 反向代理

如果希望用域名 + HTTPS 访问：

server {
    listen 80;
    server_name panel.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:1420;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

重要： 必须配置 WebSocket 升级头，否则 ClawPanel 无法通过 /ws 连接 Gateway。

---

常用命令

# 查看状态
docker ps | grep clawpanel

# 查看日志
docker logs -f clawpanel

# 进入容器
docker exec -it clawpanel bash

# 重启
docker restart clawpanel

# 停止并删除
docker stop clawpanel && docker rm clawpanel

---

更新升级

更新 ClawPanel

docker exec -it clawpanel bash -c "cd /app && git pull origin main && npm install"
docker restart clawpanel

使用 Compose 重建

docker compose build --no-cache clawpanel
docker compose up -d clawpanel

更新 OpenClaw

docker exec -it clawpanel npm install -g @qingchencloud/openclaw-zh@latest --registry https://registry.npmmirror.com

---

常见问题

Q: 容器启动后打开面板是空白？

检查容器日志：

docker logs clawpanel

确认看到 VITE ready 和 [dev-api] 开发 API 已启动 输出。

Q: 面板显示 "openclaw.json 不存在"？

在容器内初始化 OpenClaw：

docker exec -it clawpanel openclaw init

Q: Gateway 按钮不工作（Docker 环境）？

容器内管理 Gateway 进程需要特殊权限。推荐方案：

1. Compose 模式：Gateway 作为独立容器运行，用 docker compose restart gateway 管理
2. Host 网络模式：--network host 让 ClawPanel 直接管理宿主机进程

Q: 数据会丢失吗？

只要正确配置了 Volume 挂载（-v clawpanel-data:/root/.openclaw），容器删除重建不会丢失数据。

Q: 与桌面版有什么区别？

功能	桌面版 (Win/Mac)	Docker Web 版
配置管理	✅	✅
Gateway 管理	✅	⚠️ 需 host 网络或 Compose
模型测试	✅	✅
日志查看	✅	✅
备份管理	✅	✅
Agent 记忆	✅	✅
ZIP 导出	✅	❌
系统托盘	✅	❌
自动更新	✅	手动重建镜像