---
read_when:
    - راه‌اندازی Zalo Personal برای OpenClaw
    - اشکال‌زدایی ورود به حساب یا جریان پیام در Zalo Personal
summary: پشتیبانی از حساب شخصی Zalo از طریق zca-js بومی (ورود با کد QR)، قابلیت‌ها و پیکربندی
title: Zalo شخصی
x-i18n:
    generated_at: "2026-07-27T16:19:06Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 09cecad1a9a5b34b932c5e68e2b3164b360fb6af1dcd2fd5b5979d1b2a1bd62b
    source_path: channels/zalouser.md
    workflow: 16
---

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

<Warning>
این یکپارچه‌سازی رسمی نیست و ممکن است به تعلیق یا مسدودشدن حساب منجر شود. با مسئولیت خود استفاده کنید.
</Warning>

## نصب

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

```bash
openclaw plugins install @openclaw/zalouser
```

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

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

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

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

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

## چیست

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

## نام‌گذاری

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

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

```bash
openclaw directory self --channel zalouser
openclaw 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` بازمی‌گردد.

مثال:

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

<Note>
`channels.zalouser.groups.<id>.allow` نام یک فیلد قدیمی است؛ پیکربندی کنونی از `enabled` استفاده می‌کند. `openclaw doctor --fix`، `allow` را به‌طور خودکار به `enabled` مهاجرت می‌دهد.
</Note>

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

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

مثال:

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

## چندحسابی

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

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

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

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

| متغیر                | هدف                                                                    |
| ------------------ | -------------------------------------------------------------------------- |
| `ZALOUSER_PROFILE` | نام پروفایلی که وقتی هیچ `profile` در پیکربندی کانال یا حساب تنظیم نشده است استفاده می‌شود. |
| `ZCA_PROFILE`      | مقدار جایگزین قدیمی که فقط وقتی `ZALOUSER_PROFILE` تنظیم نشده است استفاده می‌شود.             |

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

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

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

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

- OpenClaw پیش از ارسال پاسخ، یک رویداد تایپ ارسال می‌کند (به‌صورت تلاش در حد امکان).
- کنش واکنش به پیام `react` برای `zalouser` در کنش‌های کانال پشتیبانی می‌شود.
  - برای حذف یک ایموجی واکنش مشخص از پیام، از `remove: true` استفاده کنید.
  - معنای واکنش‌ها: [واکنش‌ها](/fa/tools/reactions)
- برای پیام‌های ورودی دارای فراداده رویداد، 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 خارجی اجرا می‌شود.

## مرتبط

- [نمای کلی کانال‌ها](/fa/channels) - همه کانال‌های پشتیبانی‌شده
- [جفت‌سازی](/fa/channels/pairing) - احراز هویت پیام مستقیم و جریان جفت‌سازی
- [گروه‌ها](/fa/channels/groups) - رفتار گفت‌وگوی گروهی و محدودسازی بر اساس اشاره
- [مسیریابی کانال](/fa/channels/channel-routing) - مسیریابی نشست برای پیام‌ها
- [امنیت](/fa/gateway/security) - مدل دسترسی و مقاوم‌سازی
