Skip to content

安装使用指南.md

Latest commit

 

History

History
462 lines (321 loc) · 19.2 KB

安装使用指南.md

File metadata and controls

462 lines (321 loc) · 19.2 KB
Raw

OpenClaw 飞书专版 — 安装使用指南

适用于 macOS 系统，从零开始，3 分钟配置完成。

目录

准备工作

在开始之前，请确认你满足以下条件：

  1. 一台 macOS 电脑（macOS 12 Monterey 或更高版本，Apple Silicon 或 Intel 均可）
  2. 飞书账号，且你是企业/组织的管理员，或拥有创建应用的权限
  3. 已开通至少一个 AI 模型的 API Key（MiniMax / 智谱 GLM / 豆包 / Kimi 四选一），具体开通方式见 第四部分

零依赖安装：安装包已内置 Node.js 运行时和 OpenClaw 引擎，你不需要安装任何其他软件。DMG 拖入即用。

如果你还没有 AI 模型的 API Key，可以先完成飞书机器人的创建，在安装向导中跳过模型配置，稍后在设置中补充。

第一部分：创建飞书机器人应用

这是整个流程中最关键的步骤。你需要在飞书开放平台创建一个「企业自建应用」，并为它配置正确的权限和事件订阅。

1.1 登录飞书开放平台

  1. 用浏览器打开飞书开放平台：https://open.feishu.cn
  2. 点击右上角「登录」，使用你的飞书账号登录
  3. 登录后会进入「开发者后台」

如果你看不到「创建应用」按钮，说明你的飞书账号没有开发者权限。请联系你的企业管理员，在飞书管理后台为你开通开发者权限。

1.2 创建企业自建应用

  1. 在开发者后台，点击 「创建应用」 按钮
  2. 选择 「企业自建应用」（不要选"应用商店应用"）
  3. 填写基本信息：
    • 应用名称：起一个你喜欢的名字，比如 "我的AI助手"、"小智" 等（这个名字就是你在飞书中搜索机器人时用的名字）
    • 应用描述：简单描述即可，比如 "AI 智能助手，基于 OpenClaw"
    • 应用图标：上传一张图标（可选，不上传会用默认图标）
  4. 点击 「创建」

创建成功后，你会进入应用的详情页面。

1.3 添加「机器人」能力

  1. 在应用详情页面，找到左侧菜单中的 「添加应用能力」
  2. 在能力列表中，找到 「机器人」，点击 「添加」
  3. 添加后你会看到机器人已出现在应用能力列表中

这一步是告诉飞书"这个应用需要作为一个机器人来使用"。

1.4 配置权限（重要）

这是最容易出错的步骤。你需要为机器人开通正确的权限，否则机器人将无法收发消息。

  1. 在左侧菜单中，点击 「权限管理」
  2. 你需要开通以下 3 个权限：
权限名称 权限标识 用途说明 如何找到
获取与发送单聊、群组消息 im:message 让机器人能够接收和查看用户发来的消息 搜索 "im:message"
以应用的身份发消息 im:message:send_as_bot 让机器人能够回复消息 搜索 "send_as_bot"
读取用户发给机器人的单聊消息 im:message:readonly 让机器人能够读取消息内容 搜索 "readonly"

操作步骤：

  1. 在权限管理页面，你会看到一个搜索框
  2. 在搜索框中输入 im:message，找到 「获取与发送单聊、群组消息」，点击 「开通」
  3. 搜索 im:message:send_as_bot，找到 「以应用的身份发消息」，点击 「开通」
  4. 搜索 im:message:readonly，找到 「读取用户发给机器人的单聊消息」，点击 「开通」

注意：这 3 个权限缺一不可。如果漏掉了任何一个，机器人可能可以连接但无法正常收发消息。

可选但推荐的额外权限：

权限标识 用途
im:message.reactions:write_only 允许机器人给消息添加表情回应（如正在处理时显示⏳）
im:chat:readonly 获取群聊信息（如果需要在群聊中使用）

1.5 配置事件订阅（重要）

事件订阅让飞书知道"当有新消息时，通知我的机器人"。

  1. 在左侧菜单中，点击 「事件与回调」

  2. 在页面顶部，你会看到两种接收方式：

    • 请求地址（需要公网服务器，不要选这个）
    • 「使用长连接接收事件」 ← 选这个

  3. 点击 「使用长连接接收事件」，开启长连接模式

为什么选长连接？ 长连接（WebSocket）模式不需要你有公网服务器或域名。机器人会主动连接到飞书服务器，飞书通过这个连接推送消息。这对于在自己电脑上运行的应用来说是最方便的方式。

  1. 开启长连接后，你需要添加一个事件：
    • 点击 「添加事件」 按钮
    • 搜索 im.message.receive_v1
    • 找到 「接收消息」 事件，点击 「添加」

这个事件的意思是：当有人给机器人发消息时，飞书会通过长连接把消息内容推送过来。

  1. 获取 Verification Token（可选但推荐）：
    • 在「事件与回调」页面中，找到 「加密策略」 部分
    • 你会看到 Verification Token 和 Encrypt Key
    • 把这两个值记下来，后面配置时会用到

1.6 获取凭证信息

现在你需要获取两个关键信息：App ID 和 App Secret。

  1. 在左侧菜单中，点击 「凭证与基础信息」
  2. 你会看到：
    • App ID：类似 cli_a5xxxxxxxxxx 的字符串
    • App Secret：一串加密字符串，点击「显示」可以看到

请把这两个值复制保存好，后面安装配置时需要用到。

安全提醒：App Secret 是敏感信息，请不要分享给他人或发布到网上。

1.7 发布应用

创建应用后，它还处于"开发中"状态，需要发布后才能正式使用。

  1. 在左侧菜单中，点击 「版本管理与发布」
  2. 点击 「创建版本」
  3. 填写版本号（如 1.0.0）和更新说明（如 "首次发布"）
  4. 点击 「提交审核」

关于审核：企业自建应用的审核通常由你的企业管理员完成。如果你自己就是管理员，审核会几乎立即通过。发布后，企业内的成员就可以在飞书中找到并使用这个机器人了。

确认应用已发布： 发布成功后，在应用信息页面，你会看到应用状态变为 「已启用」 或 「已发布」。

第二部分：安装和配置 OpenClaw 飞书专版

2.1 安装应用

  1. 下载 OpenClaw 飞书专版的 .dmg 安装文件（约 400–500 MB，已内置全部运行依赖）
  2. 双击打开 .dmg 文件
  3. 将 「OpenClaw 飞书专版」 图标拖入 「Applications」 文件夹
  4. 打开「应用程序」文件夹，双击 「OpenClaw 飞书专版」 启动应用

安装包为什么这么大？ 为了让你开箱即用，安装包内置了 Node.js 运行时和 OpenClaw AI 引擎的全部依赖。你不需要额外安装 Node.js、npm 或任何命令行工具。

首次启动提示：macOS 可能会提示"无法验证开发者"。如果遇到：

  1. 打开「系统设置」→「隐私与安全性」
  2. 滚动到底部，找到关于 OpenClaw 的安全提示
  3. 点击「仍要打开」

首次启动后，应用会自动弹出 配置向导。

2.2 配置向导 — 飞书连接

配置向导的第一步是连接你的飞书机器人。

  1. 在欢迎页面，点击 「开始配置」
  2. 进入飞书配置页面，填入你在 1.6 中保存的信息：
    • App ID：粘贴你的 App ID（以 cli_ 开头）
    • App Secret：粘贴你的 App Secret
    • Verification Token（可选）：如果你在 1.5 中记录了，填入此处
    • Encrypt Key（可选）：同上
    • 机器人名称：默认为"我的AI助手"，你可以改成其他名字
  3. 点击 「下一步」

系统会自动验证你的飞书配置，检查以下几项：

检查项 说明 如果失败怎么办
凭证验证 App ID 和 Secret 是否正确 回到飞书开放平台重新复制，注意不要有多余的空格
权限检查 是否已开通必要的消息权限 回到 1.4 检查 3 个权限是否全部开通
应用状态 应用是否已发布 回到 1.7 完成发布流程
机器人能力 是否添加了机器人能力 回到 1.3 检查

如果所有检查都通过，你会看到绿色的 ✅ 标识，可以进入下一步。

2.3 配置向导 — 选择 AI 模型

这一步为你的机器人选择一个 AI 大脑。

安装包目前支持 5 个选择：

模型 特点 价格参考 适合场景
MiniMax（推荐） 写作能力强，中文理解好 性价比高 日常对话、写作创意
智谱 GLM 编程能力强，工具调用好 价格适中 编程辅助、技术问答
豆包 综合能力强，字节出品 价格适中 通用场景
Kimi 128K 超长上下文 价格适中 长文档处理、深度分析
自定义 兼容 OpenAI API 格式 视供应商而定 高级用户

操作步骤：

  1. 点击你想使用的模型卡片
  2. 如果还没有该模型的 API Key，点击卡片上的 「去开通 →」 链接（会打开对应平台的注册页面，详见 第四部分）
  3. 填入你的 API Key
  4. API Base URL 和 模型名称 会自动填好，一般不需要修改
  5. 点击 「测试连接」 验证 API Key 是否有效
  6. 看到 ✅ 后，点击 「下一步」

没有 API Key？ 可以点击「跳过，稍后配置」，先完成安装。但机器人在配置 AI 模型之前无法回复消息。

2.4 完成配置

看到 🎉「配置完成」页面后，你的 AI 助手就已经准备就绪了！

点击 「开始使用」，应用会：

  • 在 macOS 菜单栏显示一个小图标（通常在屏幕右上角）
  • 使用内置的 Node.js 和 OpenClaw 引擎自动启动 Gateway 服务（无需任何外部依赖）
  • 通过 WebSocket 长连接连接到飞书

第三部分：开始使用

3.1 在飞书中使用

私聊（1对1对话）：

  1. 打开飞书
  2. 点击左上角的 搜索框
  3. 输入你设置的机器人名称（默认 "我的AI助手"）
  4. 在搜索结果中找到你的机器人，点击进入对话
  5. 直接发送消息，机器人就会回复

群聊中使用：

  1. 将机器人添加到群聊：在群设置中添加机器人
  2. 在群聊中，@ 你的机器人名称 后输入消息
  3. 例如：@我的AI助手 帮我写一封邮件

注意：在群聊中，默认需要 @机器人 才会触发回复，避免机器人响应每一条群消息。

支持的消息类型：

  • 文字消息：直接发送文字即可
  • 图片：发送图片，AI 可以识别图片内容
  • 文件：发送文件（如 PDF、Word 等），AI 可以阅读和处理

3.2 管理和设置

菜单栏图标：

应用运行时，macOS 菜单栏右上角会显示一个图标：

  • 🟢 绿色 = 运行正常
  • 🔴 红色 = 连接异常
  • ⚪ 灰色 = 服务未启动

点击图标可以：

  • 查看当前状态
  • 打开设置界面
  • 查看运行日志
  • 重启服务

修改设置：

在设置界面中，你可以：

  • 修改飞书连接信息（App ID、Secret 等）
  • 切换或更换 AI 模型
  • 调整高级配置（如会话超时时间、并发数等）

第四部分：AI 模型开通指南

你需要至少开通以下一个模型的 API 服务。以下是每个平台的开通步骤。

4.1 MiniMax（推荐）

MiniMax 是一家国产 AI 公司，性价比高，中文写作能力出色。

  1. 打开 MiniMax 开放平台：https://www.minimaxi.com/platform
  2. 注册并登录账号
  3. 进入控制台，找到 「API Keys」 页面
  4. 点击 「创建 API Key」，复制保存生成的 Key
  5. 确保账户中有余额（新用户通常有赠送额度）

配置信息：

  • API Base URL：https://api.minimaxi.com/anthropic（安装包已自动填写）
  • 默认模型：MiniMax-M2.5

4.2 智谱 GLM

智谱是清华系 AI 公司，GLM 模型在编程和工具调用方面表现突出。

  1. 打开智谱开放平台：https://open.bigmodel.cn
  2. 注册并登录账号
  3. 进入「API 管理」→「API Keys」
  4. 创建一个新的 API Key，复制保存

配置信息：

  • API Base URL：https://open.bigmodel.cn/api/paas/v4（安装包已自动填写）
  • 默认模型：glm-4.7-flash

4.3 豆包 Doubao

豆包是字节跳动出品的 AI 模型，综合能力强。

  1. 打开火山引擎控制台：https://console.volcengine.com/ark
  2. 注册并登录账号（使用抖音/今日头条账号也可以）
  3. 开通「模型推理」服务
  4. 在「API Key 管理」中创建 Key，复制保存

配置信息：

  • API Base URL：https://ark.cn-beijing.volces.com/api/v3（安装包已自动填写）
  • 默认模型：doubao-1.5-pro-256k

注意：豆包的 API 接入方式可能需要先在控制台中创建一个「推理端点」，然后使用端点 ID 作为模型名称。具体请参考火山引擎的文档。

4.4 Kimi（月之暗面）

Kimi 是月之暗面出品，以超长上下文（128K tokens）著称，适合处理长文档。

  1. 打开 Moonshot 开放平台：https://platform.moonshot.cn
  2. 注册并登录账号
  3. 进入「API Key 管理」
  4. 创建一个新的 API Key，复制保存

配置信息：

  • API Base URL：https://api.moonshot.cn/v1（安装包已自动填写）
  • 默认模型：moonshot-v1-128k

常见问题与排错

Q1：配置验证时提示「凭证无效」

原因：App ID 或 App Secret 输入错误。

解决方法：

  1. 回到飞书开放平台 → 「凭证与基础信息」
  2. 重新复制 App ID 和 App Secret
  3. 注意复制时不要带上前后的空格
  4. 粘贴到安装包中重新验证

Q2：配置验证通过，但飞书中发消息没有回复

可能原因和解决方法：

  1. 应用未发布：回到飞书开放平台，确认应用状态为「已启用」。如果还是「开发中」，需要先发布。
  2. 事件订阅未配置：确认已按 1.5 配置了长连接和 im.message.receive_v1 事件。
  3. AI 模型未配置：如果跳过了模型配置，机器人无法生成回复。请在设置中补充 API Key。
  4. AI 模型 API Key 余额不足：检查对应模型平台的账户余额。
  5. 服务未运行：检查菜单栏图标是否为绿色。如果不是，尝试重启服务。

Q3：机器人回复了但内容是错误信息（如 "404 Not Found"）

原因：AI 模型的 API 请求地址配置不正确。

解决方法：

  1. 打开设置界面 → AI 模型
  2. 确认 API Base URL 和模型名称是正确的：
    • MiniMax：https://api.minimaxi.com/anthropic，模型 MiniMax-M2.5
    • 智谱 GLM：https://open.bigmodel.cn/api/paas/v4，模型 glm-4.7-flash
    • 豆包：https://ark.cn-beijing.volces.com/api/v3，模型 doubao-1.5-pro-256k
    • Kimi：https://api.moonshot.cn/v1，模型 moonshot-v1-128k
  3. 修改后保存，系统会自动重启服务

Q4：提示权限不足（如 im:message 相关错误）

解决方法：

  1. 回到飞书开放平台 → 「权限管理」
  2. 逐一搜索以下权限，确保全部已开通：
    • im:message
    • im:message:send_as_bot
    • im:message:readonly
  3. 如果添加了新权限，需要重新发布应用（创建新版本并提交审核）

Q5：群聊中 @机器人没有反应

解决方法：

  1. 确认机器人已被添加到群聊中（在群设置 → 机器人 中检查）
  2. 确认 @ 的名称和你设置的机器人名称完全一致
  3. 确认群聊权限策略为「开放」（在设置中检查）

Q6：macOS 提示"无法打开应用"或"已损坏"

解决方法：

  1. 打开「终端」（在启动台 → 其他 中找到）
  2. 输入以下命令并回车： 
    xattr -cr /Applications/OpenClaw飞书专版.app
  3. 重新打开应用

Q7：如何更换 AI 模型？

  1. 点击菜单栏图标 → 「设置」
  2. 切换到「AI 模型」标签
  3. 选择新的模型供应商
  4. 填入对应的 API Key
  5. 保存即可，无需重启

Q8：需要自己安装 Node.js 吗？

不需要。 OpenClaw 飞书专版的 DMG 安装包已经内置了 Node.js 运行时（v22 LTS）和 OpenClaw 引擎的所有依赖。拖入 Applications 即可使用，无需安装任何命令行工具。

Q9：如何查看运行日志？

如果遇到无法解决的问题，可以通过查看日志来定位：

  1. 点击菜单栏图标 → 「查看日志」
  2. 或者手动查看日志文件位置：~/.openclaw/logs/

飞书权限一览表

以下是 OpenClaw 飞书专版需要的所有飞书权限汇总：

权限标识 权限名称 是否必须 用途
im:message 获取与发送单聊、群组消息 必须 机器人接收用户消息
im:message:send_as_bot 以应用的身份发消息 必须 机器人回复消息
im:message:readonly 读取用户发给机器人的单聊消息 必须 读取消息内容
im:message.reactions:write_only 添加消息表情回应 推荐 显示处理状态表情
im:chat:readonly 获取群组信息 可选 群聊相关功能

事件订阅：

事件名称 事件标识 是否必须 接收方式
接收消息 im.message.receive_v1 必须 长连接（WebSocket）

技术支持

如果你在使用过程中遇到问题：

  1. 首先查看上方的「常见问题」部分
  2. 查看应用日志（菜单栏 → 查看日志）
  3. 访问 OpenClaw 官方文档获取更多帮助

本文档适用于 OpenClaw 飞书专版 v1.0。最后更新：2026 年 2 月。