OpenClaw 本地部署 QQ /飞书机器人接入手册

1 部署前准备

1.1 系统与环境要求

Windows 10/11（建议专业版）
WSL2 已安装并配置好 Ubuntu 发行版
安装流程： https://blog.csdn.net/weixin_45041493/article/details/160543852?spm=1001.2014.3001.5502
Node.js ≥ 22（推荐 24.x）
Git（可选，用于源码构建）
稳定的科学上网工具（访问 GitHub 和部分 API 可能需要）

2、配置 AI 模型（智谱 AI）

2.1 获取 API Key

访问智谱开放平台注册/登录
进入 API Keys 页面，点击「新建 API Key」
复制生成的密钥（格式示例：a515d134... 或 sk-...）

3、安装OpenClaw

1. 打开 WSL 终端

方法一：按 Win + R，输入 wsl 回车
方法二：在开始菜单中打开「Ubuntu」应用
方法三：按 Win +x键，搜索 PowerShell、选择以管理员身份运行，输入wsl回车

3.1 执行一键安装脚本

javascript 复制代码

curl -fsSL https://openclaw.ai/install.sh | bash

安装过程中会提示选择网关运行时，选 Node (recommended)

3.2 运行配置向导关键步骤

javascript 复制代码

openclaw onboard --mode local

按以下选项填写：

配置项	选择
Model/auth provider	Z.AI
Z.AI auth method	Z.AI API key
API Key	粘贴上一步获取的智谱 Key
Default model	推荐 zai/glm-4.7-flash（免费）或 zai/glm-5.1
Channel	Skip for now
Search provider	Skip for now
Configure skills now	No
Enable hooks	session-memory，回车
Hatch your bot?	Do this later

3.3 禁用 WSL 下冲突的插件（必须）

javascript 复制代码

openclaw plugins disable bonjour

原因：bonjour 插件在 WSL 环境中会导致网关崩溃（mDNS 广播失败）

3.4 启动网关服务

javascript 复制代码

systemctl --user restart openclaw-gateway
systemctl --user status openclaw-gateway

确认状态为 active (running)

3.5 测试 TUI 和 Web UI

javascript 复制代码

openclaw tui

如果提示 unauthorized，请使用带 token 的方式连接（见常见问题）
成功后会显示 connected to gateway，输入你好测试模型回复

此时它会自动再打开一个命令窗口来启动服务:

同时，大约过30秒左右，我们回到刚才的设置窗口，选择 Open the Web UI ，打开 OpenClaw 的UI界面：

4.接入即时通讯平台

4.1 QQ 机器人接入（个人版仅支持私聊）

4.1.1 注册 QQ 机器人

访问 QQ 开放平台

创建应用 → 选择「机器人」

记录以下三个值：

appId（纯数字）

clientSecret（一串字符）

token（你自己设置的验证 Token）

4.1.2 QQ 频道

1.首先需要自己去注册QQ开发平台帐号进入之后选择创建QQ机器人

之后生成机器人编码等

4.1.3 配置openclaw

在本地的的cmd中

在WSL终端中执行：

javascript 复制代码

wsl

安装QQ机器人插件

javascript 复制代码

openclaw plugins install @tencent-connect/openclaw-qqbot@latest

直接安装插件后可能无法正常工作，需要手动修改配置文件

javascript 复制代码

# 编辑配置文件
nano ~/.openclaw/openclaw.json

然后文本编辑中加入

javascript 复制代码

"channels": {
    "qqbot": {
      "enabled": true,
      "allowFrom": ["*"],
      "appId": "1903906163",        // 替换为你的appId
      "clientSecret": "XXX",         // 替换为你的clientSecret
      "token": "你的验证Token"        // 注意：这是开放平台设置的token，不是clientSecret
    }
}

🚀 重启网关

javascript 复制代码

systemctl --user restart openclaw-gateway

🔍 检查日志确认连接

javascript 复制代码

journalctl --user -u openclaw-gateway -n 30 --no-pager | grep -i qq

之后就可以在QQ上进行智能对话了，也可以打开OpenClaw进行查看

4.1.4 QQ机器人收不到消息

javascript 复制代码

journalctl --user -u openclaw-gateway -n 30 | grep -i qq

确认机器人已添加为好友
确认开放平台已配置事件订阅
个人QQ机器人不支持群聊，仅限私聊

4.2接入飞书

4.2.1 飞书平台

在上面的基础上接入飞书

1.创建智能机器人

2.查看智能凭证

3.添加应用能力

4.配置应用权限

5.启用机器人能力

6、创建版本

4.2.2 配置OpenClaw

在控制台输入

javascript 复制代码

openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.appId "cli_xxxxx"
openclaw config set channels.feishu.appSecret "your_app_secret"
openclaw config set channels.feishu.encryptKey "your_verification_token"
# 推荐使用 WebSocket 模式，稳定可靠
openclaw config set channels.feishu.connectionMode websocket
# 私聊策略设为 pairing，等待你批准后再对话，更安全
openclaw config set channels.feishu.dmPolicy pairing

重启网关：执行以下命令，让配置生效：

javascript 复制代码

systemctl --user restart openclaw-gateway
# 查看详细日志
journalctl --user -u openclaw-gateway -f | grep -i feishu

javascript 复制代码

# 验证飞书配置是否正确
openclaw config get channels.feishu
# 应显示 enabled: true 和你的appId

💡 提示：配置完成后会自动保存到 ~/.openclaw/openclaw.json

4.2.3 将"开发号"与"个人号"配对

找到你的 AI 助手：在飞书客户端顶部的搜索框里，输入你创建的应用名称，找到它。

发起对话并完成配对：向它发送任意消息（比如 hello）。由于我们设置了 pairing 模式，它会回复你一个配对码。

批准对话：在 WSL 终端输入 openclaw pairing list 查看待批准的请求，然后执行 openclaw pairing approve <配对码> #进行授权。

开始对话：配对成功后，AI 助手就会回复你的消息啦。

在飞书上进行测试，测试成功会有回复

4.2.4 问题：飞书机器人无响应

查看完整错误日志

javascript 复制代码

journalctl --user -u openclaw-gateway -n 50 --no-pager | grep -i feishu
# 常见原因：端口被占用
netstat -tulnp | grep 3000

4.2.5 更新openclaw

javascript 复制代码

curl -fsSL https://openclaw.ai/install.sh | bash
systemctl --user restart openclaw-gateway

5 .openclaw的文件位置查找报错

在文件资源管理的窗口中输入\wsl.localhost\Ubuntu-22.04\home\wangtao 报错

🚀 解决方案：强制重启 WSL 服务

这个方法会关闭所有正在运行的 WSL 系统，然后干净地重启，强制重新建立文件共享服务。整个过程不会删除或损坏你 WSL 里的任何文件。

请严格按照以下步骤操作：

第一步：关闭所有 WSL 实例

在 Windows 的开始菜单搜索"PowerShell"，然后右键选择 "以管理员身份运行"。

在弹出的管理员窗口中，输入以下命令并按回车：

javascript 复制代码

wsl --shutdown

第二步：重启你的 Ubuntu

现在，像平常一样重新打开你的 Ubuntu 应用（比如在开始菜单里点击 Ubuntu 图标）。等待它完全启动，直到出现让你输入命令的提示符。

第三步：验证问题是否解决

打开文件资源管理器（随便打开一个文件夹）。

在顶部的地址栏里，这次输入 \wsl.localhost 然后按回车。根据社区用户的经验，使用 \\wsl.localhost 通常比 \wsl$ 更稳定可靠。

你应该能看到一个名为 Ubuntu (或者你的发行版名称) 的文件夹，双击它就能访问 WSL 里的所有文件了。