OpenClaw接入飞书：从零搭建团队AI助手全流程

先说说我为什么折腾这事。前阵子我们团队用飞书办公，群里天天有人问"这个文档在哪""那个报表谁更新的""能不能让机器人帮我把周报汇总一下"。我实在懒得一遍遍回复，就琢磨着在飞书里接一个真正的 AI 助手——不是那种只会说"您好，请问有什么可以帮您"的空壳机器人，而是能查资料、能调技能、能记住上下文的那种。OpenClaw（原 Clawdbot）正好是我想要的东西。

OpenClaw 是一个自托管的开源 AI 代理平台，核心思路是把大模型、技能调用、长期记忆和 IM 渠道打通，让 AI 不只会聊天，还能执行实际任务。它可以接飞书、微信、钉钉、Slack 等多个渠道，底层模型可以换云端 API 也可以换本地模型，数据自己掌控。这篇文章是我从零搭完整个飞书对接流程后的完整记录，包括环境准备、OpenClaw 安装、飞书开放平台配置、两边联调，以及我在实际部署中踩过的各种坑。适合想在团队内部落地一个"真正能用"的 AI 助手、又不想被各家 SaaS 平台锁死的朋友参考。

1. OpenClaw 能做什么：为什么要在飞书里装一个 AI 代理

1.1 从 Clawdbot 到 OpenClaw：项目定位与核心能力

OpenClaw 最初叫 Clawdbot，后来项目改名，统一叫 OpenClaw。和很多"套壳聊天机器人"不一样，它更像是一个 AI 代理运行框架。它的设计核心是把三类东西组合在一起：大模型（负责理解和生成）、技能（负责执行具体动作）、渠道（负责和用户打交道）。这三者解耦之后，你可以用同一个 Agent 内核，今天接飞书，明天接钉钉，后天接网页端，业务逻辑都不用动。

我比较看重的几个能力：

• 技能（Skill）机制：相当于给 AI 装插件。创建一个技能后，AI 可以在对话中判断"这个任务我需要调用哪个技能"，然后主动执行。
• 活动记忆（Active Memory）：AI 能记住跨对话的关键信息，不是每轮都从零开始。这个对团队助手场景太重要了，不然每次都要重新介绍上下文。
• 模型可替换：云端模型、本地模型都能接。国外模型、国内模型也都能接，配置灵活。
• 自托管：所有配置和数据都在自己服务器上，不经过第三方平台，适合对数据敏感的场景。

从实际使用感受来说，OpenClaw 的价值不在"聊天聊得多好"，而在"把 AI 接到真实工作流里"。比如我在飞书里让它"读一下这个项目的文档，整理出下周要做的三件事"，它是真的会去调用文档读取技能，再基于内容生成回复，而不是瞎编。

1.2 飞书作为 AI 助手入口，优势在哪里

接飞书而不是微信、钉钉，我是经过对比的。下表是我当时的粗略评估：

这里最关键的是"长连接"三个字。飞书开放平台支持长连接模式接收事件，意思是你的服务只要主动发起一个持续的连接，飞书就能把消息事件实时推过来，不需要公网地址，不需要内网穿透，连域名都不用备。对于部署在公司内网的个人开发者来说，这省掉了整整一大块运维工作。

此外飞书的权限体系能精确到"机器人能不能读某个云文档""能不能发送某种类型的消息卡片"，这在企业内部是刚需。你要给老板解释"为什么机器人能看全公司聊天记录"之前，飞书会先拦一道，问你到底申请了什么权限——这其实是好事。

2. 动手之前的准备清单：账号、环境与模型 API

2.1 本地或服务器环境要求

OpenClaw 主程序基于 Node.js 运行，所以环境准备的核心就是 Node.js。

• Node.js：建议 18 及以上，最好装 20 LTS。太老跑不起来，太新（比如 23+）偶尔会遇到依赖兼容问题。
• npm：Node.js 自带，只要安装了 Node.js，一般就有 npm。
• 端口：OpenClaw 的 Control UI 和 API 服务默认会监听某个本地端口，通常是 3000 附近。如果被占用了，要在启动参数或配置文件里改。

如果你想部署到云服务器，还额外要注意两点：一是放行对应端口的入站规则，否则 Web 控制台打不开；二是确认服务器能正常访问外网，因为要调用模型 API。

2.2 准备一个能用的模型 API

模型是整个链路里最基础的前提。没模型，OpenClaw 服务能起，但一问就报错。我在测试时主要用了两类模型：

• 云端 API：测试期用的 DeepSeek，原因是国内访问快、成本低、申请 Key 也简单。注册后在控制台创建一个 API Key，记下来，后面配置要用。
• 本地模型：如果想完全离线，可以用 Ollama 拉起本地模型，比如 qwen2.5:7b。用之前先执行：

bash复制ollama pull qwen2.5:7b

然后启动 Ollama 服务，默认监听 http://localhost:11434。

这里强烈建议先单独验证模型 API 是通的，再去做飞书对接。不然两边一起配置好后发现是模型的问题，排查起来很头大。验证云端 API 可以用简单的 curl 请求，或者直接在模型平台的调试界面里发一条消息试试。

2.3 飞书侧权限准备

要在飞书里创建自建应用并开通机器人能力，需要你在企业里至少具备"开发者"角色，或者干脆就是管理员。个人版的飞书也能创建应用，但部分权限（比如读取云文档）需要企业版才能申请下来。建议先确认你们的企业管理员愿意配合，再开始动手。

3. OpenClaw 安装：三种途径与避坑要点

3.1 一键脚本安装

OpenClaw 官方提供了一键安装脚本，覆盖 Windows、macOS、Linux 三个平台，地址以官方文档为准。这里提醒一句：这类脚本是免费的，不要被网上某些"OpenClaw 一键部署工具终身会员特惠"之类的付费服务忽悠，官方脚本本身就是一条命令的事。

Windows 上在 PowerShell 里执行：

powershell复制# 以官方文档提供的命令为准
irm 官方安装脚本地址 | iex

macOS / Linux 上执行：

bash复制# 以官方文档提供的命令为准
curl -fsSL 官方安装脚本地址 | sh

脚本会自动检测 Node.js，缺失的话会提示你安装；然后下载 OpenClaw 主程序，初始化配置目录。不要看到一堆日志输出就慌，等它跑完，最后会打印出下一步指引。

3.2 npm 全局安装与版本控制

如果你对版本有控制要求，推荐用 npm 安装：

bash复制npm install -g openclaw

装完验证一下：

bash复制openclaw --version

如果提示命令找不到，别急着重装。大概率是 npm 全局 bin 目录没有加入 PATH。Windows 上常见的是 %APPDATA%\npm，macOS/Linux 上一般是 /usr/local/bin 或 ~/.npm-global。把它加进 PATH 再重开终端就好了。

npm 安装方式最大的优势是支持指定版本：

bash复制npm install -g openclaw@具体版本号

对团队来说，固定版本能避免"昨天好好的今天突然抽风"这种玄学问题。

3.3 程序目录与配置目录要分清

OpenClaw 装完，你要知道两个关键路径：

• 程序目录：npm 全局目录里的 openclaw 文件夹。升级用的，日常不用碰。
• 配置目录：~/.openclaw（Windows 下是 C:\Users\<你的用户名>\.openclaw）。里面放着配置文件、日志、技能、活动记忆等。

我踩过一次坑：自己改了程序目录里某个示例配置，发现重启不生效，折腾老半天，最后发现程序读的是 ~/.openclaw 里的配置。所以凡是涉及"改配置"，第一反应应该是去用户目录下的 .openclaw 文件夹里找，而不是去翻安装目录。

3.4 安装期高频报错：Node runtime not found

Windows 用户在安装或启动 OpenClaw 时，有时会遇到类似 "OpenClaw node runtime not found" 的报错。这个问题本质上是 OpenClaw 在启动时找不合适的 Node.js 运行时，但找不到。

我当时的排查链路：

1. 先执行 node -v，确认 Node.js 装了没。
2. 执行 where node（Windows）或 which node（macOS/Linux），确认 node 在不在 PATH 里。
3. 如果用了 nvm-windows 这类版本管理工具，确认当前激活的版本不是"未安装"状态。
4. 删掉 ~/.openclaw 下可能残留的运行时缓存目录，重新初始化。

实际上我试下来最有效的办法是：把 Node.js 卸载干净，装一个官方 LTS 版本，再重新装 OpenClaw，一次通过。系统的坑就是这样，不如重开。

4. 飞书开放平台配置：创建应用只是开始

4.1 创建企业自建应用

访问飞书开放平台（open.feishu.cn），进入开发者后台，点"创建企业自建应用"。应用名称建议直接叫"AI 助手"或者你团队能看懂的名字，描述里写清楚用途——后面审核的时候管理员会看。

创建完成之后，你会获得两个关键凭证：

• App ID：应用的唯一标识。
• App Secret：应用密钥，相当于密码。

这两个值先复制保存到本地，后面配置 OpenClaw 时要用。

4.2 开启机器人能力

在应用的"功能"页面里，找到"机器人"能力，点击启用。这一步不做，后面所有配置都是白搭，因为飞书根本不会给这个应用生成机器人账号。

启用后，在飞书通讯录里能搜到这个机器人，可以先试试主动给它发消息——这时候它当然不会回复，因为后端还没有服务在监听，但至少能说明机器人账号存在。

4.3 权限申请：最容易被卡住的一环

要让 OpenClaw 完整工作，至少需要开通以下几类权限：

在"权限管理"页面逐个搜索并开通。注意：飞书很多权限不是默认开放的，需要主动申请，自建应用的话管理员可以直接审批通过。

4.4 事件订阅：长连接模式是 OpenClaw 的关键

在"事件订阅"页面，飞书提供两种接收方式：

• Webhook 回调：需要提供一个公网可访问的 HTTPS 地址，企业内网部署基本没法用。
• 长连接：飞书主动推送消息到一个由你的服务保持的持久连接，不需要公网 IP。

OpenClaw 走的就是长连接方式，这也是它能轻松对接飞书的核心原因。你需要订阅一个关键事件：im.message.receive_v1（接收消息事件）。不订阅这个事件，机器人就收不到任何用户消息。

4.5 发布或添加测试白名单

飞书自建应用默认是"测试中"状态。分两种情况：

• 只想自己调试：在"版本管理与发布"里添加测试人员白名单，把你自己的账号加进去。这样改配置即时生效，不用反复走发布流程。
• 想给全团队用：需要创建一个版本并正式发布，发布后团队成员都能在通讯录里找到机器人。

我的建议是，先白名单调试，全部跑通了再正式发布。别一上来就走发布流程，否则每次改权限都要重新走一遍审核和发布，非常烦人。

5. 对接 OpenClaw：配置文件逐行拆解

5.1 初始化配置

安装完成后，先运行初始化命令生成配置文件。不同版本命令名略有差异，不确定就看帮助：

bash复制openclaw --help

一般会有一个类似 config init 或 init 的子命令，执行后会在 ~/.openclaw 目录下生成配置文件，通常是 openclaw.json。打开看会发现里面自带大量注释和默认值，不同版本字段名会有差异，一切以你自己生成的配置模板为准。

5.2 飞书渠道配置

在配置文件里找到 channels 部分，配置飞书渠道。飞书在开放平台的英文名是 Lark，所以 OpenClaw 的渠道标识可能是 lark，老一些的版本也可能用 feishu。可以用命令确认当前版本支持的渠道：

bash复制openclaw channels list

配置大致长这样（字段名以你的版本模板为准）：

json复制{
  "channels": {
    "lark": {
      "appId": "cli_xxxxxxx",
      "appSecret": "xxxxxxxxxxxxxxxxxxxx",
      "enabled": true
    }
  }
}

把飞书后台拿到的 App ID 和 App Secret 填进去，enabled 设为 true。这一步是最简单的，但也是我最容易漏的——每次配置完都顺手检查一下 enabled 字段，别问我是怎么知道的。

5.3 模型配置：云模型和本地模型

在 llm 相关字段里配置模型。我测试期用 DeepSeek 的配置：

json复制{
  "llm": {
    "provider": "deepseek",
    "apiKey": "sk-xxxxxx",
    "model": "deepseek-chat",
    "baseUrl": "https://api.deepseek.com"
  }
}

用本地 Ollama 的配置：

json复制{
  "llm": {
    "provider": "ollama",
    "baseUrl": "http://localhost:11434",
    "model": "qwen2.5:7b"
  }
}

这里有两个容易踩的坑：

第一，不要直接把 API Key 硬编码在配置文件里然后传到 Git 仓库。正确的是用环境变量引用，例如：

json复制{
  "llm": {
    "apiKey": "${DEEPSEEK_API_KEY}"
  }
}

然后在系统环境变量里设置 DEEPSEEK_API_KEY。这样配置和密钥分开，其他人拉代码也不会泄露密钥。

第二，如果 Ollama 不在本机，而是在另一台服务器上，baseUrl 必须写成那台服务器的 IP 或域名，同时确认 11434 端口对外开放。别配了半天连不上，最后发现是防火墙拦住了。

5.4 用 validate 或启动日志验证配置

有部分版本提供了配置校验命令，不确定的话可以直接启动看日志：

bash复制openclaw start

启动后，日志里如果出现类似 "Lark channel connected" 或 "feishu connected" 的字样，说明飞书渠道已经连上。这一步如果通了，就等于整个链路里最难的一环已经打通了。

6. 启动与测试：从命令行到飞书消息

6.1 启动服务与控制台

启动命令很简单：

bash复制openclaw start

启动成功后，控制台会打印出 Control UI 的地址，一般是 http://localhost:3000。在浏览器里打开，能看到一个 Web 控制台，里面显示服务状态、日志、技能列表、活动记忆等。

实际上 Control UI 是排查问题的最好入口，所有报错信息都会出现在日志面板里。我就经常盯着它看，看到底是模型报错还是飞书渠道报错。

6.2 三级测试法：从私聊到群聊

我强烈建议按下面这个顺序测试，而不是直接拉到群里试：

1. 私聊机器人：用你自己的飞书账号，给机器人发"你好"。正常情况下几秒内会收到回复。这验证的是最基本的消息收发链路。
2. 群里 @ 机器人：建一个测试群，把机器人和你自己拉进去，发一条 @ 机器人的消息。这验证的是群聊消息事件是否正常推送。
3. 让机器人调用技能：给它一个带任务性质的指令，比如"请读取这个文档并总结"。这验证的是 Agent 能力能否正常触发技能。

这一步是定位问题最快的方法。私聊都收不到，就说明通道层有问题，先别看技能；私聊通了群聊不通，那就是事件订阅里的群聊消息事件没配好；对话正常但技能不执行，才是查技能配置。

6.3 常用调试命令

记录几个我常用的命令，保存到本地备忘：

bash复制openclaw status          # 查看服务状态
openclaw logs --tail     # 实时跟踪日志
openclaw skills list     # 查看已加载的技能列表
openclaw memory          # 查看活动记忆

除此之外，如果安装了 Control UI，直接在网页上看 logs 面板最直观，错误信息会带时间和堆栈，排查时不至于没头绪。

7. 高频踩坑排查：控制台、运行时与权限问题

7.1 Control UI did not start，怎么处理

很多人在安装或启动时遇到 "Control UI did not start" 的提示。别慌，先判断是哪种情况：

• 端口被占用：Windows 上执行 netstat -ano | findstr :3000，Linux 上执行 ss -lntp | grep 3000。如果有其他进程占着，换个端口启动即可。
• 无头服务器：如果是在纯命令行服务器上跑，Control UI 本来就不会自动打开浏览器，但服务未必是挂了的，手动访问地址看结果。
• 浏览器环境问题：Windows 上有时是因为默认浏览器异常，导致自动打开失败。这种情况不影响服务本身，手动开浏览器访问即可。

7.2 消息发不出去或收不到，按这个顺序查

这个问题是我在飞书对接里遇到最多的情况，大概率是飞书后台配置的问题。按优先级排查：

1. 机器人能力启用了吗？
2. 事件订阅里，im.message.receive_v1 事件添加了吗？
3. 接收方式选的是"长连接"，不是 Webhook 吧？
4. 权限管理里有没有 im:message 和 im:message:send_as_bot？
5. 应用处于"测试中"还是"已发布"？你的账号在不在测试白名单里？
6. App ID / App Secret 填写时有没有多复制出空格或换行？

我遇到过一个最隐蔽的情况：飞书后台"机器人"能力明明启动了，但权限管理里 im:message 那一项并没有单独授权。飞书很多权限默认不开放，不主动申请就不会生效——这个一定要去权限管理页面逐项确认，别只看一眼就跳过。

7.3 failed to remove ~/.openclaw：文件占用问题

卸载或重装 OpenClaw 时，Windows 上删除 ~/.openclaw 目录可能报这样的错：

code复制failed to remove ~\.openclaw: error: ebusy: resource busy or locked, unlink ...

这个报错的原因是：还有 OpenClaw 相关的进程占着目录里的文件，可能是数据库句柄，也可能是有个 node 进程没退干净。

解决这件事的步骤：

1. 先停掉所有 OpenClaw 相关进程。Windows 上打开任务管理器，找到所有 node.exe 或 openclaw 进程，全部结束。
2. 用 PowerShell 强制删除：

powershell复制Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw"

3. 如果还是删不掉，说明进程没释放干净，直接重启电脑，重启完再删。这个方法虽然朴素，但每次都管用。

这个报错平时不影响运行，只在重装或彻底卸载时会遇到，知道了就不算坑。

7.4 模型相关报错：unknown model 与超时

如果你已经能收到消息，但 AI 回复报错，比如类似热词里提到的 Agent failed before reply: unknown model: deepsee，那不是 OpenClaw 的问题，是模型名填错了。

不同模型提供方的模型 ID 命名规则不一样，DeepSeek 官方提供的是 deepseek-chat 和 deepseek-reasoner，不叫 deepseek。Ollama 同样如此，每个模型有完整的 tag，比如 qwen2.5:7b、llama3.1:8b，写上 qwen2.5 不带 tag 也会报错。解决方法是去模型提供方控制台查一次模型 ID，照着填进去。

还有一类是"回复特别慢，最后超时"的问题。常见于本地模型，尤其是 7B 以上参数量的模型如果没有 GPU 加速，纯 CPU 推理会非常慢。我的处理方法是先换更小的量化版本，比如 3B 或 4B 的量化模型，先把链路跑通，再换更大的模型追求效果。

最后再分享一个小技巧：我接完飞书之后，其实先用的是本地 Ollama 模型把全流程跑通的，当时用的 qwen2.5:7b，虽然回复速度一般，但省了几十块 API 测试费，而且调试起来更可控——日志里能清楚看到模型内部在想什么。等链路稳定了，再切换成云端的高性能模型。这个顺序能帮你把"通道问题"和"模型问题"彻底分开，排查起来思路会非常清晰。