ClawPanel 本地安装和配置 OpenClaw

导读

先看懂这 3 个角色

第一次用的时候，最容易混淆的是：ClawPanel、OpenClaw、Coding Hub 到底分别是啥？

简单理解：

• ClawPanel：安装和管理面板，像一个本地控制台。
• OpenClaw：真正跑在你电脑上的 Agent 服务，负责处理消息、调用模型、执行任务。
• Coding Hub：公司统一的模型接口，提供 gpt-5.5、gpt-5.4-mini、gpt-image-2 等模型能力。

1. 先准备 Coding Hub 密钥

后面配置模型时，需要用到你自己的 Coding Hub API Key。

浏览器打开：https://coding-hub.yeelight.com/login

登录后创建密钥，注意这 3 点：

1. 分组选择 codex订阅。
2. 创建完成后，复制自己的 API Key。
3. 密钥只给自己使用，不要截图给别人。

如果你已经在 Codex 或 Cherry Studio 教程里创建过密钥，可以继续使用同一个密钥。

2. 打开 ClawPanel 下载页

浏览器打开：https://claw.qt.cool/clawpanel/#download

页面会按系统分成 macOS、Windows、Linux 三列。

Windows 推荐选完整包，是为了减少中途再下载 WebView2 依赖的概率。对不熟悉电脑环境的同事来说，这个选择更稳。

3. macOS 安装 ClawPanel

3.1 先确认自己的 Mac 芯片

不知道自己是 Apple Silicon 还是 Intel，可以这样看：

1. 点击屏幕左上角苹果图标。
2. 点击 关于本机。
3. 看“芯片”或“处理器”字段。

然后回到下载页：

• 如果写着 Apple M1 / M2 / M3 / M4，选 Apple Silicon。
• 如果写着 Intel，选 Intel 芯片。

3.2 打开 dmg，把 App 拖进应用程序

下载完成后，打开 .dmg 文件，把 ClawPanel.app 拖到 Applications / 应用程序。

这一步很重要。后面的 macOS 安全命令默认会去这个位置找应用：

/Applications/ClawPanel.app

3.3 解除 macOS 安全隔离

第一次打开第三方应用时，macOS 可能提示“已损坏”或“无法验证”。

如果你已经把 ClawPanel 拖进 应用程序，打开 终端，执行：

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

输入电脑密码时，终端不会显示字符，这是正常的。

下载页里也写了这条处理方式：

也可以走系统设置：

1. 打开 系统设置。
2. 进入 隐私与安全性。
3. 找到 ClawPanel 的拦截提示。
4. 点击 仍要打开。

3.4 打开 ClawPanel

完成上面步骤后，在 应用程序 里打开 ClawPanel.app。

第一次打开会进入引擎选择页面，后面从第 5 节继续。

4. Windows 安装 ClawPanel

4.1 下载 Windows 完整包

Windows 用户在下载页的 Windows 一列里，推荐选择：

完整包（含 WebView2）

这样安装时更不容易因为缺 WebView2 而卡住。

4.2 遇到 SmartScreen 提示时这样点

双击安装包后，Windows 可能会出现“已保护你的电脑”的提示。

先点击 更多信息。

4.3 选择安装语言

语言选择 中文（简体），然后点击 OK。

4.4 选择安装位置

安装目录一般保持默认即可，然后点击 下一步。

4.5 等待安装完成

安装器会自动解压文件、创建快捷方式。看到进度条完成后，点击 下一步。

4.6 勾选运行并完成

结束页建议保留：

• 运行 ClawPanel
• 创建桌面快捷方式

然后点击 完成。

5. 首次启动，选择 OpenClaw

第一次启动 ClawPanel 时，会让你选择要使用的 Agent 引擎。

这里选择 OpenClaw。

6. 环境检测和一键安装

选择 OpenClaw 后，会进入环境检测页面。

ClawPanel 会检查：

• Node.js 环境
• Git 版本管理
• OpenClaw CLI
• 配置文件

如果你的电脑已经装好了 Node.js 和 Git，会看到绿色通过状态。

安装时会出现日志弹窗。这个时候不要关闭 ClawPanel，也不要反复点击安装按钮。

7. 进入 OpenClaw 管理面板

安装完成后，会进入 ClawPanel 管理面板。

如果仪表盘里能看到版本、模型、Agent 数量、Gateway 状态等信息，就说明 OpenClaw 已经启动起来了。

• ClawPanel 负责管理本机 OpenClaw。
• Gateway 负责把本地 OpenClaw、实时聊天和消息渠道连起来。
• Coding Hub 只负责提供模型接口。
• 电脑关机、ClawPanel 退出、Gateway 停止时，消息渠道都可能无法正常回复。

如果页面里出现 WebSocket 未连接、Gateway 未运行等提示，先不用慌，后面可以用“检测与修复”处理。

8. 添加 Coding Hub 模型服务商

模型配置这一步不要跳。建议按下面这个顺序走：先准备密钥，再添加服务商，再获取模型列表，最后测试并设为主模型。

下面这张图展示的是“添加服务商”的填写位置。截图里的 openai 和 https://api.openai.com/v1 只是默认示例，实际要按上表改成 Coding Hub。

9. 获取模型列表并添加模型

添加服务商后，在服务商列表右侧点击 获取列表。

ClawPanel 会从 Coding Hub 拉取可用模型。常用可以先选择：

• gpt-5.3-codex-spark
• gpt-5.4
• gpt-5.4-mini
• gpt-5.5
• gpt-image-2

然后点击 添加选中。

• 日常助手、消息渠道主模型：优先用 gpt-5.4-mini，速度和成本更平衡。
• 复杂分析和高质量问答：可以用 gpt-5.5。
• 编程或 Agent 任务：可以测试 gpt-5.3-codex-spark。
• gpt-image-2 是绘图模型，不建议设置成普通聊天主模型。

10. 测试模型并设置主模型

模型添加完成后，在模型列表里选择一个聊天模型点击 测试。

如果右上角出现连通正常的提示，说明模型能正常调用。

测试通过后，点击 设为主模型。

11. 配置消息渠道，以飞书为例

消息渠道不是“直接让飞书调用模型”，而是让飞书机器人把消息转给本地 OpenClaw，再由 OpenClaw 调用 Coding Hub 模型，最后把回复送回飞书。

渠道列表里可以看到 QQ 机器人、钉钉、飞书、Telegram、Discord、Slack、微信、Microsoft Teams、Signal、Matrix 等入口。

这里以 飞书 为例，点击飞书卡片。

1. 前往飞书开放平台，创建企业自建应用。审核可以找
2. 在“添加应用能力”中添加 机器人。
3. 在“凭证与基础信息”中获取 App ID 和 App Secret。
4. 按页面要求配置事件回调方式。
5. 开通页面要求的消息权限。
6. 创建版本并发布。
7. 把机器人添加到目标群，再回到 ClawPanel 校验和保存。

不同消息渠道的接入方式不一样。ClawPanel 的各通道添加页面都会写清楚需要准备什么，照页面提示一步步填就行。

一文完全搞懂OpenClaw（Clawdbot）附飞书对接教程！ - 飞书官网

12. 让晴辰助手引导你配置

如果你不确定飞书、钉钉、QQ 等渠道怎么配置，可以使用 ClawPanel 里的 晴辰助手。

建议这样做：

1. 先完成前面的 模型配置，确认聊天模型能测试通过。
2. 进入 晴辰助手。
3. 打开助手设置，尽量选择 导入 OpenClaw 配置，复用已经配置好的 Coding Hub 服务商和主模型。
4. 回到助手对话框，输入下面这句话：

我想要配置飞书消息通道，请一步步引导我配置。

助手会根据你当前页面和报错，一步步提示你准备 App ID、App Secret、权限、事件回调和机器人入群。

你也可以打开 实时聊天，让它帮你排查具体错误。

13. 出问题时使用检测与修复

如果不知道问题出在哪里，不要一上来重装。先按下面这个思路判断：

点击 开始检测。

ClawPanel 会检查 OpenClaw 安装、Node.js、配置文件、Gateway、WebSocket、认证令牌、设备密钥、版本状态和连接诊断等项目。

也可以手动点击修复

14. 后续可以探索的能力

第一次使用不需要把所有菜单都搞懂。先完成安装、模型配置和一个消息渠道，能正常收发消息后，再慢慢看这些能力：

常见问题

下面的问题按“安装类、模型类、Gateway 和服务类、消息渠道类、更新和数据类”整理。普通同事优先看“怎么处理”，管理员再看命令和日志。

安装类

1. macOS 提示 ClawPanel 已损坏或无法验证怎么办？

先确认已经把 ClawPanel 拖进 应用程序，然后执行：

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

也可以到 系统设置 → 隐私与安全性 里点击 仍要打开。

2. 执行 xattr 命令提示 No such file 怎么办？

说明 /Applications/ClawPanel.app 不存在。通常是还没有拖进“应用程序”。

先打开 .dmg，把 ClawPanel.app 拖到 Applications，再重新执行命令。

3. macOS 明明装了 Node.js，但 ClawPanel 检测不到怎么办？

这通常是因为从 Finder 或 Dock 启动 App 时，ClawPanel 拿到的 PATH 不完整。

先这样处理：

1. 退出 ClawPanel，再重新打开。
2. 在环境检测页点 重新检测。
3. 如果还是检测不到，打开终端执行：

open /Applications/ClawPanel.app

1. 仍不行就点 一键安装，让 ClawPanel 使用它推荐的 Node.js 环境。

4. Windows 为什么推荐下载完整包？

因为完整包包含 WebView2，安装时更不容易卡在额外依赖下载上。小白同事直接选完整包更稳。

5. Windows 出现“已保护你的电脑”怎么办？

确认安装包来自 ClawPanel 官网下载页后，点击 更多信息，再点击 仍要运行。

6. Windows 安装 OpenClaw 报 ENOENT 或 -4058 怎么办？

这通常和文件权限、安装目录或 npm 缓存有关。

先按小白方式处理：

1. 完全退出 ClawPanel。
2. 右键 ClawPanel，选择 以管理员身份运行。
3. 回到环境检测页，重新点 一键安装。
4. 如果还是不行，重启电脑后再试一次。

如果你会用 PowerShell，可以管理员身份打开 PowerShell，执行：

npm cache clean --force

然后回到 ClawPanel 里重新安装。

7. Windows 安装报 exit 128 或 access rights 怎么办？

这通常是 Git 相关问题。

优先检查：

1. 电脑是否安装了 Git。
2. 安装 Git 后有没有重启 ClawPanel。
3. 公司网络是否能访问 GitHub。

如果已经安装 Git 但仍失败，可能是依赖拉取时走了 SSH 协议。让管理员或 AI 助手帮你切换 GitHub HTTPS 拉取方式即可，不建议小白自己改 Git 全局配置。

8. Windows 安装报 EPERM 或 operation not permitted 怎么办？

这通常是文件被占用或权限不够。

建议这样处理：

1. 关闭 ClawPanel。
2. 打开任务管理器，结束残留的 node.exe 或相关安装进程。
3. 重新以管理员身份运行 ClawPanel。
4. 再点一次 一键安装。

最简单的办法：直接重启电脑，再以管理员身份打开 ClawPanel。

模型配置类

9. 获取不到模型列表怎么办？

优先检查：

1. 接口地址是不是 https://coding-hub.yeelight.com/v1。
2. API Key 有没有完整复制。
3. API Key 是不是自己的 Coding Hub 密钥。
4. 接口类型是不是 OpenAI Chat Completions（最常用）。
5. 当前网络是否能访问 coding-hub.yeelight.com。

10. 模型测试失败怎么办？

先换 gpt-5.4-mini 测试。它更适合作为日常连通性验证模型。

如果仍然失败，回到 Coding Hub 重新复制密钥，或者重新创建一个密钥再试。

另外检查：

1. 服务商右侧开关是否打开。
2. 主模型是否设置成了聊天模型，而不是 gpt-image-2。
3. 是否刚改完配置但 Gateway 还没重启。

11. 为什么不建议把 gpt-image-2 设为主模型？

gpt-image-2 是绘图模型，不适合作为普通聊天和消息渠道的默认主模型。

建议这样分工：

• 主模型：gpt-5.4-mini 或 gpt-5.5。
• 绘图任务：需要画图时再显式选择或调用 gpt-image-2。
• 排查连通性：优先用 gpt-5.4-mini。

12. 换了 API Key 或模型后，为什么聊天还是失败？

有时 Gateway 仍在使用旧配置。按顺序处理：

1. 确认模型配置已保存。
2. 在模型列表里重新测试模型。
3. 进入 服务管理，重启 Gateway。
4. 再回到实时聊天或消息渠道测试。

Gateway 和服务类

13. Gateway 是什么？为什么重要？

Gateway 是 OpenClaw 的核心连接服务。实时聊天、消息渠道、节点通信、控制页面都依赖它。

你可以这样理解：

• Gateway 正常：OpenClaw 才能收消息、调用模型、发回复。
• Gateway 停止：模型配置可能还在，但聊天和消息渠道会不工作。
• WebSocket 未连接：通常说明页面没有连上 Gateway。

14. Gateway 启动失败怎么办？

先按这个顺序排查：

1. 打开 仪表盘，看 Gateway 是否显示运行中。
2. 进入 服务管理，尝试停止后重新启动 Gateway。
3. 进入 检测与修复，点击 开始检测。
4. 进入 日志查看，看是否有明显错误。

常见原因：

• 端口被其他进程占用。
• openclaw.json 配置文件异常。
• API Key 或主模型配置异常。
• 认证配置不兼容。

小白用户不建议手动改配置文件。优先用 检测与修复，或者把日志截图发给管理员。

15. WebSocket 未连接或聊天没反应怎么办？

先看 Gateway 是否运行中。

如果 Gateway 没运行，先去 服务管理 启动 Gateway。

如果 Gateway 运行中但页面仍提示 WebSocket 未连接：

1. 刷新页面或重启 ClawPanel。
2. 进入 检测与修复 做一次检测。
3. 如果你用的是 Web 版或反向代理部署，需要确认 WebSocket 代理配置正确。
4. 桌面版用户通常不需要改代理配置，优先重启 ClawPanel。

16. 管理员可以看哪些状态和日志？

普通同事优先用 ClawPanel 里的 检测与修复 和 日志查看。管理员需要进一步排查时，可以看这些命令：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor

常见日志位置：

• /tmp/openclaw/openclaw-YYYY-MM-DD.log
• ~/.openclaw/logs/gateway.log
• ~/.openclaw/logs/gateway.err.log

发给管理员时，优先发检测页截图和错误关键词，不要发 API Key、App Secret、Token。

消息渠道类

17. 飞书接入校验失败怎么办？

优先检查：

1. App ID 和 App Secret 有没有复制完整。
2. 飞书开放平台里的机器人能力是否已添加。
3. 权限是否开通并发布版本。
4. 事件回调方式是否按页面要求配置。
5. 机器人是否已经添加到目标群。

18. 飞书保存后机器人还是不回消息怎么办？

优先检查：

1. Gateway 是否正在运行。
2. 飞书开放平台里应用版本是否已经发布。
3. 机器人是否已经被添加到目标群。
4. 群聊测试时，是否需要 @ 机器人。
5. 消息权限是否包含页面要求的权限。

如果 OpenClaw 日志里完全没有收到消息，通常是平台侧机器人、权限、事件订阅或群配置问题；如果日志里收到消息但没有回复，再回到模型和 Gateway 排查。

19. 钉钉、QQ、Telegram、Discord 等其他渠道怎么配？

ClawPanel 的每个渠道弹窗里都有接入步骤。一般规律是：

1. 去对应平台创建机器人或应用。
2. 拿到平台给的 App ID、Secret、Token 或 Bot Token。
3. 回到 ClawPanel 的消息渠道里填写。
4. 点击校验。
5. 保存后把机器人拉进群里测试。

如果不确定，就先配置晴辰助手，然后问：

我想要配置某某消息通道，请一步步引导我配置。

更新和数据类

20. 热更新后界面异常怎么办？

如果 ClawPanel 更新后界面变奇怪、按钮不见了、页面空白，可以先重启 ClawPanel。

如果重启无效，可能是热更新文件异常。可以让管理员协助清理热更新目录后再重启：

• Windows：%USERPROFILE%\.openclaw\clawpanel\web-update\
• macOS / Linux：~/.openclaw/clawpanel/web-update/

普通同事不建议自己删除目录，先截图发给管理员。

21. 可以把 Coding Hub API Key 发给别人帮我配置吗？

不要。可以让对方远程指导你点哪里，但密钥不要发到群里，也不要截图给别人。

同样不要外发：

• 飞书 App Secret
• 钉钉 App Secret
• Telegram Bot Token
• Discord Bot Token
• OpenClaw 认证 Token

22. OpenClaw 的数据都在哪里？

OpenClaw 会在本机保存配置、日志、状态和部分运行数据。常见位置包括：

• ~/.openclaw/
• ~/.openclaw/logs/
• /tmp/openclaw/

不要一遇到问题就删除这些目录。删除前先让管理员确认，因为里面可能包含模型配置、消息渠道配置、日志和本地状态。

23. 我已经乱点过很多设置，要不要重装？

先不要重装。

建议按顺序做：

1. 进入 检测与修复，先看检测结果。
2. 进入 模型配置，确认 Coding Hub 服务商和主模型。
3. 进入 服务管理，重启 Gateway。
4. 进入 日志查看，把错误截图发给管理员。

只有在配置严重混乱、检测无法修复时，再考虑清理数据或重装。

参考来源

• ClawPanel 官网下载页
• ClawPanel GitHub README
• OpenClaw Gateway 文档
• OpenClaw Troubleshooting