OpenClaw 飞书接入完整指南 — 从零配置飞书AI机器人

飞书 + OpenClaw 能做什么

飞书（Feishu / Lark）是字节跳动旗下的企业级协作平台，在中国拥有大量企业用户。飞书开放平台提供了完善的机器人 API， 支持消息收发、事件订阅、消息卡片等丰富功能。通过将 OpenClaw AI智能体接入飞书，你可以实现以下场景：

• AI智能问答 — 员工在飞书单聊或群聊中直接向AI提问，获取即时回答。支持自然语言理解，无需记忆复杂命令。
• 企业文档搜索 — 结合 OpenClaw 的 RAG（检索增强生成）能力，将企业知识库、制度文档、产品手册接入AI，员工在飞书中即可快速检索信息。
• 任务自动化 — 通过 OpenClaw 的 Skills（Skills）系统，AI机器人可以执行网页搜索、代码生成、数据分析等任务，将结果直接发送到飞书对话中。
• 多Agent协作 — 在同一飞书环境中部署多个AI Agent，不同群组使用不同Agent，实现专业分工。例如：技术支持Agent、HR问答Agent、翻译Agent等。
• 消息卡片交互 — 利用飞书的消息卡片能力，AI机器人可以发送结构化的卡片消息，支持按钮、表单等交互元素。
• 会议纪要与日程管理 — 将AI配置为会议助手，自动整理会议要点、生成待办事项、同步到飞书日历。

飞书开放平台注册与配置（详细步骤）

以下是从零开始在飞书开放平台创建机器人应用的完整步骤。每一步都附有详细说明，即使是第一次接触飞书开放平台也能顺利完成。

OpenClaw 飞书配置（openclaw.json）

完成飞书开放平台的配置后，接下来需要在 OpenClaw 的配置文件 openclaw.json 中添加飞书渠道配置。 配置文件通常位于 ~/.openclaw/openclaw.json。

完整配置示例

以下是一个完整的飞书配置示例，包含所有必要字段：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_a1b2c3d4e5f6",
      "appSecret": "your-app-secret-here",
      "verificationToken": "your-verification-token",
      "encryptKey": "your-encrypt-key",
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4"
      }
    }
  },
  "models": {
    "providers": {
      "openrouter": {
        "apiKey": "sk-or-xxxxx"
      }
    }
  },
  "session": {
    "dmScope": "per-channel-peer"
  }
}

配置项详解

channels.feishu 配置

• enabled (true / false) — 是否启用飞书渠道。设为 true 才会激活飞书机器人。
• appId — 飞书开放平台的 App ID，从「凭证与基础信息」页面获取。格式如 cli_a1b2c3d4e5f6。
• appSecret — 飞书开放平台的 App Secret。敏感信息，请妥善保管。
• verificationToken — 事件订阅的验证令牌，从「事件订阅」页面获取。飞书用它验证 Webhook 请求的合法性。
• encryptKey — 事件订阅的加密密钥。飞书会用这个密钥对推送的事件数据进行加密，你的服务端需要用它解密。如果不需要加密传输，可以留空字符串 ""。
• dmPolicy — 私聊消息策略。飞书企业内部应用建议设为 "open"，因为只有组织内成员才能访问。如需更严格控制，使用 "pairing"。
• allowFrom — 当 dmPolicy 为 "open" 时，必须同时设置 allowFrom: ["*"]。不设置会导致配置校验失败。

plugins.entries.feishu 配置

重要：channels.feishu 和 plugins.entries.feishu 必须同时启用。 只配置 channel 而不启用 plugin，飞书渠道不会生效。这是 OpenClaw 的设计机制 — channel 配置定义连接参数，plugin 控制是否实际加载。

"plugins": {
  "entries": {
    "feishu": {
      "enabled": true   // 必须为 true，否则飞书渠道不会启动
    }
  }
}

dmPolicy 设置说明

dmPolicy 控制机器人如何处理私聊消息。飞书场景下有两种选择：

• "open" — 允许所有用户直接与机器人对话。由于飞书企业应用只在组织内可见，"open" 在飞书中是安全的（与 Telegram 不同）。 使用 "open" 时必须同时配置 allowFrom: ["*"]。
• "pairing" — 用户需要先通过 Web Gateway 配对后才能使用机器人。安全性更高，但用户体验稍差。 适用于需要严格访问控制的企业场景。

长连接配置 vs Webhook 配置

飞书支持两种消息推送方式，各有优劣：

Webhook 方式的 OpenClaw 配置无需额外参数，OpenClaw 自动监听 Webhook 端口。长连接方式需要在飞书开放平台切换为「长连接」模式，OpenClaw 会自动建立 WebSocket 连接。

"未检测到应用连接信息"错误解决

这是飞书开发者常遇到的问题，错误信息为「未检测到应用连接信息」或英文 "No app connection detected"。 主要出现在使用长连接模式时。

原因分析

飞书长连接模式需要应用主动与飞书服务器建立 WebSocket 连接。如果飞书开放平台检测不到你的应用连接，就会显示此错误。常见原因包括：

1. 应用未启动 — OpenClaw 服务没有运行，或者飞书 channel 没有正确启用
2. AppId / AppSecret 错误 — 配置文件中的凭证与飞书开放平台不一致
3. 网络连接问题 — 服务器无法访问飞书的 WebSocket 端点（中国大陆以外的服务器可能需要检查网络连通性）
4. plugin 未启用 — plugins.entries.feishu.enabled 没有设为 true
5. 事件订阅模式不匹配 — 飞书开放平台设置的是 Webhook 模式，但你期望使用长连接（或反之）

解决步骤

1. 确认 OpenClaw 已启动且飞书 channel 已加载：检查 OpenClaw 日志，应该能看到类似 [feishu] channel loaded 的信息。 如果没有这行日志，说明飞书 plugin 没有正确启用。
2. 核对凭证：确保 openclaw.json 中的 appId 和 appSecret 与飞书开放平台完全一致（注意不要有多余空格）。
3. 检查模式一致性：如果你想用长连接，确保飞书开放平台「事件订阅」中选择的是「长连接」而非「HTTP」。反之亦然。
4. 检查网络：在服务器上测试能否访问飞书 API：

   curl -I https://open.feishu.cn/open-apis/bot/v2/hook/test

   如果超时或返回错误，说明网络有问题。
5. 重启 OpenClaw：修改配置后，需要重启 OpenClaw 使配置生效。Docker 用户：

   docker restart your-openclaw-container

6. 查看飞书开放平台日志：在「监控与告警」>「日志查询」中查看是否有连接记录或错误。

飞书权限配置详解

必需权限列表

权限申请流程

1. 进入应用的「权限管理」页面
2. 在搜索框中输入权限标识（如 im:message）
3. 找到对应权限，点击「开通」
4. 如果权限标记为「免审批」，开通后立即生效
5. 如果权限标记为「需审批」，需要组织管理员在飞书管理后台 > 权限审批中通过
6. 审批通过后，创建新版本并发布，权限才会实际生效

常见权限错误

• "Permission denied" / "权限不足" — 通常是因为没有申请或没有审批通过 im:message 权限。检查「权限管理」页面，确认所有必需权限已开通。
• "Bot has no permission to send message" — 缺少 im:message:send_as_bot 权限。这个权限允许机器人以应用身份发送消息。
• "User not in app's availability scope" — 用户不在应用的可用范围内。需要在「版本管理」>「可用范围」中添加用户或设为「全员可用」。
• 权限开通后仍报错 — 可能是因为开通权限后没有创建新版本并发布。飞书的权限变更需要通过版本发布才能生效。

飞书多Agent配置

OpenClaw 支持在同一实例中配置多个 AI Agent，这在飞书企业场景中非常实用。你可以为不同的部门或群组分配不同的Agent，实现专业化的AI服务。

在飞书中运行多个AI Agent

有两种方式实现飞书多Agent：

• 方式一：单实例多Agent — 在一个 OpenClaw 实例中配置多个 Agent，通过命令或群组自动切换。配置示例：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4"
      }
    },
    "entries": {
      "tech-support": {
        "name": "技术支持",
        "systemPrompt": "你是一个技术支持专家，帮助员工解决技术问题...",
        "model": {
          "primary": "openrouter/anthropic/claude-sonnet-4"
        }
      },
      "hr-assistant": {
        "name": "HR助手",
        "systemPrompt": "你是一个人力资源助手，回答员工关于制度、假期、福利等问题...",
        "model": {
          "primary": "openrouter/anthropic/claude-sonnet-4"
        }
      },
      "translator": {
        "name": "翻译助手",
        "systemPrompt": "你是一个专业翻译，支持中英日韩等多语种互译...",
        "model": {
          "primary": "openrouter/anthropic/claude-sonnet-4"
        }
      }
    }
  }
}

• 方式二：多实例隔离 — 为每个Agent创建独立的 OpenClaw 实例和飞书应用。隔离性更好，但管理成本更高。 每个实例使用不同的飞书 App ID 和 App Secret。

不同群组不同Agent

通过 OpenClaw 的路由配置，可以根据群组 ID 将消息路由到不同的 Agent：

• 技术群 → 技术支持Agent（处理bug报告、系统问题）
• HR群 → HR助手Agent（回答制度、假期问题）
• 翻译群 → 翻译Agent（实时翻译）
• 默认私聊 → 通用Agent（全能助手）

Agent切换

用户可以通过以下方式在Agent之间切换：

• 使用命令：/agent tech-support 切换到技术支持Agent
• 使用命令：/agent hr-assistant 切换到HR助手
• 使用命令：/agent list 查看所有可用Agent
• 使用命令：/agent reset 回到默认Agent

多Agent配置让一个飞书机器人具备了「多种人格」，适合企业内不同场景的需求。

飞书 vs Telegram vs Discord — 中国用户选择指南

对于中国企业和个人用户，选择合适的平台至关重要。以下是三个主流平台的全面对比：

总结：飞书是中国企业用户的首选 — 无需VPN、权限管理完善、消息卡片功能强大。 配置虽然比 Telegram 复杂，但功能更加丰富，特别适合企业场景。 如果你是个人用户或需要全球可用的方案，推荐 Telegram（10秒部署）。

OpenClaw Launch 部署飞书机器人

OpenClaw Launch 是 OpenClaw 的可视化部署平台，让你无需手动编辑配置文件， 通过图形界面即可完成AI机器人的配置和部署。

当前支持状态

• Telegram — 原生支持，10秒一键部署，无需任何技术背景
• Discord — 原生支持，几分钟内完成部署
• Web Chat — 原生支持，网页聊天窗口
• 飞书 — 需自建部署，通过 Docker 手动配置

飞书自建部署方式

由于飞书需要企业认证和复杂的权限配置，目前通过以下方式部署：

1. 参考 Docker 部署指南 安装 OpenClaw
2. 按照本页面上方的步骤完成飞书开放平台配置
3. 编辑 openclaw.json，添加飞书渠道配置
4. 启动或重启 Docker 容器
5. 在飞书开放平台验证连接状态

更多配置选项请参考 OpenClaw 配置文件详解 和 安装部署教程。

替代方案

如果飞书配置过于复杂，可以考虑以下替代方案：

• 企业微信接入 — 同样面向中国企业用户，与微信生态深度打通
• 钉钉接入 — 阿里系企业办公平台，配置流程类似
• Telegram 接入 — 最简单的方案，10秒部署，但需要VPN

常见问题排查

机器人不回复消息

1. 检查 OpenClaw 日志是否收到了飞书的消息事件（im.message.receive_v1）
2. 确认 channels.feishu.enabled 和 plugins.entries.feishu.enabled 都为 true
3. 确认 im:message 和 im:message:send_as_bot 权限已开通
4. 检查AI模型API Key是否有效、额度是否充足
5. 确认应用已发布（未发布的应用只有测试用户能使用）
6. 如果是群聊，确认用户有 @机器人（飞书群聊中通常需要 @机器人才会触发回复）

权限不足

• 在飞书开放平台「权限管理」中确认所有必需权限已开通
• 需审批权限是否已经通过审批
• 开通权限后是否创建了新版本并发布
• 用户是否在应用的「可用范围」内

Webhook 配置错误

• 确认 Webhook URL 可以从公网访问（飞书服务器需要能连接到你的服务器）
• 确认 URL 使用 HTTPS（飞书不支持 HTTP）
• 确认服务器正确处理了飞书的 challenge 验证请求
• 检查 verificationToken 和 encryptKey 是否与飞书开放平台一致
• 使用飞书开放平台的「在线调试」工具测试 Webhook 连通性

长连接断开

• 长连接模式下，如果 OpenClaw 进程重启，连接会断开。确保进程管理器（如PM2、Docker）配置了自动重启
• 检查服务器的出站网络是否稳定
• 确认没有防火墙或代理阻止了 WebSocket 连接
• 查看 OpenClaw 日志中是否有重连相关的信息
• 如果频繁断连，考虑改用 Webhook 方式（生产环境更推荐）

消息格式问题

• 飞书支持多种消息类型（文本、富文本、卡片等），OpenClaw 默认发送文本消息
• 如果AI回复包含 Markdown 格式，飞书的文本消息不会渲染 Markdown。需要使用富文本或卡片消息
• 长消息（超过4096字符）可能被飞书截断，需要分段发送
• 图片和文件需要先上传到飞书服务器获取 image_key / file_key，再发送

常见问题（FAQ）

需要企业版飞书才能创建机器人吗？

不需要单独购买「企业版」。飞书的标准版（免费版）就支持创建企业自建应用和机器人。 但你需要有一个飞书企业组织（可以免费创建），个人飞书账号没有开发者权限。 创建组织非常简单：在飞书中创建一个团队/企业即可，不需要营业执照等企业资质。

个人版飞书能用AI机器人吗？

个人版飞书（没有加入任何组织）无法直接创建和使用自建应用机器人。 但你可以创建一个免费的飞书组织，邀请自己加入，就可以使用企业自建应用了。 这是飞书与 Telegram 的最大区别 — Telegram 任何个人账号都可以创建和使用 Bot。 如果你不想创建组织，推荐使用 Telegram 作为替代方案。

飞书机器人免费吗？

飞书开放平台的机器人基础功能完全免费，包括：创建应用、收发消息、事件订阅、长连接等。 部分高级功能（如大规模消息推送的 QPS 限制提升）可能涉及收费。 OpenClaw 本身是开源免费的，但AI模型的API调用（如 OpenRouter、OpenAI）需要付费。 通过 OpenClaw Launch 托管部署需要订阅服务（$6/月起）。

飞书机器人支持群聊吗？

完全支持。飞书机器人可以同时在单聊和群聊中使用：

• 单聊：用户直接给机器人发消息，机器人自动回复
• 群聊：将机器人添加到群组中，用户通过 @机器人名称 的方式触发对话。 这样可以避免机器人对群里的每条消息都做出回应。

在 OpenClaw 配置中，建议使用 session.dmScope: "per-channel-peer" 来隔离不同用户的对话上下文， 避免群聊中一个用户的对话影响另一个用户。

飞书多Agent怎么配置？

参考本页面「飞书多Agent配置」章节。核心思路是在 agents.entries 中定义多个Agent， 每个Agent有独立的 systemPrompt 和 model 配置。 用户可以通过 /agent 命令切换Agent。 也可以通过路由规则将不同群组自动分配给不同Agent。 如果需要完全隔离（不同模型、不同API Key），建议使用多实例方式 — 每个Agent一个独立的 OpenClaw 容器和飞书应用。

飞书妙搭是什么？和 OpenClaw 有什么区别？

飞书妙搭（Feishu Anycross）是飞书官方的低代码平台和AI应用构建工具，可以在飞书内创建简单的自动化流程和AI对话机器人。

• 飞书妙搭：低代码、无需编程、集成飞书生态，但功能受限于飞书平台，不支持自定义AI模型和高级Skills
• OpenClaw：开源、高度可定制、支持多种AI模型（Claude、GPT-4、Gemini等）、丰富的Skills系统、跨平台（飞书+Telegram+Discord+Web）

如果你只需要简单的问答机器人，飞书妙搭可能就够了。 但如果你需要自定义AI模型、复杂的Skills 系统、跨平台部署，OpenClaw 是更好的选择。

飞书机器人消息有速率限制吗？

有。飞书对机器人消息发送有 QPS（每秒查询数）限制：

• 单聊消息：默认 5 QPS
• 群聊消息：默认 5 QPS
• 批量消息：默认 50 QPS

对于一般的AI问答场景，这个限制通常不会成为瓶颈。 如果需要更高的速率，可以在飞书开放平台申请提升配额。

能否同时接入飞书和其他平台？

当然可以。OpenClaw 支持同时启用多个渠道。你可以在同一个 openclaw.json 中同时配置飞书、Telegram、Discord：

{
  "channels": {
    "feishu": { "enabled": true, ... },
    "telegram": { "enabled": true, ... },
    "discord": { "enabled": true, ... }
  },
  "plugins": {
    "entries": {
      "feishu": { "enabled": true },
      "telegram": { "enabled": true },
      "discord": { "enabled": true }
    }
  }
}

所有渠道共享同一个AI模型和Agent配置，用户可以在任何平台与同一个AI对话。 每个渠道的会话是独立的（通过 session.dmScope 隔离）。