[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-AlexAnys--openclaw-feishu":3,"tool-AlexAnys--openclaw-feishu":64},[4,17,27,35,43,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",140436,2,"2026-04-05T23:32:43",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[13,26],{"id":44,"name":45,"github_repo":46,"description_zh":47,"stars":48,"difficulty_score":23,"last_commit_at":49,"category_tags":50,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,51,52,53,15,54,26,13,55],"数据工具","视频","插件","其他","音频",{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,54],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":70,"readme_en":71,"readme_zh":72,"quickstart_zh":73,"use_case_zh":74,"hero_image_url":75,"owner_login":76,"owner_name":77,"owner_avatar_url":78,"owner_bio":79,"owner_company":79,"owner_location":79,"owner_email":79,"owner_twitter":79,"owner_website":80,"owner_url":81,"languages":82,"stars":91,"forks":92,"last_commit_at":93,"license":94,"difficulty_score":23,"env_os":95,"env_gpu":96,"env_ram":96,"env_deps":97,"category_tags":102,"github_topics":103,"view_count":23,"oss_zip_url":79,"oss_zip_packed_at":79,"status":16,"created_at":113,"updated_at":114,"faqs":115,"releases":146},2469,"AlexAnys\u002Fopenclaw-feishu","openclaw-feishu","飞书插件 × OpenClaw 保姆级配置指南 & 社区支持 （0328 - 更新飞书cli调用指南，增加 API 耗尽根因排查、Lark Webhook 内网穿透方案）","openclaw-feishu 是一个专为 OpenClaw（原 Clawdbot）用户打造的飞书接入指南与社区支持项目，旨在帮助国内用户低门槛地将 AI 智能体集成到飞书生态中。它不仅仅是一个简单的连接工具，更提供了一套经过本土化适配的完整解决方案，解决了用户在配置过程中遇到的环境差异、API 调用复杂以及缺乏中文最佳实践等痛点。\n\n该项目核心解决了“如何让 AI 真正融入日常工作流”的问题。通过整合飞书官方最新开源的 Lark CLI 和官方插件，openclaw-feishu 让 AI 能够以用户身份直接操作飞书文档、多维表格、日历日程及任务管理，实现了从“被动问答”到“主动执行”的跨越。同时，它也保留了 OpenClaw 内置插件方案，为仅需聊天入口的用户提供更轻量的选择。项目还附带了 39 个针对国内生态（如飞书、钉钉、企业微信）验证过的真实用例，填补了社区在本地化场景应用上的空白。\n\nopenclaw-feishu 非常适合希望提升工作效率的普通职场人士、开发者以及 AI 爱好者使用。对于非技术背景用户，其提供的“保姆级”配置指南和一键权限导入功能极大降低了上手难度；对于开","openclaw-feishu 是一个专为 OpenClaw（原 Clawdbot）用户打造的飞书接入指南与社区支持项目，旨在帮助国内用户低门槛地将 AI 智能体集成到飞书生态中。它不仅仅是一个简单的连接工具，更提供了一套经过本土化适配的完整解决方案，解决了用户在配置过程中遇到的环境差异、API 调用复杂以及缺乏中文最佳实践等痛点。\n\n该项目核心解决了“如何让 AI 真正融入日常工作流”的问题。通过整合飞书官方最新开源的 Lark CLI 和官方插件，openclaw-feishu 让 AI 能够以用户身份直接操作飞书文档、多维表格、日历日程及任务管理，实现了从“被动问答”到“主动执行”的跨越。同时，它也保留了 OpenClaw 内置插件方案，为仅需聊天入口的用户提供更轻量的选择。项目还附带了 39 个针对国内生态（如飞书、钉钉、企业微信）验证过的真实用例，填补了社区在本地化场景应用上的空白。\n\nopenclaw-feishu 非常适合希望提升工作效率的普通职场人士、开发者以及 AI 爱好者使用。对于非技术背景用户，其提供的“保姆级”配置指南和一键权限导入功能极大降低了上手难度；对于开发者，项目中包含的 API 耗尽排查、内网穿透方案及 Lark CLI 深度集成指南，则为构建更复杂的自动化工作流提供了坚实的技术支撑。无论你是想打造一个个人数字分身，还是探索多 Agent 协作团队，openclaw-feishu 都是连接 OpenClaw 与飞书的高效桥梁。","# feishu-openclaw\n\n飞书 × OpenClaw 保姆级配置指南 & 社区支持\n**让每个人都能用飞书轻松接入 OpenClaw（原 Clawdbot）。**\n\n---\n\n### 📚 [awesome-openclaw-usecases-zh](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fawesome-openclaw-usecases-zh) — 装好了 OpenClaw，然后呢？\n>\n> Skills 装了一堆，教程收藏了一堆，工具越来越多——但最缺的不是能力，而是**经过国内适配和验证的场景**。\n>\n> 39 个真实用例，含飞书、钉钉、企业微信、小红书等**国内生态适配方案**，每个都有完整步骤和可复制的提示词。\n>\n> **[查看中文最佳用例合集 →](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fawesome-openclaw-usecases-zh)**\n\n---\n\n## 🆕 飞书官方开源 Lark CLI（2026.3.28）\n\n飞书官方开源了 [Lark CLI](https:\u002F\u002Fgithub.com\u002Flarksuite\u002Fcli)（MIT 协议）——让你的 AI Agent 直接操作飞书：搜文档、读妙记、查日历、发消息、操作多维表格…… **2500+ API，11 个业务领域，19 个 AI Agent Skills**。\n\n安装只需要告诉你的 Agent 一句话，你只需要点一个授权链接。\n\n👉 **[Lark CLI 上手指南](docs\u002Flark-cli-guide.md)**\n\n---\n\n## 📢 飞书官方插件上线（2026.3.6）\n\n飞书团队正式推出了 OpenClaw 飞书官方插件。目前飞书接入 OpenClaw 共有三种插件方式：\n\n- **(a) 飞书官方插件** — 飞书团队开发维护，支持以用户身份操作文档、日历、任务等\n- **(b) OpenClaw 内置飞书插件** — OpenClaw 社区维护（`@openclaw\u002Ffeishu`），OpenClaw ≥ 2026.2 已内置\n- **(c) 本项目插件** — 本仓库早期开发的社区飞书插件（已停止更新，推荐迁移到 a 或 b）\n\n**👉 想了解飞书官方和 OpenClaw 内置插件的区别？** 看 [两个插件怎么选](#-飞书官方-vs-openclaw-内置怎么选)\n\n**👉 本项目插件的老用户？** 看 [如何迁移到飞书官方或 OpenClaw 内置插件](#-从旧版迁移)\n\n---\n\n## 📋 目录\n\n- [🆕 Lark CLI（飞书官方开源 CLI）](#-飞书官方开源-lark-cli2026328)\n- [飞书官方插件（安装指南）](#-飞书官方插件)\n- [飞书官方 vs OpenClaw 内置：怎么选？](#-飞书官方-vs-openclaw-内置怎么选)\n- [OpenClaw 内置插件教程（从零配置）](#-openclaw-内置插件教程从零配置)\n- [从旧版迁移](#-从旧版迁移)\n- [常见问题 & 排查清单](#-常见问题--排查清单)（含 [API 配额耗尽](#api-配额被耗尽没怎么用却超限了) 排查）\n- [进阶配置参考](#-进阶配置参考)\n- [Lark（国际版）接入指南](#-lark国际版接入指南)\n- [更新日志](#-更新日志)\n- [致社区](#致社区)\n- [链接](#-链接)\n\n---\n\n> ### 🚀 [OpenCrew](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopencrew) — 把你的 OpenClaw 变成一支 AI 团队\n>\n> 多个 Agent 各管各的领域，Slack 频道=岗位，经验自动沉淀。\n>\n> 3 个 Agent 起步 · 10 分钟部署 · 不用写代码\n>\n> **[查看 GitHub →](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopencrew)**\n\n---\n\n## 🆕 飞书官方插件\n\n飞书团队推出的 OpenClaw 官方插件，最大的不同是：**以你的身份操作飞书**（通过 OAuth 授权）。\n\n这意味着 AI 不只是\"聊天机器人\"，而是能直接帮你写文档、建多维表格、约日程、管理任务——就像一个能操作飞书的数字分身。\n\n**👉 [查看飞书官方插件安装指南](docs\u002Ffeishu-official-plugin.md)**\n\n> ⚠️ **OpenClaw 3.x 用户**：官方安装工具 `feishu-plugin-onboard` 有版本检查 bug（[#59](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues\u002F59)），会误报版本过低。安装指南中已提供替代方式，直接 `openclaw plugins install @larksuiteoapi\u002Ffeishu-openclaw-plugin` 即可绕过。\n\n> 📖 飞书团队的完整图文教程：[OpenClaw 飞书官方插件上线 | 一文讲清功能、安装更新教程与常见问题](https:\u002F\u002Fwww.feishu.cn\u002Fcontent\u002Farticle\u002F7613711414611463386)\n\n---\n\n## 📊 飞书官方 vs OpenClaw 内置：怎么选？\n\n两个插件**不能同时使用**（安装官方插件时会自动禁用内置插件）。\n\n| 维度 | 飞书官方插件 | OpenClaw 内置插件 |\n|---|---|---|\n| **操作身份** | 以**你本人**身份（OAuth） | 以**机器人**身份 |\n| **消息** | 读取、发送、回复、搜索 | 读取、发送、回复 |\n| **文档** | 创建 + 编辑 + 读取 | 读取为主 |\n| **多维表格** | 完整操作（表、字段、记录、视图） | 基础读写 |\n| **日历日程** | ✅ 创建\u002F查询\u002F修改\u002F搜索\u002F忙闲查询 | ❌ |\n| **任务管理** | ✅ 创建\u002F查询\u002F更新\u002F完成\u002F子任务 | ❌ |\n| **知识库** | ✅ 完整读写 | ✅ 只读 |\n| **云盘** | ✅ 上传\u002F下载 | ✅ 基础操作 |\n| **流式输出** | ✅ | ✅ |\n| **安装复杂度** | 需要额外安装 CLI 工具 + OAuth 授权 | OpenClaw 内置，`openclaw channels add` 即可 |\n| **维护方** | 飞书团队 | OpenClaw 社区 |\n| **问题反馈** | 飞书反馈群 | 本项目 Issues \u002F Discord |\n\n### 选择建议\n\n**选飞书官方插件，如果你：**\n- 想让 AI 帮你操作飞书（写文档、建表、约会议）\n- 需要日历、任务管理等高级功能\n- 想要以自己身份发消息（不是机器人名义）\n\n**选 OpenClaw 内置插件，如果你：**\n- 主要用飞书做聊天入口，让 AI 回答问题、执行本地任务\n- 不需要 AI 操作飞书文档\u002F日历\u002F任务\n- 偏好更简单的安装流程（内置即用）\n\n> ⚠️ **两种插件互斥，只能启用一个。** 安装飞书官方插件时会自动禁用内置插件，反之亦然。如果两个都装了，会出现 `duplicate plugin id` 报错导致飞书功能不可用。遇到这种情况：\n> ```bash\n> # 删除用户目录下的重复插件\n> rm -rf ~\u002F.openclaw\u002Fextensions\u002Ffeishu\n> openclaw gateway restart\n> ```\n> 如果想从内置切换到官方插件，见 [从 OpenClaw 内置插件迁移到飞书官方插件](#从-openclaw-内置插件迁移到飞书官方插件)。\n\n---\n\n## 🚀 OpenClaw 内置插件教程（从零配置）\n\n> 适用于：第一次使用 OpenClaw + 飞书的新用户，选择 OpenClaw 内置插件方案。\n> 前提：已安装 OpenClaw 并正常运行（`openclaw gateway status` 能看到状态）。\n> 预计耗时：15–20 分钟。\n\n### 第一步：创建飞书应用（机器人）\n\n1. 打开 [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp)，用飞书账号登录\n2. 点击 **创建企业自建应用**\n3. 填写应用名称（随意，比如 \"我的 AI 助手\"）和描述\n4. 选一个图标（可以之后改）\n\n### 第二步：启用机器人能力\n\n进入你刚创建的应用：\n\n1. 左侧菜单找到 **应用能力** > **机器人**\n2. **开启**机器人能力\n3. 给机器人起个名字\n\n### 第三步：配置权限\n\n1. 左侧菜单进入 **权限管理**\n2. 点击 **批量导入**\n3. 粘贴以下 JSON（一键导入所有需要的权限）：\n\n```json\n{\n  \"scopes\": {\n    \"tenant\": [\n      \"aily:file:read\",\n      \"aily:file:write\",\n      \"application:application.app_message_stats.overview:readonly\",\n      \"application:application:self_manage\",\n      \"application:bot.menu:write\",\n      \"cardkit:card:write\",\n      \"contact:user.employee_id:readonly\",\n      \"corehr:file:download\",\n      \"docs:document.content:read\",\n      \"event:ip_list\",\n      \"im:chat\",\n      \"im:chat.access_event.bot_p2p_chat:read\",\n      \"im:chat.members:bot_access\",\n      \"im:message\",\n      \"im:message.group_at_msg:readonly\",\n      \"im:message.group_msg\",\n      \"im:message.p2p_msg:readonly\",\n      \"im:message:readonly\",\n      \"im:message:send_as_bot\",\n      \"im:resource\",\n      \"sheets:spreadsheet\",\n      \"wiki:wiki:readonly\"\n    ],\n    \"user\": [\n      \"aily:file:read\",\n      \"aily:file:write\",\n      \"im:chat.access_event.bot_p2p_chat:read\"\n    ]\n  }\n}\n```\n\n### 第四步：配置事件订阅\n\n> ⚠️ 这一步**必须在 OpenClaw 网关启动后**再做，否则保存会失败。\n> 先做第五、六步，回来再做这一步也可以。\n\n1. 左侧菜单进入 **事件与回调** > **事件配置**\n2. 请求方式选择：**使用长连接接收事件**（这是关键！不需要公网服务器）\n3. 添加事件：搜索 `im.message.receive_v1`（接收消息），勾选添加\n\n### 第五步：记下凭证\n\n在应用的 **凭证与基础信息** 页面，复制：\n\n- **App ID**（格式如 `cli_xxxxxxxxx`）\n- **App Secret**\n\n> ❗ App Secret 很重要，请妥善保管，不要分享。\n\n### 第六步：发布应用\n\n1. 左侧菜单 **版本管理与发布**\n2. **创建版本** → 填写版本说明 → 提交\n3. 等待审批（企业内部应用通常自动通过，几秒到几分钟）\n\n### 第七步：在 OpenClaw 中配置飞书\n\n> OpenClaw ≥ 2026.2 已内置飞书插件，**不需要额外安装**，直接配置即可。\n>\n> 💡 如果你在首次 `openclaw setup` 时看到 \"Install Feishu plugin?\"，选择 **\"Download from npm\"** 即可进入配置流程。选了 \"Skip\" 也没关系，用下面的命令随时添加。\n\n打开 **终端（Terminal）**：\n\n```bash\n# 1. 添加飞书渠道（交互式，跟着提示走）\nopenclaw channels add\n# 选择 Feishu → 粘贴 App ID → 粘贴 App Secret\n\n# 2. 重启网关\nopenclaw gateway restart\n\n# 3. 查看日志，确认连接成功\nopenclaw logs --follow\n```\n\n### 第八步：发消息测试\n\n1. 在飞书里搜索你的机器人名字，打开对话\n2. 发一条消息，比如\"你好\"\n3. 如果机器人回复了**配对码**，在终端运行：\n\n```bash\nopenclaw pairing approve feishu \u003C配对码>\n```\n\n4. 授权后再发一条消息，收到正常回复 = 配置完成 🎉\n\n> **回来补第四步**：如果你先跳过了事件订阅，现在网关已启动，回到飞书开放平台把第四步做完，保存后重启网关（`openclaw gateway restart`）。\n\n### 第九步（可选）：让机器人开机自启\n\n```bash\nopenclaw gateway install\n```\n\n这样电脑重启后机器人也会自动上线。\n\n---\n\n## 🔄 从旧版迁移\n\n> 适用于：之前使用本项目（独立桥接或 npm 插件）的老用户。\n> 两种方式任选其一，效果一样。\n\n### 迁移前须知\n\n- ✅ 你之前创建的飞书应用（机器人）**可以继续用**，不需要重新创建\n- ✅ App ID 和 App Secret 不变\n- ✅ 迁移后聊天记录不受影响（记录在飞书端）\n- ⚠️ 迁移过程中机器人会短暂离线（几分钟）\n\n---\n\n### 方式一：通过 OpenClaw 升级（推荐，最省事）\n\n如果你的 OpenClaw 版本 ≥ 2026.2，升级后官方飞书插件已经内置，只需要：\n\n#### 1. 升级 OpenClaw\n\n```bash\nopenclaw update\n```\n\n升级完成后会自动重启网关。\n\n#### 2. 添加飞书渠道\n\n```bash\nopenclaw channels add\n```\n\n选择 **Feishu** → 粘贴你的 **App ID** → 粘贴你的 **App Secret**。\n\n> App ID 和 App Secret 在哪？之前可能保存在 `~\u002F.clawdbot\u002Fsecrets\u002Ffeishu_app_secret`，可以 `cat` 查看。\n> 如果找不到，去 [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp) → 你的应用 → **凭证与基础信息** 重新复制。\n\n#### 3. 补全飞书应用权限\n\n官方插件支持图片、文件、流式输出等更多功能，需要在飞书开放平台补几个权限：\n\n1. 打开 [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp) → 进入你的应用\n2. 进入 **权限管理** → 点击 **批量导入**\n3. 粘贴以下内容一键导入：\n\n```json\n{\n  \"scopes\": {\n    \"tenant\": [\n      \"aily:file:read\",\n      \"aily:file:write\",\n      \"application:application.app_message_stats.overview:readonly\",\n      \"application:application:self_manage\",\n      \"application:bot.menu:write\",\n      \"cardkit:card:write\",\n      \"contact:user.employee_id:readonly\",\n      \"corehr:file:download\",\n      \"docs:document.content:read\",\n      \"event:ip_list\",\n      \"im:chat\",\n      \"im:chat.access_event.bot_p2p_chat:read\",\n      \"im:chat.members:bot_access\",\n      \"im:message\",\n      \"im:message.group_at_msg:readonly\",\n      \"im:message.group_msg\",\n      \"im:message.p2p_msg:readonly\",\n      \"im:message:readonly\",\n      \"im:message:send_as_bot\",\n      \"im:resource\",\n      \"sheets:spreadsheet\",\n      \"wiki:wiki:readonly\"\n    ],\n    \"user\": [\n      \"aily:file:read\",\n      \"aily:file:write\",\n      \"im:chat.access_event.bot_p2p_chat:read\"\n    ]\n  }\n}\n```\n\n> 已有的权限会自动跳过，不会重复添加。\n\n4. 导入后 → **创建新版本** → **发布**（让新权限生效）\n\n#### 4. 清理旧插件\u002F桥接\n\n```bash\n# 移除旧的 npm 插件（如果装过）\nopenclaw plugins remove feishu-openclaw 2>\u002Fdev\u002Fnull\n\n# 停掉旧的桥接服务（如果用过独立桥接）\nlaunchctl unload ~\u002FLibrary\u002FLaunchAgents\u002Fcom.clawdbot.feishu-bridge.plist 2>\u002Fdev\u002Fnull\n\n# 重启网关\nopenclaw gateway restart\n```\n\n然后跳到下方 [验证](#验证) 确认一切正常。\n\n---\n\n### 方式二：不升级 OpenClaw，只加飞书\n\n适用于不想整体升级 OpenClaw、只想加飞书的情况。\n\n> **注意**：OpenClaw ≥ 2026.2 已内置飞书插件，**不需要** `openclaw plugins install`。直接配置即可。\n\n#### 1. 准备好你的飞书凭证\n\n- **App ID**：格式如 `cli_xxxxxxxxx`\n- **App Secret**\n\n> 之前可能保存在 `~\u002F.clawdbot\u002Fsecrets\u002Ffeishu_app_secret`，可以 `cat` 查看。\n> 如果找不到，去 [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp) → 你的应用 → **凭证与基础信息** 重新复制。\n\n#### 2. 补全飞书应用权限\n\n（同方式一的第 3 步，权限 JSON 一样，这里不重复粘贴——往上翻到方式一的权限 JSON 复制即可。）\n\n1. [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp) → 你的应用 → **权限管理** → **批量导入** → 粘贴上方 JSON\n2. 导入后 → **创建新版本** → **发布**\n\n#### 3. 配置飞书渠道\n\n```bash\n# 添加飞书渠道（交互式引导）\nopenclaw channels add\n#    → 选择 Feishu\n#    → 粘贴 App ID\n#    → 粘贴 App Secret\n\n# 移除旧的 npm 插件（如果装过）\nopenclaw plugins remove feishu-openclaw 2>\u002Fdev\u002Fnull\n\n# 停掉旧的桥接服务（如果用过独立桥接）\nlaunchctl unload ~\u002FLibrary\u002FLaunchAgents\u002Fcom.clawdbot.feishu-bridge.plist 2>\u002Fdev\u002Fnull\n\n# 重启网关\nopenclaw gateway restart\n```\n\n---\n\n### 验证\n\n```bash\n# 查看日志，确认飞书连接成功\nopenclaw logs --follow\n```\n\n日志中看到类似 `feishu ws connected` 或 `feishu provider ready` 就说明连上了。\n\n在飞书里给机器人发一条消息，正常收到回复 = 迁移完成 🎉\n\n> **配对授权**：如果机器人回复了一个配对码，在终端运行：\n> ```bash\n> openclaw pairing approve feishu \u003C配对码>\n> ```\n> 授权后就能正常对话了。这是一次性操作。\n\n### 迁移后清理（可选）\n\n稳定运行几天后，可以清理旧文件：\n\n```bash\n# 删除旧的 launchd 配置（桥接用户）\nrm -f ~\u002FLibrary\u002FLaunchAgents\u002Fcom.clawdbot.feishu-bridge.plist\n\n# 旧的桥接项目文件夹可以归档或删除\n# （建议先保留一段时间，确认没问题再删）\n```\n\n### 从 OpenClaw 内置插件迁移到飞书官方插件\n\n如果你正在使用 OpenClaw 内置插件，想切换到飞书官方插件：\n\n1. 按照 [飞书官方插件安装指南](docs\u002Ffeishu-official-plugin.md) 执行安装\n2. 安装过程中会**自动禁用** OpenClaw 内置飞书插件\n3. 完成 OAuth 授权后即可使用\n\n> 如果想切回内置插件：卸载官方插件后重启网关，内置插件会自动恢复。\n\n---\n\n## 🔧 常见问题 & 排查清单\n\n> 遇到问题先看这里。如果没找到答案，欢迎开 [Issue](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues)。\n\n### 没有消息发送框？（最常见）\n\n这是因为**事件订阅没有配置**。JSON 批量导入权限不会自动配置事件订阅，需要手动添加：\n\n1. 飞书开放平台 → 你的应用 → **事件与回调**\n2. 添加事件：`im.message.receive_v1`（接收消息 v2.0）\n3. 订阅方式：选择 **「使用长连接接收事件」**\n4. **版本管理** → 创建新版本 → 发布上线\n\n> ⚠️ 配置事件订阅前，确保 OpenClaw Gateway 已启动，否则长连接验证会失败。\n\n### 机器人完全没反应（收不到消息）\n\n按顺序检查：\n\n1. **网关在运行吗？**\n   ```bash\n   openclaw gateway status\n   ```\n   如果没运行：`openclaw gateway restart`\n\n2. **飞书应用发布了吗？**\n   去飞书开放平台 → 你的应用 → 版本管理，确认有已发布的版本\n\n3. **事件订阅配置了吗？**\n   - 是否选了 **\"使用长连接接收事件\"**（不是 Webhook）\n   - 是否添加了事件 `im.message.receive_v1`\n\n4. **权限够吗？**\n   至少需要：`im:message`、`im:message.p2p_msg:readonly`、`im:message:send_as_bot`\n\n5. **看日志**：\n   ```bash\n   openclaw logs --follow\n   ```\n   发一条消息，看日志有没有反应\n\n### 时断时续（有时能回复，有时没反应）\n\n常见原因：\n\n- **网络波动**：飞书 WebSocket 断开后通常会自动重连，但如果你的网络不稳定（尤其是 VPN\u002F代理环境），可能频繁断连\n- **网关重启**：检查是否有什么在反复触发网关重启\n  ```bash\n  openclaw logs | grep -i \"restart\\|reconnect\\|disconnect\"\n  ```\n- **DNS 问题**：如果你在国内使用代理，确保 `open.feishu.cn` 走直连（不走代理）\n\n### 开了代理（Clash \u002F V2Ray）后连不上？\n\n日志报 `400 The plain HTTP request was sent to HTTPS port`，token 和 WebSocket 都失败。\n\n**原因**：Axios 自动读取 `HTTP_PROXY` \u002F `HTTPS_PROXY` 环境变量，将飞书请求以明文 HTTP 发到 443 端口，被服务端拒绝。\n\n**解决**：通过 `NO_PROXY` 环境变量排除飞书域名，或在代理规则中将 `feishu.cn` 设为直连。\n\n### 发图片 \u002F 发文件，AI 看不到\n\n1. **检查权限**：必须有 `im:resource` 权限\n2. 在飞书开放平台补权限后，记得 **创建新版本 → 发布**\n3. 重启网关：`openclaw gateway restart`\n\n### AI 说生成了图片，但飞书没收到\n\n1. 确认有 `im:resource` 权限（用于上传图片到飞书）\n2. 检查日志中有没有 upload 相关的错误\n\n### 群聊中机器人不回复\n\n1. 默认需要 **@机器人** 才会回复\n2. 确认机器人已被添加到群聊\n3. 检查 `groupPolicy` 配置（见[进阶配置](#群组配置)）\n\n### 回复特别慢\n\n- 这通常是 AI 模型的响应速度决定的，和飞书插件关系不大\n- 可以开启**流式输出**（默认已开启），让回复逐步显示而不是等全部生成后一次发送\n- 如果超过 30 秒无回复，检查日志看是不是模型调用出错\n\n### \"Unknown model\" 错误\n\n- 通常发生在模型配置变更后，重启网关即可：\n  ```bash\n  openclaw gateway restart\n  ```\n\n### 配对码是什么？怎么用？\n\n首次和机器人对话时，出于安全考虑，机器人会回复一个配对码（一串字母数字）。你需要在终端\"批准\"这个配对：\n\n```bash\nopenclaw pairing approve feishu \u003C配对码>\n```\n\n批准后这个飞书用户就可以正常和机器人对话了。这是一次性操作。\n\n### 首次 setup 提示 \"Install Feishu plugin?\"\n\n这是正常的。OpenClaw 已内置飞书插件，但向导默认需要你确认启用。选择 **\"Download from npm\"** 即可，之后会直接进入 App ID \u002F App Secret 的配置步骤。\n\n如果选了 \"Skip for now\"，可以随时通过 `openclaw channels add` 手动添加飞书渠道。\n\n### 提示 \"duplicate plugin id detected\"\n\n这说明飞书插件同时存在于两个位置：OpenClaw 内置目录（stock extension）和用户目录（`~\u002F.openclaw\u002Fextensions\u002Ffeishu\u002F`）。\n\n**原因**：OpenClaw ≥ 2026.2 已内置飞书插件，如果又手动执行了 `openclaw plugins install @openclaw\u002Ffeishu`，就会产生重复。\n\n**解决**：删除用户目录下的副本，保留内置版本即可：\n\n```bash\nrm -rf ~\u002F.openclaw\u002Fextensions\u002Ffeishu\nopenclaw gateway restart\n```\n\n### API 配额被耗尽（没怎么用却超限了）\n\n**现象**：飞书开放平台显示 API 月度调用量（免费 50,000 次）耗尽，但你几乎没有主动使用飞书机器人。\n\n**原因**：OpenClaw Gateway 每 60 秒对所有启用的 channel 执行一次健康探测。飞书插件的探测会调用 `bot\u002Fv3\u002Finfo` API，每次计入月度配额。单台机器每月消耗约 27,000 次；**两台机器共用同一个飞书 App 就会超限**。\n\n**影响范围**：仅消耗 API 配额，不影响消息收发。消息通过 WebSocket 长连接接收，与 health check 无关。\n\n**修复**（发给你的 AI 助手即可）：\n\n```\n我的飞书 API 月度配额被意外耗尽了。这是 OpenClaw health check 导致的已知问题（每 60 秒调用一次 bot\u002Fv3\u002Finfo API）。请帮我排查和修复：\n1. 运行 `openclaw channels status` 查看飞书是否启用\n2. 如果我不需要飞书对话功能，禁用它：`openclaw config set channels.feishu.enabled false && openclaw gateway restart`\n3. 如果有多台机器运行 OpenClaw，在不需要飞书的机器上禁用\n4. 如果需要保留飞书，确认只有一台机器启用（单台不会超限）\n```\n\n> 📖 详细背景和诊断步骤见 [docs\u002Fapi-quota-fix.md](docs\u002Fapi-quota-fix.md)\n\n### Lark（国际版）用户\n\nLark 后台不开放 WebSocket 长连接，需要用 **Webhook 模式**。详见 [Lark 接入指南](#-lark国际版接入指南)。\n\n---\n\n## 📚 进阶配置参考\n\n### 配置文件位置\n\n```\n~\u002F.openclaw\u002Fopenclaw.json\n```\n\n### 基础配置示例\n\n```json5\n{\n  channels: {\n    feishu: {\n      enabled: true,\n      dmPolicy: \"pairing\",\n      accounts: {\n        main: {\n          appId: \"cli_xxxxxxxxx\",\n          appSecret: \"你的AppSecret\",\n          botName: \"我的AI助手\",\n        },\n      },\n    },\n  },\n}\n```\n\n### 群组配置\n\n**默认行为**：所有群组允许，但必须 @机器人。\n\n**特定群组无需 @（直接回复所有消息）**：\n\n```json5\n{\n  channels: {\n    feishu: {\n      groups: {\n        oc_你的群组ID: { requireMention: false },\n      },\n    },\n  },\n}\n```\n\n**只允许特定用户在群组中使用**：\n\n```json5\n{\n  channels: {\n    feishu: {\n      groupPolicy: \"allowlist\",\n      groupAllowFrom: [\"ou_用户1\", \"ou_用户2\"],\n    },\n  },\n}\n```\n\n> 获取群组 ID（`oc_xxx`）\u002F 用户 ID（`ou_xxx`）：给机器人发消息后看日志 `openclaw logs --follow`。\n\n### 流式输出\n\n默认开启。机器人会边生成边更新消息，而不是等全部写完再发。\n\n```json5\n{\n  channels: {\n    feishu: {\n      streaming: true,       \u002F\u002F 流式卡片输出（默认 true）\n      blockStreaming: true,   \u002F\u002F 块级流式（默认 true）\n    },\n  },\n}\n```\n\n如需关闭（等完整回复后一次性发送）：设 `streaming: false`。\n\n### 多 Agent 路由\n\n一个飞书机器人可以对接多个不同的 AI Agent（比如不同的人聊不同的Agent）：\n\n```json5\n{\n  bindings: [\n    {\n      agentId: \"main\",\n      match: { channel: \"feishu\", peer: { kind: \"dm\", id: \"ou_用户A\" } },\n    },\n    {\n      agentId: \"另一个agent\",\n      match: { channel: \"feishu\", peer: { kind: \"group\", id: \"oc_某群组\" } },\n    },\n  ],\n}\n```\n\n### 访问控制策略\n\n| 策略 (`dmPolicy`) | 行为 |\n|---|---|\n| `\"pairing\"` | **默认**。新用户收到配对码，管理员批准后可对话 |\n| `\"allowlist\"` | 仅白名单用户可对话 |\n| `\"open\"` | 允许所有人对话 |\n| `\"disabled\"` | 禁止私聊 |\n\n### 常用命令速查\n\n| 命令 | 说明 |\n|---|---|\n| `openclaw gateway status` | 查看网关状态 |\n| `openclaw gateway restart` | 重启网关 |\n| `openclaw gateway install` | 安装为开机自启服务 |\n| `openclaw logs --follow` | 实时查看日志 |\n| `openclaw pairing list feishu` | 查看待授权配对 |\n| `openclaw pairing approve feishu \u003CCODE>` | 批准配对 |\n| `openclaw plugins list` | 查看已安装插件 |\n\n---\n\n## 🌏 Lark（国际版）接入指南\n\n> Lark 后台目前不开放 WebSocket 长连接能力，所以不能像飞书国内版那样\"零公网\"直连。\n> 需要改用 **Webhook 模式**：Lark 主动把消息推送到你提供的一个公网 URL。\n\n### 与飞书版的区别\n\n| | 飞书（国内版） | Lark（国际版） |\n|---|---|---|\n| 连接方式 | WebSocket 长连接 ✅ | **Webhook HTTP 回调** |\n| 需要公网？ | ❌ 不需要 | ✅ 需要（或用隧道） |\n| 开发者平台 | [open.feishu.cn](https:\u002F\u002Fopen.feishu.cn) | [open.larksuite.com](https:\u002F\u002Fopen.larksuite.com) |\n\n### 第一步：配置 OpenClaw\n\n在 `~\u002F.openclaw\u002Fopenclaw.json` 中配置飞书渠道：\n\n```json5\n{\n  channels: {\n    feishu: {\n      domain: \"lark\",\n      connectionMode: \"webhook\",\n      webhookPort: 3000,\n      webhookPath: \"\u002Ffeishu\u002Fevents\",\n      accounts: {\n        main: {\n          appId: \"cli_xxxxxxxxx\",\n          appSecret: \"你的AppSecret\"\n        }\n      }\n    }\n  }\n}\n```\n\n> 也可以把 `domain`、`connectionMode` 等字段放在 account 级别，这样可以一个 account 连飞书、另一个连 Lark。\n\n### 第二步：启动网关 + 暴露到公网\n\n> ⚠️ **必须先启动网关**，再去 Lark 后台填 URL。因为 Lark 填写 URL 时会立刻发验证请求，网关没启动就会验证失败。\n\n**先启动网关：**\n\n```bash\nopenclaw gateway restart\nopenclaw logs --follow\n```\n\n看到 `Webhook server listening on port 3000` 说明启动成功。按 `Ctrl+C` 退出日志（网关仍在后台运行）。\n\n**再暴露端口到公网。** 推荐 **Cloudflare Tunnel**（免费、稳定）：\n\n```bash\n# 安装 cloudflared（macOS）\nbrew install cloudflared\n\n# 一键暴露本地 3000 端口（临时，用于测试）\ncloudflared tunnel --url http:\u002F\u002Flocalhost:3000\n```\n\n运行后会得到一个公网 URL，类似：`https:\u002F\u002Fxxx-yyy-zzz.trycloudflare.com`\n\n**记下这个 URL，下一步要用。**\n\n> **与 VPN\u002F代理兼容性**：Cloudflare Tunnel 不创建虚拟网卡、不修改系统路由表，与 Clash Verge、V2Ray 等代理工具**完全兼容**，可以同时使用。\n\n如需固定域名（推荐正式使用时配置）：\n\n```bash\ncloudflared tunnel login\ncloudflared tunnel create feishu-bot\ncloudflared tunnel route dns feishu-bot feishu.yourdomain.com\ncloudflared tunnel run --url http:\u002F\u002Flocalhost:3000 feishu-bot\n```\n\n其他隧道方案也可以：\n- **ngrok**：`ngrok http 3000`（免费版 URL 会变）\n- **Tailscale Funnel**：如果你已在用 Tailscale，配置最简单\n\n### 第三步：配置 Lark 后台\n\n1. 打开 [Lark Developer Console](https:\u002F\u002Fopen.larksuite.com\u002Fapp)\n2. 创建应用、添加机器人能力（操作步骤同飞书版）\n3. 进入 **Event Subscriptions**：\n   - **Request URL** 填入上一步拿到的公网 URL + webhook 路径，例如：\n     `https:\u002F\u002Fxxx-yyy-zzz.trycloudflare.com\u002Ffeishu\u002Fevents`\n   - 点保存后 Lark 会立刻发验证请求，OpenClaw 自动通过（前提是网关和隧道都在运行）\n   - 如果验证失败：检查网关是否启动、隧道是否运行、URL 是否拼对\n4. 添加事件：`Receive messages - im.message.receive_v1`\n5. 权限配置同飞书版\n\n### 第四步：发消息测试\n\n在 Lark 里搜索你的机器人，发一条消息。查看日志确认收到：\n\n```bash\nopenclaw logs --follow\n```\n\n收到正常回复 = 配置完成。\n\n### 注意事项\n\n- Webhook 模式下，OpenClaw 网关必须持续运行且公网可访问\n- 如果使用临时隧道（`cloudflared tunnel --url`），每次重启 URL 会变，需要去 Lark 后台更新 Request URL\n- 建议正式使用时配置固定域名的 Cloudflare Tunnel\n- 飞书国内版也可以使用 webhook 模式（设 `connectionMode: \"webhook\"`），但没必要——WebSocket 模式更简单\n- 如果你在 Lark 后台开启了事件加密，需要在配置中额外添加 `encryptKey` 和 `verificationToken`（从 Lark 后台的 Encrypt Key \u002F Verification Token 处复制）\n\n---\n\n## 常见问题（快问快答）\n\n**Q: 需要服务器吗？**\n不需要。飞书用 WebSocket 长连接，你的电脑（Mac \u002F Windows \u002F Linux）直接连飞书云端，不需要公网 IP。\n\n**Q: 电脑关机了怎么办？**\n机器人会离线。开机后自动重连（如果配了开机自启）。要 24\u002F7 在线可以用一台常开的机器（Mac Mini、NAS、云服务器等）。\n\n**Q: 飞书免费版能用吗？**\n可以。自建应用和机器人功能对所有飞书版本开放。\n\n**Q: 能同时接 Telegram \u002F 微信等其他渠道吗？**\n可以。OpenClaw 原生支持多渠道，飞书只是其中之一，互不影响。\n\n**Q: 飞书官方插件和 OpenClaw 内置插件能同时用吗？**\n不能。安装飞书官方插件时会自动禁用 OpenClaw 内置插件。两者只能二选一。\n\n---\n\n## 📝 更新日志\n\n### 2026.03.30 — Lark CLI 上手指南\n\n- 🆕 飞书官方开源 [Lark CLI](https:\u002F\u002Fgithub.com\u002Flarksuite\u002Fcli)（MIT），一行命令调飞书 2500+ API\n- 📖 新增 [Lark CLI 保姆级上手指南](docs\u002Flark-cli-guide.md)——安装、配置、OAuth 授权、Agent 调用示例\n- 🔧 与插件\u002F桥接互补：插件管对话，CLI 管操作\n\n### 2026.03.07 — 飞书官方插件上线\n\n- 🆕 新增飞书官方插件介绍及对比\n- 📖 新增 [飞书官方插件安装指南](docs\u002Ffeishu-official-plugin.md)\n- 🔄 更新项目定位：从\"三方桥接→内置插件迁移\"到\"帮用户选对方案\"\n- 🗑️ 移除早期独立桥接模式文档（已停止维护）\n\n### 2026.03.02 — API 配额排查\n\n- 🔧 新增 API 配额耗尽问题的根因分析和修复指南\n\n### 2026.02.24 — Lark 支持 + Webhook 模式 (v0.4.0)\n\n- 🌏 新增 Lark（国际版）支持：`domain: \"lark\"` 配置\n- 🔗 新增 Webhook 连接模式：解决 Lark 无法使用 WebSocket 的问题\n- 📖 新增 Lark 接入指南：含 Cloudflare Tunnel 内网穿透教程\n- 🛡️ Lark 用户误配 WebSocket 时自动 fallback 到 Webhook 并提示\n- 🔧 端口冲突、graceful shutdown 等稳定性改进\n\n### 2026.02 — 定位转型\n\n本项目从独立桥接\u002F插件转型为 **飞书 × OpenClaw 配置指南 & 社区支持中心**。\n\nOpenClaw 已内置官方飞书插件（`@openclaw\u002Ffeishu`），本项目继续为社区提供：保姆级教程、迁移指南、常见问题答疑。\n\n### 2026.02.02 — 媒体功能大更新（桥接模式）\n\n- ✅ 飞书传图 → AI 能看图\n- ✅ 飞书传视频\u002F文件 → 桥接可接收下载\n- ✅ AI 生图 → 自动回传飞书\n- ✅ 列表格式修复\n- ✅ 本地文件发送白名单安全控制\n\n### 2025.2.1\n\n同步更新飞书插件，适配 OpenClaw。\n\n---\n\n## 致社区\n\n感谢大家一直以来的支持与信任 🙏\n\n本项目最初是为了让飞书用户能更方便地接入 AI 助手——从独立桥接、到 npm 插件，再到一路踩坑填坑，这些都是大家的反馈推着走过来的。\n\n现在，不仅 OpenClaw 内置了飞书插件（`@openclaw\u002Ffeishu`），飞书团队也推出了官方的 OpenClaw 插件（`feishu-openclaw-plugin`），还开源了 Lark CLI 让所有 Agent 框架都能操作飞书。**这是件好事**——说明飞书 + AI 这条路走通了，社区的需求被看到了。\n\n**本项目会继续为大家服务：**\n\n- 🎯 为非技术背景的伙伴提供**最友好的入门引导**\n- 📊 帮你理清不同方案的区别，选对适合自己的路径\n- 🔧 **常见问题答疑** & 排查清单——官方文档没覆盖到的坑，这里帮你踩\n- 🔄 为老用户提供**迁移指南**\n\n遇到问题随时开 Issue，我们一起解决。\n\n---\n\n## 🔗 链接\n\n- 📖 [飞书官方插件教程](https:\u002F\u002Fwww.feishu.cn\u002Fcontent\u002Farticle\u002F7613711414611463386)\n- 📖 [OpenClaw 官方文档](https:\u002F\u002Fdocs.openclaw.ai)\n- 💬 [OpenClaw 社区 Discord](https:\u002F\u002Fdiscord.com\u002Finvite\u002Fclawd)\n- 🐛 [本项目 Issues（提问 & 反馈）](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues)\n- 🔌 [GitHub: openclaw-feishu](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu)（本项目）\n\n---\n\n## 📈 Star History\n\n\u003Ca href=\"https:\u002F\u002Fstar-history.com\u002F#AlexAnys\u002Fopenclaw-feishu&Date\">\n \u003Cpicture>\n   \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAlexAnys_openclaw-feishu_readme_4ad858d89c99.png&theme=dark\" \u002F>\n   \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAlexAnys_openclaw-feishu_readme_4ad858d89c99.png\" \u002F>\n   \u003Cimg alt=\"Star History Chart\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAlexAnys_openclaw-feishu_readme_4ad858d89c99.png\" \u002F>\n \u003C\u002Fpicture>\n\u003C\u002Fa>\n\n## License\n\nMIT\n","# feishu-openclaw\n\n飞书 × OpenClaw 保姆级配置指南 & 社区支持  \n**让每个人都能用飞书轻松接入 OpenClaw（原 Clawdbot）。**\n\n---\n\n### 📚 [awesome-openclaw-usecases-zh](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fawesome-openclaw-usecases-zh) — 装好了 OpenClaw，然后呢？\n>\n> Skills 装了一堆，教程收藏了一堆，工具越来越多——但最缺的不是能力，而是**经过国内适配和验证的场景**。\n>\n> 39 个真实用例，含飞书、钉钉、企业微信、小红书等**国内生态适配方案**，每个都有完整步骤和可复制的提示词。\n>\n> **[查看中文最佳用例合集 →](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fawesome-openclaw-usecases-zh)**\n\n---\n\n## 🆕 飞书官方开源 Lark CLI（2026.3.28）\n\n飞书官方开源了 [Lark CLI](https:\u002F\u002Fgithub.com\u002Flarksuite\u002Fcli)（MIT 协议）——让你的 AI Agent 直接操作飞书：搜文档、读妙记、查日历、发消息、操作多维表格…… **2500+ API，11 个业务领域，19 个 AI Agent Skills**。\n\n安装只需要告诉你的 Agent 一句话，你只需要点一个授权链接。\n\n👉 **[Lark CLI 上手指南](docs\u002Flark-cli-guide.md)**\n\n---\n\n## 📢 飞书官方插件上线（2026.3.6）\n\n飞书团队正式推出了 OpenClaw 飞书官方插件。目前飞书接入 OpenClaw 共有三种插件方式：\n\n- **(a) 飞书官方插件** — 飞书团队开发维护，支持以用户身份操作文档、日历、任务等\n- **(b) OpenClaw 内置飞书插件** — OpenClaw 社区维护（`@openclaw\u002Ffeishu`），OpenClaw ≥ 2026.2 已内置\n- **(c) 本项目插件** — 本仓库早期开发的社区飞书插件（已停止更新，推荐迁移到 a 或 b）\n\n**👉 想了解飞书官方和 OpenClaw 内置插件的区别？** 看 [两个插件怎么选](#-飞书官方-vs-openclaw-内置怎么选)\n\n**👉 本项目插件的老用户？** 看 [如何迁移到飞书官方或 OpenClaw 内置插件](#-从旧版迁移)\n\n---\n\n## 📋 目录\n\n- [🆕 Lark CLI（飞书官方开源 CLI）](#-飞书官方开源-lark-cli2026328)\n- [飞书官方插件（安装指南）](#-飞书官方插件)\n- [飞书官方 vs OpenClaw 内置：怎么选？](#-飞书官方-vs-openclaw-内置怎么选)\n- [OpenClaw 内置插件教程（从零配置）](#-openclaw-内置插件教程从零配置)\n- [从旧版迁移](#-从旧版迁移)\n- [常见问题 & 排查清单](#-常见问题--排查清单)（含 [API 配额耗尽](#api-配额被耗尽没怎么用却超限了) 排查）\n- [进阶配置参考](#-进阶配置参考)\n- [Lark（国际版）接入指南](#-lark国际版接入指南)\n- [更新日志](#-更新日志)\n- [致社区](#致社区)\n- [链接](#-链接)\n\n---\n\n> ### 🚀 [OpenCrew](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopencrew) — 把你的 OpenClaw 变成一支 AI 团队\n>\n> 多个 Agent 各管各的领域，Slack 频道=岗位，经验自动沉淀。\n>\n> 3 个 Agent 起步 · 10 分钟部署 · 不用写代码\n>\n> **[查看 GitHub →](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopencrew)**\n\n---\n\n## 🆕 飞书官方插件\n\n飞书团队推出的 OpenClaw 官方插件，最大的不同是：**以你的身份操作飞书**（通过 OAuth 授权）。\n\n这意味着 AI 不只是\"聊天机器人\"，而是能直接帮你写文档、建多维表格、约日程、管理任务——就像一个能操作飞书的数字分身。\n\n**👉 [查看飞书官方插件安装指南](docs\u002Ffeishu-official-plugin.md)**\n\n> ⚠️ **OpenClaw 3.x 用户**：官方安装工具 `feishu-plugin-onboard` 有版本检查 bug（[#59](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues\u002F59)），会误报版本过低。安装指南中已提供替代方式，直接 `openclaw plugins install @larksuiteoapi\u002Ffeishu-openclaw-plugin` 即可绕过。\n\n> 📖 飞书团队的完整图文教程：[OpenClaw 飞书官方插件上线 | 一文讲清功能、安装更新教程与常见问题](https:\u002F\u002Fwww.feishu.cn\u002Fcontent\u002Farticle\u002F7613711414611463386)\n\n---\n\n## 📊 飞书官方 vs OpenClaw 内置：怎么选？\n\n两个插件**不能同时使用**（安装官方插件时会自动禁用内置插件）。\n\n| 维度 | 飞书官方插件 | OpenClaw 内置插件 |\n|---|---|---|\n| **操作身份** | 以**你本人**身份（OAuth） | 以**机器人**身份 |\n| **消息** | 读取、发送、回复、搜索 | 读取、发送、回复 |\n| **文档** | 创建 + 编辑 + 读取 | 读取为主 |\n| **多维表格** | 完整操作（表、字段、记录、视图） | 基础读写 |\n| **日历日程** | ✅ 创建\u002F查询\u002F修改\u002F搜索\u002F忙闲查询 | ❌ |\n| **任务管理** | ✅ 创建\u002F查询\u002F更新\u002F完成\u002F子任务 | ❌ |\n| **知识库** | ✅ 完整读写 | ✅ 只读 |\n| **云盘** | ✅ 上传\u002F下载 | ✅ 基础操作 |\n| **流式输出** | ✅ | ✅ |\n| **安装复杂度** | 需要额外安装 CLI 工具 + OAuth 授权 | OpenClaw 内置，`openclaw channels add` 即可 |\n| **维护方** | 飞书团队 | OpenClaw 社区 |\n| **问题反馈** | 飞书反馈群 | 本项目 Issues \u002F Discord |\n\n### 选择建议\n\n**选飞书官方插件，如果你：**\n- 想让 AI 帮你操作飞书（写文档、建表、约会议）\n- 需要日历、任务管理等高级功能\n- 想要以自己身份发消息（不是机器人名义）\n\n**选 OpenClaw 内置插件，如果你：**\n- 主要用飞书做聊天入口，让 AI 回答问题、执行本地任务\n- 不需要 AI 操作飞书文档\u002F日历\u002F任务\n- 偏好更简单的安装流程（内置即用）\n\n> ⚠️ **两种插件互斥，只能启用一个。** 安装飞书官方插件时会自动禁用内置插件，反之亦然。如果两个都装了，会出现 `duplicate plugin id` 报错导致飞书功能不可用。遇到这种情况：\n> ```bash\n> # 删除用户目录下的重复插件\n> rm -rf ~\u002F.openclaw\u002Fextensions\u002Ffeishu\n> openclaw gateway restart\n> ```\n> 如果想从内置切换到官方插件，见 [从 OpenClaw 内置插件迁移到飞书官方插件](#从-openclaw-内置插件迁移到飞书官方插件)。\n\n---\n\n## 🚀 OpenClaw 内置插件教程（从零配置）\n\n> 适用于：第一次使用 OpenClaw + 飞书的新用户，选择 OpenClaw 内置插件方案。\n> 前提：已安装 OpenClaw 并正常运行（`openclaw gateway status` 能看到状态）。\n> 预计耗时：15–20 分钟。\n\n### 第一步：创建飞书应用（机器人）\n\n1. 打开 [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp)，用飞书账号登录\n2. 点击 **创建企业自建应用**\n3. 填写应用名称（随意，比如 \"我的 AI 助手\"）和描述\n4. 选一个图标（可以之后改）\n\n### 第二步：启用机器人能力\n\n进入你刚创建的应用：\n\n1. 左侧菜单找到 **应用能力** > **机器人**\n2. **开启**机器人能力\n3. 给机器人起个名字\n\n### 第三步：配置权限\n\n1. 左侧菜单进入 **权限管理**\n2. 点击 **批量导入**\n3. 粘贴以下 JSON（一键导入所有需要的权限）：\n\n```json\n{\n  \"scopes\": {\n    \"tenant\": [\n      \"aily:file:read\",\n      \"aily:file:write\",\n      \"application:application.app_message_stats.overview:readonly\",\n      \"application:application:self_manage\",\n      \"application:bot.menu:write\",\n      \"cardkit:card:write\",\n      \"contact:user.employee_id:readonly\",\n      \"corehr:file:download\",\n      \"docs:document.content:read\",\n      \"event:ip_list\",\n      \"im:chat\",\n      \"im:chat.access_event.bot_p2p_chat:read\",\n      \"im:chat.members:bot_access\",\n      \"im:message\",\n      \"im:message.group_at_msg:readonly\",\n      \"im:message.group_msg\",\n      \"im:message.p2p_msg:readonly\",\n      \"im:message:readonly\",\n      \"im:message:send_as_bot\",\n      \"im:resource\",\n      \"sheets:spreadsheet\",\n      \"wiki:wiki:readonly\"\n    ],\n    \"user\": [\n      \"aily:file:read\",\n      \"aily:file:write\",\n      \"im:chat.access_event.bot_p2p_chat:read\"\n    ]\n  }\n}\n```\n\n### 第四步：配置事件订阅\n\n> ⚠️ 这一步**必须在 OpenClaw 网关启动后**再做，否则保存会失败。\n> 先做第五、六步，回来再做这一步也可以。\n\n1. 左侧菜单进入 **事件与回调** > **事件配置**\n2. 请求方式选择：**使用长连接接收事件**（这是关键！不需要公网服务器）\n3. 添加事件：搜索 `im.message.receive_v1`（接收消息），勾选添加\n\n### 第五步：记下凭证\n\n在应用的 **凭证与基础信息** 页面，复制：\n\n- **App ID**（格式如 `cli_xxxxxxxxx`）\n- **App Secret**\n\n> ❗ App Secret 很重要，请妥善保管，不要分享。\n\n### 第六步：发布应用\n\n1. 左侧菜单 **版本管理与发布**\n2. **创建版本** → 填写版本说明 → 提交\n3. 等待审批（企业内部应用通常自动通过，几秒到几分钟）\n\n### 第七步：在 OpenClaw 中配置飞书\n\n> OpenClaw ≥ 2026.2 已内置飞书插件，**不需要额外安装**，直接配置即可。\n>\n> 💡 如果你在首次 `openclaw setup` 时看到 \"Install Feishu plugin?\"，选择 **\"Download from npm\"** 即可进入配置流程。选了 \"Skip\" 也没关系，用下面的命令随时添加。\n\n打开 **终端（Terminal）**：\n\n```bash\n# 1. 添加飞书渠道（交互式，跟着提示走）\nopenclaw channels add\n# 选择 Feishu → 粘贴 App ID → 粘贴 App Secret\n\n# 2. 重启网关\nopenclaw gateway restart\n\n# 3. 查看日志，确认连接成功\nopenclaw logs --follow\n```\n\n### 第八步：发消息测试\n\n1. 在飞书里搜索你的机器人名字，打开对话\n2. 发一条消息，比如\"你好\"\n3. 如果机器人回复了**配对码**，在终端运行：\n\n```bash\nopenclaw pairing approve feishu \u003C配对码>\n```\n\n4. 授权后再发一条消息，收到正常回复 = 配置完成 🎉\n\n> **回来补第四步**：如果你先跳过了事件订阅，现在网关已启动，回到飞书开放平台把第四步做完，保存后重启网关（`openclaw gateway restart`）。\n\n### 第九步（可选）：让机器人开机自启\n\n```bash\nopenclaw gateway install\n```\n\n这样电脑重启后机器人也会自动上线。\n\n---\n\n## 🔄 从旧版迁移\n\n> 适用于：之前使用本项目（独立桥接或 npm 插件）的老用户。\n> 两种方式任选其一，效果一样。\n\n### 迁移前须知\n\n- ✅ 你之前创建的飞书应用（机器人）**可以继续用**，不需要重新创建\n- ✅ App ID 和 App Secret 不变\n- ✅ 迁移后聊天记录不受影响（记录在飞书端）\n- ⚠️ 迁移过程中机器人会短暂离线（几分钟）\n\n---\n\n### 方法一：通过 OpenClaw 升级（推荐，最省事）\n\n如果你的 OpenClaw 版本 ≥ 2026.2，升级后官方飞书插件已经内置，只需要：\n\n#### 1. 升级 OpenClaw\n\n```bash\nopenclaw update\n```\n\n升级完成后会自动重启网关。\n\n#### 2. 添加飞书渠道\n\n```bash\nopenclaw channels add\n```\n\n选择 **Feishu** → 粘贴你的 **App ID** → 粘贴你的 **App Secret**。\n\n> App ID 和 App Secret 在哪？之前可能保存在 `~\u002F.clawdbot\u002Fsecrets\u002Ffeishu_app_secret`，可以 `cat` 查看。\n> 如果找不到，去 [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp) → 你的应用 → **凭证与基础信息** 重新复制。\n\n#### 3. 补全飞书应用权限\n\n官方插件支持图片、文件、流式输出等更多功能，需要在飞书开放平台补几个权限：\n\n1. 打开 [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp) → 进入你的应用\n2. 进入 **权限管理** → 点击 **批量导入**\n3. 粘贴以下内容一键导入：\n\n```json\n{\n  \"scopes\": {\n    \"tenant\": [\n      \"aily:file:read\",\n      \"aily:file:write\",\n      \"application:application.app_message_stats.overview:readonly\",\n      \"application:application:self_manage\",\n      \"application:bot.menu:write\",\n      \"cardkit:card:write\",\n      \"contact:user.employee_id:readonly\",\n      \"corehr:file:download\",\n      \"docs:document.content:read\",\n      \"event:ip_list\",\n      \"im:chat\",\n      \"im:chat.access_event.bot_p2p_chat:read\",\n      \"im:chat.members:bot_access\",\n      \"im:message\",\n      \"im:message.group_at_msg:readonly\",\n      \"im:message.group_msg\",\n      \"im:message.p2p_msg:readonly\",\n      \"im:message:readonly\",\n      \"im:message:send_as_bot\",\n      \"im:resource\",\n      \"sheets:spreadsheet\",\n      \"wiki:wiki:readonly\"\n    ],\n    \"user\": [\n      \"aily:file:read\",\n      \"aily:file:write\",\n      \"im:chat.access_event.bot_p2p_chat:read\"\n    ]\n  }\n}\n```\n\n> 已有的权限会自动跳过，不会重复添加。\n\n4. 导入后 → **创建新版本** → **发布**（让新权限生效）\n\n#### 4. 清理旧插件\u002F桥接\n\n```bash\n# 移除旧的 npm 插件（如果装过）\nopenclaw plugins remove feishu-openclaw 2>\u002Fdev\u002Fnull\n\n# 停掉旧的桥接服务（如果用过独立桥接）\nlaunchctl unload ~\u002FLibrary\u002FLaunchAgents\u002Fcom.clawdbot.feishu-bridge.plist 2>\u002Fdev\u002Fnull\n\n# 重启网关\nopenclaw gateway restart\n```\n\n然后跳到下方 [验证](#验证) 确认一切正常。\n\n---\n\n### 方法二：不升级 OpenClaw，只加飞书\n\n适用于不想整体升级 OpenClaw、只想加飞书的情况。\n\n> **注意**：OpenClaw ≥ 2026.2 已内置飞书插件，**不需要** `openclaw plugins install`。直接配置即可。\n\n#### 1. 准备好你的飞书凭证\n\n- **App ID**：格式如 `cli_xxxxxxxxx`\n- **App Secret**\n\n> 之前可能保存在 `~\u002F.clawdbot\u002Fsecrets\u002Ffeishu_app_secret`，可以 `cat` 查看。\n> 如果找不到，去 [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp) → 你的应用 → **凭证与基础信息** 重新复制。\n\n#### 2. 补全飞书应用权限\n\n（同方式一的第 3 步，权限 JSON 一样，这里不重复粘贴——往上翻到方式一的权限 JSON 复制即可。）\n\n1. [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp) → 你的应用 → **权限管理** → **批量导入** → 粘贴上方 JSON\n2. 导入后 → **创建新版本** → **发布**\n\n#### 3. 配置飞书渠道\n\n```bash\n# 添加飞书渠道（交互式引导）\nopenclaw channels add\n#    → 选择 Feishu\n#    → 粘贴 App ID\n#    → 粘贴 App Secret\n\n# 移除旧的 npm 插件（如果装过）\nopenclaw plugins remove feishu-openclaw 2>\u002Fdev\u002Fnull\n\n# 停掉旧的桥接服务（如果用过独立桥接）\nlaunchctl unload ~\u002FLibrary\u002FLaunchAgents\u002Fcom.clawdbot.feishu-bridge.plist 2>\u002Fdev\u002Fnull\n\n# 重启网关\nopenclaw gateway restart\n```\n\n---\n\n### 验证\n\n```bash\n# 查看日志，确认飞书连接成功\nopenclaw logs --follow\n```\n\n日志中看到类似 `feishu ws connected` 或 `feishu provider ready` 就说明连上了。\n\n在飞书中给机器人发一条消息，正常收到回复 = 迁移完成 🎉\n\n> **配对授权**：如果机器人回复了一个配对码，在终端运行：\n> ```bash\n> openclaw pairing approve feishu \u003C配对码>\n> ```\n> 授权后就能正常对话了。这是一次性操作。\n\n### 迁移后清理（可选）\n\n稳定运行几天后，可以清理旧文件：\n\n```bash\n# 删除旧的 launchd 配置（桥接用户）\nrm -f ~\u002FLibrary\u002FLaunchAgents\u002Fcom.clawdbot.feishu-bridge.plist\n\n# 旧的桥接项目文件夹可以归档或删除\n# （建议先保留一段时间，确认没问题再删）\n```\n\n### 从 OpenClaw 内置插件迁移到飞书官方插件\n\n如果你正在使用 OpenClaw 内置插件，想切换到飞书官方插件：\n\n1. 按照 [飞书官方插件安装指南](docs\u002Ffeishu-official-plugin.md) 执行安装\n2. 安装过程中会**自动禁用** OpenClaw 内置飞书插件\n3. 完成 OAuth 授权后即可使用\n\n> 如果想切回内置插件：卸载官方插件后重启网关，内置插件会自动恢复。\n\n---\n\n## 🔧 常见问题 & 排查清单\n\n> 遇到问题先看这里。如果没找到答案，欢迎开 [Issue](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues)。\n\n### 没有消息发送框？（最常见）\n\n这是因为**事件订阅没有配置**。JSON 批量导入权限不会自动配置事件订阅，需要手动添加：\n\n1. 飞书开放平台 → 你的应用 → **事件与回调**\n2. 添加事件：`im.message.receive_v1`（接收消息 v2.0）\n3. 订阅方式：选择 **「使用长连接接收事件」**\n4. **版本管理** → 创建新版本 → 发布上线\n\n> ⚠️ 配置事件订阅前，确保 OpenClaw Gateway 已启动，否则长连接验证会失败。\n\n### 机器人完全没反应（收不到消息）\n\n按顺序检查：\n\n1. **网关在运行吗？**\n   ```bash\n   openclaw gateway status\n   ```\n   如果没运行：`openclaw gateway restart`\n\n2. **飞书应用发布了吗？**\n   去飞书开放平台 → 你的应用 → 版本管理，确认有已发布的版本\n\n3. **事件订阅配置了吗？**\n   - 是否选了 **\"使用长连接接收事件\"**（不是 Webhook）\n   - 是否添加了事件 `im.message.receive_v1`\n\n4. **权限够吗？**\n   至少需要：`im:message`、`im:message.p2p_msg:readonly`、`im:message:send_as_bot`\n\n5. **看日志**：\n   ```bash\n   openclaw logs --follow\n   ```\n   发一条消息，看日志有没有反应\n\n### 时断时续（有时能回复，有时没反应）\n\n常见原因：\n\n- **网络波动**：飞书 WebSocket 断开后通常会自动重连，但如果你的网络不稳定（尤其是 VPN\u002F代理环境），可能频繁断连\n- **网关重启**：检查是否有什么在反复触发网关重启\n  ```bash\n  openclaw logs | grep -i \"restart\\|reconnect\\|disconnect\"\n  ```\n- **DNS 问题**：如果你在国内使用代理，确保 `open.feishu.cn` 走直连（不走代理）\n\n### 开了代理（Clash \u002F V2Ray）后连不上？\n\n日志报 `400 The plain HTTP request was sent to HTTPS port`，token 和 WebSocket 都失败。\n\n**原因**：Axios 自动读取 `HTTP_PROXY` \u002F `HTTPS_PROXY` 环境变量，将飞书请求以明文 HTTP 发到 443 端口，被服务端拒绝。\n\n**解决**：通过 `NO_PROXY` 环境变量排除飞书域名，或在代理规则中将 `feishu.cn` 设为直连。\n\n### 发图片 \u002F 发文件，AI 看不到\n\n1. **检查权限**：必须有 `im:resource` 权限\n2. 在飞书开放平台补权限后，记得 **创建新版本 → 发布**\n3. 重启网关：`openclaw gateway restart`\n\n### AI 说生成了图片，但飞书没收到\n\n1. 确认有 `im:resource` 权限（用于上传图片到飞书）\n2. 检查日志中有没有 upload 相关的错误\n\n### 群聊中机器人不回复\n\n1. 默认需要 **@机器人** 才会回复\n2. 确认机器人已被添加到群聊\n3. 检查 `groupPolicy` 配置（见[进阶配置](#群组配置)）\n\n### 回复特别慢\n\n- 这通常是 AI 模型的响应速度决定的，和飞书插件关系不大\n- 可以开启**流式输出**（默认已开启），让回复逐步显示而不是等全部生成后一次发送\n- 如果超过 30 秒无回复，检查日志看是不是模型调用出错\n\n### \"Unknown model\" 错误\n\n- 通常发生在模型配置变更后，重启网关即可：\n  ```bash\n  openclaw gateway restart\n  ```\n\n### 配对码是什么？怎么用？\n\n首次和机器人对话时，出于安全考虑，机器人会回复一个配对码（一串字母数字）。你需要在终端\"批准\"这个配对：\n\n```bash\nopenclaw pairing approve feishu \u003C配对码>\n```\n\n批准后这个飞书用户就可以正常和机器人对话了。这是一次性操作。\n\n### 首次 setup 提示 \"Install Feishu plugin?\"\n\n这是正常的。OpenClaw 已内置飞书插件，但向导默认需要你确认启用。选择 **\"Download from npm\"** 即可，之后会直接进入 App ID \u002F App Secret 的配置步骤。\n\n如果选了 \"Skip for now\"，可以随时通过 `openclaw channels add` 手动添加飞书渠道。\n\n### 提示 \"duplicate plugin id detected\"\n\n这说明飞书插件同时存在于两个位置：OpenClaw 内置目录（stock extension）和用户目录（`~\u002F.openclaw\u002Fextensions\u002Ffeishu\u002F`）。\n\n**原因**：OpenClaw ≥ 2026.2 已内置飞书插件，如果又手动执行了 `openclaw plugins install @openclaw\u002Ffeishu`，就会产生重复。\n\n**解决**：删除用户目录下的副本，保留内置版本即可：\n\n```bash\nrm -rf ~\u002F.openclaw\u002Fextensions\u002Ffeishu\nopenclaw gateway restart\n```\n\n### API 配额被耗尽（没怎么用却超限了）\n\n**现象**：飞书开放平台显示 API 月度调用量（免费 50,000 次）耗尽，但你几乎没有主动使用飞书机器人。\n\n**原因**：OpenClaw Gateway 每 60 秒对所有启用的 channel 执行一次健康探测。飞书插件的探测会调用 `bot\u002Fv3\u002Finfo` API，每次计入月度配额。单台机器每月消耗约 27,000 次；**两台机器共用同一个飞书 App 就会超限**。\n\n**影响范围**：仅消耗 API 配额，不影响消息收发。消息通过 WebSocket 长连接接收，与 health check 无关。\n\n**修复**（发给你的 AI 助手即可）：\n\n```\n我的飞书 API 月度配额被意外耗尽了。这是 OpenClaw health check 导致的已知问题（每 60 秒调用一次 bot\u002Fv3\u002Finfo API）。请帮我排查和修复：\n1. 运行 `openclaw channels status` 查看飞书是否启用\n2. 如果我不需要飞书对话功能，禁用它：`openclaw config set channels.feishu.enabled false && openclaw gateway restart`\n3. 如果有多台机器运行 OpenClaw，在不需要飞书的机器上禁用\n4. 如果需要保留飞书，确认只有一台机器启用（单台不会超限）\n```\n\n> 📖 详细背景和诊断步骤见 [docs\u002Fapi-quota-fix.md](docs\u002Fapi-quota-fix.md)\n\n### Lark（国际版）用户\n\nLark 后台不开放 WebSocket 长连接，需要用 **Webhook 模式**。详见 [Lark 接入指南](#-lark国际版接入指南)。\n\n---\n\n## 📚 进阶配置参考\n\n### 配置文件位置\n\n```\n~\u002F.openclaw\u002Fopenclaw.json\n```\n\n### 基础配置示例\n\n```json5\n{\n  channels: {\n    feishu: {\n      enabled: true,\n      dmPolicy: \"pairing\",\n      accounts: {\n        main: {\n          appId: \"cli_xxxxxxxxx\",\n          appSecret: \"你的AppSecret\",\n          botName: \"我的AI助手\",\n        },\n      },\n    },\n  },\n}\n```\n\n### 群组配置\n\n**默认行为**：所有群组允许，但必须 @机器人。\n\n**特定群组无需 @（直接回复所有消息）**：\n\n```json5\n{\n  channels: {\n    feishu: {\n      groups: {\n        oc_你的群组ID: { requireMention: false },\n      },\n    },\n  },\n}\n```\n\n**只允许特定用户在群组中使用**：\n\n```json5\n{\n  channels: {\n    feishu: {\n      groupPolicy: \"allowlist\",\n      groupAllowFrom: [\"ou_用户1\", \"ou_用户2\"],\n    },\n  },\n}\n```\n\n> 获取群组 ID（`oc_xxx`）\u002F 用户 ID（`ou_xxx`）：给机器人发消息后看日志 `openclaw logs --follow`。\n\n### 流式输出\n\n默认开启。机器人会边生成边更新消息，而不是等全部写完再发。\n\n```json5\n{\n  channels: {\n    feishu: {\n      streaming: true,       \u002F\u002F 流式卡片输出（默认 true）\n      blockStreaming: true,   \u002F\u002F 块级流式（默认 true）\n    },\n  },\n}\n```\n\n如需关闭（等完整回复后一次性发送）：设 `streaming: false`。\n\n### 多 Agent 路由\n\n一个飞书机器人可以对接多个不同的 AI Agent（比如不同的人聊不同的Agent）：\n\n```json5\n{\n  bindings: [\n    {\n      agentId: \"main\",\n      match: { channel: \"feishu\", peer: { kind: \"dm\", id: \"ou_用户A\" } },\n    },\n    {\n      agentId: \"另一个agent\",\n      match: { channel: \"feishu\", peer: { kind: \"group\", id: \"oc_某群组\" } },\n    },\n  ],\n}\n```\n\n### 访问控制策略\n\n| 策略 (`dmPolicy`) | 行为 |\n|---|---|\n| `\"pairing\"` | **默认**。新用户收到配对码，管理员批准后可对话 |\n| `\"allowlist\"` | 仅白名单用户可对话 |\n| `\"open\"` | 允许所有人对话 |\n| `\"disabled\"` | 禁止私聊 |\n\n### 常用命令速查\n\n| 命令 | 说明 |\n|---|---|\n| `openclaw gateway status` | 查看网关状态 |\n| `openclaw gateway restart` | 重启网关 |\n| `openclaw gateway install` | 安装为开机自启服务 |\n| `openclaw logs --follow` | 实时查看日志 |\n| `openclaw pairing list feishu` | 查看待授权配对 |\n| `openclaw pairing approve feishu \u003CCODE>` | 批准配对 |\n| `openclaw plugins list` | 查看已安装插件 |\n\n---\n\n## 🌏 Lark（国际版）接入指南\n\n> Lark 后台目前不开放 WebSocket 长连接能力，所以不能像飞书国内版那样\"零公网\"直连。\n> 需要改用 **Webhook 模式**：Lark 主动把消息推送到你提供的一个公网 URL。\n\n### 与飞书版的区别\n\n| | 飞书（国内版） | Lark（国际版） |\n|---|---|---|\n| 连接方式 | WebSocket 长连接 ✅ | **Webhook HTTP 回调** |\n| 需要公网？ | ❌ 不需要 | ✅ 需要（或用隧道） |\n| 开发者平台 | [open.feishu.cn](https:\u002F\u002Fopen.feishu.cn) | [open.larksuite.com](https:\u002F\u002Fopen.larksuite.com) |\n\n### 第一步：配置 OpenClaw\n\n在 `~\u002F.openclaw\u002Fopenclaw.json` 中配置飞书渠道：\n\n```json5\n{\n  channels: {\n    feishu: {\n      domain: \"lark\",\n      connectionMode: \"webhook\",\n      webhookPort: 3000,\n      webhookPath: \"\u002Ffeishu\u002Fevents\",\n      accounts: {\n        main: {\n          appId: \"cli_xxxxxxxxx\",\n          appSecret: \"你的AppSecret\"\n        }\n      }\n    }\n  }\n}\n```\n\n> 也可以把 `domain`、`connectionMode` 等字段放在 account 级别，这样可以一个 account 连飞书、另一个连 Lark。\n\n### 第二步：启动网关 + 暴露到公网\n\n> ⚠️ **必须先启动网关**，再去 Lark 后台填 URL。因为 Lark 填写 URL 时会立刻发验证请求，网关没启动就会验证失败。\n\n**先启动网关：**\n\n```bash\nopenclaw gateway restart\nopenclaw logs --follow\n```\n\n看到 `Webhook server listening on port 3000` 说明启动成功。按 `Ctrl+C` 退出日志（网关仍在后台运行）。\n\n**再暴露端口到公网。** 推荐 **Cloudflare Tunnel**（免费、稳定）：\n\n```bash\n# 安装 cloudflared（macOS）\nbrew install cloudflared\n\n# 一键暴露本地 3000 端口（临时，用于测试）\ncloudflared tunnel --url http:\u002F\u002Flocalhost:3000\n```\n\n运行后会得到一个公网 URL，类似：`https:\u002F\u002Fxxx-yyy-zzz.trycloudflare.com`\n\n**记下这个 URL，下一步要用。**\n\n> **与 VPN\u002F代理兼容性**：Cloudflare Tunnel 不创建虚拟网卡、不修改系统路由表，与 Clash Verge、V2Ray 等代理工具**完全兼容**，可以同时使用。\n\n如需固定域名（推荐正式使用时配置）：\n\n```bash\ncloudflared tunnel login\ncloudflared tunnel create feishu-bot\ncloudflared tunnel route dns feishu-bot feishu.yourdomain.com\ncloudflared tunnel run --url http:\u002F\u002Flocalhost:3000 feishu-bot\n```\n\n其他隧道方案也可以：\n- **ngrok**：`ngrok http 3000`（免费版 URL 会变）\n- **Tailscale Funnel**：如果你已在用 Tailscale，配置最简单\n\n### 第三步：配置 Lark 后台\n\n1. 打开 [Lark Developer Console](https:\u002F\u002Fopen.larksuite.com\u002Fapp)\n2. 创建应用、添加机器人能力（操作步骤同飞书版）\n3. 进入 **Event Subscriptions**：\n   - **Request URL** 填入上一步拿到的公网 URL + webhook 路径，例如：\n     `https:\u002F\u002Fxxx-yyy-zzz.trycloudflare.com\u002Ffeishu\u002Fevents`\n   - 点保存后 Lark 会立刻发验证请求，OpenClaw 自动通过（前提是网关和隧道都在运行）\n   - 如果验证失败：检查网关是否启动、隧道是否运行、URL 是否拼对\n4. 添加事件：`Receive messages - im.message.receive_v1`\n5. 权限配置同飞书版\n\n### 第四步：发消息测试\n\n在 Lark 里搜索你的机器人，发一条消息。查看日志确认收到：\n\n```bash\nopenclaw logs --follow\n```\n\n收到正常回复 = 配置完成。\n\n### 注意事项\n\n- Webhook 模式下，OpenClaw 网关必须持续运行且公网可访问\n- 如果使用临时隧道（`cloudflared tunnel --url`），每次重启 URL 会变，需要去 Lark 后台更新 Request URL\n- 建议正式使用时配置固定域名的 Cloudflare Tunnel\n- 飞书国内版也可以使用 webhook 模式（设 `connectionMode: \"webhook\"`），但没必要——WebSocket 模式更简单\n- 如果你在 Lark 后台开启了事件加密，需要在配置中额外添加 `encryptKey` 和 `verificationToken`（从 Lark 后台的 Encrypt Key \u002F Verification Token 处复制）\n\n---\n\n## 常见问题（快问快答）\n\n**Q: 需要服务器吗？**\n不需要。飞书用 WebSocket 长连接，你的电脑（Mac \u002F Windows \u002F Linux）直接连飞书云端，不需要公网 IP。\n\n**Q: 电脑关机了怎么办？**\n机器人会离线。开机后自动重连（如果配了开机自启）。要 24\u002F7 在线可以用一台常开的机器（Mac Mini、NAS、云服务器等）。\n\n**Q: 飞书免费版能用吗？**\n可以。自建应用和机器人功能对所有飞书版本开放。\n\n**Q: 能同时接 Telegram \u002F 微信等其他渠道吗？**\n可以。OpenClaw 原生支持多渠道，飞书只是其中之一，互不影响。\n\n**Q: 飞书官方插件和 OpenClaw 内置插件能同时用吗？**\n不能。安装飞书官方插件时会自动禁用 OpenClaw 内置插件。两者只能二选一。\n\n---\n\n## 📝 更新日志\n\n### 2026.03.30 — Lark CLI 上手指南\n\n- 🆕 飞书官方开源 [Lark CLI](https:\u002F\u002Fgithub.com\u002Flarksuite\u002Fcli)（MIT），一行命令调飞书 2500+ API\n- 📖 新增 [Lark CLI 保姆级上手指南](docs\u002Flark-cli-guide.md)——安装、配置、OAuth 授权、Agent 调用示例\n- 🔧 与插件\u002F桥接互补：插件管对话，CLI 管操作\n\n### 2026.03.07 — 飞书官方插件上线\n\n- 🆕 新增飞书官方插件介绍及对比\n- 📖 新增 [飞书官方插件安装指南](docs\u002Ffeishu-official-plugin.md)\n- 🔄 更新项目定位：从\"三方桥接→内置插件迁移\"到\"帮用户选对方案\"\n- 🗑️ 移除早期独立桥接模式文档（已停止维护）\n\n### 2026.03.02 — API 配额排查\n\n- 🔧 新增 API 配额耗尽问题的根因分析和修复指南\n\n### 2026.02.24 — Lark 支持 + Webhook 模式 (v0.4.0)\n\n- 🌏 新增 Lark（国际版）支持：`domain: \"lark\"` 配置\n- 🔗 新增 Webhook 连接模式：解决 Lark 无法使用 WebSocket 的问题\n- 📖 新增 Lark 接入指南：含 Cloudflare Tunnel 内网穿透教程\n- 🛡️ Lark 用户误配 WebSocket 时自动 fallback 到 Webhook 并提示\n- 🔧 端口冲突、graceful shutdown 等稳定性改进\n\n### 2026.02 — 定位转型\n\n本项目从独立桥接\u002F插件转型为 **飞书 × OpenClaw 配置指南 & 社区支持中心**。\n\nOpenClaw 已内置官方飞书插件（`@openclaw\u002Ffeishu`），本项目继续为社区提供：保姆级教程、迁移指南、常见问题答疑。\n\n### 2026.02.02 — 媒体功能大更新（桥接模式）\n\n- ✅ 飞书传图 → AI 能看图\n- ✅ 飞书传视频\u002F文件 → 桥接可接收下载\n- ✅ AI 生图 → 自动回传飞书\n- ✅ 列表格式修复\n- ✅ 本地文件发送白名单安全控制\n\n### 2025.2.1\n\n同步更新飞书插件，适配 OpenClaw。\n\n---\n\n## 致社区\n\n感谢大家一直以来的支持与信任 🙏\n\n本项目最初是为了让飞书用户能更方便地接入 AI 助手——从独立桥接、到 npm 插件，再到一路踩坑填坑，这些都是大家的反馈推着走过来的。\n\n现在，不仅 OpenClaw 内置了飞书插件（`@openclaw\u002Ffeishu`），飞书团队也推出了官方的 OpenClaw 插件（`feishu-openclaw-plugin`），还开源了 Lark CLI 让所有 Agent 框架都能操作飞书。**这是件好事**——说明飞书 + AI 这条路走通了，社区的需求被看到了。\n\n**本项目会继续为大家服务：**\n\n- 🎯 为非技术背景的伙伴提供**最友好的入门引导**\n- 📊 帮你理清不同方案的区别，选对适合自己的路径\n- 🔧 **常见问题答疑** & 排查清单——官方文档没覆盖到的坑，这里帮你踩\n- 🔄 为老用户提供**迁移指南**\n\n遇到问题随时开 Issue，我们一起解决。\n\n---\n\n## 🔗 链接\n\n- 📖 [飞书官方插件教程](https:\u002F\u002Fwww.feishu.cn\u002Fcontent\u002Farticle\u002F7613711414611463386)\n- 📖 [OpenClaw 官方文档](https:\u002F\u002Fdocs.openclaw.ai)\n- 💬 [OpenClaw 社区 Discord](https:\u002F\u002Fdiscord.com\u002Finvite\u002Fclawd)\n- 🐛 [本项目 Issues（提问 & 反馈）](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues)\n- 🔌 [GitHub: openclaw-feishu](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu)（本项目）\n\n---\n\n## 📈 Star History\n\n\u003Ca href=\"https:\u002F\u002Fstar-history.com\u002F#AlexAnys\u002Fopenclaw-feishu&Date\">\n \u003Cpicture>\n   \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAlexAnys_openclaw-feishu_readme_4ad858d89c99.png&theme=dark\" \u002F>\n   \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAlexAnys_openclaw-feishu_readme_4ad858d89c99.png\" \u002F>\n   \u003Cimg alt=\"Star History Chart\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAlexAnys_openclaw-feishu_readme_4ad858d89c99.png\" \u002F>\n \u003C\u002Fpicture>\n\u003C\u002Fa>\n\n## License\n\nMIT","# openclaw-feishu 快速上手指南\n\n本指南旨在帮助开发者快速将 OpenClaw 接入飞书（Feishu）。目前主要有两种接入方式：**OpenClaw 内置插件**（适合聊天机器人、轻量级交互）和 **飞书官方插件**（适合以用户身份操作文档、日历、任务等高级功能）。\n\n以下主要介绍配置最简便、适用于大多数场景的 **OpenClaw 内置插件** 方案。如需高级自动化能力，请参考[飞书官方插件安装指南](docs\u002Ffeishu-official-plugin.md)。\n\n## 1. 环境准备\n\n*   **系统要求**：支持 macOS、Linux 或 Windows（WSL2 推荐）。\n*   **前置依赖**：\n    *   已安装并正常运行 **OpenClaw** (版本 ≥ 2026.2)。\n    *   拥有一个飞书账号，并已登录 [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp)。\n*   **网络要求**：确保本地网络能正常访问 `open.feishu.cn`。若使用代理，请确保飞书域名走直连或正确配置 `NO_PROXY`。\n\n## 2. 安装与配置步骤\n\n### 第一步：创建飞书应用\n\n1.  登录 [飞书开放平台](https:\u002F\u002Fopen.feishu.cn\u002Fapp)，点击 **创建企业自建应用**。\n2.  填写应用名称（如 \"My AI Assistant\"）和描述，上传图标（可选）。\n3.  进入应用管理页面，在左侧菜单选择 **应用能力** > **机器人**，点击 **开启** 并设置机器人名称。\n\n### 第二步：配置权限\n\n1.  在左侧菜单进入 **权限管理**。\n2.  点击 **批量导入**，粘贴以下 JSON 内容以一键获取必要权限：\n\n```json\n{\n  \"scopes\": {\n    \"tenant\": [\n      \"aily:file:read\",\n      \"aily:file:write\",\n      \"application:application.app_message_stats.overview:readonly\",\n      \"application:application:self_manage\",\n      \"application:bot.menu:write\",\n      \"cardkit:card:write\",\n      \"contact:user.employee_id:readonly\",\n      \"corehr:file:download\",\n      \"docs:document.content:read\",\n      \"event:ip_list\",\n      \"im:chat\",\n      \"im:chat.access_event.bot_p2p_chat:read\",\n      \"im:chat.members:bot_access\",\n      \"im:message\",\n      \"im:message.group_at_msg:readonly\",\n      \"im:message.group_msg\",\n      \"im:message.p2p_msg:readonly\",\n      \"im:message:readonly\",\n      \"im:message:send_as_bot\",\n      \"im:resource\",\n      \"sheets:spreadsheet\",\n      \"wiki:wiki:readonly\"\n    ],\n    \"user\": [\n      \"aily:file:read\",\n      \"aily:file:write\",\n      \"im:chat.access_event.bot_p2p_chat:read\"\n    ]\n  }\n}\n```\n\n3.  导入成功后，前往 **版本管理与发布**，创建新版本并提交发布（企业内部应用通常自动秒级通过）。\n\n### 第三步：配置事件订阅\n\n> ⚠️ **注意**：此步骤需在 OpenClaw 网关启动后进行，否则长连接验证可能失败。建议先执行第四步启动网关，再回来完成此步。\n\n1.  在飞书开放平台左侧菜单进入 **事件与回调** > **事件配置**。\n2.  请求方式选择：**使用长连接接收事件**（关键步骤，无需公网 IP）。\n3.  点击 **添加事件**，搜索并勾选 `im.message.receive_v1`（接收消息）。\n4.  保存配置。\n\n### 第四步：获取凭证并接入 OpenClaw\n\n1.  在飞书开放平台 **凭证与基础信息** 页面，复制 **App ID** 和 **App Secret**。\n2.  打开终端，运行以下命令添加飞书渠道：\n\n```bash\n# 交互式添加渠道\nopenclaw channels add\n```\n\n3.  根据提示操作：\n    *   选择平台：**Feishu**\n    *   粘贴 **App ID**\n    *   粘贴 **App Secret**\n\n4.  重启网关以应用配置：\n\n```bash\nopenclaw gateway restart\n```\n\n5.  （可选）设置开机自启：\n\n```bash\nopenclaw gateway install\n```\n\n## 3. 基本使用\n\n### 配对授权\n\n1.  在飞书客户端中搜索你的机器人名称，打开对话窗口。\n2.  发送任意消息（如 \"你好\"）。\n3.  机器人会回复一个 **配对码**（一串字母数字）。\n4.  在终端中运行以下命令完成授权：\n\n```bash\nopenclaw pairing approve feishu \u003C配对码>\n```\n\n### 开始对话\n\n授权完成后，再次在飞书中向机器人发送消息，即可收到 AI 回复。\n\n*   **私聊**：直接发送消息即可。\n*   **群聊**：默认需要 **@机器人** 才会触发回复。\n\n### 验证连接状态\n\n如需确认连接是否正常，可查看实时日志：\n\n```bash\nopenclaw logs --follow\n```\n\n若看到 `feishu ws connected` 或 `feishu provider ready` 字样，即表示连接成功。","某互联网公司产品经理正在筹备季度复盘会议，需要协调跨部门资源、整理历史文档并同步最新进度。\n\n### 没有 openclaw-feishu 时\n- **信息检索低效**：为了查找上个季度的项目复盘文档，需要在飞书云盘中手动层层翻阅文件夹，或通过关键词搜索后逐一打开预览，耗时且容易遗漏关键版本。\n- **日程协调繁琐**：确定会议时间时，需分别打开多位核心参会人的日历查看忙闲状态，反复沟通确认空档，再手动创建会议邀请，极易出现时间冲突或通知遗漏。\n- **任务追踪断层**：会议中确定的待办事项（Action Items）需会后人工整理，再逐个在飞书任务中创建并指派给对应负责人，过程机械且容易因记忆偏差导致任务描述不清或责任人错配。\n- **身份割裂感强**：若使用普通机器人插件，发出的消息和创建的文档均显示为“机器人”名义，缺乏正式感和权威性，团队成员往往忽略非真人发出的协作请求。\n\n### 使用 openclaw-feishu 后\n- **智能文档直达**：通过自然语言指令“帮我找出上季度关于用户增长的所有复盘文档”，openclaw-feishu 以你的身份直接检索并汇总链接，甚至能提取关键结论生成摘要，秒级获取信息。\n- **自动化日程管理**：只需说“约下周二下午研发和市场负责人开一小时会”，AI 自动查询相关人员日历忙闲，锁定共同空闲时段并发送正式会议邀请，全程无需手动切换界面。\n- **闭环任务执行**：会议结束时，直接指令“将刚才讨论的三个待办项创建为飞书任务并指派给对应人”，AI 即时在飞书任务模块生成清晰条目，确保责任到人，实现从沟通到执行的无缝衔接。\n- **数字分身体验**：所有操作均以你本人的 OAuth 身份执行，发出的消息、创建的文档均带有你的个人标识，保持了职场协作的真实性和信任度，如同拥有一个能直接操作飞书的数字分身。\n\n核心价值在于将 AI 从单纯的“聊天问答”升级为能深度操控飞书生态的“执行代理”，极大释放了重复性办公操作的精力。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAlexAnys_openclaw-feishu_4d30ad34.png","AlexAnys","Alex AN","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FAlexAnys_6eb40ce1.png",null,"anyangsen@hotmail.com","https:\u002F\u002Fgithub.com\u002FAlexAnys",[83,87],{"name":84,"color":85,"percentage":86},"TypeScript","#3178c6",84.1,{"name":88,"color":89,"percentage":90},"JavaScript","#f1e05a",15.9,655,52,"2026-04-02T07:47:11","MIT","macOS, Linux","未说明",{"notes":98,"python":96,"dependencies":99},"本项目为 OpenClaw 的飞书集成指南及插件配置说明，并非独立的 AI 模型运行环境。核心依赖是已安装并正常运行的 OpenClaw (版本需 >= 2026.2)。支持两种接入方式：1. OpenClaw 内置飞书插件（推荐，配置简单，以机器人身份运行）；2. 飞书官方插件（功能更强，支持以用户身份操作文档\u002F日历\u002F任务，需 OAuth 授权及 Lark CLI）。两者互斥，不可同时启用。需注意飞书 API 配额限制，避免多实例共用同一 App ID 导致超限。",[100,101],"openclaw (>= 2026.2)","@larksuiteoapi\u002Ffeishu-openclaw-plugin (可选，官方插件)",[53,15,26],[104,105,106,107,108,109,110,111,112],"ai-agent","channel-plugin","chatbot","clawdbot","feishu","lark","openclaw","websocket","webhook","2026-03-27T02:49:30.150509","2026-04-06T08:40:53.628597",[116,121,126,131,136,141],{"id":117,"question_zh":118,"answer_zh":119,"source_url":120},11375,"安装飞书插件后报错 \"Cannot find module '@sinclair\u002Ftypebox'\" 或提示 \"duplicate plugin id detected\"，如何解决？","这是因为 OpenClaw ≥ 2026.2 版本已内置飞书插件，无需手动安装。如果之前手动删除了内置扩展并尝试通过 `openclaw plugins install` 重装，会导致依赖解析错误或插件ID冲突。\n\n解决方案：\n1. 删除用户目录下的插件副本：\n   ```bash\n   rm -rf ~\u002F.openclaw\u002Fextensions\u002Ffeishu\n   ```\n2. 运行更新命令恢复内置插件及依赖：\n   ```bash\n   openclaw update\n   ```\n3. 重启网关：\n   ```bash\n   openclaw gateway restart\n   ```\n\n建议：如果不需要飞书插件，请使用 `openclaw plugins disable feishu` 禁用，不要手动删除目录。","https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues\u002F29",{"id":122,"question_zh":123,"answer_zh":124,"source_url":125},11376,"执行 `\u002Ffeishu auth` 授权失败，日志显示 HTTP 444 Access Denied 或无反应，怎么办？","这通常是因为应用权限配置不当（授权了过多或不必要的功能）导致的。请重新创建 Bot 或检查权限配置，确保只勾选必要的权限。\n\n推荐的权限清单如下：\n```json\n{\n  \"scopes\": {\n    \"tenant\": [\n      \"application:application:self_manage\",\n      \"cardkit:card:read\",\n      \"cardkit:card:write\",\n      \"contact:contact.base:readonly\",\n      \"docx:document:readonly\",\n      \"im:chat:read\",\n      \"im:chat:update\",\n      \"im:message.group_at_msg:readonly\",\n      \"im:message.p2p_msg:readonly\",\n      \"im:message.pins:read\",\n      \"im:message.pins:write_only\",\n      \"im:message.reactions:read\",\n      \"im:message.reactions:write_only\",\n      \"im:message:readonly\",\n      \"im:message:recall\",\n      \"im:message:send_as_bot\",\n      \"im:message:send_multi_users\",\n      \"im:message:send_sys_msg\",\n      \"im:message:update\",\n      \"im:resource\"\n    ],\n    \"user\": [\n      \"docs:document.media:upload\",\n      \"docs:document:export\",\n      \"im:message.send_as_user\",\n      \"sheets:spreadsheet.meta:read\",\n      \"sheets:spreadsheet:create\",\n      \"sheets:spreadsheet:read\",\n      \"sheets:spreadsheet:write_only\"\n    ]\n  }\n}\n```\n配置好正确权限后，重新进行授权即可。","https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues\u002F65",{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},11377,"回复飞书卡片消息时，机器人无法获取原卡片内容（上下文丢失），只显示 \"[Interactive Card]\"，如何解决？","这不是飞书平台的缺陷，而是旧版或非官方插件的功能缺失。飞书在回复回调中不会内联父消息内容，但会提供 `parent_id`，插件需要主动调用 API 获取。\n\n解决方案：\n请使用飞书官方插件 `larksuite\u002Fopenclaw-lark`（包名：`@larksuiteoapi\u002Ffeishu-openclaw-plugin`）。该插件从首个版本起已支持完整处理：\n1. 从事件中提取 `parent_id`。\n2. 调用 `getMessageFeishu` 接口，并使用参数 `card_msg_content_type: 'raw_card_content'` 获取完整的卡片 JSON。\n3. 解析卡片内容并拼接到对话上下文中。\n\n如果你使用的是社区插件或内置插件且遇到此问题，请切换到官方插件，或确保插件版本为最新。","https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues\u002F69",{"id":132,"question_zh":133,"answer_zh":134,"source_url":135},11378,"发送图片或文件给 AI 时，AI 看不到内容或网关收不到，如何处理？","首先检查以下基础配置：\n1. **权限检查**：飞书开放平台应用中必须拥有 `im:resource` 权限。\n2. **发布版本**：修改权限后，记得在开放平台“创建新版本”并“发布”。\n3. **重启网关**：执行 `openclaw gateway restart`。\n\n如果上述步骤无效，且报错包含 `LocalMediaAccessError: Local media path is not under an allowed directory`，说明是媒体文件路径权限问题。OpenClaw 出于安全考虑，限制访问特定目录外的文件。\n\n建议：直接使用 OpenClaw 官方推荐的插件方案，避免使用已停止维护的社区插件，以确保媒体消息处理的兼容性。","https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues\u002F35",{"id":137,"question_zh":138,"answer_zh":139,"source_url":140},11379,"发送超长文档（如几万字的 docx）到飞书后，模型无响应或报错 \"Context overflow\"，有什么改进建议？","这是由于文档内容被完整解析为字符串后，超过了模型的上下文窗口限制（Prompt too large）。\n\n目前的表现是：\n1. 后台将文档转化为超长字符串。\n2. 模型因上下文溢出无法响应，甚至导致后续消息接收失败，报错 `Context overflow: prompt too large for the model`。\n\n临时解决方案：\n- 使用 `\u002Fnew` 或 `\u002Freset` 命令开启新的会话，清除过大的上下文。\n- 尽量避免一次性发送超出模型处理能力的超大文档，或先在本地对文档进行截断\u002F摘要处理后再发送。\n\n注：这是一个已知问题，未来版本可能会增加自动截断机制。","https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues\u002F66",{"id":142,"question_zh":143,"answer_zh":144,"source_url":145},11380,"按照教程配置后，飞书机器人聊天界面没有消息发送框，无法输入消息，原因是什么？","虽然具体截图未显示，但此类问题通常由以下原因导致：\n1. **权限未生效**：检查是否缺少 `im:message:send_as_bot` 或相关消息接收权限，且未在开放平台发布新版本。\n2. **应用类型错误**：确认创建的是“机器人”应用而非其他类型，且已在飞书客户端中正确添加该机器人到聊天中。\n3. **安全设置**：检查飞书管理后台的安全设置，是否限制了该应用的使用范围或消息权限。\n\n建议重新检查开放平台的权限配置并发布版本，同时确认机器人已正确添加到目标群组或联系人列表中。","https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fissues\u002F28",[147,152],{"id":148,"version":149,"summary_zh":150,"released_at":151},61868,"v0.4.0","## 🌏 Lark（国际版）用户现在可以接入了\n\nLark 后台不开放 WebSocket 长连接，之前国际版用户没法用。这个版本新增 **Webhook 模式**，配合 Cloudflare Tunnel 四步搞定。\n\n### 新功能\n\n- **Lark 域名支持**：配置 `domain: \"lark\"`，SDK 和 API 自动切到 `open.larksuite.com`\n- **Webhook 连接模式**：`connectionMode: \"webhook\"` 启动 HTTP 服务器接收事件回调\n- **Lark 接入指南**：README 新增完整教程，包含 Cloudflare Tunnel + VPN 兼容性说明\n\n### 改进\n\n- Lark 用户误配 WebSocket 时自动 fallback 到 Webhook 并打日志提醒\n- Webhook 服务器对非匹配路径返回 404（不再 hang）\n- 端口冲突时给出明确的错误提示\n- Graceful shutdown 改进\n\n### 配置示例（Lark 用户）\n\n```json5\n{\n  channels: {\n    feishu: {\n      domain: \"lark\",\n      connectionMode: \"webhook\",\n      webhookPort: 3000,\n      accounts: {\n        main: { appId: \"cli_xxx\", appSecret: \"xxx\" }\n      }\n    }\n  }\n}\n```\n\n### 向后兼容\n\n飞书国内版用户无需任何改动，`domain` 和 `connectionMode` 都有默认值。\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu\u002Fcompare\u002Fv0.3.1...v0.4.0","2026-02-24T12:03:13",{"id":153,"version":154,"summary_zh":155,"released_at":156},61869,"v1.0.0","## 🎉 定位转型\n\n本项目从飞书插件转型为 **飞书 × OpenClaw 保姆级配置指南 & 社区支持中心**。\n\nOpenClaw 已内置官方飞书插件（`@openclaw\u002Ffeishu`），本项目继续为社区提供：\n\n- 🔄 **保姆级迁移指南** — 两种方式，推荐 `openclaw update` 一键升级\n- 🚀 **新手从零配置教程** — 9 步走完，非技术背景也能搞定\n- 🔧 **常见问题 & 排查清单** — 收不到消息、图片不通、时断时续等\n- 📚 **进阶配置参考** — 群组、流式输出、多 Agent 路由、访问控制\n- 🌉 **独立桥接模式** — 进阶用户仍可使用\n\n### 迁移指引\n\n👉 [查看完整迁移教程](https:\u002F\u002Fgithub.com\u002FAlexAnys\u002Fopenclaw-feishu#-从旧版迁移到官方插件保姆级)\n\n推荐方式：\n\n```bash\nopenclaw update\nopenclaw channels add   # 选择 Feishu，粘贴凭证\n```\n\n迁移过程中遇到问题随时开 Issue，我们一起解决 🙌\n\n感谢大家一直以来的支持！","2026-02-07T08:50:19"]