Zalo شخصی

وضعیت: آزمایشی. این یکپارچه‌سازی یک حساب شخصی Zalo را از طریق zca-js بومی، درون‌فرایندی و بدون باینری CLI خارجی خودکار می‌کند.

نصب

Zalo Personal یک Plugin خارجی رسمی است و همراه هسته ارائه نمی‌شود. پیش از استفاده آن را نصب کنید:

openclaw plugins install @openclaw/zalouser

• سنجاق‌کردن یک نسخه: openclaw plugins install @openclaw/zalouser@<version>
• از یک نسخه دریافت‌شده از منبع: openclaw plugins install ./path/to/local/zalouser-plugin
• جزئیات: Pluginها

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

1. Plugin را نصب کنید (در بالا).
2. وارد شوید (با QR، روی دستگاه Gateway):
   • openclaw channels login --channel zalouser
   • کد QR را با برنامه موبایل Zalo اسکن کنید.
3. کانال را فعال کنید:

{  channels: {    zalouser: {      enabled: true,      dmPolicy: "pairing",    },  },}

4. Gateway را راه‌اندازی مجدد کنید (یا راه‌اندازی را به پایان برسانید).
5. دسترسی پیام مستقیم به‌طور پیش‌فرض از جفت‌سازی استفاده می‌کند؛ در نخستین تماس، کد جفت‌سازی را تأیید کنید.

چیست

• به‌طور کامل و درون‌فرایندی از طریق کتابخانه zca-js اجرا می‌شود (بدون باینری خارجی zca/openzca).
• برای دریافت پیام‌های ورودی از شنونده‌های رویداد بومی (message، error) استفاده می‌کند.
• پاسخ‌ها را مستقیماً از طریق API جاوااسکریپت ارسال می‌کند (متن/رسانه/پیوند).
• برای موارد استفاده «حساب شخصی» طراحی شده است که API ربات Zalo در دسترس نیست.

نام‌گذاری

شناسه کانال zalouser است تا صریحاً نشان دهد که این یک حساب کاربری شخصی Zalo را خودکار می‌کند (غیررسمی). zalo برای یکپارچه‌سازی رسمی احتمالی با API ‏Zalo در آینده رزرو شده است.

یافتن شناسه‌ها (دایرکتوری)

openclaw directory self --channel zalouseropenclaw directory peers list --channel zalouser --query "name"openclaw directory groups list --channel zalouser --query "work"

محدودیت‌ها

• متن خروجی به قطعه‌های 2000 نویسه‌ای تقسیم می‌شود (محدودیت کلاینت Zalo).
• پخش جریانی پشتیبانی نمی‌شود.
• شناسه‌های پیام ورودی تکمیل‌شده به‌مدت 30 روز نگه‌داری می‌شوند و برای هر حساب به 1000 ورودی اخیر محدود هستند.

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

OpenClaw هر فراخوان برگشتی خام پیام zca-js را پیش از پردازش ذخیره می‌کند. پیام‌های معلق پس از راه‌اندازی مجدد Gateway از صف حساب از سر گرفته می‌شوند و پردازش برای هر گفت‌وگوی مستقیم یا گروه به‌صورت ترتیبی باقی می‌ماند.

شنونده سوکت zca-js تأیید تحویل را ارائه نمی‌دهد و پیام‌های قدیمی را نیز پس از اتصال مجدد به‌طور خودکار بازپخش نمی‌کند. بنابراین، صف ماندگار از بازه خرابی محلی پس از رسیدن یک فراخوان برگشتی به OpenClaw محافظت می‌کند؛ اما نمی‌تواند پیامی را که سوکت هرگز تحویل نداده است بازیابی کند. سنگ‌قبرهای بازپخش عمدتاً حفاظی در برابر تکرار فراخوان برگشتی با همان شناسه پیام Zalo هستند.

کنترل دسترسی (پیام‌های مستقیم)

channels.zalouser.dmPolicy: pairing | allowlist | open | disabled (پیش‌فرض: pairing).

channels.zalouser.allowFrom باید از شناسه‌های پایدار کاربر Zalo استفاده کند. همچنین می‌تواند به گروه‌های ثابت دسترسی فرستنده (accessGroup:<name>) ارجاع دهد. هنگام راه‌اندازی تعاملی، نام‌های واردشده را می‌توان با استفاده از جست‌وجوی درون‌فرایندی مخاطبان Plugin به شناسه تبدیل کرد.

اگر نامی خام در پیکربندی باقی بماند، هنگام راه‌اندازی فقط در صورتی تبدیل می‌شود که channels.zalouser.dangerouslyAllowNameMatching: true فعال باشد. بدون این انتخاب صریح، بررسی فرستنده هنگام اجرا فقط بر اساس شناسه انجام می‌شود و نام‌های خام برای مجوزدهی نادیده گرفته می‌شوند.

تأیید از طریق:

• openclaw pairing list zalouser
• openclaw pairing approve zalouser <code>

دسترسی گروهی (اختیاری)

• پیش‌فرض: channels.zalouser.groupPolicy = "allowlist" (گروه‌ها به یک ورودی صریح در فهرست مجاز نیاز دارند).
• بازکردن همه گروه‌ها: channels.zalouser.groupPolicy = "open".
• مسدودکردن همه گروه‌ها: channels.zalouser.groupPolicy = "disabled".
• با groupPolicy = "allowlist":
  • کلیدهای channels.zalouser.groups باید شناسه‌های پایدار گروه باشند؛ نام‌ها هنگام راه‌اندازی فقط در صورتی به شناسه تبدیل می‌شوند که channels.zalouser.dangerouslyAllowNameMatching: true فعال باشد.
  • channels.zalouser.groupAllowFrom تعیین می‌کند کدام فرستندگان در گروه‌های مجاز می‌توانند ربات را فعال کنند؛ گروه‌های ثابت دسترسی فرستنده را می‌توان با accessGroup:<name> ارجاع داد.
• جادوگر پیکربندی می‌تواند فهرست‌های مجاز گروه را درخواست کند.
• تطبیق فهرست مجاز گروه به‌طور پیش‌فرض فقط بر اساس شناسه انجام می‌شود. نام‌های تبدیل‌نشده برای احراز مجوز نادیده گرفته می‌شوند، مگر آنکه channels.zalouser.dangerouslyAllowNameMatching: true فعال باشد.
• channels.zalouser.dangerouslyAllowNameMatching: true یک حالت سازگاری اضطراری است که تبدیل تغییرپذیر نام هنگام راه‌اندازی و تطبیق نام گروه هنگام اجرا را دوباره فعال می‌کند.
• groupAllowFrom برای پیام‌های عادی گروه به allowFrom بازنمی‌گردد: خالی‌گذاشتن آن در یک گروه موجود در فهرست مجاز، آن گروه را برای هر فرستنده‌ای باز می‌کند. فرمان‌های کنترلی مجاز (برای مثال /new) استثنا هستند؛ هنگامی که groupAllowFrom خالی باشد، بررسی فرستنده فرمان به allowFrom بازمی‌گردد.

مثال:

{  channels: {    zalouser: {      groupPolicy: "allowlist",      groupAllowFrom: ["1471383327500481391"],      groups: {        "123456789": { enabled: true },        "Work Chat": { enabled: true },      },    },  },}

محدودسازی بر اساس اشاره در گروه

• channels.zalouser.groups.<group>.requireMention تعیین می‌کند آیا پاسخ‌های گروه به اشاره نیاز دارند یا نه.
• ترتیب تبدیل: شناسه گروه -> نام مستعار group:<id> -> نام/نامک گروه (نامزدهای مبتنی بر نام فقط وقتی اعمال می‌شوند که dangerouslyAllowNameMatching: true) -> * -> پیش‌فرض (true).
• هم برای گروه‌های موجود در فهرست مجاز و هم برای حالت گروه باز اعمال می‌شود.
• نقل‌قول‌کردن پیام ربات برای فعال‌سازی گروه، اشاره ضمنی محسوب می‌شود.
• فرمان‌های کنترلی مجاز (برای مثال /new) می‌توانند محدودسازی بر اساس اشاره را دور بزنند.
• وقتی پیام گروهی به‌دلیل الزامی‌بودن اشاره نادیده گرفته شود، OpenClaw آن را به‌عنوان تاریخچه معلق گروه ذخیره می‌کند و در پیام گروهی پردازش‌شده بعدی می‌گنجاند.
• محدودیت تاریخچه گروه: channels.zalouser.historyLimit، سپس messages.groupChat.historyLimit، و پس از آن مقدار جایگزین 50.

مثال:

{  channels: {    zalouser: {      groupPolicy: "allowlist",      groups: {        "*": { enabled: true, requireMention: true },        "Work Chat": { enabled: true, requireMention: false },      },    },  },}

چندحسابی

حساب‌ها به پروفایل‌های zalouser در وضعیت OpenClaw نگاشت می‌شوند. مثال:

{  channels: {    zalouser: {      enabled: true,      defaultAccount: "default",      accounts: {        work: { enabled: true, profile: "work" },      },    },  },}

متغیرهای محیطی

انتخاب پروفایل می‌تواند از متغیرهای محیطی نیز انجام شود:

نام پروفایل، اعتبارنامه‌های ذخیره‌شده ورود به Zalo را در وضعیت OpenClaw انتخاب می‌کند. ترتیب تبدیل:

1. profile صریح در پیکربندی.
2. ZALOUSER_PROFILE.
3. ZCA_PROFILE.
4. شناسه حساب برای حساب‌های غیراصلی، یا default برای حساب پیش‌فرض.

برای راه‌اندازی‌های چندحسابی، ترجیحاً profile را برای هر حساب در پیکربندی تنظیم کنید تا یک متغیر محیطی باعث نشود چند حساب نشست ورود یکسانی را به اشتراک بگذارند.

وضعیت تایپ، واکنش‌ها و تأییدهای تحویل

• OpenClaw پیش از ارسال پاسخ، یک رویداد تایپ ارسال می‌کند (به‌صورت تلاش در حد امکان).
• کنش واکنش به پیام react برای zalouser در کنش‌های کانال پشتیبانی می‌شود.
  • برای حذف یک ایموجی واکنش مشخص از پیام، از remove: true استفاده کنید.
  • معنای واکنش‌ها: واکنش‌ها
• برای پیام‌های ورودی دارای فراداده رویداد، OpenClaw تأییدهای تحویل‌شده و دیده‌شده را ارسال می‌کند (به‌صورت تلاش در حد امکان).

عیب‌یابی

ورود پایدار نمی‌ماند:

• openclaw channels status --probe
• ورود مجدد: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

نام فهرست مجاز/گروه تبدیل نشد:

• از شناسه‌های عددی در allowFrom/groupAllowFrom و شناسه‌های پایدار گروه در groups استفاده کنید. اگر عمداً به نام دقیق دوست/گروه نیاز دارید، channels.zalouser.dangerouslyAllowNameMatching: true را فعال کنید.

از یک راه‌اندازی قدیمی مبتنی بر zca/CLI خارجی ارتقا داده‌اید:

• هرگونه فرض مربوط به فرایند خارجی zca را حذف کنید؛ کانال اکنون به‌طور کامل و درون‌فرایندی از طریق zca-js و بدون باینری CLI خارجی اجرا می‌شود.

مرتبط

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