OpenClaw 部署与 QQ 机器人接入指南
更新时间：2026-03-18
系统要求
在开始之前，请确保你的环境满足以下基础条件。
硬件配置
- CPU：2 核心以上
- 内存：4GB 起步（推荐 8GB）
- 硬盘：至少 20GB 可用空间
软件环境
- 操作系统：Linux (Ubuntu 20.04+)、macOS 或 Windows
- Node.js：v18+（强烈建议 v20+ LTS）
- npm：v9+
- Git
网络环境
- 稳定的互联网连接
- 若需访问海外资源，请提前配置好代理
安装 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
npm --version
Windows 用户： 直接前往 Node.js 官网 下载并安装 LTS 版本。
2. 安装 CLI 工具
全局安装 OpenClaw 命令行工具：
npm install -g openclaw
openclaw --version
openclaw help
3. 初始化工作区
创建目录并初始化网关：
mkdir -p ~/.openclaw/workspace
cd ~/.openclaw/workspace
openclaw gateway status
首次运行会自动完成初始化。
4. 启动 Gateway
openclaw gateway start
openclaw gateway status
openclaw gateway logs
openclaw gateway restart
openclaw gateway stop
配置 OpenClaw
配置文件默认位于 ~/.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. 环境变量管理
编辑 .env 文件存放敏感信息：
nano ~/.openclaw/.env
添加内容：
PERPLEXITY_API_KEY=your_api_key_here
OPENCLAW_LOG_LEVEL=info
3. 浏览器依赖安装
使用 Browser 工具需要 Chrome 支持。以 Ubuntu 为例：
sudo apt-get update
sudo apt-get install -y wget gnupg ca-certificates
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
同时安装必要的运行时依赖：
sudo apt-get install -y libnss3 libxss1 libasound2 libatk-bridge2.0-0 libgtk-3-0 libdrm2 libgbm1
QQ 机器人接入方案
根据现有环境，可选择集成方式。
方案一：使用内置扩展
检查已安装的扩展：
ls -la ~/.openclaw/extensions/
编辑配置文件：
nano ~/.openclaw/extensions/qqbot/config.yaml
配置示例：
qqbot:
enabled: true
account:
uin: "你的 QQ 号"
password: "你的 QQ 密码"
server:
host: 127.0.0.1
port: 8080
features:
autoReply: true
imageDownload: true
voiceUpload: true
修改后重启 Gateway 生效：openclaw gateway restart
方案二：使用 NapCat 框架
NapCat 是基于 NTQQ 的第三方框架，适合更复杂的场景。
1. 安装与配置
cd ~
git clone https://github.com/NapNeko/NapCatQQ.git
cd NapCatQQ
npm install
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 }
}
启动服务：npm start
3. 连接 OpenClaw 在 OpenClaw 配置文件中指定 NapCat 端点：
channels:
qqbot:
enabled: true
type: napcat
endpoint:
host: 127.0.0.1
port: 3000
account:
uin: "YOUR_QQ_NUMBER"
验证与测试
1. 检查网关状态
openclaw gateway status
# 预期输出包含 Version 和 Runtime 信息
2. 查看日志确认连接
openclaw gateway logs
# 查找类似 [INFO] QQBot connected: account=xxxxx 的记录
3. 功能测试
向机器人发送消息、图片或使用 /help、/status 命令。观察回复是否符合预期。
常见问题排查
Gateway 无法启动
检查端口占用：lsof -i :8765。查看详细日志：openclaw gateway logs --tail=100。
QQBot 连接失败
- 核对账号密码是否正确。
- 确认网络连接正常。
- 测试 API 连通性：
curl http://127.0.0.1:8080/status
Browser 工具报错 No supported browser found
确认 Chrome 已安装且依赖完整：which google-chrome。缺失依赖时重新执行安装脚本。
权限错误 (EACCES)
尝试使用 sudo 安装全局包，或修复 npm 权限配置：
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
常用命令速查
# 网关控制
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
