diff --git a/docs/FEISHU_SETUP_BEGINNER.md b/docs/FEISHU_SETUP_BEGINNER.md new file mode 100644 index 0000000..3e3156d --- /dev/null +++ b/docs/FEISHU_SETUP_BEGINNER.md @@ -0,0 +1,159 @@ +# 👶 零基础！飞书 (Feishu/Lark) 接入 OpenClaw 保姆级完整教程 + +> 🎯 **本教程专为 OpenClaw 用户设计。** +> 跟着下面的图文步骤，你可以在 10 分钟内完成飞书机器人接入（长连接模式），无需公网 IP。 + +--- + +## 🟢 核心理念：我们需要准备哪几把“钥匙”？ +将 OpenClaw 接入飞书（Lark）长连接模式，通常需要以下凭证： +1. **App ID**：应用唯一标识（相当于机器人账号 ID）。 +2. **App Secret**：应用密钥（相当于机器人密码）。 +3. **Verification Token**：事件订阅校验凭证（用于校验回调来源）。 +4. **Encrypt Key（可选）**：当你开启事件加密传输时必须填写。 + +> [!TIP] +> 飞书平台不同版本（飞书中国站 / Lark 国际站）界面文案可能略有差异，但菜单路径一致： +> **开发者后台 -> 你的应用 -> 凭证与基础信息 / 事件与回调**。 + +--- + +## 第 1 步：在飞书开放平台创建企业自建应用 + +1. 打开 [飞书开放平台](https://open.feishu.cn/)（Lark 国际站可使用 https://open.larksuite.com/）。 +2. 登录管理员账号，进入 **开发者后台**。 +3. 点击 **创建应用**，选择 **企业自建应用（Custom App）**。 +4. 填写应用名称（建议：`OpenClaw-devkit`）和应用描述，确认创建。 +5. 创建完成后进入应用详情页。 + +![步骤 1：创建企业自建应用](images/guides/feishu_step1_create_app.png) + +--- + +## 第 2 步：启用机器人能力并安装到企业 + +1. 在应用左侧菜单进入 **添加应用能力**。 +2. 打开 **启用机器人** 开关。 +3. 在 **可用范围** 中选择测试群或全员（建议先小范围测试）。 +4. 进入 **版本管理与发布**，点击 **创建版本** 并 **发布**。 +5. 在企业管理后台完成安装/可用配置（如需审批，按组织流程处理）。 + +--- + +## 第 3 步：配置事件订阅（长连接 / WebSocket） + +1. 在应用菜单进入 **事件与回调 / Event Subscriptions**。 +2. 打开 **事件订阅** 开关。 +3. 选择 **长连接（WebSocket）** 模式。 +4. 按下文“推荐事件列表”勾选必需事件。 +5. 保存配置。 +6. 找到 **Verification Token** 并复制。 +7. 如果你启用了“加密传输”或“Encrypt”开关，再复制 **Encrypt Key**。 +8. 如果未启用加密，`Encrypt Key` 可留空（或不填）。 + +![步骤 3：开启事件订阅并选择长连接](images/guides/feishu_step3_events.png) + +### 常见报错排查：未检测到应用连接信息 + +如果在飞书后台保存长连接配置时看到提示： +"未检测到应用连接信息，请确保长连接建立成功后再保存配置"，按以下顺序处理： + +1. 先填好 App ID / App Secret（如何获取详见第 4 步），再启动 OpenClaw 服务。 +2. 在飞书后台确认当前应用已经发布并安装到企业（未发布的应用不会建立稳定连接）。 +3. 检查事件订阅页是否已开启“长连接（WebSocket）”，并保持在该页面刷新状态。 +4. 打开网关日志，确认是否出现 WebSocket connected、event stream started 等成功字样。 +5. 若日志没有连接成功，优先排查出网网络： + - 服务器是否可访问飞书开放平台域名 + - 是否配置了 HTTP_PROXY / HTTPS_PROXY + - 代理是否允许容器网络出站 +6. 再次返回事件订阅页面，点击刷新后重新保存。 + +若仍失败，通常是“应用凭证不匹配”或“应用未发布安装”导致。请重新核对： +- App ID / App Secret 是否来自同一个应用 +- 当前租户是否就是该应用的安装租户 +- 机器人能力是否已启用 + +--- + +## 第 4 步：获取 App ID 与 App Secret + +1. 进入 **凭证与基础信息 / Credentials & Basic Info**。 +2. 在页面中找到并复制 **App ID**。 +3. 点击显示或重置密钥后复制 **App Secret**。 +4. 将两项临时保存到你的密码管理器或安全笔记中。 + +![步骤 4：获取 App ID 与 App Secret](images/guides/feishu_step4_info.png) + +--- + +## 第 5 步：填写 OpenClaw `.env` 示例 + +在 OpenClaw 根目录创建或编辑 `.env` 文件（首次可从 `.env.example` 复制）： + +```env +# Feishu/Lark App identity +FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxxx +FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx + +# Event verification (required when event subscription enabled) +FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxx + +# Optional: only required when encrypted event payload is enabled +FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxx + +# Recommended mode for intranet/no-public-ip deployment +FEISHU_EVENT_MODE=websocket +``` + +> [!IMPORTANT] +> 当前仓库的 `.env.example` 默认**不包含**上面这些 `FEISHU_*` 键名，且新版本 OpenClaw 在通过 `make onboard` 配置时**不一定会从 `.env` 中读取这些变量**。实际生效的配置以 `~/.openclaw/openclaw.json` 中的落盘键名和值为准。 +> > +> > 上面的 `.env` 代码片段主要用于帮你**理解飞书控制台字段与 OpenClaw 内部配置项之间的映射关系**。如果你希望继续使用 `.env` 方式，请先完成 `make onboard`，然后对照 `~/.openclaw/openclaw.json` 中的字段名称，将对应值手动映射到你自己的环境变量命名方案中。 + +--- + +## 第 6 步：启动并验证接入是否成功 + +1. 保存 `.env` 后，在项目根目录执行： + +```bash +docker compose down +docker compose up -d +``` + +2. 在飞书中把机器人拉入测试群。 +3. 在群内 @ 机器人，发送 `Hi` 或 `帮我总结今天的待办`。 +4. 若机器人正常响应，说明接入成功。 + +**推荐日志检查点**： +- 网关日志出现 WebSocket connected / event received。 +- 事件处理无鉴权错误（invalid token / decrypt failed）。 + +--- + +## ✅ 推荐权限点与事件列表（可直接照抄） + +### 建议开启的应用权限（Scopes） +- 获取与发送单聊/群聊消息 +- 获取会话基本信息（群 ID、会话类型） +- 读取 @ 机器人的消息内容 +- 发送富文本或卡片消息（如你启用了卡片交互） + +### 建议订阅的事件（Events） +- 机器人被 @（消息触发核心） +- 群消息（仅建议在受控群范围内启用） +- 单聊消息（如需 DMs 能力） +- 机器人加入群聊 / 会话变更（可选，用于状态同步） + +> [!TIP] +> 权限遵循最小化原则：先开启最小必需权限跑通流程，再按需扩展。 + +--- + +## 🚀 进阶建议（强烈推荐） + +1. **先小范围灰度**：仅在一个测试群启用，验证稳定后再扩大范围。 +2. **开启管理员审批**：若团队多人使用，建议配合 OpenClaw 的管理员审批能力，避免高危操作误触发。 +3. **频道白名单**：只允许机器人在指定业务群工作，降低噪音与风险。 +4. **代理配置**：若网络受限，请在 `.env` 中配置 `HTTP_PROXY` / `HTTPS_PROXY`。 +5. **日志监控**：定期检查网关日志，关注连接状态和事件处理情况，及时调整权限或排查问题。 \ No newline at end of file diff --git a/docs/FEISHU_SETUP_BEGINNER_en.md b/docs/FEISHU_SETUP_BEGINNER_en.md new file mode 100644 index 0000000..206d74f --- /dev/null +++ b/docs/FEISHU_SETUP_BEGINNER_en.md @@ -0,0 +1,170 @@ +# 👶 Zero-Friction! Feishu (Lark) Integration Beginner Guide for OpenClaw + +> 🎯 **This guide is written for OpenClaw users who want a step-by-step setup with screenshots.** +> You can complete Feishu/Lark integration in around 10 minutes using long connection mode (WebSocket), without exposing a public webhook endpoint. + +--- + +## 🟢 Core Concept: Which "keys" do we need? +For Feishu/Lark long-connection integration, you usually need these credentials: +1. **App ID**: Unique app identifier. +2. **App Secret**: App-level secret key. +3. **Verification Token**: Event source verification token. +4. **Encrypt Key (optional)**: Required only when encrypted event payload is enabled. + +> [!TIP] +> UI labels can differ slightly between Feishu CN and Lark Global, but the menu path is typically the same: +> **Developer Console -> Your App -> Credentials & Basic Info / Event Subscriptions**. + +--- + +## Step 1: Create a Custom App in Feishu Open Platform + +1. Open [Feishu Open Platform](https://open.feishu.cn/) (for global Lark, use https://open.larksuite.com/). +2. Sign in with an admin/developer account and enter the developer console. +3. Click **Create App** and choose **Custom App (tenant app)**. +4. Fill in app name (recommended: `OpenClaw-devkit`) and description. +5. Enter the app detail page after creation. + +![Step 1: Create custom app](images/guides/feishu_step1_create_app.png) + +--- + +## Step 2: Enable Bot Capability and Publish the App + +1. Open **Add App Capability** from the left menu. +2. Enable the bot switch. +3. Configure app availability scope (recommend a test group first). +4. Go to **Version Management & Release**, create a version, then publish. +5. Complete tenant installation/approval if your org requires it. + +--- + +## Step 3: Configure Event Subscription (WebSocket / Long Connection) + +1. Open **Event Subscriptions** in your app settings. +2. Enable event subscription. +3. Select **Long Connection (WebSocket)** if a subscription mode selector is provided. +4. Select the recommended events from the list in this guide. +5. Save the configuration. +6. Copy **Verification Token**. +7. If encrypted event delivery is enabled, copy **Encrypt Key** too. +8. If encryption is disabled, `Encrypt Key` can be empty. + +![Step 3: Enable event subscription with websocket](images/guides/feishu_step3_events.png) + +### Common Error Fix: "No app connection detected" + +If Feishu shows this message when you save long-connection settings: +"No app connection detected. Please make sure the long connection is established before saving.", +handle it in this order: + +1. Make sure you have obtained your App ID / App Secret (see Step 4), filled them correctly in OpenClaw, then start OpenClaw services. +2. In Feishu console, confirm the app is already published and installed to the tenant. +3. Verify Event Subscriptions is set to **Long Connection (WebSocket)** and keep that page refreshed. +4. Check gateway logs for success markers such as `WebSocket connected` or `event stream started`. +5. If no connection logs appear, check outbound networking first: + - whether the server can access Feishu Open Platform domains + - whether `HTTP_PROXY` / `HTTPS_PROXY` is configured + - whether your proxy allows container egress traffic +6. Return to Event Subscriptions, refresh, and save again. + +If it still fails, the most common causes are credential mismatch or app not published/installed. Re-check: +- App ID / App Secret come from the same app +- Current tenant is the same tenant where this app is installed +- Bot capability is enabled + +--- + +## Step 4: Get App ID and App Secret + +1. Go to **Credentials & Basic Info**. +2. Copy **App ID**. +3. Reveal/reset and copy **App Secret**. +4. Store both values securely. + +![Step 4: Get app id and app secret](images/guides/feishu_step4_info.png) + +--- + +## Step 5: Fill your OpenClaw `.env` file + +Create or edit `.env` in the OpenClaw root directory: + +```env +# Feishu/Lark App identity +FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxxx +FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx + +# Event verification (required when event subscription is enabled) +FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxx + +# Optional: required only when encrypted event payload is enabled +FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxx + +# Recommended for no-public-IP deployments +FEISHU_EVENT_MODE=websocket +``` + +> [!IMPORTANT] +> The `FEISHU_*` variable names shown above are **illustrative examples only**. They are **not** guaranteed to appear in `.env.example` or be read directly by OpenClaw. +> For real deployments, `make onboard` and the generated config in `~/.openclaw/openclaw.json` are the **authoritative configuration path**. +> Use this `.env` snippet only as a **conceptual mapping** between your Feishu app credentials and potential environment variables, or if your own deployment tooling is explicitly wired to expect these names. + +--- + +## Step 6: Start services and verify + +1. Save `.env`, then run in project root: + +```bash +docker compose down +docker compose up -d +``` + +2. Invite the bot into a test group. +3. Mention the bot and send `Hi` or a simple task. +4. If the bot responds, integration is successful. + +**Recommended log checkpoints**: +- Gateway logs show WebSocket connected / event received. +- No auth/decryption errors (`invalid token`, `decrypt failed`). + +--- + +## ✅ Recommended Permissions and Event List + +### Recommended app permissions (scopes) +- Send and receive group/direct messages +- Read conversation metadata (chat/group IDs, conversation type) +- Read messages that mention the bot +- Send rich text or interactive cards (if card workflow is enabled) + +### Recommended event subscriptions +- Bot mention event (core trigger) +- Group message event (enable only for controlled scopes) +- Direct message event (if DM support is needed) +- Bot joined/removed or conversation update events (optional for lifecycle sync) + +> [!TIP] +> Follow least-privilege principle: start with minimum required permissions, then expand only when needed. + +--- + +## 🚀 Advanced Recommendations + +1. **Canary rollout first**: start with one test chat. +2. **Admin approval for risky actions**: strongly recommended for team environments. +3. **Channel allowlist**: limit bot operation to specific business chats. +4. **Proxy configuration**: set `HTTP_PROXY` / `HTTPS_PROXY` if network egress is restricted. +5. **Log monitoring**: check gateway logs regularly for connection state and event handling errors. + +--- + +## 📸 Screenshot Asset Naming (under docs/images/guides/) + +- `feishu_step1_create_app.png` +- `feishu_step3_events.png` +- `feishu_step4_info.png` + +> Keep these filenames stable so the team can replace placeholders with real captured screenshots later. diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 5233ef5..42c0863 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -16,7 +16,7 @@ - [5. 数据持久化深探](#5-深度解析数据挂载与持久化) - 理解 Host Bind vs. Named Volumes。 - [6. Roles 与开发流调优](#6-roles-与开发流优化) - 基于软链接的 Git 工作流最佳实践。 - [7. 高级玩法：自定义镜像与扩展编排](#7-高级玩法自定义镜像与扩展编排) - 深入最佳实践无缝扩展底层架构。 -- [附：Slack 接入保姆级教程](SLACK_SETUP_BEGINNER.md) | [飞书 (Lark) 接入指南](#) +- [附：Slack 接入保姆级教程](SLACK_SETUP_BEGINNER.md) | [飞书 (Lark) 接入指南](FEISHU_SETUP_BEGINNER.md) ### 🔴 架构篇：底层逻辑与安全基座 - [8. 分层编排解析](#8-底层逻辑分层编排架构-layered-orchestration) - 揭秘 `docker-compose.build.yml` 的动态注入。 @@ -133,7 +133,7 @@ OpenClaw 支持通过 Socket Mode 接入多种办公平台。 > 对于代码辅助这类高级生产力场景，**便捷体验**和**展现力**至关重要。区别于普通聊天工具，Slack 和飞书提供的**高阶富文本能力**（完美渲染 Markdown、代码块语法高亮、按键交互）能让查阅代码和确认 Diff 犹如在 IDE 中般自然。此外，它们原生支持的**长连接机制（Socket Mode / WebSocket）**更是极大降低了使用门槛——哪怕没有公网 IP、身处局域网深处，也彻底免去了配置复杂内网穿透（Webhook）的烦恼，真正实现了安全且极速的“开箱即联”。 - **Slack (推荐)**：请参阅 [Slack 接入保姆级教程](SLACK_SETUP_BEGINNER.md)。 -- **飞书 (Lark)**：开发中，敬请期待。 +- **飞书 (Lark)**：请参阅 [飞书 (Lark) 接入指南](FEISHU_SETUP_BEGINNER.md)。 --- diff --git a/docs/REFERENCE_en.md b/docs/REFERENCE_en.md index f7d8cab..c727095 100644 --- a/docs/REFERENCE_en.md +++ b/docs/REFERENCE_en.md @@ -16,7 +16,7 @@ This manual is the definitive technical specification and operational guide for - [5. Data Persistence Deep Dive](#5-deep-dive-data-mounting--persistence) - Understanding Host Binds vs. Named Volumes. - [6. Roles & Dev flow Optimization](#6-roles--dev-flow-optimization) - Git workflow best practices with symlinks. - [7. Advanced Usage: Custom Images & Composability](#7-advanced-usage-custom-images--composability) - Deep insights on seamless architectural extensibility. -- [Appx: Slack Setup Beginner Guide](SLACK_SETUP_BEGINNER_en.md) | [Feishu (Lark) Guide](#) +- [Appx: Slack Setup Beginner Guide](SLACK_SETUP_BEGINNER_en.md) | [Feishu (Lark) Guide](FEISHU_SETUP_BEGINNER_en.md) ### 🔴 Architect Tier: Core Logic & Security Foundation - [8. Layered Orchestration Analysis](#8-core-logic-layered-orchestration) - The mechanics of `docker-compose.build.yml` dynamic injection. @@ -133,7 +133,7 @@ OpenClaw supports connecting to various office platforms via Socket Mode. > For code-assist scenarios, **convenience** and **expressiveness** are paramount. Unlike standard chat apps, Slack and Feishu offer **advanced rich text capabilities** (flawless Markdown rendering, highlighted code blocks, key interaction) that makes reading code and confirming diffs feel as natural as within an IDE. Furthermore, their native support for **persistent connections (Socket Mode / WebSocket)** drastically lowers the barrier to entry—even without a public IP or when deep inside an intranet firewall, it completely eliminates the headache of configuring complex Webhook tunnels, offering a truly "plug-and-play" seamless connection setup. - **Slack (Recommended)**: Refer to the [Slack Setup Beginner Guide](SLACK_SETUP_BEGINNER_en.md). -- **Feishu (Lark)**: Development in progress, stay tuned. +- **Feishu (Lark)**: Refer to the [Feishu (Lark) Guide](FEISHU_SETUP_BEGINNER_en.md). --- diff --git a/docs/images/guides/feishu_step1_create_app.png b/docs/images/guides/feishu_step1_create_app.png new file mode 100644 index 0000000..b4ba869 Binary files /dev/null and b/docs/images/guides/feishu_step1_create_app.png differ diff --git a/docs/images/guides/feishu_step3_events.png b/docs/images/guides/feishu_step3_events.png new file mode 100644 index 0000000..05e46a5 Binary files /dev/null and b/docs/images/guides/feishu_step3_events.png differ diff --git a/docs/images/guides/feishu_step4_info.png b/docs/images/guides/feishu_step4_info.png new file mode 100644 index 0000000..26b9635 Binary files /dev/null and b/docs/images/guides/feishu_step4_info.png differ