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

OpenClaw 安装与飞书机器人配置实战指南

详细记录了 OpenClaw 在 Linux 环境下的安装与飞书机器人对接全流程。内容涵盖 Node.js 环境搭建、OpenClaw 一键安装、Gateway 初始化配置、飞书开放平台应用创建及权限设置。重点解析了长连接事件订阅的关键配置步骤，并针对事件保存失败、机器人无响应、群聊@失效等常见问题提供了具体的排查思路和解决方案。通过可快速实现私有化 AI 助手在飞书端的部署与联调。

极客零度发布于 2026/4/8更新于 2026/9/1173 浏览

OpenClaw 安装与飞书机器人配置实战指南

本文适合希望部署私有化 AI 助手的开发者，从一台干净的 Linux 环境开始，完成 OpenClaw 安装、AI 模型对接及飞书机器人配置。过程中会穿插实际部署时的常见问题与解决方案。

一、OpenClaw 简介

OpenClaw 是一个开源的 AI Agent 框架，核心目标是让你拥有一个可自托管的私人 AI 助手。它支持接入飞书、Telegram、WhatsApp、Discord 等多种聊天平台。

其核心数据流向如下：

你的消息 → 飞书/Telegram... → OpenClaw Gateway → AI 模型 → 回复

选择 OpenClaw 的理由：

  • 隐私可控：数据完全自托管
  • 多平台支持：覆盖主流 IM 工具
  • 多模型兼容：支持 Claude、GPT、Gemini 等
  • 扩展性强：通过 Skill 系统像安装 App 一样扩展功能
  • 开源免费：无商业限制

二、环境准备

2.1 系统要求

项目要求
操作系统Linux / macOS / Windows (WSL2)
Node.jsv22 或更高版本
网络需能访问飞书开放平台及 AI API

2.2 安装 Node.js

如果尚未安装 Node.js，建议使用 nvm 管理版本：

# 检查当前版本
node --version

# 若版本过低或未安装，使用 nvm 安装 v22
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 的飞书支持依赖独立插件，先安装并重启 Gateway：

openclaw plugins install @openclaw/feishu
openclaw gateway restart

5.2 飞书开放平台：创建应用

Step 1：登录平台

打开 https://open.feishu.cn/app，使用企业账号登录。

国际版用户请访问 https://open.larksuite.com/app。

Step 2：创建企业自建应用
  1. 点击 「创建企业自建应用」
  2. 填写应用名称（例如 "我的 AI 助手"）及描述
  3. 上传应用图标
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 和域名，对个人开发者更友好。配置前请确保 OpenClaw Gateway 已在运行，否则飞书检测不到 WebSocket 端点会导致保存失败。

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

注意：不发布 = 不生效。很多人配完权限就以为搞定，结果发消息没反应，就是因为未发布应用。

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：配对码一直等不到

现象：发消息后机器人没有回复配对码。

原因：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 当前稳定版编写，飞书开放平台界面如有更新请以官方文档为准：https://docs.openclaw.ai

目录

  1. OpenClaw 安装与飞书机器人配置实战指南
  2. 一、OpenClaw 简介
  3. 二、环境准备
  4. 2.1 系统要求
  5. 2.2 安装 Node.js
  6. 检查当前版本
  7. 若版本过低或未安装，使用 nvm 安装 v22
  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. 🕳️ 坑 3：群聊里机器人不回复
  32. 🕳️ 坑 4：权限不足导致报错
  33. 🕳️ 坑 5：配对码一直等不到
  34. 🕳️ 坑 6：Node.js 版本太低
  35. 七、验证一切正常
  36. 1. OpenClaw 安装正常
  37. 2. Gateway 在运行
  38. 3. 飞书插件已安装
  39. 4. 飞书连接正常
  40. 5. 在飞书里发一条消息测试
  41. → 收到 AI 回复 = 全部搞定 ✅
  42. 八、进阶：常用命令速查
  43. 在飞书里可以发的命令

更多推荐文章

查看全部
  • VSCode 扩展工具 Copilot MCP 使用教程
  • Python GUI 可视化设计工具 tkinter-helper 介绍
  • LangChain 0.2 构建 RAG 应用
  • MCP 协议详解：与 Function Call 的区别及使用方式
  • Python Flask 实战：将本地学生成绩系统升级为在线 Web 应用
  • 大模型的起源、现状与未来趋势解析
  • AI 产品经理成长指南：核心能力与实战学习路线
  • Web Worker：前端多线程的隐形引擎
  • Windows WSL Ubuntu 部署 OpenClaw 接入飞书与百炼模型实战
  • Python 与 PyCharm 虚拟环境搭建及实战指南
  • 鸣潮 QQ 机器人部署指南：集成大语言模型与游戏功能
  • Nginx 部署前端 Vue 项目实战指南
  • AI工具链：Gradio演示界面
  • 使用 GitHub Copilot 配合 Figma MCP 还原设计稿生成前端代码
  • 常见 AI 模型与编程术语美式发音速查表
  • 码云（Gitee）代码推送全流程与实操指南
  • Spark SQL 整合 Hive 配置与使用
  • 大语言模型（LLM）入门教程：原理、训练与未来展望
  • Claude Skills 实战：自动化工作流构建与最佳实践
  • Page-Agent: 一行 JS 代码实现大模型对前端 DOM 的精准操控

相关免费在线工具

  • RSA密钥对生成器

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

  • Mermaid 预览与可视化编辑

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

  • 随机西班牙地址生成器

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

  • Keycode 信息

    查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online

  • Escape 与 Native 编解码

    JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online

  • JavaScript / HTML 格式化

    使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online