OpenClaw 配置与 QQ Bot接入指南

OpenClaw 配置与 QQ 机器人接入指南

创建时间：2026-03-18
更新时间：2026-03-18

目录

1. 系统要求
2. OpenClaw 安装
3. OpenClaw 配置
4. QQ 机器人接入
5. 验证与测试
6. 常见问题排查
7. 参考资源

系统要求

硬件要求

• CPU：2 核心以上
• 内存：4GB 以上（推荐 8GB）
• 硬盘：20GB 以上可用空间

软件要求

• 操作系统：Linux (Ubuntu 20.04+ 推荐推荐)、macOS、Windows
• Node.js：v18+ （推荐 v20+）
• npm：v9+
• Git

网络要求

• 稳定的互联网连接
• 如果需要访问国外网站，建议配置代理

OpenClaw 安装

1. 安装 Node.js 和 npm

Ubuntu/Debian:

# 安装 Node.js 20.xcurl-fsSL https://deb.nodesource.com/setup_20.x |sudo-Ebash - sudoapt-getinstall-y nodejs # 验证安装node--versionnpm--version

macOS:

# 使用 Homebrew 安装 brew installnode# 验证安装node--versionnpm--version

Windows:

访问 Node.js 官网 下载并安装 LTS 版本。

2. 安装 OpenClaw

# 全局安装 OpenClaw CLInpminstall-g openclaw # 验证安装 openclaw --version# 查看帮助信息 openclaw help

3. 初始化 OpenClaw

# 创建工作目录mkdir-p ~/.openclaw/workspace cd ~/.openclaw/workspace # 初始化（首次运行会自动初始化） openclaw gateway status 

4. 启动 OpenClaw Gateway

# 启动 Gateway 守护进程 openclaw gateway start # 查看 Gateway 状态 openclaw gateway status # 查看 Gateway 日志 openclaw gateway logs # 重启 Gateway openclaw gateway restart # 停止 Gateway openclaw gateway stop 

OpenClaw 配置

1. 配置文件位置

配置文件位于：~/.openclaw/config/config.yaml

2. 基本配置示例

# Gateway 配置gateway:host: 127.0.0.1 port:8765debug:false# AI 模型配置models:default: zai/glm-4.7reasoning: zai/glm-4.7# 工具配置tools:browser:enabled:trueheadless:trueweb:search:provider: perplexity apiKey:"YOUR_PERPLEXITY_API_KEY"# 通道配置channels:qqbot:enabled:trueautoReply:true

3. 配置环境变量

# 编辑环境变量文件nano ~/.openclaw/.env # 添加以下内容（根据实际情况填写）PERPLEXITY_API_KEY=your_api_key_here OPENCLAW_LOG_LEVEL=info 

4. 安装常用依赖

# 安装 Chrome 浏览器（用于 browser 工具）sudoapt-get update sudoapt-getinstall-ywget gnupg ca-certificates # 添加 Chrome 仓库wget-q-O - https://dl-ssl.google.com/linux/linux_signing_key.pub |sudo gpg --dearmor-o /usr/share/keyrings/google-chrome.gpg echo"deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main"|sudotee /etc/apt/sources.list.d/google-chrome.list # 更新并安装sudoapt-get update sudoapt-getinstall-y google-chrome-stable # 验证安装 google-chrome --version# 安装 Chrome 依赖sudoapt-getinstall-y\ libnss3 \ libxss1 \ libasound2 \ libatk-bridge2.0-0 \ libatk1.0-0 \ libatspi2.0-0 \ libcairo2 \ libcups2 \ libdbus-1-3 \ libdrm2 \ libgbm1 \ libgtk-3-0 \ libnspr4 \ libxcomposite1 \ libxdamage1 \ libxfixes3 \ libxrandr2 \ xdg-utils 

QQ 机器人接入

方式一：使用已有的 QQBot 扩展

假设你已经有了 QQBot 扩展（基于当前环境判断），以下是配置步骤：

1. 检查 QQBot 扩展

# 查看已安装的扩展ls-la ~/.openclaw/extensions/ # 或查看扩展目录ls-la ~/.local/share/pnpm/global/*/node_modules/openclaw/extensions/ 

2. 配置 QQBot

编辑 QQBot 配置文件（位置可能有所不同）：

# 找到 QQBot 配置文件find ~/.openclaw -name"*qqbot*"-type f # 编辑配置nano ~/.openclaw/extensions/qqbot/config.yaml 

3. QQBot 配置示例

# QQ 机器人配置qqbot:enabled:trueaccount:uin:"你的QQ号"password:"你的QQ密码"server:host: 127.0.0.1 port:8080features:autoReply:trueimageDownload:truevoiceUpload:truevideoUpload:truefileUpload:true

4. 重启 Gateway 使配置生效

openclaw gateway restart 

方式二：安装 QQBot 扩展

如果需要安装 QQBot 扩展：

# 使用 ClawHub 安装 clawhub search qqbot # 安装找到的 QQBot 扩展 clawhub install<package-name># 或者手动安装cd ~/.openclaw/extensions git clone https://github.com/your-repo/qqbot.git cd qqbot npminstall

方式三：使用第三方 QQ 机器人框架（如 NapCat）

如果需要使用 NapCat（基于 NTQQ 的 QQ 机器人框架）：

1. 安装 NapCat

# 克隆 NapCatcd ~ git clone https://github.com/NapNeko/NapCatQQ.git cd NapCatQQ # 安装依赖npminstall# 配置 NapCatcp config.example.json config.json nano config.json 

2. NapCat 配置示例

{"qq":{"account":"你的QQ号","password":"你的QQ密码"},"server":{"host":"127.0.0.1","port":3000,"httpApi":true,"wsApi":true},"message":{"ignoreSelf":true,"enableGroupMessage":true,"enablePrivateMessage":true}}

3. 启动 NapCat

npm start 

4. 配置 OpenClaw 连接 NapCat

编辑 OpenClaw 配置文件：

# 添加 NapCat 连接配置channels:qqbot:enabled:truetype: napcat endpoint:host: 127.0.0.1 port:3000account:uin:"你的QQ号"

验证与测试

1. 验证 OpenClaw Gateway

# 查看 Gateway 状态 openclaw gateway status # 预期输出：# ✓ OpenClaw Gateway is running# Version: x.x.x# Runtime: Linux x.x.x

2. 验证 QQBot 连接

# 查看 OpenClaw 日志 openclaw gateway logs # 检查是否有 QQBot 连接成功的日志# 预期输出类似：# [INFO] QQBot connected: account=xxxxx

3. 测试机器人

通过你的另一个 QQ 号向机器人发送测试消息：

测试消息 

机器人应该会回复（根据配置）。

4. 测试功能

测试图片发送：

发送一张图片（QQ聊天窗口发送图片） 

机器人应该能接收并处理图片。

测试命令：

/help /status 

常见问题排查

问题 1：OpenClaw Gateway 无法启动

症状：

$ openclaw gateway start Error: Failed to start Gateway 

解决方法：

# 检查端口占用lsof-i :8765 # 查看详细日志 openclaw gateway logs --tail=100# 尝试重启系统sudoreboot

问题 2：QQBot 连接失败

症状：

[ERROR] Failed to connect to QQBot 

解决方法：

1. 检查 QQ 账号密码是否正确
2. 检查网络连接
3. 检查 QQBot 服务是否运行
4. 查看详细日志

# 查看 Gateway 日志 openclaw gateway logs # 测试 QQBot API 连接curl http://127.0.0.1:8080/status 

问题 3：Browser 工具无法使用

症状：

Error: No supported browser found 

解决方法：

# 检查 Chrome 是否安装which google-chrome # 安装 Chrome（如果未安装）sudoapt-getinstall-y google-chrome-stable # 检查依赖 ldd /usr/bin/google-chrome |grep"not found"# 安装缺失的依赖sudoapt-getinstall-y libnss3 libxss1 libasound2 ... # 重启 Gateway openclaw gateway restart 

问题 4：命令执行无输出

症状：

$ whoami# 无输出

解决方法：

1. 检查沙箱权限
2. 检查是否在正确的用户下运行
3. 尝试使用绝对路径

# 检查当前用户id# 使用绝对路径执行 /usr/bin/whoami 

问题 5：npm 安装失败

症状：

Error: EACCES: permission denied 

解决方法：

# 方法 1：使用 sudosudonpminstall-g<package># 方法 2：修复 npm 权限mkdir ~/.npm-global npm config set prefix '~/.npm-global'echo'export PATH=~/.npm-global/bin:$PATH'>> ~/.bashrc source ~/.bashrc 

参考资源

官方文档

• OpenClaw 官方文档
• OpenClaw GitHub
• ClawHub 技能市场

QQ 机器人相关

• NapCat GitHub
• Go-CQHTTP
• OneBot v11 标准

其他工具

• Node.js 官网
• npm 文档

附录

A. 常用命令速查

# OpenClaw Gateway openclaw gateway start # 启动 openclaw gateway stop # 停止 openclaw gateway restart # 重启 openclaw gateway status # 状态 openclaw gateway logs # 日志# 技能管理 clawhub search <keyword># 搜索技能 clawhub install<package># 安装技能 clawhub update # 更新技能# 会话管理 openclaw sessions list # 列出会话 openclaw session status # 会话状态# 帮助 openclaw help# 帮助信息 openclaw --version# 版本信息

B. 配置文件模板

完整配置文件示例：config.yaml

# OpenClaw 完整配置示例# Gateway 配置gateway:host: 0.0.0.0 port:8765debug:falselogLevel: info # 模型配置models:default: zai/glm-4.7reasoning: zai/glm-4.7# 工具配置tools:browser:enabled:trueheadless:truenoSandbox:falseweb:search:provider: perplexity apiKey:"${PERPLEXITY_API_KEY}"# 通道配置channels:qqbot:enabled:truetype: napcat endpoint:host: 127.0.0.1 port:3000account:uin:"YOUR_QQ_NUMBER"# 技能配置skills:autoLoad:trueloadPaths:- ~/.openclaw/extensions/*/skills/*- ~/.openclaw/workspace/skills/* 

文档结束

如有问题，请查看日志文件：

• Gateway 日志：~/.openclaw/logs/gateway.log
• 通道日志：~/.openclaw/logs/qqbot.log