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

消息渠道配置

ClawPanel 支持将 AI 接入多种即时通讯平台，在「消息渠道」页面统一管理。
支持的平台
平台 类型 配置难度 说明
飞书 / Lark 企业内部应用 ⭐⭐ 支持内置插件和官方插件两种模式
钉钉 企业内部应用 ⭐⭐ Stream 模式，需创建机器人应用
Telegram Bot ⭐ 通过 @BotFather 创建 Bot
Discord Bot ⭐⭐ 需创建 Application + Bot
QQ 机器人 官方 Bot ⭐⭐⭐ 需在 QQ 开放平台注册
配置步骤（以飞书为例）

在飞书开放平台创建企业自建应用，开启机器人能力  
获取 App ID 和 App Secret  
在 ClawPanel「消息渠道」页面选择飞书，填入凭证  
点击「校验」确认连接，然后「保存」  
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 缓存问题：

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

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

如果仍报错，清理 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://git@github.com/
git config --global url."https://github.com/".insteadOf git@github.com:

没装 Git 的请先安装 Git for Windows。v0.4.2+ 已自动配置 HTTPS 模式。
Windows 安装报 EPERM (operation not permitted)

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

npm cache clean --force
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com

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

安装 Node.js 后需要重启 ClawPanel，新的 PATH 环境变量才能生效。

如果安装在非默认路径（如 D:\nodejs、F:\AI\Node），请确认该目录已加入系统 PATH 环境变量。v0.4.2+ 已自动扫描常见安装路径。
Gateway 启动失败

常见原因和解决方案：
症状 原因 解决
端口 18789 被占用 另一个 Gateway 进程残留 终端执行 pkill -f openclaw 后重启
配置文件损坏 openclaw.json 格式错误 前往「服务管理」→「从备份恢复」
反复崩溃 API Key 或模型配置异常 用 AI 助手「🔨 一键排障」自动诊断
提示 "auth mode" 错误 认证配置不兼容 在「安全设置」重置 Gateway 认证

如果仍无法解决，查看「日志查看」页面的 Gateway 日志获取详细错误信息。
模型连接超时 / 测试失败

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

WebSocket 断连 / 聊天无响应

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

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

消息渠道保存后不生效

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

热更新后界面异常 / 想回退到内嵌版本

ClawPanel 桌面端支持前端热更新，更新文件存储在：
系统 路径
Windows %USERPROFILE%.openclaw\clawpanel\web-update\
macOS / Linux ~/.openclaw/clawpanel/web-update/

如果热更新后界面显示异常或想回退到安装包自带的版本，删除该目录后重启即可：

macOS / Linux

rm -rf ~/.openclaw/clawpanel/web-update

Windows PowerShell

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

重启 ClawPanel 后将自动使用内嵌的前端资源。
相关项目
项目 说明
OpenClaw AI Agent 框架
ClawApp 跨平台移动聊天客户端
cftunnel Cloudflare Tunnel 内网穿透工具
赞助商

感谢以下赞助商对 ClawPanel 项目的支持：
慈云数据

慈云数据服务团队于 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 持续改进：

[asfork] [p1ayer222] [ntescn] [song860] [gtgc2005] [Eternity714] [flyingnight] [genan1989] [alexluoli] [iethancode] [glive1991-bit] [hYRamos] [htone8] [evanervx] [qjman524] [yahwist00] [catfishlty] [ufoleon] [fengzhao] [nicoxia] [friendfish] [pdsy520] [CaoJingBiao] [LwdAmazing] [joeshen2021] [Qentin39] [wzgrx] [aixinjie] [wangziqi7] [kizuzz] [lizheng31] [Yafeiml] [ethanbase] [BBcactus] [AGLcaicai] [zhugeafu] [sc-yx] [themeke] [erlangzhang] [YamanZzz] [huanghun5172] [kongjian19930520] [XIAzhenglin] [dacj4n] [lzzandsx] [qiangua5210] [yzswk] [nasvip] [yyy22335] [yuanjie408] [qingahan] [mentho7] [AspirantH] [skkjkk] [penghaiqiu1988] [cfx2020] [birdxs] [szuforti] [baiyucraft] [arnzh] [xyiqq] [tonyzhangbo78] [try-to] [irunmyway] [Oliveelick] [56025192] [aliceQWAS] [qingdeng888] [18574707971] [yushu200403] [fakers777] [carlyle168] [jx270417948] [wanababy] [lwsg1987] [xiaochengshiguduo] [caofakun] [adam479] [WHHGR] [z1a2q3wolf] [kof8855] [zshaxy] [l15514559690-cmd] [waicyz2009] [y864261947] [xcrossed]

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