macOS 上 OpenClaw + QQBot 安装指南

一、环境准备

1.1 安装 Node.js

bash 复制代码

brew install node

验证安装：

bash 复制代码

npm -v
# 输出: 11.11.0

1.2 配置 npm 镜像源

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

bash 复制代码

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

验证配置：

bash 复制代码

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

二、安装 OpenClaw

2.1 安装 OpenClaw

bash 复制代码

npm install -g openclaw@latest

验证安装：

bash 复制代码

openclaw --version
# 输出: 2026.3.2

2.2 向导式配置

bash 复制代码

openclaw onboard

在向导中选择：

Onboarding mode: QuickStart（Configure details later via openclaw configure）

三、解决常见配置问题

3.1 解决 "origin not allowed" 错误

编辑配置文件 ~/.openclaw/openclaw.json，在 gateway 段中添加：

json 复制代码

"gateway": {
  "controlUi": {
    "allowedOrigins": ["*"]
  }
}

3.2 解决 "pairing required" 错误

列出设备请求：

bash 复制代码

openclaw devices list

记录 RequestId
批准设备配对：

bash 复制代码

openclaw devices approve <RequestId>

四、浏览器配置

4.1 安装 Chrome 插件

bash 复制代码

openclaw browser extension install

插件文件会下载到 ~/.openclaw/browser/chrome-extension/

4.2 查看隐藏文件

macOS 默认隐藏以 . 开头的文件和目录，可通过以下方式查看：

快捷键 : 在访达中按 Cmd + Shift + . 切换显示隐藏文件
终端打开 : open ~/.openclaw

4.3 启用托管模式

bash 复制代码

# 启用托管模式（隔离、无需插件）
openclaw config set browser.defaultProfile "openclaw"

# 重启网关生效
openclaw gateway restart

五、安装 QQBot 插件

5.1 安装插件

bash 复制代码

openclaw plugins install @sliverp/qqbot@latest

5.2 绑定 QQ 机器人

访问 QQ机器人官方页面获取 AppId 和 AppSecret。

bash 复制代码

openclaw channels add --channel qqbot --token "AppId:AppSecret"

5.3 重启服务

bash 复制代码

openclaw gateway restart

六、编译 QQBot 插件（重点）

6.1 为什么需要手工编译

QQBot 插件使用 TypeScript 编写，安装后需要进行编译才能正常运行。由于插件依赖的类型定义可能不完整，编译过程中常会遇到各种错误，需要手工处理。

6.2 进入插件目录

重要：以下所有命令都需要在 QQBot 插件目录下执行

bash 复制代码

cd /Users/yijian/.openclaw/extensions/qqbot/

6.3 尝试编译并识别错误

首先尝试编译，查看具体错误：

bash 复制代码

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

bash 复制代码

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 类型检查：

json 复制代码

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

bash 复制代码

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

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

bash 复制代码

# 清除 npm 缓存
npm cache clean --force

# 重新安装
npm install --save-dev @types/node --registry=https://registry.npmmirror.com

6.5 完整的 TypeScript 配置

编辑 tsconfig.json，使用以下配置可以避免大多数编译错误：

json 复制代码

{
  "compilerOptions": {
    "noImplicitAny": false,
    "skipLibCheck": true
  }
}

配置说明：

noImplicitAny: false - 关闭隐式 any 类型报错
skipLibCheck: true - 跳过第三方库的类型检查，加快编译速度

6.6 完整的编译流程

按照以下顺序执行，可以解决大多数编译问题：

bash 复制代码

# 1. 进入插件目录
cd /Users/yijian/.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 验证编译结果

编译成功后，应该看到类似以下输出：

bash 复制代码

$ npm run build

> @sliverp/qqbot@1.5.3 build
> tsc || true

如果没有任何错误信息，说明编译成功。

6.8 编译失败的处理

如果编译仍然失败：

检查 Node.js 版本：确保使用较新的 Node.js 版本（建议 v18+）
检查 npm 版本：确保 npm 版本较新
删除 node_modules 重新安装 ：
bash 复制代码
```
rm -rf node_modules package-lock.json
npm install
```
查看详细错误信息：仔细阅读错误信息，根据具体错误类型搜索解决方案
检查插件版本：确认使用的是最新版本的 QQBot 插件

6.9 编译成功后的操作

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

bash 复制代码

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 配置：

json 复制代码

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

7.3 生效方式

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

bash 复制代码

openclaw gateway restart

八、注意事项

权限最小化原则 : 若非必要，不建议直接使用 full，可根据需求选择 coding 等精细化取值
配置格式校验 : 修改 openclaw.json 时需确保 JSON 格式规范
官方文档 : 更多配置规则可查阅 OpenClaw 官方文档

九、常用命令

bash 复制代码

# 查看版本
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 编译错误，确保已安装必要的类型定义：

bash 复制代码

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

权限问题

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

配置不生效

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

bash 复制代码

openclaw gateway restart