跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客我的书AI学习GitHub 精选镜像AI 生图工具UI配色美学关于
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
TypeScriptNode.jsAI

macOS 上 OpenClaw + QQBot 安装指南

介绍在 macOS 环境下安装配置 OpenClaw 及 QQBot 插件的完整流程。涵盖 Node.js 环境搭建、OpenClaw 基础安装与向导配置、常见错误如 origin 限制和配对问题的解决、浏览器扩展启用。重点详述了 QQBot 插件的 TypeScript 编译过程，包括缺失类型定义的处理、tsconfig.json 配置优化以及权限设置调整，确保插件正常运行。

安卓系统发布于 2026/3/30更新于 2026/9/983 浏览

一、环境准备

1.1 安装 Node.js
brew install node

验证安装：

npm -v # 输出：11.11.0
1.2 配置 npm 镜像源

配置淘宝镜像源以加速下载：

npm config set registry https://registry.npmmirror.com

验证配置：

npm config get registry # 输出：https://registry.npmmirror.com 即为配置成功

二、安装 OpenClaw

2.1 安装 OpenClaw
npm install -g openclaw@latest

验证安装：

openclaw --version # 输出：2026.3.2
2.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' 错误
  1. 列出设备请求：
openclaw devices list
  1. 记录 RequestId
  2. 批准设备配对：
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 ~/.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 控制工具权限范围：

取值权限范围说明
minimal仅开放会话状态（session_status）权限
coding开放文件系统、运行时、会话、内存、图片相关权限
messaging（默认）仅开放消息相关权限
full无权限限制，支持执行命令、发送消息等所有操作
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

目录

  1. 一、环境准备
  2. 1.1 安装 Node.js
  3. 1.2 配置 npm 镜像源
  4. 二、安装 OpenClaw
  5. 2.1 安装 OpenClaw
  6. 2.2 向导式配置
  7. 三、解决常见配置问题
  8. 3.1 解决 “origin not allowed” 错误
  9. 3.2 解决 “pairing required” 错误
  10. 四、浏览器配置
  11. 4.1 安装 Chrome 插件
  12. 4.2 查看隐藏文件
  13. 4.3 启用托管模式
  14. 启用托管模式（隔离、无需插件）
  15. 重启网关生效
  16. 五、安装 QQBot 插件
  17. 5.1 安装插件
  18. 5.2 绑定 QQ 机器人
  19. 5.3 重启服务
  20. 六、编译 QQBot 插件（重点）
  21. 6.1 为什么需要手工编译
  22. 6.2 进入插件目录
  23. 6.3 尝试编译并识别错误
  24. 6.4 常见编译错误及解决方案
  25. 错误 1：找不到 ‘ws’ 模块的声明文件
  26. 错误 2：参数隐式具有 ‘any’ 类型
  27. 错误 3：找不到名称 ‘process’
  28. 清除 npm 缓存
  29. 重新安装
  30. 6.5 完整的 TypeScript 配置
  31. 6.6 完整的编译流程
  32. 1. 进入插件目录
  33. 2. 安装必要的类型定义
  34. 3. 如果安装失败，清除缓存
  35. 4. 重新安装类型定义
  36. 5. 修改 TypeScript 配置
  37. 编辑 tsconfig.json，添加或修改以下内容：
  38. {
  39. "compilerOptions": {
  40. "noImplicitAny": false,
  41. "skipLibCheck": true
  42. }
  43. }
  44. 6. 执行编译
  45. 6.7 验证编译结果
  46. 6.8 编译失败的处理
  47. 6.9 编译成功后的操作
  48. 七、配置工具权限
  49. 7.1 了解 tools.profile
  50. 7.2 修改配置文件
  51. 7.3 生效方式
  52. 八、注意事项
  53. 九、常用命令
  54. 查看版本
  55. 启动向导配置
  56. 重启网关
  57. 列出设备
  58. 批准设备
  59. 安装插件
  60. 添加通道
  61. 配置浏览器
  62. 十、故障排查
  63. 编译错误
  64. 权限问题
  65. 配置不生效

更多推荐文章

查看全部
  • 基于 Coze 与 OpenClaw 搭建飞书机器人群组
  • Jupyter Notebook 安装教程：Python 3.10 版本
  • Vivado 工程创建与 FPGA 开发流程指南
  • Web 架构深度解析：前后端分离与传统的利弊权衡
  • 基于 Java Socket 实现多人在线聊天系统
  • Java Web 开发：JSON 基础、@Test 测试与 Cookie Session 请求处理
  • Stable Diffusion 显存管理优化：解决 Automatic1111 内存爆满问题
  • gflags 与 spdlog 实战：C++ 命令行参数与高性能日志搭配
  • JetBrains IDE 集成 LeetCode 插件配置与使用指南
  • 字节跳动豆包系列深度拆解：国民级全模态 AI 的普惠化路径
  • Xilinx Vivado 付费 IP 核 License 状态解读与获取
  • Claude Scholar：AI 学术研究全流程助手
  • Java 栈与队列原理及手写实现
  • Python 爬虫实战指南：从基础请求到分布式框架
  • 微信小程序城市公交查询与失物招领系统的开发笔记
  • C# ImageSharp 与 JavaScript Canvas 图像处理性能对比
  • LightRAG 详解：基于图结构的检索增强生成系统实践
  • 新手如何从零开始学习漏洞挖掘与渗透测试
  • OpenClaw 配置多 Agent 及多 QQ、飞书机器人
  • C/C++ 内存分布与动态内存管理机制

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online

  • Markdown转HTML

    将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online