Feishu

يتصل OpenClaw بمنصة Feishu/Lark (منصة التعاون المتكاملة) من خلال Plugin الرسمي @openclaw/feishu: الرسائل المباشرة مع البوت، ومحادثات المجموعات، وردود البطاقات المتدفقة، وأدوات مستندات Feishu والويكي والتخزين السحابي وBitable.

الحالة: جاهز للإنتاج للرسائل المباشرة مع البوت ومحادثات المجموعات. يُعد WebSocket وسيلة نقل الأحداث الافتراضية (ولا يلزم عنوان URL عام)؛ ووضع Webhook اختياري.

البدء السريع

openclaw channels login --channel feishu

openclaw gateway restart

التحكم في الوصول

الرسائل المباشرة

اضبط channels.feishu.dmPolicy (الافتراضي: pairing) للتحكم في مَن يمكنه إرسال رسالة مباشرة إلى البوت:

الموافقة على طلب إقران:

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

محادثات المجموعات

سياسة المجموعة (channels.feishu.groupPolicy، الافتراضي: allowlist):

اشتراط الإشارة (channels.feishu.requireMention):

• الافتراضي: يلزم توجيه @إشارة، إلا عندما تكون سياسة المجموعة الفعلية هي "open"؛ إذ تكون القيمة الافتراضية هناك false كي تظل الرسائل التي لا يمكن أن تتضمن إشارات (مثل الصور) تصل إلى الوكيل.
• اضبط true أو false صراحةً للتجاوز؛ والتجاوز لكل مجموعة هو: channels.feishu.groups.<chat_id>.requireMention.
• لا تُعامل إشارتا البث فقط @all و@_all على أنهما إشارتان إلى البوت. وتظل الرسالة التي تشير إلى كل من @all والبوت مباشرةً محسوبةً كإشارة إلى البوت.

أمثلة على إعداد المجموعات

السماح بجميع المجموعات، دون اشتراط @إشارة

{  channels: {    feishu: {      groupPolicy: "open", // القيمة الافتراضية لـ requireMention هي false ضمن "open"    },  },}

السماح بجميع المجموعات، مع استمرار اشتراط @إشارة

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

السماح بمجموعات محددة فقط

{  channels: {    feishu: {      groupPolicy: "allowlist",      // تبدو معرّفات المجموعات على النحو التالي: oc_xxx      groupAllowFrom: ["oc_xxx", "oc_yyy"],    },  },}

في وضع allowlist، يمكنك أيضًا قبول مجموعة بإضافة إدخال groups.<chat_id> صريح. لا تتجاوز الإدخالات الصريحة groupPolicy: "disabled". تضبط الإعدادات الافتراضية ذات حرف البدل ضمن groups.* المجموعات المطابقة، لكنها لا تقبل المجموعات بمفردها.

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

تقييد المرسلين داخل مجموعة

{  channels: {    feishu: {      groupPolicy: "allowlist",      groupAllowFrom: ["oc_xxx"],      groups: {        oc_xxx: {          // تبدو قيم open_id للمستخدمين على النحو التالي: ou_xxx          allowFrom: ["ou_user1", "ou_user2"],        },      },    },  },}

يضبط channels.feishu.groupSenderAllowFrom قائمة السماح نفسها للمرسلين في جميع المجموعات؛ ويكون لـ allowFrom الخاص بكل مجموعة الأولوية.

الحصول على معرّفات المجموعات والمستخدمين

معرّفات المجموعات (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. تأكد من توجيه @إشارة إلى البوت (مطلوب افتراضيًا)
3. تحقق من أن groupPolicy ليس "disabled"
4. تحقق من السجلات: openclaw logs --follow

لا يتلقى البوت الرسائل

1. تأكد من نشر البوت والموافقة عليه في Feishu Open Platform / Lark Developer
2. تأكد من أن اشتراك الأحداث يتضمن im.message.receive_v1
3. تأكد من تحديد persistent connection ‏(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: "البوت الأساسي",          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },        backup: {          appId: "cli_yyy",          appSecret: "yyy",          name: "البوت الاحتياطي",          enabled: false,        },      },    },  },}

يتحكم defaultAccount في الحساب المستخدم عندما لا تحدد واجهات API الصادرة accountId. ترث إدخالات الحساب إعدادات المستوى الأعلى؛ ويمكن تجاوز معظم مفاتيح المستوى الأعلى لكل حساب. يستخدم accounts.<id>.tts البنية نفسها التي يستخدمها messages.tts، ويُدمج بعمق فوق إعداد TTS العام، بحيث يمكن لإعدادات Feishu متعددة البوتات إبقاء بيانات اعتماد المزوّد المشتركة عامةً مع تجاوز الصوت أو النموذج أو الشخصية أو الوضع التلقائي فقط لكل حساب.

حدود الرسائل

• textChunkLimit - حجم جزء النص الصادر (الافتراضي: 4000 حرفًا)
• streaming.chunkMode - يقسم "length" (الافتراضي) عند الحد؛ ويفضل "newline" حدود الأسطر الجديدة
• mediaMaxMb - حد رفع الوسائط وتنزيلها (الافتراضي: 30 ميغابايت)

التدفق

يدعم Feishu/Lark الردود المتدفقة عبر البطاقات التفاعلية (واجهة Card Kit للتدفق). عند التمكين، يحدّث البوت البطاقة في الوقت الفعلي أثناء إنشاء النص.

{  channels: {    feishu: {      streaming: {        mode: "partial", // مخرجات بطاقة متدفقة (الافتراضي: "partial")        block: { enabled: true }, // الاشتراك في تدفق الكتل المكتملة      },    },  },}

اضبط streaming.mode: "off" لإرسال الرد الكامل في رسالة واحدة؛ كما يعطّل renderMode: "raw" (نص عادي بدلًا من البطاقات) البطاقات المتدفقة. يكون streaming.block.enabled معطلًا افتراضيًا؛ ولا تمكّنه إلا عندما تريد إرسال كتل المساعد المكتملة قبل الرد النهائي. تُرحّل القيمة المنطقية القديمة streaming والمفاتيح المسطحة blockStreaming / blockStreamingCoalesce / chunkMode إلى هذه البنية المتداخلة عبر openclaw doctor --fix.

تحسين الحصة

قلّل عدد استدعاءات API الخاصة بـ Feishu/Lark باستخدام علامتين اختياريتين:

• typingIndicator (الافتراضي true): اضبط false لتخطي استدعاءات تفاعل الكتابة
• resolveSenderNames (الافتراضي true): اضبط false لتخطي عمليات البحث عن الملف الشخصي للمرسل

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

نطاق جلسة المجموعة وسلاسل المواضيع

يتحكم channels.feishu.groupSessionScope (على المستوى الأعلى أو لكل حساب أو لكل مجموعة) في كيفية تعيين رسائل المجموعة إلى جلسات الوكيل:

بالنسبة إلى نطاقات المواضيع، تستخدم مجموعات المواضيع الأصلية في Feishu/Lark الحدث thread_id ‏(omt_*) بوصفه مفتاح جلسة الموضوع الأساسي. إذا أغفل حدث بدء موضوع أصلي thread_id، فإن OpenClaw يجلبه من Feishu قبل توجيه الدور. تواصل ردود المجموعات العادية التي يحولها OpenClaw إلى سلاسل استخدام معرّف الرسالة الجذرية للرد (om_*) كي يظل الدور الأول والأدوار اللاحقة في الجلسة نفسها.

اضبط replyInThread: "enabled" (على المستوى الأعلى أو لكل مجموعة) لجعل ردود البوت تنشئ سلسلة موضوع في Feishu أو تتابعها بدلًا من الرد داخل السياق. يُعد topicSessionMode السلف المهمل لـ groupSessionScope؛ ويُفضّل groupSessionScope.

أدوات مساحة عمل Feishu

يوفر Plugin أدوات للوكيل خاصة بمستندات Feishu والمحادثات وقاعدة المعرفة والتخزين السحابي والأذونات وBitable، بالإضافة إلى Skills المطابقة (feishu-doc، feishu-drive، feishu-perm، feishu-wiki). تخضع عائلات الأدوات للتحكم بواسطة channels.feishu.tools:

يمثل tools.base اسمًا مستعارًا لـ tools.bitable؛ وتتغلب قيمة bitable الصريحة عند تعيين كليهما. توجد بوابات كل حساب ضمن accounts.<id>.tools.

امنح drive:drive.metadata:readonly لإجراء عمليات بحث مباشرة عن feishu_drive info خارج الدليل الجذر، ما لم يكن التطبيق يمتلك بالفعل نطاق drive:drive الكامل. من دون أيٍّ من النطاقين، يُبقي info البحث القديم في الدليل الجذر متاحًا عبر drive:drive:readonly.

جلسات 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)

راجع الحصول على معرّفات المجموعة/المستخدم للاطلاع على نصائح البحث.

عزل الوكيل لكل مستخدم (إنشاء الوكيل الديناميكي)

فعّل dynamicAgentCreation لإنشاء نسخ وكلاء معزولة تلقائيًا لكل مستخدم للرسائل المباشرة. يحصل كل مستخدم على ما يلي:

• دليل مساحة عمل مستقل
• USER.md / SOUL.md / MEMORY.md منفصلة
• سجل محادثات خاص
• Skills وحالة معزولتان

هذا ضروري للروبوتات العامة عندما تريد أن يحظى كل مستخدم بتجربة مساعد ذكاء اصطناعي خاصة به.

الإعداد السريع

{  channels: {    feishu: {      dmPolicy: "open",      allowFrom: ["*"],      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // مهم: يجعل الرسائل المباشرة لكل مستخدم «جلسته الرئيسية»    // يحمّل USER.md / SOUL.md / MEMORY.md تلقائيًا    // لعزل أقوى، استخدم "per-channel-peer" بدلًا منه    dmScope: "main",  },}

آلية العمل

عندما يرسل مستخدم جديد رسالته المباشرة الأولى:

1. تُنشئ القناة agentId فريدًا: feishu-{user_open_id} للحساب الافتراضي، أو ملخص هوية محدودًا مسبوقًا بالحساب لحساب مُسمّى
2. تُنشئ مساحة عمل جديدة في مسار workspaceTemplate
3. تُسجّل الوكيل وتُنشئ ارتباطًا لهذا المستخدم
4. يضمن مساعد مساحة العمل وجود ملفات التمهيد (AGENTS.md وSOUL.md وUSER.md وغيرها) عند الوصول الأول
5. تُوجّه جميع الرسائل المستقبلية من هذا المستخدم إلى وكيله المخصص

خيارات الإعداد

متغيرات القالب:

• {agentId} - معرّف الوكيل المُنشأ (مثل feishu-ou_xxxxxx أو feishu-support-<identity_digest>)
• {userId} - معرّف Feishu المفتوح للمرسل (مثل ou_xxxxxx)

نطاق الجلسة

يتحكم session.dmScope في كيفية ربط الرسائل المباشرة بجلسات الوكيل. هذا إعداد عام يؤثر في جميع القنوات.

المقايضة: يتيح استخدام "main" التحميل التلقائي لملفات التمهيد (USER.md وSOUL.md وMEMORY.md)، لكنه يعني أن جميع الرسائل المباشرة عبر جميع القنوات تشترك في نمط مفتاح الجلسة نفسه. بالنسبة إلى الروبوتات العامة متعددة المستخدمين التي يكون فيها العزل أهم من التحميل التلقائي لملفات التمهيد، يُنصح باستخدام "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: {    // اختر dmScope بناءً على احتياجات العزل لديك:    // "main" للتحميل التلقائي للتهيئة الأولية، و"per-channel-peer" لعزل أقوى    dmScope: "main",  },  bindings: [], // فارغة - ترتبط الوكلاء الديناميكيون تلقائيًا}

التحقق

تحقق من سجلات Gateway للتأكد من أن الإنشاء الديناميكي يعمل:

feishu: جارٍ إنشاء الوكيل الديناميكي "feishu-ou_xxxxxx" للمستخدم ou_xxxxxx  مساحة العمل: /home/user/.openclaw/workspace-feishu-ou_xxxxxx  دليل الوكيل: /home/user/.openclaw/agents/feishu-ou_xxxxxx/agent

اعرض جميع مساحات العمل التي أُنشئت:

ls -la ~/.openclaw/workspace-*

ملاحظات

• عزل مساحة العمل: يحصل كل مستخدم على دليل مساحة عمل ومثيل وكيل خاصين به. لا يمكن للمستخدمين رؤية سجل محادثات بعضهم أو ملفاتهم ضمن تدفق المراسلة المعتاد.
• حدود الأمان: هذه آلية لعزل سياق المراسلة، وليست حدود أمان بين مستأجرين مشتركين عدائيين. تشترك الحسابات في عملية الوكيل وبيئة المضيف.
• يجب إبقاء الكتابة إلى الإعدادات مفعّلة: يكتب إنشاء الوكلاء الديناميكيين الوكلاء والارتباطات في الإعدادات؛ ويُتخطى عندما تكون channels.feishu.configWrites بالقيمة false (الافتراضي: مفعّل).
• يجب أن يكون bindings فارغًا: تسجّل الوكلاء الديناميكية ارتباطاتها تلقائيًا
• مسار الترقية: تستمر الارتباطات اليدوية الحالية في العمل إلى جانب الوكلاء الديناميكيين
• session.dmScope عام: يؤثر هذا في جميع القنوات، وليس Feishu فقط

مرجع الإعدادات

الإعدادات الكاملة: إعدادات Gateway

أنواع الرسائل المدعومة

الاستقبال

• ✅ النص
• ✅ النص المنسّق (منشور)
• ✅ الصور
• ✅ الملفات
• ✅ الصوت
• ✅ الفيديو/الوسائط
• ✅ الملصقات

تُطبَّع رسائل 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 وغيرها من صيغ الصوت المحتملة إلى Ogg/Opus بتردد 48kHz باستخدام ffmpeg فقط عندما يطلب الرد التسليم الصوتي (audioAsVoice / أداة الرسائل asVoice، بما في ذلك ردود الملاحظات الصوتية عبر TTS). تظل مرفقات MP3 العادية ملفات عادية. إذا كان ffmpeg مفقودًا أو فشل التحويل، يعود OpenClaw إلى استخدام مرفق ملف ويسجّل السبب.

سلاسل المواضيع والردود

• ✅ الردود المضمنة
• ✅ الردود ضمن سلاسل المواضيع
• ✅ تظل ردود الوسائط مرتبطة بسلسلة الموضوع عند الرد على رسالة ضمن سلسلة

تُغطّى آلية توجيه جلسات مجموعات المواضيع ضمن نطاق جلسة المجموعة وسلاسل المواضيع.

ذو صلة

• نظرة عامة على القنوات - جميع القنوات المدعومة
• الإقران - مصادقة الرسائل المباشرة وتدفق الإقران
• المجموعات - سلوك الدردشة الجماعية وتقييد الإشارات
• توجيه القنوات - توجيه جلسات الرسائل
• الأمان - نموذج الوصول والتقوية