跳到主要内容 OpenClaw 安装与飞书机器人配置指南 | 极客日志
Shell / Bash Node.js AI
OpenClaw 安装与飞书机器人配置指南 OpenClaw AI Agent 框架的安装及飞书机器人配置流程。涵盖环境准备（Node.js）、工具安装、初始向导配置、飞书应用创建与权限设置、事件订阅配置及联调测试。文中包含常见故障排查指南，如事件订阅保存失败、机器人无响应、群聊权限不足等问题，并提供相应的命令修复方案，帮助用户完成私有化 AI 助手部署。
SqlMaster 发布于 2026/4/5 更新于 2026/4/13 一、OpenClaw 是什么？
OpenClaw 是一个开源的 AI Agent 框架，简单理解就是：它让你拥有一个私人 AI 助手，可以接入飞书、Telegram、WhatsApp、Discord 等各种聊天平台。
它的核心架构很简单：
your message -> Feishu/Telegram... -> OpenClaw Gateway ->
->
🔒 数据自托管，隐私可控
🔌 支持多种聊天平台（飞书、Telegram、WhatsApp、Discord……）
🧠 支持多种 AI 模型（Claude、GPT、Gemini……）
🛠 可扩展的 Skill 系统，像安装 App 一样给 AI 加技能
💻 完全开源免费
二、环境准备
2.1 系统要求 项目 要求 操作系统 Linux / macOS / Windows (WSL2) Node.js v22 或更高 网络 能访问飞书开放平台 + AI API
2.2 安装 Node.js（如果还没装）
node --version
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
💡 提示 ：输入 node --version 后如果显示 v22.x.x，说明安装成功。
三、安装 OpenClaw
3.1 一键安装 curl -fsSL https://openclaw.ai/install.sh | bash
iwr -useb https://openclaw.ai/install.ps1 | iex
看到版本号（如 2026.3.2）就说明安装成功了。
3.2 手动安装（备选）
⚠️ 注意 ：如果遇到 EACCES: permission denied 错误，不要用 sudo npm install -g！正确做法是调整 npm 目录权限。
四、初始配置（onboard 向导） openclaw onboard --install-daemon
AI 模型密钥 — 输入你的 Anthropic / OpenAI / Google API KeyGateway 设置 — 默认端口 18789，一般不用改聊天渠道 — 这里先跳过，我们后面单独配飞书
💡 --install-daemon 参数会把 Gateway 安装为系统服务，开机自动启动。
浏览器会自动打开 http://127.0.0.1:18789，这就是 OpenClaw 的控制面板。
五、飞书机器人配置全流程 这是本文的重头戏。飞书机器人配置分 三大步 ：飞书侧建应用 → OpenClaw 侧配置 → 联调测试。
5.1 安装飞书插件 OpenClaw 的飞书支持是通过插件提供的，先安装：
openclaw plugins install @openclaw/feishu
5.2 飞书开放平台：创建应用
Step 1：登录飞书开放平台
⚠️ 如果你用的是 Lark（国际版），地址是 https://open.larksuite.com/app。
Step 2：创建企业自建应用
点击 「创建企业自建应用」
填写应用名称（比如 '我的 AI 助手'）
填写应用描述
选一个图标
Step 3：获取凭证（重要！） 进入应用后，在 「凭证与基础信息」 页面，复制两个东西：
App ID （格式：cli_xxxxxxxxx）App Secret
🔐 App Secret 务必妥善保管 ，不要泄露给任何人，不要提交到 Git。
Step 4：配置权限 进入 「权限管理」 ，点击 「批量开通」 ，粘贴以下 JSON：
{ "scopes" : { "tenant" : [ "im:message" , "im:message.group_at_msg:readonly" , "im:message.p2p_msg:readonly" , "im:message:readonly" , "im:message:send_as_bot" , "im:resource" , "im:chat.access_event.bot_p2p_chat:read" , "im:chat.members:bot_access" , "contact:user.employee_id:readonly" ] , "user" : [ "im:chat.access_event.bot_p2p_chat:read" ] } }
💡 上面是最基本的权限集。如果后续需要操作飞书文档、多维表格等，可以追加更多权限（如 docx:document、bitable:app 等）。
Step 5：开启机器人能力
Step 6：配置事件订阅（⚠️ 这步容易翻车！）
选择「使用长连接接收事件」 （WebSocket 方式）添加事件：搜索并勾选 im.message.receive_v1（接收消息 v1）
🚨 大坑警告 ：一定要选「长连接」而不是「Webhook」 ！长连接不需要公网 IP，不需要域名，不需要配置 HTTPS，对个人开发者友好得多。配置事件订阅之前，OpenClaw Gateway 必须在运行！ 否则飞书检测不到长连接端，可能导致保存失败。先跑 openclaw gateway status 确认 Gateway 在线，再来配这一步。
Step 7：发布应用
进入 「版本管理与发布」
创建一个版本
提交审核并发布
等待管理员审批（企业自建应用一般秒批）
⚠️ 不发布 = 不生效！ 很多人配完权限和机器人就以为搞定了，结果发消息没反应——因为应用还没发布。
5.3 OpenClaw 侧配置
方式一：交互式向导（推荐） 选择 Feishu ，然后按提示输入 App ID 和 App Secret。
方式二：手动编辑配置文件 编辑 ~/.openclaw/openclaw.json，添加飞书配置：
{ "channels" : { "feishu" : { "enabled" : true , "dmPolicy" : "pairing" , "accounts" : { "main" : { "appId" : "cli_xxxxxxxxx" , "appSecret" : "你的 AppSecret" } } } } }
5.4 首次联调
在飞书里找到你的机器人 ，发一条消息（比如 '你好'）机器人会回复一个 配对码 （Pairing Code）
在终端执行配对确认：
openclaw pairing approve feishu <配对码>
六、踩坑实录 & 避坑指南 以下是实际配置过程中可能遇到的坑，排列按「痛苦指数」从高到低。
🕳️ 坑 1：事件订阅保存失败 现象 ：在飞书开放平台配置长连接事件订阅时，点保存没反应或报错。
原因 ：OpenClaw Gateway 没有在运行，飞书检测不到 WebSocket 连接。
openclaw gateway start
openclaw gateway status
🕳️ 坑 2：机器人不回复消息
✅ 应用有没有 发布 ？（最常见原因！）
✅ 事件订阅里有没有添加 im.message.receive_v1？
✅ 是否选择了 「长连接」 方式？
✅ 权限是否已经全部开通？
✅ Gateway 是否在运行？
🕳️ 坑 3：群聊里机器人不回复 原因 ：默认配置下，群聊需要 @mention 机器人才会响应。而且机器人必须被 添加到群里 。
确认机器人已加入群聊
发消息时 @机器人
如果想不 @也能回复，修改配置：
{ "channels" : { "feishu" : { "groups" : { "oc_你的群 ID" : { "requireMention" : false } } } } }
💡 群 ID 怎么获取？启动 Gateway 后在群里 @机器人，然后 openclaw logs --follow 里找 chat_id。
🕳️ 坑 4：权限不足导致各种奇怪问题 现象 ：消息发送失败、无法读取文件、操作飞书文档报错。
解决 ：回到飞书开放平台 → 权限管理，按需补充权限。常用的：
场景 需要的权限 收发消息 im:message, im:message:send_as_bot读取群消息 im:message.group_at_msg:readonly操作文档 docx:document, docx:document:readonly操作多维表格 bitable:app云盘操作 drive:drive, drive:file
⚠️ 添加新权限后，需要 重新发布应用版本 才能生效！
🕳️ 坑 5：配对码（Pairing）一直等不到 原因 ：Gateway 没有成功连接飞书 WebSocket。
🕳️ 坑 6：Node.js 版本太低 现象 ：安装 OpenClaw 报错，或启动后各种奇怪问题。
原因 ：OpenClaw 要求 Node.js 22+，很多系统默认装的是 18 或 20。
node --version
nvm install 22
nvm use 22
openclaw gateway restart
七、验证一切正常
openclaw --version
openclaw gateway status
openclaw plugins list
openclaw status
八、进阶：常用命令速查 命令 用途 openclaw gateway status查看 Gateway 状态 openclaw gateway restart重启 Gateway openclaw logs --follow实时查看日志 openclaw channels add添加聊天渠道 openclaw pairing list feishu查看飞书配对请求 openclaw pairing approve feishu <CODE>确认配对 openclaw dashboard打开 Web 控制面板 openclaw skills list查看已安装技能 openclaw doctor健康检查 + 快速修复
在飞书里可以发的命令 命令 用途 /status查看机器人状态 /reset重置对话 /model查看/切换 AI 模型
微信扫一扫，关注极客日志 微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
相关免费在线工具 RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
Markdown 转 HTML 将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
HTML 转 Markdown 将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online
