跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客我的书AI学习GitHub 精选镜像AI 生图工具UI配色美学关于
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
Shell / BashNode.jsAI

OpenClaw 安装与飞书机器人配置全流程指南

OpenClaw 是开源 AI Agent 框架，支持接入飞书等聊天平台。详述了在 Linux 环境下安装 OpenClaw 及配置 Node.js 环境的步骤，涵盖 Gateway 启动、飞书应用创建、权限配置及事件订阅设置。内容包括插件安装、渠道对接、配对验证流程，并整理了事件订阅保存失败、机器人无响应等常见问题的排查方案，辅助用户快速部署私有化 AI 助手。

BackendPro发布于 2026/3/26更新于 2026/10/785 浏览

OpenClaw 安装与飞书机器人配置全流程指南

一、OpenClaw 是什么？

OpenClaw 是一个开源的 AI Agent 框架，简单理解就是：它让你拥有一个私人 AI 助手，可以接入飞书、Telegram、WhatsApp、Discord 等各种聊天平台。

它的核心架构很简单：

your message -> Feishu/Telegram... -> OpenClaw Gateway -> AI Model -> Reply

为什么选 OpenClaw？

  • 🔒 数据自托管，隐私可控
  • 🔌 支持多种聊天平台（飞书、Telegram、WhatsApp、Discord……）
  • 🧠 支持多种 AI 模型（Claude、GPT、Gemini……）
  • 🛠 可扩展的 Skill 系统，像安装 App 一样给 AI 加技能
  • 💻 完全开源免费

二、环境准备

2.1 系统要求
项目要求
操作系统Linux / macOS / Windows (WSL2)
Node.jsv22 或更高
网络能访问飞书开放平台 + AI API
2.2 安装 Node.js（如果还没装）
# 检查是否已安装 node --version
# 如果没有或版本太低，用 nvm 安装
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 一键安装

macOS / Linux：

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

Windows (PowerShell)：

iwr -useb https://openclaw.ai/install.ps1 | iex

安装完成后验证：

openclaw --version

看到版本号（如 2026.3.2）就说明安装成功了。

3.2 手动安装（备选）

如果一键脚本有问题，也可以用 npm 安装：

npm install -g openclaw

注意：如果遇到 EACCES: permission denied 错误，不要用 sudo npm install -g！正确做法是配置 npm 权限。

四、初始配置（onboard 向导）

安装完后，运行引导向导：

openclaw onboard --install-daemon

向导会引导你配置：

  1. AI 模型密钥 — 输入你的 Anthropic / OpenAI / Google API Key
  2. Gateway 设置 — 默认端口 18789，一般不用改
  3. 聊天渠道 — 这里先跳过，我们后面单独配飞书

提示：--install-daemon 参数会把 Gateway 安装为系统服务，开机自动启动。

配置完后检查 Gateway 状态：

openclaw gateway status

如果显示 running，基础安装就完成了 ✅

此时你已经可以通过 Web UI 聊天了：

openclaw dashboard

浏览器会自动打开 http://127.0.0.1:18789，这就是 OpenClaw 的控制面板。

五、飞书机器人配置全流程

这是本文的重头戏。飞书机器人配置分 三大步：飞书侧建应用 → OpenClaw 侧配置 → 联调测试。

5.1 安装飞书插件

OpenClaw 的飞书支持是通过插件提供的，先安装：

openclaw plugins install @openclaw/feishu

安装完后重启 Gateway：

openclaw gateway restart
5.2 飞书开放平台：创建应用
Step 1：登录飞书开放平台

打开 https://open.feishu.cn/app，用你的飞书账号登录。

⚠️ 如果你用的是 Lark（国际版），地址是 https://open.larksuite.com/app。

Step 2：创建企业自建应用
  1. 点击 「创建企业自建应用」
  2. 填写应用名称（比如 '我的 AI 助手'）
  3. 填写应用描述
  4. 选一个图标
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：开启机器人能力

进入 「应用能力」→「机器人」：

  1. 开启机器人能力
  2. 设置机器人名称
Step 6：配置事件订阅（⚠️ 这步容易翻车！）

进入 「事件与回调」：

  1. 选择「使用长连接接收事件」（WebSocket 方式）
  2. 添加事件：搜索并勾选 im.message.receive_v1（接收消息 v1）

🚨 大坑警告：一定要选「长连接」而不是「Webhook」！长连接不需要公网 IP，不需要域名，不需要配置 HTTPS，对个人开发者友好得多。配置事件订阅之前，OpenClaw Gateway 必须在运行！ 否则飞书检测不到长连接端，可能导致保存失败。先跑 openclaw gateway status 确认 Gateway 在线，再来配这一步。

Step 7：发布应用
  1. 进入 「版本管理与发布」
  2. 创建一个版本
  3. 提交审核并发布
  4. 等待管理员审批（企业自建应用一般秒批）

⚠️ 不发布 = 不生效！ 很多人配完权限和机器人就以为搞定了，结果发消息没反应——因为应用还没发布。

5.3 OpenClaw 侧配置
方式一：交互式向导（推荐）
openclaw channels add

选择 Feishu，然后按提示输入 App ID 和 App Secret。

方式二：手动编辑配置文件

编辑 ~/.openclaw/openclaw.json，添加飞书配置：

{"channels":{"feishu":{"enabled":true,"dmPolicy":"pairing","accounts":{"main":{"appId":"cli_xxxxxxxxx","appSecret":"你的 AppSecret"}}}}}

配置完后重启 Gateway：

openclaw gateway restart
5.4 首次联调
  1. 在飞书里找到你的机器人，发一条消息（比如 '你好'）
  2. 机器人会回复一个 配对码（Pairing Code）
  3. 在终端执行配对确认：
openclaw pairing approve feishu <配对码>
  1. 配对成功后，再次发消息，AI 就会正常回复了 🎉

六、踩坑实录 & 避坑指南

以下是实际配置过程中踩过的坑，排列按「痛苦指数」从高到低 😂

🕳️ 坑 1：事件订阅保存失败

现象：在飞书开放平台配置长连接事件订阅时，点保存没反应或报错。

原因：OpenClaw Gateway 没有在运行，飞书检测不到 WebSocket 连接。

解决：

# 先确保 Gateway 在跑
openclaw gateway start
openclaw gateway status # 确认是 running
# 然后再去飞书平台配置事件订阅
🕳️ 坑 2：机器人不回复消息

现象：飞书里发消息，机器人完全没反应。

排查清单（按顺序检查）：

  1. ✅ 应用有没有 发布？（最常见原因！）
  2. ✅ 事件订阅里有没有添加 im.message.receive_v1？
  3. ✅ 是否选择了 「长连接」 方式？
  4. ✅ 权限是否已经全部开通？
  5. ✅ Gateway 是否在运行？
# 实时查看日志，发消息后观察输出
openclaw logs --follow
🕳️ 坑 3：群聊里机器人不回复

现象：私聊正常，群聊里 @机器人 没反应。

原因：默认配置下，群聊需要 @mention 机器人才会响应。而且机器人必须被 添加到群里。

解决：

  1. 确认机器人已加入群聊
  2. 发消息时 @机器人
  3. 如果想不 @也能回复，修改配置：
{"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。

解决：

# 查看详细日志
openclaw logs --follow
# 看看有没有 feishu 连接成功的日志
# 如果有 error，根据错误信息排查（通常是 App ID/Secret 填错了）
🕳️ 坑 6：Node.js 版本太低

现象：安装 OpenClaw 报错，或启动后各种奇怪问题。

原因：OpenClaw 要求 Node.js 22+，很多系统默认装的是 18 或 20。

解决：

node --version # 检查版本
nvm install 22 # 升级到 22
nvm use 22
openclaw gateway restart # 重启

七、验证一切正常

跑完整个流程后，用这个清单逐项确认：

# 1. OpenClaw 安装正常
openclaw --version
# 2. Gateway 在运行
openclaw gateway status
# 3. 飞书插件已安装
openclaw plugins list # 应该能看到 @openclaw/feishu
# 4. 飞书连接正常
openclaw status # 应该显示 feishu: connected
# 5. 在飞书里发一条消息测试
# → 收到 AI 回复 = 全部搞定 ✅

八、进阶：常用命令速查

命令用途
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 模型

写在最后

OpenClaw + 飞书机器人的配置确实有不少坑，但只要按照本文的流程走，应该能少走很多弯路。核心要记住的就是：

  1. 先装插件，后配飞书
  2. 先跑 Gateway，后配事件订阅
  3. 配完权限，别忘了发布应用
  4. 有问题先看日志：openclaw logs --follow

本文基于 OpenClaw 2026.3.2 版本，飞书开放平台截至 2026 年 3 月。如有版本差异请以官方文档为准：https://docs.openclaw.ai

目录

  1. OpenClaw 安装与飞书机器人配置全流程指南
  2. 一、OpenClaw 是什么？
  3. 二、环境准备
  4. 2.1 系统要求
  5. 2.2 安装 Node.js（如果还没装）
  6. 检查是否已安装 node --version
  7. 如果没有或版本太低，用 nvm 安装
  8. 三、安装 OpenClaw
  9. 3.1 一键安装
  10. 3.2 手动安装（备选）
  11. 四、初始配置（onboard 向导）
  12. 五、飞书机器人配置全流程
  13. 5.1 安装飞书插件
  14. 5.2 飞书开放平台：创建应用
  15. Step 1：登录飞书开放平台
  16. Step 2：创建企业自建应用
  17. Step 3：获取凭证（重要！）
  18. Step 4：配置权限
  19. Step 5：开启机器人能力
  20. Step 6：配置事件订阅（⚠️ 这步容易翻车！）
  21. Step 7：发布应用
  22. 5.3 OpenClaw 侧配置
  23. 方式一：交互式向导（推荐）
  24. 方式二：手动编辑配置文件
  25. 5.4 首次联调
  26. 六、踩坑实录 & 避坑指南
  27. 🕳️ 坑 1：事件订阅保存失败
  28. 先确保 Gateway 在跑
  29. 然后再去飞书平台配置事件订阅
  30. 🕳️ 坑 2：机器人不回复消息
  31. 实时查看日志，发消息后观察输出
  32. 🕳️ 坑 3：群聊里机器人不回复
  33. 🕳️ 坑 4：权限不足导致各种奇怪问题
  34. 🕳️ 坑 5：配对码（Pairing）一直等不到
  35. 查看详细日志
  36. 看看有没有 feishu 连接成功的日志
  37. 如果有 error，根据错误信息排查（通常是 App ID/Secret 填错了）
  38. 🕳️ 坑 6：Node.js 版本太低
  39. 七、验证一切正常
  40. 1. OpenClaw 安装正常
  41. 2. Gateway 在运行
  42. 3. 飞书插件已安装
  43. 4. 飞书连接正常
  44. 5. 在飞书里发一条消息测试
  45. → 收到 AI 回复 = 全部搞定 ✅
  46. 八、进阶：常用命令速查
  47. 在飞书里可以发的命令
  48. 写在最后

更多推荐文章

查看全部
  • 一种光伏产品缺陷检测 AI 深度学习算法
  • Whisper-CTranslate2 高效语音识别与 AI 翻译工具
  • 深入解析 LlamaIndex Workflows：构建复杂 RAG 与智能体工作流
  • C++ 网络编程中的 Protobuf 消息分发 (Dispatcher) 设计模式
  • 高云 FPGA 远程升级原理
  • C++ 标准库 string 类基础详解
  • 麦橘超然（MajicFLUX）AI 绘画镜像部署与实测指南
  • 2025 团体程序设计天梯赛 L1-L2 题解（C++）
  • Python CSV 模块完整教程
  • MCP 协议实战：Browser Tools 插件集成指南
  • 低代码平台的两种价值观：短期成果与长期成本
  • Mac mini 无显示器部署 OpenClaw：SSH + 远程桌面
  • 鸿蒙 ArkTS 自动化测试实践：构建全链路缺陷防御体系
  • VSCode Copilot 登录失败的常见原因与排查方案
  • PyCharm 配置 Anaconda 环境时找不到 Conda 环境的解决方法
  • OpenClaw 对接腾讯 QQ 实战操作详解
  • Java 实现 PDF 文字与图片水印添加及 MinIO 下载实战
  • 快速排序非递归实现详解：手动模拟栈结构
  • Win10 WSL2 环境下 VS Code Copilot 连接失败排查与修复
  • 使用 Rclone 将远程 WebDAV 存储映射为本地硬盘

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online

  • Markdown转HTML

    将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online