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

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

系统要求

硬件要求

• 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.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs
# 验证安装
node --version
npm --version

macOS:

# 使用 Homebrew 安装
brew install node
# 验证安装
node --version
npm --version

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

2. 安装 OpenClaw

# 全局安装 OpenClaw CLI
npm install -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: 8765
  debug: false
# AI 模型配置
models:
  default: custom-model
  reasoning: custom-model
# 工具配置
tools:
  browser:
    enabled: true
    headless: true
  web:
    search:
      provider: perplexity
      apiKey: "YOUR_PERPLEXITY_API_KEY"
# 通道配置
channels:
  qqbot:
    enabled: true
    autoReply: true

3. 配置环境变量

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

4. 安装常用依赖

# 安装 Chrome 浏览器（用于 browser 工具）
sudo apt-get update
sudo apt-get install -y wget 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" | sudo tee /etc/apt/sources.list.d/google-chrome.list
# 更新并安装
sudo apt-get update
sudo apt-get install -y google-chrome-stable
# 验证安装
google-chrome --version
# 安装 Chrome 依赖
sudo apt-get install -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 \
  libxrand2 \
  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: true
  account:
    uin: "你的 QQ 号"
    password: "你的 QQ 密码"
  server:
    host: 127.0.0.1
    port: 8080
  features:
    autoReply: true
    imageDownload: true
    voiceUpload: true
    videoUpload: true
    fileUpload: 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
npm install

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

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

1. 安装 NapCat

# 克隆 NapCat
cd ~
git clone https://github.com/NapNeko/NapCatQQ.git
cd NapCatQQ
# 安装依赖
npm install
# 配置 NapCat
cp 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: true
    type: napcat
    endpoint:
      host: 127.0.0.1
      port: 3000
    account:
      uin: "YOUR_QQ_NUMBER"

验证与测试

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
# 尝试重启系统
sudo reboot

问题 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（如果未安装）
sudo apt-get install -y google-chrome-stable
# 检查依赖
ldd /usr/bin/google-chrome | grep "not found"
# 安装缺失的依赖
sudo apt-get install -y libnss3 libxss1 libasound2 ...
# 重启 Gateway
openclaw gateway restart

问题 4：命令执行无输出

症状：

$ whoami
# 无输出

解决方法：

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

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

问题 5：npm 安装失败

症状：

Error: EACCES: permission denied

解决方法：

# 方法 1：使用 sudo
sudo npm install -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-name> # 安装技能
clawhub update # 更新技能
# 会话管理
openclaw sessions list # 列出会话
openclaw session status # 会话状态
# 帮助
openclaw help # 帮助信息
openclaw --version # 版本信息

B. 配置文件模板

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

# OpenClaw 完整配置示例
# Gateway 配置
gateway:
  host: 0.0.0.0
  port: 8765
  debug: false
  logLevel: info
# 模型配置
models:
  default: custom-model
  reasoning: custom-model
# 工具配置
tools:
  browser:
    enabled: true
    headless: true
    noSandbox: false
  web:
    search:
      provider: perplexity
      apiKey: "${PERPLEXITY_API_KEY}"
# 通道配置
channels:
  qqbot:
    enabled: true
    type: napcat
    endpoint:
      host: 127.0.0.1
      port: 3000
    account:
      uin: "YOUR_QQ_NUMBER"
# 技能配置
skills:
  autoLoad: true
  loadPaths:
    - ~/.openclaw/extensions/*/skills/*
    - ~/.openclaw/workspace/skills/*

---

日志文件路径：

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