​

Bot Feishu

​

Plugin đi kèm

openclaw plugins install @openclaw/feishu

​

Bắt đầu nhanh

​

Cách 1: onboarding (khuyến nghị)

openclaw onboard

1. Tạo ứng dụng Feishu và thu thập thông tin xác thực
2. Cấu hình thông tin xác thực ứng dụng trong OpenClaw
3. Khởi động gateway

• openclaw gateway status
• openclaw logs --follow

​

Cách 2: Thiết lập qua CLI

openclaw channels add

• openclaw gateway status
• openclaw gateway restart
• openclaw logs --follow

​

Bước 1: Tạo ứng dụng Feishu

​

1. Mở Feishu Open Platform

​

2. Tạo ứng dụng

1. Nhấn Create enterprise app
2. Điền tên và mô tả ứng dụng
3. Chọn biểu tượng ứng dụng

​

3. Sao chép thông tin xác thực

• App ID (định dạng: cli_xxx)
• App Secret

​

4. Cấu hình quyền

{
  "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:read",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

​

5. Kích hoạt khả năng bot

1. Kích hoạt khả năng bot
2. Đặt tên cho bot

​

6. Cấu hình đăng ký sự kiện

1. Bạn đã chạy openclaw channels add cho Feishu
2. Gateway đang chạy (openclaw gateway status)

1. Chọn Use long connection to receive events (WebSocket)
2. Thêm sự kiện: im.message.receive_v1

​

7. Phát hành ứng dụng

1. Tạo phiên bản trong Version Management & Release
2. Gửi để xem xét và phát hành
3. Chờ phê duyệt từ quản trị viên (ứng dụng doanh nghiệp thường tự động phê duyệt)

​

Bước 2: Cấu hình OpenClaw

​

Cấu hình với trình hướng dẫn (khuyến nghị)

openclaw channels add

​

Cấu hình qua file cấu hình

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "Trợ lý AI của tôi",
        },
      },
    },
  },
}

​

Verification Token và Encrypt Key (chế độ webhook)

1. Trong Feishu Open Platform, mở ứng dụng của bạn
2. Đi tới Development → Events & Callbacks (开发配置 → 事件与回调)
3. Mở tab Encryption (加密策略)
4. Sao chép Verification Token và Encrypt Key

​

Cấu hình qua biến môi trường

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

​

Miền Lark (toàn cầu)

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

​

Cờ tối ưu hóa hạn ngạch

• typingIndicator (mặc định true): khi false, bỏ qua các cuộc gọi phản ứng gõ.
• resolveSenderNames (mặc định true): khi false, bỏ qua các cuộc gọi tra cứu hồ sơ người gửi.

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

​

Bước 3: Khởi động + kiểm tra

​

1. Khởi động gateway

openclaw gateway

​

2. Gửi tin nhắn thử nghiệm

​

3. Phê duyệt ghép đôi

openclaw pairing approve feishu <CODE>

​

Tổng quan

• Kênh bot Feishu: Bot Feishu được quản lý bởi gateway
• Định tuyến quyết định: trả lời luôn quay lại Feishu
• Cách ly phiên: DMs chia sẻ một phiên chính; nhóm được cách ly
• Kết nối WebSocket: kết nối dài qua SDK Feishu, không cần URL công khai

​

Kiểm soát truy cập

​

Tin nhắn trực tiếp

• Mặc định: dmPolicy: "pairing" (người dùng không xác định nhận mã ghép đôi)
• Phê duyệt ghép đôi:
  Sao chép

  Hỏi AI

  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>
  
• Chế độ danh sách cho phép: đặt channels.feishu.allowFrom với các Open ID được phép

​

Chat nhóm

• "open" = cho phép mọi người trong nhóm (mặc định)
• "allowlist" = chỉ cho phép groupAllowFrom
• "disabled" = vô hiệu hóa tin nhắn nhóm

• true = yêu cầu @mention (mặc định)
• false = phản hồi mà không cần đề cập

​

Ví dụ cấu hình nhóm

​

Cho phép tất cả các nhóm, yêu cầu @mention (mặc định)

{
  channels: {
    feishu: {
      groupPolicy: "open",
      // Mặc định requireMention: true
    },
  },
}

​

Cho phép tất cả các nhóm, không yêu cầu @mention

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

​

Chỉ cho phép các nhóm cụ thể

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // ID nhóm Feishu (chat_id) trông như: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

​

Hạn chế người gửi có thể nhắn tin trong nhóm (danh sách cho phép người gửi)

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // ID người dùng Feishu (open_id) trông như: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

​

Lấy ID nhóm/người dùng

​

ID nhóm (chat_id)

1. Khởi động gateway và @mention bot trong nhóm
2. Chạy openclaw logs --follow và tìm chat_id

​

ID người dùng (open_id)

1. Khởi động gateway và nhắn tin trực tiếp cho bot
2. Chạy openclaw logs --follow và tìm open_id

openclaw pairing list feishu

​

Các lệnh thông dụng

Lưu ý: Feishu chưa hỗ trợ menu lệnh gốc, vì vậy các lệnh phải được gửi dưới dạng văn bản.

​

Lệnh quản lý gateway

​

Khắc phục sự cố

​

Bot không phản hồi trong chat nhóm

1. Đảm bảo bot đã được thêm vào nhóm
2. Đảm bảo bạn @mention bot (hành vi mặc định)
3. Kiểm tra groupPolicy không được đặt thành "disabled"
4. Kiểm tra log: openclaw logs --follow

​

Bot không nhận tin nhắn

1. Đảm bảo ứng dụng đã được phát hành và phê duyệt
2. Đảm bảo đăng ký sự kiện bao gồm im.message.receive_v1
3. Đảm bảo kết nối dài đã được kích hoạt
4. Đảm bảo quyền ứng dụng đầy đủ
5. Đảm bảo gateway đang chạy: openclaw gateway status
6. Kiểm tra log: openclaw logs --follow

​

Rò rỉ App Secret

1. Đặt lại App Secret trong Feishu Open Platform
2. Cập nhật App Secret trong cấu hình của bạn
3. Khởi động lại gateway

​

Gửi tin nhắn thất bại

1. Đảm bảo ứng dụng có quyền im:message:send_as_bot
2. Đảm bảo ứng dụng đã được phát hành
3. Kiểm tra log để biết lỗi chi tiết

​

Cấu hình nâng cao

​

Nhiều tài khoản

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "Bot chính",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          botName: "Bot dự phòng",
          enabled: false,
        },
      },
    },
  },
}

​

Giới hạn tin nhắn

• textChunkLimit: kích thước đoạn văn bản outbound (mặc định: 2000 ký tự)
• mediaMaxMb: giới hạn tải lên/tải xuống phương tiện (mặc định: 30MB)

​

Streaming

{
  channels: {
    feishu: {
      streaming: true, // kích hoạt đầu ra thẻ streaming (mặc định true)
      blockStreaming: true, // kích hoạt streaming cấp khối (mặc định true)
    },
  },
}

​

Phiên ACP

• DMs
• cuộc trò chuyện chủ đề nhóm

​

Ràng buộc ACP liên tục

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "direct", id: "ou_1234567890" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
      },
      acp: { label: "codex-feishu-topic" },
    },
  ],
}

​

Khởi tạo ACP từ chat

/acp spawn codex --thread here

• --thread here hoạt động cho DMs và chủ đề Feishu.
• Tin nhắn tiếp theo trong DM/chủ đề được ràng buộc sẽ chuyển trực tiếp đến phiên ACP đó.
• v1 không nhắm mục tiêu các nhóm không phải chủ đề chung.

​

Định tuyến nhiều tác nhân

{
  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: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "clawd-fan",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_yyy" },
      },
    },
    {
      agentId: "clawd-xi",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}

• match.channel: "feishu"
• match.peer.kind: "direct" hoặc "group"
• match.peer.id: Open ID người dùng (ou_xxx) hoặc ID nhóm (oc_xxx)

​

Tham khảo cấu hình

​

Tham khảo dmPolicy

​

Các loại tin nhắn được hỗ trợ

​

Nhận

• ✅ Văn bản
• ✅ Văn bản phong phú (post)
• ✅ Hình ảnh
• ✅ Tệp
• ✅ Âm thanh
• ✅ Video/phương tiện
• ✅ Nhãn dán

​

Gửi

• ✅ Văn bản
• ✅ Hình ảnh
• ✅ Tệp
• ✅ Âm thanh
• ✅ Video/phương tiện
• ✅ Thẻ tương tác
• ⚠️ Văn bản phong phú (định dạng kiểu post và thẻ, không phải các tính năng tạo nội dung Feishu tùy ý)

​

Chủ đề và trả lời

• ✅ Trả lời nội tuyến
• ✅ Trả lời theo chủ đề nơi Feishu cung cấp reply_in_thread
• ✅ Trả lời phương tiện giữ nguyên nhận thức chủ đề khi trả lời tin nhắn trong chủ đề

​

Bề mặt hành động runtime

• send
• read
• edit
• thread-reply
• pin
• list-pins
• unpin
• member-info
• channel-info
• channel-list
• react và reactions khi các phản ứng được bật trong cấu hình