macOS 上 OpenClaw + QQBot 安装指南

四、浏览器配置

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 ~/.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 插件目录下执行：

npm install --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 插件目录下执行：

npm install --save-dev @types/node --force

如果安装失败，尝试清除缓存后重新安装：

# 清除 npm 缓存
npm cache clean --force
# 重新安装
npm install --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 ~/.openclaw/extensions/qqbot/
# 2. 安装必要的类型定义
npm install --save-dev @types/node @types/ws --registry=https://registry.npmmirror.com 
# 3. 如果安装失败，清除缓存
npm cache clean --force
# 4. 重新安装类型定义
npm install --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 编译失败的处理

如果编译仍然失败：

1. 检查 Node.js 版本：确保使用较新的 Node.js 版本（建议 v18+）
2. 检查 npm 版本：确保 npm 版本较新
3. 查看详细错误信息：仔细阅读错误信息，根据具体错误类型搜索解决方案
4. 检查插件版本：确认使用的是最新版本的 QQBot 插件

删除 node_modules 重新安装：

rm -rf node_modules package-lock.json
npm install

6.9 编译成功后的操作

编译成功后，重启 OpenClaw 网关使插件生效：

openclaw gateway restart 

七、配置工具权限

7.1 了解 tools.profile

OpenClaw 2026.3.2 版本中，tools.profile 控制工具权限范围：

7.2 修改配置文件

编辑 ~/.openclaw/openclaw.json，修改 tools 配置：

{"tools":{"profile":"full"}}

7.3 生效方式

配置修改后，重启 OpenClaw 服务使配置生效：

openclaw gateway restart 

八、注意事项

1. 权限最小化原则: 若非必要，不建议直接使用 full，可根据需求选择 coding 等精细化取值
2. 配置格式校验: 修改 openclaw.json 时需确保 JSON 格式规范
3. 官方文档: 更多配置规则可查阅 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 编译错误，确保已安装必要的类型定义：

npm install --save-dev @types/node @types/ws --registry=https://registry.npmmirror.com 

权限问题

如果无法执行命令，检查 tools.profile 配置是否设置为 full 或 coding。

配置不生效

修改配置后，确保重启 OpenClaw 网关服务：

openclaw gateway restart