🦞 OpenClaw + iMessage + 飞书 完整配置保姆级教程
从零开始,手把手教你打造专属 AI 助理,支持飞书、iMessage 双通道互动

📝 前言
OpenClaw(原 Clawdbot)是一款开源 AI Agent 框架,让你能够在各种聊天平台(飞书、钉钉、iMessage、Discord 等)中接入 AI,并赋予它系统级的操作权限——包括读写文件、执行命令、管理日程等。
这篇教程将从零开始,手把手带你完成 OpenClaw 的安装与配置,重点讲解:
- 飞书应用的完整创建流程
- OpenClaw 配置文件的详细说明
- iMessage 和飞书双通道接入
- 常见问题的排查方法
🔧 环境准备
系统要求
在开始之前,请确保你的环境满足以下条件:
- 操作系统: macOS 10.15 或更高版本
- Node.js: 18.x 或更高版本
- 包管理器: npm、Homebrew 二选一
安装前检查
打开终端,运行以下命令检查环境:
1 | # 检查 Node.js 版本 |
Result:
1 | >> node --version |
💡 小贴士:如果你还没安装 Node.js,可以去 nodejs.org 下载 LTS 版本。
🚀 安装 OpenClaw
方式一:使用 npm 安装(推荐)
1 | # 安装 OpenClaw CLI |
方式二:使用 Homebrew 安装
1 | # 添加 Homebrew tap |
启动 OpenClaw Gateway
安装完成后,需要启动 OpenClaw Gateway 服务——这是 OpenClaw 的核心组件,负责接收消息、调度任务、管理权限。
1 | # 启动服务 |

⚠️ 重要提示:
- Gateway 必须运行才能使用 iMessage 和飞书等功能
- 首次启动会要求登录或配置
- 修改配置后必须执行
openclaw gateway restart才能生效
OpenClaw 配置详解
这部分是官方文档中较少详细说明,但又是配置过程中的关键环节
配置方式对比
OpenClaw 提供了多种配置方式,每种方式适用于不同的使用场景:
| 配置方式 | 适用场景 | 难度 | 推荐度 |
|---|---|---|---|
| 交互式配置(onboard) | 新手入门,一键配置 | ⭐ 简单 | ✅ 强烈推荐 |
| 命令行配置(config set) | 精确控制单个配置项 | ⭐⭐ 中等 | |
| 频道向导(channels add) | 添加新的聊天平台 | ⭐⭐ 中等 | |
| 手动编辑配置文件 | 高级用户,批量配置 | ⭐⭐⭐ 复杂 |
🚀 方式一:交互式配置(onboard)- 新手推荐
openclaw onboard 是 OpenClaw 提供的交互式配置向导,它会引导你完成所有必要的配置步骤,非常适合第一次使用 OpenClaw 的用户。
1 | # 启动交互式配置向导 |
配置向导会依次引导你完成以下步骤:
第一步:同意免责声明
首次运行时,会显示风险提示,选择 Yes 继续。

第二步:选择配置模式
- QuickStart(快速入门):推荐新手使用,自动完成大部分配置
- Custom(自定义):适合有经验的用户,可以手动调整每个配置项

第三步:模型配置
选择你要使用的 AI 模型。OpenClaw 这里可以选择使用国产模型(如智谱 GLM、DeepSeek 等)。

小编这之前购买了智谱的 coding plan,选择使用智谱 GLM 4.7.

💡 小贴士:如果你计划使用其他国产模型(如 Kimi 等),也是类似的操作进行配置。
第四步:聊天平台(Channel)配置
OpenClaw 支持多种聊天平台。在引导流程中,国外应用显示较多,国内用户常用的飞书可以在后续通过命令行添加。


⚠️ 注意:初次配置时可能界面中没有
Feishu选项,可以先跳过,后续按照本文「配置飞书」章节使用openclaw channels add命令添加。
第五步:技能包(Skill)配置
新手可以暂时跳过额外技能包,选择 Skip for now。

第六步:Hooks 配置
然后是一系列配置,没有API或暂时用不上,但Hook三个都有用,建议选上:
boot-md:启动时注入Markdown文件,在会话开始时注入类似README的内容。command-logger:操作日志记录,记录本次会话中执行的命令与操作上下文。session-memory:开始新会话时保存当前会话上下文摘要,便于后续无缝衔接。
建议启用 Memory(记忆功能),支持多轮对话上下文关联,避免每次聊天都需要重复说明需求。

第七步:等待配置完成
配置向导会自动完成所有设置,等待进度条完成即可。如果你的电脑正在运行网关或以前安装过,建议选重启。

第八步:选择界面
- TUI:终端UI,基本上就是命令行对话
- Web UI,有一个对话的网页

默认推荐TUI,但两者不是互斥关系,其实都会安装。

如果想进入TUI,在终端输入:openclaw tui。
OpenClaw 最有意思的地方是支持大量 IM 工具接入。用熟悉的聊天工具跟 Openclaw 说话,下指令,很像当领导的感觉。比如我配置了 iMessage 和 Feishu。
下面以飞书为例,介绍工具的配置。
📱 配置 iMessage
准备工作
OpenClaw 的 iMessage 集成需要使用 imsg CLI 工具来访问 macOS 的 Messages 数据库。这是实现 iMessage 功能的核心依赖。
前置要求
- macOS 系统:iMessage 集成仅在 macOS 上可用
- Messages 应用已登录:确保系统 Messages 应用已使用 Apple ID 登录
- Homebrew:用于安装
imsgCLI 工具
💡 小贴士:建议为 OpenClaw 使用独立的 Apple ID,避免与个人 iMessage 混淆。创建一个专用 Apple ID(如
openclaw-bot@icloud.com),在 Messages 应用中登录此账号。
第一步:安装 imsg CLI 工具
imsg 是一个命令行工具,允许 OpenClaw 读写 macOS 的 iMessage 数据库。
1 | # 使用 Homebrew 安装 imsg |
验证安装是否成功:
1 | # 查看 imsg 版本 |

⚠️ 注意:首次运行
imsg命令时,macOS 会要求授予「完全磁盘访问权限」。请前往 系统设置 → 隐私与安全性 → 完全磁盘访问权限,允许终端或imsg的访问权限。
第二步:配置 iMessage 频道
OpenClaw 配置 iMessage 比较简单,在 openclaw onboard 命令中,勾选 iMessage imsg 然后根据提示,直接推进就好了。

第三步:授权系统权限
首次启动 OpenClaw Gateway 时,macOS 会弹出权限请求对话框。你需要授予以下权限:
完全磁盘访问权限
1 | "OpenClaw" 或 "Terminal" 想要访问您的磁盘? |
前往 系统设置 → 隐私与安全性 → 完全磁盘访问权限,确保已勾选:
- Terminal(如果直接在终端运行)
- OpenClaw(如果有独立的 OpenClaw 应用)

第四步:重启 Gateway(重要!)
配置完成后,必须重启 Gateway 才能让 iMessage 集成生效:
1 | # 重启 OpenClaw Gateway |
🔥 重要提示:这一步不能省略!修改任何频道配置后,都需要重启 Gateway 才能生效。
第五步:验证 iMessage 连接
1 | # 查看所有配置的频道 |
第六步:测试 iMessage 发送
有两种方式测试 iMessage 功能:
方式一:通过命令行发送
1 | # 发送测试消息(需要指定接收者) |
方式二:直接在 iMessage 中对话
- 打开 Messages 应用
- 找到你的机器人 Apple ID 对应的对话
- 发送测试消息,如 “你好”
- OpenClaw 应该会自动回复

💡 小贴士:如果使用独立的 Apple ID 作为机器人,可以给自己(主账号)发送消息来测试。
高级配置选项
对于有特殊需求的用户,OpenClaw 支持以下高级配置:
独立 macOS 用户配置(隔离环境)
为了更好的隔离性,可以创建一个专门的 macOS 用户来运行 OpenClaw:
1 | # 创建新用户(在系统设置中) |
然后在配置文件中指定 SSH 包装脚本:
1 | channels: |
访问控制配置
配置谁可以通过 iMessage 与 OpenClaw 对话:
1 | # 设置配对策略(默认:pairing) |
配对策略说明:
| 策略 | 说明 |
|---|---|
pairing(默认) |
陌生人发送消息时需要验证码,需手动批准 |
allowlist |
仅允许白名单中的联系人 |
open |
任何人都可以直接对话(不推荐) |
🐦 配置飞书
飞书是国内最友好的 OpenClaw 接入平台,支持群聊、私聊、文档、多维表格等丰富功能
准备工作
在配置飞书之前,您需要:
- 飞书企业账号
- 创建自建应用:访问 飞书开放平台
- 获取应用凭证:App ID 和 App Secret
创建飞书应用
1. 登录飞书开放平台
访问飞书开放平台:https://open.feishu.cn/app/)
2. 创建新应用
- 点击 "创建企业自建应用"
- 填写应用信息:
- 应用名称:如
OpenClaw Assistant - 应用描述:自定义描述
- 应用图标:上传图标(可选)
- 应用名称:如

3. 添加机器人能力
在 “添加应用能力” → 找到 机器人,点击 "添加"
⚠️ 注意:有些权限开通需要先有机器人能力

4. 配置应用权限
在应用的 “权限管理” 中添加以下权限:
应用身份权限(tenant):
| 权限名称 | 权限标识 | 说明 |
|---|---|---|
| 读写文档 | docx:document |
创建和编辑飞书文档 |
| 编辑多维表格 | bitable:app |
创建/更新/删除表格记录 |
| 读取多维表格 | bitable:app:readonly |
读取多维表格数据 |
| 读取联系人基础信息 | contact:contact.base:readonly |
读取联系人基本信息 |
| 读取聊天信息 | im:chat:read |
读取聊天信息 |
| 只读聊天信息 | im:chat:readonly |
只读聊天信息 |
| 更新聊天信息 | im:chat:update |
更新聊天信息 |
| 读取群聊@消息 | im:message.group_at_msg:readonly |
读取群聊@消息 |
| 读取单聊消息 | im:message.p2p_msg:readonly |
接收用户私聊消息 |
| 读取消息置顶 | im:message.pins:read |
读取消息置顶信息 |
| 写入消息置顶 | im:message.pins:write_only |
写入消息置顶信息 |
| 读取消息反应 | im:message.reactions:read |
读取消息反应 |
| 写入消息反应 | im:message.reactions:write_only |
写入消息反应 |
| 只读消息 | im:message:readonly |
只读消息 |
| 撤回消息 | im:message:recall |
撤回消息 |
| 发送机器人消息 | im:message:send_as_bot |
允许机器人发送消息 |
| 发送多人消息 | im:message:send_multi_users |
发送多人消息 |
| 发送系统消息 | im:message:send_sys_msg |
发送系统消息 |
| 更新消息 | im:message:update |
更新消息 |
| 资源访问 | im:resource |
资源访问权限 |
| 读取知识库 | wiki:wiki:readonly |
读取知识库内容 |
用户权限(user):
| 权限名称 | 权限标识 | 说明 |
|---|---|---|
| 读取员工ID | contact:user.employee_id:readonly |
读取用户员工ID信息 |
🎯 批量导入权限(推荐):
在权限管理页面,点击 “批量导入”,粘贴以下 JSON 配置:
1 | { |
💡 小贴士:这些权限是小编自己需要用的功能,你可以根据自己需要选择开通哪些权限。
配置完后效果大致如下:

⚠️ 重要说明:
- 新添加的权限可能需要一段时间才能在权限列表中显示
- 如果添加的权限没有显示,请等待 1-2 分钟后刷新页面
- 某些权限(如
bitable:app)包含多个子权限,会自动包含读写、删除等能力 - 权限配置完成后,必须执行
openclaw gateway restart才能生效
5. 获取应用凭证
在应用的 “凭证与基础信息” 中获取:
- App ID:类似
cli_xxxxxxxxx - App Secret:类似
xxxxxxxxxxxxxxxxxxxxxxxx
⚠️upload failed, check dev console
⚠️ 安全提示: App Secret 请妥善保管,不要泄露!
配置 OpenClaw 连接飞书
第一步:安装飞书插件
OpenClaw 使用插件系统来支持各种平台。有人开发了飞书的OpenClaw插件
首先,我们需要安装飞书插件:
1 | # 安装飞书插件 |
安装后会显示如下界面:

第二步:配置飞书应用凭证
获取到飞书应用的 App ID 和 App Secret 后,使用命令行进行配置。这种方式比手动编辑配置文件更直观、更不容易出错。
1 | # 设置 App ID(请替换为你的实际 App ID) |
第三步:重启 Gateway(重要!)
这是最关键的一步! 配置完成后,必须重启 Gateway 才能让飞书连接生效。
1 | # 重启 OpenClaw Gateway |
🔥 重要提示:这一步不能省略!否则下一步中,飞书配置事件时会出错(未建立连接)。重启后,OpenClaw 会与飞书服务器建立长连接。
重启后,可以使用以下命令验证飞书连接是否正常:
1 | # 查看所有配置的频道 |

💡 配置方式说明:
飞书配置也可以通过
openclaw onboard交互式向导或openclaw channels add命令完成。本文以命令行方式为例,适合需要精确控制配置项的用户。如果你是第一次使用 OpenClaw,推荐先运行openclaw onboard完成基础配置。
配置事件订阅
重点来了,很多人这里配置会出错!
1. 配置事件
在 “事件订阅” 页面:
- 订阅方式选择 "长链接"
- 点击 “添加事件”,添加以下事件:
1 | im.chat.member.bot.added_v1 # 机器人被添加到群聊 |

发布应用
在 “版本管理与发布” 页面:
- 点击 "创建版本"
- 填写版本信息
- 点击 "发布"
🔥 再次提醒:如果你在配置事件订阅和回调后遇到问题,再次执行
openclaw gateway restart重新建立连接。
✅ 验证功能
飞书聊天测试
- 打开飞书,搜索你的机器人名称
- 发送测试消息,如:“帮我搜索一下今日有色金属的行情价格怎么样”
- 机器人应该会回复你

测试多维表格访问
-
确保您有访问权限的多维表格链接
-
发送消息给 OpenClaw,请求读取表格:
1
我有一个团队周报,我想让你帮我将表格的内容整理成一个飞书文档内容。

🔥 提醒:如果你在配置过程中遇到了需要什么权限,可以评估后进行手动添加权限。
测试文档创建/编辑
发送消息给 OpenClaw:
1 | 帮我创建一个飞书文档,标题是"测试文档" |

📚 功能说明
已实现的功能示例
| 功能 | 使用方式 | 示例 |
|---|---|---|
| 读取多维表格 | 发送表格链接 | “帮我看一下这个表格:https://…” |
| 编辑多维表格 | 发送表格链接+操作 | “在表格中添加一条记录:…” |
| 创建飞书文档 | 明确请求 | “帮我创建一个文档” |
| 编辑飞书文档 | 发送文档链接 | “更新这个文档的内容:…” |
| 读取知识库 | 发送知识库链接 | “帮我读取这个知识库:https://…” |
| 读取联系人信息 | 自然语言请求 | “查看联系人信息” |
| 读取群聊@消息 | 自动处理 | 自动接收群聊@消息 |
| 读取单聊消息 | 自动处理 | 自动接收私聊消息 |
| 消息置顶管理 | 自然语言请求 | “置顶这条消息” |
| 消息反应管理 | 自然语言请求 | “给这条消息添加👍” |
| 撤回消息 | 自然语言请求 | “撤回刚才的消息” |
| 发送多人消息 | 自然语言请求 | “发送消息给张三、李四” |
| 发送系统消息 | 自然语言请求 | “发送系统通知” |
| 更新消息内容 | 自然语言请求 | “更新刚才的消息” |
| 周报自动化 | 定时任务 | “每周一18点帮我整理周报” |
| 网络搜索 | 自然语言请求 | “帮我搜索一下…” |
| 文件操作 | 自然语言请求 | “读取/写入这个文件” |
| 消息发送 | 通过 OpenClaw CLI | echo "内容" | openclaw send feishu |
可用的权限说明
飞书权限(按功能需求):
| 需求 | 需要的权限 | 权限标识 |
|---|---|---|
| 接收和发送消息 | 发送机器人消息、接收单聊消息 | im:message:send_as_botim:message.p2p_msg:readonly |
| 读取联系人 | 读取联系人基础信息 | contact:contact.base:readonly |
| 读取员工ID | 读取用户员工ID | contact:user.employee_id:readonly |
| 读取多维表格 | 读取应用多维表格 | bitable:app:readonly |
| 编辑多维表格 | 编辑应用多维表格 | bitable:app |
| 创建/编辑文档 | 读写文档 | docx:document |
| 读取知识库 | 读取知识库内容 | wiki:wiki:readonly |
| 读取聊天信息 | 读取聊天信息 | im:chat:readim:chat:readonly |
| 更新聊天信息 | 更新聊天信息 | im:chat:update |
| 读取群聊@消息 | 读取群聊@消息 | im:message.group_at_msg:readonly |
| 消息置顶管理 | 读取/写入消息置顶 | im:message.pins:readim:message.pins:write_only |
| 消息反应管理 | 读取/写入消息反应 | im:message.reactions:readim:message.reactions:write_only |
| 只读消息 | 只读消息 | im:message:readonly |
| 撤回消息 | 撤回消息 | im:message:recall |
| 发送多人消息 | 发送多人消息 | im:message:send_multi_users |
| 发送系统消息 | 发送系统消息 | im:message:send_sys_msg |
| 更新消息 | 更新消息 | im:message:update |
| 资源访问 | 资源访问 | im:resource |
🔧 高级配置
多频道配置
OpenClaw 支持同时配置多个频道(iMessage、飞书、Discord、Telegram 等):
1 | channels: |
自动化任务配置
OpenClaw 支持定时任务(如每周整理周报):
1 | schedules: |
Cron 表达式格式:分 时 日 月 周
| 表达式 | 说明 |
|---|---|
0 9 * * * |
每天早上 9 点 |
0 */2 * * * |
每 2 小时 |
0 0 * * 0 |
每周日午夜 |
0 9 * * 1-5 |
工作日早上 9 点 |
模型配置
配置 AI 模型和相关参数:
1 | model: |
💡 推荐:智谱 GLM 系列
zai/glm-4.7- 最新版本,性能强劲zai/glm-4-flash- 快速响应,适合日常对话zai/glm-4-plus- 增强版,适合复杂任务
⚡ 常用命令速查
在日常使用中,以下命令会经常用到:
Gateway 管理
| 命令 | 说明 |
|---|---|
openclaw gateway start |
启动 Gateway 服务 |
openclaw gateway stop |
停止 Gateway 服务 |
openclaw gateway restart |
重启 Gateway(最常用!) |
openclaw gateway status |
查看 Gateway 运行状态 |
插件管理
| 命令 | 说明 |
|---|---|
openclaw plugins install @插件名 |
安装插件 |
openclaw plugins list |
查看已安装插件 |
openclaw plugins uninstall @插件名 |
卸载插件 |
配置管理
| 命令 | 说明 |
|---|---|
openclaw config show |
查看当前配置 |
openclaw config set 配置项 "值" |
设置配置项 |
openclaw config get 配置项 |
获取指定配置项 |
频道管理
| 命令 | 说明 |
|---|---|
openclaw channels list |
查看所有已配置频道 |
openclaw channel show 频道名 |
查看指定频道配置 |
openclaw channel add 频道名 |
交互式添加频道 |
模型管理
| 命令 | 说明 |
|---|---|
openclaw models list |
查看可用模型 |
openclaw models set 模型名 |
设置默认模型 |
openclaw models fallbacks add 模型名 |
添加备用模型 |
TUI(终端用户界面)
| 命令 | 说明 |
|---|---|
openclaw tui |
启动终端对话界面 |
/new |
开启新对话(在 TUI 中) |
⚡ 重要提示:关于 openclaw gateway restart
在配置和使用 OpenClaw 过程中,openclaw gateway restart 命令至关重要。以下是必须执行此命令的场景:
必须执行 openclaw gateway restart 的场景:
- 修改配置文件后 - 任何对
~/.openclaw/config.yml的修改 - 添加/修改飞书权限后 - 在飞书开放平台添加新权限后
- 配置飞书应用后 - 完成飞书应用配置后
- 启用长连接管理后 - 配置长连接时间管理功能后
- 更新 OpenClaw 后 - 安装新版本后
- 功能不生效时 - 任何功能不正常工作时
- 网络连接问题 - 飞书消息接收延迟或丢失时
为什么需要重启?
- Gateway 服务在启动时加载配置
- 修改配置后,Gateway 不会自动重新加载
- 重启确保新配置和权限生效
- 重新建立与飞书、iMessage 等服务的连接
重启命令:
1 | # 重启 Gateway 服务 |
🔄 更新与维护
更新 OpenClaw
1 | # 更新到最新版本 |
查看当前版本
1 | openclaw --version |
📖 参考资源
💡 使用场景灵感
OpenClaw 不仅仅是一个聊天机器人,它可以成为你的:
- 📊 数据分析师:自动读取多维表格,生成报表
- 📝 文档助手:自动创建、编辑飞书文档
- 📅 日程管家:管理日程,发送提醒
- 🤖 自动化工具:定时执行任务,如周报整理
- 📚 知识库管理员:自动整理和检索知识库内容