macOS 上 OpenClaw + QQBot 安装指南
一、环境准备
1.1 安装 Node.js
brew installnode验证安装：
npm-v# 输出: 11.11.01.2 配置 npm 镜像源
配置淘宝镜像源以加速下载：
npm config set registry https://registry.npmmirror.com 验证配置：
npm config get registry # 输出: https://registry.npmmirror.com 即为配置成功二、安装 OpenClaw
2.1 安装 OpenClaw
npminstall-g openclaw@latest 验证安装：
openclaw --version# 输出: 2026.3.22.2 向导式配置
openclaw onboard 在向导中选择：
- Onboarding mode: QuickStart（Configure details later via openclaw configure）
三、解决常见配置问题
3.1 解决 “origin not allowed” 错误
编辑配置文件 ~/.openclaw/openclaw.json，在 gateway 段中添加：
"gateway":{"controlUi":{"allowedOrigins":["*"]}}3.2 解决 “pairing required” 错误
- 列出设备请求：
openclaw devices list - 记录
RequestId - 批准设备配对：
openclaw devices approve <RequestId>四、浏览器配置
4.1 安装 Chrome 插件
openclaw browser extension install插件文件会下载到 ~/.openclaw/browser/chrome-extension/
4.2 查看隐藏文件
macOS 默认隐藏以 . 开头的文件和目录，可通过以下方式查看：
- 快捷键: 在访达中按
Cmd + Shift + .切换显示隐藏文件 - 终端打开:
open ~/.openclaw
4.3 启用托管模式
# 启用托管模式（隔离、无需插件） openclaw config set browser.defaultProfile "openclaw"# 重启网关生效 openclaw gateway restart 五、安装 QQBot 插件
5.1 安装插件
openclaw plugins install @sliverp/qqbot@latest 5.2 绑定 QQ 机器人
访问 QQ机器人官方页面 获取 AppId 和 AppSecret。
openclaw channels add--channel qqbot --token"AppId:AppSecret"5.3 重启服务
openclaw gateway restart 六、编译 QQBot 插件（重点）
6.1 为什么需要手工编译
QQBot 插件使用 TypeScript 编写，安装后需要进行编译才能正常运行。由于插件依赖的类型定义可能不完整，编译过程中常会遇到各种错误，需要手工处理。
6.2 进入插件目录
重要：以下所有命令都需要在 QQBot 插件目录下执行
cd /Users/yijian/.openclaw/extensions/qqbot/ 6.3 尝试编译并识别错误
首先尝试编译，查看具体错误：
npm run build 6.4 常见编译错误及解决方案
错误 1：找不到 ‘ws’ 模块的声明文件
错误信息：
src/gateway.ts:1:23 - error TS7016: Could not find a declaration file for module 'ws'. Try `npm i --save-dev @types/ws` if it exists 解决方案：
在 QQBot 插件目录下执行：
npminstall --save-dev @types/ws --registry=https://registry.npmmirror.com 错误 2：参数隐式具有 ‘any’ 类型
错误信息：
src/gateway.ts:2029:31 - error TS7006: Parameter 'data' implicitly has an 'any' type. src/gateway.ts:2247:23 - error TS7006: Parameter 'code' implicitly has an 'any' type. src/gateway.ts:2247:29 - error TS7006: Parameter 'reason' implicitly has an 'any' type. src/gateway.ts:2342:23 - error TS7006: Parameter 'err' implicitly has an 'any' type. 解决方案：
修改 tsconfig.json，关闭隐式 any 类型检查：
{"compilerOptions":{"noImplicitAny":false}}错误 3：找不到名称 ‘process’
错误信息：
src/channel.ts:315:32 - error TS2580: Cannot find name 'process'. Try `npm i --save-dev @types/node`. src/config.ts:96:14 - error TS2580: Cannot find name 'process'. 解决方案：
在 QQBot 插件目录下执行：
npminstall --save-dev @types/node --force如果安装失败，尝试清除缓存后重新安装：
# 清除 npm 缓存npm cache clean --force# 重新安装npminstall --save-dev @types/node --registry=https://registry.npmmirror.com 6.5 完整的 TypeScript 配置
编辑 tsconfig.json，使用以下配置可以避免大多数编译错误：
{"compilerOptions":{"noImplicitAny":false,"skipLibCheck":true}}配置说明：
noImplicitAny: false- 关闭隐式 any 类型报错skipLibCheck: true- 跳过第三方库的类型检查，加快编译速度
6.6 完整的编译流程
按照以下顺序执行，可以解决大多数编译问题：
# 1. 进入插件目录cd /Users/yijian/.openclaw/extensions/qqbot/ # 2. 安装必要的类型定义npminstall --save-dev @types/node @types/ws --registry=https://registry.npmmirror.com # 3. 如果安装失败，清除缓存npm cache clean --force# 4. 重新安装类型定义npminstall --save-dev @types/node @types/ws --registry=https://registry.npmmirror.com # 5. 修改 TypeScript 配置# 编辑 tsconfig.json，添加或修改以下内容：# {# "compilerOptions": {# "noImplicitAny": false,# "skipLibCheck": true# }# }# 6. 执行编译npm run build 6.7 验证编译结果
编译成功后，应该看到类似以下输出：
$ npm run build > @sliverp/[email protected] build > tsc ||true如果没有任何错误信息，说明编译成功。
6.8 编译失败的处理
如果编译仍然失败：
- 检查 Node.js 版本：确保使用较新的 Node.js 版本（建议 v18+）
- 检查 npm 版本：确保 npm 版本较新
- 查看详细错误信息：仔细阅读错误信息，根据具体错误类型搜索解决方案
- 检查插件版本：确认使用的是最新版本的 QQBot 插件
删除 node_modules 重新安装：
rm-rf node_modules package-lock.json npminstall6.9 编译成功后的操作
编译成功后，重启 OpenClaw 网关使插件生效：
openclaw gateway restart 七、配置工具权限
7.1 了解 tools.profile
OpenClaw 2026.3.2 版本中，tools.profile 控制工具权限范围：
| 取值 | 权限范围说明 |
|---|---|
| minimal | 仅开放会话状态（session_status）权限 |
| coding | 开放文件系统、运行时、会话、内存、图片相关权限 |
| messaging | （默认）仅开放消息相关权限 |
| full | 无权限限制，支持执行命令、发送消息等所有操作 |
7.2 修改配置文件
编辑 ~/.openclaw/openclaw.json，修改 tools 配置：
{"tools":{"profile":"full"}}7.3 生效方式
配置修改后，重启 OpenClaw 服务使配置生效：
openclaw gateway restart 八、注意事项
- 权限最小化原则: 若非必要，不建议直接使用
full，可根据需求选择coding等精细化取值 - 配置格式校验: 修改
openclaw.json时需确保 JSON 格式规范 - 官方文档: 更多配置规则可查阅 OpenClaw 官方文档
九、常用命令
# 查看版本 openclaw --version# 启动向导配置 openclaw onboard # 重启网关 openclaw gateway restart # 列出设备 openclaw devices list # 批准设备 openclaw devices approve <RequestId># 安装插件 openclaw plugins install<plugin-name># 添加通道 openclaw channels add--channel<channel>--token"<token>"# 配置浏览器 openclaw browser extension install openclaw config set browser.defaultProfile "openclaw"十、故障排查
编译错误
如果遇到 TypeScript 编译错误，确保已安装必要的类型定义：
npminstall --save-dev @types/node @types/ws --registry=https://registry.npmmirror.com 权限问题
如果无法执行命令，检查 tools.profile 配置是否设置为 full 或 coding。
配置不生效
修改配置后，确保重启 OpenClaw 网关服务：
openclaw gateway restart 
