一、环境准备
1.1 安装 Node.js
brew install node
验证安装:
npm -v # 输出:11.11.0
1.2 配置 npm 镜像源
配置淘宝镜像源以加速下载:
介绍在 macOS 环境下安装配置 OpenClaw 及 QQBot 插件的完整流程。涵盖 Node.js 环境搭建、OpenClaw 基础安装与向导配置、常见错误如 origin 限制和配对问题的解决、浏览器扩展启用。重点详述了 QQBot 插件的 TypeScript 编译过程,包括缺失类型定义的处理、tsconfig.json 配置优化以及权限设置调整,确保插件正常运行。
brew install node
验证安装:
npm -v # 输出:11.11.0
配置淘宝镜像源以加速下载:
npm config set registry https://registry.npmmirror.com
验证配置:
npm config get registry # 输出:https://registry.npmmirror.com 即为配置成功
npm install -g openclaw@latest
验证安装:
openclaw --version # 输出:2026.3.2
openclaw onboard
在向导中选择:
编辑配置文件 ~/.openclaw/openclaw.json,在 gateway 段中添加:
"gateway":{"controlUi":{"allowedOrigins":["*"]}}
openclaw devices list
RequestIdopenclaw devices approve <RequestId>
openclaw browser extension install
插件文件会下载到 ~/.openclaw/browser/chrome-extension/
macOS 默认隐藏以 . 开头的文件和目录,可通过以下方式查看:
Cmd + Shift + . 切换显示隐藏文件open ~/.openclaw# 启用托管模式(隔离、无需插件)
openclaw config set browser.defaultProfile "openclaw"
# 重启网关生效
openclaw gateway restart
openclaw plugins install @sliverp/qqbot@latest
访问 QQ 机器人官方页面 获取 AppId 和 AppSecret。
openclaw channels add --channel qqbot --token "AppId:AppSecret"
openclaw gateway restart
QQBot 插件使用 TypeScript 编写,安装后需要进行编译才能正常运行。由于插件依赖的类型定义可能不完整,编译过程中常会遇到各种错误,需要手工处理。
重要:以下所有命令都需要在 QQBot 插件目录下执行
cd ~/.openclaw/extensions/qqbot/
首先尝试编译,查看具体错误:
npm run build
错误信息:
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
错误信息:
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}}
错误信息:
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
编辑 tsconfig.json,使用以下配置可以避免大多数编译错误:
{"compilerOptions":{"noImplicitAny":false,"skipLibCheck":true}}
配置说明:
noImplicitAny: false - 关闭隐式 any 类型报错skipLibCheck: true - 跳过第三方库的类型检查,加快编译速度按照以下顺序执行,可以解决大多数编译问题:
# 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
编译成功后,应该看到类似以下输出:
$ npm run build > @sliverp/[email protected] build > tsc ||true
如果没有任何错误信息,说明编译成功。
如果编译仍然失败:
删除 node_modules 重新安装:
rm -rf node_modules package-lock.json
npm install
编译成功后,重启 OpenClaw 网关使插件生效:
openclaw gateway restart
OpenClaw 2026.3.2 版本中,tools.profile 控制工具权限范围:
| 取值 | 权限范围说明 |
|---|---|
| minimal | 仅开放会话状态(session_status)权限 |
| coding | 开放文件系统、运行时、会话、内存、图片相关权限 |
| messaging | (默认)仅开放消息相关权限 |
| full | 无权限限制,支持执行命令、发送消息等所有操作 |
编辑 ~/.openclaw/openclaw.json,修改 tools 配置:
{"tools":{"profile":"full"}}
配置修改后,重启 OpenClaw 服务使配置生效:
openclaw gateway restart
full,可根据需求选择 coding 等精细化取值openclaw.json 时需确保 JSON 格式规范# 查看版本
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

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML 转 Markdown 互为补充。 在线工具,Markdown 转 HTML在线工具,online
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML 转 Markdown在线工具,online