Feishu

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

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

شروع سریع

openclaw channels login --channel feishu

openclaw gateway restart

کنترل دسترسی

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

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

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

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

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 باز کنید، روی آیکن منو در گوشه بالا-راست کلیک کنید، و به Settings بروید. شناسه گروه (chat_id) در صفحه تنظیمات فهرست شده است.

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

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

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)

Streaming

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

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

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

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

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

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

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

نشست‌های ACP

Feishu/Lark از ACP برای پیام‌های مستقیم و پیام‌های رشته گروهی پشتیبانی می‌کند. 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 از گفت‌وگو

در یک پیام مستقیم یا رشته Feishu/Lark:

/acp spawn codex --thread here

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

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

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

{  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" (پیام مستقیم) یا "group" (گفت‌وگوی گروهی)
• match.peer.id: Open ID کاربر (ou_xxx) یا شناسه گروه (oc_xxx)

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

ایزوله‌سازی عامل برای هر کاربر (ایجاد پویای عامل)

dynamicAgentCreation را فعال کنید تا برای هر کاربر پیام مستقیم، نمونه‌های عامل ایزوله به‌صورت خودکار ایجاد شوند. هر کاربر موارد زیر را دریافت می‌کند:

• پوشه کاری مستقل
• USER.md / SOUL.md / MEMORY.md جداگانه
• تاریخچه مکالمه خصوصی
• Skills و وضعیت ایزوله

این برای ربات‌های عمومی ضروری است؛ جایی که می‌خواهید هر کاربر تجربه دستیار AI خصوصی خودش را داشته باشد.

راه‌اندازی سریع

{  channels: {    feishu: {      dmPolicy: "open",      allowFrom: ["*"],      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Critical: makes each user's DM their "main session"    // Automatically loads USER.md / SOUL.md / MEMORY.md    // For stronger isolation, use "per-channel-peer" instead    dmScope: "main",  },}

نحوه کار

وقتی کاربر جدیدی نخستین پیام مستقیم خود را می‌فرستد:

1. کانال یک agentId یکتا تولید می‌کند: feishu-{user_open_id} برای حساب پیش‌فرض، یا یک digest هویت محدود و پیشونددار با حساب برای حساب نام‌دار
2. یک پوشه کاری جدید در مسیر workspaceTemplate ایجاد می‌کند
3. عامل را ثبت می‌کند و برای این کاربر یک اتصال می‌سازد
4. کمک‌کننده پوشه کاری در نخستین دسترسی وجود فایل‌های راه‌اندازی اولیه (AGENTS.md، SOUL.md، USER.md و غیره) را تضمین می‌کند
5. همه پیام‌های آینده از این کاربر را به عامل اختصاصی او هدایت می‌کند

گزینه‌های پیکربندی

متغیرهای قالب:

• {agentId} - شناسه عامل تولیدشده (مثلاً feishu-ou_xxxxxx یا feishu-support-<identity_digest>)
• {userId} - open_id فرستنده در Feishu (مثلاً ou_xxxxxx)

دامنه نشست

session.dmScope کنترل می‌کند پیام‌های مستقیم چگونه به نشست‌های عامل نگاشت شوند. این یک تنظیم سراسری است که روی همه کانال‌ها اثر می‌گذارد.

مصالحه: استفاده از "main" بارگذاری خودکار فایل‌های راه‌انداز (USER.md، SOUL.md، MEMORY.md) را فعال می‌کند، اما یعنی همه پیام‌های مستقیم در همه کانال‌ها الگوی کلید نشست یکسانی را به اشتراک می‌گذارند. برای ربات‌های عمومی چندکاربره که جداسازی در آن‌ها مهم‌تر از بارگذاری خودکار راه‌انداز است، "per-channel-peer" را در نظر بگیرید و فایل‌های راه‌انداز را دستی مدیریت کنید.

{  session: {    // For single-user personal bots: enables auto bootstrap loading    dmScope: "main",     // For public multi-user bots: stronger isolation    // dmScope: "per-channel-peer",  },}

استقرار معمول چندکاربره

{  channels: {    feishu: {      appId: "cli_xxx",      appSecret: "xxx",      dmPolicy: "open",      allowFrom: ["*"],      groupPolicy: "open",      requireMention: true,      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Choose dmScope based on your isolation needs:    // "main" for bootstrap auto-loading, "per-channel-peer" for stronger isolation    dmScope: "main",  },  bindings: [], // Empty - dynamic agents auto-bind}

راستی‌آزمایی

لاگ‌های Gateway را بررسی کنید تا تأیید شود ایجاد پویا کار می‌کند:

feishu: creating dynamic agent "feishu-ou_xxxxxx" for user ou_xxxxxxworkspace: /Users/you/.openclaw/workspace-feishu-ou_xxxxxxfeishu: dynamic agent created, new route: agent:feishu-ou_xxxxxx:main

فهرست همه فضاهای کاری ایجادشده:

ls -la ~/.openclaw/workspace-*

نکات

• جداسازی فضای کاری: هر کاربر پوشه فضای کاری و نمونه عامل خودش را می‌گیرد. کاربران در جریان عادی پیام‌رسانی نمی‌توانند تاریخچه مکالمه یا فایل‌های یکدیگر را ببینند.
• مرز امنیتی: این یک سازوکار جداسازی زمینه پیام‌رسانی است، نه یک مرز امنیتی برای هم‌مستأجر متخاصم. فرایند عامل و محیط میزبان مشترک هستند.
• bindings باید خالی باشد: عامل‌های پویا اتصال‌های خودشان را خودکار ثبت می‌کنند
• مسیر ارتقا: اتصال‌های دستی موجود در کنار عامل‌های پویا همچنان کار می‌کنند
• session.dmScope سراسری است: این روی همه کانال‌ها اثر می‌گذارد، نه فقط Feishu

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

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

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

دریافت

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

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

ارسال

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

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

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

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

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

مرتبط

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