Feishu

Feishu/Lark یک پلتفرم همکاری همه‌کاره است که در آن تیم‌ها گفتگو می‌کنند، اسناد را به اشتراک می‌گذارند، تقویم‌ها را مدیریت می‌کنند و کارها را با هم انجام می‌دهند.

وضعیت: آمادهٔ تولید برای DMهای ربات + گفتگوهای گروهی. WebSocket حالت پیش‌فرض است؛ حالت webhook اختیاری است.

شروع سریع

openclaw channels login --channel feishu

openclaw gateway restart

کنترل دسترسی

پیام‌های مستقیم

برای کنترل اینکه چه کسی می‌تواند به ربات DM بدهد، dmPolicy را پیکربندی کنید:

• "pairing" - کاربران ناشناس یک کد جفت‌سازی دریافت می‌کنند؛ از طریق CLI تأیید کنید
• "allowlist" - فقط کاربران فهرست‌شده در allowFrom می‌توانند گفتگو کنند (پیش‌فرض: فقط مالک ربات)
• "open" - فقط زمانی DMهای عمومی را مجاز می‌کند که allowFrom شامل "*" باشد؛ با ورودی‌های محدودکننده، فقط کاربران منطبق می‌توانند گفتگو کنند
• "disabled" - همهٔ DMها را غیرفعال می‌کند

تأیید یک درخواست جفت‌سازی:

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

گفتگوهای گروهی

سیاست گروه (channels.feishu.groupPolicy):

پیش‌فرض: allowlist

الزام اشاره (channels.feishu.requireMention):

• true - نیازمند @mention است (پیش‌فرض)
• false - بدون @mention پاسخ می‌دهد
• بازنویسی برای هر گروه: channels.feishu.groups.<chat_id>.requireMention
• @all و @_all که فقط برای پخش همگانی هستند، به‌عنوان اشاره به ربات در نظر گرفته نمی‌شوند. پیامی که هم @all و هم خود ربات را مستقیماً اشاره کند، همچنان به‌عنوان اشاره به ربات شمرده می‌شود.

نمونه‌های پیکربندی گروه

مجاز کردن همهٔ گروه‌ها، بدون نیاز به @mention

{  channels: {    feishu: {      groupPolicy: "open",    },  },}

مجاز کردن همهٔ گروه‌ها، همچنان نیازمند @mention

{  channels: {    feishu: {      groupPolicy: "open",      requireMention: true,    },  },}

فقط مجاز کردن گروه‌های مشخص

{  channels: {    feishu: {      groupPolicy: "allowlist",      // Group IDs look like: oc_xxx      groupAllowFrom: ["oc_xxx", "oc_yyy"],    },  },}

در حالت allowlist، می‌توانید با افزودن یک ورودی صریح groups.<chat_id> نیز یک گروه را بپذیرید. ورودی‌های صریح groupPolicy: "disabled" را بازنویسی نمی‌کنند. پیش‌فرض‌های wildcard زیر groups.* گروه‌های منطبق را پیکربندی می‌کنند، اما به‌تنهایی گروه‌ها را نمی‌پذیرند.

{  channels: {    feishu: {      groupPolicy: "allowlist",      groups: {        oc_xxx: {          requireMention: false,        },      },    },  },}

محدود کردن فرستندگان درون یک گروه

{  channels: {    feishu: {      groupPolicy: "allowlist",      groupAllowFrom: ["oc_xxx"],      groups: {        oc_xxx: {          // User open_ids look like: ou_xxx          allowFrom: ["ou_user1", "ou_user2"],        },      },    },  },}

دریافت شناسه‌های گروه/کاربر

شناسه‌های گروه (chat_id، قالب: oc_xxx)

گروه را در Feishu/Lark باز کنید، روی آیکن منو در گوشهٔ بالا-راست کلیک کنید و به تنظیمات بروید. شناسهٔ گروه (chat_id) در صفحهٔ تنظیمات فهرست شده است.

شناسه‌های کاربر (open_id، قالب: ou_xxx)

Gateway را شروع کنید، یک DM به ربات بفرستید، سپس لاگ‌ها را بررسی کنید:

openclaw logs --follow

در خروجی لاگ به‌دنبال open_id بگردید. همچنین می‌توانید درخواست‌های جفت‌سازی در انتظار را بررسی کنید:

openclaw pairing list feishu

فرمان‌های رایج

عیب‌یابی

ربات در گفتگوهای گروهی پاسخ نمی‌دهد

1. مطمئن شوید ربات به گروه اضافه شده است
2. مطمئن شوید ربات را @mention می‌کنید (به‌صورت پیش‌فرض لازم است)
3. بررسی کنید groupPolicy برابر "disabled" نباشد
4. لاگ‌ها را بررسی کنید: openclaw logs --follow

ربات پیام‌ها را دریافت نمی‌کند

1. مطمئن شوید ربات در Feishu Open Platform / Lark Developer منتشر و تأیید شده است
2. مطمئن شوید اشتراک رویداد شامل im.message.receive_v1 باشد
3. مطمئن شوید اتصال پایدار (WebSocket) انتخاب شده است
4. مطمئن شوید همهٔ دامنه‌های مجوز لازم اعطا شده‌اند
5. مطمئن شوید Gateway در حال اجراست: openclaw gateway status
6. لاگ‌ها را بررسی کنید: openclaw logs --follow

راه‌اندازی QR در برنامهٔ موبایل Feishu واکنش نشان نمی‌دهد

1. راه‌اندازی را دوباره اجرا کنید: openclaw channels login --channel feishu
2. راه‌اندازی دستی را انتخاب کنید
3. در Feishu Open Platform، یک برنامهٔ خودساخته ایجاد کنید و App ID و App Secret آن را کپی کنید
4. آن اعتبارنامه‌ها را در راهنمای راه‌اندازی وارد کنید

App Secret افشا شده است

1. App Secret را در Feishu Open Platform / Lark Developer بازنشانی کنید
2. مقدار را در پیکربندی خود به‌روزرسانی کنید
3. Gateway را دوباره راه‌اندازی کنید: openclaw gateway restart

پیکربندی پیشرفته

چند حساب

{  channels: {    feishu: {      defaultAccount: "main",      accounts: {        main: {          appId: "cli_xxx",          appSecret: "xxx",          name: "Primary bot",          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },        backup: {          appId: "cli_yyy",          appSecret: "yyy",          name: "Backup bot",          enabled: false,        },      },    },  },}

defaultAccount کنترل می‌کند وقتی APIهای خروجی accountId مشخص نمی‌کنند، کدام حساب استفاده شود. accounts.<id>.tts همان شکل messages.tts را استفاده می‌کند و روی پیکربندی سراسری TTS به‌صورت deep-merge اعمال می‌شود، بنابراین راه‌اندازی‌های چندرباتی Feishu می‌توانند اعتبارنامه‌های مشترک ارائه‌دهنده را به‌صورت سراسری نگه دارند و فقط صدا، مدل، persona، یا حالت خودکار را برای هر حساب بازنویسی کنند.

محدودیت‌های پیام

• textChunkLimit - اندازهٔ قطعهٔ متن خروجی (پیش‌فرض: 2000 نویسه)
• mediaMaxMb - محدودیت بارگذاری/دریافت رسانه (پیش‌فرض: 30 MB)

استریمینگ

Feishu/Lark از پاسخ‌های استریمینگ از طریق کارت‌های تعاملی پشتیبانی می‌کند. وقتی فعال باشد، ربات هنگام تولید متن، کارت را در زمان واقعی به‌روزرسانی می‌کند.

{  channels: {    feishu: {      streaming: true, // enable streaming card output (default: true)      blockStreaming: true, // opt into completed-block streaming    },  },}

برای ارسال پاسخ کامل در یک پیام، streaming: false را تنظیم کنید. blockStreaming به‌صورت پیش‌فرض خاموش است؛ فقط زمانی آن را فعال کنید که می‌خواهید بلاک‌های کامل‌شدهٔ دستیار پیش از پاسخ نهایی ارسال شوند.

بهینه‌سازی سهمیه

تعداد فراخوانی‌های API مربوط به Feishu/Lark را با دو پرچم اختیاری کاهش دهید:

• typingIndicator (پیش‌فرض true): برای رد کردن فراخوانی‌های واکنش تایپ، false تنظیم کنید
• resolveSenderNames (پیش‌فرض true): برای رد کردن جست‌وجوهای پروفایل فرستنده، false تنظیم کنید

{  channels: {    feishu: {      typingIndicator: false,      resolveSenderNames: false,    },  },}

نشست‌های ACP

Feishu/Lark از ACP برای DMها و پیام‌های رشتهٔ گروهی پشتیبانی می‌کند. ACP در Feishu/Lark مبتنی بر فرمان متنی است - منوهای بومی فرمان اسلش وجود ندارند، بنابراین از پیام‌های /acp ... مستقیماً در گفتگو استفاده کنید.

اتصال پایدار ACP

{  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" },    },  ],}

ایجاد ACP از گفتگو

در یک DM یا رشتهٔ Feishu/Lark:

/acp spawn codex --thread here

--thread here برای DMها و پیام‌های رشتهٔ Feishu/Lark کار می‌کند. پیام‌های بعدی در گفتگوی متصل‌شده مستقیماً به همان نشست ACP هدایت می‌شوند.

مسیریابی چندعاملی

برای هدایت DMها یا گروه‌های Feishu/Lark به عامل‌های مختلف، از bindings استفاده کنید.

{  agents: {    list: [      { id: "main" },      { id: "agent-a", workspace: "/home/user/agent-a" },      { id: "agent-b", workspace: "/home/user/agent-b" },    ],  },  bindings: [    {      agentId: "agent-a",      match: {        channel: "feishu",        peer: { kind: "direct", id: "ou_xxx" },      },    },    {      agentId: "agent-b",      match: {        channel: "feishu",        peer: { kind: "group", id: "oc_zzz" },      },    },  ],}

فیلدهای مسیریابی:

• match.channel: "feishu"
• match.peer.kind: "direct" (DM) یا "group" (گفتگوی گروهی)
• match.peer.id: Open ID کاربر (ou_xxx) یا شناسهٔ گروه (oc_xxx)

برای نکات جست‌وجو، دریافت شناسه‌های گروه/کاربر را ببینید.

مرجع پیکربندی

پیکربندی کامل: پیکربندی Gateway

نوع‌های پیام پشتیبانی‌شده

دریافت

• ✅ متن
• ✅ متن غنی (post)
• ✅ تصویرها
• ✅ فایل‌ها
• ✅ صدا
• ✅ ویدئو/رسانه
• ✅ استیکرها

پیام‌های صوتی ورودی Feishu/Lark به‌جای JSON خام file_key به‌صورت جای‌نگهدار رسانه نرمال‌سازی می‌شوند. وقتی tools.media.audio پیکربندی شده باشد، OpenClaw منبع یادداشت صوتی را دانلود می‌کند و پیش از نوبت عامل، رونویسی صوتی مشترک را اجرا می‌کند؛ بنابراین عامل رونوشت گفتار را دریافت می‌کند. اگر Feishu متن رونوشت را مستقیماً در payload صوتی شامل کند، همان متن بدون فراخوانی ASR دیگر استفاده می‌شود. بدون ارائه‌دهنده رونویسی صوتی، عامل همچنان یک جای‌نگهدار <media:audio> به‌همراه پیوست ذخیره‌شده را دریافت می‌کند، نه payload خام منبع Feishu.

ارسال

• ✅ متن
• ✅ تصویرها
• ✅ فایل‌ها
• ✅ صدا
• ✅ ویدئو/رسانه
• ✅ کارت‌های تعاملی (از جمله به‌روزرسانی‌های جریانی)
• ⚠️ متن غنی (قالب‌بندی به سبک post؛ از قابلیت‌های کامل نویسندگی Feishu/Lark پشتیبانی نمی‌کند)

حباب‌های صوتی بومی Feishu/Lark از نوع پیام audio در Feishu استفاده می‌کنند و به رسانه بارگذاری‌شده Ogg/Opus (file_type: "opus") نیاز دارند. رسانه‌های موجود .opus و .ogg مستقیماً به‌صورت صدای بومی ارسال می‌شوند. MP3/WAV/M4A و دیگر قالب‌های محتمل صوتی فقط زمانی که پاسخ درخواست تحویل صوتی داشته باشد (audioAsVoice / ابزار پیام asVoice، از جمله پاسخ‌های یادداشت صوتی TTS)، با ffmpeg به Ogg/Opus با 48kHz تبدیل می‌شوند. پیوست‌های معمولی MP3 به‌صورت فایل‌های عادی باقی می‌مانند. اگر ffmpeg موجود نباشد یا تبدیل ناموفق شود، OpenClaw به پیوست فایل برمی‌گردد و دلیل را ثبت می‌کند.

رشته‌ها و پاسخ‌ها

• ✅ پاسخ‌های درون‌خطی
• ✅ پاسخ‌های رشته‌ای
• ✅ پاسخ‌های رسانه‌ای هنگام پاسخ به یک پیام رشته‌ای همچنان از رشته آگاه می‌مانند

برای groupSessionScope: "group_topic" و "group_topic_sender"، گروه‌های موضوعی بومی Feishu/Lark از thread_id رویداد (omt_*) به‌عنوان کلید canonical جلسه موضوع استفاده می‌کنند. اگر یک رویداد آغازگر موضوع بومی thread_id را حذف کند، OpenClaw پیش از مسیریابی نوبت آن را از Feishu hydrate می‌کند. پاسخ‌های عادی گروه که OpenClaw آن‌ها را به رشته تبدیل می‌کند، همچنان از شناسه پیام ریشه پاسخ (om_*) استفاده می‌کنند تا نوبت اول و نوبت پیگیری در همان جلسه بمانند.

مرتبط

• نمای کلی کانال‌ها - همه کانال‌های پشتیبانی‌شده
• جفت‌سازی - احراز هویت DM و جریان جفت‌سازی
• گروه‌ها - رفتار چت گروهی و gate کردن mention
• مسیریابی کانال - مسیریابی جلسه برای پیام‌ها
• امنیت - مدل دسترسی و سخت‌سازی