JavaScriptNode.jsAI
OpenClaw 配置与 QQ 机器人接入指南
OpenClaw 是基于 Node.js 的 AI 自动化框架。档涵盖系统环境要求、软件安装流程、核心配置文件说明及 QQ 机器人接入方案。支持通过内置扩展或 NapCat 第三方框架连接 QQ，实现消息收发与图片处理。包含常见问题排查与命令速查，帮助开发者快速部署本地 AI 助手。
OpenClaw 是基于 Node.js 的 AI 自动化框架。档涵盖系统环境要求、软件安装流程、核心配置文件说明及 QQ 机器人接入方案。支持通过内置扩展或 NapCat 第三方框架连接 QQ，实现消息收发与图片处理。包含常见问题排查与命令速查，帮助开发者快速部署本地 AI 助手。
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 版本。
# 全局安装 OpenClaw CLI
npm install -g openclaw
# 验证安装
openclaw --version
# 查看帮助信息
openclaw help
# 创建工作目录
mkdir -p ~/.openclaw/workspace
cd ~/.openclaw/workspace
# 初始化（首次运行会自动初始化）
openclaw gateway status
# 启动 Gateway 守护进程
openclaw gateway start
# 查看 Gateway 状态
openclaw gateway status
# 查看 Gateway 日志
openclaw gateway logs
# 重启 Gateway
openclaw gateway restart
# 停止 Gateway
openclaw gateway stop
配置文件位于：~/.openclaw/config/config.yaml
# Gateway 配置
gateway:
host: 127.0.0.1
port: 8765
debug: false
# AI 模型配置
models:
default: glm-4.7
reasoning: glm-4.7
# 工具配置
tools:
browser:
enabled: true
headless: true
web:
search:
provider: perplexity
apiKey: "YOUR_PERPLEXITY_API_KEY"
# 通道配置
channels:
qqbot:
enabled: true
autoReply: true
# 编辑环境变量文件
nano ~/.openclaw/.env
# 添加以下内容（根据实际情况填写）
PERPLEXITY_API_KEY=your_api_key_here
OPENCLAW_LOG_LEVEL=info
# 安装 Chrome 浏览器（用于 browser 工具）
sudo apt-get update
sudo apt-get install -y wget gnupg ca-certificates
# 添加 Chrome 仓库
wget -qO- 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
假设你已经有了 QQBot 扩展（基于当前环境判断），以下是配置步骤：
# 查看已安装的扩展
ls -la ~/.openclaw/extensions/
# 或查看扩展目录
ls -la ~/.local/share/pnpm/global/*/node_modules/openclaw/extensions/
编辑 QQBot 配置文件（位置可能有所不同）：
# 找到 QQBot 配置文件
find ~/.openclaw -name "*qqbot*" -type f
# 编辑配置
nano ~/.openclaw/extensions/qqbot/config.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
openclaw gateway restart
如果需要安装 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
如果需要使用 NapCat（基于 NTQQ 的 QQ 机器人框架）：
# 克隆 NapCat
cd ~
git clone https://github.com/NapNeko/NapCatQQ.git
cd NapCatQQ
# 安装依赖
npm install
# 配置 NapCat
cp config.example.json config.json
nano config.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
}
}
npm start
编辑 OpenClaw 配置文件：
# 添加 NapCat 连接配置
channels:
qqbot:
enabled: true
type: napcat
endpoint:
host: 127.0.0.1
port: 3000
account:
uin: "你的 QQ 号"
# 查看 Gateway 状态
openclaw gateway status
# 预期输出：
# ✓ OpenClaw Gateway is running
# Version: x.x.x
# Runtime: Linux x.x.x
# 查看 OpenClaw 日志
openclaw gateway logs
# 检查是否有 QQBot 连接成功的日志
# 预期输出类似：
# [INFO] QQBot connected: account=xxxxx
通过你的另一个 QQ 号向机器人发送测试消息：
测试消息
机器人应该会回复（根据配置）。
测试图片发送：
发送一张图片（QQ 聊天窗口发送图片）。机器人应该能接收并处理图片。
测试命令：
/help
/status
症状：
$ openclaw gateway start
Error: Failed to start Gateway
解决方法：
# 检查端口占用
lsof -i :8765
# 查看详细日志
openclaw gateway logs --tail=100
# 尝试重启系统
sudo reboot
症状：
[ERROR] Failed to connect to QQBot
解决方法：
# 查看 Gateway 日志
openclaw gateway logs
# 测试 QQBot API 连接
curl http://127.0.0.1:8080/status
症状：
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
症状：
$ whoami
# 无输出
解决方法：
# 检查当前用户
id
# 使用绝对路径执行
/usr/bin/whoami
症状：
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 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 # 版本信息
完整配置文件示例：config.yaml
# OpenClaw 完整配置示例
# Gateway 配置
gateway:
host: 0.0.0.0
port: 8765
debug: false
logLevel: info
# 模型配置
models:
default: glm-4.7
reasoning: 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
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online