跳转到主要内容

​
飞书机器人

当你的团队已经使用飞书或 Lark，并且希望网关加入这些对话而不公开入站 webhook 时，使用飞书。该插件会保持与平台的长连接事件通道，并通过标准机器人 API 发送回复。
状态：Fased 随包提供的飞书/Lark 渠道扩展。它支持常见机器人流程、账号感知配置，以及标准 Fased 配对和群组控制。

​
从 Agent > Channels 设置

飞书作为本地 bundled channel extension 随 Fased 提供。正常安装不需要下载 npm 包。 打开 Agents，选择 Agent，然后进入 Agent > Channels > Feishu。填写 App ID、App Secret 和域名，保存渠道；如果 UI 提示运行时尚未加载，请重启 gateway。 如果你维护自定义飞书插件包，请在 Extensions 管理。正常飞书设置使用 bundled channel extension 和 Agent > Channels 中的字段。

​
快速开始

飞书路径有两部分：飞书/Lark 开发者控制台中的应用，以及本地 Fased 配置中保存的应用凭证。配置完成后，gateway 会为你维持实时连接。 添加飞书渠道有三种方式：

​
方式一：Agent > Channels（推荐）

打开 Agents，选择 Agent，然后打开 Agent > Channels > Feishu。填写 App ID、App Secret 和域名。这是正常的浏览器设置路径。

​
方式二：CLI onboarding

如果您刚安装完 Fased，可以直接运行向导，根据提示添加飞书： 
fased onboard
向导会引导您完成：
  1. 创建飞书应用并获取凭证
  2. 配置应用凭证
  3. 启动网关
✅ 完成配置后，您可以使用以下命令检查网关状态：
  • fased gateway status - 查看网关运行状态
  • fased logs --follow - 查看实时日志

​
方式三：CLI setup

如果您已经完成了初始安装，可以用以下命令添加飞书渠道： 
fased channels add
然后根据交互式提示选择 Feishu，输入 App ID 和 App Secret 即可。 ✅ 完成配置后，您可以使用以下命令管理网关：
  • fased gateway status - 查看网关运行状态
  • fased gateway restart - 重启网关以应用新配置
  • fased logs --follow - 查看实时日志

​
第一步：创建飞书应用

​
1. 打开飞书开放平台

访问 飞书开放平台，使用飞书账号登录。 Lark（国际版）请使用 https://open.larksuite.com/app，并在配置中设置 domain: "lark"。

​
2. 创建应用

  1. 点击 创建企业自建应用
  2. 填写应用名称和描述
  3. 选择应用图标

​
3. 获取应用凭证

在应用的 凭证与基础信息 页面，复制：
  • App ID（格式如 cli_xxx）
  • App Secret
❗ 重要：请妥善保管 App Secret，不要分享给他人。

​
4. 配置应用权限

在 权限管理 页面，点击 批量导入 按钮，粘贴以下 JSON 配置一键导入所需权限： 
{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

​
5. 启用机器人能力

在 应用能力 > 机器人 页面：
  1. 开启机器人能力
  2. 配置机器人名称

​
6. 配置事件订阅

⚠️ 重要提醒：在配置事件订阅前，请务必确保已完成以下步骤：
  1. 运行 fased channels add 添加了 Feishu 渠道
  2. 网关处于启动状态（可通过 fased gateway status 检查状态）
在 事件订阅 页面：
  1. 选择 使用长连接接收事件（WebSocket 模式）
  2. 添加事件：im.message.receive_v1（接收消息）
⚠️ 注意：如果网关未启动或渠道未添加，长连接设置将保存失败。

​
7. 发布应用

  1. 在 版本管理与发布 页面创建版本
  2. 提交审核并发布
  3. 等待管理员审批（企业自建应用通常自动通过）

​
第二步：配置 Fased

​
通过向导配置（推荐）

运行以下命令，根据提示粘贴 App ID 和 App Secret： 
fased channels add
选择 Feishu，然后输入您在第一步获取的凭证即可。

​
通过配置文件配置

编辑 ~/.fased/fased.json： 
{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "我的AI助手",
        },
      },
    },
  },
}

​
通过环境变量配置

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

​
Lark（国际版）域名

如果您的租户在 Lark（国际版），请设置域名为 lark（或完整域名），可配置 channels.feishu.domain 或 channels.feishu.accounts.<id>.domain： 
{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

​
第三步：启动并测试

​
1. 启动网关

fased gateway

​
2. 发送测试消息

在飞书中找到您创建的机器人，发送一条消息。

​
3. 配对授权

默认情况下，机器人会回复一个 配对码。您需要批准此代码： 
fased pairing approve feishu <配对码>
批准后即可正常对话。

​
介绍

  • 飞书机器人渠道：由网关管理的飞书机器人
  • 确定性路由：回复始终返回飞书，模型不会选择渠道
  • 会话隔离：私聊共享主会话；群组独立隔离
  • WebSocket 连接：使用飞书 SDK 的长连接模式，无需公网 URL

​
访问控制

​
私聊访问

  • 默认：dmPolicy: "pairing"，陌生用户会收到配对码
  • 批准配对： 
    fased pairing list feishu      # 查看待审批列表
fased pairing approve feishu <CODE>  # 批准
  • 白名单模式：通过 channels.feishu.allowFrom 配置允许的用户 Open ID

​
群组访问

1. 群组策略（channels.feishu.groupPolicy）：
  • "open" = 允许群组中所有人（默认）
  • "allowlist" = 仅允许 groupAllowFrom 中的用户
  • "disabled" = 禁用群组消息
2. @提及要求（channels.feishu.groups.<chat_id>.requireMention）：
  • true = 需要 @机器人才响应（默认）
  • false = 无需 @也响应

​
群组配置示例

​
允许所有群组，需要 @提及（默认行为）

{
  channels: {
    feishu: {
      groupPolicy: "open",
      // 默认 requireMention: true
    },
  },
}

​
允许所有群组，无需 @提及

需要为特定群组配置： 
{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}

​
仅允许特定用户在群组中使用

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["ou_xxx", "ou_yyy"],
    },
  },
}

​
获取群组/用户 ID

​
获取群组 ID（chat_id）

群组 ID 格式为 oc_xxx，可以通过以下方式获取： 方法一（推荐）：
  1. 启动网关并在群组中 @机器人发消息
  2. 运行 fased logs --follow 查看日志中的 chat_id
方法二： 使用飞书 API 调试工具获取机器人所在群组列表。

​
获取用户 ID（open_id）

用户 ID 格式为 ou_xxx，可以通过以下方式获取： 方法一（推荐）：
  1. 启动网关并给机器人发消息
  2. 运行 fased logs --follow 查看日志中的 open_id
方法二： 查看配对请求列表，其中包含用户的 Open ID： 
fased pairing list feishu

​
常用命令

命令说明
/status查看机器人状态
/reset重置对话会话
/model查看/切换模型
注意：飞书目前不支持原生命令菜单，命令需要以文本形式发送。

​
网关管理命令

在配置和使用飞书渠道时，您可能需要使用以下网关管理命令：
命令说明
fased gateway status查看网关运行状态
fased gateway install安装/启动网关服务
fased gateway stop停止网关服务
fased gateway restart重启网关服务
fased logs --follow实时查看日志输出

​
故障排除

​
机器人在群组中不响应

  1. 检查机器人是否已添加到群组
  2. 检查是否 @了机器人（默认需要 @提及）
  3. 检查 groupPolicy 是否为 "disabled"
  4. 查看日志：fased logs --follow

​
机器人收不到消息

  1. 检查应用是否已发布并审批通过
  2. 检查事件订阅是否配置正确（im.message.receive_v1）
  3. 检查是否选择了 长连接 模式
  4. 检查应用权限是否完整
  5. 检查网关是否正在运行：fased gateway status
  6. 查看实时日志：fased logs --follow

​
App Secret 泄露怎么办

  1. 在飞书开放平台重置 App Secret
  2. 更新配置文件中的 App Secret
  3. 重启网关

​
发送消息失败

  1. 检查应用是否有 im:message:send_as_bot 权限
  2. 检查应用是否已发布
  3. 查看日志获取详细错误信息

​
高级配置

​
多账号配置

如果需要管理多个飞书机器人： 
{
  channels: {
    feishu: {
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "主机器人",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          botName: "备用机器人",
          enabled: false, // 暂时禁用
        },
      },
    },
  },
}

​
消息限制

  • textChunkLimit：出站文本分块大小（默认 2000 字符）
  • mediaMaxMb：媒体上传/下载限制（默认 30MB）

​
流式输出

飞书支持通过交互式卡片实现流式输出，机器人会实时更新卡片内容显示生成进度。默认配置： 
{
  channels: {
    feishu: {
      streaming: true, // 启用流式卡片输出（默认 true）
      blockStreaming: true, // 启用块级流式（默认 true）
    },
  },
}
如需禁用流式输出（等待完整回复后一次性发送），可设置 streaming: false。

​
消息引用

在群聊中，机器人的回复可以引用用户发送的原始消息，让对话上下文更加清晰。 配置选项： 
{
  channels: {
    feishu: {
      // 账户级别配置（默认 "all"）
      replyToMode: "all",
      groups: {
        oc_xxx: {
          // 特定群组可以覆盖
          replyToMode: "first",
        },
      },
    },
  },
}
replyToMode 值说明：
值行为
"off"不引用原消息（私聊默认值）
"first"仅在第一条回复时引用原消息
"all"所有回复都引用原消息（群聊默认值）
注意：消息引用功能与流式卡片输出（streaming: true）不能同时使用。当启用流式输出时，回复会以卡片形式呈现，不会显示引用。

​
多 Agent 路由

通过 bindings 配置，您可以用一个飞书机器人对接多个不同功能或性格的 Agent。系统会根据用户 ID 或群组 ID 自动将对话分发到对应的 Agent。 配置示例： 
{
  agents: {
    list: [
      { id: "main" },
      {
        id: "research-fan",
        workspace: "/home/user/research-fan",
        agentDir: "/home/user/.fased/agents/research-fan/agent",
      },
      {
        id: "ops-xi",
        workspace: "/home/user/ops-xi",
        agentDir: "/home/user/.fased/agents/ops-xi/agent",
      },
    ],
  },
  bindings: [
    {
      // 用户 A 的私聊 → main agent
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "dm", id: "ou_28b31a88..." },
      },
    },
    {
      // 用户 B 的私聊 → research-fan agent
      agentId: "research-fan",
      match: {
        channel: "feishu",
        peer: { kind: "dm", id: "ou_0fe6b1c9..." },
      },
    },
    {
      // 某个群组 → ops-xi agent
      agentId: "ops-xi",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_xxx..." },
      },
    },
  ],
}
匹配规则说明：
字段说明
agentId目标 Agent 的 ID，需要在 agents.list 中定义
match.channel渠道类型，这里固定为 "feishu"
match.peer.kind对话类型："dm"（私聊）或 "group"（群组）
match.peer.id用户 Open ID（ou_xxx）或群组 ID（oc_xxx）
获取 ID 的方法：参见上文 获取群组/用户 ID 章节。

​
配置参考

完整配置请参考：网关配置 主要选项：
配置项说明默认值
channels.feishu.enabled启用/禁用渠道true
channels.feishu.domainAPI 域名（feishu 或 lark）feishu
channels.feishu.accounts.<id>.appId应用 App ID-
channels.feishu.accounts.<id>.appSecret应用 App Secret-
channels.feishu.accounts.<id>.domain单账号 API 域名覆盖feishu
channels.feishu.dmPolicy私聊策略pairing
channels.feishu.allowFrom私聊白名单（open_id 列表）-
channels.feishu.groupPolicy群组策略open
channels.feishu.groupAllowFrom群组白名单-
channels.feishu.groups.<chat_id>.requireMention是否需要 @提及true
channels.feishu.groups.<chat_id>.enabled是否启用该群组true
channels.feishu.textChunkLimit消息分块大小2000
channels.feishu.mediaMaxMb媒体大小限制30
channels.feishu.streaming启用流式卡片输出true
channels.feishu.blockStreaming启用块级流式true

​
dmPolicy 策略说明

值行为
"pairing"默认。未知用户收到配对码，管理员批准后才能对话
"allowlist"仅 allowFrom 列表中的用户可对话，其他静默忽略
"open"允许所有人对话（需在 allowFrom 中加 "*"）
"disabled"完全禁止私聊

​
支持的消息类型

​
接收

  • ✅ 文本消息
  • ✅ 图片
  • ✅ 文件
  • ✅ 音频
  • ✅ 视频
  • ✅ 表情包

​
发送

  • ✅ 文本消息
  • ✅ 图片
  • ✅ 文件
  • ✅ 音频
  • ⚠️ 富文本（部分支持）