clawpanel

ClawPanel 是支持多 AI Agent 框架的可视化管理面板，目前支持 OpenClaw、Hermes Agent、DeepSeek Harness、OpenCode 和实验版 Pi。内置智能 AI 助手，帮你一键安装、自动诊断配置、排查问题、修复错误。8 大工具 + 4 种模式 + 交互式问答，从新手到老手都能轻松管理。

🌐 官网: claw.qt.cool | 📦 下载: 官网下载中心 | 📚 文档: 文档导航 | 备用: GitHub Releases | 国内镜像: AtomGit

🧪 DeepSeek Harness：面板内完成配置与实际操作

• 受管运行时 — 在“运行与配置”页面安装、启动、停止和卸载固定验收版本，不污染全局 npm 环境；稳定版默认使用 0.2.0-rc.2，可显式安装 0.2.1-alpha.2 Alpha 候选版并随时切回稳定版。
• 独立工作台 — 通过左侧“工作台”进入完整 DSH Web 界面，直接对话、选择工作区、切换模型和管理会话。
• 统一模型渠道 — 将 Provider、API Key、上下文窗口、输出上限和默认模型从 ClawPanel 同步到 DSH，并回读确认结果。
• Web/headless 安全内嵌 — DSH 保持回环监听，远程 Web 版通过短期令牌和沙箱代理使用完整界面，无需额外开放公网端口。

✨ Hermes Agent：会话、记忆、人格与工具全景管理

把 Agent 从一次性聊天窗口，升级为可持续运营的智能体系统。

查看 Hermes Agent 图文指南 →

  [![Hermes Agent 控制台](docs/h00.png)](docs/h00.png)

  控制台总览

  

查看运行状态、入口能力和主要管理模块。

  [![Hermes Agent 长期记忆](docs/h01.png)](docs/h01.png)

  长期记忆

  

Notes / User Profile / Soul 三份 Markdown 沉淀上下文。

  [![Hermes Agent 会话与消息流](docs/h02.png)](docs/h02.png)

  会话与消息流

  

追踪对话过程、上下文质量和真实运行表现。

  [![Hermes Agent 工具与运行细节](docs/h03.png)](docs/h03.png)

  工具与运行细节

  

定位工具调用、运行步骤和 Agent 执行链路。

• 长期记忆可视化 — 在线编辑 Notes、User Profile、Soul，让事实、偏好与人格持续沉淀。
• 会话可运营 — 统一查看对话、消息流、运行状态和工具调用细节。
• 人格可维护 — 把 Agent 的表达风格、价值观和偏好固化为可编辑资产。
• 渠道可扩展 — 面向 QQ、Telegram、Discord 等外部渠道集中管理连接能力。

🧪 免费测试：晴辰云

晴辰云是 ClawPanel 配套的免费签到测试平台，适合模型体验和功能验证。ClawPanel 不内置或自动读取晴辰云密钥；请自行注册并前往签到页领取测试额度与 API Key，再手动粘贴到 ClawPanel 选择模型并一键配置。具体开放状态和额度规则以晴辰云页面为准。

🤝 赞助推广：词元 API

第三方赞助推广，具体规则以词元 API 页面为准。


• 主流前沿模型 — 支持 GPT、Claude、Gemini、Grok、Kimi 等模型
• 充值福利 — 充值 ¥1 到账 $1 平台额度
• 模型折扣 — 部分线路按折扣计费，具体以模型广场为准
• OpenAI Compatible — 获取 API Key 后可在 ClawPanel 中一键接入

配合 OpenClaw 使用：在 词元 API 注册并获取 API Key，选择 OpenAI Compatible 提供商，Base URL 填写 https://ciyapi.79tian.com/v1。可前往模型广场查看实时模型和价格。

🔥 开发板 / 嵌入式设备支持

ClawPanel 提供纯 Web 版部署模式（零 GUI 依赖），天然兼容 ARM64 开发板和嵌入式设备：

• Orange Pi / 树莓派 / RK3588 等 ARM64 板子 — npm run serve 即可运行
• Docker ARM64 — 使用仓库 Dockerfile 本地构建，详见 ARM 部署指南
• Armbian / Debian / Ubuntu Server — 一键部署脚本自动检测架构
• 无需 Rust / Tauri / 图形界面；基础 Web 后端需要 Node.js 18+，完整引擎部署推荐 Node.js 24.16.0+（24.x），运行 OpenClaw Gateway 时会按已安装版本的 engines.node 自动检测

📖 详见 Armbian 部署指南 | Web 版开发说明

社区交流

一群对 AI Agent 充满热情的开发者和玩家，欢迎加入交流。

  [![QQ 群二维码](docs/qr-qq.png "os:140x")](https://qt.cool/c/OpenClaw)

  [QQ 群](https://qt.cool/c/OpenClaw)




  [![微信群二维码](docs/qr-wechat.png "os:140x")](https://qt.cool/c/OpenClawWx)

  [微信群](https://qt.cool/c/OpenClawWx)




  [![抖音群二维码](docs/qr-dy.png "os:140x")](https://qt.cool/c/OpenClawDY)

  [抖音群](https://qt.cool/c/OpenClawDY)




  [![飞书群二维码](https://qt.cool/c/feishu/qr.png "os:140x")](https://qt.cool/c/feishu)

  [飞书群](https://qt.cool/c/feishu)

Discord  ·  Telegram 群  ·  元宝派  ·  Discussions  ·  反馈 Issue  ·  飞书群

下载安装

前往 官网下载中心 下载最新版本。页面会自动识别系统，也可以手动选择 Windows、macOS 或 Linux 安装包；GitHub Releases 作为备用下载入口保留。

macOS

不确定芯片类型？点击左上角 → 关于本机，查看「芯片」一栏。

安装方式：打开 .dmg 文件，先将 ClawPanel 拖入「应用程序」文件夹，再双击打开。

⚠️ 首次打开提示"已损坏"或"无法验证开发者"？ 由于应用未签名，macOS 会拦截。请在终端执行以下命令解除限制：

sudo xattr -rd com.apple.quarantine /Applications/ClawPanel.app

或者前往「系统设置 → 隐私与安全性」，找到 ClawPanel 点击「仍要打开」。

提示 No such file？说明没有拖入应用程序文件夹。请先拖入，或改用：

sudo xattr -rd com.apple.quarantine ~/Downloads/ClawPanel.app

Windows

Linux

Linux 服务器（Web 版）

没有桌面环境？一键部署 ClawPanel Web 版，通过浏览器远程管理多个引擎：

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

部署脚本的新安装默认使用官方稳定版 OpenClaw；如需汉化版可显式执行 curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | OPENCLAW_SOURCE=chinese bash。 部署完成后访问 http://服务器IP:1420，再在左侧选择需要的引擎。模型测试、工作目录和引擎进程都在服务器上执行；各引擎不保证功能完全相同。

也可以从 GitHub Release 下载 web-x.y.z.zip 完整 Web 服务端包。升级时必须整体替换前端与 Node 后端并重启服务；frontend-hot-update-x.y.z.zip 只供桌面端热更新，不能用于 Web 服务器部署。

📖 详细教程见 Linux 部署指南

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 [email protected] --registry https://registry.npmmirror.com && \
    git clone https://github.com/qingchencloud/clawpanel.git /app && \
    cd /app && npm ci && npm run build && npm run serve"

📖 详细教程见 Docker 部署指南（含 Compose、自定义镜像、Nginx 反向代理等）

升级面板

ClawPanel 提供多种升级方式，根据你的安装方式选择对应方案。

macOS / Windows 桌面版升级

桌面版会通过官网 API 检查新版本。发现新版本后，面板会推荐适合当前系统的完整安装包：

1. 打开 ClawPanel，如有新版本会弹出升级提示
2. 点击「下载推荐安装包」，浏览器会从官网镜像下载文件
3. 退出 ClawPanel，按系统安装器提示覆盖安装
4. 也可前往「关于」页面手动检查更新

手动升级：如果官网下载失败，可前往 GitHub Releases 下载最新安装包，覆盖安装即可。数据不会丢失。

Linux 桌面版升级

Linux Web 版升级

方式一：一键升级脚本（推荐）

系统级安装（/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 服务的实际工作目录，使用 git pull --ff-only 拉取代码，重新构建并重启服务。Git 拉取失败、本地存在未提交修改或权限模式不匹配时会明确报错并停止，不会继续用旧源码构建。

方式二：手动升级

cd /opt/clawpanel  # 替换为实际安装目录
git status --short  # 有输出时先处理本地修改
git pull --ff-only origin main
npm ci
npm run build
node -p "require('./package.json').version"  # 应输出最新版本
sudo systemctl restart clawpanel

普通用户服务将最后一行替换为 systemctl --user restart clawpanel。升级后如果浏览器仍显示旧版本，请使用 Ctrl+F5 强制刷新。

重要：Web 版不能只覆盖 dist/。页面前端、scripts/dev-api.js 和 WebSocket 代理必须保持同一版本；新版会在 /__api/health 自动核对前后端版本，不一致时会停止加载并提示安装完整 Web 包。

升级 OpenClaw：面板和 OpenClaw 版本需要匹配。可在「服务管理」页面一键升级，或手动执行：

sudo npm install -g [email protected] --registry https://registry.npmmirror.com

汉化版仍可显式安装：sudo npm install -g @qingchencloud/[email protected] --registry https://registry.npmmirror.com。

Docker 升级

Docker Compose 方式（推荐）

cd /path/to/clawpanel  # 包含 docker-compose.yml 的目录
docker compose build --no-cache clawpanel
docker compose up -d clawpanel

docker run 方式

# 停止并删除旧容器（数据保存在 Volume 中不会丢失）
docker stop clawpanel
docker rm clawpanel

# 重新启动新容器
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 [email protected] --registry https://registry.npmmirror.com && \
    git clone https://github.com/qingchencloud/clawpanel.git /app && \
    cd /app && npm ci && npm run build && npm run serve"

仅升级容器内的 OpenClaw

docker exec -it clawpanel npm install -g [email protected] --registry https://registry.npmmirror.com

macOS / Windows Web 版升级

如果你使用源码部署了 Web 版（非桌面客户端），升级方式与 Linux Web 版一致：

cd clawpanel  # 替换为实际安装目录
git pull origin main
npm install
npm run build
npm run serve  # 重新启动

卸载面板

macOS 桌面版卸载

# 1. 删除应用
sudo rm -rf /Applications/ClawPanel.app

# 2. 清理应用数据（可选，删除后配置将丢失）
rm -rf ~/Library/Application\ Support/com.clawpanel.app
rm -rf ~/Library/Caches/com.clawpanel.app
rm -rf ~/Library/Preferences/com.clawpanel.app.plist

Windows 桌面版卸载

方式一：通过系统设置

1. 打开「设置」→「应用」→「已安装的应用」
2. 搜索 ClawPanel，点击「卸载」

方式二：通过控制面板

1. 打开「控制面板」→「程序」→「卸载程序」
2. 找到 ClawPanel，右键「卸载」

清理残留数据（可选）：

# 删除应用数据
Remove-Item -Recurse -Force "$env:APPDATA\com.clawpanel.app"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\com.clawpanel.app"

Linux 桌面版卸载

清理应用数据（可选）：

rm -rf ~/.local/share/com.clawpanel.app
rm -rf ~/.config/com.clawpanel.app

Linux Web 版卸载

# 1. 停止并禁用服务
sudo systemctl stop clawpanel
sudo systemctl disable clawpanel

# 2. 删除 systemd 服务文件
sudo rm -f /etc/systemd/system/clawpanel.service
sudo systemctl daemon-reload

# 3. 删除面板代码
sudo rm -rf /opt/clawpanel

# 4. 卸载 OpenClaw（可选）
sudo npm uninstall -g @qingchencloud/openclaw-zh

# 5. 删除 OpenClaw 数据（可选，删除后所有配置和记忆将丢失）
rm -rf ~/.openclaw

⚠️ 第 5 步会删除所有 OpenClaw 配置（API Key、模型设置、Agent 记忆等），请确认不再需要后再执行。

Docker 卸载

# 1. 停止并删除容器
docker stop clawpanel
docker rm clawpanel

# 2. 删除镜像（可选）
docker rmi $(docker images --filter "reference=*clawpanel*" -q) 2>/dev/null

# 3. 删除数据卷（可选，删除后所有配置将丢失）
docker volume rm clawpanel-data

如果使用 Docker Compose：

cd /path/to/clawpanel
docker compose down          # 停止并删除容器
docker compose down -v       # 同时删除数据卷（谨慎！）
docker rmi $(docker images --filter "reference=*clawpanel*" -q) 2>/dev/null

功能特性

• 🤖 AI 助手（全新·重磅） — 内置独立 AI 助手，4 种操作模式 + 8 大工具 + 交互式问答，详见下方 AI 助手亮点
• 🧩 多引擎架构 — 支持 OpenClaw、Hermes Agent、DeepSeek Harness、OpenCode，以及实验版 Pi；自由切换，各自独立管理
• π Pi 实验工作台 — 独立安装与会话管理、统一模型渠道、流式回复及逐次工具审批；不依赖 OpenClaw Gateway。使用说明与验收边界
• 🧪 DeepSeek Harness 工作台 — 面板内完成受管安装、模型渠道同步和完整 DSH Web 操作，无需另开页面或额外开放端口
• 🤖 Hermes Agent 对话 — 内置 Hermes Agent 聊天界面，支持工具调用可视化、文件系统访问开关、SSE 流式输出
• 🖼️ 图片识别 — 粘贴截图或拖拽图片，AI 自动识别分析，支持多模态图文混排对话
• 仪表盘 — 系统概览，服务状态实时监控，快捷操作
• 服务管理 — OpenClaw / Hermes Gateway 与 DeepSeek Harness 受管运行时启停控制、版本检测、配置备份与还原
• 模型配置 — 多服务商管理、模型增删改查、批量连通性测试、延迟检测、拖拽排序、自动保存+撤销
• 网关配置 — 端口、访问权限（本机/局域网）、认证 Token、Tailscale 组网
• 运行时管理 — OpenClaw Gateway 以及 DSH、OpenCode、Pi 独立运行时的状态、版本和生命周期控制
• 消息渠道 — 统一管理 Telegram、Discord、飞书、钉钉、QQ 等消息接入，支持同平台多 Agent 绑定
• 通信与自动化 — 消息设置、广播策略、斜杠命令、Webhook、执行审批转发等高级配置
• 使用情况 — Token 用量、API 费用、热门模型/服务商/工具排行、每日用量图表
• Agent 管理 — Agent 增删改查、身份编辑、模型配置、工作区管理
• 聊天 — 流式响应、Markdown 渲染、会话管理、/fast /think /verbose /reasoning 命令、Compaction 状态指示
• 定时任务 — Cron 定时执行，支持多渠道投递
• 日志查看 — 多日志源实时查看与关键词搜索
• 记忆管理 — 记忆文件查看/编辑、分类管理、ZIP 导出、Agent 切换
• 晴辰云免费测试 — 签到领取测试额度，支持获取模型并一键配置
• 词元 API 赞助推广 — 支持 GPT、Claude 等模型，充值 ¥1 到账 $1 平台额度
• 扩展工具 — cftunnel 内网穿透管理、ClawApp 状态监控
• 关于 — 版本信息、社群入口、相关项目链接、一键升级

功能截图

🤖 AI 助手 — 8 大技能卡片，一键触发配置检查、Gateway 诊断、环境检测、一键排障等常用操作

仪表盘 — Gateway / 隧道 / 服务实时状态，版本信息、Agent 数量、模型池一屏掌握

⚙️ AI 设置 — 晴辰云免费测试与词元 API 赞助服务均可一键接入

� 借尸还魂 — 从 OpenClaw Agent 加载灵魂（SOUL / IDENTITY / USER / AGENTS / TOOLS），继承人格与记忆

实时聊天 — WebSocket 流式对话，多 Provider 模型自动聚合，支持多模态

模型配置 — 多服务商统一管理，公益接口一键添加全部模型，主模型+备选自动切换

记忆文件 — 工作记忆、记忆归档、核心文件在线编辑，多 Agent 记忆隔离

查看更多截图

Agent 管理 — 多 Agent 创建、身份配置与独立工作区管理

Gateway — Token / 密码双认证，Agent 工具权限三档管控，会话可见性控制

服务管理 — 启停控制、版本检测、一键升级、npm 源切换、配置备份

安全设置 — 访问密码保护与无视风险模式

扩展工具 — cftunnel 内网穿透、ClawApp 移动客户端一键安装

系统诊断 — 全面健康检测、WebSocket 测试、一键修复配对

关于 — 版本信息、社群入口（QQ / 微信 / 抖音）、相关项目链接

🤖 AI 助手亮点

ClawPanel 内置的 AI 助手不只是聊天机器人——它能直接操作你的系统，帮你诊断、修复、甚至提交 PR。

四种操作模式

一键切换，界面颜色随模式变化，清晰感知当前权限状态：

设置中还有工具开关（终端/文件），优先级高于模式——关掉终端，即使无限模式也调不了命令。

八大工具

交互式问答（ask_user）

AI 可以通过 ask_user 工具向你提问，支持三种交互方式：

• 单选 — 从多个方案中选一个，还能输入自定义答案
• 多选 — 勾选多项，比如"选择要检查的组件"
• 文本 — 自由输入，比如"描述你遇到的问题"

AI 等你回答后才会继续操作，实现真正的人机协作。

PR 助手 & Bug 报告

发现 Bug？AI 不只是告诉你怎么修——它直接帮你修：

1. 🐛 提交 Bug 报告 — AI 自动收集系统环境、读取错误日志，按标准模板整理成 GitHub Issue，你复制粘贴就能提交
2. 🔀 PR 助手 — AI 分析 Bug 根因 → 定位代码 → 生成修复方案 → 通过 run_command 执行 git 命令完成 Fork/Branch/Commit/Push，用户只需点确认

内置技能卡片

欢迎页提供一键触发的常用技能：

技术架构

clawpanel/
├── src/                    # 前端源码
│   ├── pages/              # 10 个页面模块
│   ├── components/         # 通用组件（侧边栏、弹窗、Toast）
│   ├── lib/                # 工具库（Tauri API 封装、主题）
│   ├── style/              # 样式文件
│   ├── router.js           # 路由
│   └── main.js             # 入口
├── src-tauri/              # Rust 后端
│   ├── src/                # Tauri 命令与业务逻辑
│   ├── Cargo.toml          # Rust 依赖
│   └── tauri.conf.json     # Tauri 配置
├── public/                 # 静态资源
├── scripts/                # 开发与构建脚本
│   ├── dev.sh              # 开发模式启动
│   └── build.sh            # 编译与打包
├── .github/workflows/      # CI/CD
│   ├── ci.yml              # 持续集成（push/PR 自动检查）
│   └── release.yml         # 发布构建（全平台打包）
├── index.html              # HTML 入口
├── vite.config.js          # Vite 配置
└── package.json            # 前端依赖

从源码构建

前置条件

• Node.js >= 18 可构建基础前端；完整引擎开发与验收推荐 Node.js 24.16.0+（24.x）
• Rust (stable)
• Tauri v2 系统依赖（参考 Tauri 官方文档）

安装与开发

git clone https://github.com/qingchencloud/clawpanel.git
cd clawpanel
npm install

国内网络可使用 AtomGit 镜像：

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

macOS / Linux

# 启动完整 Tauri 桌面应用
./scripts/dev.sh

# 仅启动 Vite 前端（浏览器调试，使用 mock 数据）
./scripts/dev.sh web

Windows

# 启动完整 Tauri 桌面应用
npm run tauri dev

# 仅启动 Vite 前端（浏览器调试，使用 mock 数据）
npm run dev

构建

macOS / Linux

# 编译 debug 版本
./scripts/build.sh

# 仅检查 Rust 编译（最快，不生成产物）
./scripts/build.sh check

# 编译正式发布版本（含打包）
./scripts/build.sh release

Windows

# 检查 Rust 编译
cd src-tauri && cargo check

# 编译正式发布版本
npm run tauri build

# 指定打包格式（NSIS 安装器）
npm run tauri build -- --bundles nsis

产物位于 src-tauri/target/release/ 目录。

Web 开发版（无需 Rust/Tauri）

如果你只想开发前端或部署 Web 版，不需要安装 Rust：

# 克隆并安装
git clone https://github.com/qingchencloud/clawpanel.git
cd clawpanel
npm install

# 开发模式（热更新，自带 API mock 后端）
npm run dev
# 浏览器打开 http://localhost:1420

# 构建生产版本
npm run build

# 启动 Web 服务器（Headless，适用于 Linux/ARM/Docker）
npm run serve
# 默认监听 0.0.0.0:1420，支持 --port 和 --host 参数

Web 版通过 Node.js 后端调用服务器上的 CLI 和受管运行时；各引擎能力不同，模型渠道保存后需要显式同步到目标引擎。详细边界见 多引擎与模型渠道。

ARM/Armbian 用户：Web 模式天然兼容 ARM64 设备，详见 Armbian 部署指南。

快速上手

安装完成后，按以下步骤即可开始使用：

1. 初始设置

首次启动 ClawPanel 会自动进入初始设置页面，引导你完成环境检测：

• ✅ Node.js — 自动检测，未安装时提供一键安装
• ✅ Git — 自动检测并配置 HTTPS 模式（解决 SSH 不通问题）
• ✅ 引擎运行时 — 在左侧选择 OpenClaw、Hermes、DSH、OpenCode 或 Pi，按引擎页面完成安装

所有步骤均有绿色勾标记，全部通过后点击「前往模型配置」。

2. 配置 AI 模型

进入通用 → 模型渠道页面，添加至少一个 AI 服务商。保存后，点击对应按钮显式同步到目标引擎：

填入 Base URL 和 API Key，点击「测试连接」确认可用，然后保存。

3. 启动运行时

OpenClaw 前往服务管理页面，点击「启动」按钮启动 Gateway。DSH、OpenCode 和 Pi 在各自引擎的「运行与配置」页面独立启停。

Gateway 是 OpenClaw 的核心服务。其他引擎有自己的本地运行时，不共享 Gateway 生命周期。

4. 开始聊天

前往 OpenClaw 的实时聊天，或进入其他引擎的工作台，选择模型后发送一条完整测试消息。各引擎的会话、项目和权限彼此独立。

Web 版部署指南

Web 版适用于 Linux 服务器（无桌面环境），通过浏览器远程管理多个引擎。模型测试、工作目录和引擎进程都在运行 ClawPanel 的服务器上执行。

环境要求

• Node.js 推荐 24.16.0+（24.x）；面板会按已安装 OpenClaw 的 engines.node 检测兼容性，当前官方稳定版 2026.10.4 要求 >=24.16.0 =26.1.0
• Git（用于 OpenClaw 依赖安装）
• 端口 1420（ClawPanel）+ 18789（Gateway）

一键部署

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

部署完成后访问 http://服务器IP:1420。

安全注意事项

⚠️ 公网暴露风险：Web 版默认监听所有网卡。请务必：

1. 设置访问密码 — 首次登录会提示修改默认密码，或在「安全设置」页面配置
2. 防火墙限制 — 仅开放 1420 端口给可信 IP
3. Nginx 反向代理 + HTTPS — 生产环境强烈建议使用 HTTPS

Nginx 反向代理配置示例

server {
    listen 443 ssl;
    server_name openclaw.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:1420;
        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 支持（实时聊天需要）
    location /ws {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

API Key 安全

• API Key 存储在服务器的 ~/.openclaw/openclaw.json 中，不会传输到外部
• 建议为 ~/.openclaw/ 目录设置 chmod 700 权限
• 多人共用时，每人应使用独立的 OpenClaw 实例

消息渠道配置

ClawPanel 支持将 AI 接入多种即时通讯平台，在「消息渠道」页面统一管理。

支持的平台

配置步骤（以飞书为例）

1. 在飞书开放平台创建企业自建应用，开启机器人能力
2. 获取 App ID 和 App Secret
3. 在 ClawPanel「消息渠道」页面选择飞书，填入凭证
4. 点击「校验」确认连接，然后「保存」
5. Gateway 会自动重载，飞书机器人即刻可用

📖 详细教程：飞书接入指南 | 钉钉接入指南

注意事项

• 消息渠道需要 Gateway 正在运行才能接收消息
• 每个平台需要配对审批才能连接（在渠道设置中完成）
• 飞书/钉钉需要在对应平台发布应用版本后，机器人才对其他人可见

常见问题

macOS 提示"已损坏，无法打开"

没有苹果开发者签名，macOS Gatekeeper 会拦截。终端执行：

sudo xattr -rd com.apple.quarantine /Applications/ClawPanel.app

或前往「系统设置 → 隐私与安全性」点击「仍要打开」。

macOS 检测不到 Node.js

从 Finder/Dock 启动 ClawPanel 时，应用的 PATH 环境变量可能不包含 Node.js 安装路径。

v0.4.1 已修复：自动补充 /usr/local/bin、/opt/homebrew/bin、~/.nvm、~/.volta 等常见路径。

临时解决：从终端启动 ClawPanel：

open /Applications/ClawPanel.app

Windows 安装 OpenClaw 报 ENOENT (-4058)

通常是文件权限或 npm 缓存问题：

1. 以管理员身份运行 ClawPanel
2. 或打开 PowerShell（管理员）手动安装：

   npm install -g [email protected] --registry https://registry.npmmirror.com
   

3. 如果仍报错，清理 npm 缓存：npm cache clean --force

Windows 安装报 exit 128 (access rights)

npm 依赖需要 Git。如果已装 Git 但仍报 128，是因为依赖用了 SSH 协议拉代码但你没配 GitHub SSH Key。运行以下命令改用 HTTPS：

git config --global url."https://github.com/".insteadOf ssh://[email protected]/
git config --global url."https://github.com/".insteadOf [email protected]:

没装 Git 的请先安装 Git for Windows。v0.4.2+ 已自动配置 HTTPS 模式。

Windows 安装报 EPERM (operation not permitted)

文件被其他进程锁定。先关闭 ClawPanel 和所有 Node.js 进程，以管理员身份打开 PowerShell 重装：

npm cache clean --force
npm install -g [email protected] --registry https://registry.npmmirror.com

安装后 Node.js 检测不到（Windows）

安装 Node.js 后点击「重新检测」即可；如果仍显示旧版本，再重启 ClawPanel 或检查 PATH 优先级。

如果安装在非默认路径（如 D:\nodejs、F:\AI\Node），可以在设置向导中使用「自动扫描」或手动填写 Node.js 安装目录。面板会校验该 Node.js 是否满足当前 OpenClaw 要求，版本过低的路径不会保存。

Gateway 启动失败

常见原因和解决方案：

如果仍无法解决，查看「日志查看」页面的 Gateway 日志获取详细错误信息。

模型连接超时 / 测试失败

1. 检查 API Key — 确认 Key 未过期、余额充足
2. 检查 Base URL — 不同服务商 URL 格式不同，注意结尾不要多 /v1（ClawPanel 会自动处理）
3. 网络问题 — 国内访问 OpenAI 需要代理；DeepSeek / 阿里通义 / Ollama 国内直连
4. Ollama 特殊处理 — URL 填 http://127.0.0.1:11434（不加 /v1，ClawPanel 自动补全）

WebSocket 断连 / 聊天无响应

1. 确认 Gateway 正在运行（顶部状态栏显示绿色）
2. 反向代理需要配置 WebSocket 支持（参见上方 Nginx 配置）
3. 如果使用 HTTPS，WebSocket 需要 wss:// 协议（v0.7.3+ 已自动适配）
4. 清除浏览器缓存后刷新页面

Web 版报"未实现的命令"

升级到 v0.8.5+。旧版本的 Web 后端缺少部分命令实现，v0.8.5 已补全所有 handler。

cd /opt/clawpanel  # 替换为实际安装目录
git pull origin main
npm install
npm run build
sudo systemctl restart clawpanel  # 或 pm2 restart clawpanel

消息渠道保存后不生效

1. 确认 Gateway 正在运行
2. 飞书/钉钉：需要在对应开放平台发布应用版本
3. 飞书：私聊测试需在「工作台」搜索机器人名称；群聊需通过「群设置 → 智能群助手」添加
4. 钉钉：消息接收模式必须选择 Stream 模式

旧版前端热更新残留 / 想回退到内嵌版本

新版 ClawPanel 的主更新方式是下载完整安装包并覆盖安装。前端热更新目录仅用于兼容旧版本残留资源和回滚处理；如果你曾经使用过旧版热更新，相关文件会存储在：

如果界面显示异常或想回退到安装包自带的内嵌前端，删除该目录后重启即可：

# macOS / Linux
rm -rf ~/.openclaw/clawpanel/web-update

# Windows PowerShell
Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw\clawpanel\web-update"

重启 ClawPanel 后将自动使用内嵌的前端资源。

相关项目

赞助商

感谢以下赞助商对 ClawPanel 项目的支持：

  [![慈云数据](https://img.shields.io/badge/慈云数据-香港直连2H2G_99元/年-FF6B35?style=for-the-badge&logo=icloud&logoColor=white)](https://www.ciyundata.com/cart/goods.htm?id=267)
  

  

慈云数据服务团队于 2020 年成立，专注于基础云计算、游戏云、主题站长等业务

售前售后服务 24 小时在线值班，强力保证为客户提供优质稳定的网络资源与机房服务

贡献

欢迎提交 Issue 和 Pull Request。贡献流程详见 CONTRIBUTING.md。

致谢

ClawPanel 的成长离不开每一位贡献者的付出。感谢你们让这个项目变得更好！

🛠 代码贡献者

感谢以下开发者提交 Pull Request，直接参与了代码建设：

liucong2013 #88

axdlee #58

ATGCS #107

livisun #106

kiss-kedaya #101 #94

wzh4869 #82

0xsline #15

jonntd #18

octo-patch #163

SEVENTEEN-TAN #161

roc-xie #162

🐛 社区反馈者

感谢以下用户提交 Issue 报告 Bug 或建议功能，帮助 ClawPanel 持续改进：

如果遗漏了你的贡献，请 提交 Issue 告知我们，我们会第一时间补充！

许可证

本项目采用 AGPL-3.0 开源协议。企业如需闭源商用，可联系获取商业授权。

© 2026 武汉晴辰天下网络科技有限公司 | claw.qt.cool

内容由编辑整理，部分信息来自 GitHub 与项目官网，版权归原作者所有。发现错误？报告问题