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

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

本文档基于实际部署经验整理，旨在帮助开发者快速搭建 OpenClaw 环境并接入 QQ 机器人。

系统与环境准备

在开始之前，确保你的机器满足以下基础要求。OpenClaw 依赖 Node.js 生态，因此环境一致性很重要。

硬件与软件清单

• CPU：2 核心以上（推荐 4 核）
• 内存：4GB 起步（运行 AI 模型建议 8GB+）
• 硬盘：预留 20GB 空间用于缓存和日志
• 操作系统：Linux (Ubuntu 20.04+)、macOS 或 Windows
• 运行时：Node.js v18+ (推荐 v20 LTS)
• 包管理：npm v9+
• 版本控制：Git

网络方面需要保持连接稳定，若需调用海外 API（如 Perplexity），请提前配置好代理环境。

安装 OpenClaw

1. 准备 Node.js 环境

不同系统安装方式略有差异，选择适合你的一键执行即可。

Ubuntu/Debian:

# 添加 NodeSource 源并安装 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:

brew install node
node --version

Windows: 直接访问 Node.js 官网 下载并安装 LTS 版本，安装向导默认勾选 npm 即可。

2. 全局安装 CLI 工具

使用 npm 安装 OpenClaw 命令行工具：

npm install -g openclaw
openclaw --version
openclaw help

3. 初始化工作区

首次运行会自动创建配置目录，建议手动指定工作路径以便管理：

mkdir -p ~/.openclaw/workspace
cd ~/.openclaw/workspace
openclaw gateway status

4. 启动网关服务

Gateway 是 OpenClaw 的核心进程，负责调度模型和插件。

# 启动守护进程
openclaw gateway start

# 查看状态、日志或重启
openclaw gateway status
openclaw gateway logs
openclaw gateway restart
openclaw gateway stop

核心配置详解

配置文件位于 ~/.openclaw/config/config.yaml，这是整个系统的中枢。

1. 基础配置结构

gateway:
  host: 127.0.0.1
  port: 8765
  debug: false

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

2. 环境变量管理

敏感信息（如 API Key）建议放入 .env 文件，避免硬编码在配置中。

nano ~/.openclaw/.env
# 添加内容
PERPLEXITY_API_KEY=your_api_key_here
OPENCLAW_LOG_LEVEL=info

3. 浏览器依赖安装

由于启用了 Browser 工具，必须安装无头 Chrome 浏览器及其依赖库。这一步最容易踩坑，请务必按顺序执行。

# 更新源并安装基础工具
sudo apt-get update
sudo apt-get install -y wget gnupg ca-certificates

# 添加 Google 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

# 安装 Chrome
sudo apt-get update
sudo apt-get install -y google-chrome-stable
google-chrome --version

# 安装缺失的依赖库
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 扩展

如果你已有相关扩展，只需确认配置生效。

1. 检查扩展状态

   ls -la ~/.openclaw/extensions/
   

2. 编辑配置文件 找到对应目录下的 config.yaml：

   find ~/.openclaw -name "*qqbot*" -type f
   nano ~/.openclaw/extensions/qqbot/config.yaml
   

3. 配置示例

   qqbot:
     enabled: true
     account:
       uin: "你的 QQ 号"
       password: "你的 QQ 密码"
     server:
       host: 127.0.0.1
       port: 8080
     features:
       autoReply: true
       imageDownload: true
       voiceUpload: true
   

4. 重启网关

   openclaw gateway restart
   

方案二：通过 ClawHub 安装扩展

如果本地没有扩展，可以直接从市场拉取：

clawhub search qqbot
clawhub install <package-name>

或者手动克隆仓库：

cd ~/.openclaw/extensions
git clone https://github.com/your-repo/qqbot.git
cd qqbot
npm install

方案三：对接 NapCat (NTQQ)

NapCat 是基于 NTQQ 协议的成熟框架，稳定性较好。

1. 安装与配置 NapCat

   cd ~
   

git clone https://github.com/NapNeko/NapCatQQ.git cd NapCatQQ npm install

复制配置模板并修改

cp config.example.json config.json nano config.json

   `config.json` 关键配置：
   ```json
   {
     "qq": { "account": "你的 QQ 号", "password": "你的 QQ 密码" },
     "server": { "host": "127.0.0.1", "port": 3000, "httpApi": true, "wsApi": true },
     "message": { "ignoreSelf": true, "enableGroupMessage": true }
   }

2. 启动 NapCat

   npm start
   

3. 配置 OpenClaw 连接 在 config.yaml 中添加通道配置：

   channels:
     qqbot:
       enabled: true
       type: napcat
       endpoint:
         host: 127.0.0.1
         port: 3000
       account:
         uin: "YOUR_QQ_NUMBER"
   

验证与排查

1. 验证 Gateway 状态

openclaw gateway status
# 预期输出：✓ OpenClaw Gateway is running

2. 验证 QQBot 连接

查看日志是最直接的反馈方式：

openclaw gateway logs
# 查找类似 [INFO] QQBot connected: account=xxxxx 的记录

3. 功能测试

用另一个 QQ 号发送消息给机器人，观察回复情况。同时测试图片发送、指令 /help 等交互。

常见问题速查

• Gateway 无法启动：检查端口 8765 是否被占用 (lsof -i :8765)，查看详细日志排除冲突。
• QQBot 连接失败：核对账号密码，确认 NapCat 或 Bot 服务已启动且网络可达。
• Browser 工具报错：通常是 Chrome 依赖缺失，重新执行上述依赖安装步骤。
• 命令无输出：检查沙箱权限及当前用户权限，尝试使用绝对路径执行。
• npm 权限错误：避免直接使用 sudo npm install，建议配置 npm prefix 或使用 nvm 管理版本。

常用命令速查

# 服务管理
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

附录：完整配置模板

参考 config.yaml 完整结构：

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/*

调试过程中，重点关注 ~/.openclaw/logs/gateway.log 和通道日志 ~/.openclaw/logs/qqbot.log，大部分问题都能从中找到线索。