Tại Sao Feishu?
Feishu (飞书), được biết đến quốc tế là Lark, là nền tảng cộng tác doanh nghiệp của ByteDance — được sử dụng rộng rãi trong các công ty công nghệ Trung Quốc, startup, và ngày càng nhiều ở Đông Nam Á. Với OpenClaw v2026.2.2, Feishu trở thành ứng dụng chat Trung Quốc đầu tiên được hỗ trợ chính thức.
- •Không cần URL công khai — không cần ngrok, không cần tên miền, không cần webhook server
- •Hoạt động sau tường lửa — kết nối là outbound từ máy của bạn
- •Độ trễ thấp — nhắn tin hai chiều thời gian thực
- •Hỗ trợ nội dung phong phú — văn bản, hình ảnh, tệp, âm thanh, video, và sticker
Yêu Cầu Tiên Quyết
- •OpenClaw v2026.2.2 hoặc mới hơn
- •Tài khoản doanh nghiệp Feishu/Lark (gói miễn phí hoạt động được)
- •Quyền admin để tạo ứng dụng trên Feishu Open Platform
Bước 1: Tạo Ứng Dụng Feishu
- 1.Truy cập Feishu Open Platform (hoặc Lark Developer Console cho tenant quốc tế)
- 2.Nhấp Create Custom App
- 3.Đặt tên ứng dụng (ví dụ: "OpenClaw Agent") và mô tả
- 4.Tải lên biểu tượng (logo tôm hùm OpenClaw rất phù hợp)
- 5.Sao chép App ID (định dạng:
cli_xxx) và App Secret từ trang Credentials
Bước 2: Cấu Hình Quyền Ứng Dụng
Trong cài đặt quyền ứng dụng, bật các scope sau:
| Quyền | Mục đích |
|---|---|
im:message | Gửi và nhận tin nhắn |
im:message.group_at_msg | Nhận @mention trong chat nhóm |
im:resource | Truy cập hình ảnh và tệp |
contact:user.id:readonly | Xác định người dùng |
Sau khi thêm quyền, nhấp Publish để gửi xét duyệt. Trong hầu hết các tenant doanh nghiệp, ứng dụng tự xây được tự động phê duyệt.
Bước 3: Bật Đăng Ký Sự Kiện
- 1.Trong cài đặt ứng dụng, vào Event Subscriptions
- 2.Chọn WebSocket Mode (kết nối dài) — điều này rất quan trọng. KHÔNG sử dụng chế độ webhook, vì nó yêu cầu URL công khai.
- 3.Đăng ký các sự kiện:
Bước 4: Cấu Hình OpenClaw
Thêm thông tin xác thực Feishu vào cấu hình OpenClaw. Chỉnh sửa ~/.openclaw/.env:
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret_here
Hoặc nếu sử dụng tệp cấu hình OpenClaw (~/.openclaw/config.yaml):
channels:
feishu:
enabled: true
appId: cli_xxxxxxxxxxxxx
appSecret: your_app_secret_here
Khởi động lại OpenClaw:
openclaw restart
Bạn sẽ thấy thông báo nhật ký xác nhận kết nối WebSocket Feishu đã được thiết lập.
Bước 5: Kiểm Tra Kết Nối
Mở Feishu và tìm ứng dụng trong danh sách chat (tìm kiếm tên ứng dụng bạn đặt ở Bước 1). Gửi tin nhắn:
> Xin chào!
- •Tin nhắn văn bản
- •Hình ảnh (tác tử có thể phân tích nếu sử dụng mô hình hỗ trợ thị giác)
- •Tệp (tác tử có thể đọc tài liệu)
- •Tin nhắn thoại (được chuyển đổi và xử lý dưới dạng văn bản)
Cấu Hình Chat Nhóm
OpenClaw hỗ trợ chat nhóm Feishu với ba chế độ truy cập:
| Chế độ | Hành vi |
|---|---|
open (mặc định) | Bất kỳ thành viên nhóm nào đều có thể kích hoạt bot khi @mention |
allowlist | Chỉ người dùng được phê duyệt mới có thể tương tác, ngay cả khi @mention |
disabled | Tin nhắn nhóm bị bỏ qua hoàn toàn |
Cấu hình trong config.yaml:
channels:
feishu:
groupAccess: open # hoặc "allowlist" hoặc "disabled"
allowedUsers: # chỉ dùng với chế độ "allowlist"
- user_id_1
- user_id_2
Trong chat nhóm, tác tử chỉ phản hồi khi được @mention, tránh gây ồn trong các kênh bận rộn.
Phản Hồi Streaming
OpenClaw hỗ trợ streaming phản hồi AI trong Feishu sử dụng interactive cards. Thay vì đợi phản hồi đầy đủ, tác tử gửi một card ban đầu và cập nhật theo thời gian thực khi AI tạo văn bản. Điều này mang lại trải nghiệm người dùng tốt hơn nhiều cho các phản hồi dài.
Streaming được bật mặc định. Để tắt:
channels:
feishu:
streaming: false
Loại Tin Nhắn Được Hỗ Trợ
| Hướng | Loại được hỗ trợ |
|---|---|
| Đầu vào (người dùng → tác tử) | Văn bản, rich text (post), hình ảnh, tệp, âm thanh, video, sticker |
| Đầu ra (tác tử → người dùng) | Văn bản, hình ảnh, tệp, âm thanh, interactive cards |
Xử Lý Sự Cố
Lỗi "App not found": Đảm bảo ứng dụng đã được publish và phê duyệt trong tenant Feishu. Ứng dụng tự xây trong tenant doanh nghiệp thường được tự động phê duyệt, nhưng một số tổ chức yêu cầu phê duyệt admin.
Không có phản hồi từ tác tử: Kiểm tra nhật ký OpenClaw (openclaw logs) để tìm lỗi kết nối WebSocket. Xác minh App ID và App Secret chính xác.
Tin nhắn không đến trong chat nhóm: Đảm bảo bot đã được thêm vào nhóm, và người dùng đang @mention bot đúng cách. Kiểm tra cài đặt groupAccess.
Kết nối bị ngắt: Kết nối WebSocket tự động kết nối lại. Nếu ngắt kết nối thường xuyên, kiểm tra độ ổn định mạng hoặc cài đặt tường lửa.
Sử Dụng Bridge Cộng Đồng (Thay Thế)
Nếu bạn cần các tính năng ngoài tích hợp gốc, feishu-openclaw bridge do cộng đồng duy trì bởi AlexAnys cung cấp khả năng bổ sung như định dạng tin nhắn tùy chỉnh và quản lý nhóm nâng cao. Mất khoảng 5 phút để thiết lập và không cần máy chủ công khai.
Để xem tài liệu đầy đủ, xem hướng dẫn kênh Feishu chính thức.