飞书机器人

---

内置插件

bash
openclaw plugins install @openclaw/feishu

---

快速开始

方式一：通过安装向导添加（推荐）

bash
openclaw onboard

1. ✦创建飞书应用并获取凭证
2. ✦配置应用凭证
3. ✦启动网关

• ✦openclaw gateway status - 查看网关运行状态
• ✦openclaw logs --follow - 查看实时日志

方式二：通过命令行添加

bash
openclaw channels add

• ✦openclaw gateway status - 查看网关运行状态
• ✦openclaw gateway restart - 重启网关以应用新配置
• ✦openclaw logs --follow - 查看实时日志

---

第一步：创建飞书应用

1. 打开飞书开放平台

2. 创建应用

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

3. 获取应用凭证

• ✦App ID（格式如 cli_xxx）
• ✦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. ✦运行 openclaw channels add 添加了 Feishu 渠道
2. ✦网关处于启动状态（可通过 openclaw gateway status 检查状态）

1. ✦选择 使用长连接接收事件（WebSocket 模式）
2. ✦添加事件：im.message.receive_v1（接收消息）

7. 发布应用

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

---

第二步：配置 OpenClaw

通过向导配置（推荐）

bash
openclaw channels add

通过配置文件配置

json5
{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "我的AI助手",
        },
      },
    },
  },
}

获取 Verification Token（仅 Webhook 模式）

1. ✦在飞书开放平台打开您的应用
2. ✦进入 开发配置 → 事件与回调
3. ✦打开 加密策略 选项卡
4. ✦复制 Verification Token（校验令牌）

通过环境变量配置

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

Lark（国际版）域名

json5
{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

配额优化

• ✦typingIndicator（默认 true）：设为 false 时不发送“正在输入”状态。
• ✦resolveSenderNames（默认 true）：设为 false 时不拉取发送者资料。

json5
{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          typingIndicator: true,
          resolveSenderNames: false,
        },
      },
    },
  },
}

---

第三步：启动并测试

1. 启动网关

bash
openclaw gateway

2. 发送测试消息

3. 配对授权

bash
openclaw pairing approve feishu <配对码>

---

介绍

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

---

访问控制

私聊访问

• ✦默认：dmPolicy: "pairing"，陌生用户会收到配对码
• ✦批准配对：

  bash
  openclaw pairing list feishu      # 查看待审批列表
  openclaw pairing approve feishu <CODE>  # 批准
  

• ✦白名单模式：通过 channels.feishu.allowFrom 配置允许的用户 Open ID

群组访问

• ✦"open" = 允许群组中所有人（默认）
• ✦"allowlist" = 仅允许 groupAllowFrom 中的群组
• ✦"disabled" = 禁用群组消息

• ✦true = 需要 @机器人才响应（默认）
• ✦false = 无需 @也响应

---

群组配置示例

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

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

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

json5
{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}

仅允许特定群组

json5
{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // 群组 ID 格式为 oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

仅允许特定成员在群组中发信（发送者白名单）

json5
{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // 用户 open_id 格式为 ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

---

获取群组/用户 ID

获取群组 ID（chat_id）

1. ✦启动网关并在群组中 @机器人发消息
2. ✦运行 openclaw logs --follow 查看日志中的 chat_id

获取用户 ID（open_id）

1. ✦启动网关并给机器人发消息
2. ✦运行 openclaw logs --follow 查看日志中的 open_id

bash
openclaw pairing list feishu

---

常用命令

注意：飞书目前不支持原生命令菜单，命令需要以文本形式发送。

网关管理命令

---

故障排除

机器人在群组中不响应

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

机器人收不到消息

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

App Secret 泄露怎么办

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

发送消息失败

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

---

高级配置

多账号配置

json5
{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "主机器人",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          botName: "备用机器人",
          enabled: false, // 暂时禁用
        },
      },
    },
  },
}

消息限制

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

流式输出

json5
{
  channels: {
    feishu: {
      streaming: true, // 启用流式卡片输出（默认 true）
      blockStreaming: true, // 启用块级流式（默认 true）
    },
  },
}

消息引用

json5
{
  channels: {
    feishu: {
      // 账户级别配置（默认 "all"）
      replyToMode: "all",
      groups: {
        oc_xxx: {
          // 特定群组可以覆盖
          replyToMode: "first",
        },
      },
    },
  },
}

注意：消息引用功能与流式卡片输出（streaming: true）不能同时使用。当启用流式输出时，回复会以卡片形式呈现，不会显示引用。

多 Agent 路由

json5
{
  agents: {
    list: [
      { id: "main" },
      {
        id: "clawd-fan",
        workspace: "/home/user/clawd-fan",
        agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
      },
      {
        id: "clawd-xi",
        workspace: "/home/user/clawd-xi",
        agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
      },
    ],
  },
  bindings: [
    {
      // 用户 A 的私聊 → main agent
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "dm", id: "ou_28b31a88..." },
      },
    },
    {
      // 用户 B 的私聊 → clawd-fan agent
      agentId: "clawd-fan",
      match: {
        channel: "feishu",
        peer: { kind: "dm", id: "ou_0fe6b1c9..." },
      },
    },
    {
      // 某个群组 → clawd-xi agent
      agentId: "clawd-xi",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_xxx..." },
      },
    },
  ],
}

获取 ID 的方法：参见上文 获取群组/用户 ID 章节。

---

配置参考

---

dmPolicy 策略说明

---

支持的消息类型

接收

• ✦✅ 文本消息
• ✦✅ 富文本（帖子）
• ✦✅ 图片
• ✦✅ 文件
• ✦✅ 音频
• ✦✅ 视频
• ✦✅ 表情包

发送

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