clawpanel

ClawPanel Linux 部署指南

本文介绍如何在 Linux 服务器上部署 ClawPanel Web 版，通过浏览器远程管理 OpenClaw、Hermes Agent、DeepSeek Harness、OpenCode 和实验版 Pi。

适用场景：云服务器、NAS、家庭 HomeLab、无 GUI 的 Linux 主机。

ClawPanel 的 Linux 服务器部署使用 Web 模式，不需要图形界面或 Tauri。桌面端与 Web 端共享前端和 API 契约，但受管引擎、系统权限和安装方式仍以部署环境为准。

---

目录

• 架构说明
• 前提条件
• 方式一：一键部署
• 方式二：手动部署
• 方式三：Docker 部署
• 访问 ClawPanel
• 进程守护
• Nginx 反向代理
• 防火墙配置
• 更新升级
• 常见问题

---

架构说明

浏览器 ──HTTP──▶ ClawPanel Web (Node.js 后端, :1420)
                        │
                        ├── /__api/*  读写 ~/.openclaw/ 配置文件
                        ├── /ws       WebSocket 代理 → Gateway
                        └── 管理 Gateway 及受管引擎进程
                              │
                              ▼
                     OpenClaw Gateway (:18789，可选)

ClawPanel Web 版 = 构建后的前端 + serve.js / dev-api.js Node.js 后端，提供：

• 配置读写（openclaw.json、mcp.json）
• Gateway 服务管理（启动/停止/重启/状态检测）
• 设备配对、模型测试、日志查看、备份管理
• WebSocket 代理到 Gateway
• 独立引擎的安装、状态和工作台代理（按引擎能力提供）

---

前提条件

依赖	最低版本	说明
Node.js	18+	基础 Web 后端；完整引擎部署推荐 24.16.0+（24.x），OpenClaw 再按已安装版本的 engines.node 检测
npm	随 Node.js	包管理器
Git	任意	克隆仓库
OpenClaw	可选	使用 OpenClaw 引擎或 Gateway 时安装；新安装默认官方稳定版

---

方式一：一键部署

curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | bash

脚本自动完成：

1. 检测系统、安装 Node.js（如果缺少）
2. 安装 OpenClaw 官方稳定版（如果缺少；可用 OPENCLAW_SOURCE=chinese 显式选择汉化版）
3. 克隆 ClawPanel 仓库、安装依赖
4. 创建 systemd 服务、开机自启
5. 启动 ClawPanel Web，输出访问地址

如需离线/压缩包部署，请从 GitHub Release 下载 web-x.y.z.zip 完整 Web 服务端包。frontend-hot-update-x.y.z.zip 仅包含桌面端热更新前端，不能替代 Web 后端。

部署完成后访问 http://服务器IP:1420，然后在左侧选择需要使用的引擎。Pi、OpenCode 和 DSH 的运行时可从各自「运行与配置」页安装；Docker 预装 OpenClaw 不代表其他引擎已安装。

---

方式二：手动部署

1. 安装 Node.js

Ubuntu / Debian：

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

CentOS / RHEL / Fedora：

curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo yum install -y nodejs

Alpine：

apk add nodejs npm git

验证安装：

node -v   # v24.x.x
npm -v    # 10.x.x

2. 安装 OpenClaw

使用 OpenClaw 引擎时需要安装并初始化 OpenClaw；只使用其他独立引擎时可跳过此步骤：

npm install -g openclaw@2026.9.8 --registry https://registry.npmmirror.com

如需汉化版：

npm install -g @qingchencloud/openclaw-zh@2026.7.1-2-zh.1 --registry https://registry.npmmirror.com

初始化配置（首次）：

openclaw init

3. 克隆 ClawPanel

cd /opt
sudo git clone https://github.com/qingchencloud/clawpanel.git
sudo chown -R $(whoami) clawpanel
cd clawpanel
npm ci

国内网络可使用 AtomGit 镜像：

sudo git clone https://atomgit.com/qingchencloud/clawpanel.git

4. 构建并启动 ClawPanel Web

npm run build    # 构建生产版前端
npm run serve    # 启动 Web 服务器 (默认 0.0.0.0:1420)

自定义端口：

npm run serve -- --port 8080

看到以下输出即为成功：

  ┌─────────────────────────────────────────┐
  │   🦀 ClawPanel Web Server (Headless)    │
  │   http://localhost:1420/                │
  └─────────────────────────────────────────┘
  [api] API 已启动，配置目录: /root/.openclaw

打开浏览器访问 http://服务器IP:1420 即可使用 ClawPanel。

---

方式三：Docker 部署

📖 Docker 完整教程（Compose、自定义镜像、数据持久化等）见 Docker 部署指南

快速启动：

docker run -d \
  --name clawpanel \
  --restart unless-stopped \
  -p 1420:1420 \
  -v clawpanel-data:/root/.openclaw \
  node:24.16.0-slim \
  sh -c "apt-get update && apt-get install -y git && \
    npm install -g openclaw@2026.9.8 --registry https://registry.npmmirror.com && \
    git clone https://github.com/qingchencloud/clawpanel.git /app && \
    cd /app && npm ci && npm run build && npm run serve"

---

访问 ClawPanel

部署完成后，用浏览器打开：

http://服务器IP:1420

ClawPanel 会自动检测本机的 OpenClaw 安装，你可以：

• 管理模型配置（添加/删除/测试 Provider）
• 启动/停止/重启 Gateway
• 查看 Gateway 日志
• 管理 Agent 记忆文件
• 配置备份与恢复

---

进程守护

前台运行会在终端关闭后退出，推荐用 systemd 或 PM2 保持常驻。

方式一：systemd（推荐）

创建服务文件：

# 先确认 node 的实际路径（不同安装方式路径不同）
which node
# 常见路径：/usr/bin/node、/usr/local/bin/node、~/.nvm/versions/node/vXX/bin/node

sudo tee /etc/systemd/system/clawpanel.service << EOF
[Unit]
Description=ClawPanel Web - OpenClaw Management Panel
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/clawpanel
ExecStart=$(which node) scripts/serve.js
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production
Environment=PATH=/usr/local/bin:/usr/bin:/bin:$(dirname $(which node)):$(dirname $(which openclaw 2>/dev/null || echo /usr/local/bin/openclaw))

[Install]
WantedBy=multi-user.target
EOF

⚠️ 注意：ExecStart 必须使用 Node.js 的绝对路径。systemd 不继承用户的 PATH 环境变量，所以 node 这种相对路径会找不到。上面的 $(which node) 会在创建服务时自动替换为实际路径。Environment=PATH=... 确保 OpenClaw CLI 也能被找到。

启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable clawpanel
sudo systemctl start clawpanel

常用命令：

sudo systemctl status clawpanel    # 查看状态
sudo systemctl restart clawpanel   # 重启
sudo journalctl -u clawpanel -f    # 查看日志

方式二：PM2

npm install -g pm2

cd /opt/clawpanel
npm run build
pm2 start "npm run serve" --name clawpanel
pm2 save
pm2 startup    # 开机自启

---

Nginx 反向代理

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

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 升级（Upgrade + Connection），否则 ClawPanel 无法连接 Gateway。

配合 Let’s Encrypt 启用 HTTPS：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d panel.yourdomain.com

---

防火墙配置

UFW (Ubuntu/Debian)

sudo ufw allow 1420/tcp    # ClawPanel Web
sudo ufw allow 18789/tcp   # OpenClaw Gateway（如需外部直连）

firewalld (CentOS/RHEL)

sudo firewall-cmd --permanent --add-port=1420/tcp
sudo firewall-cmd --reload

---

更新升级

更新 ClawPanel

推荐直接重新运行部署脚本。必须与原安装权限保持一致：

# 系统级安装（/opt/clawpanel）
curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | sudo bash

# 普通用户安装（~/.local/share/clawpanel）
curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | bash

脚本会自动读取 systemd 服务的 WorkingDirectory，更新实际运行的目录，并在构建后重启对应服务。拉取失败、存在未提交修改或权限模式不匹配时，脚本会停止并显示具体原因。

手动升级：

cd /opt/clawpanel        # root 部署路径
# 或 ~/.local/share/clawpanel  # 普通用户路径

git status --short       # 有输出时先处理本地修改
git pull --ff-only origin main
npm ci --registry https://registry.npmmirror.com
npm run build
node -p "require('./package.json').version"  # 核对实际源码版本
sudo systemctl restart clawpanel  # 或 pm2 restart clawpanel

普通用户 systemd 服务使用 systemctl --user restart clawpanel。升级后浏览器仍显示旧页面时，使用 Ctrl+F5 强制刷新。

不要只替换 dist/：Web 版的页面、Node API 与 WebSocket 代理必须同步升级。完整 Web 包内含 scripts/、src/lib/、版本策略和依赖清单；启动时 /__api/health 会核对前后端版本。

国内拉不到 GitHub？可切换到 AtomGit 镜像：

git remote set-url origin https://atomgit.com/qingchencloud/clawpanel.git
git pull --ff-only origin main

更新 OpenClaw

方式一：在 ClawPanel 面板中操作（推荐）

打开「关于」页面 → 点击版本管理，优先切换到当前面板绑定的推荐稳定版。面板会自动处理 sudo 权限、镜像源与 Git HTTPS 兼容。

版本策略说明：ClawPanel 会按面板版本绑定一组 OpenClaw 推荐稳定版，避免老面板直接管理最新版带来的兼容性风险。如需尝试最新版，请在「关于」页手动切换版本，并自行验证兼容性。

方式二：命令行手动升级

# 官方原版（当前新安装默认）
sudo npm install -g openclaw@2026.9.8 --registry https://registry.npmmirror.com

# 汉化版（按策略文件中的兼容版本）
sudo npm install -g @qingchencloud/openclaw-zh@2026.7.1-2-zh.1 --registry https://registry.npmmirror.com

# 国内镜像失败时，再切 npm 官方源重试
sudo npm install -g openclaw@2026.9.8 --registry https://registry.npmjs.org

维护说明：如果你是 ClawPanel 维护者，后续只需要更新仓库根目录的 openclaw-version-policy.json，即可统一调整不同面板版本对应的推荐 OpenClaw 版本。桌面端程序版本以 package.json 为唯一真相源，运行 npm run version:sync 同步到 Tauri 配置；docs/update/latest.json 仅保留给旧版前端热更新兼容链路。

权限说明：Linux 全局 npm 包安装需要 root 权限。ClawPanel 现已自动检测非 root 用户并加 sudo，同时会自动补 GitHub HTTPS rewrite 规则；如仍遇权限问题，手动加 sudo 即可。

更新频率

• ClawPanel：git pull 获取最新代码，无需重新安装依赖（除非 package.json 变了）
• OpenClaw：优先通过面板切换到策略文件中的推荐稳定版；如需尝试其它版本，请在「关于」页手动切换并验证 Gateway
• 其他引擎：在各自「运行与配置」页检查版本、更新或卸载；模型渠道需要重新显式同步
• ClawPanel 桌面版：通过官网版本接口发现新版本，下载推荐完整安装包后覆盖安装
• 前端热更新：仅保留旧版本兼容和回滚目录处理，新版用户界面不再作为主更新入口展示

---

常见问题

Q: 端口 1420 被占用？

# 查看占用
lsof -i :1420

# 使用其他端口
npm run serve -- --port 3000

systemd 服务也需要改 ExecStart 中的端口。

Q: 打开面板显示 “openclaw.json 不存在”？

使用 OpenClaw 引擎时需要先安装并初始化 OpenClaw；只使用其他独立引擎时不需要为它们额外安装 OpenClaw：

npm install -g openclaw@2026.9.8 --registry https://registry.npmmirror.com
openclaw init

Q: Gateway 启动/停止按钮不工作？

ClawPanel Web 版在 Linux 上通过 child_process 管理进程。确保：

• openclaw 命令在 PATH 中
• 运行 ClawPanel 的用户有权限操作进程

which openclaw   # 应输出路径
openclaw --version

Q: 从外网无法访问？

1. 检查防火墙是否放行端口 1420
2. 云服务器需在安全组/防火墙规则中开放端口
3. 推荐使用 Nginx 反向代理 + HTTPS，避免直接暴露端口

Q: 如何同时启动 Gateway 和 ClawPanel？

Gateway 和 ClawPanel 是独立进程，需要分别启动：

# 启动 Gateway（后台）
openclaw gateway start &

# 启动 ClawPanel Web
cd /opt/clawpanel
npm run serve

或者用 systemd 分别创建两个服务。也可以在 ClawPanel 面板中直接点击「启动」按钮管理 Gateway。

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

功能	桌面版 (Win/Mac)	Web 版 (Linux)
配置管理	✅	✅
Gateway 管理	✅	✅
模型测试	✅	✅
日志查看	✅	✅
备份管理	✅	✅
Agent 记忆	✅	✅
ZIP 导出	✅	❌
系统托盘	✅	❌
自动更新	✅	手动 git pull

This site is open source. Improve this page.