OpenClaw 配置与 QQ Bot接入指南
OpenClaw 配置与 QQ 机器人接入指南
创建时间：2026-03-18
更新时间：2026-03-18
目录
系统要求
硬件要求
- 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--versionmacOS:
# 使用 Homebrew 安装 brew installnode# 验证安装node--versionnpm--versionWindows:
访问 Node.js 官网 下载并安装 LTS 版本。
2. 安装 OpenClaw
# 全局安装 OpenClaw CLInpminstall-g openclaw # 验证安装 openclaw --version# 查看帮助信息 openclaw help3. 初始化 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:true3. 配置环境变量
# 编辑环境变量文件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:true4. 重启 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.x2. 验证 QQBot 连接
# 查看 OpenClaw 日志 openclaw gateway logs # 检查是否有 QQBot 连接成功的日志# 预期输出类似：# [INFO] QQBot connected: account=xxxxx3. 测试机器人
通过你的另一个 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 解决方法：
- 检查 QQ 账号密码是否正确
- 检查网络连接
- 检查 QQBot 服务是否运行
- 查看详细日志
# 查看 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# 无输出解决方法：
- 检查沙箱权限
- 检查是否在正确的用户下运行
- 尝试使用绝对路径
# 检查当前用户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 参考资源
官方文档
QQ 机器人相关
其他工具
附录
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
