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:

bash 复制代码

# 安装 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:

bash 复制代码

# 使用 Homebrew 安装
brew install node

# 验证安装
node --version
npm --version

Windows:

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

2. 安装 OpenClaw

bash 复制代码

# 全局安装 OpenClaw CLI
npm install -g openclaw

# 验证安装
openclaw --version

# 查看帮助信息
openclaw help

3. 初始化 OpenClaw

bash 复制代码

# 创建工作目录
mkdir -p ~/.openclaw/workspace
cd ~/.openclaw/workspace

# 初始化（首次运行会自动初始化）
openclaw gateway status

4. 启动 OpenClaw Gateway

bash 复制代码

# 启动 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. 基本配置示例

yaml 复制代码

# Gateway 配置
gateway:
  host: 127.0.0.1
  port: 8765
  debug: false

# AI 模型配置
models:
  default: zai/glm-4.7
  reasoning: zai/glm-4.7

# 工具配置
tools:
  browser:
    enabled: true
    headless: true
  web:
    search:
      provider: perplexity
      apiKey: "YOUR_PERPLEXITY_API_KEY"

# 通道配置
channels:
  qqbot:
    enabled: true
    autoReply: true

3. 配置环境变量

bash 复制代码

# 编辑环境变量文件
nano ~/.openclaw/.env

# 添加以下内容（根据实际情况填写）
PERPLEXITY_API_KEY=your_api_key_here
OPENCLAW_LOG_LEVEL=info

4. 安装常用依赖

bash 复制代码

# 安装 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 \
  libxrandr2 \
  xdg-utils

QQ 机器人接入

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

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

1. 检查 QQBot 扩展

bash 复制代码

# 查看已安装的扩展
ls -la ~/.openclaw/extensions/

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

2. 配置 QQBot

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

bash 复制代码

# 找到 QQBot 配置文件
find ~/.openclaw -name "*qqbot*" -type f

# 编辑配置
nano ~/.openclaw/extensions/qqbot/config.yaml

3. QQBot 配置示例

yaml 复制代码

# 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 使配置生效

bash 复制代码

openclaw gateway restart

方式二：安装 QQBot 扩展

如果需要安装 QQBot 扩展：

bash 复制代码

# 使用 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

bash 复制代码

# 克隆 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 配置示例

json 复制代码

{
  "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

bash 复制代码

npm start

4. 配置 OpenClaw 连接 NapCat

编辑 OpenClaw 配置文件：

yaml 复制代码

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

验证与测试

1. 验证 OpenClaw Gateway

bash 复制代码

# 查看 Gateway 状态
openclaw gateway status

# 预期输出：
# ✓ OpenClaw Gateway is running
# Version: x.x.x
# Runtime: Linux x.x.x

2. 验证 QQBot 连接

bash 复制代码

# 查看 OpenClaw 日志
openclaw gateway logs

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

3. 测试机器人

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

复制代码

测试消息

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

4. 测试功能

测试图片发送：

复制代码

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

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

测试命令：

复制代码

/help
/status

常见问题排查

问题 1：OpenClaw Gateway 无法启动

症状：

bash 复制代码

$ openclaw gateway start
Error: Failed to start Gateway

解决方法：

bash 复制代码

# 检查端口占用
lsof -i :8765

# 查看详细日志
openclaw gateway logs --tail=100

# 尝试重启系统
sudo reboot

问题 2：QQBot 连接失败

症状：

复制代码

[ERROR] Failed to connect to QQBot

解决方法：

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

bash 复制代码

# 查看 Gateway 日志
openclaw gateway logs

# 测试 QQBot API 连接
curl http://127.0.0.1:8080/status

问题 3：Browser 工具无法使用

症状：

复制代码

Error: No supported browser found

解决方法：

bash 复制代码

# 检查 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：命令执行无输出

症状：

bash 复制代码

$ whoami
# 无输出

解决方法：

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

bash 复制代码

# 检查当前用户
id

# 使用绝对路径执行
/usr/bin/whoami

问题 5：npm 安装失败

症状：

复制代码

Error: EACCES: permission denied

解决方法：

bash 复制代码

# 方法 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

参考资源

官方文档

QQ 机器人相关

其他工具

附录

A. 常用命令速查

bash 复制代码

# 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

yaml 复制代码

# OpenClaw 完整配置示例

# Gateway 配置
gateway:
  host: 0.0.0.0
  port: 8765
  debug: false
  logLevel: info

# 模型配置
models:
  default: zai/glm-4.7
  reasoning: zai/glm-4.7

# 工具配置
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