openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh fa translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-04 07:12:54 +00:00
parent ac60263840
commit 03b39495f4
22 changed files with 4438 additions and 3834 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

564
docs/fa/channels/discord.md
View File

File diff suppressed because it is too large Load Diff

517
docs/fa/channels/slack.md
View File

@ -1,47 +1,47 @@
---
read_when:
- راه‌اندازی Slack یا اشکال‌زدایی حالت سوکت/HTTP در Slack
summary: راه‌اندازی Slack و رفتار زمان اجرا (حالت Socket + نشانی‌های URL درخواست HTTP)
summary: راه‌اندازی Slack و رفتار زمان اجرا (حالت سوکت + URLهای درخواست HTTP)
title: Slack
x-i18n:
generated_at: "2026-05-04T02:22:25Z"
generated_at: "2026-05-04T07:02:46Z"
model: gpt-5.5
provider: openai
source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b
source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228
source_path: channels/slack.md
workflow: 16
---
آماده برای تولید در DMها و کانال‌ها از طریق یکپارچه‌سازی‌های برنامه Slack. حالت پیش‌فرض Socket Mode است؛ HTTP Request URLs نیز پشتیبانی می‌شوند.
آمادهٔ تولید برای پیام‌های مستقیم و کانال‌ها از طریق یکپارچه‌سازی‌های اپلیکیشن Slack. حالت پیش‌فرض، حالت Socket است؛ URLهای درخواست HTTP نیز پشتیبانی می‌شوند.
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/fa/channels/pairing">
DMهای Slack به‌طور پیش‌فرض در حالت همگام‌سازی هستند.
<Card title="جفت‌سازی" icon="link" href="/fa/channels/pairing">
پیام‌های مستقیم Slack به‌طور پیش‌فرض از حالت جفت‌سازی استفاده می‌کنند.
</Card>
<Card title="Slash commands" icon="terminal" href="/fa/tools/slash-commands">
رفتار فرمان بومی و کاتالوگ فرمان‌ها.
<Card title="دستورهای اسلش" icon="terminal" href="/fa/tools/slash-commands">
رفتار دستورهای بومی و فهرست دستورها.
</Card>
<Card title="Channel troubleshooting" icon="wrench" href="/fa/channels/troubleshooting">
تشخیص‌های میان‌کانالی و دستورالعمل‌های تعمیر.
<Card title="عیب‌یابی کانال" icon="wrench" href="/fa/channels/troubleshooting">
عیب‌یابی میان‌کانالی و راهنماهای عملیاتی تعمیر.
</Card>
</CardGroup>
## راه‌اندازی سریع
<Tabs>
<Tab title="Socket Mode (default)">
<Tab title="حالت Socket (پیش‌فرض)">
<Steps>
<Step title="Create a new Slack app">
در تنظیمات برنامه Slack دکمه **[Create New App](https://api.slack.com/apps/new)** را فشار دهید:
<Step title="ایجاد یک اپلیکیشن Slack جدید">
در تنظیمات اپلیکیشن Slack دکمهٔ **[Create New App](https://api.slack.com/apps/new)** را فشار دهید:
- گزینه **from a manifest** را انتخاب کنید و یک workspace برای برنامه خود برگزینید
- [نمونه manifest](#manifest-and-scope-checklist) زیر را جای‌گذاری کنید و برای ایجاد ادامه دهید
- یک **App-Level Token** (`xapp-...`) با `connections:write` ایجاد کنید
- برنامه را نصب کنید و **Bot Token** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید
- گزینهٔ **from a manifest** را انتخاب کنید و یک فضای کاری برای اپلیکیشن خود برگزینید
- [نمونهٔ manifest](#manifest-and-scope-checklist) زیر را جای‌گذاری کنید و برای ایجاد ادامه دهید
- یک **توکن سطح اپلیکیشن** (`xapp-...`) با `connections:write` ایجاد کنید
- اپلیکیشن را نصب کنید و **توکن Bot** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید
</Step>
<Step title="Configure OpenClaw">
<Step title="پیکربندی OpenClaw">
راه‌اندازی پیشنهادی SecretRef:
@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-...
</Step>
<Step title="Start gateway">
<Step title="شروع Gateway">
```bash
openclaw gateway
@ -84,19 +84,19 @@ openclaw gateway
</Tab>
<Tab title="HTTP Request URLs">
<Tab title="URLهای درخواست HTTP">
<Steps>
<Step title="Create a new Slack app">
در تنظیمات برنامه Slack دکمه **[Create New App](https://api.slack.com/apps/new)** را فشار دهید:
<Step title="ایجاد یک اپلیکیشن Slack جدید">
در تنظیمات اپلیکیشن Slack دکمهٔ **[Create New App](https://api.slack.com/apps/new)** را فشار دهید:
- گزینه **from a manifest** را انتخاب کنید و یک workspace برای برنامه خود برگزینید
- [نمونه manifest](#manifest-and-scope-checklist) را جای‌گذاری کنید و پیش از ایجاد، URLها را به‌روزرسانی کنید
- **Signing Secret** را برای راستی‌آزمایی درخواست ذخیره کنید
- برنامه را نصب کنید و **Bot Token** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید
- گزینهٔ **from a manifest** را انتخاب کنید و یک فضای کاری برای اپلیکیشن خود برگزینید
- [نمونهٔ manifest](#manifest-and-scope-checklist) را جای‌گذاری کنید و پیش از ایجاد، URLها را به‌روزرسانی کنید
- **راز امضا** را برای راستی‌آزمایی درخواست ذخیره کنید
- اپلیکیشن را نصب کنید و **توکن Bot** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید
</Step>
<Step title="Configure OpenClaw">
<Step title="پیکربندی OpenClaw">
راه‌اندازی پیشنهادی SecretRef:
@ -121,14 +121,14 @@ openclaw config patch --file ./slack.http.patch.json5
```
<Note>
برای HTTP چندحسابی، مسیرهای Webhook یکتا استفاده کنید
برای HTTP چندحسابی از مسیرهای webhook یکتا استفاده کنید
به هر حساب یک `webhookPath` متمایز بدهید (پیش‌فرض `/slack/events`) تا ثبت‌ها با هم تداخل نداشته باشند.
به هر حساب یک `webhookPath` متمایز (پیش‌فرض `/slack/events`) بدهید تا ثبت‌ها با هم تداخل نکنند.
</Note>
</Step>
<Step title="Start gateway">
<Step title="شروع Gateway">
```bash
openclaw gateway
@ -140,9 +140,9 @@ openclaw gateway
</Tab>
</Tabs>
## تنظیم انتقال Socket Mode
## تنظیم دقیق انتقال در حالت Socket
OpenClaw به‌طور پیش‌فرض برای Socket Mode، زمان‌انتظار pong کلاینت SDK مربوط به Slack را روی ۱۵ ثانیه تنظیم می‌کند. تنظیمات انتقال را فقط وقتی بازنویسی کنید که به تنظیمات اختصاصی workspace یا میزبان نیاز دارید:
OpenClaw به‌طور پیش‌فرض زمان پایان انتظار pong کلاینت SDK Slack را برای حالت Socket روی ۱۵ ثانیه تنظیم می‌کند. تنظیمات انتقال را فقط زمانی بازنویسی کنید که به تنظیم دقیق مخصوص فضای کاری یا میزبان نیاز دارید:
```json5
{
@ -159,13 +159,13 @@ OpenClaw به‌طور پیش‌فرض برای Socket Mode، زمان‌انت
}
```
این را فقط برای workspaceهای Socket Mode استفاده کنید که زمان‌انتظار‌های Slack websocket pong/server-ping را ثبت می‌کنند یا روی میزبان‌هایی با کمبود شناخته‌شده چرخه رویداد اجرا می‌شوند. `clientPingTimeout` مدت انتظار برای pong پس از ارسال client ping توسط SDK است؛ `serverPingTimeout` مدت انتظار برای pingهای سرور Slack است. پیام‌ها و رویدادهای برنامه، وضعیت برنامه باقی می‌مانند، نه سیگنال‌های زنده‌بودن انتقال.
این را فقط برای فضاهای کاری حالت Socket استفاده کنید که پایان زمان انتظار pong وب‌سوکت Slack یا server-ping را ثبت می‌کنند، یا روی میزبان‌هایی اجرا می‌شوند که گرسنگی حلقهٔ رویداد شناخته‌شده دارند. `clientPingTimeout` مدت انتظار برای pong پس از ارسال ping کلاینت توسط SDK است؛ `serverPingTimeout` مدت انتظار برای pingهای سرور Slack است. پیام‌ها و رویدادهای اپلیکیشن همچنان وضعیت اپلیکیشن هستند، نه سیگنال‌های زنده‌بودن انتقال.
## فهرست کنترل manifest و scope
## فهرست بررسی manifest و scope
manifest پایه برنامه Slack برای Socket Mode و HTTP Request URLs یکسان است. فقط بلوک `settings` (و `url` فرمان slash) تفاوت دارد.
manifest پایهٔ اپلیکیشن Slack برای حالت Socket و URLهای درخواست HTTP یکسان است. فقط بلوک `settings` (و `url` دستور اسلش) متفاوت است.
manifest پایه (پیش‌فرض Socket Mode):
manifest پایه (پیش‌فرض حالت Socket):
```json
{
@ -240,7 +240,7 @@ manifest پایه (پیش‌فرض Socket Mode):
}
```
برای حالت **HTTP Request URLs**، `settings` را با گونه HTTP جایگزین کنید و به هر فرمان slash مقدار `url` اضافه کنید. URL عمومی لازم است:
برای **حالت URLهای درخواست HTTP**، `settings` را با گونهٔ HTTP جایگزین کنید و به هر دستور اسلش `url` اضافه کنید. URL عمومی لازم است:
```json
{
@ -282,24 +282,24 @@ manifest پایه (پیش‌فرض Socket Mode):
}
```
### تنظیمات اضافی manifest
### تنظیمات تکمیلی manifest
قابلیت‌های متفاوتی را آشکار کنید که پیش‌فرض‌های بالا را گسترش می‌دهند.
ویژگی‌های متفاوتی را که پیش‌فرض‌های بالا را گسترش می‌دهند، ارائه کنید.
manifest پیش‌فرض، زبانه **Home** در Slack App Home را فعال می‌کند و در `app_home_opened` مشترک می‌شود. وقتی عضوی از workspace زبانه Home را باز می‌کند، OpenClaw با `views.publish` یک نمای Home پیش‌فرض امن منتشر می‌کند؛ هیچ payload مکالمه یا پیکربندی خصوصی گنجانده نمی‌شود. زبانه **Messages** برای DMهای Slack فعال می‌ماند.
manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعال می‌کند و در `app_home_opened` مشترک می‌شود. وقتی یکی از اعضای فضای کاری زبانهٔ Home را باز می‌کند، OpenClaw با `views.publish` یک نمای Home پیش‌فرض امن منتشر می‌کند؛ هیچ payload مکالمه یا پیکربندی خصوصی در آن گنجانده نمی‌شود. زبانهٔ **Messages** برای پیام‌های مستقیم Slack همچنان فعال می‌ماند.
<AccordionGroup>
<Accordion title="Optional native slash commands">
<Accordion title="دستورهای اسلش بومی اختیاری">
می‌توان به‌جای یک فرمان پیکربندی‌شده واحد، با ظرافت از چند [فرمان slash بومی](#commands-and-slash-behavior) استفاده کرد:
می‌توان به‌جای یک دستور پیکربندی‌شدهٔ واحد، از چندین [دستور اسلش بومی](#commands-and-slash-behavior) با جزئیات استفاده کرد:
- از `/agentstatus` به‌جای `/status` استفاده کنید، چون فرمان `/status` رزرو شده است.
- هم‌زمان بیش از ۲۵ فرمان slash را نمی‌توان در دسترس قرار داد.
- از `/agentstatus` به‌جای `/status` استفاده کنید، چون دستور `/status` رزرو شده است.
- نمی‌توان بیش از ۲۵ دستور اسلش را هم‌زمان در دسترس قرار داد.
بخش موجود `features.slash_commands` خود را با زیرمجموعه‌ای از [فرمان‌های موجود](/fa/tools/slash-commands#command-list) جایگزین کنید:
بخش `features.slash_commands` موجود خود را با زیرمجموعه‌ای از [دستورهای موجود](/fa/tools/slash-commands#command-list) جایگزین کنید:
<Tabs>
<Tab title="Socket Mode (default)">
<Tab title="حالت Socket (پیش‌فرض)">
```json
{
@ -422,8 +422,8 @@ manifest پیش‌فرض، زبانه **Home** در Slack App Home را فعال
```
</Tab>
<Tab title="HTTP Request URLs">
از همان فهرست `slash_commands` بالا برای Socket Mode استفاده کنید، و به هر مدخل `"url": "https://gateway-host.example.com/slack/events"` اضافه کنید. نمونه:
<Tab title="URLهای درخواست HTTP">
از همان فهرست `slash_commands` حالت Socket در بالا استفاده کنید و به هر ورودی `"url": "https://gateway-host.example.com/slack/events"` اضافه کنید. نمونه:
```json
{
@ -443,20 +443,20 @@ manifest پیش‌فرض، زبانه **Home** در Slack App Home را فعال
}
```
آن مقدار `url` را روی هر فرمان در فهرست تکرار کنید.
آن مقدار `url` را برای هر دستور در فهرست تکرار کنید.
</Tab>
</Tabs>
</Accordion>
<Accordion title="Optional authorship scopes (write operations)">
اگر می‌خواهید پیام‌های خروجی به‌جای هویت پیش‌فرض برنامه Slack از هویت agent فعال (نام کاربری و آیکون سفارشی) استفاده کنند، scope ربات `chat:write.customize` را اضافه کنید.
<Accordion title="دامنه‌های اختیاری نویسندگی (عملیات نوشتن)">
اگر می‌خواهید پیام‌های خروجی به‌جای هویت پیش‌فرض برنامه Slack از هویت عامل فعال (نام کاربری و نماد سفارشی) استفاده کنند، دامنه ربات `chat:write.customize` را اضافه کنید.
اگر از آیکون ایموجی استفاده می‌کنید، Slack انتظار دستور زبان `:emoji_name:` را دارد.
اگر از نماد ایموجی استفاده می‌کنید، Slack انتظار نحو `:emoji_name:` را دارد.
</Accordion>
<Accordion title="Optional user-token scopes (read operations)">
اگر `channels.slack.userToken` را پیکربندی می‌کنید، scopeهای خواندن معمول عبارت‌اند از:
<Accordion title="دامنه‌های اختیاری توکن کاربر (عملیات خواندن)">
اگر `channels.slack.userToken` را پیکربندی کنید، دامنه‌های خواندن معمول عبارت‌اند از:
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
@ -473,34 +473,34 @@ manifest پیش‌فرض، زبانه **Home** در Slack App Home را فعال
- `botToken` + `appToken` برای Socket Mode الزامی هستند.
- حالت HTTP به `botToken` + `signingSecret` نیاز دارد.
- `botToken`، `appToken`، `signingSecret`، و `userToken` رشته‌های متن ساده
یا شیءهای SecretRef را می‌پذیرند.
- توکن‌های پیکربندی fallback متغیرهای محیطی را override می‌کنند.
- fallback متغیرهای محیطی `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود.
- `userToken` (`xoxp-...`) فقط از پیکربندی می‌آید (بدون fallback متغیر محیطی) و رفتار پیش‌فرض آن فقط‌خواندنی است (`userTokenReadOnly: true`).
- `botToken`، `appToken`، `signingSecret` و `userToken` رشته‌های متن ساده
یا اشیای SecretRef را می‌پذیرند.
- توکن‌های پیکربندی، جایگزین بازگشت env می‌شوند.
- بازگشت env برای `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود.
- `userToken` (`xoxp-...`) فقط از طریق پیکربندی است (بدون بازگشت env) و به‌طور پیش‌فرض رفتار فقط‌خواندنی دارد (`userTokenReadOnly: true`).
رفتار snapshot وضعیت:
رفتار نمایه وضعیت:
- بازرسی حساب Slack فیلدهای `*Source` و `*Status`
را برای هر credential پیگیری می‌کند (`botToken`، `appToken`، `signingSecret`، `userToken`).
- وضعیت `available`، `configured_unavailable`، یا `missing` است.
را برای هر اعتبارنامه (`botToken`، `appToken`، `signingSecret`، `userToken`) رهگیری می‌کند.
- وضعیت `available`، `configured_unavailable` یا `missing` است.
- `configured_unavailable` یعنی حساب از طریق SecretRef
یا منبع secret غیر inline دیگری پیکربندی شده است، اما مسیر فرمان/runtime فعلی
یا منبع راز غیرخطی دیگری پیکربندی شده است، اما مسیر فرمان/زمان اجرای فعلی
نتوانسته مقدار واقعی را resolve کند.
- در حالت HTTP، `signingSecretStatus` درج می‌شود؛ در Socket Mode،
- در حالت HTTP، `signingSecretStatus` گنجانده می‌شود؛ در Socket Mode،
جفت الزامی `botTokenStatus` + `appTokenStatus` است.
<Tip>
برای actionها/خواندن‌های directory، وقتی user token پیکربندی شده باشد، می‌تواند ترجیح داده شود. برای نوشتن‌ها، bot token همچنان ترجیح داده می‌شود؛ نوشتن با user-token فقط وقتی مجاز است که `userTokenReadOnly: false` باشد و bot token در دسترس نباشد.
برای خواندن‌های اقدامات/فهرست، وقتی توکن کاربر پیکربندی شده باشد می‌توان آن را ترجیح داد. برای نوشتن‌ها، توکن ربات همچنان ترجیح داده می‌شود؛ نوشتن با توکن کاربر فقط وقتی مجاز است که `userTokenReadOnly: false` باشد و توکن ربات در دسترس نباشد.
</Tip>
## actionها و gateها
## اقدامات و گیت‌ها
actionهای Slack با `channels.slack.actions.*` کنترل می‌شوند.
اقدامات Slack با `channels.slack.actions.*` کنترل می‌شوند.
گروه‌های action موجود در ابزارهای فعلی Slack:
گروه‌های اقدام موجود در ابزار فعلی Slack:
| گروه | پیش‌فرض |
| گروه | پیش‌فرض |
| ---------- | ------- |
| messages | فعال |
| reactions | فعال |
@ -508,60 +508,60 @@ actionهای Slack با `channels.slack.actions.*` کنترل می‌شوند.
| memberInfo | فعال |
| emojiList | فعال |
actionهای پیام فعلی Slack شامل `send`، `upload-file`، `download-file`، `read`، `edit`، `delete`، `pin`، `unpin`، `list-pins`، `member-info`، و `emoji-list` هستند. `download-file` شناسه‌های فایل Slack نشان‌داده‌شده در placeholderهای فایل ورودی را می‌پذیرد و برای تصویرها preview تصویر یا برای انواع فایل دیگر metadata فایل محلی برمی‌گرداند.
اقدامات پیام فعلی Slack شامل `send`، `upload-file`، `download-file`، `read`، `edit`، `delete`، `pin`، `unpin`، `list-pins`، `member-info` و `emoji-list` است. `download-file` شناسه‌های فایل Slack را که در جای‌نگهدارهای فایل ورودی نشان داده می‌شوند می‌پذیرد و برای تصاویر پیش‌نمایش تصویر یا برای انواع دیگر فایل، فراداده فایل محلی را برمی‌گرداند.
## کنترل دسترسی و مسیریابی
<Tabs>
<Tab title="DM policy">
`channels.slack.dmPolicy` دسترسی DM را کنترل می‌کند. `channels.slack.allowFrom` allowlist رسمی DM است.
<Tab title="سیاست DM">
`channels.slack.dmPolicy` دسترسی DM را کنترل می‌کند. `channels.slack.allowFrom` فهرست مجاز canonical برای DM است.
- `pairing` (پیش‌فرض)
- `allowlist`
- `open` (نیاز دارد `channels.slack.allowFrom` شامل `"*"` باشد)
- `disabled`
flagهای DM:
پرچم‌های DM:
- `dm.enabled` (پیش‌فرض true)
- `channels.slack.allowFrom`
- `dm.allowFrom` (قدیمی)
- `dm.groupEnabled` (DMهای گروهی به‌طور پیش‌فرض false)
- `dm.groupChannels` (allowlist اختیاری MPIM)
- `dm.groupEnabled` (DMهای گروهی به‌طور پیش‌فرض false هستند)
- `dm.groupChannels` (فهرست مجاز MPIM اختیاری)
اولویت چندحسابی:
تقدم چندحسابی:
- `channels.slack.accounts.default.allowFrom` فقط برای حساب `default` اعمال می‌شود.
- حساب‌های نام‌دار وقتی `allowFrom` خودشان unset باشد، `channels.slack.allowFrom` را به ارث می‌برند.
- حساب‌های نام‌دار `channels.slack.accounts.default.allowFrom` را به ارث نمی‌برند.
- حساب‌های نام‌گذاری‌شده وقتی `allowFrom` خودشان تنظیم نشده باشد، `channels.slack.allowFrom` را به ارث می‌برند.
- حساب‌های نام‌گذاری‌شده `channels.slack.accounts.default.allowFrom` را به ارث نمی‌برند.
`channels.slack.dm.policy` و `channels.slack.dm.allowFrom` قدیمی همچنان برای سازگاری خوانده می‌شوند. `openclaw doctor --fix` وقتی بتواند بدون تغییر دسترسی این کار را انجام دهد، آن‌ها را به `dmPolicy` و `allowFrom` migrate می‌کند.
`channels.slack.dm.policy` و `channels.slack.dm.allowFrom` قدیمی همچنان برای سازگاری خوانده می‌شوند. `openclaw doctor --fix` وقتی بتواند بدون تغییر دسترسی این کار را انجام دهد، آن‌ها را به `dmPolicy` و `allowFrom` مهاجرت می‌دهد.
Pairing در DMها از `openclaw pairing approve slack <code>` استفاده می‌کند.
جفت‌سازی در DMها از `openclaw pairing approve slack <code>` استفاده می‌کند.
</Tab>
<Tab title="Channel policy">
`channels.slack.groupPolicy` نحوه رسیدگی به کانال را کنترل می‌کند:
<Tab title="سیاست کانال">
`channels.slack.groupPolicy` مدیریت کانال را کنترل می‌کند:
- `open`
- `allowlist`
- `disabled`
allowlist کانال زیر `channels.slack.channels` قرار دارد و **باید از شناسه‌های پایدار کانال Slack** (برای نمونه `C12345678`) به‌عنوان کلیدهای پیکربندی استفاده کند.
فهرست مجاز کانال زیر `channels.slack.channels` قرار دارد و **باید از شناسه‌های پایدار کانال Slack** (برای مثال `C12345678`) به‌عنوان کلیدهای پیکربندی استفاده کند.
نکته runtime: اگر `channels.slack` کاملاً وجود نداشته باشد (راه‌اندازی فقط با env)، runtime به `groupPolicy="allowlist"` fallback می‌کند و warning ثبت می‌کند (حتی اگر `channels.defaults.groupPolicy` تنظیم شده باشد).
نکته زمان اجرا: اگر `channels.slack` کاملا وجود نداشته باشد (راه‌اندازی فقط با env)، زمان اجرا به `groupPolicy="allowlist"` برمی‌گردد و یک هشدار ثبت می‌کند (حتی اگر `channels.defaults.groupPolicy` تنظیم شده باشد).
resolve نام/شناسه:
- entryهای allowlist کانال و entryهای allowlist مربوط به DM هنگام startup و وقتی دسترسی token اجازه دهد resolve می‌شوند
- entryهای resolveنشده نام کانال همان‌طور که پیکربندی شده‌اند نگه داشته می‌شوند، اما به‌طور پیش‌فرض برای مسیریابی نادیده گرفته می‌شوند
- authorization ورودی و مسیریابی کانال به‌طور پیش‌فرض ID-first هستند؛ تطبیق مستقیم username/slug به `channels.slack.dangerouslyAllowNameMatching: true` نیاز دارد
- ورودی‌های فهرست مجاز کانال و ورودی‌های فهرست مجاز DM هنگام راه‌اندازی، وقتی دسترسی توکن اجازه دهد، resolve می‌شوند
- ورودی‌های resolveنشده نام کانال همان‌طور که پیکربندی شده‌اند نگه داشته می‌شوند، اما به‌طور پیش‌فرض برای مسیریابی نادیده گرفته می‌شوند
- مجوزدهی ورودی و مسیریابی کانال به‌طور پیش‌فرض ابتدا بر پایه شناسه است؛ تطبیق مستقیم نام کاربری/slug به `channels.slack.dangerouslyAllowNameMatching: true` نیاز دارد
<Warning>
کلیدهای مبتنی بر نام (`#channel-name` یا `channel-name`) زیر `groupPolicy: "allowlist"` مطابقت **نمی‌کنند**. lookup کانال به‌طور پیش‌فرض ID-first است، بنابراین کلید مبتنی بر نام هرگز با موفقیت route نمی‌شود و همه پیام‌های آن کانال بی‌صدا block می‌شوند. این با `groupPolicy: "open"` فرق دارد؛ در آن حالت کلید کانال برای مسیریابی لازم نیست و کلید مبتنی بر نام ظاهراً کار می‌کند.
کلیدهای مبتنی بر نام (`#channel-name` یا `channel-name`) تحت `groupPolicy: "allowlist"` تطبیق **نمی‌شوند**. جست‌وجوی کانال به‌طور پیش‌فرض ابتدا بر پایه شناسه است، بنابراین یک کلید مبتنی بر نام هرگز با موفقیت مسیریابی نمی‌شود و همه پیام‌های آن کانال بی‌صدا مسدود خواهند شد. این با `groupPolicy: "open"` فرق دارد؛ در آنجا کلید کانال برای مسیریابی لازم نیست و به نظر می‌رسد یک کلید مبتنی بر نام کار می‌کند.
همیشه از شناسه کانال Slack به‌عنوان کلید استفاده کنید. برای پیدا کردن آن: در Slack روی کانال راست‌کلیک کنید → **Copy link** — شناسه (`C...`) در انتهای URL ظاهر می‌شود.
همیشه از شناسه کانال Slack به‌عنوان کلید استفاده کنید. برای یافتن آن: روی کانال در Slack راست‌کلیک کنید → **Copy link** — شناسه (`C...`) در انتهای URL ظاهر می‌شود.
درست:
@ -578,7 +578,7 @@ actionهای پیام فعلی Slack شامل `send`، `upload-file`، `download
}
```
نادرست (زیر `groupPolicy: "allowlist"` بی‌صدا block می‌شود):
نادرست (به‌صورت بی‌صدا تحت `groupPolicy: "allowlist"` مسدود می‌شود):
```json5
{
@ -597,93 +597,112 @@ actionهای پیام فعلی Slack شامل `send`، `upload-file`، `download
</Tab>
<Tab title="Mentions and channel users">
پیام‌های کانال به‌طور پیش‌فرض با mention gated می‌شوند.
پیام‌های کانال به‌صورت پیش‌فرض با اشاره کنترل می‌شوند.
منابع mention:
منابع اشاره:
- mention صریح app (`<@botId>`)
- mention گروه کاربری Slack (`<!subteam^S...>`) وقتی کاربر ربات عضو آن گروه کاربری باشد؛ به `usergroups:read` نیاز دارد
- الگوهای regex برای mention (`agents.list[].groupChat.mentionPatterns`، fallback با `messages.groupChat.mentionPatterns`)
- رفتار thread ضمنی reply-to-bot (وقتی `thread.requireExplicitMention` برابر `true` باشد غیرفعال می‌شود)
- اشاره صریح به اپ (`<@botId>`)
- اشاره به گروه کاربری Slack (`<!subteam^S...>`) وقتی کاربر ربات عضو آن گروه کاربری باشد؛ به `usergroups:read` نیاز دارد
- الگوهای regex اشاره (`agents.list[].groupChat.mentionPatterns`، جایگزین `messages.groupChat.mentionPatterns`)
- رفتار ضمنی پاسخ به رشته ربات (وقتی `thread.requireExplicitMention` برابر `true` باشد غیرفعال می‌شود)
کنترل‌های هر کانال (`channels.slack.channels.<id>`؛ نام‌ها فقط از طریق resolve در startup یا `dangerouslyAllowNameMatching`):
کنترل‌های هر کانال (`channels.slack.channels.<id>`؛ نام‌ها فقط از طریق حل‌وفصل هنگام راه‌اندازی یا `dangerouslyAllowNameMatching`):
- `requireMention`
- `users` (allowlist)
- `allowBots`
- `skills`
- `systemPrompt`
- `tools`, `toolsBySender`
- `tools`، `toolsBySender`
- قالب کلید `toolsBySender`: `id:`، `e164:`، `username:`، `name:`، یا wildcard `"*"`
(کلیدهای قدیمی بدون prefix همچنان فقط به `id:` map می‌شوند)
(کلیدهای قدیمی بدون پیشوند همچنان فقط به `id:` نگاشت می‌شوند)
`allowBots` برای کانال‌ها و کانال‌های خصوصی محافظه‌کارانه است: پیام‌های room که توسط bot نوشته شده‌اند فقط وقتی پذیرفته می‌شوند که bot فرستنده صراحتاً در allowlist `users` همان room فهرست شده باشد، یا وقتی دست‌کم یک شناسه صریح مالک Slack از `channels.slack.allowFrom` در حال حاضر عضو room باشد. wildcardها و entryهای مالک با display-name حضور مالک را برآورده نمی‌کنند. حضور مالک از `conversations.members` Slack استفاده می‌کند؛ مطمئن شوید app scope خواندن مطابق با نوع room را دارد (`channels:read` برای کانال‌های عمومی، `groups:read` برای کانال‌های خصوصی). اگر member lookup شکست بخورد، OpenClaw پیام room نوشته‌شده توسط bot را drop می‌کند.
`allowBots` برای کانال‌ها و کانال‌های خصوصی محافظه‌کارانه است: پیام‌های اتاق که توسط ربات نوشته شده‌اند فقط وقتی پذیرفته می‌شوند که ربات فرستنده به‌صراحت در allowlist `users` همان اتاق فهرست شده باشد، یا وقتی دست‌کم یک شناسه مالک صریح Slack از `channels.slack.allowFrom` در حال حاضر عضو اتاق باشد. wildcardها و ورودی‌های مالک با نام نمایشی، حضور مالک را برآورده نمی‌کنند. حضور مالک از `conversations.members` در Slack استفاده می‌کند؛ مطمئن شوید اپ scope خواندن متناظر با نوع اتاق را دارد (`channels:read` برای کانال‌های عمومی، `groups:read` برای کانال‌های خصوصی). اگر جست‌وجوی عضو شکست بخورد، OpenClaw پیام اتاق نوشته‌شده توسط ربات را حذف می‌کند.
</Tab>
</Tabs>
## threadها، sessionها، و tagهای پاسخ
## رشته‌ها، نشست‌ها، و برچسب‌های پاسخ
- DMها به‌صورت `direct` route می‌شوند؛ کانال‌ها به‌صورت `channel`؛ MPIMها به‌صورت `group`.
- bindingهای route در Slack شناسه‌های خام peer به‌علاوه شکل‌های هدف Slack مانند `channel:C12345678`، `user:U12345678`، و `<@U12345678>` را می‌پذیرند.
- با `session.dmScope=main` پیش‌فرض، DMهای Slack به session اصلی agent collapse می‌شوند.
- sessionهای کانال: `agent:<agentId>:slack:channel:<channelId>`.
- پاسخ‌های thread می‌توانند در صورت کاربرد، suffixهای session thread بسازند (`:thread:<threadTs>`).
- DMها به‌صورت `direct` مسیر‌دهی می‌شوند؛ کانال‌ها به‌صورت `channel`؛ MPIMها به‌صورت `group`.
- اتصال‌های مسیر Slack شناسه‌های خام طرف مقابل به‌علاوه فرم‌های مقصد Slack مانند `channel:C12345678`، `user:U12345678`، و `<@U12345678>` را می‌پذیرند.
- با مقدار پیش‌فرض `session.dmScope=main`، DMهای Slack در نشست اصلی عامل ادغام می‌شوند.
- نشست‌های کانال: `agent:<agentId>:slack:channel:<channelId>`.
- پاسخ‌های رشته می‌توانند در صورت کاربرد پسوندهای نشست رشته (`:thread:<threadTs>`) بسازند.
- مقدار پیش‌فرض `channels.slack.thread.historyScope` برابر `thread` است؛ مقدار پیش‌فرض `thread.inheritParent` برابر `false` است.
- `channels.slack.thread.initialHistoryLimit` کنترل می‌کند هنگام شروع session جدید thread چند پیام موجود از thread fetch شود (پیش‌فرض `20`؛ برای غیرفعال‌سازی `0` تنظیم کنید).
- `channels.slack.thread.requireExplicitMention` (پیش‌فرض `false`): وقتی `true` باشد، mentionهای ضمنی thread را suppress می‌کند تا bot فقط به mentionهای صریح `@bot` داخل threadها پاسخ دهد، حتی وقتی bot قبلاً در thread مشارکت کرده باشد. بدون این، پاسخ‌ها در threadی که bot در آن مشارکت کرده است gate مربوط به `requireMention` را bypass می‌کنند.
- `channels.slack.thread.initialHistoryLimit` کنترل می‌کند هنگام شروع یک نشست رشته جدید چند پیام موجود رشته دریافت شود (پیش‌فرض `20`؛ برای غیرفعال‌سازی روی `0` تنظیم کنید).
- `channels.slack.thread.requireExplicitMention` (پیش‌فرض `false`): وقتی `true` باشد، اشاره‌های ضمنی رشته را سرکوب می‌کند تا ربات فقط به اشاره‌های صریح `@bot` داخل رشته‌ها پاسخ دهد، حتی وقتی ربات قبلا در رشته مشارکت کرده باشد. بدون این، پاسخ‌ها در رشته‌ای که ربات در آن مشارکت داشته از کنترل `requireMention` عبور می‌کنند.
کنترل‌های thread پاسخ:
کنترل‌های رشته پاسخ:
- `channels.slack.replyToMode`: `off|first|all|batched` (پیش‌فرض `off`)
- `channels.slack.replyToModeByChatType`: برای هر `direct|group|channel`
- fallback قدیمی برای چت‌های مستقیم: `channels.slack.dm.replyToMode`
- `channels.slack.replyToModeByChatType`: به‌ازای هر `direct|group|channel`
- جایگزین قدیمی برای چت‌های مستقیم: `channels.slack.dm.replyToMode`
tagهای پاسخ دستی پشتیبانی می‌شوند:
برچسب‌های پاسخ دستی پشتیبانی می‌شوند:
- `[[reply_to_current]]`
- `[[reply_to:<id>]]`
<Note>
`replyToMode="off"` **همه** thread کردن پاسخ در Slack را غیرفعال می‌کند، از جمله tagهای صریح `[[reply_to_*]]`. این با Telegram متفاوت است؛ در آنجا tagهای صریح همچنان در حالت `"off"` رعایت می‌شوند. threadهای Slack پیام‌ها را از کانال پنهان می‌کنند، در حالی که پاسخ‌های Telegram به‌صورت inline قابل مشاهده می‌مانند.
`replyToMode="off"` **تمام** رشته‌سازی پاسخ در Slack را غیرفعال می‌کند، از جمله برچسب‌های صریح `[[reply_to_*]]`. این با Telegram متفاوت است، جایی که برچسب‌های صریح همچنان در حالت `"off"` رعایت می‌شوند. رشته‌های Slack پیام‌ها را از کانال پنهان می‌کنند، در حالی که پاسخ‌های Telegram به‌صورت درون‌خطی قابل مشاهده می‌مانند.
</Note>
## واکنش‌های Ack
## واکنش‌های تایید
`ackReaction` هنگام پردازش پیام ورودی توسط OpenClaw، یک ایموجی acknowledgement می‌فرستد.
`ackReaction` هنگام پردازش پیام ورودی توسط OpenClaw یک ایموجی تایید ارسال می‌کند.
ترتیب resolve:
ترتیب حل‌وفصل:
- `channels.slack.accounts.<accountId>.ackReaction`
- `channels.slack.ackReaction`
- `messages.ackReaction`
- fallback ایموجی هویت agent (`agents.list[].identity.emoji`، وگرنه "👀")
- جایگزین ایموجی هویت عامل (`agents.list[].identity.emoji`، وگرنه "👀")
نکته‌ها:
- Slack انتظار shortcode دارد (برای نمونه `"eyes"`).
- برای غیرفعال‌سازی واکنش برای حساب Slack یا به‌صورت global از `""` استفاده کنید.
- Slack انتظار shortcode دارد (برای مثال `"eyes"`).
- برای غیرفعال کردن واکنش برای حساب Slack یا به‌صورت سراسری از `""` استفاده کنید.
## streaming متن
## پخش جریانی متن
`channels.slack.streaming` رفتار preview زنده را کنترل می‌کند:
`channels.slack.streaming` رفتار پیش‌نمایش زنده را کنترل می‌کند:
- `off`: streaming preview زنده را غیرفعال می‌کند.
- `partial` (پیش‌فرض): متن preview را با آخرین خروجی partial جایگزین می‌کند.
- `block`: به‌روزرسانی‌های preview تکه‌تکه‌شده را append می‌کند.
- `progress`: هنگام تولید، متن وضعیت progress را نشان می‌دهد، سپس متن نهایی را می‌فرستد.
- `streaming.preview.toolProgress`: وقتی draft preview فعال است، به‌روزرسانی‌های tool/progress را به همان پیام preview ویرایش‌شده route می‌کند (پیش‌فرض: `true`). برای نگه‌داشتن پیام‌های tool/progress جداگانه، `false` تنظیم کنید.
- `off`: پخش جریانی پیش‌نمایش زنده را غیرفعال می‌کند.
- `partial` (پیش‌فرض): متن پیش‌نمایش را با آخرین خروجی جزئی جایگزین می‌کند.
- `block`: به‌روزرسانی‌های پیش‌نمایش بخش‌بندی‌شده را اضافه می‌کند.
- `progress`: هنگام تولید، متن وضعیت پیشرفت را نشان می‌دهد، سپس متن نهایی را ارسال می‌کند.
- `streaming.preview.toolProgress`: وقتی پیش‌نمایش پیش‌نویس فعال است، به‌روزرسانی‌های ابزار/پیشرفت را به همان پیام پیش‌نمایش ویرایش‌شده مسیر‌دهی می‌کند (پیش‌فرض: `true`). برای نگه داشتن پیام‌های جداگانه ابزار/پیشرفت، روی `false` تنظیم کنید.
- `streaming.preview.commandText` / `streaming.progress.commandText`: برای حفظ خطوط فشرده پیشرفت ابزار هنگام پنهان کردن متن خام command/exec، روی `status` تنظیم کنید (پیش‌فرض: `raw`).
`channels.slack.streaming.nativeTransport` وقتی `channels.slack.streaming.mode` برابر `partial` باشد، streaming متن native در Slack را کنترل می‌کند (پیش‌فرض: `true`).
پنهان کردن متن خام command/exec در عین حفظ خطوط فشرده پیشرفت:
- برای نمایش streaming متن native و وضعیت thread دستیار Slack، یک thread پاسخ باید در دسترس باشد. انتخاب thread همچنان از `replyToMode` پیروی می‌کند.
- کانال، group-chat، و ریشه‌های DM سطح بالا همچنان می‌توانند وقتی native streaming در دسترس نیست یا thread پاسخی وجود ندارد از draft preview عادی استفاده کنند.
- DMهای سطح بالای Slack به‌طور پیش‌فرض خارج از thread می‌مانند، بنابراین preview native stream/status به سبک thread Slack را نشان نمی‌دهند؛ OpenClaw به‌جای آن یک draft preview در DM post و edit می‌کند.
- payloadهای رسانه‌ای و غیرمتنی به delivery عادی fallback می‌کنند.
- finalهای رسانه/خطا ویرایش‌های pending preview را cancel می‌کنند؛ finalهای واجد شرایط متن/block فقط وقتی flush می‌شوند که بتوانند preview را درجا edit کنند.
- اگر streaming در میانه پاسخ شکست بخورد، OpenClaw برای payloadهای باقی‌مانده به delivery عادی fallback می‌کند.
```json
{
"channels": {
"slack": {
"streaming": {
"mode": "progress",
"progress": {
"toolProgress": true,
"commandText": "status"
}
}
}
}
}
```
استفاده از draft preview به‌جای streaming متن native در Slack:
`channels.slack.streaming.nativeTransport` پخش جریانی متن بومی Slack را وقتی `channels.slack.streaming.mode` برابر `partial` است کنترل می‌کند (پیش‌فرض: `true`).
- برای ظاهر شدن پخش جریانی متن بومی و وضعیت رشته دستیار Slack، باید یک رشته پاسخ در دسترس باشد. انتخاب رشته همچنان از `replyToMode` پیروی می‌کند.
- ریشه‌های کانال، چت گروهی، و DM سطح بالا همچنان می‌توانند وقتی پخش جریانی بومی در دسترس نیست یا رشته پاسخی وجود ندارد، از پیش‌نمایش پیش‌نویس معمول استفاده کنند.
- DMهای سطح بالای Slack به‌صورت پیش‌فرض خارج از رشته می‌مانند، بنابراین پیش‌نمایش جریان/وضعیت بومی به سبک رشته Slack را نشان نمی‌دهند؛ OpenClaw به‌جای آن یک پیش‌نمایش پیش‌نویس را در DM ارسال و ویرایش می‌کند.
- رسانه و payloadهای غیرمتنی به تحویل معمول بازمی‌گردند.
- نتیجه‌های نهایی رسانه/خطا ویرایش‌های پیش‌نمایش معلق را لغو می‌کنند؛ نتیجه‌های نهایی متن/block واجد شرایط فقط وقتی flush می‌شوند که بتوانند پیش‌نمایش را درجا ویرایش کنند.
- اگر پخش جریانی در میانه پاسخ شکست بخورد، OpenClaw برای payloadهای باقی‌مانده به تحویل معمول بازمی‌گردد.
استفاده از پیش‌نمایش پیش‌نویس به‌جای پخش جریانی متن بومی Slack:
```json5
{
@ -700,41 +719,41 @@ tagهای پاسخ دستی پشتیبانی می‌شوند:
کلیدهای قدیمی:
- `channels.slack.streamMode` (`replace | status_final | append`) به‌صورت خودکار به `channels.slack.streaming.mode` migrate می‌شود.
- boolean `channels.slack.streaming` به‌صورت خودکار به `channels.slack.streaming.mode` و `channels.slack.streaming.nativeTransport` migrate می‌شود.
- `channels.slack.nativeStreaming` قدیمی به‌صورت خودکار به `channels.slack.streaming.nativeTransport` migrate می‌شود.
- `channels.slack.streamMode` (`replace | status_final | append`) به‌صورت خودکار به `channels.slack.streaming.mode` مهاجرت داده می‌شود.
- مقدار boolean `channels.slack.streaming` به‌صورت خودکار به `channels.slack.streaming.mode` و `channels.slack.streaming.nativeTransport` مهاجرت داده می‌شود.
- `channels.slack.nativeStreaming` قدیمی به‌صورت خودکار به `channels.slack.streaming.nativeTransport` مهاجرت داده می‌شود.
## fallback واکنش typing
## جایگزین واکنش تایپ کردن
`typingReaction` هنگام پردازش پاسخ توسط OpenClaw، یک واکنش موقت به پیام ورودی Slack اضافه می‌کند و وقتی run پایان می‌یابد آن را حذف می‌کند. این بیرون از پاسخ‌های thread بیشترین کاربرد را دارد؛ پاسخ‌های thread از نشانگر وضعیت پیش‌فرض "is typing..." استفاده می‌کنند.
`typingReaction` هنگامی که OpenClaw در حال پردازش یک پاسخ است، یک واکنش موقت به پیام ورودی Slack اضافه می‌کند و سپس هنگام پایان اجرای کار آن را حذف می‌کند. این قابلیت بیشتر خارج از پاسخ‌های رشته‌ای مفید است؛ پاسخ‌های رشته‌ای از نشانگر وضعیت پیش‌فرض «در حال تایپ است...» استفاده می‌کنند.
ترتیب resolve:
ترتیب حل:
- `channels.slack.accounts.<accountId>.typingReaction`
- `channels.slack.typingReaction`
نکته‌ها:
- Slack انتظار shortcodeها را دارد (برای مثال `"hourglass_flowing_sand"`).
- واکنش به‌صورت best-effort انجام می‌شود و پس از تکمیل مسیر پاسخ یا شکست، پاک‌سازی به‌طور خودکار تلاش می‌شود.
- Slack انتظار کدهای کوتاه دارد (برای مثال `"hourglass_flowing_sand"`).
- واکنش به‌صورت بهترین تلاش انجام می‌شود و پس از تکمیل مسیر پاسخ یا شکست، پاک‌سازی به‌طور خودکار تلاش می‌شود.
## رسانه، بخش‌بندی و تحویل
## رسانه، بخش‌بندی، و تحویل
<AccordionGroup>
<Accordion title="پیوست‌های ورودی">
پیوست‌های فایل Slack از URLهای خصوصی میزبانی‌شده توسط Slack دانلود می‌شوند (جریان درخواست احراز هویت‌شده با توکن) و وقتی واکشی موفق باشد و محدودیت‌های اندازه اجازه دهند، در مخزن رسانه نوشته می‌شوند. جای‌نگهدارهای فایل شامل `fileId` مربوط به Slack هستند تا عامل‌ها بتوانند فایل اصلی را با `download-file` واکشی کنند.
پیوست‌های فایل Slack از URLهای خصوصی میزبانی‌شده توسط Slack دانلود می‌شوند (جریان درخواست احراز هویت‌شده با توکن) و وقتی واکشی موفق باشد و محدودیت‌های اندازه اجازه دهند، در مخزن رسانه نوشته می‌شوند. جای‌نگهدارهای فایل شامل `fileId` مربوط به Slack هستند تا agentها بتوانند فایل اصلی را با `download-file` واکشی کنند.
دانلودها از timeoutهای idle و کل محدودشده استفاده می‌کنند. اگر بازیابی فایل Slack متوقف شود یا شکست بخورد، OpenClaw پردازش پیام را ادامه می‌دهد و به جای‌نگهدار فایل fallback می‌کند.
دانلودها از timeoutهای محدود برای بیکاری و کل زمان استفاده می‌کنند. اگر بازیابی فایل Slack متوقف شود یا شکست بخورد، OpenClaw پردازش پیام را ادامه می‌دهد و به جای‌نگهدار فایل برمی‌گردد.
سقف اندازه ورودی runtime به‌طور پیش‌فرض `20MB` است، مگر اینکه با `channels.slack.mediaMaxMb` بازنویسی شود.
سقف اندازه ورودی در زمان اجرا به‌طور پیش‌فرض `20MB` است، مگر اینکه با `channels.slack.mediaMaxMb` بازنویسی شود.
</Accordion>
<Accordion title="متن و فایل‌های خروجی">
- بخش‌های متن از `channels.slack.textChunkLimit` استفاده می‌کنند (پیش‌فرض 4000)
- `channels.slack.chunkMode="newline"` تقسیم‌بندی با اولویت پاراگراف را فعال می‌کند
- ارسال فایل از APIهای آپلود Slack استفاده می‌کند و می‌تواند شامل پاسخ‌های thread (`thread_ts`) باشد
- سقف رسانه خروجی، وقتی پیکربندی شده باشد، از `channels.slack.mediaMaxMb` پیروی می‌کند؛ در غیر این صورت ارسال‌های کانال از پیش‌فرض‌های نوع MIME در pipeline رسانه استفاده می‌کنند
- ارسال فایل‌ها از APIهای بارگذاری Slack استفاده می‌کند و می‌تواند شامل پاسخ‌های رشته‌ای (`thread_ts`) باشد
- سقف رسانه خروجی هنگام پیکربندی از `channels.slack.mediaMaxMb` پیروی می‌کند؛ در غیر این صورت ارسال‌های کانال از پیش‌فرض‌های نوع MIME در pipeline رسانه استفاده می‌کنند
</Accordion>
@ -744,14 +763,14 @@ tagهای پاسخ دستی پشتیبانی می‌شوند:
- `user:<id>` برای DMها
- `channel:<id>` برای کانال‌ها
DMهای Slack که فقط متن/بلاک دارند می‌توانند مستقیماً به شناسه‌های کاربر post شوند؛ آپلود فایل و ارسال‌های thread ابتدا DM را از طریق APIهای مکالمه Slack باز می‌کنند، زیرا این مسیرها به یک شناسه مکالمه مشخص نیاز دارند.
DMهای Slack فقط متنی/بلوکی می‌توانند مستقیماً به شناسه‌های کاربر ارسال شوند؛ بارگذاری فایل و ارسال‌های رشته‌ای ابتدا DM را از طریق APIهای گفت‌وگوی Slack باز می‌کنند، چون آن مسیرها به یک شناسه گفت‌وگوی مشخص نیاز دارند.
</Accordion>
</AccordionGroup>
## دستورها و رفتار slash
دستورهای slash در Slack یا به‌صورت یک دستور پیکربندی‌شده واحد ظاهر می‌شوند یا چند دستور native. برای تغییر پیش‌فرض‌های دستور، `channels.slack.slashCommand` را پیکربندی کنید:
دستورهای slash در Slack یا به‌صورت یک دستور پیکربندی‌شده واحد ظاهر می‌شوند یا به‌صورت چند دستور native. برای تغییر پیش‌فرض‌های دستور، `channels.slack.slashCommand` را پیکربندی کنید:
- `enabled: false`
- `name: "openclaw"`
@ -762,7 +781,7 @@ tagهای پاسخ دستی پشتیبانی می‌شوند:
/openclaw /help
```
دستورهای native به [تنظیمات manifest اضافی](#additional-manifest-settings) در برنامه Slack شما نیاز دارند و در عوض با `channels.slack.commands.native: true` یا `commands.native: true` در پیکربندی‌های سراسری فعال می‌شوند.
دستورهای native به [تنظیمات manifest اضافی](#additional-manifest-settings) در برنامه Slack شما نیاز دارند و به‌جای آن با `channels.slack.commands.native: true` یا `commands.native: true` در پیکربندی‌های سراسری فعال می‌شوند.
- حالت خودکار دستور native برای Slack **خاموش** است، بنابراین `commands.native: "auto"` دستورهای native Slack را فعال نمی‌کند.
@ -770,24 +789,24 @@ tagهای پاسخ دستی پشتیبانی می‌شوند:
/help
```
منوهای آرگومان native از راهبرد رندر تطبیقی استفاده می‌کنند که پیش از dispatch کردن مقدار گزینه انتخاب‌شده، یک modal تأیید نشان می‌دهد:
منوهای آرگومان native از یک راهبرد رندر تطبیقی استفاده می‌کنند که پیش از dispatch کردن مقدار گزینه انتخاب‌شده، یک modal تأیید نشان می‌دهد:
- تا 5 گزینه: بلاک‌های دکمه
- 6 تا 100 گزینه: منوی انتخاب static
- بیش از 100 گزینه: انتخاب external با فیلترسازی گزینه async وقتی handlerهای گزینه‌های interactivity در دسترس باشند
- عبور از محدودیت‌های Slack: مقادیر گزینه encoded به دکمه‌ها fallback می‌کنند
- تا 5 گزینه: بلوک‌های دکمه
- 6 تا 100 گزینه: منوی انتخاب ایستا
- بیش از 100 گزینه: انتخاب خارجی با فیلتر ناهمگام گزینه‌ها وقتی handlerهای گزینه‌های interactivity در دسترس باشند
- عبور از محدودیت‌های Slack: مقدارهای کدگذاری‌شده گزینه به دکمه‌ها برمی‌گردند
```txt
/think
```
نشست‌های slash از کلیدهای ایزوله مانند `agent:<agentId>:slack:slash:<userId>` استفاده می‌کنند و همچنان اجرای دستورها را با استفاده از `CommandTargetSessionKey` به نشست مکالمه هدف route می‌کنند.
نشست‌های slash از کلیدهای جداشده‌ای مانند `agent:<agentId>:slack:slash:<userId>` استفاده می‌کنند و همچنان اجرای دستورها را با استفاده از `CommandTargetSessionKey` به نشست گفت‌وگوی مقصد route می‌کنند.
## پاسخ‌های تعاملی
Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌شده توسط عامل را رندر کند، اما این قابلیت به‌طور پیش‌فرض غیرفعال است.
Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌شده توسط agent را رندر کند، اما این قابلیت به‌طور پیش‌فرض غیرفعال است.
آن را به‌صورت سراسری فعال کنید:
فعال‌سازی سراسری:
```json5
{
@ -801,7 +820,7 @@ Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌
}
```
یا آن را فقط برای یک حساب Slack فعال کنید:
یا فقط برای یک حساب Slack فعال کنید:
```json5
{
@ -819,44 +838,44 @@ Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌
}
```
وقتی فعال باشد، عامل‌ها می‌توانند directiveهای پاسخ فقط مخصوص Slack تولید کنند:
پس از فعال‌سازی، agentها می‌توانند دستورهای پاسخ فقط مخصوص Slack منتشر کنند:
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
این directiveها به Slack Block Kit کامپایل می‌شوند و clickها یا انتخاب‌ها را از مسیر event تعامل Slack موجود دوباره route می‌کنند.
این دستورها به Slack Block Kit کامپایل می‌شوند و کلیک‌ها یا انتخاب‌ها را از مسیر موجود رویداد تعامل Slack برمی‌گردانند.
یادداشت‌ها:
نکته‌ها:
- این UI مخصوص Slack است. کانال‌های دیگر directiveهای Slack Block Kit را به سامانه‌های دکمه خودشان ترجمه نمی‌کنند.
- مقادیر callback تعاملی، توکن‌های opaque تولیدشده توسط OpenClaw هستند، نه مقادیر خام نوشته‌شده توسط عامل.
- اگر بلاک‌های تعاملی تولیدشده از محدودیت‌های Slack Block Kit عبور کنند، OpenClaw به‌جای ارسال payload بلاک‌های نامعتبر، به پاسخ متنی اصلی fallback می‌کند.
- این UI مخصوص Slack است. کانال‌های دیگر دستورهای Slack Block Kit را به سیستم‌های دکمه خودشان ترجمه نمی‌کنند.
- مقدارهای callback تعاملی، توکن‌های opaque تولیدشده توسط OpenClaw هستند، نه مقدارهای خام نوشته‌شده توسط agent.
- اگر بلوک‌های تعاملی تولیدشده از محدودیت‌های Slack Block Kit فراتر بروند، OpenClaw به‌جای ارسال payload بلوک‌های نامعتبر، به پاسخ متنی اصلی برمی‌گردد.
## تأییدهای exec در Slack
Slack می‌تواند به‌جای fallback کردن به Web UI یا ترمینال، به‌عنوان یک client تأیید native با دکمه‌ها و تعامل‌های تعاملی عمل کند.
Slack می‌تواند به‌جای برگشت به Web UI یا ترمینال، با دکمه‌ها و تعامل‌های تعاملی به‌عنوان یک client تأیید native عمل کند.
- تأییدهای exec از `channels.slack.execApprovals.*` برای route کردن native در DM/کانال استفاده می‌کنند.
- تأییدهای Plugin همچنان می‌توانند از طریق همان سطح دکمه native Slack resolve شوند، وقتی درخواست از قبل در Slack فرود آمده باشد و نوع شناسه تأیید `plugin:` باشد.
- مجوزدهی تأییدکننده همچنان اعمال می‌شود: فقط کاربرانی که به‌عنوان تأییدکننده شناسایی شده‌اند می‌توانند از طریق Slack درخواست‌ها را تأیید یا رد کنند.
- تأییدهای exec از `channels.slack.execApprovals.*` برای route کردن native به DM/کانال استفاده می‌کنند.
- تأییدهای Plugin همچنان می‌توانند از همان سطح دکمه native در Slack حل شوند، وقتی درخواست از قبل در Slack فرود آمده باشد و نوع شناسه تأیید `plugin:` باشد.
- مجوز تأییدکننده همچنان اعمال می‌شود: فقط کاربرانی که به‌عنوان تأییدکننده شناسایی شده‌اند می‌توانند درخواست‌ها را از طریق Slack تأیید یا رد کنند.
این از همان سطح دکمه تأیید مشترک مانند کانال‌های دیگر استفاده می‌کند. وقتی `interactivity` در تنظیمات برنامه Slack شما فعال باشد، promptهای تأیید مستقیماً در مکالمه به‌صورت دکمه‌های Block Kit رندر می‌شوند.
وقتی آن دکمه‌ها وجود دارند، UX اصلی تأیید هستند؛ OpenClaw
فقط باید زمانی یک دستور دستی `/approve` اضافه کند که نتیجه ابزار بگوید تأییدهای chat
این از همان سطح مشترک دکمه تأیید مثل کانال‌های دیگر استفاده می‌کند. وقتی `interactivity` در تنظیمات برنامه Slack شما فعال باشد، promptهای تأیید مستقیماً در گفت‌وگو به‌صورت دکمه‌های Block Kit رندر می‌شوند.
وقتی آن دکمه‌ها وجود دارند، UX اصلی تأیید همان‌ها هستند؛ OpenClaw
فقط وقتی باید دستور دستی `/approve` را اضافه کند که نتیجه ابزار بگوید تأییدهای chat
در دسترس نیستند یا تأیید دستی تنها مسیر است.
مسیر پیکربندی:
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers` (اختیاری؛ وقتی ممکن باشد به `commands.ownerAllowFrom` fallback می‌کند)
- `channels.slack.execApprovals.approvers` (اختیاری؛ در صورت امکان به `commands.ownerAllowFrom` برمی‌گردد)
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`، پیش‌فرض: `dm`)
- `agentFilter`, `sessionFilter`
وقتی `enabled` تنظیم نشده یا `"auto"` باشد و دست‌کم یک
تأییدکننده resolve شود، Slack تأییدهای exec native را به‌طور خودکار فعال می‌کند. برای غیرفعال کردن صریح Slack به‌عنوان client تأیید native، `enabled: false` را تنظیم کنید.
برای اجبار به روشن بودن تأییدهای native وقتی تأییدکننده‌ها resolve می‌شوند، `enabled: true` را تنظیم کنید.
Slack وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و دست‌کم یک
تأییدکننده حل شود، تأییدهای exec native را به‌طور خودکار فعال می‌کند. برای غیرفعال کردن صریح Slack به‌عنوان client تأیید native، `enabled: false` را تنظیم کنید.
برای اجبار به فعال‌سازی تأییدهای native وقتی تأییدکننده‌ها حل می‌شوند، `enabled: true` را تنظیم کنید.
رفتار پیش‌فرض بدون پیکربندی صریح تأیید exec Slack:
رفتار پیش‌فرض بدون پیکربندی صریح تأیید exec در Slack:
```json5
{
@ -866,8 +885,8 @@ Slack می‌تواند به‌جای fallback کردن به Web UI یا ترم
}
```
پیکربندی صریح native برای Slack فقط زمانی لازم است که بخواهید تأییدکننده‌ها را بازنویسی کنید، فیلتر اضافه کنید، یا
به تحویل در chat مبدأ opt in کنید:
پیکربندی صریح native مربوط به Slack فقط زمانی لازم است که بخواهید تأییدکننده‌ها را بازنویسی کنید، filter اضافه کنید، یا
تحویل به chat مبدأ را فعال کنید:
```json5
{
@ -883,37 +902,37 @@ Slack می‌تواند به‌جای fallback کردن به Web UI یا ترم
}
```
forward کردن مشترک `approvals.exec` جداست. فقط زمانی از آن استفاده کنید که promptهای تأیید exec باید همچنین
به chatهای دیگر یا مقصدهای out-of-band صریح route شوند. forward کردن مشترک `approvals.plugin` نیز
جداست؛ دکمه‌های native Slack همچنان می‌توانند تأییدهای Plugin را resolve کنند، وقتی آن درخواست‌ها از قبل
forwarding مشترک `approvals.exec` جدا است. فقط وقتی از آن استفاده کنید که promptهای تأیید exec باید همچنین
به chatهای دیگر یا مقصدهای out-of-band صریح route شوند. forwarding مشترک `approvals.plugin` نیز
جدا است؛ دکمه‌های native Slack همچنان می‌توانند تأییدهای Plugin را حل کنند، وقتی آن درخواست‌ها از قبل
در Slack فرود آمده باشند.
`/approve` در همان chat نیز در کانال‌ها و DMهای Slack که از قبل از دستورها پشتیبانی می‌کنند کار می‌کند. برای مدل کامل forward کردن تأیید، [تأییدهای exec](/fa/tools/exec-approvals) را ببینید.
`/approve` در همان chat نیز در کانال‌ها و DMهای Slack که از قبل از دستورها پشتیبانی می‌کنند کار می‌کند. برای مدل کامل forwarding تأیید، [تأییدهای exec](/fa/tools/exec-approvals) را ببینید.
## eventها و رفتار عملیاتی
## رویدادها و رفتار عملیاتی
- ویرایش/حذف پیام‌ها به eventهای سامانه map می‌شوند.
- broadcastهای thread (پاسخ‌های thread با گزینه «همچنین به کانال ارسال شود») به‌عنوان پیام‌های عادی کاربر پردازش می‌شوند.
- eventهای افزودن/حذف واکنش به eventهای سامانه map می‌شوند.
- eventهای پیوستن/خروج عضو، ایجاد/تغییرنام کانال، و افزودن/حذف pin به eventهای سامانه map می‌شوند.
- `channel_id_changed` می‌تواند وقتی `configWrites` فعال باشد، کلیدهای پیکربندی کانال را migrate کند.
- فراداده topic/purpose کانال به‌عنوان context غیرقابل اعتماد تلقی می‌شود و می‌تواند به context routing تزریق شود.
- آغازگر thread و seeding context تاریخچه اولیه thread، در صورت کاربرد، با allowlistهای فرستنده پیکربندی‌شده فیلتر می‌شوند.
- کنش‌های بلاک و تعامل‌های modal، eventهای ساختاریافته سامانه با قالب `Slack interaction: ...` و fieldهای payload غنی تولید می‌کنند:
- کنش‌های بلاک: مقادیر انتخاب‌شده، برچسب‌ها، مقادیر picker و فراداده `workflow_*`
- eventهای modal `view_submission` و `view_closed` با فراداده کانال routeشده و ورودی‌های فرم
- ویرایش/حذف پیام‌ها به رویدادهای سیستم نگاشت می‌شوند.
- پخش‌های رشته‌ای (پاسخ‌های رشته‌ای «Also send to channel») به‌عنوان پیام‌های عادی کاربر پردازش می‌شوند.
- رویدادهای افزودن/حذف واکنش به رویدادهای سیستم نگاشت می‌شوند.
- رویدادهای پیوستن/ترک عضو، ایجاد/تغییرنام کانال، و افزودن/حذف pin به رویدادهای سیستم نگاشت می‌شوند.
- وقتی `configWrites` فعال باشد، `channel_id_changed` می‌تواند کلیدهای پیکربندی کانال را migrate کند.
- metadata موضوع/هدف کانال به‌عنوان context غیرقابل اعتماد در نظر گرفته می‌شود و می‌تواند به context route کردن inject شود.
- آغازکننده رشته و seed کردن context اولیه تاریخچه رشته، در صورت کاربرد، بر اساس allowlistهای فرستنده پیکربندی‌شده filter می‌شوند.
- کنش‌های بلوک و تعامل‌های modal رویدادهای ساخت‌یافته سیستم `Slack interaction: ...` را با فیلدهای payload غنی منتشر می‌کنند:
- کنش‌های بلوک: مقدارهای انتخاب‌شده، labelها، مقدارهای picker، و metadata مربوط به `workflow_*`
- رویدادهای modal `view_submission` و `view_closed` با metadata کانال route‌شده و ورودی‌های فرم
## مرجع پیکربندی
مرجع اصلی: [مرجع پیکربندی - Slack](/fa/gateway/config-channels#slack).
<Accordion title="فیلدهای مهم Slack">
<Accordion title="فیلدهای پرسیگنال Slack">
- mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
- دسترسی DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- دسترسی DM: `dm.enabled`, `dmPolicy`, `allowFrom` (قدیمی: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- toggle سازگاری: `dangerouslyAllowNameMatching` (break-glass؛ مگر در صورت نیاز خاموش نگه دارید)
- دسترسی کانال: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- thread/history: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- رشته‌بندی/تاریخچه: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- تحویل: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
- عملیات/قابلیت‌ها: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
@ -922,13 +941,13 @@ forward کردن مشترک `approvals.exec` جداست. فقط زمانی از
## عیب‌یابی
<AccordionGroup>
<Accordion title="پاسخی در کانال‌ها وجود ندارد">
<Accordion title="هیچ پاسخی در کانال‌ها دریافت نمی‌شود">
به‌ترتیب بررسی کنید:
- `groupPolicy`
- allowlist کانال (`channels.slack.channels`) — **کلیدها باید شناسه کانال باشند** (`C12345678`)، نه نام‌ها (`#channel-name`). کلیدهای مبتنی بر نام تحت `groupPolicy: "allowlist"` بی‌صدا شکست می‌خورند، زیرا routing کانال به‌طور پیش‌فرض ابتدا بر اساس شناسه است. برای یافتن شناسه: روی کانال در Slack راست‌کلیک کنید → **Copy link** — مقدار `C...` در انتهای URL شناسه کانال است.
- allowlist کانال (`channels.slack.channels`) — **کلیدها باید شناسه کانال باشند** (`C12345678`)، نه نام‌ها (`#channel-name`). کلیدهای مبتنی بر نام زیر `groupPolicy: "allowlist"` بی‌صدا شکست می‌خورند، چون route کردن کانال به‌طور پیش‌فرض ID-first است. برای پیدا کردن یک ID: روی کانال در Slack راست‌کلیک کنید → **Copy link** — مقدار `C...` در انتهای URL شناسه کانال است.
- `requireMention`
- allowlist کاربران برای هر کانال
- allowlist کاربران در سطح هر کانال
دستورهای مفید:
@ -944,11 +963,11 @@ openclaw doctor
بررسی کنید:
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy` (یا legacy `channels.slack.dm.policy`)
- `channels.slack.dmPolicy` (یا گزینه قدیمی `channels.slack.dm.policy`)
- تأییدهای pairing / ورودی‌های allowlist
- eventهای DM دستیار Slack: لاگ‌های verbose که به `drop message_changed` اشاره می‌کنند
معمولاً یعنی Slack یک event ویرایش‌شده thread دستیار را بدون
فرستنده انسانی قابل بازیابی در فراداده پیام ارسال کرده است
- رویدادهای DM مربوط به Slack Assistant: logهای verbose که `drop message_changed` را ذکر می‌کنند
معمولاً یعنی Slack یک رویداد ویرایش‌شده Assistant-thread بدون
فرستنده انسانی قابل بازیابی در metadata پیام فرستاده است
```bash
openclaw pairing list slack
@ -957,16 +976,16 @@ openclaw pairing list slack
</Accordion>
<Accordion title="Socket mode وصل نمی‌شود">
توکن‌های bot و app و فعال‌سازی Socket Mode را در تنظیمات برنامه Slack اعتبارسنجی کنید.
توکن‌های bot + app و فعال بودن Socket Mode را در تنظیمات برنامه Slack اعتبارسنجی کنید.
اگر `openclaw channels status --probe --json` مقدار `botTokenStatus` یا
`appTokenStatus: "configured_unavailable"` را نشان می‌دهد، حساب Slack
پیکربندی شده است اما runtime فعلی نتوانسته مقدار پشتوانه‌شده با SecretRef را
پیکربندی شده است اما runtime فعلی نتوانسته مقدار پشتیبانی‌شده با SecretRef را
resolve کند.
</Accordion>
<Accordion title="HTTP mode eventها را دریافت نمی‌کند">
<Accordion title="HTTP mode رویدادها را دریافت نمی‌کند">
اعتبارسنجی کنید:
- signing secret
@ -975,106 +994,106 @@ openclaw pairing list slack
- `webhookPath` یکتا برای هر حساب HTTP
اگر `signingSecretStatus: "configured_unavailable"` در snapshotهای حساب
ظاهر شود، حساب HTTP پیکربندی شده است اما runtime فعلی نتوانسته signing secret پشتوانه‌شده با SecretRef را
resolve کند.
ظاهر شود، حساب HTTP پیکربندی شده است اما runtime فعلی نتوانسته
signing secret پشتیبانی‌شده با SecretRef را resolve کند.
</Accordion>
<Accordion title="دستورهای native/slash اجرا نمی‌شوند">
بررسی کنید که کدام را مدنظر داشتید:
بررسی کنید که منظورتان کدام بوده است:
- حالت دستور native (`channels.slack.commands.native: true`) با دستورهای slash متناظر ثبت‌شده در Slack
- یا حالت تک دستور slash (`channels.slack.slashCommand.enabled: true`)
- یا حالت دستور slash واحد (`channels.slack.slashCommand.enabled: true`)
همچنین `commands.useAccessGroups` و allowlistهای کانال/کاربر را بررسی کنید.
</Accordion>
</AccordionGroup>
## مرجع vision پیوست‌ها
## مرجع vision پیوست
Slack می‌تواند وقتی دانلود فایل‌های Slack موفق باشد و محدودیت‌های اندازه اجازه دهند، رسانه دانلودشده را به turn عامل پیوست کند. فایل‌های تصویری می‌توانند از مسیر درک رسانه عبور داده شوند یا مستقیماً به یک مدل پاسخ vision-capable داده شوند؛ فایل‌های دیگر به‌جای اینکه به‌عنوان ورودی تصویر تلقی شوند، به‌صورت context فایل قابل دانلود نگه داشته می‌شوند.
Slack وقتی دانلود فایل‌های Slack موفق باشند و محدودیت‌های اندازه اجازه دهند، می‌تواند رسانه دانلودشده را به turn مربوط به agent پیوست کند. فایل‌های تصویر می‌توانند از مسیر درک رسانه عبور داده شوند یا مستقیماً به مدل پاسخ دارای قابلیت vision داده شوند؛ فایل‌های دیگر به‌جای اینکه به‌عنوان ورودی تصویر در نظر گرفته شوند، به‌عنوان context فایل قابل دانلود نگه داشته می‌شوند.
### انواع رسانه پشتیبانی‌شده
| نوع رسانه | منبع | رفتار فعلی | یادداشت‌ها |
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| تصاویر JPEG / PNG / GIF / WebP | URL فایل Slack | دانلود و برای پردازش با قابلیت بینایی به نوبت پیوست می‌شود | سقف هر فایل: `channels.slack.mediaMaxMb` (پیش‌فرض ۲۰ MB) |
| فایل‌های PDF | URL فایل Slack | دانلود و به‌عنوان زمینهٔ فایل برای ابزارهایی مانند `download-file` یا `pdf` ارائه می‌شود | ورودی Slack به‌طور خودکار PDFها را به ورودی بینایی تصویری تبدیل نمی‌کند |
| فایل‌های دیگر | URL فایل Slack | در صورت امکان دانلود و به‌عنوان زمینهٔ فایل ارائه می‌شود | فایل‌های باینری به‌عنوان ورودی تصویر در نظر گرفته نمی‌شوند |
| پاسخ‌های رشته | فایل‌های شروع‌کنندهٔ رشته | وقتی پاسخ رسانهٔ مستقیم ندارد، فایل‌های پیام ریشه می‌توانند به‌عنوان زمینه آماده‌سازی شوند | شروع‌کننده‌های فقط‌فایل از جای‌نگهدار پیوست استفاده می‌کنند |
| پیام‌های چندتصویری | چند فایل Slack | هر فایل به‌طور مستقل ارزیابی می‌شود | پردازش Slack به هشت فایل برای هر پیام محدود است |
| تصاویر JPEG / PNG / GIF / WebP | URL فایل Slack | دانلود می‌شود و برای پردازش دارای قابلیت بینایی به نوبت پیوست می‌شود | سقف هر فایل: `channels.slack.mediaMaxMb` (پیش‌فرض 20 MB) |
| فایل‌های PDF | URL فایل Slack | دانلود می‌شود و به‌عنوان زمینهٔ فایل برای ابزارهایی مانند `download-file` یا `pdf` در دسترس قرار می‌گیرد | ورودی Slack به‌طور خودکار PDFها را به ورودی بینایی تصویر تبدیل نمی‌کند |
| فایل‌های دیگر | URL فایل Slack | در صورت امکان دانلود می‌شود و به‌عنوان زمینهٔ فایل در دسترس قرار می‌گیرد | فایل‌های باینری به‌عنوان ورودی تصویر در نظر گرفته نمی‌شوند |
| پاسخ‌های رشته | فایل‌های آغازگر رشته | فایل‌های پیام ریشه وقتی پاسخ رسانهٔ مستقیم ندارد می‌توانند به‌عنوان زمینه بارگذاری شوند | آغازگرهای فقط‌فایل از یک جای‌نگهدار پیوست استفاده می‌کنند |
| پیام‌های چندتصویری | چند فایل Slack | هر فایل به‌صورت مستقل ارزیابی می‌شود | پردازش Slack به هشت فایل برای هر پیام محدود است |
### خط لولهٔ ورودی
وقتی یک پیام Slack همراه با پیوست‌های فایل می‌رسد:
وقتی یک پیام Slack با پیوست‌های فایل می‌رسد:
1. OpenClaw فایل را از URL خصوصی Slack با استفاده از توکن ربات (`xoxb-...`) دانلود می‌کند.
2. در صورت موفقیت، فایل در ذخیره‌گاه رسانه نوشته می‌شود.
2. فایل در صورت موفقیت در انبار رسانه نوشته می‌شود.
3. مسیرهای رسانهٔ دانلودشده و نوع‌های محتوا به زمینهٔ ورودی افزوده می‌شوند.
4. مسیرهای مدل/ابزار دارای قابلیت تصویر می‌توانند از پیوست‌های تصویری آن زمینه استفاده کنند.
4. مسیرهای مدل/ابزار دارای قابلیت تصویر می‌توانند از پیوست‌های تصویر موجود در آن زمینه استفاده کنند.
5. فایل‌های غیرتصویری همچنان به‌صورت فرادادهٔ فایل یا ارجاع‌های رسانه برای ابزارهایی که می‌توانند آن‌ها را پردازش کنند در دسترس می‌مانند.
### ارث‌بری پیوست از ریشهٔ رشته
### وراثت پیوست ریشهٔ رشته
وقتی پیامی در یک رشته می‌رسد (دارای والد `thread_ts` است):
وقتی پیامی در یک رشته می‌رسد (یک والد `thread_ts` دارد):
- اگر خود پاسخ رسانهٔ مستقیم نداشته باشد و پیام ریشهٔ شامل‌شده فایل داشته باشد، Slack می‌تواند فایل‌های ریشه را به‌عنوان زمینهٔ شروع‌کنندهٔ رشته آماده‌سازی کند.
- اگر خود پاسخ رسانهٔ مستقیم نداشته باشد و پیام ریشهٔ گنجانده‌شده فایل داشته باشد، Slack می‌تواند فایل‌های ریشه را به‌عنوان زمینهٔ آغازگر رشته بارگذاری کند.
- پیوست‌های مستقیم پاسخ بر پیوست‌های پیام ریشه اولویت دارند.
- پیام ریشه‌ای که فقط فایل دارد و متن ندارد، با یک جای‌نگهدار پیوست نمایش داده می‌شود تا مسیر جایگزین همچنان بتواند فایل‌های آن را شامل کند.
- پیام ریشه‌ای که فقط فایل دارد و متن ندارد با یک جای‌نگهدار پیوست نمایش داده می‌شود تا مسیر پشتیبان همچنان بتواند فایل‌های آن را شامل شود.
### پردازش چندپیوستی
### مدیریت چند پیوست
وقتی یک پیام Slack شامل چند پیوست فایل باشد:
- هر پیوست به‌طور مستقل از خط لولهٔ رسانه پردازش می‌شود.
- هر پیوست به‌صورت مستقل از طریق خط لولهٔ رسانه پردازش می‌شود.
- ارجاع‌های رسانهٔ دانلودشده در زمینهٔ پیام تجمیع می‌شوند.
- ترتیب پردازش از ترتیب فایل‌های Slack در payload رویداد پیروی می‌کند.
- شکست در دانلود یک پیوست، پیوست‌های دیگر را مسدود نمی‌کند.
- ترتیب پردازش از ترتیب فایل‌های Slack در بار رویداد پیروی می‌کند.
- شکست در دانلود یک پیوست، سایر پیوست‌ها را مسدود نمی‌کند.
### محدودیت‌های اندازه، دانلود و مدل
- **سقف اندازه**: پیش‌فرض ۲۰ MB برای هر فایل. از طریق `channels.slack.mediaMaxMb` قابل پیکربندی است.
- **شکست‌های دانلود**: فایل‌هایی که Slack نمی‌تواند ارائه کند، URLهای منقضی‌شده، فایل‌های غیرقابل‌دسترسی، فایل‌های بیش‌ازحد بزرگ، و پاسخ‌های HTML ورود/احراز هویت Slack به‌جای گزارش شدن به‌عنوان قالب‌های پشتیبانی‌نشده نادیده گرفته می‌شوند.
- **مدل بینایی**: تحلیل تصویر از مدل پاسخ فعال استفاده می‌کند، اگر از بینایی پشتیبانی کند؛ در غیر این صورت از مدل تصویر پیکربندی‌شده در `agents.defaults.imageModel` استفاده می‌شود.
- **سقف اندازه**: پیش‌فرض 20 MB برای هر فایل. از طریق `channels.slack.mediaMaxMb` قابل پیکربندی است.
- **شکست‌های دانلود**: فایل‌هایی که Slack نمی‌تواند ارائه کند، URLهای منقضی‌شده، فایل‌های غیرقابل‌دسترسی، فایل‌های بیش‌ازحد بزرگ، و پاسخ‌های HTML مربوط به احراز هویت/ورود Slack به‌جای اینکه به‌عنوان قالب‌های پشتیبانی‌نشده گزارش شوند، نادیده گرفته می‌شوند.
- **مدل بینایی**: تحلیل تصویر وقتی مدل پاسخ فعال از بینایی پشتیبانی کند از همان مدل استفاده می‌کند، یا از مدل تصویر پیکربندی‌شده در `agents.defaults.imageModel` استفاده می‌کند.
### محدودیت‌های شناخته‌شده
| سناریو | رفتار فعلی | راهکار جایگزین |
| سناریو | رفتار فعلی | راه‌حل جایگزین |
| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| URL منقضی‌شدهٔ فایل Slack | فایل نادیده گرفته می‌شود؛ خطایی نشان داده نمی‌شود | فایل را دوباره در Slack بارگذاری کنید |
| مدل بینایی پیکربندی نشده است | پیوست‌های تصویری به‌عنوان ارجاع‌های رسانه ذخیره می‌شوند، اما به‌عنوان تصویر تحلیل نمی‌شوند | `agents.defaults.imageModel` را پیکربندی کنید یا از مدل پاسخ دارای قابلیت بینایی استفاده کنید |
| تصاویر بسیار بزرگ (بیش از ۲۰ MB به‌طور پیش‌فرض) | طبق سقف اندازه نادیده گرفته می‌شوند | اگر Slack اجازه می‌دهد، `channels.slack.mediaMaxMb` را افزایش دهید |
| پیوست‌های بازفرستاده/اشتراک‌گذاری‌شده | متن و رسانهٔ تصویر/فایل میزبانی‌شده در Slack به‌صورت بهترین تلاش پردازش می‌شوند | مستقیماً در رشتهٔ OpenClaw دوباره به اشتراک بگذارید |
| پیوست‌های PDF | به‌عنوان زمینهٔ فایل/رسانه ذخیره می‌شوند، نه اینکه به‌طور خودکار از مسیر بینایی تصویر عبور داده شوند | برای فرادادهٔ فایل از `download-file` یا برای تحلیل PDF از ابزار `pdf` استفاده کنید |
| URL فایل Slack منقضی شده | فایل نادیده گرفته می‌شود؛ خطایی نمایش داده نمی‌شود | فایل را دوباره در Slack بارگذاری کنید |
| مدل بینایی پیکربندی نشده است | پیوست‌های تصویر به‌عنوان ارجاع‌های رسانه ذخیره می‌شوند، اما به‌عنوان تصویر تحلیل نمی‌شوند | `agents.defaults.imageModel` را پیکربندی کنید یا از یک مدل پاسخ دارای قابلیت بینایی استفاده کنید |
| تصاویر بسیار بزرگ (> 20 MB به‌صورت پیش‌فرض) | طبق سقف اندازه نادیده گرفته می‌شود | اگر Slack اجازه می‌دهد، `channels.slack.mediaMaxMb` را افزایش دهید |
| پیوست‌های فورواردشده/اشتراک‌گذاری‌شده | متن و رسانهٔ تصویر/فایل میزبانی‌شده در Slack به‌صورت بهترین تلاش پردازش می‌شوند | مستقیماً در رشتهٔ OpenClaw دوباره به اشتراک بگذارید |
| پیوست‌های PDF | به‌عنوان زمینهٔ فایل/رسانه ذخیره می‌شوند، نه اینکه به‌طور خودکار از مسیر بینایی تصویر عبور کنند | از `download-file` برای فرادادهٔ فایل یا از ابزار `pdf` برای تحلیل PDF استفاده کنید |
### مستندات مرتبط
- [خط لولهٔ درک رسانه](/fa/nodes/media-understanding)
- [ابزار PDF](/fa/tools/pdf)
- اپیک: [#51349](https://github.com/openclaw/openclaw/issues/51349) — فعال‌سازی بینایی برای پیوست‌های Slack
- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — فعال‌سازی بینایی پیوست‌های Slack
- آزمون‌های رگرسیون: [#51353](https://github.com/openclaw/openclaw/issues/51353)
- راستی‌آزمایی زنده: [#51354](https://github.com/openclaw/openclaw/issues/51354)
## مرتبط
<CardGroup cols={2}>
<Card title="Pairing" icon="link" href="/fa/channels/pairing">
یک کاربر Slack را با Gateway جفت کنید.
<Card title="جفت‌سازی" icon="link" href="/fa/channels/pairing">
یک کاربر Slack را به Gateway جفت کنید.
</Card>
<Card title="Groups" icon="users" href="/fa/channels/groups">
رفتار کانال و پیام مستقیم گروهی.
<Card title="گروه‌ها" icon="users" href="/fa/channels/groups">
رفتار کانال و DM گروهی.
</Card>
<Card title="Channel routing" icon="route" href="/fa/channels/channel-routing">
<Card title="مسیریابی کانال" icon="route" href="/fa/channels/channel-routing">
پیام‌های ورودی را به عامل‌ها مسیریابی کنید.
</Card>
<Card title="Security" icon="shield" href="/fa/gateway/security">
<Card title="امنیت" icon="shield" href="/fa/gateway/security">
مدل تهدید و سخت‌سازی.
</Card>
<Card title="Configuration" icon="sliders" href="/fa/gateway/configuration">
چیدمان پیکربندی و تقدم.
<Card title="پیکربندی" icon="sliders" href="/fa/gateway/configuration">
چیدمان پیکربندی و اولویت‌بندی.
</Card>
<Card title="Slash commands" icon="terminal" href="/fa/tools/slash-commands">
<Card title="فرمان‌های اسلش" icon="terminal" href="/fa/tools/slash-commands">
فهرست فرمان‌ها و رفتار.
</Card>
</CardGroup>

556
docs/fa/channels/telegram.md
View File

@ -1,25 +1,25 @@
---
read_when:
- کار روی قابلیت‌های Telegram یا Webhookها
summary: وضعیت پشتیبانی، قابلیت‌ها و پیکربندی ربات Telegram
- کار روی قابلیت‌های Telegram یا Webhook‌ها
summary: وضعیت پشتیبانی ربات Telegram، قابلیت‌ها و پیکربندی
title: Telegram
x-i18n:
generated_at: "2026-05-03T21:27:10Z"
generated_at: "2026-05-04T07:02:42Z"
model: gpt-5.5
provider: openai
source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0
source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6
source_path: channels/telegram.md
workflow: 16
---
آماده برای تولید برای DMهای ربات و گروه‌ها از طریق grammY. حالت پیش‌فرض، long polling است؛ حالت Webhook اختیاری است.
آمادهٔ تولید برای DMهای ربات و گروه‌ها از طریق grammY. حالت پیش‌فرض long polling است؛ حالت Webhook اختیاری است.
<CardGroup cols={3}>
<Card title="جفت‌سازی" icon="link" href="/fa/channels/pairing">
سیاست پیش‌فرض DM برای Telegram جفت‌سازی است.
سیاست DM پیش‌فرض برای Telegram جفت‌سازی است.
</Card>
<Card title="عیب‌یابی کانال" icon="wrench" href="/fa/channels/troubleshooting">
عیب‌یابی‌های میان‌کانالی و راهنماهای تعمیر.
عیب‌یابی‌های میان‌کانالی و راهنماهای رفع مشکل.
</Card>
<Card title="پیکربندی Gateway" icon="settings" href="/fa/gateway/configuration">
الگوها و مثال‌های کامل پیکربندی کانال.
@ -30,7 +30,7 @@ x-i18n:
<Steps>
<Step title="ساخت توکن ربات در BotFather">
Telegram را باز کنید و با **@BotFather** گفت‌وگو کنید (مطمئن شوید handle دقیقاً `@BotFather` است).
Telegram را باز کنید و با **@BotFather** گفتگو کنید (تأیید کنید که شناسه دقیقاً `@BotFather` است).
دستور `/newbot` را اجرا کنید، اعلان‌ها را دنبال کنید، و توکن را ذخیره کنید.
@ -51,7 +51,7 @@ x-i18n:
}
```
fallback محیطی: `TELEGRAM_BOT_TOKEN=...` (فقط حساب پیش‌فرض).
جایگزین env: `TELEGRAM_BOT_TOKEN=...` (فقط حساب پیش‌فرض).
Telegram از `openclaw channels login telegram` استفاده **نمی‌کند**؛ توکن را در config/env پیکربندی کنید، سپس gateway را شروع کنید.
</Step>
@ -74,35 +74,35 @@ openclaw pairing approve telegram <CODE>
</Steps>
<Note>
ترتیب resolve شدن توکن، وابسته به حساب است. در عمل، مقادیر config بر fallback محیطی اولویت دارند، و `TELEGRAM_BOT_TOKEN` فقط روی حساب پیش‌فرض اعمال می‌شود.
ترتیب حل توکن از حساب آگاه است. در عمل، مقدارهای config بر جایگزین env اولویت دارند، و `TELEGRAM_BOT_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود.
</Note>
## تنظیمات سمت Telegram
<AccordionGroup>
<Accordion title="حالت حریم خصوصی و دیده‌شدن گروه">
ربات‌های Telegram به‌طور پیش‌فرض از **Privacy Mode** استفاده می‌کنند، که پیام‌های گروهی دریافتی آن‌ها را محدود می‌کند.
<Accordion title="حالت حریم خصوصی و مشاهده‌پذیری گروه">
ربات‌های Telegram به‌صورت پیش‌فرض در **Privacy Mode** هستند، که پیام‌های گروهی دریافتی آن‌ها را محدود می‌کند.
اگر ربات باید همه پیام‌های گروه را ببیند، یکی از این کارها را انجام دهید:
- privacy mode را از طریق `/setprivacy` غیرفعال کنید، یا
- ربات را admin گروه کنید.
- حالت حریم خصوصی را از طریق `/setprivacy` غیرفعال کنید، یا
- ربات را مدیر گروه کنید.
هنگام تغییر privacy mode، ربات را در هر گروه حذف و دوباره اضافه کنید تا Telegram تغییر را اعمال کند.
هنگام تغییر حالت حریم خصوصی، ربات را در هر گروه حذف و دوباره اضافه کنید تا Telegram تغییر را اعمال کند.
</Accordion>
<Accordion title="مجوزهای گروه">
وضعیت admin در تنظیمات گروه Telegram کنترل می‌شود.
وضعیت مدیر بودن در تنظیمات گروه Telegram کنترل می‌شود.
ربات‌های admin همه پیام‌های گروه را دریافت می‌کنند، که برای رفتار گروهی همیشه‌فعال مفید است.
ربات‌های مدیر همه پیام‌های گروه را دریافت می‌کنند، که برای رفتار همیشه‌فعال در گروه مفید است.
</Accordion>
<Accordion title="تغییرات مفید BotFather">
<Accordion title="کلیدهای مفید BotFather">
- `/setjoingroups` برای اجازه دادن یا ندادن به افزودن به گروه
- `/setprivacy` برای رفتار دیده‌شدن در گروه
- `/setjoingroups` برای مجاز/غیرمجاز کردن افزودن به گروه‌ها
- `/setprivacy` برای رفتار مشاهده‌پذیری گروه
</Accordion>
</AccordionGroup>
@ -114,25 +114,25 @@ openclaw pairing approve telegram <CODE>
`channels.telegram.dmPolicy` دسترسی پیام مستقیم را کنترل می‌کند:
- `pairing` (پیش‌فرض)
- `allowlist` (حداقل به یک شناسه فرستنده در `allowFrom` نیاز دارد)
- `open` (نیاز دارد `allowFrom` شامل `"*"` باشد)
- `allowlist` (نیازمند حداقل یک شناسه فرستنده در `allowFrom`)
- `open` (نیازمند این است که `allowFrom` شامل `"*"` باشد)
- `disabled`
`dmPolicy: "open"` همراه با `allowFrom: ["*"]` به هر حساب Telegram که نام کاربری ربات را پیدا یا حدس بزند اجازه می‌دهد به ربات فرمان بدهد. فقط برای ربات‌های عمداً عمومی با ابزارهای بسیار محدود از آن استفاده کنید؛ ربات‌های تک‌مالک باید از `allowlist` با شناسه‌های عددی کاربر استفاده کنند.
`dmPolicy: "open"` همراه با `allowFrom: ["*"]` به هر حساب Telegram که نام کاربری ربات را پیدا یا حدس بزند اجازه می‌دهد به ربات فرمان بدهد. آن را فقط برای ربات‌های عمداً عمومی با ابزارهای به‌شدت محدود استفاده کنید؛ ربات‌های تک‌مالک باید از `allowlist` با شناسه‌های عددی کاربر استفاده کنند.
`channels.telegram.allowFrom` شناسه‌های عددی کاربر Telegram را می‌پذیرد. پیشوندهای `telegram:` / `tg:` پذیرفته و نرمال‌سازی می‌شوند.
در پیکربندی‌های چندحسابی، یک `channels.telegram.allowFrom` محدودکننده در سطح بالا به‌عنوان مرز ایمنی در نظر گرفته می‌شود: ورودی‌های سطح حساب `allowFrom: ["*"]` آن حساب را عمومی نمی‌کنند مگر اینکه allowlist مؤثر حساب پس از ادغام همچنان دارای یک wildcard صریح باشد.
در configهای چندحسابی، یک `channels.telegram.allowFrom` محدودکننده در سطح بالا به‌عنوان مرز ایمنی در نظر گرفته می‌شود: ورودی‌های سطح حساب `allowFrom: ["*"]` آن حساب را عمومی نمی‌کنند مگر اینکه allowlist مؤثر حساب پس از ادغام همچنان یک wildcard صریح داشته باشد.
`dmPolicy: "allowlist"` با `allowFrom` خالی همه DMها را مسدود می‌کند و توسط اعتبارسنجی config رد می‌شود.
راه‌اندازی فقط شناسه‌های عددی کاربر را درخواست می‌کند.
اگر ارتقا داده‌اید و config شما شامل ورودی‌های allowlist به شکل `@username` است، برای resolve کردن آن‌ها `openclaw doctor --fix` را اجرا کنید (تا حد امکان؛ به توکن ربات Telegram نیاز دارد).
اگر پیش‌تر به فایل‌های allowlist در pairing-store متکی بودید، `openclaw doctor --fix` می‌تواند ورودی‌ها را در جریان‌های allowlist به `channels.telegram.allowFrom` بازیابی کند (برای مثال وقتی `dmPolicy: "allowlist"` هنوز هیچ شناسه صریحی ندارد).
اگر ارتقا داده‌اید و config شما شامل ورودی‌های allowlist از نوع `@username` است، برای حل آن‌ها `openclaw doctor --fix` را اجرا کنید (بهترین تلاش؛ نیازمند توکن ربات Telegram).
اگر قبلاً به فایل‌های allowlist ذخیره جفت‌سازی متکی بودید، `openclaw doctor --fix` می‌تواند ورودی‌ها را در جریان‌های allowlist به `channels.telegram.allowFrom` بازیابی کند (برای مثال وقتی `dmPolicy: "allowlist"` هنوز هیچ شناسه صریحی ندارد).
برای ربات‌های تک‌مالک، `dmPolicy: "allowlist"` با شناسه‌های عددی صریح `allowFrom` را ترجیح دهید تا سیاست دسترسی در config پایدار بماند (به‌جای وابستگی به تأییدهای جفت‌سازی قبلی).
برای ربات‌های تک‌مالک، `dmPolicy: "allowlist"` را با شناسه‌های عددی صریح `allowFrom` ترجیح دهید تا سیاست دسترسی در config پایدار بماند (به‌جای وابستگی به تأییدهای قبلی جفت‌سازی).
سردرگمی رایج: تأیید جفت‌سازی DM به معنی «این فرستنده همه‌جا مجاز است» نیست.
جفت‌سازی دسترسی DM می‌دهد. اگر هنوز مالک فرمانی وجود نداشته باشد، اولین جفت‌سازی تأییدشده همچنین `commands.ownerAllowFrom` را تنظیم می‌کند تا فرمان‌های فقط‌مالک و تأییدهای exec یک حساب اپراتور صریح داشته باشند.
مجوز فرستنده گروه همچنان از allowlistهای صریح config می‌آید.
اگر می‌خواهید «من یک‌بار مجاز شوم و هم DMها و هم فرمان‌های گروهی کار کنند»، شناسه عددی کاربر Telegram خود را در `channels.telegram.allowFrom` قرار دهید؛ برای فرمان‌های فقط‌مالک، مطمئن شوید `commands.ownerAllowFrom` شامل `telegram:<your user id>` است.
ابهام رایج: تأیید جفت‌سازی DM به معنی «این فرستنده در همه‌جا مجاز است» نیست.
جفت‌سازی دسترسی DM را اعطا می‌کند. اگر هنوز مالک فرمانی وجود نداشته باشد، اولین جفت‌سازی تأییدشده همچنین `commands.ownerAllowFrom` را تنظیم می‌کند تا فرمان‌های فقط‌مالک و تأییدهای exec یک حساب اپراتور صریح داشته باشند.
مجوز فرستنده در گروه همچنان از allowlistهای صریح config می‌آید.
اگر می‌خواهید «یک‌بار مجاز شوم و هم DMها و هم فرمان‌های گروه کار کنند»، شناسه عددی کاربر Telegram خود را در `channels.telegram.allowFrom` قرار دهید؛ برای فرمان‌های فقط‌مالک، مطمئن شوید `commands.ownerAllowFrom` شامل `telegram:<your user id>` است.
### یافتن شناسه کاربر Telegram شما
@ -148,7 +148,7 @@ openclaw pairing approve telegram <CODE>
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
```
روش شخص ثالث (با حریم خصوصی کمتر): `@userinfobot` یا `@getidsbot`.
روش شخص ثالث (کمتر خصوصی): `@userinfobot` یا `@getidsbot`.
</Tab>
@ -156,10 +156,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
دو کنترل با هم اعمال می‌شوند:
1. **کدام گروه‌ها مجاز هستند** (`channels.telegram.groups`)
- بدون config برای `groups`:
- با `groupPolicy: "open"`: هر گروهی می‌تواند بررسی‌های شناسه گروه را پاس کند
- با `groupPolicy: "allowlist"` (پیش‌فرض): گروه‌ها تا زمانی که ورودی‌های `groups` (یا `"*"`) را اضافه نکنید مسدود می‌شوند
- `groups` پیکربندی‌شده: به‌عنوان allowlist عمل می‌کند (شناسه‌های صریح یا `"*"`)
- بدون config مربوط به `groups`:
- با `groupPolicy: "open"`: هر گروهی می‌تواند بررسی‌های شناسه گروه را بگذراند
- با `groupPolicy: "allowlist"` (پیش‌فرض): گروه‌ها مسدود می‌شوند تا زمانی که ورودی‌های `groups` (یا `"*"`) را اضافه کنید
- وقتی `groups` پیکربندی شده باشد: مانند allowlist عمل می‌کند (شناسه‌های صریح یا `"*"`)
2. **کدام فرستنده‌ها در گروه‌ها مجاز هستند** (`channels.telegram.groupPolicy`)
- `open`
@ -168,15 +168,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
`groupAllowFrom` برای فیلتر کردن فرستنده گروه استفاده می‌شود. اگر تنظیم نشده باشد، Telegram به `allowFrom` برمی‌گردد.
ورودی‌های `groupAllowFrom` باید شناسه‌های عددی کاربر Telegram باشند (پیشوندهای `telegram:` / `tg:` نرمال‌سازی می‌شوند).
شناسه‌های chat گروه یا supergroup در Telegram را در `groupAllowFrom` قرار ندهید. شناسه‌های chat منفی باید زیر `channels.telegram.groups` قرار بگیرند.
شناسه‌های گفتگوی گروه یا ابرگروه Telegram را در `groupAllowFrom` قرار ندهید. شناسه‌های منفی گفتگو زیر `channels.telegram.groups` قرار می‌گیرند.
ورودی‌های غیرعددی برای مجوز فرستنده نادیده گرفته می‌شوند.
مرز امنیتی (`2026.2.25+`): احراز مجوز فرستنده گروه، تأییدهای pairing-store مربوط به DM را به ارث **نمی‌برد**.
جفت‌سازی فقط برای DM باقی می‌ماند. برای گروه‌ها، `groupAllowFrom` یا `allowFrom` در سطح هر گروه/هر topic را تنظیم کنید.
اگر `groupAllowFrom` تنظیم نشده باشد، Telegram به `allowFrom` در config برمی‌گردد، نه pairing store.
مرز امنیتی (`2026.2.25+`): احراز هویت فرستنده گروه، تأییدهای ذخیره جفت‌سازی DM را به ارث **نمی‌برد**.
جفت‌سازی فقط برای DM باقی می‌ماند. برای گروه‌ها، `groupAllowFrom` یا `allowFrom` در سطح هر گروه/هر موضوع را تنظیم کنید.
اگر `groupAllowFrom` تنظیم نشده باشد، Telegram به config `allowFrom` برمی‌گردد، نه ذخیره جفت‌سازی.
الگوی عملی برای ربات‌های تک‌مالک: شناسه کاربر خود را در `channels.telegram.allowFrom` تنظیم کنید، `groupAllowFrom` را تنظیم‌نشده بگذارید، و گروه‌های هدف را زیر `channels.telegram.groups` مجاز کنید.
نکته runtime: اگر `channels.telegram` کاملاً وجود نداشته باشد، runtime به‌صورت پیش‌فرض fail-closed با `groupPolicy="allowlist"` کار می‌کند، مگر اینکه `channels.defaults.groupPolicy` صریحاً تنظیم شده باشد.
نکته زمان اجرا: اگر `channels.telegram` کاملاً وجود نداشته باشد، پیش‌فرض زمان اجرا fail-closed با `groupPolicy="allowlist"` است مگر اینکه `channels.defaults.groupPolicy` صراحتاً تنظیم شده باشد.
مثال: اجازه دادن به هر عضو در یک گروه مشخص:
مثال: مجاز کردن هر عضو در یک گروه مشخص:
```json5
{
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
مثال: اجازه دادن فقط به کاربران مشخص داخل یک گروه مشخص:
مثال: مجاز کردن فقط کاربران مشخص در یک گروه مشخص:
```json5
{
@ -211,32 +211,32 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
```
<Warning>
اشتباه رایج: `groupAllowFrom` یک allowlist گروه Telegram نیست.
اشتباه رایج: `groupAllowFrom`، allowlist گروه Telegram نیست.
- شناسه‌های منفی chat گروه یا supergroup در Telegram مانند `-1001234567890` را زیر `channels.telegram.groups` قرار دهید.
- وقتی می‌خواهید محدود کنید کدام افراد داخل یک گروه مجاز بتوانند ربات را فعال کنند، شناسه‌های کاربر Telegram مانند `8734062810` را زیر `groupAllowFrom` قرار دهید.
- فقط وقتی از `groupAllowFrom: ["*"]` استفاده کنید که می‌خواهید هر عضو یک گروه مجاز بتواند با ربات صحبت کند.
- شناسه‌های منفی گفتگوی گروه یا ابرگروه Telegram مانند `-1001234567890` را زیر `channels.telegram.groups` قرار دهید.
- وقتی می‌خواهید محدود کنید چه کسانی داخل یک گروه مجاز بتوانند ربات را فعال کنند، شناسه‌های کاربر Telegram مانند `8734062810` را زیر `groupAllowFrom` قرار دهید.
- فقط زمانی از `groupAllowFrom: ["*"]` استفاده کنید که می‌خواهید هر عضو یک گروه مجاز بتواند با ربات صحبت کند.
</Warning>
</Tab>
<Tab title="رفتار mention">
پاسخ‌های گروه به‌طور پیش‌فرض به mention نیاز دارند.
<Tab title="رفتار منشن">
پاسخ‌های گروهی به‌صورت پیش‌فرض به منشن نیاز دارند.
mention می‌تواند از این‌ها بیاید:
منشن می‌تواند از این موارد بیاید:
- mention بومی `@botusername`، یا
- الگوهای mention در:
- منشن بومی `@botusername`، یا
- الگوهای منشن در:
- `agents.list[].groupChat.mentionPatterns`
- `messages.groupChat.mentionPatterns`
toggleهای فرمان در سطح session:
کلیدهای فرمان در سطح نشست:
- `/activation always`
- `/activation mention`
این‌ها فقط وضعیت session را به‌روزرسانی می‌کنند. برای پایداری از config استفاده کنید.
این‌ها فقط وضعیت نشست را به‌روزرسانی می‌کنند. برای پایداری از config استفاده کنید.
مثال config پایدار:
@ -252,44 +252,45 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
گرفتن شناسه chat گروه:
دریافت شناسه گفتگوی گروه:
- یک پیام گروه را به `@userinfobot` / `@getidsbot` forward کنید
- یک پیام گروهی را به `@userinfobot` / `@getidsbot` فوروارد کنید
- یا `chat.id` را از `openclaw logs --follow` بخوانید
- یا Bot API `getUpdates` را بررسی کنید
</Tab>
</Tabs>
## رفتار runtime
## رفتار زمان اجرا
- Telegram تحت مالکیت فرایند gateway است.
- Telegram در مالکیت فرایند gateway است.
- مسیریابی قطعی است: ورودی Telegram به Telegram پاسخ داده می‌شود (مدل کانال‌ها را انتخاب نمی‌کند).
- پیام‌های ورودی به envelope کانال مشترک با metadata پاسخ و placeholderهای رسانه نرمال‌سازی می‌شوند.
- sessionهای گروه بر اساس شناسه گروه ایزوله می‌شوند. topicهای forum، `:topic:<threadId>` را اضافه می‌کنند تا topicها ایزوله بمانند.
- پیام‌های DM می‌توانند `message_thread_id` داشته باشند؛ OpenClaw شناسه thread را برای پاسخ‌ها حفظ می‌کند اما به‌طور پیش‌فرض DMها را روی session تخت نگه می‌دارد. وقتی عمداً ایزوله‌سازی session topic در DM را می‌خواهید، `channels.telegram.dm.threadReplies: "inbound"`، `channels.telegram.direct.<chatId>.threadReplies: "inbound"`، `requireTopic: true`، یا یک config topic منطبق را پیکربندی کنید.
- Long polling از runner در grammY با توالی‌دهی per-chat/per-thread استفاده می‌کند. هم‌روندی کلی runner sink از `agents.defaults.maxConcurrent` استفاده می‌کند.
- Long polling داخل هر فرایند gateway محافظت می‌شود تا در هر زمان فقط یک poller فعال بتواند از یک توکن ربات استفاده کند. اگر همچنان conflictهای `getUpdates` 409 می‌بینید، احتمالاً یک gateway دیگر OpenClaw، یک script، یا یک poller خارجی از همان توکن استفاده می‌کند.
- راه‌اندازی‌های مجدد watchdog برای long-polling به‌طور پیش‌فرض پس از ۱۲۰ ثانیه بدون liveness کامل‌شده `getUpdates` فعال می‌شوند. فقط اگر deployment شما همچنان هنگام کارهای طولانی‌مدت راه‌اندازی مجدد کاذب polling-stall می‌بیند، `channels.telegram.pollingStallThresholdMs` را افزایش دهید. مقدار بر حسب میلی‌ثانیه است و از `30000` تا `600000` مجاز است؛ overrideهای per-account پشتیبانی می‌شوند.
- پیام‌های ورودی به پوشش مشترک کانال با فراداده پاسخ و جای‌نگهدارهای رسانه نرمال‌سازی می‌شوند.
- نشست‌های گروهی بر اساس شناسه گروه ایزوله می‌شوند. موضوع‌های فروم `:topic:<threadId>` را اضافه می‌کنند تا موضوع‌ها ایزوله بمانند.
- پیام‌های DM می‌توانند `message_thread_id` داشته باشند؛ OpenClaw شناسه رشته را برای پاسخ‌ها حفظ می‌کند اما به‌صورت پیش‌فرض DMها را روی نشست تخت نگه می‌دارد. وقتی عمداً ایزوله‌سازی نشست موضوع DM را می‌خواهید، `channels.telegram.dm.threadReplies: "inbound"`، `channels.telegram.direct.<chatId>.threadReplies: "inbound"`، `requireTopic: true`، یا یک config موضوع مطابق را پیکربندی کنید.
- long polling از grammY runner با ترتیب‌دهی به‌ازای هر گفتگو/هر رشته استفاده می‌کند. همزمانی کلی runner sink از `agents.defaults.maxConcurrent` استفاده می‌کند.
- long polling داخل هر فرایند gateway محافظت می‌شود تا در هر زمان فقط یک poller فعال بتواند از توکن ربات استفاده کند. اگر همچنان تداخل‌های `getUpdates` 409 می‌بینید، احتمالاً یک gateway دیگر OpenClaw، اسکریپت، یا poller خارجی از همان توکن استفاده می‌کند.
- شروع‌های مجدد نگهبان long-polling به‌صورت پیش‌فرض پس از ۱۲۰ ثانیه بدون liveness تکمیل‌شده `getUpdates` فعال می‌شوند. فقط اگر استقرار شما همچنان هنگام کارهای طولانی‌مدت شروع مجددهای کاذب polling-stall می‌بیند، `channels.telegram.pollingStallThresholdMs` را افزایش دهید. مقدار بر حسب میلی‌ثانیه است و از `30000` تا `600000` مجاز است؛ overrideهای به‌ازای حساب پشتیبانی می‌شوند.
- Telegram Bot API از رسید خواندن پشتیبانی نمی‌کند (`sendReadReceipts` اعمال نمی‌شود).
## مرجع قابلیت‌ها
<AccordionGroup>
<Accordion title="پیش‌نمایش live stream (ویرایش پیام‌ها)">
OpenClaw می‌تواند پاسخ‌های جزئی را به‌صورت real time stream کند:
<Accordion title="پیش‌نمایش پخش زنده (ویرایش پیام)">
OpenClaw می‌تواند پاسخ‌های جزئی را به‌صورت بلادرنگ stream کند:
- chatهای مستقیم: پیام پیش‌نمایش + `editMessageText`
- گروه‌ها/topicها: پیام پیش‌نمایش + `editMessageText`
- گفتگوهای مستقیم: پیام پیش‌نمایش + `editMessageText`
- گروه‌ها/موضوع‌ها: پیام پیش‌نمایش + `editMessageText`
نیازمندی:
- `channels.telegram.streaming` برابر `off | partial | block | progress` است (پیش‌فرض: `partial`)
- `progress` یک پیش‌نویس وضعیت قابل‌ویرایش نگه می‌دارد و تا تحویل نهایی، آن را با پیشرفت ابزار به‌روزرسانی می‌کند
- `streaming.preview.toolProgress` کنترل می‌کند آیا به‌روزرسانی‌های ابزار/پیشرفت از همان پیام پیش‌نمایش ویرایش‌شده دوباره استفاده کنند یا نه (پیش‌فرض: `true` وقتی preview streaming فعال است)
- مقادیر legacy `channels.telegram.streamMode` و boolean `streaming` شناسایی می‌شوند؛ برای مهاجرت آن‌ها به `channels.telegram.streaming.mode` دستور `openclaw doctor --fix` را اجرا کنید
- `progress` یک پیش‌نویس وضعیت قابل‌ویرایش را نگه می‌دارد و تا تحویل نهایی آن را با پیشرفت ابزار به‌روزرسانی می‌کند
- `streaming.preview.toolProgress` کنترل می‌کند که آیا به‌روزرسانی‌های ابزار/پیشرفت از همان پیام پیش‌نمایش ویرایش‌شده دوباره استفاده کنند یا نه (پیش‌فرض: وقتی stream کردن پیش‌نمایش فعال است `true`)
- `streaming.preview.commandText` جزئیات command/exec داخل آن خطوط tool-progress را کنترل می‌کند: `raw` (پیش‌فرض، رفتار منتشرشده را حفظ می‌کند) یا `status` (فقط برچسب ابزار)
- مقدارهای قدیمی `channels.telegram.streamMode` و بولی `streaming` شناسایی می‌شوند؛ برای مهاجرت آن‌ها به `channels.telegram.streaming.mode`، `openclaw doctor --fix` را اجرا کنید
به‌روزرسانی‌های پیش‌نمایش tool-progress همان خطوط کوتاه وضعیت هستند که هنگام اجرای ابزارها نشان داده می‌شوند، برای مثال اجرای فرمان، خواندن فایل، به‌روزرسانی‌های برنامه‌ریزی، یا خلاصه‌های patch. Telegram این‌ها را به‌طور پیش‌فرض فعال نگه می‌دارد تا با رفتار منتشرشده OpenClaw از `v2026.4.22` و نسخه‌های بعدی منطبق باشد. برای نگه داشتن پیش‌نمایش ویرایش‌شده برای متن پاسخ اما پنهان کردن خطوط tool-progress، تنظیم کنید:
به‌روزرسانی‌های پیش‌نمایش tool-progress خطوط کوتاه وضعیتی هستند که هنگام اجرای ابزارها نشان داده می‌شوند، برای مثال اجرای فرمان، خواندن فایل‌ها، به‌روزرسانی‌های برنامه‌ریزی، یا خلاصه‌های patch. Telegram این‌ها را به‌صورت پیش‌فرض فعال نگه می‌دارد تا با رفتار منتشرشده OpenClaw از `v2026.4.22` و بعد از آن هم‌خوان باشد. برای نگه داشتن پیش‌نمایش ویرایش‌شده برای متن پاسخ اما پنهان کردن خطوط tool-progress، تنظیم کنید:
```json
{
@ -306,25 +307,61 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
از `streaming.mode: "off"` فقط زمانی استفاده کنید که تحویل فقط-نهایی می‌خواهید: ویرایش‌های پیش‌نمایش Telegram غیرفعال می‌شوند و گفت‌وگوی عمومی ابزار/پیشرفت به‌جای ارسال به‌عنوان پیام‌های وضعیت مستقل، سرکوب می‌شود. اعلان‌های تأیید، محموله‌های رسانه‌ای و خطاها همچنان از مسیر تحویل نهایی عادی عبور می‌کنند. وقتی فقط می‌خواهید ویرایش‌های پیش‌نمایش پاسخ را نگه دارید و خطوط وضعیت پیشرفت ابزار را پنهان کنید، از `streaming.preview.toolProgress: false` استفاده کنید.
برای اینکه tool-progress قابل مشاهده بماند اما متن command/exec پنهان شود، تنظیم کنید:
```json
{
"channels": {
"telegram": {
"streaming": {
"mode": "partial",
"preview": {
"commandText": "status"
}
}
}
}
}
```
برای حالت پیش‌نویس پیشرفت، همان سیاست متن فرمان را زیر `streaming.progress` قرار دهید:
```json
{
"channels": {
"telegram": {
"streaming": {
"mode": "progress",
"progress": {
"toolProgress": true,
"commandText": "status"
}
}
}
}
}
```
از `streaming.mode: "off"` فقط زمانی استفاده کنید که تحویل فقط نهایی می‌خواهید: ویرایش‌های پیش‌نمایش Telegram غیرفعال می‌شوند و گفت‌وگوی عمومی ابزار/پیشرفت به‌جای ارسال به‌صورت پیام‌های وضعیت مستقل، سرکوب می‌شود. اعلان‌های تأیید، بارهای رسانه‌ای، و خطاها همچنان از مسیر تحویل نهایی معمول عبور می‌کنند. وقتی فقط می‌خواهید ویرایش‌های پیش‌نمایش پاسخ را نگه دارید و خط‌های وضعیت پیشرفت ابزار را پنهان کنید، از `streaming.preview.toolProgress: false` استفاده کنید.
<Note>
پاسخ‌های نقل‌قول انتخاب‌شده Telegram استثنا هستند. وقتی `replyToMode` برابر `"first"`، `"all"` یا `"batched"` باشد و پیام ورودی شامل متن نقل‌قول انتخاب‌شده باشد، OpenClaw پاسخ نهایی را به‌جای ویرایش پیش‌نمایش پاسخ، از مسیر بومی پاسخِ نقل‌قولی Telegram ارسال می‌کند؛ بنابراین `streaming.preview.toolProgress` نمی‌تواند خطوط کوتاه وضعیت را برای آن نوبت نشان دهد. پاسخ‌های پیام فعلی بدون متن نقل‌قول انتخاب‌شده همچنان جریان پیش‌نمایش را نگه می‌دارند. وقتی نمایش پیشرفت ابزار از پاسخ‌های نقل‌قولی بومی مهم‌تر است، `replyToMode: "off"` را تنظیم کنید، یا برای پذیرفتن این بده‌بستان `streaming.preview.toolProgress: false` را تنظیم کنید.
پاسخ‌های نقل‌قولی انتخاب‌شده در Telegram استثنا هستند. وقتی `replyToMode` برابر `"first"`، `"all"`، یا `"batched"` باشد و پیام ورودی شامل متن نقل‌قول انتخاب‌شده باشد، OpenClaw پاسخ نهایی را به‌جای ویرایش پیش‌نمایش پاسخ، از مسیر بومی پاسخ نقل‌قولی Telegram ارسال می‌کند؛ بنابراین `streaming.preview.toolProgress` نمی‌تواند خط‌های کوتاه وضعیت را برای آن نوبت نشان دهد. پاسخ‌ها به پیام فعلی بدون متن نقل‌قول انتخاب‌شده همچنان پخش پیش‌نمایش را نگه می‌دارند. وقتی دیده‌شدن پیشرفت ابزار از پاسخ‌های نقل‌قولی بومی مهم‌تر است، `replyToMode: "off"` را تنظیم کنید، یا برای پذیرش این بده‌بستان `streaming.preview.toolProgress: false` را تنظیم کنید.
</Note>
برای پاسخ‌های فقط متنی:
- پیش‌نمایش‌های کوتاه DM/گروه/موضوع: OpenClaw همان پیام پیش‌نمایش را نگه می‌دارد و یک ویرایش نهایی را در همان‌جا انجام می‌دهد، مگر اینکه پس از ظاهر شدن پیش‌نمایش، یک پیام غیرپیش‌نمایش قابل‌مشاهده ارسال شده باشد
- پیش‌نمایش‌هایی که خروجی غیرپیش‌نمایش قابل‌مشاهده پس از آن‌ها می‌آید: OpenClaw پاسخ کامل‌شده را به‌عنوان یک پیام نهایی تازه ارسال می‌کند و پیش‌نمایش قدیمی‌تر را پاک می‌کند، بنابراین پاسخ نهایی پس از خروجی میانی ظاهر می‌شود
- پیش‌نمایش‌های قدیمی‌تر از حدود یک دقیقه: OpenClaw پاسخ کامل‌شده را به‌عنوان یک پیام نهایی تازه ارسال می‌کند و سپس پیش‌نمایش را پاک می‌کند، بنابراین زمان‌نمای قابل‌مشاهده Telegram زمان تکمیل را به‌جای زمان ایجاد پیش‌نمایش نشان می‌دهد
- پیش‌نمایش‌های کوتاه DM/گروه/موضوع: OpenClaw همان پیام پیش‌نمایش را نگه می‌دارد و یک ویرایش نهایی را درجا انجام می‌دهد، مگر اینکه پس از ظاهر شدن پیش‌نمایش یک پیام غیرپیش‌نمایش قابل مشاهده ارسال شده باشد
- پیش‌نمایش‌هایی که خروجی غیرپیش‌نمایش قابل مشاهده پس از آنها می‌آید: OpenClaw پاسخ کامل‌شده را به‌صورت یک پیام نهایی تازه ارسال می‌کند و پیش‌نمایش قدیمی‌تر را پاک می‌کند، بنابراین پاسخ نهایی پس از خروجی میانی ظاهر می‌شود
- پیش‌نمایش‌های قدیمی‌تر از حدود یک دقیقه: OpenClaw پاسخ کامل‌شده را به‌صورت یک پیام نهایی تازه ارسال می‌کند و سپس پیش‌نمایش را پاک می‌کند، بنابراین مهر زمانی قابل مشاهده Telegram به‌جای زمان ایجاد پیش‌نمایش، زمان تکمیل را نشان می‌دهد
برای پاسخ‌های پیچیده (برای مثال محموله‌های رسانه‌ای)، OpenClaw به تحویل نهایی عادی بازمی‌گردد و سپس پیام پیش‌نمایش را پاک می‌کند.
برای پاسخ‌های پیچیده (برای مثال بارهای رسانه‌ای)، OpenClaw به تحویل نهایی معمول برمی‌گردد و سپس پیام پیش‌نمایش را پاک می‌کند.
جریان پیش‌نمایش از جریان بلوکی جدا است. وقتی جریان بلوکی به‌طور صریح برای Telegram فعال شده باشد، OpenClaw برای جلوگیری از جریان‌دهی دوگانه، جریان پیش‌نمایش را رد می‌کند.
پخش پیش‌نمایش از پخش بلوک جداست. وقتی پخش بلوک به‌صراحت برای Telegram فعال باشد، OpenClaw برای جلوگیری از پخش دوگانه، پخش پیش‌نمایش را نادیده می‌گیرد.
جریان استدلال فقط برای Telegram:
جریان استدلال فقط مخصوص Telegram:
- `/reasoning stream` هنگام تولید، استدلال را به پیش‌نمایش زنده ارسال می‌کند
- `/reasoning stream` هنگام تولید، استدلال را به پیش‌نمایش زنده می‌فرستد
- پیش‌نمایش استدلال پس از تحویل نهایی حذف می‌شود؛ وقتی استدلال باید قابل مشاهده باقی بماند از `/reasoning on` استفاده کنید
- پاسخ نهایی بدون متن استدلال ارسال می‌شود
</Accordion>
@ -332,11 +369,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
<Accordion title="قالب‌بندی و جایگزین HTML">
متن خروجی از Telegram `parse_mode: "HTML"` استفاده می‌کند.
- متن شبیه Markdown به HTML امن برای Telegram رندر می‌شود.
- HTML خام مدل escape می‌شود تا شکست‌های parse در Telegram کاهش یابد.
- اگر Telegram HTML تجزیه‌شده را رد کند، OpenClaw دوباره به‌صورت متن ساده تلاش می‌کند.
- متن شبیه Markdown به HTML ایمن برای Telegram رندر می‌شود.
- HTML خام مدل برای کاهش شکست‌های پردازش Telegram escape می‌شود.
- اگر Telegram HTML پردازش‌شده را رد کند، OpenClaw به‌صورت متن ساده دوباره تلاش می‌کند.
پیش‌نمایش‌های لینک به‌طور پیش‌فرض فعال هستند و می‌توان آن‌ها را با `channels.telegram.linkPreview: false` غیرفعال کرد.
پیش‌نمایش‌های لینک به‌طور پیش‌فرض فعال هستند و می‌توان آنها را با `channels.telegram.linkPreview: false` غیرفعال کرد.
</Accordion>
@ -367,25 +404,25 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- نام‌ها نرمال‌سازی می‌شوند (`/` ابتدایی حذف می‌شود، حروف کوچک می‌شوند)
- الگوی معتبر: `a-z`، `0-9`، `_`، طول `1..32`
- فرمان‌های سفارشی نمی‌توانند فرمان‌های بومی را بازنویسی کنند
- تداخل‌ها/تکراری‌ها رد می‌شوند و لاگ می‌شوند
- تعارض‌ها/تکراری‌ها نادیده گرفته و ثبت می‌شوند
نکته‌ها:
نکات:
- فرمان‌های سفارشی فقط ورودی‌های منو هستند؛ آن‌ها رفتار را به‌صورت خودکار پیاده‌سازی نمی‌کنند
- فرمان‌های Plugin/skill حتی اگر در منوی Telegram نمایش داده نشوند، همچنان هنگام تایپ می‌توانند کار کنند
- فرمان‌های سفارشی فقط ورودی‌های منو هستند؛ رفتار را به‌طور خودکار پیاده‌سازی نمی‌کنند
- فرمان‌های plugin/skill حتی اگر در منوی Telegram نمایش داده نشوند، همچنان می‌توانند هنگام تایپ کار کنند
اگر فرمان‌های بومی غیرفعال باشند، موارد داخلی حذف می‌شوند. فرمان‌های سفارشی/Plugin در صورت پیکربندی همچنان ممکن است ثبت شوند.
اگر فرمان‌های بومی غیرفعال باشند، داخلی‌ها حذف می‌شوند. فرمان‌های سفارشی/plugin در صورت پیکربندی همچنان ممکن است ثبت شوند.
شکست‌های رایج راه‌اندازی:
خطاهای رایج راه‌اندازی:
- `setMyCommands failed` همراه با `BOT_COMMANDS_TOO_MUCH` یعنی منوی Telegram حتی پس از کوتاه‌سازی هم سرریز شده است؛ فرمان‌های Plugin/skill/سفارشی را کاهش دهید یا `channels.telegram.commands.native` را غیرفعال کنید.
- شکست `deleteWebhook`، `deleteMyCommands` یا `setMyCommands` با `404: Not Found` در حالی که فرمان‌های مستقیم curl برای Bot API کار می‌کنند، می‌تواند یعنی `channels.telegram.apiRoot` روی endpoint کامل `/bot<TOKEN>` تنظیم شده است. `apiRoot` باید فقط ریشه Bot API باشد، و `openclaw doctor --fix` یک `/bot<TOKEN>` انتهایی تصادفی را حذف می‌کند.
- `getMe returned 401` یعنی Telegram توکن بات پیکربندی‌شده را رد کرده است. `botToken`، `tokenFile` یا `TELEGRAM_BOT_TOKEN` را با توکن فعلی BotFather به‌روزرسانی کنید؛ OpenClaw پیش از polling متوقف می‌شود، بنابراین این مورد به‌عنوان شکست پاک‌سازی Webhook گزارش نمی‌شود.
- `setMyCommands failed` همراه با `BOT_COMMANDS_TOO_MUCH` یعنی منوی Telegram پس از کوتاه‌سازی همچنان سرریز شده است؛ فرمان‌های plugin/skill/سفارشی را کاهش دهید یا `channels.telegram.commands.native` را غیرفعال کنید.
- شکست `deleteWebhook`، `deleteMyCommands`، یا `setMyCommands` با `404: Not Found` در حالی که فرمان‌های مستقیم curl مربوط به Bot API کار می‌کنند می‌تواند به این معنا باشد که `channels.telegram.apiRoot` روی endpoint کامل `/bot<TOKEN>` تنظیم شده است. `apiRoot` باید فقط ریشه Bot API باشد، و `openclaw doctor --fix` یک `/bot<TOKEN>` انتهایی تصادفی را حذف می‌کند.
- `getMe returned 401` یعنی Telegram توکن بات پیکربندی‌شده را رد کرده است. `botToken`، `tokenFile`، یا `TELEGRAM_BOT_TOKEN` را با توکن فعلی BotFather به‌روزرسانی کنید؛ OpenClaw پیش از polling متوقف می‌شود، بنابراین این مورد به‌عنوان شکست پاک‌سازی webhook گزارش نمی‌شود.
- `setMyCommands failed` همراه با خطاهای network/fetch معمولاً یعنی DNS/HTTPS خروجی به `api.telegram.org` مسدود شده است.
### فرمان‌های جفت‌سازی دستگاه (Plugin `device-pair`)
### فرمان‌های جفت‌سازی دستگاه (plugin `device-pair`)
وقتی Plugin `device-pair` نصب شده باشد:
وقتی plugin `device-pair` نصب شده باشد:
1. `/pair` کد راه‌اندازی تولید می‌کند
2. کد را در برنامه iOS جای‌گذاری کنید
@ -393,11 +430,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
4. درخواست را تأیید کنید:
- `/pair approve <requestId>` برای تأیید صریح
- `/pair approve` وقتی فقط یک درخواست در انتظار وجود دارد
- `/pair approve latest` برای تازه‌ترین مورد
- `/pair approve latest` برای جدیدترین مورد
کد راه‌اندازی یک توکن bootstrap کوتاه‌عمر را حمل می‌کند. handoff داخلی bootstrap توکن node اصلی را در `scopes: []` نگه می‌دارد؛ هر توکن operator واگذار‌شده به `operator.approvals`، `operator.read`، `operator.talk.secrets` و `operator.write` محدود می‌ماند. بررسی‌های دامنه bootstrap با پیشوند نقش هستند، بنابراین آن allowlist مربوط به operator فقط درخواست‌های operator را برآورده می‌کند؛ نقش‌های غیر-operator همچنان به دامنه‌هایی زیر پیشوند نقش خودشان نیاز دارند.
کد راه‌اندازی یک توکن bootstrap کوتاه‌عمر را حمل می‌کند. واگذاری bootstrap داخلی توکن نود اصلی را در `scopes: []` نگه می‌دارد؛ هر توکن عملگر واگذارشده در محدوده‌های `operator.approvals`، `operator.read`، `operator.talk.secrets`، و `operator.write` محدود می‌ماند. بررسی‌های دامنه bootstrap با پیشوند نقش انجام می‌شوند، بنابراین آن allowlist عملگر فقط درخواست‌های عملگر را برآورده می‌کند؛ نقش‌های غیرعملگر همچنان به دامنه‌هایی زیر پیشوند نقش خودشان نیاز دارند.
اگر دستگاهی با جزئیات احراز هویت تغییر‌یافته دوباره تلاش کند (برای مثال نقش/دامنه‌ها/کلید عمومی)، درخواست در انتظار قبلی جایگزین می‌شود و درخواست جدید از `requestId` متفاوتی استفاده می‌کند. پیش از تأیید، `/pair pending` را دوباره اجرا کنید.
اگر دستگاهی با جزئیات احراز هویت تغییرکرده دوباره تلاش کند (برای مثال نقش/دامنه‌ها/کلید عمومی)، درخواست در انتظار قبلی جایگزین می‌شود و درخواست جدید از `requestId` متفاوتی استفاده می‌کند. پیش از تأیید دوباره `/pair pending` را اجرا کنید.
جزئیات بیشتر: [جفت‌سازی](/fa/channels/pairing#pair-via-telegram-recommended-for-ios).
@ -446,7 +483,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
`capabilities: ["inlineButtons"]` قدیمی به `inlineButtons: "all"` نگاشت می‌شود.
نمونه اقدام پیام:
نمونه کنش پیام:
```json5
{
@ -464,23 +501,23 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
کلیک‌های callback به‌صورت متن به agent پاس داده می‌شوند:
کلیک‌های callback به‌صورت متن به عامل منتقل می‌شوند:
`callback_data: <value>`
</Accordion>
<Accordion title="اقدام‌های پیام Telegram برای agentها و اتوماسیون">
اقدام‌های ابزار Telegram شامل این موارد است:
<Accordion title="کنش‌های پیام Telegram برای عامل‌ها و خودکارسازی">
کنش‌های ابزار Telegram شامل این موارد هستند:
- `sendMessage` (`to`, `content`, اختیاری `mediaUrl`, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`)
- `deleteMessage` (`chatId`, `messageId`)
- `editMessage` (`chatId`, `messageId`, `content`)
- `createForumTopic` (`chatId`, `name`, اختیاری `iconColor`, `iconCustomEmojiId`)
- `sendMessage` (`to`، `content`، اختیاری `mediaUrl`، `replyToMessageId`، `messageThreadId`)
- `react` (`chatId`، `messageId`، `emoji`)
- `deleteMessage` (`chatId`، `messageId`)
- `editMessage` (`chatId`، `messageId`، `content`)
- `createForumTopic` (`chatId`، `name`، اختیاری `iconColor`، `iconCustomEmojiId`)
اقدام‌های پیام channel نام‌های مستعار خوش‌دست را ارائه می‌کنند (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
کنش‌های پیام کانال aliasهای ارگونومیک را ارائه می‌کنند (`send`، `react`، `delete`، `edit`، `sticker`، `sticker-search`، `topic-create`).
کنترل‌های gating:
کنترل‌های محدودسازی:
- `channels.telegram.actions.sendMessage`
- `channels.telegram.actions.deleteMessage`
@ -488,16 +525,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `channels.telegram.actions.sticker` (پیش‌فرض: غیرفعال)
نکته: `edit` و `topic-create` در حال حاضر به‌طور پیش‌فرض فعال هستند و toggleهای جداگانه `channels.telegram.actions.*` ندارند.
ارسال‌های runtime از snapshot فعال پیکربندی/secretها (راه‌اندازی/بارگذاری مجدد) استفاده می‌کنند، بنابراین مسیرهای اقدام برای هر ارسال، SecretRef را به‌صورت ad-hoc دوباره resolve نمی‌کنند.
ارسال‌های زمان اجرا از snapshot پیکربندی/رازهای فعال (راه‌اندازی/بارگذاری مجدد) استفاده می‌کنند، بنابراین مسیرهای کنش برای هر ارسال بازحل ad-hoc مربوط به SecretRef انجام نمی‌دهند.
معنای حذف واکنش: [/tools/reactions](/fa/tools/reactions)
معناشناسی حذف واکنش: [/tools/reactions](/fa/tools/reactions)
</Accordion>
<Accordion title="تگ‌های رشته‌بندی پاسخ">
Telegram از تگ‌های صریح رشته‌بندی پاسخ در خروجی تولیدشده پشتیبانی می‌کند:
<Accordion title="برچسب‌های رشته‌بندی پاسخ">
Telegram از برچسب‌های رشته‌بندی پاسخ صریح در خروجی تولیدشده پشتیبانی می‌کند:
- `[[reply_to_current]]` به پیام تحریک‌کننده پاسخ می‌دهد
- `[[reply_to_current]]` به پیام محرک پاسخ می‌دهد
- `[[reply_to:<id>]]` به یک شناسه پیام مشخص Telegram پاسخ می‌دهد
`channels.telegram.replyToMode` مدیریت را کنترل می‌کند:
@ -506,29 +543,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `first`
- `all`
وقتی رشته‌بندی پاسخ فعال باشد و متن یا caption اصلی Telegram در دسترس باشد، OpenClaw به‌طور خودکار یک گزیده نقل‌قول بومی Telegram را شامل می‌کند. Telegram متن نقل‌قول بومی را به 1024 واحد کد UTF-16 محدود می‌کند، بنابراین پیام‌های طولانی‌تر از ابتدا نقل می‌شوند و اگر Telegram نقل‌قول را رد کند، به پاسخ ساده fallback می‌کنند.
وقتی رشته‌بندی پاسخ فعال باشد و متن یا کپشن اصلی Telegram در دسترس باشد، OpenClaw به‌طور خودکار یک گزیده نقل‌قول بومی Telegram را شامل می‌کند. Telegram متن نقل‌قول بومی را به ۱۰۲۴ واحد کد UTF-16 محدود می‌کند، بنابراین پیام‌های طولانی‌تر از ابتدا نقل‌قول می‌شوند و اگر Telegram نقل‌قول را رد کند به یک پاسخ ساده برمی‌گردند.
نکته: `off` رشته‌بندی ضمنی پاسخ را غیرفعال می‌کند. تگ‌های صریح `[[reply_to_*]]` همچنان رعایت می‌شوند.
نکته: `off` رشته‌بندی پاسخ ضمنی را غیرفعال می‌کند. برچسب‌های صریح `[[reply_to_*]]` همچنان رعایت می‌شوند.
</Accordion>
<Accordion title="موضوعات Forum و رفتار thread">
ابرگروه‌های Forum:
<Accordion title="موضوعات انجمن و رفتار رشته">
ابرگروه‌های انجمن:
- کلیدهای session موضوع `:topic:<threadId>` را اضافه می‌کنند
- پاسخ‌ها و typing موضوع thread را هدف می‌گیرند
- کلیدهای جلسه موضوع `:topic:<threadId>` را اضافه می‌کنند
- پاسخ‌ها و typing موضوع رشته را هدف می‌گیرند
- مسیر پیکربندی موضوع:
`channels.telegram.groups.<chatId>.topics.<threadId>`
حالت ویژه موضوع عمومی (`threadId=1`):
- ارسال پیام‌ها `message_thread_id` را حذف می‌کند (Telegram `sendMessage(...thread_id=1)` را رد می‌کند)
- اقدام‌های typing همچنان `message_thread_id` را شامل می‌شوند
- ارسال‌های پیام `message_thread_id` را حذف می‌کنند (Telegram، `sendMessage(...thread_id=1)` را رد می‌کند)
- کنش‌های typing همچنان `message_thread_id` را شامل می‌شوند
ارث‌بری موضوع: ورودی‌های موضوع تنظیمات گروه را ارث می‌برند مگر اینکه بازنویسی شده باشند (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
وراثت موضوع: ورودی‌های موضوع تنظیمات گروه را به ارث می‌برند مگر اینکه بازنویسی شوند (`requireMention`، `allowFrom`، `skills`، `systemPrompt`، `enabled`، `groupPolicy`).
`agentId` فقط مخصوص موضوع است و از پیش‌فرض‌های گروه ارث نمی‌برد.
**مسیریابی agent برای هر موضوع**: هر موضوع می‌تواند با تنظیم `agentId` در پیکربندی موضوع، به agent متفاوتی مسیر داده شود. این کار به هر موضوع workspace، memory و session ایزوله خودش را می‌دهد. مثال:
**مسیریابی عامل برای هر موضوع**: هر موضوع می‌تواند با تنظیم `agentId` در پیکربندی موضوع، به عامل متفاوتی مسیریابی شود. این به هر موضوع workspace، حافظه، و جلسه جداگانه خودش را می‌دهد. مثال:
```json5
{
@ -548,26 +585,26 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
سپس هر موضوع کلید session خودش را دارد: `agent:zu:telegram:group:-1001234567890:topic:3`
سپس هر موضوع کلید جلسه خودش را دارد: `agent:zu:telegram:group:-1001234567890:topic:3`
**اتصال پایدار موضوع ACP**: موضوعات Forum می‌توانند sessionهای harness مربوط به ACP را از طریق bindingهای تایپ‌شده ACP در سطح بالا pin کنند (`bindings[]` با `type: "acp"` و `match.channel: "telegram"`، `peer.kind: "group"`، و یک شناسه واجد موضوع مثل `-1001234567890:topic:42`). در حال حاضر به موضوعات Forum در گروه‌ها/ابرگروه‌ها محدود است. [Agentهای ACP](/fa/tools/acp-agents) را ببینید.
**اتصال پایدار موضوع ACP**: موضوعات انجمن می‌توانند جلسه‌های harness مربوط به ACP را از طریق اتصال‌های ACP تایپ‌شده سطح بالا pin کنند (`bindings[]` با `type: "acp"` و `match.channel: "telegram"`، `peer.kind: "group"`، و یک شناسه دارای topic qualifier مانند `-1001234567890:topic:42`). در حال حاضر به موضوعات انجمن در گروه‌ها/ابرگروه‌ها محدود است. [عامل‌های ACP](/fa/tools/acp-agents) را ببینید.
**spawn وابسته به thread برای ACP از chat**: `/acp spawn <agent> --thread here|auto` موضوع فعلی را به یک session جدید ACP متصل می‌کند؛ پیگیری‌ها مستقیماً به همان‌جا مسیر داده می‌شوند. OpenClaw تأیید spawn را درون موضوع pin می‌کند. نیاز دارد `channels.telegram.threadBindings.spawnSessions` فعال بماند (پیش‌فرض: `true`).
**spawn کردن ACP وابسته به رشته از chat**: `/acp spawn <agent> --thread here|auto` موضوع فعلی را به یک جلسه ACP جدید متصل می‌کند؛ پیگیری‌ها مستقیم به آنجا مسیریابی می‌شوند. OpenClaw تأیید spawn را داخل موضوع pin می‌کند. نیاز دارد `channels.telegram.threadBindings.spawnSessions` فعال بماند (پیش‌فرض: `true`).
زمینه template، `MessageThreadId` و `IsForum` را ارائه می‌کند. chatهای DM با `message_thread_id` به‌طور پیش‌فرض مسیریابی DM و metadata پاسخ را روی sessionهای تخت نگه می‌دارند؛ آن‌ها فقط زمانی از کلیدهای session آگاه از thread استفاده می‌کنند که با `threadReplies: "inbound"`، `threadReplies: "always"`، `requireTopic: true` یا یک پیکربندی موضوع مطابق پیکربندی شده باشند. برای پیش‌فرض حساب از `channels.telegram.dm.threadReplies` در سطح بالا، یا برای یک DM از `direct.<chatId>.threadReplies` استفاده کنید.
زمینهٔ الگو `MessageThreadId` و `IsForum` را در دسترس می‌گذارد. چت‌های DM با `message_thread_id` به‌طور پیش‌فرض مسیریابی DM و فرادادهٔ پاسخ را در نشست‌های تخت نگه می‌دارند؛ آن‌ها فقط وقتی از کلیدهای نشست آگاه از رشته استفاده می‌کنند که با `threadReplies: "inbound"`، `threadReplies: "always"`، `requireTopic: true`، یا یک پیکربندی موضوع منطبق تنظیم شده باشند. برای پیش‌فرض حساب از `channels.telegram.dm.threadReplies` در سطح بالا استفاده کنید، یا برای یک DM از `direct.<chatId>.threadReplies`.
</Accordion>
<Accordion title="صدا، ویدیو و استیکرها">
<Accordion title="Audio, video, and stickers">
### پیام‌های صوتی
Telegram یادداشت‌های صوتی را از فایل‌های صوتی متمایز می‌کند.
Telegram میان یادداشت‌های صوتی و فایل‌های صوتی تمایز می‌گذارد.
- پیش‌فرض: رفتار فایل صوتی
- تگ `[[audio_as_voice]]` در پاسخ agent برای اجبار ارسال به‌صورت یادداشت صوتی
- رونوشت‌های یادداشت صوتی ورودی در زمینه agent به‌عنوان متن تولیدشده توسط ماشین و نامطمئن frame می‌شوند؛ تشخیص mention همچنان از رونوشت خام استفاده می‌کند، بنابراین پیام‌های صوتی وابسته به mention همچنان کار می‌کنند.
- برچسب `[[audio_as_voice]]` در پاسخ عامل برای اجبار ارسال یادداشت صوتی
- رونویسی‌های یادداشت صوتی ورودی در زمینهٔ عامل به‌عنوان متن تولیدشده توسط ماشین و نامطمئن قاب‌بندی می‌شوند؛ تشخیص اشاره همچنان از رونویسی خام استفاده می‌کند تا پیام‌های صوتی وابسته به اشاره همچنان کار کنند.
نمونه اقدام پیام:
نمونهٔ کنش پیام:
```json5
{
@ -581,7 +618,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
### پیام‌های ویدیویی
Telegram فایل‌های ویدیویی را از پیام‌های ویدیویی متمایز می‌کند.
Telegram میان فایل‌های ویدیویی و یادداشت‌های ویدیویی تمایز می‌گذارد.
نمونهٔ کنش پیام:
@ -595,13 +632,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
پیام‌های ویدیویی از کپشن پشتیبانی نمی‌کنند؛ متن پیام ارائه‌شده جداگانه ارسال می‌شود.
یادداشت‌های ویدیویی از کپشن پشتیبانی نمی‌کنند؛ متن پیام ارائه‌شده جداگانه ارسال می‌شود.
### استیکرها
مدیریت استیکرهای ورودی:
مدیریت استیکر ورودی:
- WEBP ایستا: دانلود و پردازش می‌شود (placeholder `<media:sticker>`)
- WEBP ایستا: دانلود و پردازش می‌شود (جای‌نگهدار `<media:sticker>`)
- TGS متحرک: نادیده گرفته می‌شود
- WEBM ویدیویی: نادیده گرفته می‌شود
@ -633,7 +670,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
کنش ارسال استیکر:
ارسال کنش استیکر:
```json5
{
@ -644,7 +681,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
جستجوی استیکرهای کش‌شده:
جست‌وجوی استیکرهای کش‌شده:
```json5
{
@ -657,10 +694,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="اعلان‌های واکنش">
واکنش‌های Telegram به‌صورت به‌روزرسانی‌های `message_reaction` دریافت می‌شوند (جدا از payloadهای پیام).
<Accordion title="Reaction notifications">
واکنش‌های Telegram به‌صورت به‌روزرسانی‌های `message_reaction` می‌رسند (جدا از بارهای پیام).
وقتی فعال باشد، OpenClaw رویدادهای سیستمی مانند این را در صف قرار می‌دهد:
هنگام فعال بودن، OpenClaw رویدادهای سیستمی مانند این را در صف قرار می‌دهد:
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
@ -671,40 +708,40 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
نکته‌ها:
- `own` یعنی فقط واکنش‌های کاربر به پیام‌های ارسال‌شده توسط bot (بهترین تلاش از طریق کش پیام‌های ارسال‌شده).
- رویدادهای واکنش همچنان کنترل‌های دسترسی Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`) را رعایت می‌کنند؛ فرستندگان غیرمجاز حذف می‌شوند.
- Telegram در به‌روزرسانی‌های واکنش شناسهٔ thread ارائه نمی‌کند.
- گروه‌های غیر forum به نشست چت گروهی هدایت می‌شوند
- گروه‌های forum به نشست موضوع عمومی گروه (`:topic:1`) هدایت می‌شوند، نه موضوع دقیق مبدأ
- `own` یعنی فقط واکنش‌های کاربر به پیام‌های ارسال‌شده توسط ربات (بهترین تلاش از طریق کش پیام‌های ارسال‌شده).
- رویدادهای واکنش همچنان کنترل‌های دسترسی Telegram را رعایت می‌کنند (`dmPolicy`، `allowFrom`، `groupPolicy`، `groupAllowFrom`)؛ فرستنده‌های غیرمجاز حذف می‌شوند.
- Telegram شناسهٔ رشته را در به‌روزرسانی‌های واکنش ارائه نمی‌کند.
- گروه‌های غیرانجمنی به نشست چت گروهی مسیریابی می‌شوند
- گروه‌های انجمنی به نشست موضوع عمومی گروه (`:topic:1`) مسیریابی می‌شوند، نه موضوع دقیق مبدأ
`allowed_updates` برای polling/webhook به‌طور خودکار شامل `message_reaction` است.
`allowed_updates` برای polling/Webhook به‌طور خودکار شامل `message_reaction` است.
</Accordion>
<Accordion title="واکنش‌های تأیید">
`ackReaction` هنگام پردازش پیام ورودی توسط OpenClaw یک emoji تأیید ارسال می‌کند.
<Accordion title="Ack reactions">
`ackReaction` در حالی که OpenClaw در حال پردازش یک پیام ورودی است، یک ایموجی تأیید می‌فرستد.
ترتیب حل:
- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- fallback emoji هویت agent (`agents.list[].identity.emoji`، وگرنه "👀")
- جایگزین ایموجی هویت عامل (`agents.list[].identity.emoji`، در غیر این صورت "👀")
نکته‌ها:
- Telegram انتظار emoji یونیکد دارد (برای مثال "👀").
- از `""` برای غیرفعال‌کردن واکنش برای یک channel یا account استفاده کنید.
- Telegram انتظار ایموجی یونیکد دارد (برای مثال "👀").
- برای غیرفعال کردن واکنش برای یک کانال یا حساب، از `""` استفاده کنید.
</Accordion>
<Accordion title="نوشتن پیکربندی از رویدادها و فرمان‌های Telegram">
نوشتن پیکربندی channel به‌طور پیش‌فرض فعال است (`configWrites !== false`).
<Accordion title="Config writes from Telegram events and commands">
نوشتن پیکربندی کانال به‌طور پیش‌فرض فعال است (`configWrites !== false`).
نوشتن‌های فعال‌شده توسط Telegram شامل موارد زیر است:
نوشتن‌های برانگیخته از Telegram شامل این موارد است:
- رویدادهای مهاجرت گروه (`migrate_to_chat_id`) برای به‌روزرسانی `channels.telegram.groups`
- `/config set` و `/config unset` (نیازمند فعال‌سازی فرمان)
- `/config set` و `/config unset` (به فعال‌سازی فرمان نیاز دارد)
غیرفعال‌سازی:
@ -720,30 +757,30 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Long polling در برابر webhook">
پیش‌فرض long polling است. برای حالت webhook، `channels.telegram.webhookUrl` و `channels.telegram.webhookSecret` را تنظیم کنید؛ `webhookPath`، `webhookHost` و `webhookPort` اختیاری هستند (پیش‌فرض‌ها `/telegram-webhook`، `127.0.0.1`، `8787`).
<Accordion title="Long polling vs webhook">
پیش‌فرض long polling است. برای حالت Webhook، `channels.telegram.webhookUrl` و `channels.telegram.webhookSecret` را تنظیم کنید؛ `webhookPath`، `webhookHost`، `webhookPort` اختیاری‌اند (پیش‌فرض‌ها `/telegram-webhook`، `127.0.0.1`، `8787`).
شنوندهٔ محلی به `127.0.0.1:8787` متصل می‌شود. برای ورودی عمومی، یا یک reverse proxy جلوی پورت محلی قرار دهید یا عمداً `webhookHost: "0.0.0.0"` را تنظیم کنید.
شنوندهٔ محلی به `127.0.0.1:8787` متصل می‌شود. برای ورودی عمومی، یا یک reverse proxy جلوی پورت محلی قرار دهید یا عامدانه `webhookHost: "0.0.0.0"` را تنظیم کنید.
حالت webhook پیش از بازگرداندن `200` به Telegram، guardهای درخواست، توکن محرمانهٔ Telegram و بدنهٔ JSON را اعتبارسنجی می‌کند.
سپس OpenClaw به‌روزرسانی را به‌صورت ناهمگام از طریق همان مسیرهای bot برای هر چت/هر موضوع که long polling استفاده می‌کند پردازش می‌کند، بنابراین نوبت‌های کند agent باعث نگه‌داشتن ACK تحویل Telegram نمی‌شوند.
حالت Webhook پیش از بازگرداندن `200` به Telegram، نگهبان‌های درخواست، توکن محرمانهٔ Telegram، و بدنهٔ JSON را اعتبارسنجی می‌کند.
سپس OpenClaw به‌روزرسانی را به‌صورت ناهمگام از طریق همان مسیرهای ربات به‌ازای هر چت/هر موضوع که در long polling استفاده می‌شوند پردازش می‌کند، بنابراین نوبت‌های کند عامل، ACK تحویل Telegram را معطل نمی‌کنند.
</Accordion>
<Accordion title="محدودیت‌ها، تلاش مجدد، و هدف‌های CLI">
<Accordion title="Limits, retry, and CLI targets">
- پیش‌فرض `channels.telegram.textChunkLimit` برابر 4000 است.
- `channels.telegram.chunkMode="newline"` پیش از تقسیم بر اساس طول، مرزهای پاراگراف (خطوط خالی) را ترجیح می‌دهد.
- `channels.telegram.mediaMaxMb` (پیش‌فرض 100) اندازهٔ رسانهٔ ورودی و خروجی Telegram را محدود می‌کند.
- `channels.telegram.mediaGroupFlushMs` (پیش‌فرض 500) کنترل می‌کند که آلبوم‌ها/گروه‌های رسانه‌ای Telegram چه مدت buffer شوند پیش از آنکه OpenClaw آن‌ها را به‌عنوان یک پیام ورودی dispatch کند. اگر بخش‌های آلبوم دیر می‌رسند، آن را افزایش دهید؛ برای کاهش تأخیر پاسخ آلبوم آن را کاهش دهید.
- `channels.telegram.timeoutSeconds` timeout کلاینت API Telegram را override می‌کند (اگر تنظیم نشده باشد، پیش‌فرض grammY اعمال می‌شود). کلاینت‌های bot مقدارهای پیکربندی‌شدهٔ کمتر از guard درخواست 60 ثانیه‌ای متن/typing خروجی را clamp می‌کنند تا grammY پیش از اجرای transport guard و fallback OpenClaw، تحویل پاسخ قابل مشاهده را abort نکند. long polling همچنان از guard درخواست 45 ثانیه‌ای `getUpdates` استفاده می‌کند تا pollهای idle برای همیشه رها نشوند.
- `channels.telegram.pollingStallThresholdMs` به‌طور پیش‌فرض `120000` است؛ فقط برای restartهای false-positive polling-stall، آن را بین `30000` و `600000` تنظیم کنید.
- `channels.telegram.mediaGroupFlushMs` (پیش‌فرض 500) کنترل می‌کند آلبوم‌ها/گروه‌های رسانه‌ای Telegram چه مدت پیش از اینکه OpenClaw آن‌ها را به‌عنوان یک پیام ورودی dispatch کند، buffer شوند. اگر بخش‌های آلبوم دیر می‌رسند، آن را افزایش دهید؛ برای کاهش تأخیر پاسخ آلبوم، آن را کاهش دهید.
- `channels.telegram.timeoutSeconds` timeout کلاینت Telegram API را بازنویسی می‌کند (اگر تنظیم نشده باشد، پیش‌فرض grammY اعمال می‌شود). کلاینت‌های ربات مقادیر پیکربندی‌شدهٔ کمتر از نگهبان 60 ثانیه‌ای درخواست متن/تایپ خروجی را clamp می‌کنند تا grammY تحویل پاسخ قابل مشاهده را پیش از اجرای نگهبان transport و fallback در OpenClaw لغو نکند. Long polling همچنان از نگهبان درخواست 45 ثانیه‌ای `getUpdates` استفاده می‌کند تا pollهای بیکار به‌طور نامحدود رها نشوند.
- `channels.telegram.pollingStallThresholdMs` به‌طور پیش‌فرض `120000` است؛ فقط برای راه‌اندازی‌های مجدد polling-stall مثبت کاذب، آن را بین `30000` و `600000` تنظیم کنید.
- تاریخچهٔ زمینهٔ گروه از `channels.telegram.historyLimit` یا `messages.groupChat.historyLimit` استفاده می‌کند (پیش‌فرض 50)؛ `0` غیرفعال می‌کند.
- زمینهٔ تکمیلی reply/quote/forward در حال حاضر همان‌طور که دریافت شده منتقل می‌شود.
- allowlistهای Telegram عمدتاً تعیین می‌کنند چه کسی می‌تواند agent را فعال کند، نه اینکه یک مرز کامل حذف زمینهٔ تکمیلی باشند.
- زمینهٔ تکمیلی پاسخ/نقل‌قول/forward در حال حاضر همان‌طور که دریافت شده منتقل می‌شود.
- allowlistهای Telegram عمدتاً کنترل می‌کنند چه کسی می‌تواند عامل را فعال کند، نه یک مرز کامل ویرایش زمینهٔ تکمیلی.
- کنترل‌های تاریخچهٔ DM:
- `channels.telegram.dmHistoryLimit`
- `channels.telegram.dms["<user_id>"].historyLimit`
- پیکربندی `channels.telegram.retry` برای خطاهای قابل بازیابی API خروجی، روی helperهای ارسال Telegram (CLI/tools/actions) اعمال می‌شود. تحویل پاسخ نهایی ورودی نیز برای خرابی‌های پیش‌اتصال Telegram از تلاش مجدد safe-send محدود استفاده می‌کند، اما envelopeهای شبکهٔ مبهم پس از ارسال را که می‌توانند پیام‌های قابل مشاهده را تکراری کنند، دوباره امتحان نمی‌کند.
- پیکربندی `channels.telegram.retry` برای خطاهای API خروجی قابل بازیابی، روی کمک‌تابع‌های ارسال Telegram (CLI/ابزارها/کنش‌ها) اعمال می‌شود. تحویل پاسخ نهایی ورودی نیز برای خرابی‌های پیش‌اتصال Telegram از یک retry محدود safe-send استفاده می‌کند، اما envelopeهای شبکه‌ای مبهم پس از ارسال را که ممکن است پیام‌های قابل مشاهده را تکراری کنند، retry نمی‌کند.
هدف ارسال CLI می‌تواند شناسهٔ عددی چت یا نام کاربری باشد:
@ -752,7 +789,7 @@ openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
```
pollهای Telegram از `openclaw message poll` استفاده می‌کنند و از موضوع‌های forum پشتیبانی می‌کنند:
pollهای Telegram از `openclaw message poll` استفاده می‌کنند و از موضوعات انجمن پشتیبانی می‌کنند:
```bash
openclaw message poll --channel telegram --target 123456789 \
@ -762,41 +799,41 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
--poll-duration-seconds 300 --poll-public
```
flagهای poll مخصوص Telegram:
پرچم‌های poll فقط مخصوص Telegram:
- `--poll-duration-seconds` (5-600)
- `--poll-anonymous`
- `--poll-public`
- `--thread-id` برای موضوع‌های forum (یا از هدف `:topic:` استفاده کنید)
- `--thread-id` برای موضوعات انجمن (یا از یک هدف `:topic:` استفاده کنید)
ارسال Telegram همچنین پشتیبانی می‌کند از:
ارسال Telegram همچنین از این موارد پشتیبانی می‌کند:
- `--presentation` همراه با blockهای `buttons` برای inline keyboardها وقتی `channels.telegram.capabilities.inlineButtons` اجازه دهد
- `--pin` یا `--delivery '{"pin":true}'` برای درخواست تحویل pinned وقتی bot بتواند در آن چت pin کند
- `--force-document` برای ارسال تصویرها و GIFهای خروجی به‌صورت document به‌جای آپلودهای photo فشرده یا animated-media
- `--presentation` با بلوک‌های `buttons` برای صفحه‌کلیدهای inline وقتی `channels.telegram.capabilities.inlineButtons` اجازه دهد
- `--pin` یا `--delivery '{"pin":true}'` برای درخواست تحویل pin‌شده وقتی ربات بتواند در آن چت pin کند
- `--force-document` برای ارسال تصاویر خروجی و GIFها به‌صورت سند به‌جای آپلود عکس فشرده یا رسانهٔ متحرک
gating کنش:
کنترل کنش:
- `channels.telegram.actions.sendMessage=false` پیام‌های خروجی Telegram، از جمله pollها را غیرفعال می‌کند
- `channels.telegram.actions.poll=false` ایجاد poll در Telegram را غیرفعال می‌کند و ارسال‌های عادی را فعال نگه می‌دارد
- `channels.telegram.actions.poll=false` ساخت poll در Telegram را غیرفعال می‌کند و ارسال‌های عادی را فعال نگه می‌دارد
</Accordion>
<Accordion title="تأییدهای exec در Telegram">
Telegram از تأییدهای exec در DMهای approver پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری promptها را در چت یا موضوع مبدأ ارسال کند. Approverها باید شناسه‌های عددی کاربر Telegram باشند.
<Accordion title="Exec approvals in Telegram">
Telegram از تأییدهای exec در DMهای تأییدکننده پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری promptها را در چت یا موضوع مبدأ ارسال کند. تأییدکنندگان باید شناسه‌های عددی کاربر Telegram باشند.
مسیر پیکربندی:
- `channels.telegram.execApprovals.enabled` (وقتی دست‌کم یک approver قابل resolve باشد، خودکار فعال می‌شود)
- `channels.telegram.execApprovals.enabled` (وقتی حداقل یک تأییدکننده قابل حل باشد، خودکار فعال می‌شود)
- `channels.telegram.execApprovals.approvers` (به شناسه‌های عددی owner از `commands.ownerAllowFrom` fallback می‌کند)
- `channels.telegram.execApprovals.target`: `dm` (پیش‌فرض) | `channel` | `both`
- `agentFilter`, `sessionFilter`
`channels.telegram.allowFrom`، `groupAllowFrom` و `defaultTo` کنترل می‌کنند چه کسی می‌تواند با bot صحبت کند و bot پاسخ‌های عادی را کجا ارسال کند. این‌ها کسی را به approver exec تبدیل نمی‌کنند. نخستین جفت‌سازی DM تأییدشده، وقتی هنوز owner فرمانی وجود ندارد، `commands.ownerAllowFrom` را bootstrap می‌کند، بنابراین راه‌اندازی تک-owner همچنان بدون تکرار شناسه‌ها زیر `execApprovals.approvers` کار می‌کند.
`channels.telegram.allowFrom`، `groupAllowFrom`، و `defaultTo` کنترل می‌کنند چه کسی می‌تواند با ربات صحبت کند و ربات پاسخ‌های عادی را کجا ارسال می‌کند. آن‌ها کسی را به تأییدکنندهٔ exec تبدیل نمی‌کنند. نخستین pair کردن DM تأییدشده، وقتی هنوز owner فرمانی وجود ندارد، `commands.ownerAllowFrom` را bootstrap می‌کند، بنابراین راه‌اندازی تک‌مالک همچنان بدون تکرار شناسه‌ها زیر `execApprovals.approvers` کار می‌کند.
تحویل channel متن فرمان را در چت نشان می‌دهد؛ `channel` یا `both` را فقط در گروه‌ها/موضوع‌های مورد اعتماد فعال کنید. وقتی prompt در یک موضوع forum قرار می‌گیرد، OpenClaw موضوع را برای prompt تأیید و پیام follow-up حفظ می‌کند. تأییدهای exec به‌طور پیش‌فرض پس از 30 دقیقه منقضی می‌شوند.
تحویل کانال متن فرمان را در چت نشان می‌دهد؛ `channel` یا `both` را فقط در گروه‌ها/موضوعات مورد اعتماد فعال کنید. وقتی prompt در یک موضوع انجمن قرار می‌گیرد، OpenClaw موضوع را برای prompt تأیید و پیگیری حفظ می‌کند. تأییدهای exec به‌طور پیش‌فرض پس از 30 دقیقه منقضی می‌شوند.
دکمه‌های تأیید inline همچنین نیاز دارند `channels.telegram.capabilities.inlineButtons` سطح هدف (`dm`، `group`، یا `all`) را مجاز کند. شناسه‌های تأیید با پیشوند `plugin:` از طریق تأییدهای plugin resolve می‌شوند؛ بقیه ابتدا از طریق تأییدهای exec resolve می‌شوند.
دکمه‌های تأیید inline نیز نیاز دارند `channels.telegram.capabilities.inlineButtons` سطح هدف (`dm`، `group`، یا `all`) را مجاز کند. شناسه‌های تأیید با پیشوند `plugin:` از طریق تأییدهای plugin حل می‌شوند؛ سایر موارد ابتدا از طریق تأییدهای exec حل می‌شوند.
[تأییدهای exec](/fa/tools/exec-approvals) را ببینید.
@ -805,14 +842,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
## کنترل‌های پاسخ خطا
وقتی agent با خطای تحویل یا provider مواجه می‌شود، Telegram می‌تواند یا با متن خطا پاسخ دهد یا آن را suppress کند. دو کلید پیکربندی این رفتار را کنترل می‌کنند:
وقتی عامل با خطای تحویل یا provider روبه‌رو می‌شود، Telegram می‌تواند یا با متن خطا پاسخ دهد یا آن را سرکوب کند. دو کلید پیکربندی این رفتار را کنترل می‌کنند:
| کلید | مقدارها | پیش‌فرض | توضیح |
| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` یک پیام خطای دوستانه به چت ارسال می‌کند. `silent` پاسخ‌های خطا را کاملاً suppress می‌کند. |
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | حداقل زمان بین پاسخ‌های خطا به همان چت. از spam خطا هنگام قطعی جلوگیری می‌کند. |
| کلید | مقادیر | پیش‌فرض | توضیح |
| ----------------------------------- | ---------------- | ------- | --------------------------------------------------------------------------------------------- |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` یک پیام خطای دوستانه به چت می‌فرستد. `silent` پاسخ‌های خطا را کاملاً سرکوب می‌کند. |
| `channels.telegram.errorCooldownMs` | عدد (ms) | `60000` | حداقل زمان بین پاسخ‌های خطا به همان چت. از هرزپیام خطا هنگام قطعی‌ها جلوگیری می‌کند. |
Overrideهای per-account، per-group و per-topic پشتیبانی می‌شوند (همان inheritance کلیدهای دیگر پیکربندی Telegram).
بازنویسی‌های به‌ازای هر حساب، هر گروه، و هر موضوع پشتیبانی می‌شوند (همان وراثت سایر کلیدهای پیکربندی Telegram).
```json5
{
@ -833,56 +870,56 @@ Overrideهای per-account، per-group و per-topic پشتیبانی می‌شو
## عیب‌یابی
<AccordionGroup>
<Accordion title="Bot به پیام‌های گروهی بدون mention پاسخ نمی‌دهد">
<Accordion title="Bot does not respond to non mention group messages">
- اگر `requireMention=false`، حالت privacy در Telegram باید visibility کامل را مجاز کند.
- اگر `requireMention=false`، حالت حریم خصوصی Telegram باید دید کامل را مجاز کند.
- BotFather: `/setprivacy` -> Disable
- سپس bot را از گروه حذف و دوباره اضافه کنید
- وقتی پیکربندی انتظار پیام‌های گروهی بدون mention دارد، `openclaw channels status` هشدار می‌دهد.
- `openclaw channels status --probe` می‌تواند شناسه‌های عددی صریح گروه را بررسی کند؛ wildcard `"*"` را نمی‌توان membership-probe کرد.
- تست سریع نشست: `/activation always`.
- سپس ربات را از گروه حذف کنید و دوباره اضافه کنید
- وقتی پیکربندی انتظار پیام‌های گروهی بدون اشاره را داشته باشد، `openclaw channels status` هشدار می‌دهد.
- `openclaw channels status --probe` می‌تواند شناسه‌های عددی صریح گروه را بررسی کند؛ wildcard `"*"` را نمی‌توان از نظر عضویت probe کرد.
- آزمون سریع نشست: `/activation always`.
</Accordion>
<Accordion title="Bot اصلاً پیام‌های گروه را نمی‌بیند">
<Accordion title="Bot not seeing group messages at all">
- وقتی `channels.telegram.groups` وجود دارد، گروه باید فهرست شده باشد (یا شامل `"*"`)
- عضویت bot در گروه را بررسی کنید
- لاگ‌ها را مرور کنید: `openclaw logs --follow` برای دلایل skip
- وقتی `channels.telegram.groups` وجود دارد، گروه باید فهرست شده باشد (یا شامل `"*"` باشد)
- عضویت bot در گروه را تأیید کنید
- گزارش‌ها را بررسی کنید: `openclaw logs --follow` برای دلایل رد شدن
</Accordion>
<Accordion title="فرمان‌ها به‌صورت جزئی کار می‌کنند یا اصلاً کار نمی‌کنند">
<Accordion title="دستورات به‌صورت جزئی کار می‌کنند یا اصلاً کار نمی‌کنند">
- هویت فرستندهٔ خود را مجاز کنید (pairing و/یا `allowFrom` عددی)
- مجوز فرمان حتی وقتی policy گروه `open` باشد همچنان اعمال می‌شود
- `setMyCommands failed` همراه با `BOT_COMMANDS_TOO_MUCH` یعنی منوی native ورودی‌های زیادی دارد؛ فرمان‌های Plugin/skill/custom را کاهش دهید یا منوهای native را غیرفعال کنید
- فراخوانی‌های startup مربوط به `deleteMyCommands` / `setMyCommands` و فراخوانی‌های typing مربوط به `sendChatAction` محدود هستند و در timeout درخواست، یک‌بار از طریق fallback transport Telegram دوباره امتحان می‌شوند. خطاهای پایدار network/fetch معمولاً نشان‌دهندهٔ مشکلات دسترسی DNS/HTTPS به `api.telegram.org` هستند
- هویت فرستنده خود را مجاز کنید (pairing و/یا `allowFrom` عددی)
- مجوزدهی دستورها حتی وقتی سیاست گروه `open` است همچنان اعمال می‌شود
- `setMyCommands failed` با `BOT_COMMANDS_TOO_MUCH` یعنی منوی بومی ورودی‌های بیش‌ازحد زیادی دارد؛ تعداد دستورهای Plugin/Skills/سفارشی را کاهش دهید یا منوهای بومی را غیرفعال کنید
- فراخوانی‌های راه‌اندازی `deleteMyCommands` / `setMyCommands` و فراخوانی‌های تایپ `sendChatAction` محدود هستند و هنگام timeout درخواست، یک‌بار از طریق fallback انتقال Telegram دوباره تلاش می‌شوند. خطاهای پایدار شبکه/fetch معمولاً نشان‌دهنده مشکل دسترسی DNS/HTTPS به `api.telegram.org` هستند
</Accordion>
<Accordion title="Startup توکن غیرمجاز گزارش می‌کند">
<Accordion title="راه‌اندازی، token غیرمجاز گزارش می‌کند">
- `getMe returned 401` شکست احراز هویت Telegram برای توکن بات پیکربندی‌شده است.
- توکن بات را در BotFather دوباره کپی یا بازتولید کنید، سپس `channels.telegram.botToken`، `channels.telegram.tokenFile`، `channels.telegram.accounts.<id>.botToken`، یا `TELEGRAM_BOT_TOKEN` را برای حساب پیش‌فرض به‌روزرسانی کنید.
- `deleteWebhook 401 Unauthorized` هنگام راه‌اندازی نیز شکست احراز هویت است؛ در نظر گرفتن آن به‌عنوان «هیچ webhookای وجود ندارد» فقط همان شکست ناشی از توکن نامعتبر را به فراخوانی‌های بعدی API موکول می‌کند.
- `getMe returned 401` یک شکست احراز هویت Telegram برای token پیکربندی‌شده bot است.
- token مربوط به bot را در BotFather دوباره کپی یا بازتولید کنید، سپس `channels.telegram.botToken`، `channels.telegram.tokenFile`، `channels.telegram.accounts.<id>.botToken` یا `TELEGRAM_BOT_TOKEN` را برای حساب پیش‌فرض به‌روزرسانی کنید.
- `deleteWebhook 401 Unauthorized` هنگام راه‌اندازی نیز شکست احراز هویت است؛ تلقی کردن آن به‌عنوان «هیچ webhookی وجود ندارد» فقط همان شکست token نامعتبر را به فراخوانی‌های بعدی API موکول می‌کند.
</Accordion>
<Accordion title="Polling or network instability">
<Accordion title="ناپایداری polling یا شبکه">
- Node 22+ به‌همراه fetch/proxy سفارشی می‌تواند در صورت ناسازگاری نوع‌های AbortSignal، رفتار لغو فوری را فعال کند.
- برخی میزبان‌ها ابتدا `api.telegram.org` را به IPv6 حل می‌کنند؛ خروجی IPv6 خراب می‌تواند باعث شکست‌های متناوب API Telegram شود.
- اگر لاگ‌ها شامل `TypeError: fetch failed` یا `Network request for 'getUpdates' failed!` باشند، OpenClaw اکنون این موارد را به‌عنوان خطاهای شبکه قابل بازیابی دوباره تلاش می‌کند.
- هنگام راه‌اندازی polling، OpenClaw همان بررسی موفق `getMe` زمان راه‌اندازی را برای grammY دوباره استفاده می‌کند تا اجراکننده پیش از نخستین `getUpdates` به `getMe` دوم نیاز نداشته باشد.
- اگر `deleteWebhook` هنگام راه‌اندازی polling با خطای شبکه گذرا شکست بخورد، OpenClaw به‌جای انجام یک فراخوانی control-plane دیگر پیش از poll، وارد long polling می‌شود. webhook همچنان فعال به‌صورت تعارض `getUpdates` ظاهر می‌شود؛ سپس OpenClaw انتقال Telegram را بازسازی می‌کند و پاک‌سازی webhook را دوباره تلاش می‌کند.
- اگر سوکت‌های Telegram در یک تناوب کوتاه و ثابت بازیافت می‌شوند، مقدار پایین `channels.telegram.timeoutSeconds` را بررسی کنید؛ کلاینت‌های بات مقدارهای پیکربندی‌شده کمتر از محافظ‌های درخواست خروجی و `getUpdates` را محدود می‌کنند، اما نسخه‌های قدیمی‌تر ممکن بود وقتی این مقدار کمتر از آن محافظ‌ها تنظیم می‌شد، هر poll یا پاسخ را لغو کنند.
- اگر لاگ‌ها شامل `Polling stall detected` باشند، OpenClaw به‌طور پیش‌فرض پس از ۱۲۰ ثانیه بدون زنده‌بودن long-poll کامل‌شده، polling را دوباره شروع می‌کند و انتقال Telegram را بازسازی می‌کند.
- `openclaw channels status --probe` و `openclaw doctor` زمانی هشدار می‌دهند که یک حساب polling در حال اجرا پس از مهلت راه‌اندازی `getUpdates` را کامل نکرده باشد، یک حساب webhook در حال اجرا پس از مهلت راه‌اندازی `setWebhook` را کامل نکرده باشد، یا آخرین فعالیت موفق انتقال polling کهنه شده باشد.
- `channels.telegram.pollingStallThresholdMs` را فقط زمانی افزایش دهید که فراخوانی‌های طولانی‌مدت `getUpdates` سالم هستند اما میزبان شما همچنان راه‌اندازی‌های مجدد polling-stall کاذب گزارش می‌کند. توقف‌های پایدار معمولاً به مشکلات proxy، DNS، IPv6، یا خروجی TLS بین میزبان و `api.telegram.org` اشاره دارند.
- Telegram همچنین envهای proxy فرایند را برای انتقال Bot API رعایت می‌کند، از جمله `HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY` و گونه‌های حروف کوچک آن‌ها. `NO_PROXY` / `no_proxy` همچنان می‌تواند `api.telegram.org` را دور بزند.
- اگر proxy مدیریت‌شده OpenClaw از طریق `OPENCLAW_PROXY_URL` برای محیط سرویس پیکربندی شده باشد و هیچ env استاندارد proxy وجود نداشته باشد، Telegram نیز از همان URL برای انتقال Bot API استفاده می‌کند.
- روی میزبان‌های VPS با خروجی مستقیم/TLS ناپایدار، فراخوانی‌های API Telegram را از طریق `channels.telegram.proxy` مسیریابی کنید:
- Node 22+ همراه با fetch/proxy سفارشی می‌تواند در صورت ناسازگاری نوع‌های AbortSignal باعث رفتار abort فوری شود.
- برخی میزبان‌ها ابتدا `api.telegram.org` را به IPv6 resolve می‌کنند؛ خروجی IPv6 خراب می‌تواند باعث شکست‌های متناوب API Telegram شود.
- اگر گزارش‌ها شامل `TypeError: fetch failed` یا `Network request for 'getUpdates' failed!` باشند، OpenClaw اکنون این‌ها را به‌عنوان خطاهای شبکه قابل بازیابی دوباره تلاش می‌کند.
- هنگام راه‌اندازی polling، OpenClaw probe موفق `getMe` راه‌اندازی را برای grammY دوباره استفاده می‌کند تا اجراکننده پیش از اولین `getUpdates` به `getMe` دوم نیاز نداشته باشد.
- اگر `deleteWebhook` هنگام راه‌اندازی polling با خطای شبکه گذرا شکست بخورد، OpenClaw به‌جای انجام یک فراخوانی control-plane دیگر پیش از poll، وارد long polling می‌شود. Webhook همچنان فعال به‌صورت تعارض `getUpdates` نمایان می‌شود؛ سپس OpenClaw انتقال Telegram را دوباره می‌سازد و cleanup webhook را دوباره تلاش می‌کند.
- اگر socketهای Telegram با یک آهنگ ثابت کوتاه بازیافت می‌شوند، مقدار پایین `channels.telegram.timeoutSeconds` را بررسی کنید؛ clientهای bot مقادیر پیکربندی‌شده زیر guardهای درخواست خروجی و `getUpdates` را clamp می‌کنند، اما نسخه‌های قدیمی‌تر وقتی این مقدار زیر آن guardها تنظیم می‌شد می‌توانستند هر poll یا پاسخ را abort کنند.
- اگر گزارش‌ها شامل `Polling stall detected` باشند، OpenClaw به‌صورت پیش‌فرض پس از ۱۲۰ ثانیه بدون liveness تکمیل‌شده long-poll، polling را restart می‌کند و انتقال Telegram را دوباره می‌سازد.
- `openclaw channels status --probe` و `openclaw doctor` وقتی یک حساب polling در حال اجرا پس از مهلت شروع، `getUpdates` را کامل نکرده باشد، وقتی یک حساب webhook در حال اجرا پس از مهلت شروع، `setWebhook` را کامل نکرده باشد، یا وقتی آخرین فعالیت موفق انتقال polling کهنه باشد، هشدار می‌دهند.
- `channels.telegram.pollingStallThresholdMs` را فقط زمانی افزایش دهید که فراخوانی‌های بلندمدت `getUpdates` سالم هستند اما میزبان شما همچنان restartهای polling-stall مثبت کاذب گزارش می‌کند. stallهای پایدار معمولاً به مشکلات proxy، DNS، IPv6 یا خروجی TLS بین میزبان و `api.telegram.org` اشاره دارند.
- Telegram همچنین envهای proxy فرایند را برای انتقال Bot API رعایت می‌کند، از جمله `HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY` و گونه‌های حروف کوچک آن‌ها. `NO_PROXY` / `no_proxy` همچنان می‌تواند `api.telegram.org` را bypass کند.
- اگر proxy مدیریت‌شده OpenClaw از طریق `OPENCLAW_PROXY_URL` برای یک محیط سرویس پیکربندی شده باشد و env استاندارد proxy وجود نداشته باشد، Telegram نیز از همان URL برای انتقال Bot API استفاده می‌کند.
- روی میزبان‌های VPS با خروجی/TLS مستقیم ناپایدار، فراخوانی‌های API Telegram را از طریق `channels.telegram.proxy` مسیریابی کنید:
```yaml
channels:
@ -890,7 +927,7 @@ channels:
proxy: socks5://<user>:<password>@proxy-host:1080
```
- Node 22+ به‌طور پیش‌فرض `autoSelectFamily=true` است (به‌جز WSL2). ترتیب نتیجه DNS برای Telegram ابتدا `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`، سپس `channels.telegram.network.dnsResultOrder`، سپس پیش‌فرض فرایند مانند `NODE_OPTIONS=--dns-result-order=ipv4first` را رعایت می‌کند؛ اگر هیچ‌کدام اعمال نشود، Node 22+ به `ipv4first` بازمی‌گردد.
- Node 22+ به‌صورت پیش‌فرض `autoSelectFamily=true` دارد (به‌جز WSL2). ترتیب نتیجه DNS برای Telegram ابتدا `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`، سپس `channels.telegram.network.dnsResultOrder`، سپس پیش‌فرض فرایند مانند `NODE_OPTIONS=--dns-result-order=ipv4first` را رعایت می‌کند؛ اگر هیچ‌کدام اعمال نشود، Node 22+ به `ipv4first` fallback می‌کند.
- اگر میزبان شما WSL2 است یا صراحتاً با رفتار فقط IPv4 بهتر کار می‌کند، انتخاب خانواده را اجباری کنید:
```yaml
@ -900,11 +937,10 @@ channels:
autoSelectFamily: false
```
- پاسخ‌های محدوده benchmark در RFC 2544 (`198.18.0.0/15`) از قبل به‌طور پیش‌فرض
برای دانلودهای رسانه Telegram مجاز هستند. اگر یک fake-IP یا
proxy شفاف مورد اعتماد، `api.telegram.org` را هنگام دانلود رسانه به نشانی
خصوصی/داخلی/با کاربرد ویژه دیگری بازنویسی می‌کند، می‌توانید برای دورزدن فقط مخصوص Telegram
opt-in کنید:
- پاسخ‌های بازه benchmark RFC 2544 (`198.18.0.0/15`) از قبل به‌صورت پیش‌فرض
برای دانلودهای رسانه Telegram مجاز هستند. اگر یک fake-IP قابل‌اعتماد یا
proxy شفاف، هنگام دانلود رسانه، `api.telegram.org` را به نشانی خصوصی/داخلی/کاربرد ویژه دیگری بازنویسی کند، می‌توانید
در bypass مخصوص Telegram opt in کنید:
```yaml
channels:
@ -913,17 +949,17 @@ channels:
dangerouslyAllowPrivateNetwork: true
```
- همین opt-in برای هر حساب نیز در
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork` در دسترس است.
- اگر proxy شما میزبان‌های رسانه Telegram را به `198.18.x.x` حل می‌کند، ابتدا
پرچم خطرناک را خاموش نگه دارید. رسانه Telegram از قبل به‌طور پیش‌فرض محدوده
benchmark در RFC 2544 را مجاز می‌داند.
- همین opt-in برای هر حساب در
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork` نیز در دسترس است.
- اگر proxy شما میزبان‌های رسانه Telegram را به `198.18.x.x` resolve می‌کند، ابتدا
flag خطرناک را خاموش نگه دارید. رسانه Telegram از قبل بازه benchmark
RFC 2544 را به‌صورت پیش‌فرض مجاز می‌داند.
<Warning>
`channels.telegram.network.dangerouslyAllowPrivateNetwork` محافظت‌های SSRF رسانه Telegram را تضعیف می‌کند. از آن فقط برای محیط‌های proxy مورد اعتماد و تحت کنترل اپراتور مانند Clash، Mihomo، یا مسیریابی fake-IP در Surge استفاده کنید، آن هم زمانی که پاسخ‌های خصوصی یا با کاربرد ویژه خارج از محدوده benchmark در RFC 2544 تولید می‌کنند. برای دسترسی عادی Telegram روی اینترنت عمومی آن را خاموش نگه دارید.
`channels.telegram.network.dangerouslyAllowPrivateNetwork` محافظت‌های SSRF رسانه Telegram را تضعیف می‌کند. فقط در محیط‌های proxy قابل‌اعتماد و تحت کنترل operator مانند مسیریابی fake-IP در Clash، Mihomo یا Surge از آن استفاده کنید، آن هم زمانی که پاسخ‌های خصوصی یا کاربرد ویژه خارج از بازه benchmark RFC 2544 تولید می‌کنند. برای دسترسی عادی عمومی اینترنت به Telegram، آن را خاموش نگه دارید.
</Warning>
- بازنویسی‌های محیطی (موقت):
- overrideهای محیطی (موقت):
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
@ -943,48 +979,48 @@ dig +short api.telegram.org AAAA
مرجع اصلی: [مرجع پیکربندی - Telegram](/fa/gateway/config-channels#telegram).
<Accordion title="High-signal Telegram fields">
<Accordion title="فیلدهای پُرسیگنال Telegram">
- راه‌اندازی/احراز هویت: `enabled`، `botToken`، `tokenFile`، `accounts.*` (`tokenFile` باید به یک فایل معمولی اشاره کند؛ symlinkها رد می‌شوند)
- کنترل دسترسی: `dmPolicy`، `allowFrom`، `groupPolicy`، `groupAllowFrom`، `groups`، `groups.*.topics.*`، `bindings[]` سطح بالا (`type: "acp"`)
- تأییدهای اجرا: `execApprovals`، `accounts.*.execApprovals`
- فرمان/منو: `commands.native`، `commands.nativeSkills`، `customCommands`
- threadها/پاسخ‌ها: `replyToMode`، `dm.threadReplies`، `direct.*.threadReplies`
- streaming: `streaming` (پیش‌نمایش)، `streaming.preview.toolProgress`، `blockStreaming`
- قالب‌بندی/تحویل: `textChunkLimit`، `chunkMode`، `linkPreview`، `responsePrefix`
- رسانه/شبکه: `mediaMaxMb`، `mediaGroupFlushMs`، `timeoutSeconds`، `pollingStallThresholdMs`، `retry`، `network.autoSelectFamily`، `network.dangerouslyAllowPrivateNetwork`، `proxy`
- ریشه API سفارشی: `apiRoot` (فقط ریشه Bot API؛ `/bot<TOKEN>` را وارد نکنید)
- webhook: `webhookUrl`، `webhookSecret`، `webhookPath`، `webhookHost`
- کنش‌ها/قابلیت‌ها: `capabilities.inlineButtons`، `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
- واکنش‌ها: `reactionNotifications`، `reactionLevel`
- خطاها: `errorPolicy`، `errorCooldownMs`
- نوشتن‌ها/تاریخچه: `configWrites`، `historyLimit`، `dmHistoryLimit`، `dms.*.historyLimit`
- راه‌اندازی/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` باید به یک فایل معمولی اشاره کند؛ symlinkها رد می‌شوند)
- کنترل دسترسی: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` سطح بالا (`type: "acp"`)
- تأییدهای exec: `execApprovals`, `accounts.*.execApprovals`
- دستور/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
- thread/reply: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
- streaming: `streaming` (پیش‌نمایش), `streaming.preview.toolProgress`, `blockStreaming`
- قالب‌بندی/تحویل: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
- رسانه/شبکه: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
- ریشه API سفارشی: `apiRoot` (فقط ریشه Bot API؛ شامل `/bot<TOKEN>` نباشد)
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
- actionها/capabilityها: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
- reactionها: `reactionNotifications`, `reactionLevel`
- خطاها: `errorPolicy`, `errorCooldownMs`
- نوشتن/history: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
</Accordion>
<Note>
اولویت چندحسابی: وقتی دو یا چند شناسه حساب پیکربندی شده‌اند، `channels.telegram.defaultAccount` را تنظیم کنید (یا `channels.telegram.accounts.default` را شامل کنید) تا مسیریابی پیش‌فرض صریح شود. در غیر این صورت OpenClaw به نخستین شناسه حساب نرمال‌سازی‌شده بازمی‌گردد و `openclaw doctor` هشدار می‌دهد. حساب‌های نام‌گذاری‌شده `channels.telegram.allowFrom` / `groupAllowFrom` را به ارث می‌برند، اما مقدارهای `accounts.default.*` را نه.
اولویت چندحسابی: وقتی دو یا چند شناسه حساب پیکربندی شده‌اند، `channels.telegram.defaultAccount` را تنظیم کنید (یا `channels.telegram.accounts.default` را شامل کنید) تا مسیریابی پیش‌فرض صریح شود. در غیر این صورت OpenClaw به اولین شناسه حساب نرمال‌شده fallback می‌کند و `openclaw doctor` هشدار می‌دهد. حساب‌های نام‌گذاری‌شده `channels.telegram.allowFrom` / `groupAllowFrom` را به ارث می‌برند، اما مقدارهای `accounts.default.*` را نه.
</Note>
## مرتبط
<CardGroup cols={2}>
<Card title="Pairing" icon="link" href="/fa/channels/pairing">
یک کاربر Telegram را با Gateway جفت کنید.
یک کاربر Telegram را به Gateway pair کنید.
</Card>
<Card title="Groups" icon="users" href="/fa/channels/groups">
رفتار allowlist برای گروه و موضوع.
<Card title="گروه‌ها" icon="users" href="/fa/channels/groups">
رفتار allowlist گروه و موضوع.
</Card>
<Card title="Channel routing" icon="route" href="/fa/channels/channel-routing">
<Card title="مسیریابی کانال" icon="route" href="/fa/channels/channel-routing">
پیام‌های ورودی را به agentها مسیریابی کنید.
</Card>
<Card title="Security" icon="shield" href="/fa/gateway/security">
<Card title="امنیت" icon="shield" href="/fa/gateway/security">
مدل تهدید و سخت‌سازی.
</Card>
<Card title="Multi-agent routing" icon="sitemap" href="/fa/concepts/multi-agent">
<Card title="مسیریابی چندعاملی" icon="sitemap" href="/fa/concepts/multi-agent">
گروه‌ها و موضوع‌ها را به agentها نگاشت کنید.
</Card>
<Card title="Troubleshooting" icon="wrench" href="/fa/channels/troubleshooting">
عیب‌یابی میان‌کانالی.
<Card title="عیب‌یابی" icon="wrench" href="/fa/channels/troubleshooting">
عیب‌یابی‌های میان‌کانالی.
</Card>
</CardGroup>

478
docs/fa/ci.md
View File

@ -1,94 +1,94 @@
---
read_when:
- لازم است بدانید چرا یک وظیفهٔ CI اجرا شده یا نشده است
- شما در حال اشکال‌زدایی یک بررسی ناموفق GitHub Actions هستید
- شما اجرای اعتبارسنجی انتشار یا اجرای مجدد آن را هماهنگ می‌کنید
- شما در حال تغییر فراخوانی ClawSweeper یا بازارسال فعالیت‌های GitHub هستید
summary: گراف کارهای CI، گیت‌های محدوده، چترهای انتشار، و معادل‌های دستورهای محلی
title: خط لوله CI
- باید بفهمید چرا یک وظیفهٔ CI اجرا شد یا نشد
- شما در حال عیب‌یابی یک بررسی ناموفق GitHub Actions هستید
- شما در حال هماهنگی یک اجرای اعتبارسنجی انتشار یا اجرای مجدد آن هستید
- شما در حال تغییر ارسال ClawSweeper یا بازارسال فعالیت GitHub هستید
summary: گراف کارهای CI، گیت‌های دامنه، چترهای انتشار و معادل‌های فرمان‌های محلی
title: خط لولهٔ CI
x-i18n:
generated_at: "2026-05-03T21:27:40Z"
generated_at: "2026-05-04T07:03:13Z"
model: gpt-5.5
provider: openai
source_hash: e07fc44aa844cb66ce529c570cbbbbf502a61bcbcbc3d9488557abb459ef7678
source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d
source_path: ci.md
workflow: 16
---
OpenClaw CI روی هر push به `main` و هر pull request اجرا می‌شود. job `preflight`، diff را طبقه‌بندی می‌کند و وقتی فقط بخش‌های نامرتبط تغییر کرده باشند، laneهای پرهزینه را خاموش می‌کند. اجرای دستی `workflow_dispatch` عمدا scoped هوشمند را دور می‌زند و کل graph را برای release candidateها و اعتبارسنجی گسترده پخش می‌کند. laneهای Android از طریق `include_android` همچنان opt-in می‌مانند. پوشش Plugin مخصوص release در workflow جداگانه [`پیش‌انتشار Plugin`](#plugin-prerelease) قرار دارد و فقط از [`اعتبارسنجی کامل release`](#full-release-validation) یا یک dispatch دستی صریح اجرا می‌شود.
OpenClaw CI روی هر push به `main` و هر pull request اجرا می‌شود. job `preflight`، diff را طبقه‌بندی می‌کند و وقتی فقط بخش‌های نامرتبط تغییر کرده باشند، laneهای پرهزینه را خاموش می‌کند. اجراهای دستی `workflow_dispatch` عمداً از محدوده‌بندی هوشمند عبور می‌کنند و برای release candidateها و اعتبارسنجی گسترده، کل گراف را منشعب می‌کنند. laneهای Android از طریق `include_android` همچنان اختیاری می‌مانند. پوشش Plugin مخصوص انتشار در workflow جداگانه [`Plugin Prerelease`](#plugin-prerelease) قرار دارد و فقط از [`Full Release Validation`](#full-release-validation) یا یک dispatch دستی صریح اجرا می‌شود.
## نمای کلی pipeline
| Job | هدف | زمان اجرا |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | تشخیص تغییرات فقط-docs، scopeهای تغییرکرده، extensionهای تغییرکرده، و ساخت manifest مربوط به CI | همیشه روی pushها و PRهای non-draft |
| `security-scm-fast` | تشخیص کلید خصوصی و audit workflow از طریق `zizmor` | همیشه روی pushها و PRهای non-draft |
| `security-dependency-audit` | audit lockfile production بدون dependency در برابر advisoryهای npm | همیشه روی pushها و PRهای non-draft |
| `security-fast` | aggregate لازم برای jobهای امنیتی سریع | همیشه روی pushها و PRهای non-draft |
| `check-dependencies` | pass فقط-dependency مربوط به Knip در production به‌همراه guard مربوط به allowlist فایل‌های استفاده‌نشده | تغییرات مرتبط با Node |
| `build-artifacts` | ساخت `dist/`، Control UI، بررسی‌های built-artifact، و artifactهای قابل‌استفاده مجدد برای downstream | تغییرات مرتبط با Node |
| `preflight` | تشخیص تغییرات فقط مستندات، scopeهای تغییرکرده، extensionهای تغییرکرده، و ساخت manifest مربوط به CI | همیشه روی pushها و PRهای غیر draft |
| `security-scm-fast` | تشخیص کلید خصوصی و audit workflow از طریق `zizmor` | همیشه روی pushها و PRهای غیر draft |
| `security-dependency-audit` | audit بدون وابستگی lockfile تولید در برابر advisoryهای npm | همیشه روی pushها و PRهای غیر draft |
| `security-fast` | aggregate الزامی برای jobهای امنیتی سریع | همیشه روی pushها و PRهای غیر draft |
| `check-dependencies` | گذر فقط وابستگی Knip تولید به‌علاوه guard مربوط به allowlist فایل‌های استفاده‌نشده | تغییرات مرتبط با Node |
| `build-artifacts` | ساخت `dist/`، Control UI، بررسی‌های artifact ساخته‌شده، و artifactهای پایین‌دستی قابل استفاده مجدد | تغییرات مرتبط با Node |
| `checks-fast-core` | laneهای صحت‌سنجی سریع Linux مانند بررسی‌های bundled/plugin-contract/protocol | تغییرات مرتبط با Node |
| `checks-fast-contracts-channels` | بررسی‌های sharded مربوط به contractهای channel با یک نتیجه aggregate پایدار | تغییرات مرتبط با Node |
| `checks-node-core-test` | shardهای آزمون Core Node، به‌جز laneهای channel، bundled، contract، و extension | تغییرات مرتبط با Node |
| `check` | معادل gate محلی اصلی به‌صورت sharded: typeهای prod، lint، guardها، typeهای test، و smoke سخت‌گیرانه | تغییرات مرتبط با Node |
| `check-additional` | architecture، boundary/prompt drift به‌صورت sharded، guardهای extension، package boundary، و gateway watch | تغییرات مرتبط با Node |
| `build-smoke` | آزمون‌های smoke برای CLI ساخته‌شده و smoke حافظه startup | تغییرات مرتبط با Node |
| `checks` | verifier برای آزمون‌های channel مربوط به built-artifact | تغییرات مرتبط با Node |
| `checks-node-compat-node22` | lane ساخت و smoke برای سازگاری Node 22 | dispatch دستی CI برای releaseها |
| `check-docs` | قالب‌بندی docs، lint، و بررسی لینک‌های خراب | docs تغییر کرده باشد |
| `skills-python` | Ruff + pytest برای Skills مبتنی بر Python | تغییرات مرتبط با Python-skill |
| `checks-windows` | آزمون‌های process/path مخصوص Windows به‌همراه regressionهای مشترک runtime import specifier | تغییرات مرتبط با Windows |
| `macos-node` | lane آزمون TypeScript روی macOS با استفاده از artifactهای ساخته‌شده مشترک | تغییرات مرتبط با macOS |
| `macos-swift` | lint، build، و آزمون‌های Swift برای app macOS | تغییرات مرتبط با macOS |
| `android` | آزمون‌های واحد Android برای هر دو flavor به‌همراه یک build از debug APK | تغییرات مرتبط با Android |
| `test-performance-agent` | بهینه‌سازی روزانه آزمون‌های کند Codex پس از فعالیت trusted | موفقیت CI اصلی یا dispatch دستی |
| `openclaw-performance` | گزارش‌های عملکرد runtime روزانه/درخواستی Kova با laneهای mock-provider، deep-profile، و GPT 5.4 live | dispatch زمان‌بندی‌شده و دستی |
| `checks-fast-contracts-channels` | بررسی‌های sharded قرارداد channel با نتیجه بررسی aggregate پایدار | تغییرات مرتبط با Node |
| `checks-node-core-test` | shardهای تست Core Node، به‌جز laneهای channel، bundled، contract، و extension | تغییرات مرتبط با Node |
| `check` | معادل gate محلی اصلی sharded: typeهای تولید، lint، guardها، typeهای تست، و smoke سختگیرانه | تغییرات مرتبط با Node |
| `check-additional` | معماری، drift مرزی/prompt به‌صورت sharded، guardهای extension، مرز package، و gateway watch | تغییرات مرتبط با Node |
| `build-smoke` | تست‌های smoke مربوط به CLI ساخته‌شده و smoke حافظه startup | تغییرات مرتبط با Node |
| `checks` | verifier برای تست‌های channel مربوط به artifact ساخته‌شده | تغییرات مرتبط با Node |
| `checks-node-compat-node22` | lane ساخت و smoke سازگاری Node 22 | dispatch دستی CI برای انتشارها |
| `check-docs` | قالب‌بندی مستندات، lint، و بررسی لینک‌های خراب | مستندات تغییر کرده باشند |
| `skills-python` | Ruff + pytest برای skills مبتنی بر Python | تغییرات مرتبط با Python-skill |
| `checks-windows` | تست‌های process/path مخصوص Windows به‌علاوه regressionهای مشترک runtime import specifier | تغییرات مرتبط با Windows |
| `macos-node` | lane تست TypeScript در macOS با استفاده از artifactهای ساخته‌شده مشترک | تغییرات مرتبط با macOS |
| `macos-swift` | lint، build، و تست‌های Swift برای app macOS | تغییرات مرتبط با macOS |
| `android` | تست‌های unit Android برای هر دو flavor به‌علاوه یک build APK debug | تغییرات مرتبط با Android |
| `test-performance-agent` | بهینه‌سازی روزانه تست‌های کند Codex پس از فعالیت مورد اعتماد | موفقیت Main CI یا dispatch دستی |
| `openclaw-performance` | گزارش‌های عملکرد runtime روزانه/درخواستی Kova با laneهای mock-provider، deep-profile، و live GPT 5.4 | dispatch زمان‌بندی‌شده و دستی |
## ترتیب fail-fast
1. `preflight` تصمیم می‌گیرد اصلا کدام laneها وجود داشته باشند. منطق `docs-scope` و `changed-scope` stepهایی داخل همین job هستند، نه jobهای مستقل.
2. `security-scm-fast`، `security-dependency-audit`، `security-fast`، `check`، `check-additional`، `check-docs`، و `skills-python` بدون انتظار برای jobهای سنگین‌تر artifact و platform matrix سریع fail می‌شوند.
3. `build-artifacts` با laneهای سریع Linux هم‌پوشانی دارد تا مصرف‌کنندگان downstream به‌محض آماده‌شدن build مشترک بتوانند شروع کنند.
4. پس از آن، laneهای سنگین‌تر platform و runtime پخش می‌شوند: `checks-fast-core`، `checks-fast-contracts-channels`، `checks-node-core-test`، `checks`، `checks-windows`، `macos-node`، `macos-swift`، و `android`.
1. `preflight` تصمیم می‌گیرد اصلاً کدام laneها وجود داشته باشند. منطق `docs-scope` و `changed-scope` مرحله‌هایی داخل این job هستند، نه jobهای مستقل.
2. `security-scm-fast`، `security-dependency-audit`، `security-fast`، `check`، `check-additional`، `check-docs`، و `skills-python` بدون انتظار برای jobهای سنگین‌تر artifact و matrix پلتفرم، سریع fail می‌شوند.
3. `build-artifacts` با laneهای سریع Linux هم‌پوشانی دارد تا مصرف‌کنندگان پایین‌دستی به‌محض آماده شدن build مشترک شروع شوند.
4. پس از آن، laneهای سنگین‌تر پلتفرم و runtime منشعب می‌شوند: `checks-fast-core`، `checks-fast-contracts-channels`، `checks-node-core-test`، `checks`، `checks-windows`، `macos-node`، `macos-swift`، و `android`.
GitHub ممکن است وقتی push جدیدتری روی همان PR یا ref مربوط به `main` می‌نشیند، jobهای superseded را با وضعیت `cancelled` علامت‌گذاری کند. این را noise مربوط به CI در نظر بگیرید، مگر اینکه جدیدترین اجرا برای همان ref نیز در حال fail شدن باشد. بررسی‌های aggregate shard از `!cancelled() && always()` استفاده می‌کنند، بنابراین همچنان failureهای عادی shard را گزارش می‌دهند اما پس از اینکه کل workflow از قبل superseded شده باشد در صف قرار نمی‌گیرند. concurrency key خودکار CI نسخه‌دار است (`CI-v7-*`) تا یک zombie سمت GitHub در یک queue group قدیمی نتواند اجرای جدیدتر main را برای مدت نامحدود block کند. اجراهای دستی full-suite از `CI-manual-v1-*` استفاده می‌کنند و اجراهای درحال‌انجام را cancel نمی‌کنند.
GitHub ممکن است وقتی push جدیدتری روی همان PR یا ref مربوط به `main` قرار می‌گیرد، jobهای جایگزین‌شده را به‌صورت `cancelled` علامت‌گذاری کند. این را noise مربوط به CI در نظر بگیرید، مگر اینکه جدیدترین اجرا برای همان ref نیز fail شده باشد. بررسی‌های aggregate shard از `!cancelled() && always()` استفاده می‌کنند، بنابراین همچنان failureهای عادی shard را گزارش می‌کنند اما پس از اینکه کل workflow از قبل جایگزین شده باشد، در queue قرار نمی‌گیرند. کلید concurrency خودکار CI نسخه‌گذاری شده است (`CI-v7-*`) تا یک zombie سمت GitHub در یک queue group قدیمی نتواند اجراهای جدیدتر main را برای مدت نامحدود block کند. اجراهای دستی full-suite از `CI-manual-v1-*` استفاده می‌کنند و اجراهای در حال انجام را cancel نمی‌کنند.
## Scope و routing
منطق scope در `scripts/ci-changed-scope.mjs` قرار دارد و با آزمون‌های واحد در `src/scripts/ci-changed-scope.test.ts` پوشش داده شده است. dispatch دستی از تشخیص changed-scope عبور می‌کند و باعث می‌شود manifest مربوط به preflight طوری عمل کند که انگار همه بخش‌های scoped تغییر کرده‌اند.
منطق scope در `scripts/ci-changed-scope.mjs` قرار دارد و با تست‌های unit در `src/scripts/ci-changed-scope.test.ts` پوشش داده شده است. dispatch دستی، تشخیص changed-scope را رد می‌کند و باعث می‌شود manifest مربوط به preflight طوری عمل کند که انگار همه بخش‌های scoped تغییر کرده‌اند.
- **ویرایش‌های workflow مربوط به CI** graph مربوط به Node CI و workflow linting را اعتبارسنجی می‌کنند، اما به‌تنهایی buildهای native مربوط به Windows، Android، یا macOS را force نمی‌کنند؛ آن laneهای platform همچنان به تغییرات source مربوط به platform محدود می‌مانند.
- **ویرایش‌های فقط-routing مربوط به CI، ویرایش‌های منتخب و ارزان fixture آزمون core، و ویرایش‌های محدود helper/test-routing مربوط به plugin contract** از مسیر manifest سریع و فقط-Node استفاده می‌کنند: `preflight`، امنیت، و یک task واحد `checks-fast-core`. وقتی تغییر فقط به surfaceهای routing یا helper محدود باشد که task سریع مستقیما exercise می‌کند، آن مسیر از build artifactها، سازگاری Node 22، channel contractها، shardهای کامل core، shardهای bundled-plugin، و matrixهای guard اضافی عبور می‌کند.
- **بررسی‌های Windows Node** به wrapperهای process/path مخصوص Windows، helperهای runner مربوط به npm/pnpm/UI، config مدیر package، و surfaceهای workflow مربوط به CI که آن lane را اجرا می‌کنند محدود است؛ تغییرات نامرتبط در source، plugin، install-smoke، و فقط-test روی laneهای Linux Node می‌مانند.
- **ویرایش‌های workflow مربوط به CI** گراف Node CI به‌علاوه linting workflow را اعتبارسنجی می‌کنند، اما به‌تنهایی buildهای native Windows، Android، یا macOS را اجبار نمی‌کنند؛ آن laneهای پلتفرم همچنان به تغییرات source پلتفرم scoped می‌مانند.
- **ویرایش‌های فقط routing مربوط به CI، ویرایش‌های منتخب و کم‌هزینه fixture تست core، و ویرایش‌های محدود helper/test-routing قرارداد Plugin** از مسیر سریع manifest فقط Node استفاده می‌کنند: `preflight`، امنیت، و یک task واحد `checks-fast-core`. وقتی تغییر به سطح‌های routing یا helper محدود باشد که task سریع مستقیماً آن‌ها را اجرا می‌کند، آن مسیر artifactهای build، سازگاری Node 22، قراردادهای channel، shardهای کامل core، shardهای bundled-plugin، و matrixهای guard اضافی را رد می‌کند.
- **بررسی‌های Windows Node** به wrapperهای process/path مخصوص Windows، helperهای runner مربوط به npm/pnpm/UI، config مدیر package، و سطح‌های workflow مربوط به CI که آن lane را اجرا می‌کنند scoped هستند؛ تغییرات نامرتبط source، Plugin، install-smoke، و فقط تست روی laneهای Linux Node باقی می‌مانند.
کندترین خانواده‌های آزمون Node split یا balanced شده‌اند تا هر job بدون رزرو بیش‌ازحد runner کوچک بماند: channel contractها به‌صورت سه shard وزن‌دار اجرا می‌شوند، laneهای core unit fast/support جداگانه اجرا می‌شوند، core runtime infra بین shardهای state و process/config تقسیم شده است، auto-reply به‌صورت workerهای balanced اجرا می‌شود (با subtree مربوط به reply که به shardهای agent-runner، dispatch، و commands/state-routing تقسیم شده است)، و configهای agentic gateway/server به‌جای انتظار برای built artifactها بین laneهای chat/auth/model/http-plugin/runtime/startup تقسیم شده‌اند. آزمون‌های گسترده browser، QA، media، و pluginهای متفرقه به‌جای catch-all مشترک plugin از configهای اختصاصی Vitest خودشان استفاده می‌کنند. shardهای include-pattern، entryهای timing را با نام shard مربوط به CI ثبت می‌کنند، بنابراین `.artifacts/vitest-shard-timings.json` می‌تواند یک config کامل را از یک shard فیلترشده تشخیص دهد. `check-additional` کار compile/canary مربوط به package-boundary را کنار هم نگه می‌دارد و architecture مربوط به runtime topology را از پوشش gateway watch جدا می‌کند؛ فهرست guardهای boundary بین چهار shard matrix نواری تقسیم شده است، که هرکدام guardهای مستقل منتخب را همزمان اجرا می‌کنند و timing هر check را چاپ می‌کنند، از جمله `pnpm prompt:snapshots:check` تا drift مربوط به prompt مسیر موفق runtime در Codex به همان PR که باعث آن شده pin شود. Gateway watch، آزمون‌های channel، و shard مربوط به core support-boundary داخل `build-artifacts` پس از اینکه `dist/` و `dist-runtime/` از قبل ساخته شدند، همزمان اجرا می‌شوند.
کندترین خانواده‌های تست Node تقسیم یا متعادل شده‌اند تا هر job بدون رزرو بیش‌ازحد runnerها کوچک بماند: قراردادهای channel به‌صورت سه shard وزن‌دار اجرا می‌شوند، laneهای core unit fast/support جداگانه اجرا می‌شوند، زیرساخت runtime core بین shardهای state و process/config تقسیم شده است، auto-reply به‌صورت workerهای متعادل اجرا می‌شود (با تقسیم subtree مربوط به reply به shardهای agent-runner، dispatch، و commands/state-routing)، و configهای agentic gateway/server به‌جای انتظار برای artifactهای ساخته‌شده، میان laneهای chat/auth/model/http-plugin/runtime/startup تقسیم شده‌اند. تست‌های گسترده browser، QA، media، و Pluginهای متفرقه به‌جای catch-all مشترک Plugin، از configهای اختصاصی Vitest خود استفاده می‌کنند. shardهای include-pattern، entryهای timing را با نام shard مربوط به CI ثبت می‌کنند، بنابراین `.artifacts/vitest-shard-timings.json` می‌تواند یک config کامل را از یک shard فیلترشده تشخیص دهد. `check-additional` کارهای compile/canary مرز package را کنار هم نگه می‌دارد و معماری توپولوژی runtime را از پوشش gateway watch جدا می‌کند؛ فهرست guard مرزی روی چهار shard matrix stripe شده است، که هرکدام guardهای مستقل منتخب را هم‌زمان اجرا می‌کنند و timing هر بررسی را چاپ می‌کنند، از جمله `pnpm prompt:snapshots:check` تا drift prompt مسیر موفق runtime مربوط به Codex به PRی که باعث آن شده pin شود. Gateway watch، تست‌های channel، و shard مرز support مربوط به core پس از اینکه `dist/` و `dist-runtime/` ساخته شدند، هم‌زمان داخل `build-artifacts` اجرا می‌شوند.
Android CI هر دو `testPlayDebugUnitTest` و `testThirdPartyDebugUnitTest` را اجرا می‌کند و سپس Play debug APK را می‌سازد. flavor شخص ثالث source set یا manifest جداگانه‌ای ندارد؛ lane آزمون واحد آن همچنان flavor را با flagهای BuildConfig مربوط به SMS/call-log compile می‌کند، درحالی‌که از job تکراری package کردن debug APK روی هر push مرتبط با Android جلوگیری می‌کند.
Android CI هم `testPlayDebugUnitTest` و هم `testThirdPartyDebugUnitTest` را اجرا می‌کند و سپس APK debug مربوط به Play را می‌سازد. flavor شخص ثالث هیچ source set یا manifest جداگانه‌ای ندارد؛ lane تست unit آن همچنان flavor را با flagهای BuildConfig مربوط به SMS/call-log کامپایل می‌کند، در حالی که از یک job تکراری package کردن APK debug در هر push مرتبط با Android جلوگیری می‌کند.
shard `check-dependencies` دستور `pnpm deadcode:dependencies` (یک pass فقط-dependency مربوط به Knip در production که به آخرین نسخه Knip pin شده، با minimum release age مربوط به pnpm که برای نصب `dlx` غیرفعال شده است) و `pnpm deadcode:unused-files` را اجرا می‌کند؛ دومی findingهای production unused-file در Knip را با `scripts/deadcode-unused-files.allowlist.mjs` مقایسه می‌کند. وقتی یک PR فایل استفاده‌نشده جدید و بررسی‌نشده‌ای اضافه کند یا entry کهنه‌ای در allowlist باقی بگذارد، guard مربوط به unused-file fail می‌شود، درحالی‌که surfaceهای عمدی dynamic plugin، generated، build، live-test، و package bridge را که Knip نمی‌تواند به‌صورت statically resolve کند حفظ می‌کند.
shard مربوط به `check-dependencies`، `pnpm deadcode:dependencies` (یک گذر فقط وابستگی Knip تولید که به آخرین نسخه Knip pin شده و minimum release age مربوط به pnpm برای نصب `dlx` غیرفعال است) و `pnpm deadcode:unused-files` را اجرا می‌کند، که یافته‌های فایل استفاده‌نشده تولیدی Knip را با `scripts/deadcode-unused-files.allowlist.mjs` مقایسه می‌کند. guard فایل استفاده‌نشده زمانی fail می‌شود که یک PR فایل استفاده‌نشده جدید و بازبینی‌نشده‌ای اضافه کند یا یک entry قدیمی در allowlist باقی بگذارد، در حالی که سطح‌های intentional dynamic plugin، generated، build، live-test، و package bridge را که Knip نمی‌تواند به‌صورت static resolve کند حفظ می‌کند.
## forwarding فعالیت ClawSweeper
`.github/workflows/clawsweeper-dispatch.yml` bridge سمت هدف از فعالیت repository مربوط به OpenClaw به ClawSweeper است. این workflow کد pull request غیرtrusted را checkout یا اجرا نمی‌کند. workflow یک token برای GitHub App از `CLAWSWEEPER_APP_PRIVATE_KEY` می‌سازد، سپس payloadهای فشرده `repository_dispatch` را به `openclaw/clawsweeper` dispatch می‌کند.
`.github/workflows/clawsweeper-dispatch.yml` پل سمت هدف از فعالیت repository مربوط به OpenClaw به ClawSweeper است. این workflow کد pull request غیرقابل اعتماد را checkout یا اجرا نمی‌کند. workflow یک token مربوط به GitHub App از `CLAWSWEEPER_APP_PRIVATE_KEY` ایجاد می‌کند، سپس payloadهای فشرده `repository_dispatch` را به `openclaw/clawsweeper` dispatch می‌کند.
این workflow چهار lane دارد:
- `clawsweeper_item` برای درخواست‌های دقیق review مربوط به issue و pull request؛
- `clawsweeper_comment` برای commandهای صریح ClawSweeper در commentهای issue؛
- `clawsweeper_commit_review` برای درخواست‌های review در سطح commit روی pushهای `main`؛
- `github_activity` برای فعالیت عمومی GitHub که agent مربوط به ClawSweeper ممکن است inspect کند.
- `github_activity` برای فعالیت عمومی GitHub که agent مربوط به ClawSweeper ممکن است بررسی کند.
lane مربوط به `github_activity` فقط metadata نرمال‌شده را forward می‌کند: نوع event، action، actor، repository، شماره item، URL، title، state، و excerptهای کوتاه برای commentها یا reviewها در صورت وجود. این کار عمدا از forward کردن body کامل webhook پرهیز می‌کند. workflow دریافت‌کننده در `openclaw/clawsweeper` فایل `.github/workflows/github-activity.yml` است، که event نرمال‌شده را برای agent مربوط به ClawSweeper به OpenClaw Gateway hook ارسال می‌کند.
lane مربوط به `github_activity` فقط metadata نرمال‌شده را forward می‌کند: نوع event، action، actor، repository، شماره item، URL، title، state، و excerptهای کوتاه برای commentها یا reviewها وقتی وجود داشته باشند. این lane عمداً از forward کردن کل body مربوط به webhook اجتناب می‌کند. workflow دریافت‌کننده در `openclaw/clawsweeper`، `.github/workflows/github-activity.yml` است، که event نرمال‌شده را برای agent مربوط به ClawSweeper به hook مربوط به OpenClaw Gateway ارسال می‌کند.
فعالیت عمومی observation است، نه delivery-by-default. agent مربوط به ClawSweeper هدف Discord را در prompt خود دریافت می‌کند و باید فقط وقتی event غافلگیرکننده، actionable، پرریسک، یا از نظر عملیاتی مفید است در `#clawsweeper` پست کند. بازکردن‌ها، ویرایش‌ها، churn ربات‌ها، noise تکراری webhook، و traffic عادی review باید به `NO_REPLY` منجر شوند.
فعالیت عمومی observation است، نه delivery-by-default. agent مربوط به ClawSweeper مقصد Discord را در prompt خود دریافت می‌کند و فقط وقتی event غافلگیرکننده، قابل اقدام، پرریسک، یا از نظر عملیاتی مفید باشد باید در `#clawsweeper` پست کند. openهای routine، editها، bot churn، noise تکراری Webhook، و ترافیک عادی review باید به `NO_REPLY` منجر شوند.
در سراسر این مسیر، titleها، commentها، bodyها، متن review، نام branchها، و پیام‌های commit در GitHub را داده غیرtrusted بدانید. آن‌ها ورودی summarization و triage هستند، نه دستورهایی برای workflow یا runtime مربوط به agent.
در سراسر این مسیر، titleها، commentها، bodyها، متن review، نام branchها، و messageهای commit مربوط به GitHub را داده غیرقابل اعتماد در نظر بگیرید. آن‌ها input برای summarization و triage هستند، نه دستورالعمل برای workflow یا runtime agent.
## dispatchهای دستی
اجرای دستی CI همان گراف کار معمول CI را اجرا می‌کند، اما هر مسیر محدوده‌دار غیر Android را اجباری فعال می‌کند: شاردهای Linux Node، شاردهای Pluginهای بسته‌بندی‌شده، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، smoke ساخت، بررسی‌های مستندات، Skills پایتون، Windows، macOS و i18n مربوط به Control UI. اجرای مستقل دستی CI فقط Android را با `include_android=true` اجرا می‌کند؛ چتر کامل انتشار، Android را با ارسال `include_android=true` فعال می‌کند. بررسی‌های ایستای پیش‌انتشار Plugin، شارد فقط-انتشار `agentic-plugins`، پیمایش دسته‌ای کامل extension، و مسیرهای Docker پیش‌انتشار Plugin از CI کنار گذاشته شده‌اند. مجموعه پیش‌انتشار Docker فقط زمانی اجرا می‌شود که `Full Release Validation`، workflow جداگانه `Plugin Prerelease` را با gate اعتبارسنجی انتشار فعال dispatch کند.
اجرای دستی CI همان گراف کارهای CI عادی را اجرا می‌کند، اما همه مسیرهای scoped غیر Android را اجباری فعال می‌کند: shardهای Linux Node، shardهای Plugin بسته‌بندی‌شده، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسی‌های مستندات، Python skills، Windows، macOS و Control UI i18n. اجرای دستی مستقل CI فقط Android را با `include_android=true` اجرا می‌کند؛ چتر کامل انتشار، Android را با ارسال `include_android=true` فعال می‌کند. بررسی‌های ایستای پیش‌انتشار Plugin، shard فقط مخصوص انتشار `agentic-plugins`، sweep کامل دسته extension و مسیرهای Docker پیش‌انتشار Plugin از CI مستثنا هستند. مجموعه پیش‌انتشار Docker فقط زمانی اجرا می‌شود که `Full Release Validation` workflow جداگانه `Plugin Prerelease` را با gate اعتبارسنجی انتشار فعال dispatch کند.
اجرای دستی از یک گروه concurrency یکتا استفاده می‌کند تا مجموعه کامل release-candidate توسط اجرای push یا PR دیگری روی همان ref لغو نشود. ورودی اختیاری `target_ref` به یک فراخوان trusted اجازه می‌دهد آن گراف را در برابر یک branch، tag، یا SHA کامل commit اجرا کند، در حالی که از فایل workflow مربوط به dispatch ref انتخاب‌شده استفاده می‌شود.
اجراهای دستی از یک گروه concurrency یکتا استفاده می‌کنند تا مجموعه کامل release-candidate با یک اجرای push یا PR دیگر روی همان ref لغو نشود. ورودی اختیاری `target_ref` به فراخوان مورد اعتماد اجازه می‌دهد آن گراف را روی یک branch، tag یا commit SHA کامل اجرا کند، در حالی که از فایل workflow متعلق به dispatch ref انتخاب‌شده استفاده می‌شود.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -96,14 +96,14 @@ gh workflow run ci.yml --ref main -f target_ref=<branch-or-sha> -f include_andro
gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
```
## Runnerها
## اجراکننده‌ها
| Runner | کارها |
| اجراکننده | کارها |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`، کارهای امنیتی سریع و aggregateها (`security-scm-fast`، `security-dependency-audit`، `security-fast`)، بررسی‌های سریع protocol/contract/bundled، بررسی‌های شاردشده قرارداد کانال، شاردهای `check` به‌جز lint، شاردها و aggregateهای `check-additional`، verifierهای aggregate تست Node، بررسی‌های مستندات، Skills پایتون، workflow-sanity، labeler، auto-response؛ preflight مربوط به install-smoke نیز از Ubuntu میزبانی‌شده در GitHub استفاده می‌کند تا matrix مربوط به Blacksmith زودتر بتواند queue شود |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`، شاردهای extension سبک‌تر، `checks-fast-core`، `checks-node-compat-node22`، `check-prod-types` و `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`، build-smoke، شاردهای تست Linux Node، شاردهای تست Plugin بسته‌بندی‌شده، `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (به‌اندازه‌ای به CPU حساس است که 8 vCPU بیش از صرفه‌جویی‌اش هزینه داشت)؛ ساخت‌های Docker مربوط به install-smoke (هزینه زمان queue برای 32-vCPU بیش از صرفه‌جویی‌اش بود) |
| `ubuntu-24.04` | `preflight`، کارهای امنیتی سریع و aggregateها (`security-scm-fast`، `security-dependency-audit`، `security-fast`)، بررسی‌های سریع protocol/contract/bundled، بررسی‌های sharded قرارداد کانال، shardهای `check` به‌جز lint، shardها و aggregateهای `check-additional`، verifierهای aggregate آزمون Node، بررسی‌های مستندات، Python skills، workflow-sanity، labeler، auto-response؛ install-smoke preflight نیز از Ubuntu میزبانی‌شده در GitHub استفاده می‌کند تا matrix Blacksmith زودتر بتواند queue شود |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`، shardهای extension سبک‌تر، `checks-fast-core`، `checks-node-compat-node22`، `check-prod-types` و `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`، build-smoke، shardهای آزمون Linux Node، shardهای آزمون Plugin بسته‌بندی‌شده، `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (به اندازه‌ای حساس به CPU که 8 vCPU بیش از آنکه صرفه‌جویی کند هزینه داشت)؛ buildهای Docker برای install-smoke (هزینه زمان queue برای 32-vCPU بیش از صرفه‌جویی آن بود) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` روی `openclaw/openclaw`؛ forkها به `macos-latest` fallback می‌کنند |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` روی `openclaw/openclaw`؛ forkها به `macos-latest` fallback می‌کنند |
@ -137,7 +137,7 @@ pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.jso
## عملکرد OpenClaw
`OpenClaw Performance` workflow عملکرد product/runtime است. این workflow روزانه روی `main` اجرا می‌شود و می‌توان آن را دستی هم dispatch کرد:
`OpenClaw Performance` workflow عملکرد محصول/runtime است. این workflow هر روز روی `main` اجرا می‌شود و می‌توان آن را به‌صورت دستی dispatch کرد:
```bash
gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
@ -145,25 +145,25 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1
gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3
```
Dispatch دستی معمولا benchmark را روی workflow ref انجام می‌دهد. برای benchmark کردن یک tag انتشار یا branch دیگر با پیاده‌سازی فعلی workflow، `target_ref` را تنظیم کنید. مسیرهای گزارش منتشرشده و pointerهای latest بر اساس ref تست‌شده کلیدگذاری می‌شوند، و هر `index.md` ref/SHA تست‌شده، workflow ref/SHA، Kova ref، profile، حالت auth مسیر، مدل، تعداد تکرار، و فیلترهای سناریو را ثبت می‌کند.
dispatch دستی معمولاً benchmark را روی workflow ref اجرا می‌کند. برای benchmark گرفتن از یک tag انتشار یا branch دیگر با پیاده‌سازی فعلی workflow، `target_ref` را تنظیم کنید. مسیرهای گزارش منتشرشده و pointerهای latest بر اساس ref آزموده‌شده کلیدگذاری می‌شوند و هر `index.md`، ref/SHA آزموده‌شده، workflow ref/SHA، Kova ref، profile، حالت احراز هویت lane، model، تعداد تکرار و فیلترهای سناریو را ثبت می‌کند.
این workflow، OCM را از یک انتشار pin‌شده و Kova را از `openclaw/Kova` در ورودی pin‌شده `kova_ref` نصب می‌کند، سپس سه مسیر را اجرا می‌کند:
این workflow، OCM را از یک انتشار pinشده و Kova را از `openclaw/Kova` در ورودی pinشده `kova_ref` نصب می‌کند، سپس سه lane را اجرا می‌کند:
- `mock-provider`: سناریوهای diagnostic مربوط به Kova در برابر runtime ساخت محلی با auth جعلی deterministic سازگار با OpenAI.
- `mock-deep-profile`: profiling مربوط به CPU/heap/trace برای نقاط داغ startup، Gateway، و agent-turn.
- `live-gpt54`: یک نوبت agent واقعی OpenAI `openai/gpt-5.4` که وقتی `OPENAI_API_KEY` در دسترس نباشد skip می‌شود.
- `mock-provider`: سناریوهای diagnostic Kova در برابر runtime با local-build و احراز هویت fake سازگار با OpenAI به‌صورت deterministic.
- `mock-deep-profile`: profiling CPU/heap/trace برای hotspotهای startup، Gateway و agent-turn.
- `live-gpt54`: یک agent turn واقعی OpenAI `openai/gpt-5.4`، که وقتی `OPENAI_API_KEY` در دسترس نباشد skip می‌شود.
مسیر mock-provider پس از عبور Kova، probeهای source بومی OpenClaw را نیز اجرا می‌کند: زمان‌بندی boot و حافظه Gateway در حالت‌های startup پیش‌فرض، hook، و 50-Plugin؛ loopهای hello تکراری `channel-chat-baseline` با mock-OpenAI؛ و فرمان‌های startup مربوط به CLI در برابر Gateway بوت‌شده. خلاصه Markdown مربوط به source probe در بسته گزارش، در `source/index.md` قرار دارد و JSON خام کنار آن است.
lane مربوط به mock-provider پس از عبور Kova، probeهای source بومی OpenClaw را نیز اجرا می‌کند: زمان‌بندی boot و حافظه Gateway در حالت‌های startup پیش‌فرض، hook و 50-Plugin؛ loopهای تکراری hello برای mock-OpenAI `channel-chat-baseline`؛ و فرمان‌های startup CLI در برابر Gateway بوت‌شده. خلاصه Markdown مربوط به source probe در bundle گزارش در `source/index.md` قرار دارد و JSON خام کنار آن است.
هر مسیر artifactهای GitHub را upload می‌کند. وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، workflow همچنین `report.json`، `report.md`، bundleها، `index.md`، و artifactهای source-probe را در `openclaw/clawgrit-reports` زیر `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/` commit می‌کند. pointer فعلی tested-ref به‌شکل `openclaw-performance/<tested-ref>/latest-<lane>.json` نوشته می‌شود.
هر lane artifactهای GitHub را upload می‌کند. وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، workflow همچنین `report.json`، `report.md`، bundleها، `index.md` و artifactهای source-probe را در `openclaw/clawgrit-reports` زیر `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/` commit می‌کند. pointer فعلی ref آزموده‌شده به‌صورت `openclaw-performance/<tested-ref>/latest-<lane>.json` نوشته می‌شود.
## اعتبارسنجی کامل انتشار
`Full Release Validation` workflow چتر دستی برای «اجرای همه‌چیز پیش از انتشار» است. این workflow یک branch، tag، یا SHA کامل commit می‌پذیرد، workflow دستی `CI` را با آن target dispatch می‌کند، `Plugin Prerelease` را برای proof فقط-انتشار مربوط به Plugin/package/static/Docker dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، مجموعه‌های Docker release-path، live/E2E، OpenWebUI، parity مربوط به QA Lab، Matrix، و مسیرهای Telegram dispatch می‌کند. با `rerun_group=all` و `release_profile=full`، این workflow همچنین `NPM Telegram Beta E2E` را در برابر artifact مربوط به `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، `npm_telegram_package_spec` را ارسال کنید تا همان مسیر package مربوط به Telegram در برابر package منتشرشده npm دوباره اجرا شود.
`Full Release Validation` workflow دستی چتری برای «اجرای همه چیز پیش از انتشار» است. این workflow یک branch، tag یا commit SHA کامل را می‌پذیرد، workflow دستی `CI` را با آن target dispatch می‌کند، `Plugin Prerelease` را برای اثبات فقط مخصوص انتشار در حوزه Plugin/package/static/Docker dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، مجموعه‌های Docker release-path، live/E2E، OpenWebUI، QA Lab parity، Matrix و laneهای Telegram dispatch می‌کند. با `rerun_group=all` و `release_profile=full`، همچنین `NPM Telegram Beta E2E` را در برابر artifact `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، `npm_telegram_package_spec` را ارسال کنید تا همان lane package مربوط به Telegram در برابر package منتشرشده npm دوباره اجرا شود.
برای matrix مرحله، نام دقیق jobهای workflow، تفاوت‌های profile، artifactها، و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید.
برای matrix مرحله، نام دقیق jobهای workflow، تفاوت‌های profile، artifactها و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید.
`OpenClaw Release Publish` workflow دستی mutating انتشار است. پس از وجود داشتن tag انتشار و پس از موفقیت preflight مربوط به npm در OpenClaw، آن را از `release/YYYY.M.D` یا `main` dispatch کنید. این workflow، `pnpm plugins:sync:check` را verify می‌کند، `Plugin NPM Release` را برای همه packageهای قابل انتشار Plugin dispatch می‌کند، `Plugin ClawHub Release` را برای همان SHA انتشار dispatch می‌کند، و فقط سپس `OpenClaw NPM Release` را با `preflight_run_id` ذخیره‌شده dispatch می‌کند.
`OpenClaw Release Publish` workflow دستی mutating انتشار است. پس از اینکه tag انتشار وجود داشت و preflight مربوط به npm برای OpenClaw موفق شد، آن را از `release/YYYY.M.D` یا `main` dispatch کنید. این workflow، `pnpm plugins:sync:check` را verify می‌کند، `Plugin NPM Release` را برای همه packageهای Plugin قابل انتشار dispatch می‌کند، `Plugin ClawHub Release` را برای همان release SHA dispatch می‌کند، و فقط بعد از آن `OpenClaw NPM Release` را با `preflight_run_id` ذخیره‌شده dispatch می‌کند.
```bash
gh workflow run openclaw-release-publish.yml \
@ -173,40 +173,35 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
برای proof مربوط به commit pin‌شده روی یک branch با حرکت سریع، به‌جای `gh workflow run ... --ref main -f ref=<sha>` از helper استفاده کنید:
برای اثبات commit pinشده روی یک branch که سریع حرکت می‌کند، به‌جای `gh workflow run ... --ref main -f ref=<sha>` از helper استفاده کنید:
```bash
pnpm ci:full-release --sha <full-sha>
```
Dispatch refهای workflow در GitHub باید branch یا tag باشند، نه SHA خام commit. helper یک branch موقت `release-ci/<sha>-...` را در SHA هدف push می‌کند، `Full Release Validation` را از آن ref pin‌شده dispatch می‌کند، verify می‌کند که `headSha` هر workflow فرزند با target مطابقت دارد، و پس از تکمیل run، branch موقت را حذف می‌کند. verifier چتر همچنین اگر هر workflow فرزند روی SHA متفاوتی اجرا شده باشد، fail می‌شود.
dispatch refهای GitHub workflow باید branch یا tag باشند، نه commit SHA خام. helper یک branch موقت `release-ci/<sha>-...` را در target SHA push می‌کند، `Full Release Validation` را از همان ref pinشده dispatch می‌کند، verify می‌کند که `headSha` هر child workflow با target مطابقت داشته باشد، و پس از کامل شدن run، branch موقت را حذف می‌کند. verifier چتری همچنین اگر هر child workflow در SHA متفاوتی اجرا شده باشد fail می‌شود.
`release_profile` گستره‌ی live/provider را که به بررسی‌های انتشار داده می‌شود کنترل می‌کند. گردش‌کارهای انتشار دستی به‌طور پیش‌فرض از `stable` استفاده می‌کنند؛ فقط زمانی از `full` استفاده کنید که عمدا ماتریس گسترده‌ی مشورتی provider/media را می‌خواهید.
`release_profile` گستره live/ارائه‌دهنده‌ای را کنترل می‌کند که به بررسی‌های انتشار پاس داده می‌شود. گردش‌کارهای انتشار دستی به‌طور پیش‌فرض از `stable` استفاده می‌کنند؛ فقط زمانی از `full` استفاده کنید که عمداً ماتریس گسترده مشورتی ارائه‌دهنده/رسانه را می‌خواهید.
- `minimum` سریع‌ترین مسیرهای حیاتی انتشار OpenAI/core را نگه می‌دارد.
- `stable` مجموعه‌ی پایدار provider/backend را اضافه می‌کند.
- `full` ماتریس گسترده‌ی مشورتی provider/media را اجرا می‌کند.
- `minimum` سریع‌ترین مسیرهای OpenAI/هسته‌ای حیاتی برای انتشار را نگه می‌دارد.
- `stable` مجموعه پایدار ارائه‌دهنده/پس‌زمینه را اضافه می‌کند.
- `full` ماتریس گسترده مشورتی ارائه‌دهنده/رسانه را اجرا می‌کند.
چتر، شناسه‌های اجرای فرزندِ dispatchشده را ثبت می‌کند و کار نهایی `Verify full validation` دوباره نتیجه‌گیری‌های فعلی اجرای فرزند را بررسی می‌کند و جدول‌های کندترین کارها را برای هر اجرای فرزند اضافه می‌کند. اگر یک گردش‌کار فرزند دوباره اجرا شد و سبز شد، فقط کار تأییدکننده‌ی والد را دوباره اجرا کنید تا نتیجه‌ی چتر و خلاصه‌ی زمان‌بندی تازه‌سازی شود.
چتر، شناسه‌های اجرای فرزند ارسال‌شده را ثبت می‌کند، و کار نهایی `Verify full validation` نتیجه‌های فعلی اجرای فرزند را دوباره بررسی می‌کند و جدول‌های کندترین کار را برای هر اجرای فرزند پیوست می‌کند. اگر یک گردش‌کار فرزند دوباره اجرا شود و سبز شود، فقط کار راستی‌آزمای والد را دوباره اجرا کنید تا نتیجه چتر و خلاصه زمان‌بندی تازه شود.
برای بازیابی، هم `Full Release Validation` و هم `OpenClaw Release Checks` مقدار `rerun_group` را می‌پذیرند. برای یک نامزد انتشار از `all` استفاده کنید، برای فقط فرزند CI کامل عادی از `ci`، برای فقط فرزند پیش‌انتشار Plugin از `plugin-prerelease`، برای هر فرزند انتشار از `release-checks`، یا از یک گروه محدودتر روی چتر: `install-smoke`، `cross-os`، `live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، یا `npm-telegram`. این کار اجرای دوباره‌ی یک جعبه‌ی انتشار ناموفق را پس از یک رفع متمرکز محدود نگه می‌دارد.
برای بازیابی، هر دو `Full Release Validation` و `OpenClaw Release Checks` ورودی `rerun_group` را می‌پذیرند. برای یک نامزد انتشار از `all`، فقط برای فرزند CI کامل عادی از `ci`، فقط برای فرزند پیش‌انتشار Plugin از `plugin-prerelease`، برای هر فرزند انتشار از `release-checks`، یا از یک گروه محدودتر استفاده کنید: `install-smoke`، `cross-os`، `live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، یا `npm-telegram` روی چتر. این کار اجرای دوباره یک جعبه انتشار ناموفق را پس از یک اصلاح متمرکز، محدود نگه می‌دارد.
`OpenClaw Release Checks` از ref گردش‌کار معتمد استفاده می‌کند تا ref انتخاب‌شده را یک بار به tarball با نام `release-package-under-test` تبدیل کند، سپس آن artifact را هم به گردش‌کار Docker مسیر انتشار live/E2E و هم به shard پذیرش بسته می‌دهد. این کار بایت‌های بسته را در جعبه‌های انتشار یکسان نگه می‌دارد و از بسته‌بندی دوباره‌ی همان نامزد در چند کار فرزند جلوگیری می‌کند.
`OpenClaw Release Checks` از ref گردش‌کار مورداعتماد استفاده می‌کند تا ref انتخاب‌شده را یک‌بار به یک tarball به نام `release-package-under-test` تبدیل کند، سپس آن artifact را هم به گردش‌کار Docker مسیر انتشار live/E2E و هم به shard پذیرش بسته پاس می‌دهد. این کار بایت‌های بسته را در سراسر جعبه‌های انتشار ثابت نگه می‌دارد و از بسته‌بندی دوباره همان نامزد در چندین کار فرزند جلوگیری می‌کند.
اجراهای تکراری `Full Release Validation` برای `ref=main` و `rerun_group=all`
چتر قدیمی‌تر را جایگزین می‌کنند. ناظر والد هر گردش‌کار فرزندی را که
قبلا dispatch کرده است، هنگام لغو شدن والد لغو می‌کند، بنابراین اعتبارسنجی
جدیدتر main پشت یک اجرای قدیمی دو ساعته‌ی بررسی انتشار منتظر نمی‌ماند.
اعتبارسنجی شاخه/برچسب انتشار و گروه‌های اجرای دوباره‌ی متمرکز
`cancel-in-progress: false` را نگه می‌دارند.
اجراهای تکراری `Full Release Validation` برای `ref=main` و `rerun_group=all` چتر قدیمی‌تر را منسوخ می‌کنند. پایشگر والد هر گردش‌کار فرزندی را که قبلاً ارسال کرده باشد هنگام لغو والد لغو می‌کند، بنابراین اعتبارسنجی جدیدتر main پشت یک اجرای قدیمی دوساعته بررسی انتشار منتظر نمی‌ماند. اعتبارسنجی شاخه/برچسب انتشار و گروه‌های اجرای دوباره متمرکز، `cancel-in-progress: false` را حفظ می‌کنند.
## Shardهای live و E2E
## shardهای live و E2E
فرزند live/E2E انتشار، پوشش گسترده‌ی native `pnpm test:live` را نگه می‌دارد، اما آن را به‌جای یک کار ترتیبی، به‌صورت shardهای نام‌گذاری‌شده از طریق `scripts/test-live-shard.mjs` اجرا می‌کند:
فرزند live/E2E انتشار پوشش گسترده بومی `pnpm test:live` را نگه می‌دارد، اما آن را به‌جای یک کار سریالی، به‌صورت shardهای نام‌گذاری‌شده از طریق `scripts/test-live-shard.mjs` اجرا می‌کند:
- `native-live-src-agents`
- `native-live-src-gateway-core`
- کارهای provider-filtered با نام `native-live-src-gateway-profiles`
- کارهای `native-live-src-gateway-profiles` فیلترشده بر اساس ارائه‌دهنده
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
@ -214,63 +209,61 @@ Dispatch refهای workflow در GitHub باید branch یا tag باشند، ن
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- shardهای جداشده‌ی صدای/ویدئوی media و shardهای موسیقی provider-filtered
- shardهای جداشده صوت/ویدئوی رسانه و shardهای موسیقی فیلترشده بر اساس ارائه‌دهنده
این کار همان پوشش فایل را حفظ می‌کند، درحالی‌که اجرای دوباره و عیب‌یابی خرابی‌های کند provider در live را آسان‌تر می‌کند. نام shardهای تجمیعی `native-live-extensions-o-z`، `native-live-extensions-media`، و `native-live-extensions-media-music` همچنان برای اجرای دوباره‌ی دستی یک‌باره معتبر می‌مانند.
این کار همان پوشش فایل را حفظ می‌کند، در حالی که اجرای دوباره و تشخیص خرابی‌های کند ارائه‌دهنده live را آسان‌تر می‌کند. نام‌های shard تجمیعی `native-live-extensions-o-z`، `native-live-extensions-media` و `native-live-extensions-media-music` همچنان برای اجرای دوباره دستی یک‌مرحله‌ای معتبر می‌مانند.
Shardهای media native live در `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` اجرا می‌شوند که توسط گردش‌کار `Live Media Runner Image` ساخته می‌شود. آن تصویر `ffmpeg` و `ffprobe` را از پیش نصب می‌کند؛ کارهای media فقط پیش از آماده‌سازی، باینری‌ها را بررسی می‌کنند. مجموعه‌های live متکی بر Docker را روی runnerهای عادی Blacksmith نگه دارید — کارهای container جای مناسبی برای اجرای تست‌های Docker تودرتو نیستند.
shardهای رسانه live بومی در `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` اجرا می‌شوند که توسط گردش‌کار `Live Media Runner Image` ساخته می‌شود. آن image، `ffmpeg` و `ffprobe` را از پیش نصب می‌کند؛ کارهای رسانه فقط پیش از راه‌اندازی دودویی‌ها را راستی‌آزمایی می‌کنند. مجموعه‌های live متکی بر Docker را روی runnerهای معمول Blacksmith نگه دارید — کارهای کانتینری جای درستی برای راه‌اندازی آزمون‌های Docker تو‌در‌تو نیستند.
Shardهای live model/backend متکی بر Docker از یک تصویر مشترک جداگانه‌ی `ghcr.io/openclaw/openclaw-live-test:<sha>` برای هر commit انتخاب‌شده استفاده می‌کنند. گردش‌کار live انتشار آن تصویر را یک بار می‌سازد و push می‌کند، سپس shardهای Docker live model، Gateway با shardبندی provider، CLI backend، اتصال ACP، و harness مربوط به Codex با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌شوند. Shardهای Gateway Docker سقف‌های explicit در سطح script با `timeout` دارند که پایین‌تر از timeout کار گردش‌کار است، تا یک container گیرکرده یا مسیر پاک‌سازی به‌جای مصرف کل بودجه‌ی بررسی انتشار سریع شکست بخورد. اگر آن shardها هدف Docker کامل source را مستقل بازسازی کنند، اجرای انتشار پیکربندی نادرستی دارد و زمان دیواری را برای ساخت‌های تکراری تصویر هدر خواهد داد.
shardهای live مدل/پس‌زمینه متکی بر Docker برای هر commit انتخاب‌شده از یک image مشترک جداگانه `ghcr.io/openclaw/openclaw-live-test:<sha>` استفاده می‌کنند. گردش‌کار انتشار live آن image را یک‌بار می‌سازد و push می‌کند، سپس shardهای مدل live Docker، Gateway شاردشده بر اساس ارائه‌دهنده، پس‌زمینه CLI، اتصال ACP و harness Codex با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌شوند. shardهای Docker مربوط به Gateway سقف‌های `timeout` صریح در سطح اسکریپت دارند که پایین‌تر از timeout کار گردش‌کار است، تا یک کانتینر گیرکرده یا مسیر پاک‌سازی، به‌جای مصرف کل بودجه بررسی انتشار، سریع شکست بخورد. اگر آن shardها target کامل Docker منبع را مستقل دوباره بسازند، اجرای انتشار بد پیکربندی شده است و زمان دیواری را روی ساخت‌های تکراری image هدر خواهد داد.
## پذیرش بسته
وقتی پرسش این است که «آیا این بسته‌ی قابل نصب OpenClaw به‌عنوان یک محصول کار می‌کند؟» از `Package Acceptance` استفاده کنید. این با CI عادی فرق دارد: CI عادی درخت source را اعتبارسنجی می‌کند، درحالی‌که پذیرش بسته یک tarball واحد را از طریق همان harness Docker E2E که کاربران پس از نصب یا به‌روزرسانی به کار می‌گیرند اعتبارسنجی می‌کند.
از `Package Acceptance` وقتی استفاده کنید که پرسش این است: «آیا این بسته قابل نصب OpenClaw به‌عنوان یک محصول کار می‌کند؟» این با CI عادی متفاوت است: CI عادی درخت منبع را اعتبارسنجی می‌کند، در حالی که پذیرش بسته یک tarball واحد را از طریق همان harness Docker E2E اعتبارسنجی می‌کند که کاربران پس از نصب یا به‌روزرسانی تجربه می‌کنند.
### کارها
1. `resolve_package` مقدار `workflow_ref` را checkout می‌کند، یک نامزد بسته را resolve می‌کند، `.artifacts/docker-e2e-package/openclaw-current.tgz` را می‌نویسد، `.artifacts/docker-e2e-package/package-candidate.json` را می‌نویسد، هر دو را به‌عنوان artifact با نام `package-under-test` آپلود می‌کند، و source، ref گردش‌کار، ref بسته، نسخه، SHA-256، و profile را در خلاصه‌ی مرحله‌ی GitHub چاپ می‌کند.
2. `docker_acceptance` فایل `openclaw-live-and-e2e-checks-reusable.yml` را با `ref=workflow_ref` و `package_artifact_name=package-under-test` فراخوانی می‌کند. گردش‌کار قابل استفاده‌ی مجدد آن artifact را دانلود می‌کند، inventory مربوط به tarball را اعتبارسنجی می‌کند، هنگام نیاز تصویرهای Docker با digest بسته را آماده می‌کند، و مسیرهای Docker انتخاب‌شده را به‌جای بسته‌بندی checkout گردش‌کار، در برابر آن بسته اجرا می‌کند. وقتی یک profile چند `docker_lanes` هدفمند را انتخاب می‌کند، گردش‌کار قابل استفاده‌ی مجدد بسته و تصویرهای مشترک را یک بار آماده می‌کند، سپس آن مسیرها را به‌عنوان کارهای Docker هدفمند موازی با artifactهای یکتا پخش می‌کند.
3. `package_telegram` به‌صورت اختیاری `NPM Telegram Beta E2E` را فراخوانی می‌کند. وقتی `telegram_mode` برابر `none` نیست اجرا می‌شود و زمانی که پذیرش بسته یک مورد را resolve کرده باشد همان artifact با نام `package-under-test` را نصب می‌کند؛ dispatch مستقل Telegram همچنان می‌تواند یک spec منتشرشده‌ی npm را نصب کند.
4. `summary` اگر resolve بسته، پذیرش Docker، یا مسیر اختیاری Telegram شکست خورده باشد گردش‌کار را ناموفق می‌کند.
1. `resolve_package`، `workflow_ref` را checkout می‌کند، یک نامزد بسته را resolve می‌کند، `.artifacts/docker-e2e-package/openclaw-current.tgz` را می‌نویسد، `.artifacts/docker-e2e-package/package-candidate.json` را می‌نویسد، هر دو را به‌عنوان artifact به نام `package-under-test` بارگذاری می‌کند، و منبع، ref گردش‌کار، ref بسته، نسخه، SHA-256 و profile را در خلاصه گام GitHub چاپ می‌کند.
2. `docker_acceptance`، `openclaw-live-and-e2e-checks-reusable.yml` را با `ref=workflow_ref` و `package_artifact_name=package-under-test` فراخوانی می‌کند. گردش‌کار قابل استفاده مجدد آن artifact را دانلود می‌کند، موجودی tarball را اعتبارسنجی می‌کند، در صورت نیاز imageهای Docker با digest بسته را آماده می‌کند، و مسیرهای انتخاب‌شده Docker را به‌جای بسته‌بندی checkout گردش‌کار، علیه همان بسته اجرا می‌کند. وقتی یک profile چند `docker_lanes` هدفمند را انتخاب می‌کند، گردش‌کار قابل استفاده مجدد بسته و imageهای مشترک را یک‌بار آماده می‌کند، سپس آن مسیرها را به‌صورت کارهای Docker هدفمند موازی با artifactهای یکتا پخش می‌کند.
3. `package_telegram` به‌صورت اختیاری `NPM Telegram Beta E2E` را فراخوانی می‌کند. این کار وقتی اجرا می‌شود که `telegram_mode` برابر `none` نباشد و همان artifact به نام `package-under-test` را زمانی نصب می‌کند که پذیرش بسته یکی را resolve کرده باشد؛ ارسال مستقل Telegram همچنان می‌تواند یک مشخصه منتشرشده npm را نصب کند.
4. `summary` اگر resolve بسته، پذیرش Docker، یا مسیر اختیاری Telegram شکست خورده باشد، گردش‌کار را ناموفق می‌کند.
### منابع نامزد
- `source=npm` فقط `openclaw@beta`، `openclaw@latest`، یا یک نسخه‌ی دقیق انتشار OpenClaw مانند `openclaw@2026.4.27-beta.2` را می‌پذیرد. از این برای پذیرش پیش‌انتشار/پایدار منتشرشده استفاده کنید.
- `source=ref` یک شاخه، برچسب، یا SHA کامل commit از `package_ref` معتمد را بسته‌بندی می‌کند. Resolver شاخه‌ها/برچسب‌های OpenClaw را fetch می‌کند، بررسی می‌کند که commit انتخاب‌شده از تاریخچه‌ی شاخه‌ی repository یا یک برچسب انتشار قابل دسترسی باشد، deps را در یک worktree جداشده نصب می‌کند، و آن را با `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند.
- `source=url` یک `.tgz` مبتنی بر HTTPS را دانلود می‌کند؛ `package_sha256` الزامی است.
- `source=artifact` یک `.tgz` را از `artifact_run_id` و `artifact_name` دانلود می‌کند؛ `package_sha256` اختیاری است اما برای artifactهای به‌اشتراک‌گذاشته‌شده‌ی بیرونی باید ارائه شود.
- `source=npm` فقط `openclaw@beta`، `openclaw@latest`، یا یک نسخه انتشار دقیق OpenClaw مانند `openclaw@2026.4.27-beta.2` را می‌پذیرد. از این برای پذیرش پیش‌انتشار/پایدار منتشرشده استفاده کنید.
- `source=ref` یک شاخه، برچسب، یا SHA کامل commit مورداعتماد `package_ref` را بسته‌بندی می‌کند. resolver شاخه‌ها/برچسب‌های OpenClaw را fetch می‌کند، راستی‌آزمایی می‌کند که commit انتخاب‌شده از تاریخچه شاخه مخزن یا یک برچسب انتشار قابل دسترسی باشد، وابستگی‌ها را در یک worktree جداشده نصب می‌کند، و آن را با `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند.
- `source=url` یک `.tgz` از HTTPS دانلود می‌کند؛ `package_sha256` الزامی است.
- `source=artifact` یک `.tgz` را از `artifact_run_id` و `artifact_name` دانلود می‌کند؛ `package_sha256` اختیاری است، اما برای artifactهای اشتراک‌گذاری‌شده خارجی باید ارائه شود.
`workflow_ref` و `package_ref` را جدا نگه دارید. `workflow_ref` کد معتمد گردش‌کار/harness است که تست را اجرا می‌کند. `package_ref` همان commit منبعی است که وقتی `source=ref` باشد بسته‌بندی می‌شود. این اجازه می‌دهد harness تست فعلی commitهای منبع معتمد قدیمی‌تر را بدون اجرای منطق قدیمی گردش‌کار اعتبارسنجی کند.
`workflow_ref` و `package_ref` را جدا نگه دارید. `workflow_ref` کد مورداعتماد گردش‌کار/harness است که آزمون را اجرا می‌کند. `package_ref` commit منبعی است که وقتی `source=ref` باشد بسته‌بندی می‌شود. این اجازه می‌دهد harness آزمون فعلی، commitهای منبع مورداعتماد قدیمی‌تر را بدون اجرای منطق گردش‌کار قدیمی اعتبارسنجی کند.
### Profileهای مجموعه
### profileهای مجموعه
- `smoke` — `npm-onboard-channel-agent`، `gateway-network`، `config-reload`
- `package` — `npm-onboard-channel-agent`، `doctor-switch`، `update-channel-switch`، `upgrade-survivor`، `published-upgrade-survivor`، `plugins-offline`، `plugin-update`
- `product` — `package` به‌علاوه‌ی `mcp-channels`، `cron-mcp-cleanup`، `openai-web-search-minimal`، `openwebui`
- `full` — chunkهای کامل مسیر انتشار Docker با OpenWebUI
- `custom` — مقدار دقیق `docker_lanes`؛ وقتی `suite_profile=custom` باشد الزامی است
- `product` — `package` به‌علاوه `mcp-channels`، `cron-mcp-cleanup`، `openai-web-search-minimal`، `openwebui`
- `full` — chunkهای کامل Docker مسیر انتشار همراه با OpenWebUI
- `custom` — `docker_lanes` دقیق؛ وقتی `suite_profile=custom` باشد الزامی است
Profile مربوط به `package` از پوشش آفلاین Plugin استفاده می‌کند تا اعتبارسنجی بسته‌ی منتشرشده به دسترس‌بودن live ClawHub وابسته نباشد. مسیر اختیاری Telegram از artifact با نام `package-under-test` در `NPM Telegram Beta E2E` دوباره استفاده می‌کند، و مسیر spec منتشرشده‌ی npm برای dispatchهای مستقل نگه داشته می‌شود.
profile به نام `package` از پوشش آفلاین Plugin استفاده می‌کند تا اعتبارسنجی بسته منتشرشده وابسته به دسترس‌پذیری live ClawHub نباشد. مسیر اختیاری Telegram در `NPM Telegram Beta E2E` از artifact به نام `package-under-test` دوباره استفاده می‌کند، در حالی که مسیر مشخصه npm منتشرشده برای ارسال‌های مستقل نگه داشته می‌شود.
برای سیاست اختصاصی تست به‌روزرسانی و Plugin، شامل فرمان‌های محلی،
مسیرهای Docker، ورودی‌های پذیرش بسته، پیش‌فرض‌های انتشار، و triage شکست،
[تست به‌روزرسانی‌ها و Pluginها](/fa/help/testing-updates-plugins) را ببینید.
برای سیاست اختصاصی آزمون به‌روزرسانی و Plugin، شامل فرمان‌های محلی، مسیرهای Docker، ورودی‌های پذیرش بسته، پیش‌فرض‌های انتشار، و تریاژ خرابی، [Testing updates and plugins](/fa/help/testing-updates-plugins) را ببینید.
بررسی‌های انتشار، پذیرش بسته را با `source=artifact`، artifact بسته‌ی انتشار آماده‌شده، `suite_profile=custom`، `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`، `published_upgrade_survivor_baselines=all-since-2026.4.23`، `published_upgrade_survivor_scenarios=reported-issues`، و `telegram_mode=mock-openai` فراخوانی می‌کنند. این کار اثبات مهاجرت بسته، به‌روزرسانی، پاک‌سازی وابستگی Plugin کهنه، ترمیم نصب Plugin پیکربندی‌شده، Plugin آفلاین، به‌روزرسانی Plugin، و Telegram را روی همان tarball بسته‌ی resolveشده نگه می‌دارد. برای اجرای همان ماتریس در برابر یک بسته‌ی npm ارسال‌شده به‌جای artifact ساخته‌شده از SHA، مقدار `package_acceptance_package_spec` را روی Full Release Validation یا OpenClaw Release Checks تنظیم کنید. بررسی‌های انتشار cross-OS همچنان onboarding، installer، و رفتار platform وابسته به سیستم‌عامل را پوشش می‌دهند؛ اعتبارسنجی محصول بسته/به‌روزرسانی باید با پذیرش بسته شروع شود. مسیر Docker با نام `published-upgrade-survivor` در هر اجرا یک baseline بسته‌ی منتشرشده را اعتبارسنجی می‌کند. در پذیرش بسته، tarball resolveشده‌ی `package-under-test` همیشه نامزد است و `published_upgrade_survivor_baseline` baseline منتشرشده‌ی fallback را انتخاب می‌کند، که پیش‌فرض آن `openclaw@latest` است؛ فرمان‌های اجرای دوباره‌ی مسیر ناموفق آن baseline را حفظ می‌کنند. برای گسترش Full Release CI در همه‌ی انتشارهای پایدار npm از `2026.4.23` تا `latest`، مقدار `published_upgrade_survivor_baselines=all-since-2026.4.23` را تنظیم کنید؛ `release-history` همچنان برای نمونه‌گیری دستی گسترده‌تر با anchor قدیمی‌تر پیش از تاریخ در دسترس است. برای گسترش همان baselineها در fixtureهای شبیه issue برای پیکربندی Feishu، فایل‌های bootstrap/persona حفظ‌شده، نصب‌های OpenClaw Plugin پیکربندی‌شده، مسیرهای log با tilde، و rootهای وابستگی legacy Plugin کهنه، مقدار `published_upgrade_survivor_scenarios=reported-issues` را تنظیم کنید. گردش‌کار جداگانه‌ی `Update Migration` زمانی از مسیر Docker با نام `update-migration` همراه با `all-since-2026.4.23` و `plugin-deps-cleanup` استفاده می‌کند که پرسش درباره‌ی پاک‌سازی کامل به‌روزرسانی منتشرشده باشد، نه گستره‌ی عادی Full Release CI. اجراهای تجمیعی محلی می‌توانند specهای دقیق بسته را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` بدهند، یک مسیر واحد را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` مانند `openclaw@2026.4.15` نگه دارند، یا `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` را برای ماتریس scenario تنظیم کنند. مسیر منتشرشده baseline را با یک دستورالعمل آماده‌ی فرمان `openclaw config set` پیکربندی می‌کند، گام‌های دستورالعمل را در `summary.json` ثبت می‌کند، و پس از شروع Gateway، `/healthz`، `/readyz`، به‌علاوه‌ی وضعیت RPC را probe می‌کند. مسیرهای تازه‌ی بسته‌بندی‌شده و installer در Windows همچنین بررسی می‌کنند که یک بسته‌ی نصب‌شده بتواند override مربوط به browser-control را از یک مسیر مطلق خام Windows import کند. Smoke مربوط به agent-turn cross-OS با OpenAI در صورت تنظیم‌شدن `OPENCLAW_CROSS_OS_OPENAI_MODEL` به‌طور پیش‌فرض از آن استفاده می‌کند، وگرنه از `openai/gpt-5.4`، تا اثبات نصب و Gateway روی مدل تست GPT-5 بماند و از پیش‌فرض‌های GPT-4.x دوری شود.
بررسی‌های انتشار، پذیرش بسته را با `source=artifact`، artifact بسته انتشار آماده‌شده، `suite_profile=custom`، `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`، `published_upgrade_survivor_baselines=all-since-2026.4.23`، `published_upgrade_survivor_scenarios=reported-issues` و `telegram_mode=mock-openai` فراخوانی می‌کنند. این کار اثبات مهاجرت بسته، به‌روزرسانی، پاک‌سازی وابستگی Plugin کهنه، تعمیر نصب Plugin پیکربندی‌شده، Plugin آفلاین، به‌روزرسانی Plugin و Telegram را روی همان tarball بسته resolveشده نگه می‌دارد. برای اجرای همان ماتریس علیه یک بسته npm ارسال‌شده به‌جای artifact ساخته‌شده از SHA، `package_acceptance_package_spec` را روی Full Release Validation یا OpenClaw Release Checks تنظیم کنید. بررسی‌های انتشار چندسیستمی همچنان onboarding، نصب‌کننده، و رفتار پلتفرمی خاص OS را پوشش می‌دهند؛ اعتبارسنجی محصول بسته/به‌روزرسانی باید از پذیرش بسته شروع شود. مسیر Docker به نام `published-upgrade-survivor` در هر اجرا یک baseline بسته منتشرشده را اعتبارسنجی می‌کند. در پذیرش بسته، tarball resolveشده `package-under-test` همیشه نامزد است و `published_upgrade_survivor_baseline`، baseline منتشرشده fallback را انتخاب می‌کند که پیش‌فرض آن `openclaw@latest` است؛ فرمان‌های اجرای دوباره مسیر ناموفق آن baseline را حفظ می‌کنند. برای گسترش CI انتشار کامل روی هر انتشار پایدار npm از `2026.4.23` تا `latest`، `published_upgrade_survivor_baselines=all-since-2026.4.23` را تنظیم کنید؛ `release-history` برای نمونه‌برداری دستی گسترده‌تر با لنگر پیشاتاریخ قدیمی‌تر همچنان در دسترس است. برای گسترش همان baselineها در fixtureهای مشابه issue برای پیکربندی Feishu، فایل‌های bootstrap/persona حفظ‌شده، نصب‌های Plugin پیکربندی‌شده OpenClaw، مسیرهای log با tilde، و ریشه‌های وابستگی Plugin قدیمی و کهنه، `published_upgrade_survivor_scenarios=reported-issues` را تنظیم کنید. گردش‌کار جداگانه `Update Migration` وقتی پرسش، پاک‌سازی جامع به‌روزرسانی منتشرشده است و نه گستره عادی CI انتشار کامل، از مسیر Docker به نام `update-migration` همراه با `all-since-2026.4.23` و `plugin-deps-cleanup` استفاده می‌کند. اجراهای تجمیعی محلی می‌توانند مشخصه‌های دقیق بسته را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` پاس دهند، یک مسیر واحد را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` مانند `openclaw@2026.4.15` نگه دارند، یا `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` را برای ماتریس سناریو تنظیم کنند. مسیر منتشرشده baseline را با یک دستور پخته‌شده `openclaw config set` پیکربندی می‌کند، گام‌های دستور را در `summary.json` ثبت می‌کند، و پس از شروع Gateway، `/healthz`، `/readyz` و وضعیت RPC را probe می‌کند. مسیرهای تازه بسته‌بندی‌شده و نصب‌کننده Windows همچنین راستی‌آزمایی می‌کنند که یک بسته نصب‌شده بتواند override کنترل مرورگر را از یک مسیر مطلق خام Windows import کند. smoke چرخش agent چندسیستمی OpenAI وقتی `OPENCLAW_CROSS_OS_OPENAI_MODEL` تنظیم شده باشد به‌طور پیش‌فرض از آن استفاده می‌کند، وگرنه از `openai/gpt-5.4`، تا اثبات نصب و Gateway روی یک مدل آزمون GPT-5 بماند و از پیش‌فرض‌های GPT-4.x پرهیز شود.
### پنجره‌های سازگاری legacy
پذیرش بسته برای بسته‌های از قبل منتشرشده پنجره‌های سازگاری legacy محدود دارد. بسته‌ها تا `2026.4.25`، شامل `2026.4.25-beta.*`، می‌توانند از مسیر سازگاری استفاده کنند:
پذیرش بسته پنجره‌های سازگاری legacy محدود برای بسته‌هایی دارد که از قبل منتشر شده‌اند. بسته‌ها تا `2026.4.25`، شامل `2026.4.25-beta.*`، ممکن است از مسیر سازگاری استفاده کنند:
- ورودی‌های QA خصوصی شناخته‌شده در `dist/postinstall-inventory.json` ممکن است به فایل‌هایی اشاره کنند که از tarball حذف شده‌اند؛
- وقتی بسته آن flag را expose نمی‌کند، `doctor-switch` ممکن است زیرمورد persistence مربوط به `gateway install --wrapper` را رد کند؛
- `update-channel-switch` ممکن است `pnpm.patchedDependencies` مفقود را از fixture ساختگی git مشتق‌شده از tarball حذف کند و ممکن است مقدار persisted مفقود `update.channel` را log کند؛
- smokeهای Plugin ممکن است محل‌های legacy رکورد نصب را بخوانند یا persistence مفقود رکورد نصب marketplace را بپذیرند؛
- `plugin-update` ممکن است مهاجرت metadata پیکربندی را مجاز بداند، درحالی‌که همچنان لازم می‌داند رکورد نصب و رفتار بدون نصب دوباره بدون تغییر بمانند.
- ورودی‌های خصوصی شناخته‌شده QA در `dist/postinstall-inventory.json` ممکن است به فایل‌های حذف‌شده از tarball اشاره کنند؛
- `doctor-switch` ممکن است زیرمورد ماندگاری `gateway install --wrapper` را وقتی بسته آن flag را expose نمی‌کند رد کند؛
- `update-channel-switch` ممکن است `pnpm.patchedDependencies` گمشده را از fixture جعلی git مشتق‌شده از tarball هرس کند و ممکن است `update.channel` ماندگار گمشده را log کند؛
- smokeهای Plugin ممکن است مکان‌های legacy رکورد نصب را بخوانند یا نبود ماندگاری رکورد نصب marketplace را بپذیرند؛
- `plugin-update` ممکن است مهاجرت metadata پیکربندی را مجاز بداند، در حالی که همچنان الزام می‌کند رکورد نصب و رفتار عدم نصب مجدد بدون تغییر بمانند.
بسته‌ی منتشرشده‌ی `2026.4.26` همچنین ممکن است برای فایل‌های stamp مربوط به metadata ساخت محلی که از قبل ارسال شده بودند هشدار بدهد. بسته‌های بعدی باید قراردادهای مدرن را برآورده کنند؛ همان شرایط به‌جای هشدار یا رد شدن، شکست می‌خورند.
بسته منتشرشده `2026.4.26` نیز ممکن است برای فایل‌های stamp metadata ساخت محلی که از قبل ارسال شده بودند هشدار دهد. بسته‌های بعدی باید قراردادهای مدرن را برآورده کنند؛ همان شرایط به‌جای هشدار یا رد شدن، شکست می‌خورند.
### مثال‌ها
### نمونه‌ها
```bash
# Validate the current beta package with product-level coverage.
@ -311,110 +304,110 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
هنگام اشکال‌زدایی یک اجرای ناموفق پذیرش بسته، از خلاصه‌ی `resolve_package` شروع کنید تا منبع بسته، نسخه، و SHA-256 را تأیید کنید. سپس اجرای فرزند `docker_acceptance` و مصنوعات Docker آن را بررسی کنید: `.artifacts/docker-tests/**/summary.json`، `failures.json`، گزارش‌های lane، زمان‌بندی فازها، و فرمان‌های اجرای دوباره. به‌جای اجرای دوباره‌ی اعتبارسنجی کامل انتشار، اجرای دوباره‌ی پروفایل بسته‌ی ناموفق یا laneهای دقیق Docker را ترجیح دهید.
هنگام اشکال‌زدایی اجرای ناموفق پذیرش بسته، از خلاصه‌ی `resolve_package` شروع کنید تا منبع بسته، نسخه و SHA-256 را تأیید کنید. سپس اجرای فرزند `docker_acceptance` و آرتیفکت‌های Docker آن را بررسی کنید: `.artifacts/docker-tests/**/summary.json`، `failures.json`، لاگ‌های lane، زمان‌بندی فازها و فرمان‌های اجرای دوباره. اجرای دوباره‌ی پروفایل بسته‌ی ناموفق یا laneهای دقیق Docker را به اجرای دوباره‌ی اعتبارسنجی کامل انتشار ترجیح دهید.
## آزمون smoke نصب
## دودآزمایی نصب
گردش‌کار جداگانه‌ی `Install Smoke` همان اسکریپت دامنه را از طریق کار `preflight` خودش دوباره استفاده می‌کند. این پوشش smoke را به `run_fast_install_smoke` و `run_full_install_smoke` تقسیم می‌کند.
Workflow جداگانه‌ی `Install Smoke` همان اسکریپت دامنه را از طریق job مخصوص خود به نام `preflight` دوباره استفاده می‌کند. این workflow پوشش دودآزمایی را به `run_fast_install_smoke` و `run_full_install_smoke` تقسیم می‌کند.
- **مسیر سریع** برای pull requestهایی اجرا می‌شود که سطح‌های Docker/بسته، تغییرات بسته/manifest مربوط به Pluginهای همراه، یا سطح‌های اصلی Plugin/channel/Gateway/Plugin SDK را لمس می‌کنند که کارهای smoke Docker آن‌ها را اجرا می‌کنند. تغییرات فقط-منبع در Pluginهای همراه، ویرایش‌های فقط-تست، و ویرایش‌های فقط-مستندات، workerهای Docker را رزرو نمی‌کنند. مسیر سریع، تصویر Dockerfile ریشه را یک‌بار می‌سازد، CLI را بررسی می‌کند، smoke حذف agents از فضای کاری مشترک در CLI را اجرا می‌کند، e2e مربوط به gateway-network کانتینر را اجرا می‌کند، یک آرگومان ساخت extension همراه را تأیید می‌کند، و پروفایل Docker محدود Plugin همراه را زیر مهلت زمانی تجمیعی ۲۴۰ ثانیه‌ای برای فرمان اجرا می‌کند (اجرای Docker هر سناریو جداگانه محدود می‌شود).
- **مسیر کامل** نصب بسته QR و پوشش Docker/به‌روزرسانی نصب‌کننده را برای اجراهای زمان‌بندی‌شده‌ی شبانه، dispatchهای دستی، بررسی‌های انتشار workflow-call، و pull requestهایی نگه می‌دارد که واقعاً سطح‌های نصب‌کننده/بسته/Docker را لمس می‌کنند. در حالت کامل، install-smoke یک تصویر smoke هدف-SHA از Dockerfile ریشه در GHCR را آماده یا دوباره استفاده می‌کند، سپس نصب بسته QR، smokeهای Dockerfile/Gateway ریشه، smokeهای نصب‌کننده/به‌روزرسانی، و E2E سریع Docker مربوط به Plugin همراه را به‌عنوان کارهای جداگانه اجرا می‌کند تا کار نصب‌کننده پشت smokeهای تصویر ریشه منتظر نماند.
- **مسیر سریع** برای pull requestهایی اجرا می‌شود که سطح‌های Docker/بسته، تغییرات بسته/manifest مربوط به Pluginهای همراه، یا سطح‌های Plugin/کانال/Gateway/Plugin SDK هسته را که jobهای دودآزمایی Docker اجرا می‌کنند، لمس کرده باشند. تغییرات فقط‌منبع در Pluginهای همراه، ویرایش‌های فقط‌تست، و ویرایش‌های فقط‌مستندات workerهای Docker را رزرو نمی‌کنند. مسیر سریع تصویر Dockerfile ریشه را یک‌بار می‌سازد، CLI را بررسی می‌کند، دودآزمایی CLI حذف agentهای workspace مشترک را اجرا می‌کند، e2e مربوط به gateway-network کانتینر را اجرا می‌کند، یک build arg برای extension همراه را تأیید می‌کند، و پروفایل Docker محدودِ Plugin همراه را با timeout تجمعی ۲۴۰ ثانیه‌ای برای فرمان اجرا می‌کند (اجرای Docker هر سناریو جداگانه محدود می‌شود).
- **مسیر کامل** پوشش نصب بسته‌ی QR و Docker/update مربوط به نصب‌کننده را برای اجراهای زمان‌بندی‌شده‌ی شبانه، dispatchهای دستی، بررسی‌های انتشار با workflow-call، و pull requestهایی نگه می‌دارد که واقعاً سطح‌های نصب‌کننده/بسته/Docker را لمس می‌کنند. در حالت کامل، install-smoke یک تصویر دودآزمایی GHCR از Dockerfile ریشه برای target-SHA آماده می‌کند یا دوباره استفاده می‌کند، سپس نصب بسته‌ی QR، دودآزمایی‌های Dockerfile/Gateway ریشه، دودآزمایی‌های نصب‌کننده/update، و Docker E2E سریعِ Plugin همراه را به‌عنوان jobهای جداگانه اجرا می‌کند تا کار نصب‌کننده پشت دودآزمایی‌های تصویر ریشه منتظر نماند.
pushهای `main` (از جمله commitهای merge) مسیر کامل را اجبار نمی‌کنند؛ وقتی منطق دامنه‌ی تغییرات روی یک push پوشش کامل را درخواست کند، گردش‌کار smoke سریع Docker را نگه می‌دارد و smoke کامل نصب را به اعتبارسنجی شبانه یا انتشار واگذار می‌کند.
pushهای `main` (از جمله merge commitها) مسیر کامل را اجباری نمی‌کنند؛ وقتی منطق دامنه‌ی تغییرات روی یک push پوشش کامل را درخواست کند، workflow دودآزمایی سریع Docker را نگه می‌دارد و دودآزمایی کامل نصب را به اعتبارسنجی شبانه یا انتشار واگذار می‌کند.
smoke کند provider تصویر در نصب سراسری Bun به‌طور جداگانه با `run_bun_global_install_smoke` دروازه‌بانی می‌شود. این smoke روی زمان‌بندی شبانه و از گردش‌کار بررسی‌های انتشار اجرا می‌شود، و dispatchهای دستی `Install Smoke` می‌توانند آن را فعال کنند، اما pull requestها و pushهای `main` آن را اجرا نمی‌کنند. تست‌های QR و Docker نصب‌کننده، Dockerfileهای متمرکز بر نصب خودشان را نگه می‌دارند.
دودآزمایی کندِ ارائه‌دهنده‌ی تصویر با نصب global در Bun به‌طور جداگانه با `run_bun_global_install_smoke` کنترل می‌شود. این دودآزمایی در زمان‌بندی شبانه و از workflow بررسی‌های انتشار اجرا می‌شود، و dispatchهای دستی `Install Smoke` می‌توانند آن را فعال کنند، اما pull requestها و pushهای `main` این کار را نمی‌کنند. تست‌های Docker مربوط به QR و نصب‌کننده Dockerfileهای نصب‌محور خودشان را نگه می‌دارند.
## E2E محلی Docker
## Docker E2E محلی
`pnpm test:docker:all` یک تصویر مشترک live-test را از پیش می‌سازد، OpenClaw را یک‌بار به‌صورت tarball npm بسته‌بندی می‌کند، و دو تصویر مشترک `scripts/e2e/Dockerfile` می‌سازد:
`pnpm test:docker:all` یک تصویر live-test مشترک را از قبل می‌سازد، OpenClaw را یک‌بار به‌صورت tarball npm بسته‌بندی می‌کند، و دو تصویر مشترک `scripts/e2e/Dockerfile` را می‌سازد:
- یک اجراکننده‌ی خام Node/Git برای laneهای نصب‌کننده/به‌روزرسانی/وابستگی-Plugin؛
- یک runner خام Node/Git برای laneهای نصب‌کننده/update/وابستگی Plugin؛
- یک تصویر کاربردی که همان tarball را برای laneهای عملکرد عادی در `/app` نصب می‌کند.
تعریف‌های laneهای Docker در `scripts/lib/docker-e2e-scenarios.mjs` قرار دارند، منطق برنامه‌ریز در `scripts/lib/docker-e2e-plan.mjs` قرار دارد، و اجراکننده فقط طرح انتخاب‌شده را اجرا می‌کند. زمان‌بند تصویر را برای هر lane با `OPENCLAW_DOCKER_E2E_BARE_IMAGE` و `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` انتخاب می‌کند، سپس laneها را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند.
تعریف‌های laneهای Docker در `scripts/lib/docker-e2e-scenarios.mjs` قرار دارند، منطق برنامه‌ریز در `scripts/lib/docker-e2e-plan.mjs` قرار دارد، و runner فقط طرح انتخاب‌شده را اجرا می‌کند. زمان‌بند تصویر هر lane را با `OPENCLAW_DOCKER_E2E_BARE_IMAGE` و `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` انتخاب می‌کند، سپس laneها را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند.
### قابل تنظیم‌ها
### تنظیم‌پذیرها
| متغیر | پیش‌فرض | هدف |
| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | تعداد slotهای استخر اصلی برای laneهای عادی. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | تعداد slotهای استخر انتهایی حساس به provider. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | سقف laneهای live هم‌زمان تا providerها throttle نکنند. |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | تعداد slotهای pool اصلی برای laneهای عادی. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | تعداد slotهای pool انتهایی حساس به provider. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | سقف laneهای live هم‌زمان تا providerها throttle نکنند. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | سقف laneهای نصب npm هم‌زمان. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | سقف laneهای چندسرویسی هم‌زمان. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | فاصله‌گذاری بین شروع laneها برای جلوگیری از هجوم ایجاد در daemon Docker؛ برای بدون فاصله‌گذاری `0` تنظیم کنید. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | مهلت زمانی پشتیبان برای هر lane (۱۲۰ دقیقه)؛ laneهای live/tail انتخاب‌شده سقف‌های فشرده‌تری دارند. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` طرح زمان‌بند را بدون اجرای laneها چاپ می‌کند. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | فهرست دقیق laneها با جداکننده‌ی ویرگول؛ smoke پاک‌سازی را رد می‌کند تا agents بتوانند یک lane ناموفق را بازتولید کنند. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | سقف laneهای چندسرویسی هم‌زمان. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | فاصله‌ی زمانی بین شروع laneها برای جلوگیری از هجوم create در daemon Docker؛ برای نبود فاصله `0` بگذارید. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | timeout پشتیبان برای هر lane (۱۲۰ دقیقه)؛ laneهای live/tail انتخاب‌شده سقف‌های سخت‌گیرانه‌تری دارند. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` طرح زمان‌بند را بدون اجرای laneها چاپ می‌کند. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | فهرست دقیق laneها با جداکننده‌ی کاما؛ دودآزمایی پاک‌سازی را رد می‌کند تا agentها بتوانند یک lane ناموفق را بازتولید کنند. |
laneای که از سقف مؤثرش سنگین‌تر باشد همچنان می‌تواند از یک استخر خالی شروع شود، سپس تا زمانی که ظرفیت را آزاد کند به‌تنهایی اجرا می‌شود. preflightهای تجمیعی محلی Docker را بررسی می‌کنند، کانتینرهای کهنه‌ی E2E مربوط به OpenClaw را حذف می‌کنند، وضعیت lane فعال را منتشر می‌کنند، زمان‌بندی laneها را برای ترتیب‌دهی longest-first ماندگار می‌کنند، و به‌طور پیش‌فرض پس از نخستین شکست، زمان‌بندی laneهای pooled جدید را متوقف می‌کنند.
laneای که از سقف مؤثر خود سنگین‌تر است همچنان می‌تواند از یک pool خالی شروع شود، سپس تا زمانی که ظرفیت را آزاد کند به‌تنهایی اجرا می‌شود. preflight تجمعی محلی Docker را بررسی می‌کند، کانتینرهای کهنه‌ی OpenClaw E2E را حذف می‌کند، وضعیت laneهای فعال را منتشر می‌کند، زمان‌بندی laneها را برای مرتب‌سازی طولانی‌ترین‌ها در ابتدا نگه می‌دارد، و به‌طور پیش‌فرض پس از نخستین شکست، زمان‌بندی laneهای pooled جدید را متوقف می‌کند.
### گردش‌کار live/E2E قابل استفاده‌ی دوباره
### Workflow قابل‌استفاده‌ی دوباره‌ی live/E2E
گردش‌کار live/E2E قابل استفاده‌ی دوباره از `scripts/test-docker-all.mjs --plan-json` می‌پرسد که کدام بسته، نوع تصویر، تصویر live، lane، و پوشش credential لازم است. سپس `scripts/docker-e2e.mjs` آن طرح را به خروجی‌ها و خلاصه‌های GitHub تبدیل می‌کند. این گردش‌کار یا OpenClaw را از طریق `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند، یا مصنوع بسته‌ی اجرای جاری را دانلود می‌کند، یا یک مصنوع بسته را از `package_artifact_run_id` دانلود می‌کند؛ موجودی tarball را اعتبارسنجی می‌کند؛ وقتی طرح به laneهای با بسته نصب‌شده نیاز دارد، تصویرهای E2E خام/کاربردی Docker در GHCR با tag مبتنی بر digest بسته را از طریق کش لایه‌ی Docker در Blacksmith می‌سازد و push می‌کند؛ و به‌جای ساخت دوباره، ورودی‌های `docker_e2e_bare_image`/`docker_e2e_functional_image` ارائه‌شده یا تصویرهای موجود مبتنی بر digest بسته را دوباره استفاده می‌کند. pullهای تصویر Docker با یک مهلت زمانی محدود ۱۸۰ ثانیه‌ای برای هر تلاش دوباره امتحان می‌شوند تا جریان گیرکرده‌ی registry/cache به‌جای مصرف بیشتر مسیر بحرانی CI، سریع دوباره تلاش شود.
Workflow قابل‌استفاده‌ی دوباره‌ی live/E2E از `scripts/test-docker-all.mjs --plan-json` می‌پرسد کدام بسته، نوع تصویر، تصویر live، lane و پوشش credential لازم است. سپس `scripts/docker-e2e.mjs` آن طرح را به خروجی‌ها و خلاصه‌های GitHub تبدیل می‌کند. این workflow یا OpenClaw را از طریق `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند، یا آرتیفکت بسته‌ی اجرای فعلی را دانلود می‌کند، یا یک آرتیفکت بسته را از `package_artifact_run_id` دانلود می‌کند؛ inventory tarball را اعتبارسنجی می‌کند؛ وقتی طرح به laneهای package-installed نیاز داشته باشد، تصاویر Docker E2E خام/کاربردی GHCR با tag مبتنی بر digest بسته را از طریق cache لایه‌ی Docker در Blacksmith می‌سازد و push می‌کند؛ و به‌جای ساخت دوباره، از ورودی‌های ارائه‌شده‌ی `docker_e2e_bare_image`/`docker_e2e_functional_image` یا تصاویر موجود مبتنی بر digest بسته دوباره استفاده می‌کند. pullهای تصویر Docker با timeout محدود ۱۸۰ ثانیه‌ای برای هر تلاش دوباره امتحان می‌شوند تا جریان گیرکرده‌ی registry/cache به‌جای مصرف بخش بزرگی از مسیر بحرانی CI، سریع دوباره امتحان شود.
### تکه‌های مسیر انتشار
پوشش Docker انتشار، کارهای کوچک‌تر و تکه‌شده را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند تا هر تکه فقط نوع تصویری را که نیاز دارد pull کند و چندین lane را از طریق همان زمان‌بند وزن‌دار اجرا کند:
پوشش Docker انتشار jobهای تکه‌تکه‌ی کوچک‌تری را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند تا هر تکه فقط نوع تصویر موردنیاز خود را pull کند و چندین lane را از طریق همان زمان‌بند وزن‌دار اجرا کند:
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
تکه‌های فعلی Docker انتشار عبارت‌اند از `core`، `package-update-openai`، `package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`، `plugins-runtime-services`، و `plugins-runtime-install-a` تا `plugins-runtime-install-h`. `plugins-runtime-core`، `plugins-runtime`، و `plugins-integrations` همچنان aliasهای تجمیعی Plugin/runtime باقی می‌مانند. alias مربوط به lane `install-e2e` همچنان alias تجمیعی اجرای دوباره‌ی دستی برای هر دو lane نصب‌کننده‌ی provider باقی می‌ماند.
تکه‌های فعلی Docker انتشار عبارت‌اند از `core`، `package-update-openai`، `package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`، `plugins-runtime-services`، و `plugins-runtime-install-a` تا `plugins-runtime-install-h`. `plugins-runtime-core`، `plugins-runtime` و `plugins-integrations` همچنان aliasهای تجمعی Plugin/runtime هستند. alias مربوط به lane به نام `install-e2e` همچنان alias تجمعی اجرای دوباره‌ی دستی برای هر دو lane نصب‌کننده‌ی provider است.
OpenWebUI وقتی پوشش کامل release-path آن را درخواست کند در `plugins-runtime-services` ادغام می‌شود، و تکه‌ی مستقل `openwebui` را فقط برای dispatchهای فقط-OpenWebUI نگه می‌دارد. laneهای به‌روزرسانی کانال همراه، برای شکست‌های گذرای شبکه npm یک‌بار دوباره تلاش می‌کنند.
وقتی پوشش کامل release-path آن را درخواست کند، OpenWebUI در `plugins-runtime-services` ادغام می‌شود، و فقط برای dispatchهای مختص OpenWebUI، یک تکه‌ی مستقل `openwebui` را نگه می‌دارد. laneهای update کانال‌های همراه برای شکست‌های گذرای شبکه‌ی npm یک‌بار دوباره تلاش می‌کنند.
هر تکه `.artifacts/docker-tests/` را همراه با گزارش‌های lane، زمان‌بندی‌ها، `summary.json`، `failures.json`، زمان‌بندی فازها، JSON طرح زمان‌بند، جدول‌های laneهای کند، و فرمان‌های اجرای دوباره برای هر lane بارگذاری می‌کند. ورودی `docker_lanes` گردش‌کار، laneهای انتخاب‌شده را به‌جای کارهای تکه‌ای علیه تصویرهای آماده اجرا می‌کند؛ این کار اشکال‌زدایی lane ناموفق را به یک کار Docker هدفمند محدود می‌کند و مصنوع بسته را برای همان اجرا آماده، دانلود، یا دوباره استفاده می‌کند؛ اگر یک lane انتخاب‌شده lane زنده‌ی Docker باشد، کار هدفمند تصویر live-test را برای همان اجرای دوباره به‌صورت محلی می‌سازد. فرمان‌های اجرای دوباره‌ی GitHub تولیدشده برای هر lane، وقتی آن مقدارها وجود داشته باشند، شامل `package_artifact_run_id`، `package_artifact_name`، و ورودی‌های تصویر آماده هستند، تا یک lane ناموفق بتواند همان بسته و تصویرهای دقیق اجرای ناموفق را دوباره استفاده کند.
هر تکه `.artifacts/docker-tests/` را همراه با لاگ‌های lane، زمان‌بندی‌ها، `summary.json`، `failures.json`، زمان‌بندی فازها، JSON طرح زمان‌بند، جدول‌های laneهای کند، و فرمان‌های اجرای دوباره برای هر lane آپلود می‌کند. ورودی `docker_lanes` در workflow به‌جای jobهای تکه‌ای، laneهای انتخاب‌شده را روی تصاویر آماده‌شده اجرا می‌کند؛ این کار اشکال‌زدایی lane ناموفق را به یک job هدفمند Docker محدود نگه می‌دارد و آرتیفکت بسته را برای آن اجرا آماده، دانلود یا دوباره استفاده می‌کند؛ اگر lane انتخاب‌شده یک lane زنده‌ی Docker باشد، job هدفمند تصویر live-test را برای آن اجرای دوباره به‌صورت محلی می‌سازد. فرمان‌های اجرای دوباره‌ی GitHub تولیدشده برای هر lane، وقتی آن مقادیر وجود داشته باشند، شامل `package_artifact_run_id`، `package_artifact_name` و ورودی‌های تصویر آماده هستند، تا یک lane ناموفق بتواند از همان بسته و تصاویر دقیق اجرای ناموفق دوباره استفاده کند.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
```
گردش‌کار زمان‌بندی‌شده‌ی live/E2E هر روز مجموعه‌ی کامل Docker مربوط به release-path را اجرا می‌کند.
Workflow زمان‌بندی‌شده‌ی live/E2E مجموعه‌ی کامل Docker مربوط به release-path را روزانه اجرا می‌کند.
## پیش‌انتشار Plugin
`Plugin Prerelease` پوشش محصول/بسته‌ی پرهزینه‌تری است، بنابراین گردش‌کاری جداگانه است که توسط `Full Release Validation` یا توسط یک اپراتور صریح dispatch می‌شود. pull requestهای عادی، pushهای `main`، و dispatchهای دستی مستقل CI این مجموعه را خاموش نگه می‌دارند. این گردش‌کار تست‌های Plugin همراه را میان هشت worker extension متوازن می‌کند؛ آن کارهای shard مربوط به extension هم‌زمان تا دو گروه پیکربندی Plugin را با یک worker Vitest برای هر گروه و heap بزرگ‌تر Node اجرا می‌کنند تا دسته‌های Plugin با import سنگین، کارهای CI اضافی ایجاد نکنند. مسیر پیش‌انتشار Docker فقط-انتشار، laneهای هدفمند Docker را در گروه‌های کوچک دسته‌بندی می‌کند تا از رزرو ده‌ها runner برای کارهای یک تا سه دقیقه‌ای جلوگیری شود.
`Plugin Prerelease` پوشش محصول/بسته‌ی پرهزینه‌تری است، بنابراین workflow جداگانه‌ای است که توسط `Full Release Validation` یا یک operator صریح dispatch می‌شود. pull requestهای عادی، pushهای `main` و dispatchهای دستی مستقل CI این مجموعه را خاموش نگه می‌دارند. این workflow تست‌های Plugin همراه را میان هشت worker مربوط به extension متعادل می‌کند؛ آن jobهای shard مربوط به extension تا دو گروه config Plugin را هم‌زمان با یک worker از Vitest برای هر گروه و heap بزرگ‌تر Node اجرا می‌کنند تا batchهای Plugin با import سنگین jobهای CI اضافی ایجاد نکنند. مسیر prerelease مخصوص انتشار در Docker، laneهای هدفمند Docker را در گروه‌های کوچک batch می‌کند تا برای jobهای یک تا سه دقیقه‌ای ده‌ها runner رزرو نشود.
## آزمایشگاه QA
آزمایشگاه QA laneهای اختصاصی CI خارج از گردش‌کار اصلی smart-scoped دارد. همسانی agentic زیر harnessهای گسترده‌ی QA و انتشار تو در تو قرار دارد، نه یک گردش‌کار مستقل PR. وقتی همسانی باید همراه یک اجرای اعتبارسنجی گسترده اجرا شود، از `Full Release Validation` با `rerun_group=qa-parity` استفاده کنید.
آزمایشگاه QA laneهای CI اختصاصی بیرون از workflow اصلی با دامنه‌ی هوشمند دارد. برابری agentic زیر harnessهای گسترده‌ی QA و انتشار قرار دارد، نه یک workflow مستقل PR. وقتی برابری باید همراه یک اجرای اعتبارسنجی گسترده باشد، از `Full Release Validation` با `rerun_group=qa-parity` استفاده کنید.
- گردش‌کار `QA-Lab - All Lanes` هر شب روی `main` و در dispatch دستی اجرا می‌شود؛ این گردش‌کار lane همسانی mock، lane زنده‌ی Matrix، و laneهای زنده‌ی Telegram و Discord را به‌عنوان کارهای موازی منشعب می‌کند. کارهای زنده از محیط `qa-live-shared` استفاده می‌کنند، و Telegram/Discord از leaseهای Convex استفاده می‌کنند.
- Workflow `QA-Lab - All Lanes` هر شب روی `main` و هنگام dispatch دستی اجرا می‌شود؛ این workflow lane برابری mock، lane زنده‌ی Matrix، و laneهای زنده‌ی Telegram و Discord را به‌صورت jobهای موازی fan out می‌کند. jobهای live از محیط `qa-live-shared` استفاده می‌کنند، و Telegram/Discord از leaseهای Convex استفاده می‌کنند.
بررسی‌های انتشار، laneهای transport زنده‌ی Matrix و Telegram را با provider mock قطعی و مدل‌های mock-qualified (`mock-openai/gpt-5.5` و `mock-openai/gpt-5.5-alt`) اجرا می‌کنند تا قرارداد channel از تأخیر مدل زنده و راه‌اندازی عادی provider-plugin جدا شود. Gateway مربوط به transport زنده، جست‌وجوی حافظه را غیرفعال می‌کند زیرا همسانی QA رفتار حافظه را جداگانه پوشش می‌دهد؛ اتصال provider توسط مجموعه‌های جداگانه‌ی مدل زنده، provider بومی، و provider در Docker پوشش داده می‌شود.
بررسی‌های انتشار، laneهای transport زنده‌ی Matrix و Telegram را با provider mock قطعی و مدل‌های دارای صلاحیت mock (`mock-openai/gpt-5.5` و `mock-openai/gpt-5.5-alt`) اجرا می‌کنند تا قرارداد کانال از latency مدل live و راه‌اندازی عادی provider-plugin جدا شود. Gateway مربوط به transport زنده، جست‌وجوی memory را غیرفعال می‌کند، زیرا برابری QA رفتار memory را جداگانه پوشش می‌دهد؛ اتصال provider توسط مجموعه‌های جداگانه‌ی مدل live، provider بومی، و provider Docker پوشش داده می‌شود.
Matrix از `--profile fast` برای gateهای زمان‌بندی‌شده و انتشار استفاده می‌کند و فقط وقتی CLI checkout‌شده از آن پشتیبانی کند `--fail-fast` را اضافه می‌کند. پیش‌فرض CLI و ورودی گردش‌کار دستی همچنان `all` می‌مانند؛ dispatch دستی با `matrix_profile=all` همیشه پوشش کامل Matrix را به کارهای `transport`، `media`، `e2ee-smoke`، `e2ee-deep`، و `e2ee-cli` shard می‌کند.
Matrix برای gateهای زمان‌بندی‌شده و انتشار از `--profile fast` استفاده می‌کند و فقط وقتی CLI checkoutشده از آن پشتیبانی کند، `--fail-fast` را اضافه می‌کند. پیش‌فرض CLI و ورودی workflow دستی همچنان `all` است؛ dispatch دستی با `matrix_profile=all` همیشه پوشش کامل Matrix را به jobهای `transport`، `media`، `e2ee-smoke`، `e2ee-deep` و `e2ee-cli` shard می‌کند.
`OpenClaw Release Checks` همچنین laneهای حیاتی انتشار آزمایشگاه QA را پیش از تأیید انتشار اجرا می‌کند؛ gate همسانی QA آن بسته‌های نامزد و baseline را به‌عنوان کارهای lane موازی اجرا می‌کند، سپس هر دو مصنوع را در یک کار گزارش کوچک برای مقایسه‌ی نهایی همسانی دانلود می‌کند.
`OpenClaw Release Checks` همچنین laneهای حیاتی انتشارِ آزمایشگاه QA را پیش از تأیید انتشار اجرا می‌کند؛ gate برابری QA آن، بسته‌های candidate و baseline را به‌صورت jobهای lane موازی اجرا می‌کند، سپس هر دو آرتیفکت را در یک job گزارش کوچک برای مقایسه‌ی نهایی برابری دانلود می‌کند.
برای PRهای عادی، به‌جای تلقی همسانی به‌عنوان یک وضعیت الزامی، از شواهد CI/check دامنه‌مند پیروی کنید.
برای PRهای عادی، به‌جای اینکه برابری را یک status الزامی بدانید، از شواهد CI/check دامنه‌دار پیروی کنید.
## CodeQL
گردش‌کار `CodeQL` عمداً یک اسکنر امنیتی مرحلهٔ اول و محدود است، نه پیمایش کامل مخزن. اجراهای محافظ روزانه، دستی و pull requestهای غیرپیش‌نویس، کد گردش‌کارهای Actions به‌همراه پرریسک‌ترین سطوح JavaScript/TypeScript را با پرس‌وجوهای امنیتی با اطمینان بالا که به `security-severity` بالا/بحرانی محدود شده‌اند اسکن می‌کنند.
گردش‌کار `CodeQL` عمداً یک اسکنر امنیتی باریک برای گذر اول است، نه پایش کامل مخزن. اجراهای روزانه، دستی، و محافظ pull requestهای غیرپیش‌نویس، کد گردش‌کار Actions به‌علاوه پرریسک‌ترین سطوح JavaScript/TypeScript را با queryهای امنیتی با اطمینان بالا که به `security-severity` بالا/بحرانی فیلتر شده‌اند اسکن می‌کنند.
محافظ pull request سبک می‌ماند: فقط برای تغییرات زیر `.github/actions`، `.github/codeql`، `.github/workflows`، `packages`، یا `src` شروع می‌شود و همان ماتریس امنیتی با اطمینان بالا را مثل گردش‌کار زمان‌بندی‌شده اجرا می‌کند. CodeQL مربوط به Android و macOS خارج از پیش‌فرض‌های PR می‌مانند.
محافظ pull request سبک می‌ماند: فقط برای تغییرات زیر `.github/actions`، `.github/codeql`، `.github/workflows`، `packages`، یا `src` شروع می‌شود، و همان ماتریس امنیتی با اطمینان بالا را مثل گردش‌کار زمان‌بندی‌شده اجرا می‌کند. Android و macOS CodeQL خارج از پیش‌فرض‌های PR می‌مانند.
### دسته‌های امنیتی
| دسته | سطح |
| دسته | سطح |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Auth، secrets، sandbox، cron، و خط مبنای gateway |
| `/codeql-security-high/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال core به‌علاوه runtime مربوط به Plugin کانال، Gateway، Plugin SDK، secrets، نقاط تماس audit |
| `/codeql-security-high/network-ssrf-boundary` | سطوح سیاست SSRF در core، تحلیل IP، محافظ شبکه، web-fetch، و Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | سرورهای MCP، کمک‌کننده‌های اجرای فرایند، تحویل خروجی، و دروازه‌های اجرای ابزار agent |
| `/codeql-security-high/plugin-trust-boundary` | سطوح اعتماد نصب Plugin، loader، manifest، registry، نصب package-manager، بارگذاری منبع، و قرارداد بستهٔ Plugin SDK |
| `/codeql-security-high/core-auth-secrets` | Auth، secrets، sandbox، Cron، و خط مبنای Gateway |
| `/codeql-security-high/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال هسته به‌همراه runtime مربوط به channel plugin، Gateway، Plugin SDK، secrets، و نقاط تماس audit |
| `/codeql-security-high/network-ssrf-boundary` | سطوح SSRF هسته، تجزیه IP، نگهبان شبکه، web-fetch، و سیاست SSRF در Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | سرورهای MCP، helperهای اجرای فرایند، تحویل خروجی، و gateهای اجرای ابزار agent |
| `/codeql-security-high/plugin-trust-boundary` | سطوح اعتماد نصب Plugin، loader، manifest، registry، نصب package-manager، بارگذاری منبع، و قرارداد package در Plugin SDK |
### شاردهای امنیتی ویژهٔ پلتفرم
### shardهای امنیتی مختص پلتفرم
- `CodeQL Android Critical Security` — شارد امنیتی زمان‌بندی‌شدهٔ Android. برنامهٔ Android را برای CodeQL به‌صورت دستی روی کوچک‌ترین رانر Blacksmith Linux پذیرفته‌شده توسط workflow sanity می‌سازد. زیر `/codeql-critical-security/android` بارگذاری می‌کند.
- `CodeQL macOS Critical Security` — شارد امنیتی هفتگی/دستی macOS. برنامهٔ macOS را برای CodeQL به‌صورت دستی روی Blacksmith macOS می‌سازد، نتایج ساخت وابستگی‌ها را از SARIF بارگذاری‌شده فیلتر می‌کند، و زیر `/codeql-critical-security/macos` بارگذاری می‌کند. خارج از پیش‌فرض‌های روزانه نگه داشته شده چون ساخت macOS حتی وقتی پاک است، runtime را غالب می‌کند.
- `CodeQL Android Critical Security` — shard امنیتی زمان‌بندی‌شده Android. برنامه Android را برای CodeQL روی کوچک‌ترین runner لینوکسی Blacksmith که sanity گردش‌کار می‌پذیرد به‌صورت دستی build می‌کند. خروجی را زیر `/codeql-critical-security/android` بارگذاری می‌کند.
- `CodeQL macOS Critical Security` — shard امنیتی هفتگی/دستی macOS. برنامه macOS را برای CodeQL روی Blacksmith macOS به‌صورت دستی build می‌کند، نتایج build وابستگی‌ها را از SARIF بارگذاری‌شده فیلتر می‌کند، و خروجی را زیر `/codeql-critical-security/macos` بارگذاری می‌کند. خارج از پیش‌فرض‌های روزانه نگه داشته شده، چون build macOS حتی در حالت تمیز هم بر زمان اجرا غالب است.
### دسته‌های کیفیت بحرانی
`CodeQL Critical Quality` شارد غیرامنیتی متناظر است. فقط پرس‌وجوهای کیفیت JavaScript/TypeScript با شدت خطا و غیرامنیتی را روی سطوح محدود و باارزش بالا روی رانر کوچک‌تر Blacksmith Linux اجرا می‌کند. محافظ pull request آن عمداً کوچک‌تر از پروفایل زمان‌بندی‌شده است: PRهای غیرپیش‌نویس فقط شاردهای متناظر `agent-runtime-boundary`، `config-boundary`، `core-auth-secrets`، `channel-runtime-boundary`، `gateway-runtime-boundary`، `memory-runtime-boundary`، `mcp-process-runtime-boundary`، `provider-runtime-boundary`، `session-diagnostics-boundary`، `plugin-boundary`، `plugin-sdk-package-contract`، و `plugin-sdk-reply-runtime` را برای تغییرات کد اجرای command/model/tool و dispatch پاسخ agent، کد schema/migration/IO پیکربندی، کد auth/secrets/sandbox/security، runtime کانال core و Plugin کانال بسته‌بندی‌شده، protocol/server-method مربوط به Gateway، runtime/SDK glue مربوط به memory، MCP/process/outbound delivery، runtime/catalog مدل provider، session diagnostics/delivery queues، loader مربوط به Plugin، قرارداد Plugin SDK/package، یا runtime پاسخ Plugin SDK اجرا می‌کنند. تغییرات پیکربندی CodeQL و گردش‌کار کیفیت، هر دوازده شارد کیفیت PR را اجرا می‌کنند.
`CodeQL Critical Quality` shard غیرامنیتی متناظر است. فقط queryهای کیفیت JavaScript/TypeScript غیرامنیتی با شدت خطا را روی سطوح باریک و باارزش بالا، روی runner لینوکسی کوچک‌تر Blacksmith اجرا می‌کند. محافظ pull request آن عمداً کوچک‌تر از پروفایل زمان‌بندی‌شده است: PRهای غیرپیش‌نویس فقط shardهای متناظر `agent-runtime-boundary`، `config-boundary`، `core-auth-secrets`، `channel-runtime-boundary`، `gateway-runtime-boundary`، `memory-runtime-boundary`، `mcp-process-runtime-boundary`، `provider-runtime-boundary`، `session-diagnostics-boundary`، `plugin-boundary`، `plugin-sdk-package-contract`، و `plugin-sdk-reply-runtime` را برای کد اجرای فرمان/مدل/ابزار agent و dispatch پاسخ، schema/migration/IO پیکربندی، کد auth/secrets/sandbox/security، هسته کانال و runtime مربوط به channel plugin بسته‌بندی‌شده، پروتکل Gateway/server-method، چسب runtime/SDK حافظه، MCP/process/تحویل خروجی، runtime/provider catalog مدل، diagnostics جلسه/صف‌های تحویل، loader Plugin، قرارداد Plugin SDK/package، یا تغییرات runtime پاسخ Plugin SDK اجرا می‌کنند. تغییرات CodeQL config و گردش‌کار کیفیت هر دوازده shard کیفیت PR را اجرا می‌کنند.
dispatch دستی می‌پذیرد:
@ -422,40 +415,40 @@ dispatch دستی می‌پذیرد:
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
```
پروفایل‌های محدود، قلاب‌های آموزش/تکرار برای اجرای یک شارد کیفیت به‌صورت جداگانه هستند.
پروفایل‌های باریک hookهای آموزش/تکرار برای اجرای یک shard کیفیت به‌صورت جداگانه هستند.
| دسته | سطح |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | کد مرز امنیتی Auth، secrets، sandbox، cron، و gateway |
| `/codeql-critical-quality/config-boundary` | قراردادهای schema، migration، normalization، و IO پیکربندی |
| `/codeql-critical-quality/gateway-runtime-boundary` | schemaهای protocol مربوط به Gateway و قراردادهای server method |
| `/codeql-critical-quality/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال core و Plugin کانال بسته‌بندی‌شده |
| `/codeql-critical-quality/agent-runtime-boundary` | اجرای command، dispatch مربوط به model/provider، dispatch و queueهای auto-reply، و قراردادهای runtime صفحهٔ کنترل ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | سرورهای MCP و پل‌های ابزار، کمک‌کننده‌های نظارت بر فرایند، و قراردادهای تحویل خروجی |
| `/codeql-critical-quality/memory-runtime-boundary` | Memory host SDK، facadeهای runtime حافظه، aliasهای Plugin SDK حافظه، glue فعال‌سازی runtime حافظه، و commandهای doctor حافظه |
| `/codeql-critical-quality/session-diagnostics-boundary` | اجزای داخلی reply queue، queueهای تحویل session، کمک‌کننده‌های binding/delivery نشست خروجی، سطوح diagnostic event/log bundle، و قراردادهای CLI مربوط به session doctor |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | dispatch پاسخ ورودی Plugin SDK، کمک‌کننده‌های reply payload/chunking/runtime، گزینه‌های پاسخ کانال، queueهای تحویل، و کمک‌کننده‌های binding نشست/thread |
| `/codeql-critical-quality/provider-runtime-boundary` | normalization کاتالوگ مدل، auth و discovery مربوط به provider، ثبت runtime مربوط به provider، defaults/catalogs مربوط به provider، و registryهای web/search/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | راه‌اندازی Control UI، persistence محلی، جریان‌های کنترل Gateway، و قراردادهای runtime صفحهٔ کنترل task |
| `/codeql-critical-quality/web-media-runtime-boundary` | قراردادهای runtime مربوط به fetch/search وب core، IO رسانه، فهم رسانه، تولید تصویر، و تولید رسانه |
| `/codeql-critical-quality/plugin-boundary` | قراردادهای loader، registry، public-surface، و entrypointهای Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | منبع منتشرشدهٔ Plugin SDK در سمت بسته و کمک‌کننده‌های قرارداد بستهٔ Plugin |
| `/codeql-critical-quality/core-auth-secrets` | کد مرز امنیتی Auth، secrets، sandbox، Cron، و Gateway |
| `/codeql-critical-quality/config-boundary` | قراردادهای schema پیکربندی، migration، نرمال‌سازی، و IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | schemaهای پروتکل Gateway و قراردادهای server method |
| `/codeql-critical-quality/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال هسته و channel pluginهای بسته‌بندی‌شده |
| `/codeql-critical-quality/agent-runtime-boundary` | اجرای فرمان، dispatch مدل/provider، dispatch و صف‌های auto-reply، و قراردادهای runtime صفحه کنترل ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | سرورهای MCP و پل‌های ابزار، helperهای نظارت بر فرایند، و قراردادهای تحویل خروجی |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK میزبان حافظه، facadeهای runtime حافظه، aliasهای Plugin SDK حافظه، چسب فعال‌سازی runtime حافظه، و فرمان‌های doctor حافظه |
| `/codeql-critical-quality/session-diagnostics-boundary` | بخش‌های داخلی صف پاسخ، صف‌های تحویل جلسه، helperهای اتصال/تحویل جلسه خروجی، سطوح diagnostic event/log bundle، و قراردادهای CLI مربوط به session doctor |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | dispatch پاسخ ورودی Plugin SDK، helperهای payload/chunking/runtime پاسخ، گزینه‌های پاسخ کانال، صف‌های تحویل، و helperهای اتصال session/thread |
| `/codeql-critical-quality/provider-runtime-boundary` | نرمال‌سازی catalog مدل، auth و discovery provider، ثبت runtime provider، پیش‌فرض‌ها/catalogهای provider، و registryهای web/search/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | راه‌اندازی Control UI، persistence محلی، جریان‌های کنترل Gateway، و قراردادهای runtime صفحه کنترل task |
| `/codeql-critical-quality/web-media-runtime-boundary` | قراردادهای runtime مربوط به fetch/search وب هسته، media IO، درک رسانه، تولید تصویر، و تولید رسانه |
| `/codeql-critical-quality/plugin-boundary` | قراردادهای loader، registry، public-surface، و entrypointهای Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | منبع Plugin SDK سمت package منتشرشده و helperهای قرارداد package مربوط به plugin |
کیفیت از امنیت جدا می‌ماند تا یافته‌های کیفیت بتوانند بدون مبهم‌کردن سیگنال امنیتی زمان‌بندی، اندازه‌گیری، غیرفعال یا گسترش داده شوند. گسترش CodeQL برای Swift، Python، و Pluginهای بسته‌بندی‌شده فقط پس از پایدار شدن runtime و سیگنال پروفایل‌های محدود باید دوباره به‌عنوان کار پیگیری scoped یا sharded اضافه شود.
کیفیت از امنیت جدا می‌ماند تا یافته‌های کیفیت بتوانند بدون پنهان‌کردن سیگنال امنیتی زمان‌بندی، اندازه‌گیری، غیرفعال، یا گسترش داده شوند. گسترش CodeQL برای Swift، Python، و pluginهای بسته‌بندی‌شده باید فقط پس از پایدار شدن runtime و سیگنال پروفایل‌های باریک، به‌صورت کار پیگیری scopeشده یا shardشده دوباره اضافه شود.
## گردش‌کارهای نگهداشت
## گردش‌کارهای نگهداری
### Docs Agent
### عامل مستندات
گردش‌کار `Docs Agent` یک مسیر نگهداشت Codex رویدادمحور برای همسو نگه‌داشتن اسناد موجود با تغییرات اخیراً land شده است. زمان‌بندی خالص ندارد: یک اجرای CI موفق از push غیرربات روی `main` می‌تواند آن را trigger کند، و dispatch دستی می‌تواند مستقیماً آن را اجرا کند. فراخوانی‌های workflow-run وقتی `main` جلو رفته باشد یا وقتی اجرای Docs Agent غیر skip شدهٔ دیگری در یک ساعت گذشته ساخته شده باشد، skip می‌شوند. وقتی اجرا می‌شود، بازهٔ commit را از SHA منبع قبلیِ Docs Agent غیر skip شده تا `main` فعلی بررسی می‌کند، بنابراین یک اجرای ساعتی می‌تواند همهٔ تغییرات main انباشته‌شده از آخرین گذر اسناد را پوشش دهد.
گردش‌کار `Docs Agent` یک مسیر نگهداری event-driven با Codex برای هم‌راستا نگه‌داشتن مستندات موجود با تغییراتی است که اخیراً landing شده‌اند. برنامه زمان‌بندی خالص ندارد: یک اجرای موفق CI مربوط به push غیررباتی روی `main` می‌تواند آن را trigger کند، و dispatch دستی می‌تواند مستقیماً آن را اجرا کند. invocationهای workflow-run وقتی `main` جلو رفته باشد یا وقتی اجرای غیر skipشده دیگری از Docs Agent در ساعت گذشته ایجاد شده باشد skip می‌شوند. وقتی اجرا می‌شود، بازه commit از source SHA مربوط به Docs Agent غیر skipشده قبلی تا `main` فعلی را review می‌کند، بنابراین یک اجرای ساعتی می‌تواند همه تغییرات main انباشته‌شده از آخرین گذر مستندات را پوشش دهد.
### Test Performance Agent
### عامل عملکرد تست
گردش‌کار `Test Performance Agent` یک مسیر نگهداشت Codex رویدادمحور برای تست‌های کند است. زمان‌بندی خالص ندارد: یک اجرای CI موفق از push غیرربات روی `main` می‌تواند آن را trigger کند، اما اگر فراخوانی workflow-run دیگری در همان روز UTC قبلاً اجرا شده باشد یا در حال اجرا باشد، skip می‌شود. dispatch دستی این دروازهٔ فعالیت روزانه را دور می‌زند. این مسیر یک گزارش عملکرد Vitest گروه‌بندی‌شدهٔ مجموعهٔ کامل می‌سازد، به Codex اجازه می‌دهد فقط اصلاحات کوچک عملکرد تست که coverage را حفظ می‌کنند انجام دهد، نه refactorهای گسترده، سپس گزارش مجموعهٔ کامل را دوباره اجرا می‌کند و تغییراتی را که تعداد تست‌های پاس‌شدهٔ baseline را کاهش دهند رد می‌کند. اگر baseline تست‌های شکست‌خورده داشته باشد، Codex فقط می‌تواند شکست‌های آشکار را اصلاح کند و گزارش مجموعهٔ کامل پس از agent باید قبل از commit شدن هر چیزی پاس شود. وقتی `main` پیش از land شدن bot push جلو می‌رود، این مسیر patch اعتبارسنجی‌شده را rebase می‌کند، `pnpm check:changed` را دوباره اجرا می‌کند، و push را retry می‌کند؛ patchهای کهنهٔ دارای conflict skip می‌شوند. از Ubuntu میزبانی‌شده توسط GitHub استفاده می‌کند تا action مربوط به Codex بتواند همان وضعیت ایمنی drop-sudo را مثل docs agent حفظ کند.
گردش‌کار `Test Performance Agent` یک مسیر نگهداری event-driven با Codex برای تست‌های کند است. برنامه زمان‌بندی خالص ندارد: یک اجرای موفق CI مربوط به push غیررباتی روی `main` می‌تواند آن را trigger کند، اما اگر invocation دیگری از workflow-run در همان روز UTC قبلاً اجرا شده باشد یا در حال اجرا باشد، skip می‌شود. dispatch دستی آن gate فعالیت روزانه را دور می‌زند. این مسیر یک گزارش عملکرد Vitest گروه‌بندی‌شده برای کل suite می‌سازد، به Codex اجازه می‌دهد فقط اصلاحات کوچک عملکرد تست با حفظ پوشش انجام دهد نه refactorهای گسترده، سپس گزارش کل suite را دوباره اجرا می‌کند و تغییراتی را که تعداد baseline تست‌های موفق را کاهش دهند رد می‌کند. اگر baseline تست‌های ناموفق داشته باشد، Codex فقط می‌تواند failureهای بدیهی را اصلاح کند و گزارش کل suite پس از agent باید پیش از هر commit موفق شود. وقتی `main` پیش از landing شدن push ربات جلو می‌رود، این مسیر patch اعتبارسنجی‌شده را rebase می‌کند، `pnpm check:changed` را دوباره اجرا می‌کند، و push را retry می‌کند؛ patchهای stale دارای conflict skip می‌شوند. از GitHub-hosted Ubuntu استفاده می‌کند تا action مربوط به Codex بتواند همان وضعیت ایمنی drop-sudo را مثل عامل مستندات حفظ کند.
### PRهای تکراری پس از Merge
### PRهای تکراری پس از ادغام
گردش‌کار `Duplicate PRs After Merge` یک گردش‌کار دستی maintainer برای پاک‌سازی تکراری‌ها پس از land است. پیش‌فرض آن dry-run است و فقط وقتی `apply=true` باشد PRهای صراحتاً فهرست‌شده را می‌بندد. پیش از تغییر GitHub، بررسی می‌کند که PR land شده merge شده باشد و هر تکراری یا issue ارجاع‌شدهٔ مشترک داشته باشد یا hunkهای تغییر یافتهٔ همپوشان.
گردش‌کار `Duplicate PRs After Merge` یک گردش‌کار دستی maintainer برای پاک‌سازی duplicate پس از land است. پیش‌فرض آن dry-run است و فقط وقتی `apply=true` باشد PRهای صراحتاً فهرست‌شده را می‌بندد. پیش از تغییر دادن GitHub، تأیید می‌کند که PR landشده merge شده و هر duplicate یا issue ارجاع‌شده مشترک دارد یا hunkهای تغییر یافته هم‌پوشان دارد.
```bash
gh workflow run duplicate-after-merge.yml \
@ -464,38 +457,115 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## دروازه‌های بررسی محلی و مسیریابی تغییرات
## gateهای check محلی و مسیریابی تغییرات
منطق changed-lane محلی در `scripts/changed-lanes.mjs` قرار دارد و توسط `scripts/check-changed.mjs` اجرا می‌شود. آن دروازهٔ بررسی محلی نسبت به دامنهٔ پلتفرم CI گسترده، دربارهٔ مرزهای معماری سخت‌گیرتر است:
منطق changed-lane محلی در `scripts/changed-lanes.mjs` قرار دارد و توسط `scripts/check-changed.mjs` اجرا می‌شود. آن gate check محلی نسبت به scope گسترده پلتفرم CI درباره مرزهای معماری سخت‌گیرتر است:
- تغییرات production مربوط به core، typecheck تولید core و تست core به‌علاوه lint/guardهای core را اجرا می‌کنند؛
- تغییرات فقط تست مربوط به core، فقط typecheck تست core به‌علاوه lint core را اجرا می‌کنند؛
- تغییرات production مربوط به extension، typecheck تولید extension و تست extension به‌علاوه lint extension را اجرا می‌کنند؛
- تغییرات فقط تست مربوط به extension، typecheck تست extension به‌علاوه lint extension را اجرا می‌کنند؛
- تغییرات public Plugin SDK یا plugin-contract به typecheck مربوط به extension گسترش می‌یابند چون extensionها به آن قراردادهای core وابسته‌اند (پیمایش‌های extension با Vitest کار تست صریح می‌مانند)؛
- افزایش نسخه‌های فقط metadata انتشار، بررسی‌های هدفمند version/config/root-dependency را اجرا می‌کنند؛
- تغییرات ناشناختهٔ root/config برای fail-safe به همهٔ مسیرهای بررسی می‌روند.
- تغییرات production هسته، typecheck مربوط به core prod و core test به‌علاوه lint/guardهای هسته را اجرا می‌کنند؛
- تغییرات فقط-test هسته، فقط typecheck مربوط به core test به‌علاوه lint هسته را اجرا می‌کنند؛
- تغییرات production extension، typecheck مربوط به extension prod و extension test به‌علاوه lint extension را اجرا می‌کنند؛
- تغییرات فقط-test extension، typecheck مربوط به extension test به‌علاوه lint extension را اجرا می‌کنند؛
- تغییرات Plugin SDK عمومی یا قرارداد plugin به typecheck extension گسترش می‌یابند، چون extensionها به آن قراردادهای هسته وابسته‌اند (پایش‌های Vitest extension همچنان کار تست صریح می‌مانند)؛
- افزایش نسخه‌های فقط metadata انتشار، checkهای هدفمند version/config/root-dependency را اجرا می‌کنند؛
- تغییرات ناشناخته root/config برای fail-safe به همه check laneها می‌روند.
مسیریابی changed-test محلی در `scripts/test-projects.test-support.mjs` قرار دارد و عمداً ارزان‌تر از `check:changed` است: ویرایش‌های مستقیم تست خودشان را اجرا می‌کنند، ویرایش‌های منبع ابتدا mappingهای صریح را ترجیح می‌دهند، سپس تست‌های sibling و وابستگان import-graph را. پیکربندی تحویل shared group-room یکی از mappingهای صریح است: تغییرات در پیکربندی پاسخ قابل‌مشاهدهٔ گروه، حالت تحویل پاسخ منبع، یا مسیر message-tool system prompt از تست‌های پاسخ core به‌علاوه regressionهای تحویل Discord و Slack عبور می‌کنند تا تغییر پیش‌فرض مشترک پیش از اولین push مربوط به PR شکست بخورد. فقط وقتی تغییر آن‌قدر harness-wide است که مجموعهٔ mapped ارزان proxy قابل‌اعتمادی نیست، از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید.
مسیریابی changed-test محلی در `scripts/test-projects.test-support.mjs` قرار دارد و عمداً ارزان‌تر از `check:changed` است: ویرایش مستقیم تست‌ها خودشان را اجرا می‌کنند، ویرایش‌های source ابتدا mappingهای صریح را ترجیح می‌دهند، سپس تست‌های sibling و وابستگان import-graph را. پیکربندی تحویل shared group-room یکی از mappingهای صریح است: تغییرات در پیکربندی visible-reply گروه، حالت تحویل پاسخ source، یا system prompt ابزار پیام، از طریق تست‌های پاسخ هسته به‌علاوه regressionهای تحویل Discord و Slack مسیر داده می‌شوند تا تغییر پیش‌فرض مشترک پیش از اولین push PR شکست بخورد. فقط وقتی از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید که تغییر آن‌قدر harness-wide باشد که مجموعه mapped ارزان نماینده قابل اعتمادی نباشد.
## اعتبارسنجی Testbox
Testbox را از ریشهٔ مخزن اجرا کنید و برای اثبات گسترده، یک باکس تازه و از پیش گرم‌شده را ترجیح دهید. پیش از صرف کردن یک گیت کند روی باکسی که دوباره استفاده شده، منقضی شده، یا همین حالا همگام‌سازی غیرمنتظره بزرگی گزارش کرده است، ابتدا `pnpm testbox:sanity` را داخل باکس اجرا کنید.
Testbox را از ریشهٔ مخزن اجرا کنید و برای اثبات‌های گسترده، یک جعبهٔ تازه گرم‌شده را ترجیح دهید. پیش از صرف‌کردن یک گیت کند روی جعبه‌ای که دوباره استفاده شده، منقضی شده، یا همین حالا همگام‌سازیِ غیرمنتظره بزرگی گزارش کرده است، ابتدا `pnpm testbox:sanity` را داخل جعبه اجرا کنید.
بررسی سلامت وقتی فایل‌های ریشهٔ لازم مانند `pnpm-lock.yaml` ناپدید شده باشند، یا وقتی `git status --short` دست‌کم ۲۰۰ حذفِ رهگیری‌شده را نشان دهد، سریع شکست می‌خورد. این معمولا یعنی وضعیت همگام‌سازی ریموت یک کپی قابل اعتماد از PR نیست؛ آن باکس را متوقف کنید و به‌جای اشکال‌زدایی شکست تست محصول، یک باکس تازه را گرم کنید. برای PRهایی که حذف‌های بزرگ عمدی دارند، برای آن اجرای سلامت `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` را تنظیم کنید.
بررسی سلامت وقتی فایل‌های ضروری ریشه مانند `pnpm-lock.yaml` ناپدید شده باشند یا وقتی `git status --short` دست‌کم ۲۰۰ حذفِ ردیابی‌شده نشان دهد، سریع شکست می‌خورد. این معمولاً یعنی وضعیت همگام‌سازی راه‌دور، کپی قابل اعتمادی از PR نیست؛ به‌جای اشکال‌زدایی شکست آزمون محصول، آن جعبه را متوقف کنید و یک جعبهٔ تازه گرم کنید. برای PRهای بزرگ‌حذفِ عمدی، برای همان اجرای سلامت `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` را تنظیم کنید.
`pnpm testbox:run` همچنین یک فراخوانی محلی Blacksmith CLI را که بیش از پنج دقیقه بدون خروجی پس از همگام‌سازی در مرحلهٔ همگام‌سازی بماند، پایان می‌دهد. برای غیرفعال کردن این محافظ، `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` را تنظیم کنید، یا برای diffهای محلی غیرمعمول بزرگ از یک مقدار بزرگ‌تر بر حسب میلی‌ثانیه استفاده کنید.
`pnpm testbox:run` همچنین فراخوانی محلی Blacksmith CLI را که بیش از پنج دقیقه بدون خروجی پس از همگام‌سازی در مرحلهٔ همگام‌سازی می‌ماند، پایان می‌دهد. برای غیرفعال‌کردن آن محافظ، `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` را تنظیم کنید، یا برای diffهای محلی غیرمعمولاً بزرگ، مقدار میلی‌ثانیه‌ای بزرگ‌تری به کار ببرید.
Crabbox مسیر دومِ باکس ریموتِ متعلق به مخزن برای اثبات Linux است، وقتی Blacksmith در دسترس نیست یا وقتی ظرفیت ابریِ تحت مالکیت ترجیح داده می‌شود. یک باکس را گرم کنید، آن را از طریق گردش‌کار پروژه آماده کنید، سپس دستورها را از طریق Crabbox CLI اجرا کنید:
Crabbox پوشش جعبهٔ راه‌دورِ متعلق به مخزن برای اثبات لینوکس نگه‌دارندگان است. وقتی یک بررسی برای حلقهٔ ویرایش محلی بیش از حد گسترده است، وقتی هم‌ارزی CI مهم است، یا وقتی اثبات به secrets، Docker، مسیرهای بسته، جعبه‌های قابل استفادهٔ مجدد، یا گزارش‌های راه‌دور نیاز دارد، از آن استفاده کنید. backend عادی OpenClaw برابر `blacksmith-testbox` است؛ ظرفیت AWS/Hetzner تحت مالکیت، پشتیبانِ قطعی‌های Blacksmith، مشکلات سهمیه، یا آزمون صریح ظرفیت تحت مالکیت است.
پیش از نخستین اجرا، پوشش را از ریشهٔ مخزن بررسی کنید:
```bash
pnpm crabbox:warmup -- --idle-timeout 90m
pnpm crabbox:hydrate -- --id <cbx_id>
pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed"
pnpm crabbox:stop -- <cbx_id>
pnpm crabbox:run -- --help | sed -n '1,120p'
```
`.crabbox.yaml` مالک پیش‌فرض‌های ارائه‌دهنده، همگام‌سازی، و آماده‌سازی GitHub Actions است. این فایل `.git` محلی را مستثنا می‌کند تا checkout آماده‌شدهٔ Actions به‌جای همگام‌سازی ریموت‌ها و انبارهای آبجکت محلیِ نگه‌دارنده، فرادادهٔ Git ریموت خودش را حفظ کند، و آرتیفکت‌های محلی runtime/build را که هرگز نباید منتقل شوند مستثنا می‌کند. `.github/workflows/crabbox-hydrate.yml` مالک checkout، راه‌اندازی Node/pnpm، دریافت `origin/main`، و تحویل محیط غیرمحرمانه‌ای است که دستورهای بعدی `crabbox run --id <cbx_id>` از آن source می‌کنند.
پوشش مخزن، دودویی Crabbox کهنه‌ای را که `blacksmith-testbox` را اعلام نمی‌کند رد می‌کند. با اینکه `.crabbox.yaml` پیش‌فرض‌های ابرِ تحت مالکیت دارد، ارائه‌دهنده را صریحاً پاس دهید.
گیت تغییرات:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
--blacksmith-org openclaw \
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
--blacksmith-job check \
--blacksmith-ref main \
--idle-timeout 90m \
--ttl 240m \
--timing-json \
--shell -- \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
```
اجرای دوبارهٔ آزمون متمرکز:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
--blacksmith-org openclaw \
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
--blacksmith-job check \
--blacksmith-ref main \
--idle-timeout 90m \
--ttl 240m \
--timing-json \
--shell -- \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>"
```
مجموعهٔ کامل:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
--blacksmith-org openclaw \
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
--blacksmith-job check \
--blacksmith-ref main \
--idle-timeout 90m \
--ttl 240m \
--timing-json \
--shell -- \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
```
خلاصهٔ نهایی JSON را بخوانید. فیلدهای مفید `provider`، `leaseId`، `syncDelegated`، `exitCode`، `commandMs` و `totalMs` هستند. اجراهای یک‌بارهٔ Crabbox با پشتوانهٔ Blacksmith باید Testbox را به‌طور خودکار متوقف کنند؛ اگر اجرا قطع شد یا پاک‌سازی نامشخص بود، جعبه‌های زنده را بررسی کنید و فقط جعبه‌هایی را که خودتان ساخته‌اید متوقف کنید:
```bash
blacksmith testbox list
blacksmith testbox stop --id <tbx_id>
```
فقط وقتی استفادهٔ مجدد را به کار ببرید که عمداً به چند فرمان روی همان جعبهٔ آماده‌شده نیاز دارید:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
pnpm crabbox:stop -- <tbx_id>
```
اگر لایهٔ خراب Crabbox است اما خود Blacksmith کار می‌کند، از Blacksmith مستقیم به‌عنوان پشتیبان محدود استفاده کنید:
```bash
blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
blacksmith testbox stop --id <tbx_id>
```
فقط وقتی به ظرفیت Crabbox تحت مالکیت ارتقا دهید که Blacksmith از کار افتاده، با محدودیت سهمیه روبه‌رو است، محیط لازم را ندارد، یا ظرفیت تحت مالکیت صراحتاً هدف است:
```bash
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
pnpm crabbox:hydrate -- --id <cbx_id-or-slug>
pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
pnpm crabbox:stop -- <cbx_id-or-slug>
```
`.crabbox.yaml` مالک پیش‌فرض‌های ارائه‌دهنده، همگام‌سازی، و آماده‌سازی GitHub Actions برای مسیرهای ابرِ تحت مالکیت است. این فایل `.git` محلی را مستثنی می‌کند تا checkout آماده‌شدهٔ Actions فرادادهٔ Git راه‌دور خودش را نگه دارد، نه اینکه remoteهای محلی نگه‌دارنده و انباره‌های object را همگام کند؛ همچنین artifactهای runtime/build محلی را که هرگز نباید منتقل شوند مستثنی می‌کند. `.github/workflows/crabbox-hydrate.yml` مالک checkout، راه‌اندازی Node/pnpm، دریافت `origin/main`، و تحویل محیط غیرمحرمانه برای فرمان‌های ابرِ تحت مالکیت `crabbox run --id <cbx_id>` است.
## مرتبط

189
docs/fa/cli/plugins.md
View File

@ -1,20 +1,20 @@
---
read_when:
- می‌خواهید Pluginهای Gateway یا بسته‌های سازگار را نصب یا مدیریت کنید
- می‌خواهید Plugin‌های Gateway یا بسته‌های سازگار را نصب یا مدیریت کنید
- می‌خواهید خطاهای بارگذاری Plugin را اشکال‌زدایی کنید
sidebarTitle: Plugins
summary: مرجع CLI برای `openclaw plugins` (list، install، marketplace، uninstall، enable/disable، doctor)
title: Plugin‌ها
title: Pluginها
x-i18n:
generated_at: "2026-05-03T21:28:58Z"
generated_at: "2026-05-04T07:03:00Z"
model: gpt-5.5
provider: openai
source_hash: d854d052b0a012a86f9c775775676a9a8fe8ae86b2c38a18118f1abf0732174c
source_hash: 36ae7edb12986ead7e126f25e0761bf312b2644b35017181b674082105886776
source_path: cli/plugins.md
workflow: 16
---
مدیریت Pluginهای Gateway، بسته‌های hook و باندل‌های سازگار.
Pluginهای Gateway، بسته‌های hook و bundleهای سازگار را مدیریت کنید.
<CardGroup cols={2}>
<Card title="سامانه Plugin" href="/fa/tools/plugin">
@ -23,14 +23,14 @@ x-i18n:
<Card title="مدیریت Pluginها" href="/fa/plugins/manage-plugins">
نمونه‌های سریع برای نصب، فهرست‌کردن، به‌روزرسانی، حذف نصب و انتشار.
</Card>
<Card title="باندل‌های Plugin" href="/fa/plugins/bundles">
مدل سازگاری باندل.
<Card title="bundleهای Plugin" href="/fa/plugins/bundles">
مدل سازگاری bundle.
</Card>
<Card title="مانیفست Plugin" href="/fa/plugins/manifest">
فیلدهای مانیفست و شِمای پیکربندی.
</Card>
<Card title="امنیت" href="/fa/gateway/security">
سخت‌سازی امنیتی برای نصب Pluginها.
مقاوم‌سازی امنیتی برای نصب Pluginها.
</Card>
</CardGroup>
@ -62,14 +62,14 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
برای بررسی نصب، inspect، حذف نصب یا تازه‌سازی رجیستری که کند است، فرمان را با `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` اجرا کنید. trace زمان‌بندی فازها را در stderr می‌نویسد و خروجی JSON را قابل تجزیه نگه می‌دارد. [عیب‌یابی](/fa/help/debugging#plugin-lifecycle-trace) را ببینید.
برای بررسی نصب، inspect، حذف نصب یا تازه‌سازی registry که کند است، فرمان را با `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` اجرا کنید. trace زمان‌بندی فازها را در stderr می‌نویسد و خروجی JSON را قابل parse نگه می‌دارد. [اشکال‌زدایی](/fa/help/debugging#plugin-lifecycle-trace) را ببینید.
<Note>
Pluginهای همراه با OpenClaw همراه محصول ارائه می‌شوند. برخی به‌صورت پیش‌فرض فعال هستند (برای مثال ارائه‌دهندگان مدل همراه، ارائه‌دهندگان گفتار همراه، و Plugin مرورگر همراه)؛ بقیه به `plugins enable` نیاز دارند.
Pluginهای bundled همراه OpenClaw ارائه می‌شوند. برخی به‌صورت پیش‌فرض فعال هستند (برای مثال providerهای مدل bundled، providerهای گفتار bundled و Plugin مرورگر bundled)؛ بقیه به `plugins enable` نیاز دارند.
Pluginهای بومی OpenClaw باید `openclaw.plugin.json` را همراه یک JSON Schema درون‌خطی (`configSchema`، حتی اگر خالی باشد) ارائه کنند. باندل‌های سازگار به‌جای آن از مانیفست‌های باندل خودشان استفاده می‌کنند.
Pluginهای native OpenClaw باید `openclaw.plugin.json` را با یک JSON Schema درون‌خطی (`configSchema`، حتی اگر خالی باشد) ارائه کنند. bundleهای سازگار به‌جای آن از مانیفست‌های bundle خودشان استفاده می‌کنند.
`plugins list` مقدار `Format: openclaw` یا `Format: bundle` را نشان می‌دهد. خروجی مفصل list/info همچنین زیرنوع باندل (`codex`، `claude` یا `cursor`) به‌علاوه قابلیت‌های شناسایی‌شده باندل را نشان می‌دهد.
`plugins list` مقدار `Format: openclaw` یا `Format: bundle` را نشان می‌دهد. خروجی verbose فهرست/اطلاعات همچنین زیرگونه bundle (`codex`، `claude` یا `cursor`) به‌همراه قابلیت‌های bundle شناسایی‌شده را نشان می‌دهد.
</Note>
### نصب
@ -91,100 +91,100 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
```
<Warning>
در دوره گذار راه‌اندازی، نام‌های ساده بسته به‌صورت پیش‌فرض از npm نصب می‌شوند. برای ClawHub از `clawhub:<package>` استفاده کنید. نصب Plugin را مانند اجرای کد در نظر بگیرید. نسخه‌های پین‌شده را ترجیح دهید.
نام‌های ساده package در دوره جابه‌جایی launch به‌صورت پیش‌فرض از npm نصب می‌شوند. برای ClawHub از `clawhub:<package>` استفاده کنید. نصب Plugin را مثل اجرای کد در نظر بگیرید. نسخه‌های pinned را ترجیح دهید.
</Warning>
`plugins search` برای بسته‌های Plugin قابل نصب، ClawHub را جست‌وجو می‌کند و نام بسته‌های آماده نصب را چاپ می‌کند. این فرمان بسته‌های code-plugin و bundle-plugin را جست‌وجو می‌کند، نه Skills را. برای Skills در ClawHub از `openclaw skills search` استفاده کنید.
`plugins search` برای packageهای Plugin قابل نصب از ClawHub پرس‌وجو می‌کند و نام‌های package آماده نصب را چاپ می‌کند. این فرمان packageهای code-plugin و bundle-plugin را جست‌وجو می‌کند، نه skills را. برای Skills در ClawHub از `openclaw skills search` استفاده کنید.
<Note>
ClawHub سطح اصلی توزیع و کشف برای بیشتر Pluginها است. Npm همچنان یک مسیر fallback پشتیبانی‌شده و مسیر نصب مستقیم است. بسته‌های Plugin متعلق به OpenClaw با الگوی `@openclaw/*` دوباره روی npm منتشر می‌شوند؛ فهرست فعلی را در [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) یا [فهرست موجودی Plugin](/fa/plugins/plugin-inventory) ببینید. نصب‌های پایدار از `latest` استفاده می‌کنند. نصب‌ها و به‌روزرسانی‌های کانال beta، وقتی npm dist-tag با نام `beta` در دسترس باشد آن را ترجیح می‌دهند و سپس به `latest` برمی‌گردند.
ClawHub سطح اصلی توزیع و کشف برای بیشتر Pluginها است. npm همچنان یک fallback پشتیبانی‌شده و مسیر نصب مستقیم باقی می‌ماند. packageهای Plugin متعلق به OpenClaw با الگوی `@openclaw/*` دوباره روی npm منتشر می‌شوند؛ فهرست فعلی را در [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) یا [موجودی Plugin](/fa/plugins/plugin-inventory) ببینید. نصب‌های پایدار از `latest` استفاده می‌کنند. نصب‌ها و به‌روزرسانی‌های کانال beta وقتی tag در دسترس باشد، dist-tag مربوط به `beta` در npm را ترجیح می‌دهند و سپس به `latest` fallback می‌کنند.
</Note>
<AccordionGroup>
<Accordion title="includeهای پیکربندی و تعمیر پیکربندی نامعتبر">
اگر بخش `plugins` شما با یک `$include` تک‌فایلی پشتیبانی می‌شود، `plugins install/update/enable/disable/uninstall` تغییرات را در همان فایل includeشده می‌نویسد و `openclaw.json` را دست‌نخورده می‌گذارد. includeهای ریشه، آرایه‌های include و includeهایی با overrideهای هم‌سطح، به‌جای تخت‌سازی با حالت fail closed متوقف می‌شوند. برای شکل‌های پشتیبانی‌شده [includeهای پیکربندی](/fa/gateway/configuration) را ببینید.
<Accordion title="Config includes و ترمیم پیکربندی نامعتبر">
اگر بخش `plugins` شما با یک `$include` تک‌فایلی پشتیبانی می‌شود، `plugins install/update/enable/disable/uninstall` در همان فایل includeشده می‌نویسد و `openclaw.json` را دست‌نخورده باقی می‌گذارد. includeهای ریشه، آرایه‌های include و includeهایی با overrideهای هم‌سطح به‌جای flatten شدن، fail closed می‌شوند. برای شکل‌های پشتیبانی‌شده، [Config includes](/fa/gateway/configuration) را ببینید.
اگر پیکربندی هنگام نصب نامعتبر باشد، `plugins install` معمولاً با حالت fail closed متوقف می‌شود و به شما می‌گوید ابتدا `openclaw doctor --fix` را اجرا کنید. هنگام راه‌اندازی Gateway و بارگذاری مجدد داغ، پیکربندی نامعتبر Plugin مانند هر پیکربندی نامعتبر دیگری با حالت fail closed متوقف می‌شود؛ `openclaw doctor --fix` می‌تواند ورودی نامعتبر Plugin را قرنطینه کند. تنها استثنای مستند در زمان نصب، مسیر بازیابی محدودی برای Pluginهای همراه است که صراحتاً `openclaw.install.allowInvalidConfigRecovery` را فعال کرده‌اند.
اگر پیکربندی هنگام نصب نامعتبر باشد، `plugins install` معمولاً fail closed می‌شود و به شما می‌گوید ابتدا `openclaw doctor --fix` را اجرا کنید. هنگام راه‌اندازی Gateway و hot reload، پیکربندی نامعتبر Plugin مانند هر پیکربندی نامعتبر دیگر fail closed می‌شود؛ `openclaw doctor --fix` می‌تواند ورودی نامعتبر Plugin را قرنطینه کند. تنها استثنای مستندشده در زمان نصب، یک مسیر بازیابی محدود برای Pluginهای bundled است که صراحتاً `openclaw.install.allowInvalidConfigRecovery` را opt in می‌کنند.
</Accordion>
<Accordion title="--force و نصب مجدد در برابر به‌روزرسانی">
`--force` هدف نصب موجود را دوباره استفاده می‌کند و Plugin یا بسته hook نصب‌شده قبلی را در همان‌جا بازنویسی می‌کند. وقتی عمداً همان شناسه را از یک مسیر محلی جدید، آرشیو، بسته ClawHub یا artifact مربوط به npm دوباره نصب می‌کنید، از آن استفاده کنید. برای ارتقاهای معمول یک Plugin مربوط به npm که از قبل ردیابی شده است، `openclaw plugins update <id-or-npm-spec>` را ترجیح دهید.
`--force` از مقصد نصب موجود دوباره استفاده می‌کند و یک Plugin یا hook pack ازپیش‌نصب‌شده را درجا بازنویسی می‌کند. وقتی عمداً همان id را از یک مسیر محلی جدید، archive، package از ClawHub یا artifact از npm دوباره نصب می‌کنید از آن استفاده کنید. برای ارتقاهای معمول یک Plugin از npm که از قبل دنبال می‌شود، `openclaw plugins update <id-or-npm-spec>` را ترجیح دهید.
اگر `plugins install` را برای شناسه Pluginای اجرا کنید که از قبل نصب شده است، OpenClaw متوقف می‌شود و برای ارتقای عادی شما را به `plugins update <id-or-npm-spec>`، یا وقتی واقعاً می‌خواهید نصب فعلی را از منبعی متفاوت بازنویسی کنید به `plugins install <package> --force` ارجاع می‌دهد.
اگر `plugins install` را برای id یک Plugin که از قبل نصب شده اجرا کنید، OpenClaw متوقف می‌شود و برای ارتقای معمول شما را به `plugins update <id-or-npm-spec>` ارجاع می‌دهد، یا وقتی واقعاً می‌خواهید نصب فعلی را از منبعی متفاوت بازنویسی کنید، به `plugins install <package> --force` ارجاع می‌دهد.
</Accordion>
<Accordion title="دامنه --pin">
`--pin` فقط برای نصب‌های npm اعمال می‌شود. با نصب‌های `git:` پشتیبانی نمی‌شود؛ وقتی منبع پین‌شده می‌خواهید، از یک git ref صریح مانند `git:github.com/acme/plugin@v1.2.3` استفاده کنید. با `--marketplace` پشتیبانی نمی‌شود، چون نصب‌های marketplace به‌جای npm spec فراداده منبع marketplace را نگه می‌دارند.
`--pin` فقط برای نصب‌های npm اعمال می‌شود. با نصب‌های `git:` پشتیبانی نمی‌شود؛ وقتی منبع pinned می‌خواهید، از یک git ref صریح مثل `git:github.com/acme/plugin@v1.2.3` استفاده کنید. با `--marketplace` پشتیبانی نمی‌شود، چون نصب‌های marketplace به‌جای spec از npm، metadata منبع marketplace را پایدار می‌کنند.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` گزینه‌ای اضطراری برای مثبت‌های کاذب در اسکنر داخلی کد خطرناک است. این گزینه اجازه می‌دهد نصب حتی وقتی اسکنر داخلی یافته‌های `critical` گزارش می‌کند ادامه یابد، اما مسدودسازی‌های سیاست hook مربوط به `before_install` در Plugin را دور نمی‌زند و شکست‌های اسکن را نیز دور نمی‌زند.
`--dangerously-force-unsafe-install` یک گزینه break-glass برای مثبت‌های کاذب در اسکنر داخلی کد خطرناک است. این گزینه اجازه می‌دهد نصب حتی وقتی اسکنر داخلی یافته‌های `critical` گزارش می‌کند ادامه پیدا کند، اما blockهای policy مربوط به hook `before_install` در Plugin را دور نمی‌زند و خطاهای scan را هم دور نمی‌زند.
این پرچم CLI برای جریان‌های نصب/به‌روزرسانی Plugin اعمال می‌شود. نصب‌های وابستگی Skill مبتنی بر Gateway از override درخواست متناظر `dangerouslyForceUnsafeInstall` استفاده می‌کنند، در حالی که `openclaw skills install` همچنان یک جریان جداگانه دانلود/نصب Skill از ClawHub است.
این پرچم CLI برای جریان‌های نصب/به‌روزرسانی Plugin اعمال می‌شود. نصب‌های وابستگی Skills که از Gateway پشتیبانی می‌شوند از override درخواست متناظر `dangerouslyForceUnsafeInstall` استفاده می‌کنند، در حالی که `openclaw skills install` همچنان یک جریان جداگانه دانلود/نصب Skills از ClawHub باقی می‌ماند.
اگر Pluginای که در ClawHub منتشر کرده‌اید توسط اسکن رجیستری مسدود شده است، از مراحل ناشر در [ClawHub](/fa/tools/clawhub) استفاده کنید.
اگر Pluginی که روی ClawHub منتشر کرده‌اید با scan registry مسدود شده است، از گام‌های ناشر در [ClawHub](/fa/tools/clawhub) استفاده کنید.
</Accordion>
<Accordion title="بسته‌های hook و specهای npm">
`plugins install` همچنین سطح نصب برای بسته‌های hook است که `openclaw.hooks` را در `package.json` ارائه می‌کنند. برای دیدپذیری فیلترشده hook و فعال‌سازی تک‌به‌تک hookها از `openclaw hooks` استفاده کنید، نه برای نصب بسته.
<Accordion title="Hook packها و specهای npm">
`plugins install` همچنین سطح نصب برای hook packهایی است که `openclaw.hooks` را در `package.json` عرضه می‌کنند. برای دید محدودشده hook و فعال‌سازی هر hook از `openclaw hooks` استفاده کنید، نه برای نصب package.
specهای npm **فقط رجیستری** هستند (نام بسته + **نسخه دقیق** اختیاری یا **dist-tag** اختیاری). specهای Git/URL/file و بازه‌های semver رد می‌شوند. نصب‌های وابستگی برای ایمنی، حتی وقتی shell شما تنظیمات نصب سراسری npm دارد، به‌صورت project-local با `--ignore-scripts` اجرا می‌شوند.
specهای npm **فقط registry** هستند (نام package + **نسخه دقیق** اختیاری یا **dist-tag** اختیاری). specهای Git/URL/file و rangeهای semver رد می‌شوند. نصب‌های dependency برای ایمنی، حتی وقتی shell شما تنظیمات global نصب npm دارد، به‌صورت project-local با `--ignore-scripts` اجرا می‌شوند.
وقتی می‌خواهید حل‌وفصل npm را صریح کنید، از `npm:<package>` استفاده کنید. در دوره گذار راه‌اندازی، specهای ساده بسته نیز مستقیماً از npm نصب می‌شوند.
وقتی می‌خواهید resolution مربوط به npm را صریح کنید، از `npm:<package>` استفاده کنید. specهای ساده package نیز در دوره جابه‌جایی launch مستقیماً از npm نصب می‌شوند.
specهای ساده و `@latest` روی مسیر پایدار می‌مانند. اگر npm هرکدام از آن‌ها را به یک prerelease حل کند، OpenClaw متوقف می‌شود و از شما می‌خواهد با یک برچسب prerelease مانند `@beta`/`@rc` یا یک نسخه دقیق prerelease مانند `@1.2.3-beta.4` صریحاً opt in کنید.
specهای ساده و `@latest` روی track پایدار باقی می‌مانند. نسخه‌های اصلاحی date-stamped مربوط به OpenClaw مانند `2026.5.3-1` برای این check، releaseهای پایدار هستند. اگر npm هرکدام از این‌ها را به prerelease resolve کند، OpenClaw متوقف می‌شود و از شما می‌خواهد با یک tag prerelease مانند `@beta`/`@rc` یا یک نسخه دقیق prerelease مانند `@1.2.3-beta.4` صریحاً opt in کنید.
اگر یک spec نصب ساده با شناسه رسمی Plugin منطبق باشد (برای مثال `diffs`)، OpenClaw مستقیماً ورودی کاتالوگ را نصب می‌کند. برای نصب بسته npm با همان نام، از یک spec scoped صریح استفاده کنید (برای مثال `@scope/diffs`).
اگر یک spec نصب ساده با id رسمی Plugin مطابقت داشته باشد (برای مثال `diffs`)، OpenClaw ورودی catalog را مستقیماً نصب می‌کند. برای نصب یک package از npm با همان نام، از یک spec scoped صریح استفاده کنید (برای مثال `@scope/diffs`).
</Accordion>
<Accordion title="مخزن‌های Git">
برای نصب مستقیم از یک مخزن git از `git:<repo>` استفاده کنید. شکل‌های پشتیبانی‌شده شامل URLهای clone با قالب‌های `git:github.com/owner/repo`، `git:owner/repo`، `https://` کامل، `ssh://`، `git://`، `file://` و `git@host:owner/repo.git` هستند. برای checkout کردن یک شاخه، tag یا commit پیش از نصب، `@<ref>` یا `#<ref>` را اضافه کنید.
<Accordion title="مخازن Git">
برای نصب مستقیم از یک مخزن git از `git:<repo>` استفاده کنید. شکل‌های پشتیبانی‌شده شامل URLهای clone با الگوهای `git:github.com/owner/repo`، `git:owner/repo`، `https://` کامل، `ssh://`، `git://`، `file://` و `git@host:owner/repo.git` هستند. برای checkout کردن یک branch، tag یا commit پیش از نصب، `@<ref>` یا `#<ref>` اضافه کنید.
نصب‌های Git در یک پوشه موقت clone می‌شوند، در صورت وجود ref درخواستی آن را checkout می‌کنند، و سپس از نصب‌کننده عادی پوشه Plugin استفاده می‌کنند. یعنی اعتبارسنجی مانیفست، اسکن کد خطرناک، کار نصب package-manager و رکوردهای نصب مانند نصب‌های npm رفتار می‌کنند. نصب‌های git ثبت‌شده شامل URL/ref منبع به‌همراه commit حل‌شده هستند تا `openclaw plugins update` بتواند بعداً منبع را دوباره resolve کند.
نصب‌های Git در یک دایرکتوری موقت clone می‌شوند، اگر ref درخواست‌شده وجود داشته باشد آن را checkout می‌کنند و سپس از نصب‌کننده عادی دایرکتوری Plugin استفاده می‌کنند. یعنی اعتبارسنجی manifest، اسکن کد خطرناک، کار نصب package-manager و رکوردهای نصب مانند نصب‌های npm رفتار می‌کنند. نصب‌های git ثبت‌شده شامل URL/ref منبع به‌همراه commit resolveشده هستند تا `openclaw plugins update` بتواند بعداً منبع را دوباره resolve کند.
پس از نصب از git، برای تأیید ثبت‌های runtime مانند متدهای gateway و فرمان‌های CLI از `openclaw plugins inspect <id> --runtime --json` استفاده کنید. اگر Plugin با `api.registerCli` یک ریشه CLI ثبت کرده باشد، آن فرمان را مستقیماً از طریق CLI ریشه OpenClaw اجرا کنید، برای مثال `openclaw demo-plugin ping`.
پس از نصب از git، از `openclaw plugins inspect <id> --runtime --json` برای تأیید registrationهای runtime مانند methodهای gateway و فرمان‌های CLI استفاده کنید. اگر Plugin با `api.registerCli` یک root مربوط به CLI ثبت کرده باشد، آن فرمان را مستقیماً از طریق CLI ریشه OpenClaw اجرا کنید، برای مثال `openclaw demo-plugin ping`.
</Accordion>
<Accordion title="آرشیوها">
آرشیوهای پشتیبانی‌شده: `.zip`، `.tgz`، `.tar.gz`، `.tar`. آرشیوهای Plugin بومی OpenClaw باید در ریشه Plugin استخراج‌شده یک `openclaw.plugin.json` معتبر داشته باشند؛ آرشیوهایی که فقط `package.json` دارند پیش از اینکه OpenClaw رکوردهای نصب را بنویسد رد می‌شوند.
<Accordion title="Archiveها">
Archiveهای پشتیبانی‌شده: `.zip`، `.tgz`، `.tar.gz`، `.tar`. Archiveهای Plugin native OpenClaw باید در ریشه Plugin استخراج‌شده یک `openclaw.plugin.json` معتبر داشته باشند؛ archiveهایی که فقط شامل `package.json` هستند پیش از اینکه OpenClaw رکوردهای نصب را بنویسد رد می‌شوند.
نصب‌های marketplace مربوط به Claude نیز پشتیبانی می‌شوند.
</Accordion>
</AccordionGroup>
نصب‌های ClawHub از locator صریح `clawhub:<package>` استفاده می‌کنند:
نصب‌های ClawHub از یک locator صریح `clawhub:<package>` استفاده می‌کنند:
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
در دوره گذار راه‌اندازی، specهای Plugin ساده و امن برای npm به‌صورت پیش‌فرض از npm نصب می‌شوند:
specهای ساده Plugin که برای npm امن هستند، در دوره جابه‌جایی launch به‌صورت پیش‌فرض از npm نصب می‌شوند:
```bash
openclaw plugins install openclaw-codex-app-server
```
برای صریح‌کردن حل‌وفصل فقط npm از `npm:` استفاده کنید:
برای صریح‌کردن resolution فقط از npm، از `npm:` استفاده کنید:
```bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
OpenClaw پیش از نصب، API اعلام‌شده Plugin / حداقل سازگاری Gateway را بررسی می‌کند. وقتی نسخه انتخاب‌شده ClawHub یک artifact از نوع ClawPack منتشر کند، OpenClaw فایل `.tgz` نسخه‌دار npm-pack را دانلود می‌کند، header digest مربوط به ClawHub و artifact digest را تأیید می‌کند، سپس آن را از مسیر عادی آرشیو نصب می‌کند. نسخه‌های قدیمی‌تر ClawHub بدون فراداده ClawPack همچنان از مسیر قدیمی تأیید آرشیو بسته نصب می‌شوند. نصب‌های ثبت‌شده فراداده منبع ClawHub، نوع artifact، integrity مربوط به npm، shasum مربوط به npm، نام tarball و واقعیت‌های digest مربوط به ClawPack را برای به‌روزرسانی‌های بعدی نگه می‌دارند.
نصب‌های بدون نسخه ClawHub یک spec ثبت‌شده بدون نسخه نگه می‌دارند تا `openclaw plugins update` بتواند نسخه‌های جدیدتر ClawHub را دنبال کند؛ انتخابگرهای نسخه یا tag صریح مانند `clawhub:pkg@1.2.3` و `clawhub:pkg@beta` به همان انتخابگر پین‌شده باقی می‌مانند.
OpenClaw سازگاری API تبلیغ‌شده Plugin / حداقل Gateway را پیش از نصب بررسی می‌کند. وقتی نسخه انتخاب‌شده ClawHub یک artifact از ClawPack منتشر می‌کند، OpenClaw فایل `.tgz` مربوط به npm-pack نسخه‌گذاری‌شده را دانلود می‌کند، header digest مربوط به ClawHub و digest artifact را تأیید می‌کند، سپس آن را از مسیر عادی archive نصب می‌کند. نسخه‌های قدیمی‌تر ClawHub بدون metadata مربوط به ClawPack همچنان از مسیر قدیمی اعتبارسنجی archive مربوط به package نصب می‌شوند. نصب‌های ثبت‌شده metadata منبع ClawHub، نوع artifact، integrity مربوط به npm، shasum مربوط به npm، نام tarball و واقعیت‌های digest مربوط به ClawPack را برای به‌روزرسانی‌های بعدی نگه می‌دارند.
نصب‌های ClawHub بدون نسخه، spec ثبت‌شده بدون نسخه را نگه می‌دارند تا `openclaw plugins update` بتواند releaseهای جدیدتر ClawHub را دنبال کند؛ selectorهای نسخه یا tag صریح مانند `clawhub:pkg@1.2.3` و `clawhub:pkg@beta` به همان selector pinned باقی می‌مانند.
#### کوتاه‌نویسی Marketplace
وقتی نام marketplace در cache رجیستری محلی Claude در `~/.claude/plugins/known_marketplaces.json` وجود دارد، از کوتاه‌نویسی `plugin@marketplace` استفاده کنید:
وقتی نام marketplace در cache محلی registry مربوط به Claude در `~/.claude/plugins/known_marketplaces.json` وجود دارد، از کوتاه‌نویسی `plugin@marketplace` استفاده کنید:
```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
وقتی می‌خواهید منبع marketplace را صریحاً پاس دهید، از `--marketplace` استفاده کنید:
وقتی می‌خواهید منبع marketplace را صریحاً پاس بدهید، از `--marketplace` استفاده کنید:
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
@ -194,28 +194,28 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
<Tabs>
<Tab title="منابع Marketplace">
- نام marketplace شناخته‌شده Claude از `~/.claude/plugins/known_marketplaces.json`
- ریشه marketplace محلی یا مسیر `marketplace.json`
- کوتاه‌نویسی مخزن GitHub مانند `owner/repo`
- URL مخزن GitHub مانند `https://github.com/owner/repo`
<Tab title="منابع بازار">
- یک نام بازار شناخته‌شده Claude از `~/.claude/plugins/known_marketplaces.json`
- یک ریشه بازار محلی یا مسیر `marketplace.json`
- یک کوتاه‌نویسی مخزن GitHub مانند `owner/repo`
- یک URL مخزن GitHub مانند `https://github.com/owner/repo`
- یک URL git
</Tab>
<Tab title="قواعد marketplace راه‌دور">
برای marketplaceهای راه‌دوری که از GitHub یا git بارگذاری می‌شوند، ورودی‌های Plugin باید داخل مخزن marketplace کلون‌شده باقی بمانند. OpenClaw منابع مسیر نسبی را از آن مخزن می‌پذیرد و منابع HTTP(S)، مسیر مطلق، git، GitHub و دیگر منابع غیرمسیری Plugin را از manifestهای راه‌دور رد می‌کند.
<Tab title="قواعد بازار راه‌دور">
برای بازارهای راه‌دوری که از GitHub یا git بارگذاری می‌شوند، ورودی‌های Plugin باید داخل مخزن بازار کلون‌شده بمانند. OpenClaw منابع مسیر نسبی را از همان مخزن می‌پذیرد و منابع HTTP(S)، مسیر مطلق، git، GitHub، و دیگر منابع غیرمسیر Plugin را از manifestهای راه‌دور رد می‌کند.
</Tab>
</Tabs>
برای مسیرها و آرشیوهای محلی، OpenClaw به‌صورت خودکار تشخیص می‌دهد:
برای مسیرها و آرشیوهای محلی، OpenClaw به‌طور خودکار تشخیص می‌دهد:
- Pluginهای بومی OpenClaw (`openclaw.plugin.json`)
- بسته‌های سازگار با Codex (`.codex-plugin/plugin.json`)
- بسته‌های سازگار با Claude (`.claude-plugin/plugin.json` یا چیدمان پیش‌فرض مؤلفه Claude)
- بسته‌های سازگار با Claude (`.claude-plugin/plugin.json` یا چیدمان پیش‌فرض مؤلفه‌های Claude)
- بسته‌های سازگار با Cursor (`.cursor-plugin/plugin.json`)
<Note>
بسته‌های سازگار در ریشه معمول Plugin نصب می‌شوند و در همان جریان فهرست/اطلاعات/فعال‌سازی/غیرفعال‌سازی شرکت می‌کنند. امروز، Skills بسته، command-skillsهای Claude، پیش‌فرض‌های Claude `settings.json`، پیش‌فرض‌های Claude `.lsp.json` / `lspServers` اعلام‌شده در manifest، command-skillsهای Cursor، و دایرکتوری‌های hook سازگار Codex پشتیبانی می‌شوند؛ قابلیت‌های دیگر بسته که شناسایی شوند در diagnostics/info نمایش داده می‌شوند اما هنوز به اجرای زمان اجرا متصل نشده‌اند.
بسته‌های سازگار در ریشه معمول Plugin نصب می‌شوند و در همان جریان فهرست/اطلاعات/فعال‌سازی/غیرفعال‌سازی شرکت می‌کنند. امروز، Skills بسته، command-skills مربوط به Claude، پیش‌فرض‌های `settings.json` مربوط به Claude، پیش‌فرض‌های `.lsp.json` مربوط به Claude / `lspServers` اعلام‌شده در manifest، command-skills مربوط به Cursor، و دایرکتوری‌های hook سازگار Codex پشتیبانی می‌شوند؛ قابلیت‌های بسته دیگری که تشخیص داده شوند در diagnostics/info نمایش داده می‌شوند، اما هنوز به اجرای زمان اجرا متصل نشده‌اند.
</Note>
### فهرست
@ -231,49 +231,48 @@ openclaw plugins search <query> --json
```
<ParamField path="--enabled" type="boolean">
فقط Pluginهای فعال‌شده را نشان بده.
فقط Pluginهای فعال را نشان بده.
</ParamField>
<ParamField path="--verbose" type="boolean">
از نمای جدول به خط‌های جزئیات برای هر Plugin با metadata منبع/خاستگاه/نسخه/فعال‌سازی تغییر بده.
از نمای جدول به خط‌های جزئیات برای هر Plugin با فراداده منبع/مبدأ/نسخه/فعال‌سازی تغییر بده.
</ParamField>
<ParamField path="--json" type="boolean">
موجودی قابل‌خواندن برای ماشین همراه با diagnostics رجیستری و وضعیت نصب وابستگی بسته.
فهرست موجودی قابل خواندن برای ماشین، به‌همراه diagnostics رجیستری و وضعیت نصب وابستگی‌های بسته.
</ParamField>
<Note>
`plugins list` ابتدا رجیستری محلی پایدارشده Plugin را می‌خواند، و اگر رجیستری وجود نداشته باشد یا نامعتبر باشد از یک fallback مشتق‌شده فقط از manifest استفاده می‌کند. این فرمان برای بررسی اینکه آیا یک Plugin نصب، فعال و برای برنامه‌ریزی شروع سرد قابل مشاهده است مفید است، اما probe زنده زمان اجرا برای یک فرایند Gateway ازپیش‌درحال‌اجرا نیست. پس از تغییر کد Plugin، فعال‌سازی، سیاست hook، یا `plugins.load.paths`، پیش از انتظار اجرای کد `register(api)` یا hookهای جدید، Gatewayای را که به کانال سرویس می‌دهد راه‌اندازی مجدد کنید. برای استقرارهای راه‌دور/کانتینری، بررسی کنید که فرزند واقعی `openclaw gateway run` را راه‌اندازی مجدد می‌کنید، نه فقط یک فرایند wrapper.
`plugins list` ابتدا رجیستری محلی ماندگارشده Plugin را می‌خواند، و وقتی رجیستری وجود نداشته باشد یا نامعتبر باشد از جایگزین مشتق‌شده فقط از manifest استفاده می‌کند. این دستور برای بررسی اینکه آیا یک Plugin نصب شده، فعال است، و برای برنامه‌ریزی راه‌اندازی سرد قابل مشاهده است مفید است، اما یک کاوش زنده زمان اجرا از فرایند Gateway در حال اجرا نیست. پس از تغییر کد Plugin، فعال‌سازی، سیاست hook، یا `plugins.load.paths`، پیش از انتظار برای اجرای کد `register(api)` یا hookهای جدید، Gatewayای را که به کانال سرویس می‌دهد راه‌اندازی مجدد کنید. برای استقرارهای راه‌دور/کانتینری، مطمئن شوید فرزند واقعی `openclaw gateway run` را راه‌اندازی مجدد می‌کنید، نه فقط یک فرایند wrapper.
`plugins list --json` شامل `dependencyStatus` هر Plugin از `package.json`
`dependencies` و `optionalDependencies` است. OpenClaw بررسی می‌کند که آیا نام‌های آن بسته‌ها در مسیر lookup معمول Node `node_modules` برای Plugin وجود دارند یا نه؛ کد زمان اجرای Plugin را import نمی‌کند، package manager اجرا نمی‌کند، و وابستگی‌های گمشده را repair نمی‌کند.
`plugins list --json` شامل `dependencyStatus` هر Plugin از `dependencies` و `optionalDependencies` در `package.json` است. OpenClaw بررسی می‌کند که آیا نام‌های آن بسته‌ها در مسیر معمول جست‌وجوی Node `node_modules` مربوط به Plugin وجود دارند؛ کد زمان اجرای Plugin را import نمی‌کند، package manager اجرا نمی‌کند، و وابستگی‌های گم‌شده را تعمیر نمی‌کند.
</Note>
`plugins search` یک lookup کاتالوگ راه‌دور ClawHub است. این فرمان وضعیت محلی را بازرسی نمی‌کند، config را تغییر نمی‌دهد، بسته‌ها را نصب نمی‌کند، یا کد زمان اجرای Plugin را بارگذاری نمی‌کند. نتایج جستجو شامل نام بسته ClawHub، خانواده، کانال، نسخه، خلاصه، و یک راهنمای نصب مانند `openclaw plugins install clawhub:<package>` هستند.
`plugins search` یک جست‌وجوی کاتالوگ راه‌دور ClawHub است. این دستور وضعیت محلی را بازرسی نمی‌کند، config را تغییر نمی‌دهد، بسته‌ها را نصب نمی‌کند، و کد زمان اجرای Plugin را بارگذاری نمی‌کند. نتایج جست‌وجو شامل نام بسته ClawHub، خانواده، کانال، نسخه، خلاصه، و یک راهنمای نصب مانند `openclaw plugins install clawhub:<package>` هستند.
برای کار روی Pluginهای بسته‌بندی‌شده داخل یک تصویر Docker بسته‌بندی‌شده، دایرکتوری منبع Plugin را روی مسیر منبع بسته‌بندی‌شده متناظر bind-mount کنید، مانند `/app/extensions/synology-chat`. OpenClaw آن overlay منبع mount‌شده را پیش از `/app/dist/extensions/synology-chat` کشف می‌کند؛ یک دایرکتوری منبع صرفا کپی‌شده بی‌اثر می‌ماند تا نصب‌های بسته‌بندی‌شده معمول همچنان از dist کامپایل‌شده استفاده کنند.
برای کار روی Pluginهای بسته‌بندی‌شده داخل یک تصویر Docker بسته‌بندی‌شده، دایرکتوری منبع Plugin را روی مسیر منبع بسته‌بندی‌شده متناظر bind-mount کنید، مانند `/app/extensions/synology-chat`. OpenClaw آن overlay منبع mount‌شده را پیش از `/app/dist/extensions/synology-chat` کشف می‌کند؛ یک دایرکتوری منبع که صرفاً کپی شده باشد بی‌اثر می‌ماند تا نصب‌های بسته‌بندی‌شده معمول همچنان از dist کامپایل‌شده استفاده کنند.
برای عیب‌یابی hook زمان اجرا:
برای اشکال‌زدایی hookهای زمان اجرا:
- `openclaw plugins inspect <id> --runtime --json` hookهای ثبت‌شده و diagnostics را از یک pass بازرسی با module-loaded نشان می‌دهد. بازرسی زمان اجرا هرگز وابستگی‌ها را نصب نمی‌کند؛ برای پاک‌سازی وضعیت وابستگی legacy یا نصب Pluginهای قابل‌دانلود پیکربندی‌شده گمشده از `openclaw doctor --fix` استفاده کنید.
- `openclaw gateway status --deep --require-rpc` Gateway قابل دسترس، راهنمایی‌های سرویس/فرایند، مسیر config، و سلامت RPC را تأیید می‌کند.
- hookهای گفت‌وگوی غیر bundled (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) به `plugins.entries.<id>.hooks.allowConversationAccess=true` نیاز دارند.
- `openclaw plugins inspect <id> --runtime --json` hookهای ثبت‌شده و diagnostics را از یک گذر بازرسی با ماژول بارگذاری‌شده نشان می‌دهد. بازرسی زمان اجرا هرگز وابستگی‌ها را نصب نمی‌کند؛ برای پاک‌سازی وضعیت وابستگی قدیمی یا نصب Pluginهای قابل دانلودِ پیکربندی‌شده و گم‌شده از `openclaw doctor --fix` استفاده کنید.
- `openclaw gateway status --deep --require-rpc` Gateway قابل دسترسی، اشاره‌های سرویس/فرایند، مسیر config، و سلامت RPC را تأیید می‌کند.
- hookهای گفت‌وگوی غیرهمراه (`llm_input`، `llm_output`، `before_agent_finalize`، `agent_end`) به `plugins.entries.<id>.hooks.allowConversationAccess=true` نیاز دارند.
برای جلوگیری از کپی‌کردن یک دایرکتوری محلی از `--link` استفاده کنید (به `plugins.load.paths` اضافه می‌کند):
برای جلوگیری از کپی کردن یک دایرکتوری محلی از `--link` استفاده کنید (به `plugins.load.paths` اضافه می‌کند):
```bash
openclaw plugins install -l ./my-plugin
```
<Note>
`--force` همراه با `--link` پشتیبانی نمی‌شود، زیرا نصب‌های linked به‌جای کپی‌کردن روی یک هدف نصب مدیریت‌شده، از مسیر منبع دوباره استفاده می‌کنند.
`--force` همراه با `--link` پشتیبانی نمی‌شود، چون نصب‌های linked به‌جای کپی کردن روی هدف نصب مدیریت‌شده، مسیر منبع را دوباره استفاده می‌کنند.
در نصب‌های npm از `--pin` استفاده کنید تا spec دقیق resolve‌شده (`name@version`) در اندیس Plugin مدیریت‌شده ذخیره شود و در عین حال رفتار پیش‌فرض unpinned باقی بماند.
در نصب‌های npm از `--pin` استفاده کنید تا spec دقیق resolve‌شده (`name@version`) در نمایه Plugin مدیریت‌شده ذخیره شود، در حالی که رفتار پیش‌فرض بدون pin باقی بماند.
</Note>
### اندیس Plugin
### نمایه Plugin
metadata نصب Plugin وضعیت مدیریت‌شده توسط ماشین است، نه config کاربر. نصب‌ها و به‌روزرسانی‌ها آن را در `plugins/installs.json` زیر دایرکتوری وضعیت فعال OpenClaw می‌نویسند. map سطح بالای `installRecords` منبع پایدار metadata نصب است، شامل رکوردهای manifestهای Plugin خراب یا گمشده. آرایه `plugins` کش رجیستری سرد مشتق‌شده از manifest است. این فایل شامل هشدار ویرایش‌نکنید است و توسط `openclaw plugins update`، حذف نصب، diagnostics، و رجیستری سرد Plugin استفاده می‌شود.
فراداده نصب Plugin وضعیت مدیریت‌شده توسط ماشین است، نه config کاربر. نصب‌ها و به‌روزرسانی‌ها آن را در `plugins/installs.json` زیر دایرکتوری وضعیت فعال OpenClaw می‌نویسند. نگاشت سطح‌بالای `installRecords` منبع ماندگار فراداده نصب است، از جمله recordهای مربوط به manifestهای خراب یا گم‌شده Plugin. آرایه `plugins` کش رجیستری سرد مشتق‌شده از manifest است. فایل شامل هشدار ویرایش‌نکنید است و توسط `openclaw plugins update`، uninstall، diagnostics، و رجیستری سرد Plugin استفاده می‌شود.
وقتی OpenClaw رکوردهای legacy ارسال‌شده `plugins.installs` را در config ببیند، آن‌ها را به اندیس Plugin منتقل می‌کند و کلید config را حذف می‌کند؛ اگر هرکدام از writeها شکست بخورد، رکوردهای config نگه داشته می‌شوند تا metadata نصب از دست نرود.
وقتی OpenClaw recordهای قدیمی ارسال‌شده `plugins.installs` را در config ببیند، آن‌ها را به نمایه Plugin منتقل می‌کند و کلید config را حذف می‌کند؛ اگر هرکدام از نوشتن‌ها شکست بخورد، recordهای config حفظ می‌شوند تا فراداده نصب از دست نرود.
### حذف نصب
@ -283,10 +282,10 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` رکوردهای Plugin را از `plugins.entries`، اندیس پایدارشده Plugin، ورودی‌های فهرست allow/deny برای Plugin، و ورودی‌های linked `plugins.load.paths` در صورت کاربرد حذف می‌کند. مگر اینکه `--keep-files` تنظیم شده باشد، حذف نصب همچنین دایرکتوری نصب مدیریت‌شده track‌شده را وقتی داخل ریشه extensions Pluginهای OpenClaw باشد حذف می‌کند. برای Pluginهای active memory، slot حافظه به `memory-core` بازنشانی می‌شود.
`uninstall` recordهای Plugin را از `plugins.entries`، نمایه ماندگار Plugin، ورودی‌های فهرست allow/deny مربوط به Plugin، و در صورت کاربرد ورودی‌های linked `plugins.load.paths` حذف می‌کند. مگر اینکه `--keep-files` تنظیم شده باشد، uninstall همچنین دایرکتوری نصب مدیریت‌شده ردیابی‌شده را وقتی داخل ریشه افزونه‌های Plugin OpenClaw باشد حذف می‌کند. برای Pluginهای حافظه فعال، slot حافظه به `memory-core` بازنشانی می‌شود.
<Note>
`--keep-config` به‌عنوان alias منسوخ برای `--keep-files` پشتیبانی می‌شود.
`--keep-config` به‌عنوان نام مستعار منسوخ‌شده برای `--keep-files` پشتیبانی می‌شود.
</Note>
### به‌روزرسانی
@ -299,29 +298,29 @@ openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
به‌روزرسانی‌ها روی نصب‌های Plugin track‌شده در اندیس Plugin مدیریت‌شده و نصب‌های hook-pack track‌شده در `hooks.internal.installs` اعمال می‌شوند.
به‌روزرسانی‌ها روی نصب‌های Plugin ردیابی‌شده در نمایه Plugin مدیریت‌شده و نصب‌های hook-pack ردیابی‌شده در `hooks.internal.installs` اعمال می‌شوند.
<AccordionGroup>
<Accordion title="Resolve کردن شناسه Plugin در برابر spec npm">
وقتی یک شناسه Plugin پاس می‌دهید، OpenClaw از spec نصب ثبت‌شده برای آن Plugin دوباره استفاده می‌کند. یعنی dist-tagهای ذخیره‌شده قبلی مانند `@beta` و نسخه‌های دقیق pinned همچنان در اجراهای بعدی `update <id>` استفاده می‌شوند.
<Accordion title="حل‌کردن id Plugin در برابر spec npm">
وقتی یک id مربوط به Plugin را می‌دهید، OpenClaw از spec نصب ثبت‌شده برای آن Plugin دوباره استفاده می‌کند. یعنی dist-tagهای ذخیره‌شده قبلی مانند `@beta` و نسخه‌های دقیق pinشده در اجرای بعدی `update <id>` همچنان استفاده می‌شوند.
برای نصب‌های npm، همچنین می‌توانید یک spec صریح بسته npm با dist-tag یا نسخه دقیق پاس دهید. OpenClaw آن نام بسته را به رکورد Plugin track‌شده برمی‌گرداند، آن Plugin نصب‌شده را به‌روزرسانی می‌کند، و spec جدید npm را برای به‌روزرسانی‌های مبتنی بر شناسه در آینده ثبت می‌کند.
برای نصب‌های npm، می‌توانید یک spec صریح بسته npm با dist-tag یا نسخه دقیق هم بدهید. OpenClaw آن نام بسته را به record ردیابی‌شده Plugin برمی‌گرداند، آن Plugin نصب‌شده را به‌روزرسانی می‌کند، و spec جدید npm را برای به‌روزرسانی‌های آینده مبتنی بر id ثبت می‌کند.
پاس‌دادن نام بسته npm بدون نسخه یا tag نیز به رکورد Plugin track‌شده برمی‌گردد. وقتی یک Plugin به یک نسخه دقیق pinned شده و می‌خواهید آن را به خط انتشار پیش‌فرض رجیستری برگردانید، از این استفاده کنید.
دادن نام بسته npm بدون نسخه یا tag نیز به record ردیابی‌شده Plugin برمی‌گردد. وقتی Plugin به یک نسخه دقیق pin شده و می‌خواهید آن را به خط انتشار پیش‌فرض رجیستری برگردانید، از این استفاده کنید.
</Accordion>
<Accordion title="به‌روزرسانی‌های کانال beta">
`openclaw plugins update` از spec Plugin track‌شده دوباره استفاده می‌کند مگر اینکه spec جدیدی پاس دهید. `openclaw update` علاوه بر این کانال فعال به‌روزرسانی OpenClaw را می‌شناسد: در کانال beta، رکوردهای Plugin خط پیش‌فرض npm و ClawHub ابتدا `@beta` را امتحان می‌کنند، سپس اگر انتشار beta برای Plugin وجود نداشته باشد به spec پیش‌فرض/latest ثبت‌شده fallback می‌کنند. نسخه‌های دقیق و tagهای صریح روی همان selector pinned می‌مانند.
<Accordion title="به‌روزرسانی‌های کانال بتا">
`openclaw plugins update` از spec ردیابی‌شده Plugin دوباره استفاده می‌کند، مگر اینکه spec جدیدی بدهید. `openclaw update` علاوه بر این کانال به‌روزرسانی فعال OpenClaw را می‌شناسد: در کانال بتا، recordهای Plugin مربوط به npm و ClawHub در خط پیش‌فرض ابتدا `@beta` را امتحان می‌کنند، سپس اگر انتشار بتای Plugin وجود نداشته باشد به spec پیش‌فرض/latest ثبت‌شده برمی‌گردند. نسخه‌های دقیق و tagهای صریح روی همان selector pin می‌مانند.
</Accordion>
<Accordion title="بررسی‌های نسخه و drift یکپارچگی">
پیش از به‌روزرسانی زنده npm، OpenClaw نسخه بسته نصب‌شده را با metadata رجیستری npm بررسی می‌کند. اگر نسخه نصب‌شده و هویت artifact ثبت‌شده از قبل با هدف resolve‌شده تطبیق داشته باشند، به‌روزرسانی بدون دانلود، نصب مجدد، یا بازنویسی `openclaw.json` رد می‌شود.
پیش از یک به‌روزرسانی زنده npm، OpenClaw نسخه بسته نصب‌شده را در برابر فراداده رجیستری npm بررسی می‌کند. اگر نسخه نصب‌شده و هویت artifact ثبت‌شده از قبل با هدف resolve‌شده مطابقت داشته باشند، به‌روزرسانی بدون دانلود، نصب مجدد، یا بازنویسی `openclaw.json` رد می‌شود.
وقتی یک hash یکپارچگی ذخیره‌شده وجود داشته باشد و hash artifact دریافت‌شده تغییر کند، OpenClaw آن را drift artifact npm تلقی می‌کند. فرمان تعاملی `openclaw plugins update` hashهای مورد انتظار و واقعی را چاپ می‌کند و پیش از ادامه تأیید می‌خواهد. helperهای به‌روزرسانی غیرتعاملی به‌صورت fail closed عمل می‌کنند مگر اینکه caller یک سیاست ادامه صریح ارائه کند.
وقتی یک hash یکپارچگی ذخیره‌شده وجود داشته باشد و hash artifact دریافت‌شده تغییر کند، OpenClaw آن را drift در artifact npm تلقی می‌کند. دستور تعاملی `openclaw plugins update` hashهای مورد انتظار و واقعی را چاپ می‌کند و پیش از ادامه تأیید می‌خواهد. helperهای به‌روزرسانی غیرتعاملی fail closed می‌شوند، مگر اینکه فراخوان یک سیاست ادامه صریح ارائه کند.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install در update">
`--dangerously-force-unsafe-install` همچنین در `plugins update` به‌عنوان override اضطراری برای مثبت‌های کاذب اسکن dangerous-code داخلی هنگام به‌روزرسانی Pluginها در دسترس است. این گزینه همچنان blockهای سیاست `before_install` Plugin یا blocking ناشی از شکست اسکن را دور نمی‌زند، و فقط روی به‌روزرسانی‌های Plugin اعمال می‌شود، نه به‌روزرسانی‌های hook-pack.
`--dangerously-force-unsafe-install` روی `plugins update` نیز به‌عنوان override اضطراری برای false positiveهای اسکن داخلی کد خطرناک هنگام به‌روزرسانی Plugin در دسترس است. این گزینه همچنان blockهای سیاست `before_install` مربوط به Plugin یا مسدودسازی ناشی از شکست اسکن را دور نمی‌زند، و فقط برای به‌روزرسانی‌های Plugin اعمال می‌شود، نه به‌روزرسانی‌های hook-pack.
</Accordion>
</AccordionGroup>
@ -333,21 +332,21 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
```
Inspect هویت، وضعیت بارگذاری، منبع، قابلیت‌های manifest، flagهای سیاست، diagnostics، metadata نصب، قابلیت‌های بسته، و هر پشتیبانی شناسایی‌شده MCP یا سرور LSP را بدون import کردن پیش‌فرض زمان اجرای Plugin نشان می‌دهد. برای بارگذاری ماژول Plugin و شامل‌کردن hookها، tools، commands، services، متدهای gateway، و routeهای HTTP ثبت‌شده، `--runtime` را اضافه کنید. بازرسی زمان اجرا وابستگی‌های گمشده Plugin را مستقیما گزارش می‌کند؛ نصب‌ها و repairها در `openclaw plugins install`، `openclaw plugins update`، و `openclaw doctor --fix` باقی می‌مانند.
Inspect هویت، وضعیت بارگذاری، منبع، قابلیت‌های manifest، پرچم‌های سیاست، diagnostics، فراداده نصب، قابلیت‌های بسته، و هر پشتیبانی تشخیص‌داده‌شده از سرور MCP یا LSP را بدون import کردن زمان اجرای Plugin به‌صورت پیش‌فرض نشان می‌دهد. برای بارگذاری ماژول Plugin و شامل‌کردن hookها، tools، commands، services، methodهای gateway، و routeهای HTTP ثبت‌شده، `--runtime` را اضافه کنید. بازرسی زمان اجرا وابستگی‌های گم‌شده Plugin را مستقیماً گزارش می‌کند؛ نصب‌ها و تعمیرها در `openclaw plugins install`، `openclaw plugins update`، و `openclaw doctor --fix` باقی می‌مانند.
فرمان‌های CLI متعلق به Plugin به‌عنوان گروه‌های فرمان ریشه `openclaw` نصب می‌شوند. پس از اینکه `inspect --runtime` یک فرمان را زیر `cliCommands` نشان داد، آن را به‌شکل `openclaw <command> ...` اجرا کنید؛ برای مثال Pluginای که `demo-git` را ثبت می‌کند می‌تواند با `openclaw demo-git ping` تأیید شود.
دستورهای CLI متعلق به Plugin به‌عنوان گروه‌های دستور ریشه `openclaw` نصب می‌شوند. پس از اینکه `inspect --runtime` یک دستور را زیر `cliCommands` نشان داد، آن را به‌صورت `openclaw <command> ...` اجرا کنید؛ برای نمونه، Pluginای که `demo-git` را ثبت می‌کند می‌تواند با `openclaw demo-git ping` تأیید شود.
هر Plugin بر اساس چیزی که واقعا در زمان اجرا ثبت می‌کند طبقه‌بندی می‌شود:
هر Plugin بر اساس آنچه واقعاً در زمان اجرا ثبت می‌کند طبقه‌بندی می‌شود:
- **plain-capability** — یک نوع قابلیت (برای مثال یک Plugin فقط provider)
- **hybrid-capability** — چند نوع قابلیت (برای مثال متن + گفتار + تصویر)
- **plain-capability** — یک نوع قابلیت (مثلاً یک Plugin فقط provider)
- **hybrid-capability** — چند نوع قابلیت (مثلاً متن + گفتار + تصاویر)
- **hook-only** — فقط hookها، بدون قابلیت یا surface
- **non-capability** — tools/commands/services اما بدون قابلیت
برای اطلاعات بیشتر درباره مدل قابلیت، [شکل‌های Plugin](/fa/plugins/architecture#plugin-shapes) را ببینید.
<Note>
flag `--json` گزارشی قابل‌خواندن برای ماشین تولید می‌کند که برای اسکریپت‌نویسی و auditing مناسب است. `inspect --all` یک جدول سراسری با ستون‌های shape، نوع‌های قابلیت، اعلان‌های سازگاری، قابلیت‌های بسته، و خلاصه hook رندر می‌کند. `info` نام مستعار `inspect` است.
پرچم `--json` گزارشی قابل خواندن برای ماشین تولید می‌کند که برای اسکریپت‌نویسی و حسابرسی مناسب است. `inspect --all` یک جدول در سطح کل مجموعه با ستون‌های شکل، گونه‌های قابلیت، اعلان‌های سازگاری، قابلیت‌های بسته، و خلاصه hook نمایش می‌دهد. `info` نام مستعار `inspect` است.
</Note>
### Doctor
@ -358,9 +357,9 @@ openclaw plugins doctor
`doctor` خطاهای بارگذاری Plugin، diagnostics مربوط به manifest/discovery، و اعلان‌های سازگاری را گزارش می‌کند. وقتی همه چیز پاک باشد، `No plugin issues detected.` را چاپ می‌کند.
اگر یک Plugin پیکربندی‌شده روی دیسک حاضر باشد اما توسط بررسی‌های path-safety لودر blocked شده باشد، اعتبارسنجی config ورودی Plugin را نگه می‌دارد و آن را به‌صورت `present but blocked` گزارش می‌کند. به‌جای حذف config مربوط به `plugins.entries.<id>` یا `plugins.allow`، diagnostic قبلی Plugin blocked را رفع کنید، مانند مالکیت مسیر یا مجوزهای world-writable.
اگر یک Plugin پیکربندی‌شده روی دیسک وجود داشته باشد اما توسط بررسی‌های path-safety loader مسدود شود، اعتبارسنجی config ورودی Plugin را نگه می‌دارد و آن را به‌صورت `present but blocked` گزارش می‌کند. به‌جای حذف config مربوط به `plugins.entries.<id>` یا `plugins.allow`، diagnostic قبلی Plugin مسدودشده، مانند مالکیت مسیر یا مجوزهای world-writable را اصلاح کنید.
برای شکست‌های شکل ماژول مانند exportهای گمشده `register`/`activate`، با `OPENCLAW_PLUGIN_LOAD_DEBUG=1` دوباره اجرا کنید تا خلاصه فشرده‌ای از export-shape در خروجی diagnostic گنجانده شود.
برای شکست‌های شکل ماژول مانند exportهای گم‌شده `register`/`activate`، با `OPENCLAW_PLUGIN_LOAD_DEBUG=1` دوباره اجرا کنید تا یک خلاصه فشرده از شکل exportها در خروجی diagnostic گنجانده شود.
### رجیستری
@ -370,12 +369,12 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
رجیستری محلی Plugin مدل خواندن سرد پایدارشده OpenClaw برای هویت Plugin نصب‌شده، فعال‌سازی، metadata منبع، و مالکیت contribution است. شروع معمول، lookup مالک provider، طبقه‌بندی راه‌اندازی کانال، و موجودی Plugin می‌توانند بدون import کردن ماژول‌های زمان اجرای Plugin آن را بخوانند.
رجیستری محلی Plugin مدل خواندن سرد ماندگار OpenClaw برای هویت Plugin نصب‌شده، فعال‌سازی، فراداده منبع، و مالکیت مشارکت است. راه‌اندازی معمول، جست‌وجوی مالک provider، طبقه‌بندی راه‌اندازی کانال، و موجودی Plugin می‌توانند بدون import کردن ماژول‌های زمان اجرای Plugin آن را بخوانند.
از `plugins registry` برای بررسی اینکه رجیستری پایدارشده موجود، به‌روز یا قدیمی است استفاده کنید. از `--refresh` برای بازسازی آن از نمایهٔ Plugin پایدارشده، سیاست پیکربندی، و فرادادهٔ manifest/package استفاده کنید. این یک مسیر تعمیر است، نه مسیر فعال‌سازی در زمان اجرا.
از `plugins registry` استفاده کنید تا بررسی کنید آیا رجیستری پایدارشده وجود دارد، به‌روز است، یا کهنه شده است. از `--refresh` استفاده کنید تا آن را از شاخص Plugin پایدارشده، سیاست پیکربندی، و فراداده‌های manifest/package بازسازی کنید. این یک مسیر تعمیر است، نه مسیر فعال‌سازی در زمان اجرا.
<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` یک سوییچ سازگاری منسوخ‌شدهٔ اضطراری برای خطاهای خواندن رجیستری است. `plugins registry --refresh` یا `openclaw doctor --fix` را ترجیح دهید؛ fallback محیطی فقط برای بازیابی اضطراری راه‌اندازی هنگام عرضهٔ مهاجرت است.
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` یک کلید سازگاری اضطراری منسوخ برای خرابی‌های خواندن رجیستری است. `plugins registry --refresh` یا `openclaw doctor --fix` را ترجیح دهید؛ جایگزین env فقط برای بازیابی اضطراری شروع به کار در زمانی است که مهاجرت در حال انتشار است.
</Warning>
### بازارچه
@ -385,7 +384,7 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
فهرست بازارچه یک مسیر بازارچهٔ محلی، یک مسیر `marketplace.json`، یک اختصار GitHub مانند `owner/repo`، یک URL مخزن GitHub، یا یک URL گیت را می‌پذیرد. `--json` برچسب منبع حل‌شده را به‌همراه manifest بازارچهٔ تجزیه‌شده و ورودی‌های Plugin چاپ می‌کند.
فهرست بازارچه یک مسیر بازارچه محلی، یک مسیر `marketplace.json`، یک خلاصه‌نویسی GitHub مانند `owner/repo`، یک URL مخزن GitHub، یا یک URL git را می‌پذیرد. `--json` برچسب منبع حل‌شده را همراه با manifest بازارچه تجزیه‌شده و ورودی‌های Plugin چاپ می‌کند.
## مرتبط

48
docs/fa/cli/proxy.md
View File

@ -1,24 +1,29 @@
---
read_when:
- باید مسیریابی پروکسیِ مدیریت‌شده توسط اپراتور را پیش از استقرار اعتبارسنجی کنید
- باید ترافیک انتقال OpenClaw را به‌صورت محلی برای اشکال‌زدایی ضبط کنید
- می‌خواهید نشست‌های پراکسی اشکال‌زدایی، blobها یا پیش‌تنظیم‌های داخلی پرس‌وجو را بررسی کنید
- باید مسیریابی پروکسیِ مدیریت‌شده توسط اپراتور را پیش از استقرار اعتبارسنجی کنید.
- برای اشکال‌زدایی باید ترافیک انتقال OpenClaw را به‌صورت محلی ضبط کنید
- می‌خواهید نشست‌های پراکسی اشکال‌زدایی، اشیای باینری بزرگ، یا پیش‌تنظیم‌های پرس‌وجوی داخلی را بررسی کنید
summary: مرجع CLI برای `openclaw proxy`، شامل اعتبارسنجی پروکسی مدیریت‌شده توسط اپراتور و بازرس ضبط پروکسی اشکال‌زدایی محلی
title: پروکسی
x-i18n:
generated_at: "2026-05-01T11:44:59Z"
generated_at: "2026-05-04T07:03:02Z"
model: gpt-5.5
provider: openai
source_hash: e0820de861bfe1ec14e0c1624d636d6474b5fedd317e3ba1baaa61f6530e06e9
source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb
source_path: cli/proxy.md
workflow: 16
---
# `openclaw proxy`
مسیریابی پراکسی تحت مدیریت اپراتور را اعتبارسنجی کنید، یا پراکسی اشکال‌زدایی صریح محلی را اجرا کنید و ترافیک ضبط‌شده را بررسی کنید.
مسیریابی پراکسیِ مدیریت‌شده توسط راهبر را اعتبارسنجی کنید، یا پراکسی اشکال‌زدایی صریح محلی را اجرا کنید
و ترافیک ثبت‌شده را بررسی کنید.
از `validate` برای پیش‌بررسی یک پراکسی پیش‌برنده تحت مدیریت اپراتور پیش از فعال‌سازی مسیریابی پراکسی OpenClaw استفاده کنید. فرمان‌های دیگر ابزارهای اشکال‌زدایی برای بررسی در سطح انتقال هستند: آن‌ها می‌توانند یک پراکسی محلی را شروع کنند، یک فرمان فرزند را با ضبط فعال اجرا کنند، نشست‌های ضبط را فهرست کنند، الگوهای رایج ترافیک را پرس‌وجو کنند، blobهای ضبط‌شده را بخوانند، و داده‌های ضبط محلی را پاک کنند.
از `validate` برای پیش‌بررسی یک پراکسی روبه‌جلوی مدیریت‌شده توسط راهبر، پیش از فعال‌سازی
مسیریابی پراکسی OpenClaw استفاده کنید. فرمان‌های دیگر ابزارهای اشکال‌زدایی برای
بررسی در سطح انتقال هستند: آن‌ها می‌توانند یک پراکسی محلی را شروع کنند، یک فرمان فرزند را
با ثبت فعال اجرا کنند، نشست‌های ثبت را فهرست کنند، الگوهای رایج ترافیک را پرس‌وجو کنند، blobهای
ثبت‌شده را بخوانند، و داده‌های ثبت محلی را پاک‌سازی کنند.
## فرمان‌ها
@ -35,17 +40,23 @@ openclaw proxy purge
## اعتبارسنجی
`openclaw proxy validate` نشانی مؤثر پراکسی تحت مدیریت اپراتور را از `--proxy-url`، پیکربندی، یا `OPENCLAW_PROXY_URL` بررسی می‌کند. وقتی هیچ پراکسی‌ای فعال و پیکربندی نشده باشد، یک مشکل پیکربندی گزارش می‌کند؛ برای یک پیش‌بررسی موردی پیش از تغییر پیکربندی، از `--proxy-url` استفاده کنید. به‌طور پیش‌فرض بررسی می‌کند که یک مقصد عمومی از طریق پراکسی موفق شود و پراکسی نتواند به یک قناری موقت loopback دسترسی پیدا کند. مقصدهای ردشده سفارشی fail-closed هستند: پاسخ‌های HTTP و خطاهای مبهم انتقال هر دو ناموفق محسوب می‌شوند، مگر اینکه بتوانید یک سیگنال رد دسترسی ویژه استقرار را جداگانه تأیید کنید.
`openclaw proxy validate` نشانی URL مؤثر پراکسیِ مدیریت‌شده توسط راهبر را از
`--proxy-url`، پیکربندی، یا `OPENCLAW_PROXY_URL` بررسی می‌کند. وقتی
هیچ پراکسی‌ای فعال و پیکربندی نشده باشد، یک مشکل پیکربندی گزارش می‌دهد؛ برای یک پیش‌بررسی موردی
پیش از تغییر پیکربندی، از `--proxy-url` استفاده کنید. به‌طور پیش‌فرض، بررسی می‌کند که یک مقصد عمومی
از طریق پراکسی موفق شود و پراکسی نتواند به یک کاناری موقت بازگشت محلی دسترسی پیدا کند.
مقصدهای ردشده سفارشی fail-closed هستند: پاسخ‌های HTTP و خطاهای مبهم انتقال
هر دو شکست محسوب می‌شوند، مگر اینکه بتوانید یک سیگنال ردشدن مخصوص استقرار را جداگانه تأیید کنید.
گزینه‌ها:
- `--json`: JSON قابل خواندن توسط ماشین را چاپ می‌کند.
- `--proxy-url <url>`: این نشانی پراکسی را به‌جای پیکربندی یا env اعتبارسنجی می‌کند.
- `--allowed-url <url>`: مقصدی را اضافه می‌کند که انتظار می‌رود از طریق پراکسی موفق شود. برای بررسی چند مقصد، تکرار کنید.
- `--denied-url <url>`: مقصدی را اضافه می‌کند که انتظار می‌رود توسط پراکسی مسدود شود. برای بررسی چند مقصد، تکرار کنید.
- `--json`: JSON قابل‌خواندن توسط ماشین چاپ می‌کند.
- `--proxy-url <url>`: این URL پراکسی را به‌جای پیکربندی یا env اعتبارسنجی می‌کند.
- `--allowed-url <url>`: مقصدی را اضافه می‌کند که انتظار می‌رود از طریق پراکسی موفق شود. برای بررسی چند مقصد تکرار کنید.
- `--denied-url <url>`: مقصدی را اضافه می‌کند که انتظار می‌رود توسط پراکسی مسدود شود. برای بررسی چند مقصد تکرار کنید.
- `--timeout-ms <ms>`: مهلت زمانی هر درخواست بر حسب میلی‌ثانیه.
برای راهنمایی استقرار و معناشناسی رد دسترسی، [پراکسی شبکه](/fa/security/network-proxy) را ببینید.
برای راهنمای استقرار و معناشناسی ردشدن، [پراکسی شبکه](/fa/security/network-proxy) را ببینید.
## پیش‌تنظیم‌های پرس‌وجو
@ -58,15 +69,16 @@ openclaw proxy purge
- `missing-ack`
- `error-bursts`
## نکات
## یادداشت‌ها
- `start` به‌طور پیش‌فرض از `127.0.0.1` استفاده می‌کند، مگر اینکه `--host` تنظیم شده باشد.
- `run` یک پراکسی اشکال‌زدایی محلی را شروع می‌کند و سپس فرمان پس از `--` را اجرا می‌کند.
- `validate` وقتی پیکربندی پراکسی یا بررسی‌های مقصد ناموفق شوند، با کد 1 خارج می‌شود.
- ضبط‌ها داده‌های اشکال‌زدایی محلی هستند؛ پس از اتمام کار از `openclaw proxy purge` استفاده کنید.
- `run` یک پراکسی اشکال‌زدایی محلی را شروع می‌کند و سپس فرمان بعد از `--` را اجرا می‌کند.
- ارسال مستقیم به upstream در پراکسی اشکال‌زدایی، سوکت‌های upstream را برای عیب‌یابی باز می‌کند. وقتی حالت پراکسی مدیریت‌شده OpenClaw فعال باشد، ارسال مستقیم برای درخواست‌های پراکسی و تونل‌های CONNECT به‌طور پیش‌فرض غیرفعال است؛ `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` را فقط برای عیب‌یابی محلی تأییدشده تنظیم کنید.
- `validate` وقتی پیکربندی پراکسی یا بررسی‌های مقصد شکست بخورند، با کد 1 خارج می‌شود.
- ثبت‌ها داده‌های اشکال‌زدایی محلی هستند؛ پس از پایان کار از `openclaw proxy purge` استفاده کنید.
## مرتبط
- [مرجع CLI](/fa/cli)
- [پراکسی شبکه](/fa/security/network-proxy)
- [احراز هویت پراکسی معتمد](/fa/gateway/trusted-proxy-auth)
- [احراز هویت پراکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth)

83
docs/fa/cli/sessions.md
View File

@ -1,28 +1,34 @@
---
read_when:
- می‌خواهید جلسات ذخیره‌شده را فهرست کنید و فعالیت اخیر را ببینید
summary: مرجع CLI برای `openclaw sessions` (فهرست کردن نشست‌های ذخیره‌شده + نحوه استفاده)
- می‌خواهید نشست‌های ذخیره‌شده را فهرست کنید و فعالیت‌های اخیر را ببینید
summary: مرجع CLI برای `openclaw sessions` (فهرست‌کردن نشست‌های ذخیره‌شده + نحوه استفاده)
title: نشست‌ها
x-i18n:
generated_at: "2026-05-02T20:42:20Z"
generated_at: "2026-05-04T07:02:44Z"
model: gpt-5.5
provider: openai
source_hash: 5c9ec3ca55f7c5b6217b481e9da62f5416df73e69405a0dc15e77d2afeac723f
source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e
source_path: cli/sessions.md
workflow: 16
---
# `openclaw sessions`
نشست‌های مکالمه ذخیره‌شده را فهرست کنید.
نشست‌های گفت‌وگوی ذخیره‌شده را فهرست کنید.
فهرست‌های نشست، بررسی زنده‌بودن کانال/ارائه‌دهنده نیستند. آن‌ها ردیف‌های
مکالمه پایدارشده را از ذخیره‌گاه‌های نشست نشان می‌دهند. یک کانال ساکت Discord،
Slack، Telegram یا کانالی دیگر می‌تواند بدون ایجاد ردیف نشست جدید، تا زمانی که
پیامی پردازش شود، با موفقیت دوباره وصل شود. وقتی به اتصال زنده کانال نیاز دارید،
از `openclaw channels status --probe`،‏ `openclaw status --deep` یا
فهرست‌های نشست، بررسی زنده‌بودن کانال/ارائه‌دهنده نیستند. آن‌ها ردیف‌های گفت‌وگوی
ماندگارشده از مخزن‌های نشست را نشان می‌دهند. یک Discord، Slack، Telegram یا
کانال دیگرِ ساکت می‌تواند بدون ایجاد ردیف نشست جدید با موفقیت دوباره وصل شود
تا زمانی که پیامی پردازش شود. وقتی به اتصال زندهٔ کانال نیاز دارید از
`openclaw channels status --probe`، `openclaw status --deep` یا
`openclaw health --verbose` استفاده کنید.
پاسخ‌های Gateway `sessions.list` به‌طور پیش‌فرض محدود هستند تا مخزن‌های بزرگ و
دیرپا نتوانند حلقهٔ رویداد Gateway را در انحصار بگیرند. وقتی بازهٔ نتیجهٔ
متفاوتی لازم است، از کلاینت‌های RPC یک `limit` مثبت و صریح ارسال کنید؛ پاسخ‌ها
وقتی فراخوان‌ها نیاز داشته باشند نشان دهند ردیف‌های بیشتری وجود دارد، شامل
`totalCount`، `limitApplied` و `hasMore` هستند.
```bash
openclaw sessions
openclaw sessions --agent work
@ -34,29 +40,28 @@ openclaw sessions --json
انتخاب دامنه:
- پیش‌فرض: ذخیره‌گاه عامل پیش‌فرض پیکربندی‌شده
- `--verbose`: ثبت گزارش تفصیلی
- `--agent <id>`: یک ذخیره‌گاه عامل پیکربندی‌شده
- `--all-agents`: تجمیع همه ذخیره‌گاه‌های عامل پیکربندی‌شده
- `--store <path>`: مسیر صریح ذخیره‌گاه (نمی‌تواند با `--agent` یا `--all-agents` ترکیب شود)
- پیش‌فرض: مخزن عامل پیش‌فرض پیکربندی‌شده
- `--verbose`: گزارش‌گیری پرجزئیات
- `--agent <id>`: یک مخزن عامل پیکربندی‌شده
- `--all-agents`: تجمیع همهٔ مخزن‌های عامل پیکربندی‌شده
- `--store <path>`: مسیر صریح مخزن (نمی‌توان آن را با `--agent` یا `--all-agents` ترکیب کرد)
یک بسته مسیر اجرا برای یک نشست ذخیره‌شده صادر کنید:
یک بستهٔ مسیر اجرا را برای یک نشست ذخیره‌شده صادر کنید:
```bash
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
```
این همان مسیر دستوری است که پس از تایید درخواست اجرا توسط مالک، توسط دستور اسلش
`/export-trajectory` استفاده می‌شود. دایرکتوری خروجی همیشه داخل
`.openclaw/trajectory-exports/` زیر فضای کاری انتخاب‌شده resolve می‌شود.
این همان مسیر فرمانی است که فرمان اسلش `/export-trajectory` پس از تأیید درخواست
اجرایی توسط مالک استفاده می‌کند. پوشهٔ خروجی همیشه داخل
`.openclaw/trajectory-exports/` در فضای کاری انتخاب‌شده resolve می‌شود.
`openclaw sessions --all-agents` ذخیره‌گاه‌های عامل پیکربندی‌شده را می‌خواند.
کشف نشست Gateway و ACP گسترده‌تر است: آن‌ها ذخیره‌گاه‌های فقط-دیسک را هم که زیر
ریشه پیش‌فرض `agents/` یا ریشه قالب‌دار `session.store` پیدا می‌شوند شامل
می‌کنند. این ذخیره‌گاه‌های کشف‌شده باید به فایل‌های معمولی `sessions.json` داخل
ریشه عامل resolve شوند؛ پیوندهای نمادین و مسیرهای خارج از ریشه نادیده گرفته
می‌شوند.
`openclaw sessions --all-agents` مخزن‌های عامل پیکربندی‌شده را می‌خواند. کشف
نشست در Gateway و ACP گسترده‌تر است: آن‌ها مخزن‌های فقط-دیسکی پیدا‌شده زیر ریشهٔ
پیش‌فرض `agents/` یا یک ریشهٔ قالب‌بندی‌شدهٔ `session.store` را هم شامل می‌شوند.
آن مخزن‌های کشف‌شده باید به فایل‌های عادی `sessions.json` داخل ریشهٔ عامل resolve
شوند؛ symlinkها و مسیرهای بیرون از ریشه نادیده گرفته می‌شوند.
نمونه‌های JSON:
@ -79,9 +84,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12
}
```
## نگه‌داری پاک‌سازی
## نگهداری پاک‌سازی
نگه‌داری را اکنون اجرا کنید (به‌جای انتظار برای چرخه نوشتن بعدی):
همین حالا نگهداری را اجرا کنید (به‌جای انتظار برای چرخهٔ نوشتن بعدی):
```bash
openclaw sessions cleanup --dry-run
@ -94,22 +99,22 @@ openclaw sessions cleanup --json
`openclaw sessions cleanup` از تنظیمات `session.maintenance` در پیکربندی استفاده می‌کند:
- نکته دامنه: `openclaw sessions cleanup` ذخیره‌گاه‌های نشست، transcriptها و فایل‌های جانبی مسیر اجرا را نگه‌داری می‌کند. این دستور گزارش‌های اجرای cron (`cron/runs/<jobId>.jsonl`) را هرس نمی‌کند؛ آن‌ها توسط `cron.runLog.maxBytes` و `cron.runLog.keepLines` در [پیکربندی Cron](/fa/automation/cron-jobs#configuration) مدیریت می‌شوند و در [نگه‌داری Cron](/fa/automation/cron-jobs#maintenance) توضیح داده شده‌اند.
- نکتهٔ دامنه: `openclaw sessions cleanup` مخزن‌های نشست، رونوشت‌ها و sidecarهای مسیر اجرا را نگهداری می‌کند. این فرمان گزارش‌های اجرای cron را (`cron/runs/<jobId>.jsonl`) هرس نمی‌کند؛ این گزارش‌ها با `cron.runLog.maxBytes` و `cron.runLog.keepLines` در [پیکربندی Cron](/fa/automation/cron-jobs#configuration) مدیریت می‌شوند و در [نگهداری Cron](/fa/automation/cron-jobs#maintenance) توضیح داده شده‌اند.
- `--dry-run`: پیش‌نمایش تعداد ورودی‌هایی که بدون نوشتن هرس/محدود می‌شوند.
- در حالت متنی، dry-run یک جدول اقدام برای هر نشست چاپ می‌کند (`Action`، `Key`، `Age`، `Model`، `Flags`) تا بتوانید ببینید چه چیزی نگه داشته می‌شود و چه چیزی حذف می‌شود.
- `--enforce`: نگه‌داری را حتی وقتی `session.maintenance.mode` برابر `warn` است اعمال می‌کند.
- `--fix-missing`: ورودی‌هایی را که فایل‌های transcript آن‌ها گم شده‌اند حذف می‌کند، حتی اگر به طور عادی هنوز از نظر سن/تعداد مشمول حذف نمی‌شدند.
- `--active-key <key>`: از یک کلید فعال مشخص در برابر تخلیه ناشی از بودجه دیسک محافظت می‌کند. اشاره‌گرهای بادوام مکالمه خارجی، مانند نشست‌های گروهی و نشست‌های گفت‌وگوی محدود به thread، نیز توسط نگه‌داری سن/تعداد/بودجه دیسک نگه داشته می‌شوند.
- `--agent <id>`: پاک‌سازی را برای یک ذخیره‌گاه عامل پیکربندی‌شده اجرا می‌کند.
- `--all-agents`: پاک‌سازی را برای همه ذخیره‌گاه‌های عامل پیکربندی‌شده اجرا می‌کند.
- `--store <path>`: روی یک فایل `sessions.json` مشخص اجرا می‌کند.
- `--json`: خلاصه JSON چاپ می‌کند. با `--all-agents`، خروجی شامل یک خلاصه برای هر ذخیره‌گاه است.
- `--enforce`: نگهداری را حتی وقتی `session.maintenance.mode` برابر `warn` است اعمال می‌کند.
- `--fix-missing`: ورودی‌هایی را که فایل‌های رونوشتشان وجود ندارد حذف می‌کند، حتی اگر معمولاً هنوز به دلیل سن/تعداد حذف نمی‌شدند.
- `--active-key <key>`: از یک کلید فعال مشخص در برابر تخلیهٔ بودجهٔ دیسک محافظت می‌کند. اشاره‌گرهای بادوام گفت‌وگوی خارجی، مانند نشست‌های گروهی و نشست‌های گفت‌وگوی محدود به thread، نیز توسط نگهداری سن/تعداد/بودجهٔ دیسک نگه داشته می‌شوند.
- `--agent <id>`: پاک‌سازی را برای یک مخزن عامل پیکربندی‌شده اجرا می‌کند.
- `--all-agents`: پاک‌سازی را برای همهٔ مخزن‌های عامل پیکربندی‌شده اجرا می‌کند.
- `--store <path>`: روی یک فایل مشخص `sessions.json` اجرا می‌شود.
- `--json`: خلاصهٔ JSON چاپ می‌کند. با `--all-agents`، خروجی شامل یک خلاصه برای هر مخزن است.
وقتی یک Gateway در دسترس باشد، پاک‌سازی غیر dry-run برای ذخیره‌گاه‌های عامل
پیکربندی‌شده از طریق Gateway فرستاده می‌شود تا همان نویسنده ذخیره‌گاه نشست
را که ترافیک زمان اجرا استفاده می‌کند به اشتراک بگذارد. برای تعمیر آفلاین صریح
یک فایل ذخیره‌گاه، از `--store <path>` استفاده کنید.
وقتی یک Gateway در دسترس باشد، پاک‌سازی غیر dry-run برای مخزن‌های عامل
پیکربندی‌شده از طریق Gateway ارسال می‌شود تا از همان نویسندهٔ مخزن نشستِ ترافیک
زمان اجرا استفاده کند. برای تعمیر آفلاین صریحِ یک فایل مخزن از `--store <path>`
استفاده کنید.
`openclaw sessions cleanup --all-agents --dry-run --json`:

359
docs/fa/concepts/mantis.md
View File

@ -1,58 +1,58 @@
---
read_when:
- ساخت یا اجرای کنترل کیفیت بصری زنده برای باگ‌های OpenClaw
- ساخت یا اجرای تضمین کیفیت بصری زنده برای باگ‌های OpenClaw
- افزودن راستی‌آزمایی قبل و بعد برای یک درخواست کشش
- افزودن Discord، Slack، WhatsApp یا سناریوهای انتقال زندهٔ دیگر
- اشکال‌زدایی اجراهای تضمین کیفیت که به نماگرفت‌ها، خودکارسازی مرورگر یا دسترسی VNC نیاز دارند
summary: Mantis سامانهٔ تأیید بصری سرتاسری برای بازتولید باگ‌های OpenClaw روی انتقال‌دهنده‌های زنده، ثبت شواهد قبل و بعد، و پیوست کردن مصنوعات به درخواست‌های کشش است.
- افزودن Discord، Slack، WhatsApp یا سناریوهای ترابری زندهٔ دیگر
- اشکال‌زدایی اجراهای QA که به اسکرین‌شات، خودکارسازی مرورگر یا دسترسی VNC نیاز دارند
summary: Mantis سامانهٔ راستی‌آزمایی بصری سرتاسری برای بازتولید باگ‌های OpenClaw روی بسترهای انتقال زنده، ثبت شواهد قبل و بعد، و پیوست کردن آرتیفکت‌ها به PRها است.
title: آخوندک
x-i18n:
generated_at: "2026-05-04T02:23:59Z"
generated_at: "2026-05-04T07:03:13Z"
model: gpt-5.5
provider: openai
source_hash: 5a86ab4bc876d1c53ada1c30580034165f028194a072f559eb54a898a369211d
source_hash: 9d3f3fa3db111b1b5c85f8efeccd749fbd5885cee6b7843ca4c8d049acfd9164
source_path: concepts/mantis.md
workflow: 16
---
Mantis سامانهٔ راستی‌آزمایی سرتاسری OpenClaw برای باگ‌هایی است که به runtime واقعی، transport واقعی و اثبات دیداری نیاز دارند. این سامانه یک سناریو را روی یک ref خرابِ شناخته‌شده اجرا می‌کند، شواهد را ثبت می‌کند، همان سناریو را روی یک ref نامزد اجرا می‌کند، و مقایسه را به‌صورت artifactهایی منتشر می‌کند که یک نگه‌دارنده می‌تواند از یک PR یا از یک فرمان محلی بررسی کند.
Mantis سامانه راستی‌آزمایی سرتاسری OpenClaw برای باگ‌هایی است که به runtime واقعی، transport واقعی و شواهد قابل مشاهده نیاز دارند. این سامانه یک سناریو را روی ref شناخته‌شده معیوب اجرا می‌کند، شواهد را ثبت می‌کند، همان سناریو را روی ref نامزد اجرا می‌کند و مقایسه را به‌صورت artifacts منتشر می‌کند تا نگه‌دارنده بتواند آن را از یک PR یا از یک فرمان محلی بررسی کند.
Mantis با Discord شروع می‌شود، چون Discord یک مسیر اولیهٔ بسیار ارزشمند در اختیار ما می‌گذارد: احراز هویت واقعی bot، کانال‌های واقعی guild، واکنش‌ها، threadها، فرمان‌های بومی، و یک رابط کاربری مرورگر که انسان‌ها می‌توانند در آن به‌صورت دیداری تأیید کنند transport چه چیزی را نشان داده است.
Mantis با Discord شروع می‌شود چون Discord یک مسیر نخست با ارزش بالا در اختیار ما می‌گذارد: احراز هویت واقعی بات، کانال‌های واقعی guild، reactionها، threadها، فرمان‌های بومی و یک رابط کاربری مرورگر که انسان‌ها می‌توانند در آن به‌صورت بصری تأیید کنند transport چه چیزی نشان داده است.
## اهداف
- بازتولید یک باگ از یک issue یا PR در GitHub با همان شکل transport که کاربران می‌بینند.
- ثبت یک artifact **قبل** روی ref مبنا پیش از اعمال اصلاح.
- ثبت یک artifact **بعد** روی ref نامزد پس از اعمال اصلاح.
- استفاده از oracle قطعی هر زمان ممکن باشد، مانند خواندن واکنش با Discord REST یا بررسی رونوشت کانال.
- استفاده از oracle قطعی هر زمان ممکن باشد، مانند خواندن reaction با Discord REST یا بررسی transcript کانال.
- ثبت screenshotها وقتی باگ سطح رابط کاربری قابل مشاهده دارد.
- اجرای محلی از یک CLI کنترل‌شده توسط agent و اجرای راه‌دور از GitHub.
- حفظ وضعیت کافی از ماشین برای نجات با VNC وقتی ورود، خودکارسازی مرورگر، یا احراز هویت provider گیر می‌کند.
- ارسال وضعیت کوتاه به یک کانال Discord عملیاتی وقتی اجرا مسدود شده، به کمک دستی VNC نیاز دارد، یا تمام می‌شود.
- اجرای محلی از یک CLI تحت کنترل agent و اجرای راه دور از GitHub.
- حفظ وضعیت کافی ماشین برای نجات با VNC وقتی ورود، خودکارسازی مرورگر یا احراز هویت provider گیر می‌کند.
- ارسال وضعیت مختصر به یک کانال Discord اپراتور وقتی اجرا مسدود شده، به کمک دستی VNC نیاز دارد یا تمام می‌شود.
## غیرهدف‌ها
- Mantis جایگزین تست‌های واحد نیست. اجرای Mantis معمولاً باید پس از فهمیدن اصلاح، به یک تست regression کوچک‌تر تبدیل شود.
- Mantis دروازهٔ CI سریع معمول نیست. کندتر است، از credentialهای زنده استفاده می‌کند، و برای باگ‌هایی نگه داشته می‌شود که محیط زنده در آن‌ها مهم است.
- Mantis نباید برای عملیات عادی به انسان نیاز داشته باشد. VNC دستی مسیر نجات است، نه مسیر مطلوب.
- Mantis secretهای خام را در artifactها، logها، screenshotها، گزارش‌های Markdown، یا دیدگاه‌های PR ذخیره نمی‌کند.
- Mantis جایگزین unit testها نیست. اجرای Mantis معمولاً پس از فهمیدن اصلاح باید به یک regression test کوچک‌تر تبدیل شود.
- Mantis gate سریع و معمول CI نیست. کندتر است، از اعتبارنامه‌های زنده استفاده می‌کند و برای باگ‌هایی نگه داشته می‌شود که محیط زنده در آن‌ها مهم است.
- Mantis نباید برای عملکرد عادی به انسان نیاز داشته باشد. VNC دستی مسیر نجات است، نه مسیر مطلوب.
- Mantis secretهای خام را در artifacts، logها، screenshotها، گزارش‌های Markdown یا دیدگاه‌های PR ذخیره نمی‌کند.
## مالکیت
Mantis در پشتهٔ QA OpenClaw قرار دارد.
Mantis در پشته QA OpenClaw قرار دارد.
- OpenClaw مالک runtime سناریو، adapterهای transport، schema شواهد، و CLI محلی زیر `pnpm openclaw qa mantis` است.
- QA Lab مالک قطعه‌های harness مربوط به transport زنده، helperهای ثبت مرورگر، و writerهای artifact است.
- Crabbox مالک ماشین‌های Linux گرم‌شده وقتی به VM راه‌دور نیاز باشد است.
- GitHub Actions مالک نقطهٔ ورود workflow راه‌دور و نگه‌داری artifact است.
- ClawSweeper مالک مسیریابی دیدگاه‌های GitHub است: parse کردن فرمان‌های نگه‌دارنده، dispatch کردن workflow، و ارسال دیدگاه نهایی PR.
- agentهای OpenClaw وقتی یک سناریو به راه‌اندازی agentic، اشکال‌زدایی، یا گزارش وضعیت گیرکرده نیاز دارد، Mantis را از طریق Codex هدایت می‌کنند.
- OpenClaw مالک runtime سناریو، adapterهای transport، schema شواهد و CLI محلی زیر `pnpm openclaw qa mantis` است.
- QA Lab مالک قطعات harness مربوط به transport زنده، helperهای ثبت مرورگر و نویسنده‌های artifact است.
- Crabbox مالک ماشین‌های Linux گرم‌شده است وقتی به VM راه دور نیاز باشد.
- GitHub Actions مالک نقطه ورود workflow راه دور و نگه‌داری artifact است.
- ClawSweeper مالک مسیریابی دیدگاه‌های GitHub است: parse کردن فرمان‌های نگه‌دارنده، dispatch کردن workflow و ارسال دیدگاه نهایی PR.
- agentهای OpenClaw وقتی یک سناریو به راه‌اندازی agentic، debugging یا گزارش وضعیت گیرکرده نیاز دارد، Mantis را از طریق Codex هدایت می‌کنند.
این مرز دانش transport را در OpenClaw، زمان‌بندی ماشین را در Crabbox، و چسب workflow نگه‌دارنده را در ClawSweeper نگه می‌دارد.
این مرز، دانش transport را در OpenClaw، زمان‌بندی ماشین را در Crabbox و چسب workflow نگه‌دارنده را در ClawSweeper نگه می‌دارد.
## شکل فرمان
نخستین فرمان محلی، bot در Discord، guild، کانال، ارسال پیام، ارسال واکنش، و مسیر artifact را راستی‌آزمایی می‌کند:
نخستین فرمان محلی، بات Discord، guild، کانال، ارسال پیام، ارسال reaction و مسیر artifact را راستی‌آزمایی می‌کند:
```bash
pnpm openclaw qa mantis discord-smoke \
@ -70,7 +70,7 @@ pnpm openclaw qa mantis run \
--output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions
```
runner زیر دایرکتوری خروجی، worktreeهای جداشدهٔ baseline و candidate می‌سازد، وابستگی‌ها را نصب می‌کند، هر ref را build می‌کند، سناریو را با `--allow-failures` اجرا می‌کند، سپس `baseline/`، `candidate/`، `comparison.json`، و `mantis-report.md` را می‌نویسد. برای نخستین سناریوی Discord، راستی‌آزمایی موفق یعنی وضعیت baseline برابر `fail` و وضعیت candidate برابر `pass` است.
runner، worktreeهای detached مبنا و نامزد را زیر دایرکتوری خروجی می‌سازد، dependencyها را نصب می‌کند، هر ref را build می‌کند، سناریو را با `--allow-failures` اجرا می‌کند، سپس `baseline/`، `candidate/`، `comparison.json` و `mantis-report.md` را می‌نویسد. برای نخستین سناریوی Discord، راستی‌آزمایی موفق یعنی وضعیت مبنا `fail` و وضعیت نامزد `pass` است.
نخستین primitive مربوط به VM/مرورگر، smoke دسکتاپ است:
@ -79,22 +79,55 @@ pnpm openclaw qa mantis desktop-browser-smoke \
--output-dir .artifacts/qa-e2e/mantis/desktop-browser
```
این فرمان یک ماشین دسکتاپ Crabbox را اجاره می‌کند یا دوباره به‌کار می‌گیرد، یک مرورگر قابل مشاهده را داخل نشست VNC شروع می‌کند، دسکتاپ را ثبت می‌کند، artifactها را به دایرکتوری خروجی محلی برمی‌گرداند، و فرمان reconnect را داخل گزارش می‌نویسد. فرمان به‌صورت پیش‌فرض از provider Hetzner استفاده می‌کند، چون نخستین provider با پوشش کارآمد دسکتاپ/VNC در مسیر Mantis است. هنگام اجرا روی fleet دیگری از Crabbox، آن را با `--provider`، `--crabbox-bin`، یا `OPENCLAW_MANTIS_CRABBOX_PROVIDER` override کنید.
این فرمان یک ماشین دسکتاپ Crabbox را lease یا بازاستفاده می‌کند، مرورگری قابل مشاهده را داخل نشست VNC شروع می‌کند، دسکتاپ را ثبت می‌کند، artifacts را به دایرکتوری خروجی محلی برمی‌گرداند و فرمان reconnect را در گزارش می‌نویسد. فرمان به‌صورت پیش‌فرض از provider Hetzner استفاده می‌کند چون نخستین provider با پوشش دسکتاپ/VNC فعال در مسیر Mantis است. هنگام اجرا روی fleet دیگری از Crabbox، آن را با `--provider`، `--crabbox-bin` یا `OPENCLAW_MANTIS_CRABBOX_PROVIDER` override کنید.
flagهای مفید smoke دسکتاپ:
- `--lease-id <cbx_...>` یا `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` یک دسکتاپ گرم‌شده را دوباره به‌کار می‌گیرد.
- `--lease-id <cbx_...>` یا `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` یک دسکتاپ گرم‌شده را بازاستفاده می‌کند.
- `--browser-url <url>` صفحه‌ای را که در مرورگر قابل مشاهده باز می‌شود تغییر می‌دهد.
- `--html-file <path>` یک artifact HTML محلی repo را در مرورگر قابل مشاهده render می‌کند. Mantis از این برای ثبت timeline تولیدشدهٔ واکنش‌های وضعیت Discord از طریق یک دسکتاپ واقعی Crabbox استفاده می‌کند.
- `--keep-lease` یا `OPENCLAW_MANTIS_KEEP_VM=1` یک lease تازه‌ساخته و موفق را برای بررسی VNC باز نگه می‌دارد. اجراهای ناموفق وقتی lease ساخته شده باشد به‌صورت پیش‌فرض آن را نگه می‌دارند تا یک operator بتواند دوباره وصل شود.
- `--class`، `--idle-timeout`، و `--ttl` اندازهٔ ماشین و طول عمر lease را تنظیم می‌کنند.
- `--html-file <path>` یک artifact HTML محلی repo را در مرورگر قابل مشاهده render می‌کند. Mantis از این برای ثبت timeline تولیدشده reactionهای وضعیت Discord از طریق یک دسکتاپ واقعی Crabbox استفاده می‌کند.
- `--keep-lease` یا `OPENCLAW_MANTIS_KEEP_VM=1` یک lease تازه‌ساخته و موفق را برای بررسی VNC باز نگه می‌دارد. اجراهای ناموفق به‌صورت پیش‌فرض وقتی lease ساخته شده باشد آن را نگه می‌دارند تا اپراتور بتواند دوباره وصل شود.
- `--class`، `--idle-timeout` و `--ttl` اندازه ماشین و عمر lease را تنظیم می‌کنند.
workflow smoke در GitHub برابر `Mantis Discord Smoke` است. workflow قبل و بعد GitHub برای نخستین سناریوی واقعی برابر `Mantis Discord Status Reactions` است. این workflow موارد زیر را می‌پذیرد:
نخستین primitive کامل transport دسکتاپ، smoke دسکتاپ Slack است:
- `baseline_ref`: همان ref که انتظار می‌رود رفتار فقط queued را بازتولید کند.
- `candidate_ref`: همان ref که انتظار می‌رود `queued -> thinking -> done` را نشان دهد.
```bash
pnpm openclaw qa mantis slack-desktop-smoke \
--output-dir .artifacts/qa-e2e/mantis/slack-desktop \
--gateway-setup \
--scenario slack-canary \
--keep-lease
```
این workflow، ref مربوط به harness workflow را checkout می‌کند، worktreeهای جداگانهٔ baseline و candidate را build می‌کند، `discord-status-reactions-tool-only` را روی هر worktree اجرا می‌کند، و `baseline/`، `candidate/`، `comparison.json`، و `mantis-report.md` را به‌عنوان artifactهای Actions upload می‌کند. همچنین HTML timeline هر مسیر را در مرورگر دسکتاپ Crabbox render می‌کند و آن screenshotهای VNC را کنار PNGهای قطعی timeline در دیدگاه PR منتشر می‌کند. workflow، CLI مربوط به Crabbox را از main در `openclaw/crabbox` build می‌کند تا بتواند از flagهای فعلی lease دسکتاپ/مرورگر پیش از انتشار binary بعدی Crabbox استفاده کند.
این فرمان یک ماشین دسکتاپ Crabbox را lease یا بازاستفاده می‌کند، checkout فعلی را داخل VM همگام می‌کند، `pnpm openclaw qa slack` را داخل آن VM اجرا می‌کند، Slack Web را در مرورگر VNC باز می‌کند، دسکتاپ قابل مشاهده را ثبت می‌کند و هم artifacts مربوط به Slack QA و هم screenshot مربوط به VNC را به دایرکتوری خروجی محلی کپی می‌کند. این نخستین شکل Mantis است که در آن Gateway متعلق به SUT OpenClaw و مرورگر هر دو داخل همان VM دسکتاپ Linux زندگی می‌کنند.
با `--gateway-setup`، فرمان یک خانه OpenClaw یک‌بارمصرف و پایدار در `$HOME/.openclaw-mantis/slack-openclaw` آماده می‌کند، پیکربندی Slack Socket Mode را برای کانال انتخاب‌شده patch می‌کند، `openclaw gateway run` را روی port `38973` شروع می‌کند و Chrome را در نشست VNC در حال اجرا نگه می‌دارد. این حالت «برایم یک دسکتاپ Linux با Slack و یک claw در حال اجرا بگذار» است؛ مسیر Slack QA بات‌به‌بات وقتی `--gateway-setup` حذف شود همچنان پیش‌فرض است.
ورودی‌های لازم برای `--credential-source env`:
- `OPENCLAW_QA_SLACK_CHANNEL_ID`
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN`
- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN`
- `OPENCLAW_LIVE_OPENAI_KEY` برای مسیر مدل راه دور. اگر فقط
`OPENAI_API_KEY` به‌صورت محلی تنظیم شده باشد، Mantis پیش از فراخوانی Crabbox آن را به `OPENCLAW_LIVE_OPENAI_KEY` map می‌کند تا forwarding envهای `OPENCLAW_*` در Crabbox بتواند آن را به VM منتقل کند.
flagهای مفید دسکتاپ Slack:
- `--lease-id <cbx_...>` اجرا را روی ماشینی تکرار می‌کند که اپراتور قبلاً از طریق VNC وارد Slack Web شده است.
- `--gateway-setup` به‌جای فقط اجرای مسیر QA بات‌به‌بات، یک Gateway پایدار OpenClaw Slack را در VM شروع می‌کند.
- `--slack-url <url>` یک URL مشخص Slack Web را باز می‌کند. بدون آن، Mantis وقتی token بات SUT موجود باشد، `https://app.slack.com/client/<team>/<channel>` را از Slack `auth.test` استخراج می‌کند.
- `--slack-channel-id <id>` allowlist کانال Slack را که setup مربوط به gateway استفاده می‌کند کنترل می‌کند.
- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` پروفایل پایدار Chrome داخل VM را کنترل می‌کند. پیش‌فرض `$HOME/.config/openclaw-mantis/slack-chrome-profile` است، پس ورود دستی Slack Web روی همان lease در اجراهای دوباره باقی می‌ماند.
- `--credential-source convex --credential-role ci` به‌جای tokenهای مستقیم env مربوط به Slack، از pool اعتبارنامه مشترک استفاده می‌کند.
- `--provider-mode`، `--model`، `--alt-model` و `--fast` به مسیر زنده Slack pass-through می‌شوند.
workflow smoke در GitHub برابر `Mantis Discord Smoke` است. workflow قبل و بعد در GitHub برای نخستین سناریوی واقعی برابر `Mantis Discord Status Reactions` است. این ورودی‌ها را می‌پذیرد:
- `baseline_ref`: refای که انتظار می‌رود رفتار فقط queued را بازتولید کند.
- `candidate_ref`: refای که انتظار می‌رود `queued -> thinking -> done` را نشان دهد.
این workflow، ref مربوط به harness workflow را checkout می‌کند، worktreeهای جداگانه مبنا و نامزد را build می‌کند، `discord-status-reactions-tool-only` را روی هر worktree اجرا می‌کند و `baseline/`، `candidate/`، `comparison.json` و `mantis-report.md` را به‌عنوان artifacts در Actions upload می‌کند. همچنین HTML مربوط به timeline هر مسیر را در یک مرورگر دسکتاپ Crabbox render می‌کند و آن screenshotهای VNC را کنار PNGهای deterministic timeline در دیدگاه PR منتشر می‌کند. workflow، CLI مربوط به Crabbox را از main در `openclaw/crabbox` build می‌کند تا بتواند پیش از انتشار binary بعدی Crabbox از flagهای فعلی lease دسکتاپ/مرورگر استفاده کند.
همچنین می‌توانید اجرای status-reactions را مستقیماً از یک دیدگاه PR trigger کنید:
@ -102,7 +135,7 @@ workflow smoke در GitHub برابر `Mantis Discord Smoke` است. workflow ق
@Mantis discord status reactions
```
trigger دیدگاه عمداً محدود است. فقط روی دیدگاه‌های pull request از کاربرانی با دسترسی write، maintain، یا admin اجرا می‌شود، و فقط درخواست‌های مربوط به واکنش وضعیت Discord را تشخیص می‌دهد. به‌صورت پیش‌فرض، از ref مبنای خرابِ شناخته‌شده و SHA مربوط به head فعلی PR به‌عنوان candidate استفاده می‌کند. نگه‌دارنده‌ها می‌توانند هر دو ref را override کنند:
trigger دیدگاه عمداً محدود است. فقط روی دیدگاه‌های pull request از کاربرانی با دسترسی write، maintain یا admin اجرا می‌شود و فقط درخواست‌های status-reaction مربوط به Discord را تشخیص می‌دهد. به‌صورت پیش‌فرض از ref مبنای شناخته‌شده معیوب و SHA فعلی head در PR به‌عنوان نامزد استفاده می‌کند. نگه‌دارنده‌ها می‌توانند هر کدام از refها را override کنند:
```text
@Mantis discord status reactions baseline=origin/main candidate=HEAD
@ -115,43 +148,43 @@ trigger دیدگاه عمداً محدود است. فقط روی دیدگاه‌
@clawsweeper verify e2e discord
```
فرمان اول صریح و متمرکز بر سناریو است. فرمان دوم می‌تواند بعداً یک PR یا issue را از روی labelها، فایل‌های تغییرکرده، و یافته‌های review در ClawSweeper به سناریوهای پیشنهادی Mantis نگاشت کند.
فرمان اول explicit و متمرکز بر سناریو است. فرمان دوم می‌تواند بعداً یک PR یا issue را از روی labelها، فایل‌های تغییریافته و یافته‌های review در ClawSweeper به سناریوهای پیشنهادی Mantis map کند.
## چرخهٔ اجرای
## چرخه عمر اجرا
1. دریافت credentialها.
2. تخصیص یا استفادهٔ دوباره از یک VM.
3. آماده‌سازی profile دسکتاپ/مرورگر وقتی سناریو به شواهد رابط کاربری نیاز دارد.
1. گرفتن اعتبارنامه‌ها.
2. تخصیص یا بازاستفاده از یک VM.
3. آماده‌سازی پروفایل دسکتاپ/مرورگر وقتی سناریو به شواهد UI نیاز دارد.
4. آماده‌سازی یک checkout تمیز برای ref مبنا.
5. نصب وابستگی‌ها و build فقط آنچه سناریو نیاز دارد.
6. شروع یک OpenClaw Gateway فرزند با دایرکتوری وضعیت ایزوله.
7. پیکربندی transport زنده، provider، model، و profile مرورگر.
8. اجرای سناریو و ثبت شواهد baseline.
5. نصب dependencyها و build کردن فقط آنچه سناریو نیاز دارد.
6. شروع یک Gateway فرزند OpenClaw با دایرکتوری وضعیت ایزوله.
7. پیکربندی transport زنده، provider، مدل و پروفایل مرورگر.
8. اجرای سناریو و ثبت شواهد مبنا.
9. توقف gateway و حفظ logها.
10. آماده‌سازی ref نامزد در همان VM.
11. اجرای همان سناریو و ثبت شواهد candidate.
12. مقایسهٔ نتایج oracle و شواهد دیداری.
13. نوشتن Markdown، JSON، logها، screenshotها، و artifactهای trace اختیاری.
14. upload کردن artifactهای GitHub Actions.
15. ارسال یک پیام وضعیت کوتاه در PR یا Discord.
11. اجرای همان سناریو و ثبت شواهد نامزد.
12. مقایسه نتایج oracle و شواهد بصری.
13. نوشتن Markdown، JSON، logها، screenshotها و artifacts اختیاری trace.
14. upload کردن artifacts در GitHub Actions.
15. ارسال یک پیام وضعیت مختصر در PR یا Discord.
سناریو باید بتواند به دو شکل متفاوت شکست بخورد:
سناریو باید بتواند به دو روش متفاوت fail شود:
- **بازتولید باگ**: baseline به شکل مورد انتظار شکست خورده است.
- **شکست harness**: راه‌اندازی محیط، credentialها، Discord API، مرورگر، یا provider پیش از معنادار شدن oracle باگ شکست خورده است.
- **باگ بازتولید شد**: مبنا به روش مورد انتظار fail شد.
- **شکست harness**: راه‌اندازی محیط، اعتبارنامه‌ها، Discord API، مرورگر یا provider پیش از معنادار شدن oracle باگ fail شد.
گزارش نهایی باید این موارد را جدا کند تا نگه‌دارنده‌ها محیط ناپایدار را با رفتار محصول اشتباه نگیرند.
## MVP در Discord
## Discord MVP
نخستین سناریو باید واکنش‌های وضعیت Discord را در کانال‌های guild هدف بگیرد، جایی که حالت تحویل پاسخ منبع `message_tool_only` است.
نخستین سناریو باید reactionهای وضعیت Discord را در کانال‌های guild هدف بگیرد، جایی که حالت تحویل پاسخ منبع `message_tool_only` است.
چرا seed خوبی برای Mantis است:
چرا بذر خوبی برای Mantis است:
- در Discord به‌صورت واکنش روی پیام triggerکننده قابل مشاهده است.
- از طریق وضعیت واکنش پیام Discord یک oracle قوی REST دارد.
- یک OpenClaw Gateway واقعی، احراز هویت bot در Discord، dispatch پیام، حالت تحویل پاسخ منبع، وضعیت واکنش وضعیت، و چرخهٔ عمر turn در model را تمرین می‌دهد.
- به‌اندازهٔ کافی محدود است تا نخستین پیاده‌سازی دقیق بماند.
- در Discord به‌صورت reaction روی پیام triggerکننده قابل مشاهده است.
- از طریق وضعیت reaction پیام در Discord یک oracle قوی REST دارد.
- یک Gateway واقعی OpenClaw، احراز هویت بات Discord، dispatch پیام، حالت تحویل پاسخ منبع، وضعیت reaction وضعیت و چرخه عمر turn مدل را تمرین می‌دهد.
- به‌اندازه کافی محدود است تا نخستین پیاده‌سازی را درست و صادق نگه دارد.
شکل مورد انتظار سناریو:
@ -184,9 +217,9 @@ evidence:
screenshotMessageRow: true
```
شواهد baseline باید واکنش acknowledgement مربوط به queued را نشان دهد اما در حالت tool-only هیچ transition چرخهٔ عمر نداشته باشد. شواهد candidate باید نشان دهد واکنش‌های وضعیت چرخهٔ عمر وقتی `messages.statusReactions.enabled` به‌صورت صریح true است اجرا می‌شوند.
شواهد مبنا باید reaction تأیید queued را نشان دهد اما در حالت فقط tool هیچ lifecycle transition نشان ندهد. شواهد نامزد باید نشان دهد که status reactionهای چرخه عمر وقتی `messages.statusReactions.enabled` صریحاً true است اجرا می‌شوند.
نخستین بخش اجرایی، سناریوی QA زندهٔ Discord به‌صورت opt-in است:
نخستین برش قابل اجرا، سناریوی opt-in زنده QA در Discord است:
```bash
pnpm openclaw qa discord \
@ -198,24 +231,32 @@ pnpm openclaw qa discord \
--output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate
```
این SUT را با رسیدگی همیشه‌روشن به guild، `visibleReplies:
"message_tool"`، `ackReaction: "👀"`، و واکنش‌های وضعیت صریح پیکربندی می‌کند. oracle پیام triggerکنندهٔ واقعی Discord را poll می‌کند و sequence مشاهده‌شدهٔ `👀 -> 🤔 -> 👍` را انتظار دارد. artifactها شامل `discord-qa-reaction-timelines.json`، `discord-status-reactions-tool-only-timeline.html`، و `discord-status-reactions-tool-only-timeline.png` هستند.
این کار SUT را با رسیدگی همیشه‌فعال به guild، `visibleReplies:
"message_tool"`، `ackReaction: "👀"` و واکنش‌های وضعیت صریح پیکربندی می‌کند. اوراکل
پیام محرک واقعی Discord را نظرسنجی می‌کند و انتظار دارد توالی مشاهده‌شده
`👀 -> 🤔 -> 👍` باشد. مصنوعات شامل `discord-qa-reaction-timelines.json`،
`discord-status-reactions-tool-only-timeline.html` و
`discord-status-reactions-tool-only-timeline.png` هستند.
## قطعه‌های موجود QA
## اجزای QA موجود
Mantis باید به‌جای شروع از صفر، روی پشتهٔ خصوصی QA موجود ساخته شود:
Mantis باید به‌جای شروع از صفر، بر پشته QA خصوصی موجود بنا شود:
- `pnpm openclaw qa discord` از قبل یک مسیر زندهٔ Discord را با botهای driver و SUT اجرا می‌کند.
- runner مربوط به transport زنده از قبل گزارش‌ها و artifactهای observed-message را زیر `.artifacts/qa-e2e/` می‌نویسد.
- leaseهای credential در Convex از قبل دسترسی انحصاری به credentialهای transport زندهٔ مشترک را فراهم می‌کنند.
- سرویس کنترل مرورگر از قبل از screenshotها، snapshotها، profileهای مدیریت‌شدهٔ headless، و profileهای CDP راه‌دور پشتیبانی می‌کند.
- QA Lab از قبل یک رابط کاربری debugger و bus برای تست‌هایی با شکل transport دارد.
- `pnpm openclaw qa discord` از قبل یک مسیر زنده Discord را با ربات‌های محرک و
SUT اجرا می‌کند.
- اجراکننده انتقال زنده از قبل گزارش‌ها و مصنوعات پیام مشاهده‌شده را زیر
`.artifacts/qa-e2e/` می‌نویسد.
- اجاره‌های اعتبارنامه Convex از قبل دسترسی انحصاری به اعتبارنامه‌های انتقال زنده مشترک را فراهم می‌کنند.
- سرویس کنترل مرورگر از قبل از نماگرفت‌ها، snapshotها،
پروفایل‌های مدیریت‌شده headless و پروفایل‌های CDP راه‌دور پشتیبانی می‌کند.
- QA Lab از قبل یک رابط کاربری اشکال‌زدا و گذرگاه برای آزمون‌هایی با شکل انتقال دارد.
نخستین پیاده‌سازی Mantis می‌تواند یک runner نازک قبل/بعد روی این قطعه‌ها، به‌علاوهٔ یک لایهٔ شواهد دیداری باشد.
پیاده‌سازی اول Mantis می‌تواند یک اجراکننده نازک قبل/بعد روی همین اجزا،
به‌علاوه یک لایه شواهد بصری باشد.
## مدل شواهد
هر اجرا یک دایرکتوری artifact پایدار می‌نویسد:
هر اجرا یک پوشه مصنوع پایدار می‌نویسد:
```text
.artifacts/qa-e2e/mantis/<run-id>/
@ -235,63 +276,77 @@ Mantis باید به‌جای شروع از صفر، روی پشتهٔ خصوص
run.log
```
`mantis-summary.json` باید منبع حقیقت machine-readable باشد. گزارش Markdown برای دیدگاه‌های PR و review انسانی است.
`mantis-summary.json` باید منبع حقیقت قابل‌خواندن برای ماشین باشد. گزارش
Markdown برای نظرهای PR و بازبینی انسانی است.
summary باید شامل این موارد باشد:
خلاصه باید شامل موارد زیر باشد:
- refها و SHAهای تست‌شده
- transport و شناسهٔ سناریو
- provider ماشین و شناسهٔ ماشین یا شناسهٔ lease
- منبع credential بدون مقادیر secret
- نتیجهٔ baseline
- نتیجهٔ candidate
- refها و SHAهای آزموده‌شده
- انتقال و شناسه سناریو
- ارائه‌دهنده ماشین و شناسه ماشین یا شناسه اجاره
- منبع اعتبارنامه بدون مقادیر محرمانه
- نتیجه baseline
- نتیجه candidate
- اینکه آیا باگ روی baseline بازتولید شد یا نه
- اینکه آیا candidate آن را اصلاح کرد یا نه
- مسیرهای artifact
- مشکلات setup یا cleanup پاک‌سازی‌شده
- اینکه آیا candidate آن را رفع کرد یا نه
- مسیرهای مصنوع
- مشکلات راه‌اندازی یا پاک‌سازی پالایش‌شده
screenshotها شواهد هستند، نه secret. بااین‌حال همچنان به انضباط redaction نیاز دارند: نام کانال‌های خصوصی، نام کاربران، یا محتوای پیام ممکن است ظاهر شود. برای PRهای عمومی، تا زمانی که داستان redaction قوی‌تر شود، linkهای artifact در GitHub Actions را به imageهای inline ترجیح دهید.
نماگرفت‌ها شواهد هستند، نه راز. بااین‌حال همچنان به انضباط ویرایش محرمانگی نیاز دارند:
نام کانال‌های خصوصی، نام کاربران یا محتوای پیام ممکن است ظاهر شود. برای PRهای عمومی،
تا زمانی که داستان ویرایش محرمانگی قوی‌تر نشده است، پیوندهای مصنوع GitHub Actions را
به تصویرهای درون‌خطی ترجیح دهید.
## مرورگر و VNC
مسیر مرورگر دو حالت دارد:
- **خودکارسازی headless**: پیش‌فرض برای CI. Chrome با CDP فعال اجرا می‌شود، و Playwright یا کنترل مرورگر OpenClaw screenshotها را ثبت می‌کند.
- **نجات با VNC**: روی همان VM فعال می‌شود وقتی ورود، MFA، ضدخودکارسازی Discord، یا اشکال‌زدایی دیداری به انسان نیاز دارد.
- **خودکارسازی headless**: پیش‌فرض برای CI. Chrome با CDP فعال اجرا می‌شود، و
Playwright یا کنترل مرورگر OpenClaw نماگرفت‌ها را ثبت می‌کند.
- **نجات VNC**: روی همان VM فعال می‌شود وقتی ورود، MFA، ضدخودکارسازی Discord،
یا اشکال‌زدایی بصری به انسان نیاز دارد.
پروفایل مرورگر ناظر Discord باید آن‌قدر پایدار باشد که برای هر اجرا نیاز به ورود دوباره نباشد، اما از وضعیت مرورگر شخصی جدا باشد. یک پروفایل به استخر ماشین Mantis تعلق دارد، نه به لپ‌تاپ یک توسعه‌دهنده.
پروفایل مرورگر ناظر Discord باید به‌اندازه‌ای پایدار باشد که برای هر اجرا نیاز به
ورود دوباره نباشد، اما از وضعیت مرورگر شخصی جدا باشد. یک پروفایل متعلق به مخزن ماشین
Mantis است، نه لپ‌تاپ توسعه‌دهنده.
وقتی Mantis گیر می‌کند، یک پیام وضعیت Discord ارسال می‌کند که شامل این موارد است:
وقتی Mantis گیر می‌کند، یک پیام وضعیت Discord با این موارد ارسال می‌کند:
- شناسه اجرا
- شناسه سناریو
- ارائه‌دهنده ماشین
- دایرکتوری آرتیفکت
- پوشه مصنوع
- دستورالعمل‌های اتصال VNC یا noVNC در صورت وجود
- متن کوتاه مانع
- متن کوتاه مسدودکننده
اولین استقرار خصوصی می‌تواند این پیام‌ها را در کانال فعلی اپراتورها ارسال کند و بعدا به یک کانال اختصاصی Mantis منتقل شود.
استقرار خصوصی اول می‌تواند این پیام‌ها را در کانال عملیاتی موجود ارسال کند و بعدا
به یک کانال اختصاصی Mantis منتقل شود.
## ماشین‌ها
Mantis باید برای اولین پیاده‌سازی راه‌دور، AWS از طریق Crabbox را ترجیح دهد. Crabbox ماشین‌های آماده، رهگیری اجاره، آماده‌سازی، لاگ‌ها، نتایج و پاک‌سازی را در اختیار ما می‌گذارد. اگر ظرفیت AWS بیش از حد کند یا ناموجود بود، یک ارائه‌دهنده Hetzner پشت همان رابط ماشین اضافه کنید.
Mantis باید برای اولین پیاده‌سازی راه‌دور، AWS از طریق Crabbox را ترجیح دهد.
Crabbox ماشین‌های آماده، رهگیری اجاره، آب‌رسانی، لاگ‌ها، نتایج و پاک‌سازی را در اختیارمان می‌گذارد.
اگر ظرفیت AWS بیش‌ازحد کند یا در دسترس نبود، یک ارائه‌دهنده Hetzner پشت همان
رابط ماشین اضافه کنید.
حداقل نیازمندی‌های VM:
حداقل الزامات VM:
- Linux با نصب Chrome یا Chromium که قابلیت دسکتاپ داشته باشد
- Linux با نصب Chrome یا Chromium مناسب دسکتاپ
- دسترسی CDP برای خودکارسازی مرورگر
- VNC یا noVNC برای بازیابی
- VNC یا noVNC برای نجات
- Node 22 و pnpm
- checkout از OpenClaw و کش وابستگی‌ها
- کش مرورگر Playwright Chromium وقتی از Playwright استفاده می‌شود
- checkout مربوط به OpenClaw و cache وابستگی‌ها
- cache مرورگر Playwright Chromium وقتی از Playwright استفاده می‌شود
- CPU و حافظه کافی برای یک OpenClaw Gateway، یک مرورگر، و یک اجرای مدل
- دسترسی خروجی به Discord، GitHub، ارائه‌دهندگان مدل، و کارگزار اعتبارنامه
VM نباید رازهای خام بلندمدت را بیرون از مخزن‌های مورد انتظار اعتبارنامه یا پروفایل مرورگر نگه دارد.
VM نباید رازهای خام بلندمدت را بیرون از مخزن‌های مورد انتظار اعتبارنامه یا
پروفایل مرورگر نگه دارد.
## رازها
رازها برای اجراهای راه‌دور در رازهای سازمان یا مخزن GitHub، و برای اجراهای محلی در یک فایل راز محلی تحت کنترل اپراتور نگهداری می‌شوند.
رازها برای اجراهای راه‌دور در رازهای سازمان یا مخزن GitHub، و برای اجراهای محلی در
یک فایل راز تحت کنترل اپراتور محلی قرار می‌گیرند.
نام‌های پیشنهادی رازها:
@ -301,34 +356,51 @@ VM نباید رازهای خام بلندمدت را بیرون از مخزن
- `OPENCLAW_QA_DISCORD_GUILD_ID`
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
- `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID`
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` برای بارگذاری آرتیفکت‌های عمومی GitHub
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` برای بارگذاری مصنوعات عمومی GitHub
- `OPENCLAW_QA_CONVEX_SITE_URL`
- `OPENCLAW_QA_CONVEX_SECRET_CI`
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR`
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN`
در بلندمدت، استخر اعتبارنامه Convex باید منبع عادی برای اعتبارنامه‌های انتقال زنده باقی بماند. رازهای GitHub کارگزار و مسیرهای fallback را راه‌اندازی اولیه می‌کنند. گردش‌کار واکنش‌های وضعیت Discord رازهای Mantis Crabbox را دوباره به متغیرهای محیطی `CRABBOX_COORDINATOR` و `CRABBOX_COORDINATOR_TOKEN` که CLI مربوط به Crabbox انتظار دارد نگاشت می‌کند. نام‌های ساده راز GitHub با الگوی `CRABBOX_*` همچنان به‌عنوان fallback سازگاری پذیرفته می‌شوند.
در بلندمدت، مخزن اعتبارنامه Convex باید منبع عادی اعتبارنامه‌های انتقال زنده باقی بماند.
رازهای GitHub کارگزار و مسیرهای fallback را راه‌اندازی اولیه می‌کنند.
گردش‌کار واکنش‌های وضعیت Discord رازهای Mantis Crabbox را دوباره به متغیرهای محیطی
`CRABBOX_COORDINATOR` و `CRABBOX_COORDINATOR_TOKEN` نگاشت می‌کند که CLI مربوط به Crabbox انتظار دارد.
نام‌های ساده راز GitHub با الگوی `CRABBOX_*` همچنان به‌عنوان fallback سازگاری پذیرفته می‌شوند.
اجراکننده Mantis هرگز نباید این موارد را چاپ کند:
اجراکننده Mantis هرگز نباید موارد زیر را چاپ کند:
- توکن‌های ربات Discord
- کلیدهای API ارائه‌دهنده
- کوکی‌های مرورگر
- cookieهای مرورگر
- محتوای پروفایل احراز هویت
- گذرواژه‌های VNC
- payloadهای خام اعتبارنامه
بارگذاری آرتیفکت‌های عمومی باید فراداده هدف Discord مانند شناسه‌های ربات، guild، کانال و پیام را نیز حذف کند. گردش‌کار smoke در GitHub به همین دلیل `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` را فعال می‌کند.
بارگذاری‌های مصنوع عمومی همچنین باید فراداده هدف Discord مانند شناسه‌های ربات،
guild، کانال و پیام را ویرایش محرمانه کنند. گردش‌کار smoke GitHub به همین دلیل
`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` را فعال می‌کند.
اگر یک توکن تصادفا در issue، PR، چت یا لاگ چسبانده شد، پس از ذخیره شدن راز جدید، آن را چرخش دهید.
اگر توکنی به‌طور تصادفی در یک issue، PR، chat یا log جای‌گذاری شد، پس از ذخیره شدن
راز جدید آن را بچرخانید.
## آرتیفکت‌های GitHub و دیدگاه‌های PR
## مصنوعات GitHub و نظرهای PR
گردش‌کارهای Mantis باید بسته کامل شواهد را به‌عنوان یک آرتیفکت کوتاه‌مدت Actions بارگذاری کنند. وقتی گردش‌کار برای یک گزارش باگ یا PR اصلاح اجرا می‌شود، باید اسکرین‌شات‌های PNG حذف‌اطلاعات‌شده را نیز در شاخه `qa-artifacts` منتشر کند و روی همان باگ یا PR اصلاح، یک دیدگاه با اسکرین‌شات‌های درون‌خطی قبل/بعد درج یا به‌روزرسانی کند. اثبات اصلی را فقط روی یک PR عمومی خودکارسازی QA منتشر نکنید. لاگ‌های خام، پیام‌های مشاهده‌شده و شواهد حجیم دیگر در آرتیفکت Actions باقی می‌مانند.
گردش‌کارهای Mantis باید بسته کامل شواهد را به‌عنوان یک مصنوع کوتاه‌عمر Actions
بارگذاری کنند. وقتی گردش‌کار برای گزارش باگ یا PR رفع اجرا می‌شود، باید
نماگرفت‌های PNG ویرایش محرمانه‌شده را نیز در شاخه `qa-artifacts` منتشر کند و
روی آن باگ یا PR رفع، نظری با نماگرفت‌های قبل/بعد درون‌خطی upsert کند. اثبات اصلی را
فقط روی یک PR عمومی خودکارسازی QA منتشر نکنید. لاگ‌های خام، پیام‌های مشاهده‌شده،
و شواهد حجیم دیگر در مصنوع Actions باقی می‌مانند.
گردش‌کارهای تولیدی باید این دیدگاه‌ها را با Mantis GitHub App ارسال کنند، نه با `github-actions[bot]`. شناسه app و کلید خصوصی را به‌عنوان رازهای GitHub Actions با نام‌های `MANTIS_GITHUB_APP_ID` و `MANTIS_GITHUB_APP_PRIVATE_KEY` ذخیره کنید. گردش‌کار از یک marker پنهان به‌عنوان کلید upsert استفاده می‌کند، وقتی توکن بتواند آن را ویرایش کند همان دیدگاه را به‌روزرسانی می‌کند، و وقتی marker قدیمی متعلق به ربات قابل ویرایش نیست یک دیدگاه جدید متعلق به Mantis می‌سازد.
گردش‌کارهای production باید آن نظرها را با Mantis GitHub App منتشر کنند، نه با
`github-actions[bot]`. شناسه app و کلید خصوصی را به‌عنوان رازهای GitHub Actions
با نام‌های `MANTIS_GITHUB_APP_ID` و `MANTIS_GITHUB_APP_PRIVATE_KEY` ذخیره کنید.
گردش‌کار از یک نشانگر پنهان به‌عنوان کلید upsert استفاده می‌کند، وقتی توکن بتواند آن را
ویرایش کند همان نظر را به‌روزرسانی می‌کند، و وقتی نشانگر قدیمی متعلق به ربات قابل‌ویرایش
نباشد یک نظر جدید متعلق به Mantis ایجاد می‌کند.
دیدگاه PR باید کوتاه و تصویری باشد:
نظر PR باید کوتاه و بصری باشد:
```md
Mantis Discord Status Reactions QA
@ -348,60 +420,69 @@ candidate showed the expected queued -> thinking -> done sequence.
| <inline screenshot> | <inline screenshot> |
```
وقتی اجرا به‌دلیل شکست harness ناموفق می‌شود، دیدگاه باید همین را بگوید و القا نکند که candidate شکست خورده است.
وقتی اجرا به دلیل شکست harness ناموفق می‌شود، نظر باید همین را بگوید، نه اینکه القا کند
candidate شکست خورده است.
## یادداشت‌های استقرار خصوصی
یک استقرار خصوصی ممکن است از قبل یک برنامه Discord برای Mantis داشته باشد. وقتی آن برنامه مجوزهای درست ربات را دارد و می‌توان آن را با ایمنی چرخش داد، به‌جای ساختن یک app دیگر، همان برنامه را دوباره استفاده کنید.
یک استقرار خصوصی ممکن است از قبل یک برنامه Discord مربوط به Mantis داشته باشد. وقتی آن برنامه
مجوزهای ربات درست را دارد و می‌توان آن را با اطمینان چرخاند، به‌جای ساختن app دیگر از همان استفاده کنید.
کانال اولیه اعلان اپراتور را از طریق رازها یا پیکربندی استقرار تنظیم کنید. این کانال ابتدا می‌تواند به یک کانال فعلی نگه‌دارندگان یا عملیات اشاره کند، سپس پس از ایجاد کانال اختصاصی Mantis به آن منتقل شود.
کانال اعلان اپراتور اولیه را از طریق رازها یا پیکربندی استقرار تنظیم کنید.
این کانال ابتدا می‌تواند به یک کانال نگه‌دارنده یا عملیات موجود اشاره کند، سپس پس از ایجاد
کانال اختصاصی Mantis به آن منتقل شود.
شناسه‌های guild، شناسه‌های کانال، توکن‌های ربات، کوکی‌های مرورگر یا گذرواژه‌های VNC را در این سند قرار ندهید. آن‌ها را در رازهای GitHub، کارگزار اعتبارنامه، یا مخزن راز محلی اپراتور ذخیره کنید.
شناسه‌های guild، شناسه‌های کانال، توکن‌های ربات، cookieهای مرورگر یا گذرواژه‌های VNC را
در این سند قرار ندهید. آن‌ها را در رازهای GitHub، کارگزار اعتبارنامه، یا مخزن راز محلی
اپراتور ذخیره کنید.
## افزودن یک سناریو
یک سناریوی Mantis باید این موارد را اعلان کند:
یک سناریوی Mantis باید موارد زیر را اعلام کند:
- شناسه و عنوان
- انتقال
- اعتبارنامه‌های موردنیاز
- سیاست ref خط مبنا
- سیاست ref candidate
- patch پیکربندی OpenClaw
- مراحل راه‌اندازی
- اعتبارنامه‌های لازم
- خط‌مشی ref مربوط به baseline
- خط‌مشی ref مربوط به candidate
- وصله پیکربندی OpenClaw
- گام‌های راه‌اندازی
- محرک
- oracle مورد انتظار خط مبنا
- oracle مورد انتظار candidate
- اوراکل baseline مورد انتظار
- اوراکل candidate مورد انتظار
- هدف‌های ثبت بصری
- بودجه timeout
- مراحل پاک‌سازی
- گام‌های پاک‌سازی
سناریوها باید oracleهای کوچک و typed را ترجیح دهند:
سناریوها باید اوراکل‌های کوچک و typed را ترجیح دهند:
- وضعیت واکنش Discord برای باگ‌های واکنش
- ارجاع‌های پیام Discord برای باگ‌های threading
- ارجاع‌های پیام Discord برای باگ‌های thread
- thread ts و وضعیت API واکنش Slack برای باگ‌های Slack
- شناسه‌ها و headerهای پیام ایمیل برای باگ‌های ایمیل
- اسکرین‌شات‌های مرورگر وقتی UI تنها مشاهده‌پذیر قابل‌اعتماد است
- شناسه‌ها و headerهای پیام email برای باگ‌های email
- نماگرفت‌های مرورگر وقتی UI تنها مشاهده‌پذیر قابل‌اعتماد است
بررسی‌های بینایی باید افزایشی باشند. اگر یک API پلتفرم می‌تواند باگ را اثبات کند، از API به‌عنوان oracle قبولی/شکست استفاده کنید و اسکرین‌شات‌ها را برای اطمینان انسانی نگه دارید.
بررسی‌های بینایی باید افزایشی باشند. اگر یک API پلتفرم می‌تواند باگ را اثبات کند،
از API به‌عنوان اوراکل قبولی/ردی استفاده کنید و نماگرفت‌ها را برای اطمینان انسانی نگه دارید.
## گسترش ارائه‌دهنده
پس از Discord، همان اجراکننده می‌تواند این موارد را اضافه کند:
پس از Discord، همان اجراکننده می‌تواند موارد زیر را اضافه کند:
- Slack: واکنش‌ها، threadها، اشاره به app، modalها، بارگذاری فایل.
- ایمیل: احراز هویت Gmail و threading پیام با استفاده از `gog` در جاهایی که connectorها کافی نیستند.
- Slack: واکنش‌ها، threadها، mentionهای app، modalها، بارگذاری فایل.
- Email: احراز هویت Gmail و thread کردن پیام با استفاده از `gog` در جاهایی که connectorها کافی نیستند.
- WhatsApp: ورود QR، شناسایی دوباره، تحویل پیام، رسانه، واکنش‌ها.
- Telegram: دروازه‌بانی mention گروه، commandها، واکنش‌ها در صورت وجود.
- Matrix: roomهای رمزنگاری‌شده، رابطه‌های thread یا reply، ازسرگیری پس از restart.
- Telegram: gating مربوط به mention گروه، فرمان‌ها، واکنش‌ها در صورت پشتیبانی.
- Matrix: اتاق‌های رمزگذاری‌شده، روابط thread یا reply، ازسرگیری پس از راه‌اندازی دوباره.
هر انتقال باید یک سناریوی smoke ارزان و یک یا چند سناریوی کلاس باگ داشته باشد. سناریوهای بصری پرهزینه باید opt-in باقی بمانند.
هر انتقال باید یک سناریوی smoke ارزان و یک یا چند سناریوی رده باگ داشته باشد.
سناریوهای بصری پرهزینه باید opt-in باقی بمانند.
## پرسش‌های باز
- وقتی ربات فعلی Mantis دوباره استفاده می‌شود، کدام ربات Discord باید driver باشد و کدام باید SUT باشد؟
- ورود مرورگر ناظر در فاز اول باید از حساب انسانی Discord، حساب آزمایشی، یا فقط شواهد REST قابل‌خواندن توسط ربات استفاده کند؟
- GitHub چه مدت باید آرتیفکت‌های Mantis را برای PRها نگه دارد؟
- چه زمانی ClawSweeper باید به‌جای انتظار برای command نگه‌دارنده، Mantis را به‌صورت خودکار پیشنهاد کند؟
- آیا اسکرین‌شات‌ها باید پیش از بارگذاری برای PRهای عمومی حذف‌اطلاعات یا برش داده شوند؟
- وقتی ربات موجود Mantis دوباره استفاده می‌شود، کدام ربات Discord باید driver باشد و کدام باید SUT باشد؟
- ورود مرورگر ناظر باید در فاز اول از حساب انسانی Discord، حساب test،
یا فقط شواهد REST قابل‌خواندن برای ربات استفاده کند؟
- GitHub باید مصنوعات Mantis برای PRها را چه مدت نگه دارد؟
- چه زمانی ClawSweeper باید به‌جای انتظار برای فرمان نگه‌دارنده، به‌طور خودکار Mantis را پیشنهاد کند؟
- آیا نماگرفت‌ها باید پیش از بارگذاری برای PRهای عمومی ویرایش محرمانه یا برش داده شوند؟

106
docs/fa/concepts/messages.md
View File

@ -1,20 +1,20 @@
---
read_when:
- توضیح اینکه چگونه پیام‌های ورودی به پاسخ تبدیل می‌شوند
- شفاف‌سازی نشست‌ها، حالت‌های صف‌بندی یا رفتار پخش جریانی
- توضیح اینکه پیام‌های ورودی چگونه به پاسخ تبدیل می‌شوند
- شفاف‌سازی نشست‌ها، حالت‌های صف‌بندی یا رفتار جریان‌دهی
- مستندسازی قابلیت مشاهدهٔ استدلال و پیامدهای استفاده
summary: جریان پیام، نشست‌ها، صف‌بندی و مشاهده‌پذیری استدلال
summary: جریان پیام، نشست‌ها، صف‌بندی و قابلیت مشاهدهٔ استدلال
title: پیام‌ها
x-i18n:
generated_at: "2026-04-30T16:27:51Z"
generated_at: "2026-05-04T07:03:52Z"
model: gpt-5.5
provider: openai
source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9
source_hash: 15242e21fd17a9f2013561003e108d197204d834caf51bbcdc53ffb3f118b14f
source_path: concepts/messages.md
workflow: 16
---
OpenClaw پیام‌های ورودی را از طریق خط لوله‌ای شامل تشخیص نشست، صف‌بندی، جریان‌سازی، اجرای ابزار و نمایش‌پذیری استدلال پردازش می‌کند. این صفحه مسیر از پیام ورودی تا پاسخ را ترسیم می‌کند.
OpenClaw پیام‌های ورودی را از طریق یک خط لوله شامل تشخیص نشست، صف‌گذاری، جریان‌دهی، اجرای ابزار، و نمایش‌پذیری استدلال پردازش می‌کند. این صفحه مسیر از پیام ورودی تا پاسخ را ترسیم می‌کند.
## جریان پیام (سطح بالا)
@ -28,19 +28,19 @@ Inbound message
تنظیمات کلیدی در پیکربندی قرار دارند:
- `messages.*` برای پیشوندها، صف‌بندی و رفتار گروه.
- `agents.defaults.*` برای پیش‌فرض‌های جریان‌سازی بلوکی و تکه‌تکه‌سازی.
- بازنویسی‌های کانال (`channels.whatsapp.*`، `channels.telegram.*` و غیره) برای سقف‌ها و کلیدهای جریان‌سازی.
- `messages.*` برای پیشوندها، صف‌گذاری، و رفتار گروه.
- `agents.defaults.*` برای پیش‌فرض‌های جریان‌دهی بلوکی و قطعه‌بندی.
- بازنویسی‌های کانال (`channels.whatsapp.*`، `channels.telegram.*`، و غیره) برای سقف‌ها و کلیدهای جریان‌دهی.
برای طرح‌واره کامل، [پیکربندی](/fa/gateway/configuration) را ببینید.
## حذف تکرار ورودی
کانال‌ها می‌توانند پس از اتصال دوباره همان پیام را دوباره تحویل دهند. OpenClaw یک کش کوتاه‌عمر نگه می‌دارد که با شناسه کانال/حساب/همتا/نشست/پیام کلیدگذاری شده است تا تحویل‌های تکراری باعث اجرای دوباره عامل نشوند.
کانال‌ها می‌توانند پس از اتصال دوباره همان پیام را دوباره تحویل دهند. OpenClaw یک حافظه نهان کوتاه‌عمر نگه می‌دارد که با شناسه کانال/حساب/همتا/نشست/پیام کلیدگذاری می‌شود تا تحویل‌های تکراری اجرای عامل دیگری را آغاز نکنند.
## ضدپرش ورودی
## ادغام تأخیری ورودی
پیام‌های پشت‌سرهم سریع از **همان فرستنده** می‌توانند از طریق `messages.inbound` در یک نوبت واحد عامل دسته‌بندی شوند. ضدپرش برای هر کانال + گفتگو محدوده‌بندی می‌شود و از تازه‌ترین پیام برای رشته‌بندی/شناسه‌های پاسخ استفاده می‌کند.
پیام‌های پی‌درپی سریع از **همان فرستنده** می‌توانند از طریق `messages.inbound` در یک نوبت عامل واحد تجمیع شوند. ادغام تأخیری برای هر کانال + گفتگو جداگانه اعمال می‌شود و برای رشته‌بندی/شناسه‌های پاسخ از جدیدترین پیام استفاده می‌کند.
پیکربندی (پیش‌فرض سراسری + بازنویسی‌های هر کانال):
@ -61,69 +61,69 @@ Inbound message
نکته‌ها:
- ضدپرش فقط روی پیام‌های **فقط متنی** اعمال می‌شود؛ رسانه/پیوست‌ها بلافاصله تخلیه می‌شوند.
- فرمان‌های کنترلی ضدپرش را دور می‌زنند تا مستقل بمانند — **مگر** وقتی کانالی صراحتا در ادغام DM از همان فرستنده شرکت کند (برای نمونه [BlueBubbles `coalesceSameSenderDms`](/fa/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition))، که در آن فرمان‌های DM داخل پنجره ضدپرش منتظر می‌مانند تا محتوای ارسالِ تقسیم‌شده بتواند به همان نوبت عامل بپیوندد.
- ادغام تأخیری برای پیام‌های **فقط متنی** اعمال می‌شود؛ رسانه/پیوست‌ها بلافاصله تخلیه می‌شوند.
- فرمان‌های کنترلی از ادغام تأخیری عبور می‌کنند تا مستقل باقی بمانند — **به‌جز** زمانی که یک کانال صریحاً ادغام پیام‌های مستقیم از همان فرستنده را فعال کند (برای مثال [BlueBubbles `coalesceSameSenderDms`](/fa/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition))، که در آن فرمان‌های پیام مستقیم داخل پنجره ادغام تأخیری منتظر می‌مانند تا یک محموله ارسال‌شده به‌صورت جداشده بتواند به همان نوبت عامل بپیوندد.
## نشست‌ها و دستگاه‌ها
نشست‌ها متعلق به Gateway هستند، نه کلاینت‌ها.
نشست‌ها متعلق به Gateway هستند، نه مشتری‌ها.
- گفتگوهای مستقیم در کلید نشست اصلی عامل ادغام می‌شوند.
- گروه‌ها/کانال‌ها کلیدهای نشست خودشان را می‌گیرند.
- ذخیره‌گاه نشست و رونوشت‌ها روی میزبان Gateway قرار دارند.
- چت‌های مستقیم در کلید نشست اصلی عامل ادغام می‌شوند.
- گروه‌ها/کانال‌ها کلیدهای نشست خودشان را دریافت می‌کنند.
- ذخیره‌ساز نشست و رونوشت‌ها روی میزبان Gateway قرار دارند.
چند دستگاه/کانال می‌توانند به یک نشست نگاشت شوند، اما تاریخچه به‌طور کامل به همه کلاینت‌ها همگام‌سازی نمی‌شود. توصیه: برای گفتگوهای طولانی از یک دستگاه اصلی استفاده کنید تا از واگرایی زمینه جلوگیری شود. Control UI و TUI همیشه رونوشت نشست پشتیبانی‌شده توسط Gateway را نشان می‌دهند، پس منبع حقیقت هستند.
چند دستگاه/کانال می‌توانند به یک نشست یکسان نگاشت شوند، اما تاریخچه به‌طور کامل به همه مشتری‌ها همگام‌سازی نمی‌شود. توصیه: برای گفتگوهای طولانی از یک دستگاه اصلی استفاده کنید تا از واگرایی زمینه جلوگیری شود. رابط کاربری کنترل و TUI همیشه رونوشت نشست متکی بر Gateway را نشان می‌دهند، بنابراین منبع حقیقت هستند.
جزئیات: [مدیریت نشست](/fa/concepts/session).
## فراداده نتیجه ابزار
`content` نتیجه ابزار، نتیجه قابل مشاهده برای مدل است. `details` نتیجه ابزار فراداده زمان اجرا برای رندر UI، عیب‌یابی، تحویل رسانه و Pluginها است.
`content` نتیجه ابزار همان نتیجه قابل مشاهده برای مدل است. `details` نتیجه ابزار فراداده زمان اجرا برای رندر رابط کاربری، عیب‌یابی، تحویل رسانه، و Pluginها است.
OpenClaw این مرز را صریح نگه می‌دارد:
- `toolResult.details` پیش از بازپخش ارائه‌دهنده و ورودی Compaction حذف می‌شود.
- رونوشت‌های نشست پایدارشده فقط `details` محدود را نگه می‌دارند؛ فراداده بزرگ‌تر با خلاصه‌ای فشرده جایگزین می‌شود که با `persistedDetailsTruncated: true` علامت‌گذاری شده است.
- Pluginها و ابزارها باید متنی را که مدل باید بخواند در `content` قرار دهند، نه فقط در `details`.
- رونوشت‌های نشست ماندگارشده فقط `details` محدودشده را نگه می‌دارند؛ فراداده بزرگ‌تر از حد با خلاصه‌ای فشرده جایگزین می‌شود که با `persistedDetailsTruncated: true` علامت‌گذاری شده است.
- Pluginها و ابزارها باید متنی را که مدل باید بخواند در `content` بگذارند، نه فقط در `details`.
## بدنه‌های ورودی و زمینه تاریخچه
OpenClaw **بدنه پرامپت** را از **بدنه فرمان** جدا می‌کند:
- `BodyForAgent`: متن اصلی رو به مدل برای پیام فعلی. Pluginهای کانال باید این را روی متن فعلی فرستنده که حامل پرامپت است متمرکز نگه دارند.
- `Body`: جایگزین قدیمی پرامپت. این ممکن است شامل پوشش‌های کانال و پوشش‌های اختیاری تاریخچه باشد، اما کانال‌های فعلی نباید وقتی `BodyForAgent` در دسترس است به‌عنوان ورودی اصلی مدل به آن تکیه کنند.
- `CommandBody`: متن خام کاربر برای تحلیل دستورالعمل/فرمان.
- `BodyForAgent`: متن اصلی رو به مدل برای پیام فعلی. Pluginهای کانال باید این بخش را روی متن فعلی فرستنده که حامل پرامپت است متمرکز نگه دارند.
- `Body`: جایگزین قدیمی پرامپت. این مورد ممکن است شامل لفافه‌های کانال و پوشش‌های اختیاری تاریخچه باشد، اما کانال‌های فعلی وقتی `BodyForAgent` در دسترس است نباید به آن به‌عنوان ورودی اصلی مدل تکیه کنند.
- `CommandBody`: متن خام کاربر برای تجزیه دستور/فرمان.
- `RawBody`: نام مستعار قدیمی برای `CommandBody` (برای سازگاری نگه داشته شده است).
وقتی یک کانال تاریخچه ارائه می‌کند، از پوشش مشترک استفاده می‌کند:
وقتی یک کانال تاریخچه فراهم می‌کند، از یک پوشش مشترک استفاده می‌کند:
- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`
برای **گفتگوهای غیرمستقیم** (گروه‌ها/کانال‌ها/اتاق‌ها)، **بدنه پیام فعلی** با برچسب فرستنده پیشوند می‌گیرد (همان سبکی که برای ورودی‌های تاریخچه استفاده می‌شود). این کار پیام‌های بی‌درنگ و صف‌شده/تاریخچه را در پرامپت عامل سازگار نگه می‌دارد.
برای **چت‌های غیرمستقیم** (گروه‌ها/کانال‌ها/اتاق‌ها)، پیشوند **بدنه پیام فعلی** برچسب فرستنده است (همان سبکی که برای ورودی‌های تاریخچه استفاده می‌شود). این کار پیام‌های بلادرنگ و صف‌شده/تاریخچه را در پرامپت عامل سازگار نگه می‌دارد.
بافرهای تاریخچه **فقط معلق** هستند: آن‌ها شامل پیام‌های گروهی می‌شوند که اجرا را _فعال نکرده‌اند_ (برای مثال، پیام‌های محدودشده به منشن) و پیام‌هایی را که از قبل در رونوشت نشست هستند **حذف می‌کنند**.
بافرهای تاریخچه **فقط در انتظار** هستند: آن‌ها پیام‌های گروهی را شامل می‌شوند که اجرای عامل را آغاز _نکرده‌اند_ (برای مثال، پیام‌های محدودشده به ذکر نام) و پیام‌هایی را که از قبل در رونوشت نشست هستند **حذف** می‌کنند.
حذف دستورالعمل فقط روی بخش **پیام فعلی** اعمال می‌شود تا تاریخچه دست‌نخورده بماند. کانال‌هایی که تاریخچه را پوشش می‌دهند باید `CommandBody` (یا `RawBody`) را روی متن پیام اصلی تنظیم کنند و `Body` را به‌عنوان پرامپت ترکیبی نگه دارند. تاریخچه ساخت‌یافته، پاسخ، پیام‌های بازفرستاده‌شده و فراداده کانال هنگام مونتاژ پرامپت به‌صورت بلوک‌های زمینه غیرقابل اعتماد با نقش کاربر رندر می‌شوند.
بافرهای تاریخچه از طریق `messages.groupChat.historyLimit` (پیش‌فرض سراسری) و بازنویسی‌های هر کانال مانند `channels.slack.historyLimit` یا `channels.telegram.accounts.<id>.historyLimit` قابل پیکربندی هستند (`0` را برای غیرفعال‌سازی تنظیم کنید).
حذف دستورالعمل فقط روی بخش **پیام فعلی** اعمال می‌شود تا تاریخچه دست‌نخورده بماند. کانال‌هایی که تاریخچه را پوشش می‌دهند باید `CommandBody` (یا `RawBody`) را روی متن اصلی پیام تنظیم کنند و `Body` را به‌عنوان پرامپت ترکیبی نگه دارند. تاریخچه ساختاریافته، پاسخ، پیام‌های بازفرستاده‌شده، و فراداده کانال هنگام مونتاژ پرامپت به‌صورت بلوک‌های زمینه نامطمئن با نقش کاربر رندر می‌شوند.
بافرهای تاریخچه از طریق `messages.groupChat.historyLimit` (پیش‌فرض سراسری) و بازنویسی‌های هر کانال مانند `channels.slack.historyLimit` یا `channels.telegram.accounts.<id>.historyLimit` قابل پیکربندی هستند (برای غیرفعال کردن، `0` تنظیم کنید).
## صف‌بندی و پیگیری‌ها
## صف‌گذاری و پیگیری‌ها
اگر اجرایی از قبل فعال باشد، پیام‌های ورودی می‌توانند صف شوند، به اجرای فعلی هدایت شوند، یا برای یک نوبت پیگیری جمع‌آوری شوند.
- از طریق `messages.queue` (و `messages.queue.byChannel`) پیکربندی کنید.
- حالت پیش‌فرض `steer` است، با ضدپرش پیگیری ۵۰۰ میلی‌ثانیه‌ای وقتی هدایت به تحویل پیگیری صف‌شده برمی‌گردد.
- حالت‌ها: `steer`، `followup`، `collect`، `steer-backlog`، `interrupt`، و حالت قدیمی یکی‌درهرزمان `queue`.
- حالت پیش‌فرض `steer` است، با ادغام تأخیری پیگیری 500 میلی‌ثانیه‌ای وقتی هدایت به تحویل پیگیری صف‌شده بازمی‌گردد.
- حالت‌ها: `steer`، `followup`، `collect`، `steer-backlog`، `interrupt`، و حالت قدیمی تک‌به‌تک `queue`.
جزئیات: [صف فرمان](/fa/concepts/queue) و [صف هدایت](/fa/concepts/queue-steering).
## مالکیت اجرای کانال
Pluginهای کانال ممکن است ترتیب را حفظ کنند، ورودی را ضدپرش کنند و پیش از ورود پیام به صف نشست، پس‌فشار انتقال را اعمال کنند. آن‌ها نباید زمان‌سنج جداگانه‌ای دور خود نوبت عامل تحمیل کنند. وقتی پیام به یک نشست مسیریابی شد، کارهای طولانی‌مدت توسط چرخه عمر نشست، ابزار و زمان اجرا اداره می‌شوند تا همه کانال‌ها نوبت‌های کند را به‌شکل سازگار گزارش دهند و بازیابی کنند.
Pluginهای کانال می‌توانند ترتیب را حفظ کنند، ورودی را با تأخیر ادغام کنند، و پیش از ورود پیام به صف نشست، پس‌فشار انتقال را اعمال کنند. آن‌ها نباید پیرامون خود نوبت عامل زمان‌سنج جداگانه‌ای تحمیل کنند. پس از مسیریابی یک پیام به نشست، کارهای طولانی‌مدت توسط چرخه عمر نشست، ابزار، و زمان اجرا اداره می‌شوند تا همه کانال‌ها نوبت‌های کند را به‌صورت سازگار گزارش دهند و از آن‌ها بازیابی کنند.
## جریان‌سازی، تکه‌تکه‌سازی و دسته‌بندی
## جریان‌دهی، قطعه‌بندی، و دسته‌بندی
جریان‌سازی بلوکی پاسخ‌های جزئی را هم‌زمان با تولید بلوک‌های متن توسط مدل ارسال می‌کند. تکه‌تکه‌سازی محدودیت‌های متنی کانال را رعایت می‌کند و از تقسیم کردن کد حصارشده پرهیز می‌کند.
جریان‌دهی بلوکی پاسخ‌های جزئی را هم‌زمان با تولید بلوک‌های متن توسط مدل ارسال می‌کند. قطعه‌بندی محدودیت‌های متنی کانال را رعایت می‌کند و از شکستن کدهای محصور جلوگیری می‌کند.
تنظیمات کلیدی:
@ -134,46 +134,46 @@ Pluginهای کانال ممکن است ترتیب را حفظ کنند، ورو
- `agents.defaults.humanDelay` (مکث شبیه انسان بین پاسخ‌های بلوکی)
- بازنویسی‌های کانال: `*.blockStreaming` و `*.blockStreamingCoalesce` (کانال‌های غیر Telegram به `*.blockStreaming: true` صریح نیاز دارند)
جزئیات: [جریان‌سازی + تکه‌تکه‌سازی](/fa/concepts/streaming).
جزئیات: [جریان‌دهی + قطعه‌بندی](/fa/concepts/streaming).
## نمایش‌پذیری استدلال و توکن‌ها
OpenClaw می‌تواند استدلال مدل را آشکار یا پنهان کند:
OpenClaw می‌تواند استدلال مدل را نمایش دهد یا پنهان کند:
- `/reasoning on|off|stream` نمایش‌پذیری را کنترل می‌کند.
- محتوای استدلال، وقتی توسط مدل تولید شود، همچنان در مصرف توکن حساب می‌شود.
- Telegram از جریان استدلال به داخل حباب پیش‌نویس پشتیبانی می‌کند.
- محتوای استدلال، وقتی توسط مدل تولید شود، همچنان در مصرف توکن محاسبه می‌شود.
- Telegram از جریان استدلال به یک حباب پیش‌نویس گذرا پشتیبانی می‌کند که پس از تحویل نهایی حذف می‌شود؛ برای خروجی استدلال ماندگار از `/reasoning on` استفاده کنید.
جزئیات: [دستورالعمل‌های فکر کردن + استدلال](/fa/tools/thinking) و [مصرف توکن](/fa/reference/token-use).
جزئیات: [دستورهای تفکر + استدلال](/fa/tools/thinking) و [مصرف توکن](/fa/reference/token-use).
## پیشوندها، رشته‌بندی و پاسخ‌ها
## پیشوندها، رشته‌بندی، و پاسخ‌ها
قالب‌بندی پیام خروجی در `messages` متمرکز شده است:
قالب‌بندی پیام خروجی در `messages` متمرکز است:
- `messages.responsePrefix`، `channels.<channel>.responsePrefix` و `channels.<channel>.accounts.<id>.responsePrefix` (آبشار پیشوند خروجی)، به‌علاوه `channels.whatsapp.messagePrefix` (پیشوند ورودی WhatsApp)
- `messages.responsePrefix`، `channels.<channel>.responsePrefix`، و `channels.<channel>.accounts.<id>.responsePrefix` (آبشار پیشوند خروجی)، به‌علاوه `channels.whatsapp.messagePrefix` (پیشوند ورودی WhatsApp)
- رشته‌بندی پاسخ از طریق `replyToMode` و پیش‌فرض‌های هر کانال
جزئیات: [پیکربندی](/fa/gateway/config-agents#messages) و مستندات کانال.
## پاسخ‌های خاموش
## پاسخ‌های بی‌صدا
توکن خاموش دقیق `NO_REPLY` / `no_reply` یعنی «پاسخ قابل مشاهده برای کاربر تحویل نده».
وقتی یک نوبت همچنین رسانه ابزار معلق دارد، مانند صوت TTS تولیدشده، OpenClaw متن خاموش را حذف می‌کند اما همچنان پیوست رسانه را تحویل می‌دهد.
توکن دقیق بی‌صدا `NO_REPLY` / `no_reply` یعنی «پاسخ قابل مشاهده برای کاربر تحویل نده».
وقتی یک نوبت همچنین رسانه ابزار در انتظار داشته باشد، مانند صدای TTS تولیدشده، OpenClaw متن بی‌صدا را حذف می‌کند اما همچنان پیوست رسانه را تحویل می‌دهد.
OpenClaw این رفتار را بر اساس نوع گفتگو حل می‌کند:
- گفتگوهای مستقیم به‌طور پیش‌فرض سکوت را مجاز نمی‌دانند و یک پاسخ خاموش تنها را به جایگزین کوتاه قابل مشاهده بازنویسی می‌کنند.
- گروه‌ها/کانال‌ها به‌طور پیش‌فرض سکوت را مجاز می‌دانند.
- ارکستراسیون داخلی به‌طور پیش‌فرض سکوت را مجاز می‌داند.
- گفتگوهای مستقیم به‌صورت پیش‌فرض سکوت را مجاز نمی‌دانند و یک پاسخ صرفاً بی‌صدا را به جایگزین کوتاه قابل مشاهده بازنویسی می‌کنند.
- گروه‌ها/کانال‌ها به‌صورت پیش‌فرض سکوت را مجاز می‌دانند.
- هماهنگ‌سازی داخلی به‌صورت پیش‌فرض سکوت را مجاز می‌داند.
OpenClaw همچنین برای خرابی‌های داخلی اجراکننده که پیش از هر پاسخ دستیار در گفتگوهای غیرمستقیم رخ می‌دهند از پاسخ‌های خاموش استفاده می‌کند، تا گروه‌ها/کانال‌ها متن کلیشه‌ای خطای Gateway را نبینند. گفتگوهای مستقیم به‌طور پیش‌فرض متن کوتاه خرابی را نشان می‌دهند؛ جزئیات خام اجراکننده فقط وقتی `/verbose` روی `on` یا `full` باشد نشان داده می‌شود.
OpenClaw همچنین از پاسخ‌های بی‌صدا برای شکست‌های داخلی اجراکننده استفاده می‌کند که پیش از هر پاسخ دستیار در چت‌های غیرمستقیم رخ می‌دهند، تا گروه‌ها/کانال‌ها متن‌های کلیشه‌ای خطای Gateway را نبینند. چت‌های مستقیم به‌صورت پیش‌فرض متن شکست فشرده را نشان می‌دهند؛ جزئیات خام اجراکننده فقط زمانی نشان داده می‌شود که `/verbose` روی `on` یا `full` باشد.
پیش‌فرض‌ها زیر `agents.defaults.silentReply` و `agents.defaults.silentReplyRewrite` قرار دارند؛ `surfaces.<id>.silentReply` و `surfaces.<id>.silentReplyRewrite` می‌توانند آن‌ها را برای هر سطح بازنویسی کنند.
وقتی نشست والد یک یا چند اجرای زیرعامل ایجادشده معلق داشته باشد، پاسخ‌های خاموش تنها به‌جای بازنویسی، روی همه سطح‌ها کنار گذاشته می‌شوند، تا والد تا زمانی که رویداد تکمیل فرزند پاسخ واقعی را تحویل دهد ساکت بماند.
وقتی نشست والد یک یا چند اجرای زیرعامل ایجادشده در انتظار داشته باشد، پاسخ‌های صرفاً بی‌صدا در همه سطح‌ها به‌جای بازنویسی کنار گذاشته می‌شوند، بنابراین والد تا زمانی که رویداد تکمیل فرزند پاسخ واقعی را تحویل دهد ساکت می‌ماند.
## مرتبط
- [جریان‌سازی](/fa/concepts/streaming) — تحویل بی‌درنگ پیام
- [جریان‌دهی](/fa/concepts/streaming) — تحویل پیام بلادرنگ
- [تلاش دوباره](/fa/concepts/retry) — رفتار تلاش دوباره برای تحویل پیام
- [صف](/fa/concepts/queue) — صف پردازش پیام
- [کانال‌ها](/fa/channels) — یکپارچه‌سازی‌های پلتفرم پیام‌رسانی

184
docs/fa/concepts/progress-drafts.md
View File

@ -1,26 +1,26 @@
---
read_when:
- پیکربندی به‌روزرسانی‌های پیشرفت قابل مشاهده برای نوبت‌های گفت‌وگوی طولانی‌مدت
- انتخاب میان حالت‌های جریان‌دهی جزئی، بلوکی و پیشرفت
- توضیح اینکه OpenClaw چگونه در حالی که کار در حال انجام است، یک پیام کانال را به‌روزرسانی می‌کند
- پیکربندی به‌روزرسانی‌های قابل مشاهدهٔ پیشرفت برای نوبت‌های طولانی‌مدت گفت‌وگو
- انتخاب بین حالت‌های استریم جزئی، بلوکی و پیشرفت
- توضیح اینکه OpenClaw چگونه هنگام در جریان بودن کار، یک پیام کانال را به‌روزرسانی می‌کند
- عیب‌یابی پیش‌نویس‌های پیشرفت، پیام‌های مستقل پیشرفت، یا مسیر جایگزین نهایی‌سازی
summary: 'پیش‌نویس‌های پیشرفت: یک پیام قابل مشاهدهٔ کار در حال انجام که هنگام اجرای یک عامل به‌روزرسانی می‌شود'
title: پیش‌نویس‌های پیشرفت
title: پیش‌بردن پیش‌نویس‌ها
x-i18n:
generated_at: "2026-05-04T02:24:03Z"
generated_at: "2026-05-04T07:04:10Z"
model: gpt-5.5
provider: openai
source_hash: 8ce19262800f1c3c3e505a3cf1d41ed5c3dffcbca168ad7b7afabdce62eee8fe
source_hash: f78c07866cd7f613012a80a40413e5866c1dd2edd477088f9fc141347f5f3788
source_path: concepts/progress-drafts.md
workflow: 16
---
پیش‌نویس‌های پیشرفت باعث می‌شوند نوبت‌های طولانی‌مدت عامل در چت زنده به نظر برسند، بدون اینکه
گفت‌وگو به پشته‌ای از پاسخ‌های وضعیت موقت تبدیل شود.
گفت‌وگو به انباشته‌ای از پاسخ‌های وضعیت موقت تبدیل شود.
وقتی پیش‌نویس‌های پیشرفت فعال باشند، OpenClaw فقط پس از اینکه نوبت ثابت کرد در حال انجام کار واقعی است
یک پیام کاریِ قابل مشاهده ایجاد می‌کند، هنگام خواندن، برنامه‌ریزی، فراخوانی ابزارها یا انتظار برای تأیید توسط
عامل آن را به‌روزرسانی می‌کند، و سپس وقتی کانال بتواند این کار را با ایمنی انجام دهد، آن پیش‌نویس را
وقتی پیش‌نویس‌های پیشرفت فعال باشند، OpenClaw فقط بعد از اینکه نوبت نشان داد کار واقعی انجام می‌دهد
یک پیام visible work-in-progress ایجاد می‌کند، آن را هنگامی که
عامل می‌خواند، برنامه‌ریزی می‌کند، ابزارها را فراخوانی می‌کند یا منتظر تأیید می‌ماند به‌روزرسانی می‌کند، و سپس وقتی کانال بتواند این کار را با ایمنی انجام دهد، آن پیش‌نویس را
به پاسخ نهایی تبدیل می‌کند.
```text
@ -30,8 +30,8 @@ Shelling...
🛠️ Exec: run tests
```
وقتی در کارهای سنگین از نظر ابزار، یک پیام وضعیت مرتب می‌خواهید
و پاسخ نهایی را پس از پایان نوبت می‌خواهید، از پیش‌نویس‌های پیشرفت استفاده کنید.
وقتی در کارهای پرابزار یک پیام وضعیت مرتب می‌خواهید
و پس از پایان نوبت پاسخ نهایی را، از پیش‌نویس‌های پیشرفت استفاده کنید.
## شروع سریع
@ -49,9 +49,9 @@ Shelling...
}
```
این معمولاً کافی است. OpenClaw یک برچسب تک‌کلمه‌ای خودکار انتخاب می‌کند، صبر می‌کند
تا کار دست‌کم پنج ثانیه طول بکشد یا رویداد کاری دومی منتشر شود، در زمان انجام کار مفید
خطوط پیشرفت فشرده اضافه می‌کند، و گفت‌وگوی پیشرفت مستقلِ تکراری را برای آن نوبت سرکوب می‌کند.
این معمولاً کافی است. OpenClaw یک برچسب خودکار یک‌کلمه‌ای انتخاب می‌کند، صبر می‌کند
تا کار دست‌کم پنج ثانیه طول بکشد یا یک رویداد کاری دوم منتشر کند، هنگام انجام کار مفید
خطوط پیشرفت فشرده اضافه می‌کند، و گفت‌وگوی پیشرفت مستقل و تکراری را برای آن نوبت سرکوب می‌کند.
## کاربران چه می‌بینند
@ -60,45 +60,45 @@ Shelling...
| بخش | هدف |
| -------------- | --------------------------------------------------------------------------- |
| برچسب | عنوانی کوتاه مانند `Thinking...` یا `Shelling...`. |
| خطوط پیشرفت | به‌روزرسانی‌های اجرای فشرده با همان برچسب‌ها و آیکون‌های ابزار مانند خروجی پرجزئیات. |
| خطوط پیشرفت | به‌روزرسانی‌های اجرای فشرده با همان برچسب‌ها و آیکون‌های ابزار که در خروجی پرجزئیات استفاده می‌شوند. |
برچسب پس از شروع کار معنادار توسط عامل ظاهر می‌شود و یا تا پنج ثانیه مشغول می‌ماند
یا رویداد کاری دومی منتشر می‌کند. پاسخ‌های صرفاً متنی ساده
پیش‌نویس پیشرفت نشان نمی‌دهند. خطوط پیشرفت فقط وقتی اضافه می‌شوند که عامل
به‌روزرسانی‌های کاری مفید منتشر کند، برای مثال `🛠️ Exec`، `🔎 Web Search` یا `✍️ Write: to /tmp/file`.
به‌طور پیش‌فرض از همان حالت توضیح فشرده مانند `/verbose` استفاده می‌کنند؛ وقتی در حال اشکال‌زدایی هستید
و می‌خواهید فرمان‌ها/جزئیات خام نیز افزوده شوند، `agents.defaults.toolProgressDetail: "raw"` را تنظیم کنید.
در صورت امکان پاسخ نهایی جایگزین پیش‌نویس می‌شود؛ در غیر این صورت
OpenClaw پاسخ نهایی را به‌صورت معمول می‌فرستد و پیش‌نویس را طبق انتقال کانال
پاک می‌کند یا به‌روزرسانی آن را متوقف می‌کند.
یا یک رویداد کاری دوم منتشر می‌کند. پاسخ‌های صرفاً متنی، پیش‌نویس پیشرفت نشان نمی‌دهند.
خطوط پیشرفت فقط وقتی اضافه می‌شوند که عامل به‌روزرسانی‌های کاری مفید منتشر کند،
برای مثال `🛠️ Exec`، `🔎 Web Search`، یا `✍️ Write: to /tmp/file`.
به‌صورت پیش‌فرض از همان حالت توضیح فشرده مثل `/verbose` استفاده می‌کنند؛ وقتی در حال اشکال‌زدایی هستید و جزئیات/دستورات خام افزوده‌شده را هم می‌خواهید،
`agents.defaults.toolProgressDetail: "raw"` را تنظیم کنید.
پاسخ نهایی در صورت امکان جایگزین پیش‌نویس می‌شود؛ در غیر این صورت
OpenClaw پاسخ نهایی را به‌صورت عادی می‌فرستد و بسته به انتقال کانال،
پیش‌نویس را پاک‌سازی می‌کند یا به‌روزرسانی آن را متوقف می‌کند.
## انتخاب حالت
## انتخاب یک حالت
`channels.<channel>.streaming.mode` رفتار قابل مشاهده هنگام در جریان بودن کار را کنترل می‌کند:
`channels.<channel>.streaming.mode` رفتار visible in-progress را کنترل می‌کند:
| حالت | مناسب برای | آنچه در چت ظاهر می‌شود |
| ---------- | -------------------------------- | ------------------------------------------------- |
| `off` | کانال‌های ساکت | فقط پاسخ نهایی. |
| `off` | کانال‌های کم‌صدا | فقط پاسخ نهایی. |
| `partial` | دیدن ظاهر شدن متن پاسخ | یک پیش‌نویس که با آخرین متن پاسخ ویرایش می‌شود. |
| `block` | قطعه‌های بزرگ‌تر پیش‌نمایش پاسخ | یک پیش‌نمایش که در قطعه‌های بزرگ‌تر به‌روزرسانی یا افزوده می‌شود. |
| `progress` | نوبت‌های سنگین از نظر ابزار یا طولانی‌مدت | یک پیش‌نویس وضعیت، سپس پاسخ نهایی. |
| `block` | تکه‌های بزرگ‌تر پیش‌نمایش پاسخ | یک پیش‌نمایش که در تکه‌های بزرگ‌تر به‌روزرسانی یا افزوده می‌شود. |
| `progress` | نوبت‌های پرابزار یا طولانی‌مدت | یک پیش‌نویس وضعیت، سپس پاسخ نهایی. |
وقتی کاربران بیشتر از تماشای جریان متن پاسخ، توکن به توکن،
به «چه اتفاقی دارد می‌افتد» اهمیت می‌دهند، `progress` را انتخاب کنید.
وقتی کاربران بیشتر به «چه اتفاقی در حال رخ دادن است» اهمیت می‌دهند تا دیدن
جریان متن پاسخ به‌صورت توکن‌به‌توکن، `progress` را انتخاب کنید.
وقتی خود پاسخ، سیگنال پیشرفت است، `partial` را انتخاب کنید.
وقتی خود پاسخ سیگنال پیشرفت است، `partial` را انتخاب کنید.
وقتی می‌خواهید به‌روزرسانی‌های پیش‌نمایش پیش‌نویس در قطعه‌های متنی بزرگ‌تر باشد، `block` را انتخاب کنید. در
Discord و Telegram، `streaming.mode: "block"` همچنان جریان‌دهی پیش‌نمایش است، نه
تحویل بلوکی معمولی. وقتی پاسخ‌های بلوکی معمولی می‌خواهید، از `streaming.block.enabled` یا
وقتی به‌روزرسانی‌های پیش‌نمایش پیش‌نویس را در تکه‌های متنی بزرگ‌تر می‌خواهید، `block` را انتخاب کنید. در
Discord و Telegram، `streaming.mode: "block"` همچنان جریان پیش‌نمایش است، نه
تحویل عادی بلوکی. وقتی پاسخ‌های بلوکی عادی می‌خواهید از `streaming.block.enabled` یا
`blockStreaming` قدیمی استفاده کنید.
## پیکربندی برچسب‌ها
برچسب‌های پیشرفت زیر `channels.<channel>.streaming.progress` قرار دارند.
برچسب پیش‌فرض `auto` است که از مجموعه برچسب تک‌کلمه‌ای همراه با سه‌نقطه داخلی OpenClaw
انتخاب می‌کند:
برچسب پیش‌فرض `auto` است، که از مجموعه برچسب داخلی
تک‌کلمه‌ای-با-سه‌نقطه OpenClaw انتخاب می‌کند:
```text
Thinking...
@ -177,11 +177,11 @@ Surfacing...
## کنترل خطوط پیشرفت
خطوط پیشرفت به‌طور پیش‌فرض در حالت پیشرفت فعال هستند. آن‌ها از رویدادهای اجرای واقعی می‌آیند:
شروع ابزارها، به‌روزرسانی آیتم‌ها، برنامه‌های وظیفه، تأییدها، خروجی فرمان، خلاصه‌های وصله،
خطوط پیشرفت در حالت پیشرفت به‌صورت پیش‌فرض فعال هستند. آن‌ها از رویدادهای اجرای واقعی می‌آیند:
شروع ابزارها، به‌روزرسانی آیتم‌ها، برنامه‌های کار، تأییدها، خروجی فرمان، خلاصه‌های patch
و فعالیت‌های مشابه عامل.
OpenClaw از همان قالب‌ساز برای پیش‌نویس‌های پیشرفت و `/verbose` استفاده می‌کند:
OpenClaw برای پیش‌نویس‌های پیشرفت و `/verbose` از یک formatter یکسان استفاده می‌کند:
```json5
{
@ -193,19 +193,18 @@ OpenClaw از همان قالب‌ساز برای پیش‌نویس‌های پ
}
```
`"explain"` پیش‌فرض است و پیش‌نویس‌ها را با برچسب‌های موجز مانند
`🛠️ Exec: check JS syntax for /tmp/app.js` پایدار نگه می‌دارد. `"raw"` وقتی در دسترس باشد
فرمان/جزئیات زیربنایی را اضافه می‌کند، که هنگام اشکال‌زدایی مفید است اما در
چت پرسر و صداتر است.
`"explain"` پیش‌فرض است و پیش‌نویس‌ها را با برچسب‌های کوتاهی مثل
`🛠️ Exec: check JS syntax for /tmp/app.js` پایدار نگه می‌دارد. `"raw"` در صورت وجود، فرمان/جزئیات زیربنایی را اضافه می‌کند، که هنگام اشکال‌زدایی مفید است اما در
چت پرنویزتر است.
برای مثال، یک فرمان یکسان بسته به حالت جزئیات متفاوت ظاهر می‌شود:
برای مثال، همان فرمان بسته به حالت جزئیات متفاوت ظاهر می‌شود:
| حالت | خط پیشرفت |
| --------- | -------------------------------------------------------------------- |
| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` |
| `raw` | `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` |
تعداد خطوطی را که قابل مشاهده می‌مانند محدود کنید:
تعداد خطوطی را که visible می‌مانند محدود کنید:
```json5
{
@ -222,7 +221,34 @@ OpenClaw از همان قالب‌ساز برای پیش‌نویس‌های پ
}
```
پیش‌نویس پیشرفت تکی را نگه دارید، اما خطوط ابزار و وظیفه را پنهان کنید:
خطوط پیشرفت به‌صورت خودکار فشرده می‌شوند تا هنگام ویرایش پیش‌نویس، بازچینی حباب چت کاهش یابد.
OpenClaw به‌صورت پیش‌فرض خطوط پیشرفت طولانی را کوتاه می‌کند تا ویرایش‌های تکراری پیش‌نویس
در هر به‌روزرسانی به شکل متفاوتی wrap نشوند. پیشوند خوانا می‌ماند، و جزئیات طولانی
مانند مسیرها یا فرمان‌های خام با سه‌نقطه کوتاه می‌شوند.
Slack می‌تواند خطوط پیشرفت را به‌جای یک بدنه متنی واحد، به‌صورت فیلدهای ساختاریافته Block Kit
render کند:
```json5
{
channels: {
slack: {
streaming: {
mode: "progress",
progress: {
render: "rich",
},
},
},
},
}
```
render کردن rich همان fallback متن ساده را نگه می‌دارد تا کانال‌ها و کلاینت‌هایی که
از شکل غنی‌تر پشتیبانی نمی‌کنند همچنان بتوانند متن فشرده پیشرفت را نشان دهند.
پیش‌نویس پیشرفت واحد را نگه دارید اما خطوط ابزار و کار را پنهان کنید:
```json5
{
@ -240,8 +266,8 @@ OpenClaw از همان قالب‌ساز برای پیش‌نویس‌های پ
```
با `toolProgress: false`، OpenClaw همچنان پیام‌های قدیمی‌تر مستقل
پیشرفت ابزار را برای آن نوبت سرکوب می‌کند. کانال تا پاسخ نهایی، به‌جز برچسب در صورت پیکربندی،
از نظر بصری ساکت می‌ماند.
پیشرفت ابزار را برای آن نوبت سرکوب می‌کند. کانال تا پاسخ نهایی از نظر بصری آرام می‌ماند،
به‌جز برچسب اگر یکی پیکربندی شده باشد.
## رفتار کانال
@ -249,68 +275,68 @@ OpenClaw از همان قالب‌ساز برای پیش‌نویس‌های پ
| کانال | انتقال پیشرفت | یادداشت‌ها |
| --------------- | -------------------------------------- | --------------------------------------------------------------------- |
| Discord | یک پیام بفرست، سپس آن را ویرایش کن. | وقتی متن نهایی در یک پیام پیش‌نمایش ایمن جا شود، درجا ویرایش می‌شود. |
| Matrix | یک رویداد بفرست، سپس آن را ویرایش کن. | پیکربندی جریان‌دهی در سطح حساب، پیش‌نویس‌های سطح حساب را کنترل می‌کند. |
| Discord | یک پیام بفرست، سپس آن را ویرایش کن. | متن نهایی وقتی در یک پیام پیش‌نمایش ایمن جا شود، درجا ویرایش می‌شود. |
| Matrix | یک رویداد بفرست، سپس آن را ویرایش کن. | پیکربندی جریان در سطح حساب، پیش‌نویس‌های سطح حساب را کنترل می‌کند. |
| Microsoft Teams | جریان بومی Teams در چت‌های شخصی. | `streaming.mode: "block"` به تحویل بلوکی Teams نگاشت می‌شود. |
| Slack | جریان بومی یا پست پیش‌نویس قابل ویرایش. | دسترس‌پذیری رشته تعیین می‌کند آیا می‌توان از جریان‌دهی بومی استفاده کرد. |
| Telegram | یک پیام بفرست، سپس آن را ویرایش کن. | پیش‌نویس‌های قابل مشاهده قدیمی‌تر ممکن است جایگزین شوند تا زمان‌مهرهای نهایی مفید بمانند. |
| Mattermost | پست پیش‌نویس قابل ویرایش. | فعالیت ابزار در همان پست سبک پیش‌نویس ادغام می‌شود. |
| Slack | جریان بومی یا پست پیش‌نویس قابل ویرایش. | دسترس‌پذیری thread روی اینکه آیا جریان بومی قابل استفاده است اثر می‌گذارد. |
| Telegram | یک پیام بفرست، سپس آن را ویرایش کن. | پیش‌نویس‌های visible قدیمی‌تر ممکن است جایگزین شوند تا timestampهای نهایی مفید بمانند. |
| Mattermost | پست پیش‌نویس قابل ویرایش. | فعالیت ابزار در همان پست به سبک پیش‌نویس ادغام می‌شود. |
کانال‌هایی که پشتیبانی ایمن از ویرایش ندارند معمولاً به نشانگرهای تایپ یا
تحویل فقط نهایی بازمی‌گردند.
کانال‌هایی که از ویرایش ایمن پشتیبانی نمی‌کنند معمولاً به نشانگرهای درحال‌تایپ یا
تحویل فقط نهایی fallback می‌کنند.
## نهایی‌سازی
وقتی پاسخ نهایی آماده است، OpenClaw تلاش می‌کند چت را تمیز نگه دارد:
- اگر پیش‌نویس بتواند با ایمنی به پاسخ نهایی تبدیل شود، OpenClaw آن را درجا ویرایش می‌کند.
- اگر کانال از جریان‌دهی پیشرفت بومی استفاده کند، OpenClaw وقتی انتقال بومی متن نهایی را می‌پذیرد
آن جریان را نهایی می‌کند.
- اگر کانال از جریان پیشرفت بومی استفاده کند، OpenClaw آن جریان را
وقتی انتقال بومی متن نهایی را بپذیرد نهایی می‌کند.
- اگر پاسخ نهایی رسانه، درخواست تأیید، هدف پاسخ صریح،
قطعه‌های بیش از حد، یا ویرایش/ارسال ناموفق داشته باشد، OpenClaw پاسخ نهایی را از مسیر
تکه‌های بیش از حد، یا ویرایش/ارسال ناموفق داشته باشد، OpenClaw پاسخ نهایی را از مسیر
تحویل عادی کانال می‌فرستد.
مسیر جایگزین عمدی است. بهتر است یک پاسخ نهایی تازه ارسال شود تا اینکه
متن از دست برود، پاسخ در رشته اشتباه قرار گیرد، یا پیش‌نویس با محتوایی بازنویسی شود که کانال
نتواند آن را با ایمنی نمایش دهد.
مسیر fallback عمدی است. بهتر است یک پاسخ نهایی تازه ارسال شود تا اینکه
متن از دست برود، یک پاسخ در thread اشتباه قرار گیرد، یا پیش‌نویسی با payloadی بازنویسی شود که کانال
نمی‌تواند آن را با ایمنی نمایش دهد.
## عیب‌یابی
**فقط پاسخ نهایی را می‌بینم.**
بررسی کنید `channels.<channel>.streaming.mode` برای حساب یا کانالی که پیام را پردازش کرده
روی `progress` تنظیم شده باشد. برخی مسیرهای گروهی یا پاسخ همراه با نقل‌قول ممکن است
پیش‌نمایش‌های پیش‌نویس را برای یک نوبت غیرفعال کنند، وقتی کانال نتواند پیام درست را با ایمنی
ویرایش کند.
بررسی کنید که `channels.<channel>.streaming.mode` برای حساب یا کانالی که پیام را پردازش کرده
روی `progress` تنظیم شده باشد. برخی مسیرهای گروهی یا quote-reply ممکن است
پیش‌نمایش‌های پیش‌نویس را برای یک نوبت غیرفعال کنند وقتی کانال نتواند پیام درست را
با ایمنی ویرایش کند.
**برچسب را می‌بینم اما خطوط ابزار را نه.**
**برچسب را می‌بینم اما خطوط ابزار را نمی‌بینم.**
`streaming.progress.toolProgress` را بررسی کنید. اگر `false` باشد، OpenClaw رفتار
پیش‌نویس تکی را نگه می‌دارد اما خطوط پیشرفت ابزار و وظیفه را پنهان می‌کند.
پیش‌نویس واحد را نگه می‌دارد اما خطوط پیشرفت ابزار و کار را پنهان می‌کند.
**به‌جای پیش‌نویس ویرایش‌شده، یک پیام نهایی تازه می‌بینم.**
**به‌جای پیش‌نویس ویرایش‌شده یک پیام نهایی تازه می‌بینم.**
این یک مسیر جایگزین ایمنی است. ممکن است برای پاسخ‌های رسانه‌ای، پاسخ‌های طولانی،
هدف‌های پاسخ صریح، پیش‌نویس‌های قدیمی Telegram، هدف‌های رشته گم‌شده Slack،
این یک fallback ایمنی است. این می‌تواند برای پاسخ‌های رسانه‌ای، پاسخ‌های طولانی،
هدف‌های پاسخ صریح، پیش‌نویس‌های قدیمی Telegram، هدف‌های thread گم‌شده Slack،
پیام‌های پیش‌نمایش حذف‌شده، یا نهایی‌سازی ناموفق جریان بومی رخ دهد.
**هنوز پیام‌های پیشرفت مستقل را می‌بینم.**
**هنوز پیام‌های پیشرفت مستقل می‌بینم.**
حالت پیشرفت وقتی یک پیش‌نویس فعال باشد پیام‌های پیش‌فرض مستقل پیشرفت ابزار را سرکوب می‌کند.
اگر پیام‌های مستقل هنوز ظاهر می‌شوند، بررسی کنید که نوبت واقعاً از حالت پیشرفت استفاده می‌کند
و نه `streaming.mode: "off"` یا مسیر کانالی که
نمی‌تواند برای آن پیام پیش‌نویس ایجاد کند.
حالت پیشرفت وقتی یک پیش‌نویس فعال باشد، پیام‌های پیش‌فرض مستقل پیشرفت ابزار را سرکوب می‌کند.
اگر پیام‌های مستقل همچنان ظاهر می‌شوند، تأیید کنید که نوبت واقعاً
از حالت پیشرفت استفاده می‌کند و نه `streaming.mode: "off"` یا یک مسیر کانالی که
نمی‌تواند برای آن پیام پیش‌نویس بسازد.
**Teams متفاوت از Discord یا Telegram رفتار می‌کند.**
Microsoft Teams در چت‌های شخصی به‌جای انتقال پیش‌نمایش عمومیِ ارسال و ویرایش،
Microsoft Teams در چت‌های شخصی به‌جای انتقال عمومی پیش‌نمایش send-and-edit،
از جریان بومی استفاده می‌کند. Teams همچنین `streaming.mode: "block"` را به‌عنوان
تحویل بلوکی Teams در نظر می‌گیرد، چون همان حالت بلوکیِ پیش‌نمایش پیش‌نویس را که
تحویل بلوکی Teams در نظر می‌گیرد، زیرا همان حالت بلوکی پیش‌نمایش پیش‌نویس را که
Discord و Telegram استفاده می‌کنند ندارد.
## مرتبط
- [جریان‌دهی و قطعه‌بندی](/fa/concepts/streaming)
- [جریان و قطعه‌بندی](/fa/concepts/streaming)
- [پیام‌ها](/fa/concepts/messages)
- [پیکربندی کانال](/fa/gateway/config-channels)
- [Discord](/fa/channels/discord)

447
docs/fa/concepts/qa-e2e-automation.md
View File

@ -1,82 +1,82 @@
---
read_when:
- درک اینکه پشتهٔ QA چگونه کنار هم قرار می‌گیرد
- گسترش qa-lab، qa-channel یا یک آداپتور ترابری
- درک نحوهٔ قرارگیری اجزای پشتهٔ QA در کنار هم
- گسترش qa-lab، qa-channel یا یک آداپتور انتقال
- افزودن سناریوهای تضمین کیفیت مبتنی بر مخزن
- ساخت خودکارسازی تضمین کیفیت واقع‌گرایانه‌تر برای داشبورد Gateway
summary: 'نمای کلی پشته QA: qa-lab، qa-channel، سناریوهای متکی به مخزن، مسیرهای انتقال زنده، آداپتورهای انتقال و گزارش‌دهی.'
title: نمای کلی QA
- ساخت اتوماسیون تضمین کیفیت واقع‌گرایانه‌تر برای داشبورد Gateway
summary: 'نمای کلی پشتهٔ تضمین کیفیت: qa-lab، qa-channel، سناریوهای مبتنی بر مخزن، مسیرهای انتقال زنده، آداپتورهای انتقال، و گزارش‌دهی.'
title: نمای کلی تضمین کیفیت
x-i18n:
generated_at: "2026-05-04T02:24:18Z"
generated_at: "2026-05-04T07:05:38Z"
model: gpt-5.5
provider: openai
source_hash: 0b376767b967a51cc8a45ca5ce420f78067b52e6368d2abe921ffed533f6f9ba
source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29
source_path: concepts/qa-e2e-automation.md
workflow: 16
---
پشته QA خصوصی قرار است OpenClaw را به شکلی واقعی‌تر و
کانال‌محورتر از چیزی که یک آزمون واحد می‌تواند پوشش دهد، تمرین دهد.
استک خصوصی QA برای آن است که OpenClaw را به شکلی واقعی‌تر و
کانال‌محورتر از آنچه یک آزمون واحد می‌تواند انجام دهد، تمرین دهد.
اجزای فعلی:
- `extensions/qa-channel`: کانال پیام مصنوعی با سطوح DM، کانال، رشته،
واکنش، ویرایش، و حذف.
- `extensions/qa-lab`: رابط اشکال‌زدایی و گذرگاه QA برای مشاهده رونوشت،
- `extensions/qa-lab`: رابط کاربری اشکال‌زدا و گذرگاه QA برای مشاهده رونوشت،
تزریق پیام‌های ورودی، و صادر کردن گزارش Markdown.
- `extensions/qa-matrix`، Pluginهای اجراکننده آینده: آداپترهای انتقال زنده که
- `extensions/qa-matrix`، Pluginهای اجراکننده آینده: آداپتورهای انتقال زنده که
یک کانال واقعی را داخل یک Gateway فرزند QA هدایت می‌کنند.
- `qa/`: دارایی‌های اولیه متکی به مخزن برای وظیفه آغازین و سناریوهای پایه
QA.
- `qa/`: دارایی‌های seed پشتیبانی‌شده با مخزن برای وظیفه آغازین و سناریوهای
پایه QA.
- [Mantis](/fa/concepts/mantis): راستی‌آزمایی زنده قبل و بعد برای باگ‌هایی که
به انتقال‌های واقعی، اسکرین‌شات‌های مرورگر، وضعیت VM، و شواهد PR نیاز دارند.
## سطح فرمان
هر جریان QA زیر `pnpm openclaw qa <subcommand>` اجرا می‌شود. بسیاری از آن‌ها نام مستعار اسکریپت `pnpm qa:*`
هر جریان QA زیر `pnpm openclaw qa <subcommand>` اجرا می‌شود. بسیاری از آن‌ها نام‌های مستعار اسکریپتی `pnpm qa:*`
دارند؛ هر دو شکل پشتیبانی می‌شوند.
| فرمان | هدف |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | خودآزمایی QA بسته‌بندی‌شده؛ یک گزارش Markdown می‌نویسد. |
| `qa suite` | سناریوهای متکی به مخزن را در برابر خط Gateway QA اجرا می‌کند. نام‌های مستعار: `pnpm openclaw qa suite --runner multipass` برای یک VM لینوکسی یک‌بارمصرف. |
| `qa coverage` | فهرست پوشش سناریوی markdown را چاپ می‌کند (`--json` برای خروجی ماشینی). |
| `qa parity-report` | دو فایل `qa-suite-summary.json` را مقایسه می‌کند و گزارش برابری عاملی را می‌نویسد. |
| `qa character-eval` | سناریوی QA شخصیت را روی چند مدل زنده با یک گزارش داوری‌شده اجرا می‌کند. [گزارش‌دهی](#reporting) را ببینید. |
| `qa manual` | یک درخواست یک‌باره را در برابر خط provider/model انتخاب‌شده اجرا می‌کند. |
| `qa ui` | رابط اشکال‌زدایی QA و گذرگاه محلی QA را شروع می‌کند (نام مستعار: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | تصویر Docker از پیش پخته‌شده QA را می‌سازد. |
| `qa docker-scaffold` | یک داربست docker-compose برای داشبورد QA + خط Gateway می‌نویسد. |
| `qa up` | سایت QA را می‌سازد، پشته متکی به Docker را شروع می‌کند، و URL را چاپ می‌کند (نام مستعار: `pnpm qa:lab:up`؛ گونه `:fast` گزینه‌های `--use-prebuilt-image --bind-ui-dist --skip-ui-build` را اضافه می‌کند). |
| `qa aimock` | فقط سرور provider AIMock را شروع می‌کند. |
| `qa mock-openai` | فقط سرور provider آگاه از سناریوی `mock-openai` را شروع می‌کند. |
| `qa credentials doctor` / `add` / `list` / `remove` | مخزن مشترک اعتبارنامه Convex را مدیریت می‌کند. |
| `qa matrix` | خط انتقال زنده در برابر یک homeserver یک‌بارمصرف Tuwunel. [Matrix QA](/fa/concepts/qa-matrix) را ببینید. |
| `qa telegram` | خط انتقال زنده در برابر یک گروه خصوصی واقعی Telegram. |
| `qa discord` | خط انتقال زنده در برابر یک کانال guild خصوصی واقعی Discord. |
| `qa slack` | خط انتقال زنده در برابر یک کانال خصوصی واقعی Slack. |
| `qa mantis` | اجراکننده راستی‌آزمایی قبل و بعد برای باگ‌های انتقال زنده، همراه با شواهد واکنش‌های وضعیت Discord و یک smoke دسکتاپ/مرورگر Crabbox. [Mantis](/fa/concepts/mantis) را ببینید. |
| فرمان | هدف |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | خودآزمایی QA همراه بسته؛ یک گزارش Markdown می‌نویسد. |
| `qa suite` | سناریوهای پشتیبانی‌شده با مخزن را در برابر مسیر Gateway QA اجرا می‌کند. نام مستعار: `pnpm openclaw qa suite --runner multipass` برای یک VM یک‌بارمصرف Linux. |
| `qa coverage` | موجودی پوشش سناریو به صورت markdown را چاپ می‌کند (`--json` برای خروجی ماشینی). |
| `qa parity-report` | دو فایل `qa-suite-summary.json` را مقایسه می‌کند و گزارش برابری عامل‌محور را می‌نویسد. |
| `qa character-eval` | سناریوی QA شخصیت را روی چند مدل زنده با گزارشی داوری‌شده اجرا می‌کند. [گزارش‌دهی](#reporting) را ببینید. |
| `qa manual` | یک اعلان یک‌باره را در برابر مسیر provider/model انتخاب‌شده اجرا می‌کند. |
| `qa ui` | رابط کاربری اشکال‌زدای QA و گذرگاه محلی QA را شروع می‌کند (نام مستعار: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | تصویر ازپیش‌آماده Docker QA را می‌سازد. |
| `qa docker-scaffold` | یک اسکفولد docker-compose برای داشبورد QA + مسیر Gateway می‌نویسد. |
| `qa up` | سایت QA را می‌سازد، استک پشتیبانی‌شده با Docker را شروع می‌کند، URL را چاپ می‌کند (نام مستعار: `pnpm qa:lab:up`؛ گونه `:fast` گزینه‌های `--use-prebuilt-image --bind-ui-dist --skip-ui-build` را اضافه می‌کند). |
| `qa aimock` | فقط سرور provider مربوط به AIMock را شروع می‌کند. |
| `qa mock-openai` | فقط سرور provider سناریوآگاه `mock-openai` را شروع می‌کند. |
| `qa credentials doctor` / `add` / `list` / `remove` | مخزن اعتبارنامه مشترک Convex را مدیریت می‌کند. |
| `qa matrix` | مسیر انتقال زنده در برابر یک homeserver یک‌بارمصرف Tuwunel. [Matrix QA](/fa/concepts/qa-matrix) را ببینید. |
| `qa telegram` | مسیر انتقال زنده در برابر یک گروه خصوصی واقعی Telegram. |
| `qa discord` | مسیر انتقال زنده در برابر یک کانال guild خصوصی واقعی Discord. |
| `qa slack` | مسیر انتقال زنده در برابر یک کانال خصوصی واقعی Slack. |
| `qa mantis` | اجراکننده راستی‌آزمایی قبل و بعد برای باگ‌های انتقال زنده، همراه با شواهد واکنش‌های وضعیت Discord، smoke دسکتاپ/مرورگر Crabbox، و smoke مربوط به Slack در VNC. [Mantis](/fa/concepts/mantis) را ببینید. |
## جریان اپراتور
جریان فعلی اپراتور QA یک سایت QA دو صفحه‌ای است:
جریان فعلی اپراتور QA یک سایت QA دوپنجره‌ای است:
- چپ: داشبورد Gateway (Control UI) همراه با عامل.
- چپ: داشبورد Gateway (Control UI) همراه عامل.
- راست: QA Lab، که رونوشت شبیه Slack و برنامه سناریو را نشان می‌دهد.
آن را با این فرمان اجرا کنید:
آن را با این اجرا کنید:
```bash
pnpm qa:lab:up
```
این کار سایت QA را می‌سازد، خط Gateway متکی به Docker را شروع می‌کند، و صفحه
QA Lab را در دسترس قرار می‌دهد؛ جایی که یک اپراتور یا حلقه خودکارسازی می‌تواند به عامل یک مأموریت QA
بدهد، رفتار کانال واقعی را مشاهده کند، و ثبت کند چه چیزی کار کرد، شکست خورد، یا
این فرمان سایت QA را می‌سازد، مسیر Gateway پشتیبانی‌شده با Docker را شروع می‌کند، و صفحه
QA Lab را در دسترس قرار می‌دهد؛ جایی که یک اپراتور یا حلقه خودکار می‌تواند به عامل یک مأموریت QA
بدهد، رفتار واقعی کانال را مشاهده کند، و ثبت کند چه چیزی کار کرد، شکست خورد، یا
مسدود ماند.
برای تکرار سریع‌تر روی رابط QA Lab بدون بازسازی تصویر Docker در هر بار،
پشته را با یک بسته QA Lab متصل‌شده از طریق bind mount شروع کنید:
برای تکرار سریع‌تر روی رابط کاربری QA Lab بدون ساخت دوباره تصویر Docker در هر بار،
استک را با یک بسته QA Lab متصل‌شده با bind mount شروع کنید:
```bash
pnpm openclaw qa docker-build-image
@ -85,39 +85,39 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` سرویس‌های Docker را روی یک تصویر از پیش ساخته‌شده نگه می‌دارد و
`extensions/qa-lab/web/dist` را در کانتینر `qa-lab` به‌صورت bind-mount متصل می‌کند. `qa:lab:watch`
آن بسته را هنگام تغییر بازسازی می‌کند، و مرورگر وقتی هش دارایی QA Lab
`qa:lab:up:fast` سرویس‌های Docker را روی یک تصویر ازپیش‌ساخته نگه می‌دارد و
`extensions/qa-lab/web/dist` را داخل کانتینر `qa-lab` با bind mount متصل می‌کند. `qa:lab:watch`
آن بسته را هنگام تغییر دوباره می‌سازد، و مرورگر وقتی hash دارایی QA Lab
تغییر کند به‌صورت خودکار بارگذاری مجدد می‌شود.
برای یک smoke محلی ردیابی OpenTelemetry، اجرا کنید:
برای یک smoke محلی OpenTelemetry trace، اجرا کنید:
```bash
pnpm qa:otel:smoke
```
آن اسکریپت یک گیرنده محلی ردیابی OTLP/HTTP را شروع می‌کند، سناریوی QA
`otel-trace-smoke` را با Plugin `diagnostics-otel` فعال اجرا می‌کند، سپس
spanهای protobuf صادرشده را رمزگشایی می‌کند و شکل حیاتی برای انتشار را بررسی می‌کند:
این اسکریپت یک گیرنده trace محلی OTLP/HTTP را شروع می‌کند، سناریوی QA
`otel-trace-smoke` را با Plugin فعال `diagnostics-otel` اجرا می‌کند، سپس
spanهای protobuf صادرشده را رمزگشایی می‌کند و شکل حیاتی برای انتشار را assert می‌کند:
`openclaw.run`، `openclaw.harness.run`، `openclaw.model.call`،
`openclaw.context.assembled`، و `openclaw.message.delivery` باید وجود داشته باشند؛
فراخوانی‌های مدل نباید در نوبت‌های موفق `StreamAbandoned` صادر کنند؛ شناسه‌های خام تشخیصی و
ویژگی‌های `openclaw.content.*` باید خارج از ردیابی بمانند. این اسکریپت
`otel-smoke-summary.json` را کنار مصنوعات مجموعه QA می‌نویسد.
`openclaw.context.assembled`، و `openclaw.message.delivery` باید حاضر باشند؛
فراخوانی‌های مدل نباید در نوبت‌های موفق `StreamAbandoned` صادر کنند؛ شناسه‌های خام diagnostic و
attributeهای `openclaw.content.*` باید بیرون از trace بمانند. این اسکریپت
`otel-smoke-summary.json` را کنار artifactهای مجموعه QA می‌نویسد.
QA مشاهده‌پذیری فقط مخصوص checkout منبع می‌ماند. tarball npm عمداً
QA Lab را حذف می‌کند، بنابراین خط‌های انتشار Docker بسته فرمان‌های `qa` را اجرا نمی‌کنند. هنگام تغییر ابزارگذاری تشخیصی،
از `pnpm qa:otel:smoke` در یک checkout ساخته‌شده از منبع استفاده کنید.
QA مشاهده‌پذیری فقط مخصوص checkout منبع باقی می‌ماند. tarball مربوط به npm عمداً
QA Lab را حذف می‌کند، بنابراین مسیرهای انتشار Docker بسته فرمان‌های `qa` را اجرا نمی‌کنند. هنگام تغییر instrumentation تشخیصی،
از `pnpm qa:otel:smoke` در یک checkout منبع ساخته‌شده استفاده کنید.
برای یک خط smoke واقعی از نظر انتقال برای Matrix، اجرا کنید:
برای یک مسیر smoke مربوط به Matrix با انتقال واقعی، اجرا کنید:
```bash
pnpm openclaw qa matrix --profile fast --fail-fast
```
مرجع کامل CLI، کاتالوگ پروفایل/سناریو، متغیرهای env، و چیدمان مصنوعات برای این خط در [Matrix QA](/fa/concepts/qa-matrix) قرار دارد. در یک نگاه: این فرمان یک homeserver یک‌بارمصرف Tuwunel را در Docker فراهم می‌کند، کاربران موقت driver/SUT/observer را ثبت می‌کند، Plugin واقعی Matrix را داخل یک Gateway فرزند QA محدود به همان انتقال اجرا می‌کند (بدون `qa-channel`)، سپس یک گزارش Markdown، خلاصه JSON، مصنوع observed-events، و لاگ خروجی ترکیبی را زیر `.artifacts/qa-e2e/matrix-<timestamp>/` می‌نویسد.
مرجع کامل CLI، کاتالوگ profile/scenario، env varها، و چیدمان artifact برای این مسیر در [Matrix QA](/fa/concepts/qa-matrix) قرار دارد. در یک نگاه: این مسیر یک homeserver یک‌بارمصرف Tuwunel را در Docker فراهم می‌کند، کاربران موقت driver/SUT/observer را ثبت می‌کند، Plugin واقعی Matrix را داخل یک Gateway فرزند QA محدود به همان انتقال اجرا می‌کند (بدون `qa-channel`)، سپس یک گزارش Markdown، خلاصه JSON، artifact رویدادهای مشاهده‌شده، و log خروجی ترکیبی را زیر `.artifacts/qa-e2e/matrix-<timestamp>/` می‌نویسد.
برای خط‌های smoke واقعی از نظر انتقال برای Telegram، Discord، و Slack:
برای مسیرهای smoke با انتقال واقعی Telegram، Discord، و Slack:
```bash
pnpm openclaw qa telegram
@ -125,92 +125,107 @@ pnpm openclaw qa discord
pnpm openclaw qa slack
```
آن‌ها یک کانال واقعی از پیش موجود با دو ربات (driver + SUT) را هدف می‌گیرند. متغیرهای env لازم، فهرست سناریوها، مصنوعات خروجی، و مخزن اعتبارنامه Convex در [مرجع QA برای Telegram، Discord، و Slack](#telegram-discord-and-slack-qa-reference) در ادامه مستند شده‌اند.
این مسیرها یک کانال واقعی ازپیش‌موجود با دو bot (driver + SUT) را هدف می‌گیرند. env varهای لازم، فهرست‌های سناریو، artifactهای خروجی، و مخزن اعتبارنامه Convex در [مرجع QA مربوط به Telegram، Discord، و Slack](#telegram-discord-and-slack-qa-reference) در ادامه مستند شده‌اند.
قبل از استفاده از اعتبارنامه‌های زنده تجمیع‌شده، اجرا کنید:
برای یک اجرای کامل Slack desktop VM همراه نجات VNC، اجرا کنید:
```bash
pnpm openclaw qa mantis slack-desktop-smoke \
--gateway-setup \
--scenario slack-canary \
--keep-lease
```
این فرمان یک ماشین دسکتاپ/مرورگر Crabbox را lease می‌کند، مسیر زنده Slack را
داخل VM اجرا می‌کند، Slack Web را در مرورگر VNC باز می‌کند، از دسکتاپ تصویر می‌گیرد، و
`slack-qa/` به‌همراه `slack-desktop-smoke.png` را به دایرکتوری artifact
Mantis برمی‌گرداند. پس از ورود دستی به Slack Web از طریق VNC،
`--lease-id <cbx_...>` را دوباره استفاده کنید. با `--gateway-setup`، Mantis یک Gateway پایدار OpenClaw Slack را
داخل VM روی پورت `38973` در حال اجرا باقی می‌گذارد؛ بدون آن، فرمان مسیر QA معمولی
bot-to-bot مربوط به Slack را اجرا می‌کند و پس از ضبط artifact خارج می‌شود.
پیش از استفاده از اعتبارنامه‌های زنده pooled، اجرا کنید:
```bash
pnpm openclaw qa credentials doctor
```
doctor متغیرهای env کارگزار Convex را بررسی می‌کند، تنظیمات endpoint را اعتبارسنجی می‌کند، و وقتی secret نگهدارنده حاضر باشد دسترسی‌پذیری admin/list را راستی‌آزمایی می‌کند. برای secretها فقط وضعیت تنظیم‌شده/مفقود را گزارش می‌دهد.
doctor محیط broker مربوط به Convex را بررسی می‌کند، تنظیمات endpoint را اعتبارسنجی می‌کند، و وقتی secret نگه‌دارنده حاضر باشد دسترسی admin/list را تأیید می‌کند. برای secretها فقط وضعیت set/missing را گزارش می‌دهد.
## پوشش انتقال زنده
خط‌های انتقال زنده به‌جای اینکه هرکدام شکل فهرست سناریوی خودشان را اختراع کنند، یک قرارداد مشترک دارند. `qa-channel` مجموعه مصنوعی گسترده رفتار محصول است و بخشی از ماتریس پوشش انتقال زنده نیست.
مسیرهای انتقال زنده به‌جای اینکه هرکدام شکل فهرست سناریوی خودشان را بسازند، یک قرارداد مشترک دارند. `qa-channel` مجموعه گسترده رفتار محصول به‌صورت مصنوعی است و بخشی از ماتریس پوشش انتقال زنده نیست.
| خط | Canary | دروازه‌بانی mention | ربات-به-ربات | مسدودسازی allowlist | پاسخ سطح بالا | ازسرگیری پس از restart | پیگیری رشته | جداسازی رشته | مشاهده واکنش | فرمان help | ثبت فرمان بومی |
| مسیر | Canary | دروازه‌گذاری mention | Bot-to-bot | مسدودسازی allowlist | پاسخ سطح بالا | ازسرگیری پس از restart | پیگیری رشته | جداسازی رشته | مشاهده واکنش | فرمان help | ثبت فرمان بومی |
| -------- | ------ | -------------- | ---------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Slack | x | x | x | | | | | | | | |
این کار `qa-channel` را به‌عنوان مجموعه گسترده رفتار محصول نگه می‌دارد، در حالی که Matrix،
Telegram، و انتقال‌های زنده آینده یک چک‌لیست صریح قرارداد انتقال را
به اشتراک می‌گذارند.
این کار `qa-channel` را به‌عنوان مجموعه گسترده رفتار محصول نگه می‌دارد، درحالی‌که Matrix،
Telegram، و انتقال‌های زنده آینده یک چک‌لیست صریح قرارداد انتقال مشترک دارند.
برای یک خط VM لینوکسی یک‌بارمصرف بدون وارد کردن Docker به مسیر QA، اجرا کنید:
برای یک مسیر Linux VM یک‌بارمصرف بدون وارد کردن Docker به مسیر QA، اجرا کنید:
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
این فرمان یک مهمان تازه Multipass را بوت می‌کند، وابستگی‌ها را نصب می‌کند، OpenClaw را
داخل مهمان می‌سازد، `qa suite` را اجرا می‌کند، سپس گزارش QA معمول و
این کار یک مهمان تازه Multipass را بوت می‌کند، وابستگی‌ها را نصب می‌کند، OpenClaw را
داخل مهمان می‌سازد، `qa suite` را اجرا می‌کند، سپس گزارش عادی QA و
خلاصه را به `.artifacts/qa-e2e/...` روی میزبان کپی می‌کند.
این همان رفتار انتخاب سناریو را که `qa suite` روی میزبان دارد دوباره استفاده می‌کند.
اجراهای مجموعه روی میزبان و Multipass به‌صورت پیش‌فرض چند سناریوی انتخاب‌شده را به‌صورت موازی
با workerهای Gateway ایزوله اجرا می‌کنند. مقدار پیش‌فرض هم‌روندی `qa-channel`
4 است و به تعداد سناریوهای انتخاب‌شده محدود می‌شود. برای تنظیم
تعداد workerها از `--concurrency <count>` استفاده کنید، یا برای اجرای سریالی
`--concurrency 1` را به کار ببرید.
وقتی هر سناریویی شکست بخورد، فرمان با مقدار غیرصفر خارج می‌شود. وقتی
مصنوعات را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید.
اجراهای زنده ورودی‌های پشتیبانی‌شده احراز هویت QA را که برای
مهمان عملی هستند ارسال می‌کنند: کلیدهای provider مبتنی بر env، مسیر پیکربندی provider زنده QA، و
`CODEX_HOME` وقتی حاضر باشد. `--output-dir` را زیر ریشه مخزن نگه دارید تا مهمان
بتواند از طریق workspace متصل‌شده دوباره بنویسد.
این همان رفتار انتخاب سناریو را که `qa suite` روی میزبان دارد، دوباره استفاده می‌کند.
اجرای مجموعه روی میزبان و Multipass به‌صورت پیش‌فرض چند سناریوی انتخاب‌شده را به‌طور موازی
با workerهای Gateway ایزوله اجرا می‌کند. `qa-channel` به‌صورت پیش‌فرض هم‌روندی
4 دارد که به تعداد سناریوهای انتخاب‌شده محدود می‌شود. از `--concurrency <count>` برای تنظیم
تعداد workerها، یا از `--concurrency 1` برای اجرای سریالی استفاده کنید.
وقتی هر سناریویی شکست بخورد، فرمان با کد غیرصفر خارج می‌شود. وقتی
artifactها را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید.
اجرای زنده ورودی‌های پشتیبانی‌شده احراز هویت QA را که برای مهمان عملی هستند
forward می‌کند: کلیدهای provider مبتنی بر env، مسیر پیکربندی provider زنده QA، و
`CODEX_HOME` در صورت وجود. `--output-dir` را زیر ریشه repo نگه دارید تا مهمان
بتواند از طریق workspace mountشده بنویسد.
## مرجع QA برای Telegram، Discord، و Slack
Matrix به‌دلیل تعداد سناریوها و فراهم‌سازی homeserver متکی به Docker، یک [صفحه اختصاصی](/fa/concepts/qa-matrix) دارد. Telegram، Discord، و Slack کوچک‌تر هستند - هرکدام چند سناریو، بدون سیستم پروفایل، در برابر کانال‌های واقعی از پیش موجود - بنابراین مرجع آن‌ها اینجا قرار دارد.
Matrix به‌دلیل تعداد سناریوها و آماده‌سازی homeserver مبتنی بر Docker یک [صفحه اختصاصی](/fa/concepts/qa-matrix) دارد. Telegram، Discord، و Slack کوچک‌تر هستند — هرکدام چند سناریو، بدون سیستم profile، در برابر کانال‌های واقعی از پیش موجود — بنابراین مرجع آن‌ها اینجا قرار دارد.
### پرچم‌های مشترک CLI
این خط‌ها از طریق `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` ثبت می‌شوند و همان پرچم‌ها را می‌پذیرند:
این laneها از طریق `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` ثبت می‌شوند و همان پرچم‌ها را می‌پذیرند:
| پرچم | پیش‌فرض | توضیح |
| ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | فقط این سناریو را اجرا می‌کند. قابل تکرار است. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | محل نوشته شدن گزارش‌ها/خلاصه/پیام‌های مشاهده‌شده و لاگ خروجی. مسیرهای نسبی نسبت به `--repo-root` تفسیر می‌شوند. |
| `--repo-root <path>` | `process.cwd()` | ریشه مخزن هنگام فراخوانی از یک cwd خنثی. |
| `--sut-account <id>` | `sut` | شناسه حساب موقت داخل پیکربندی QA Gateway. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | محل نوشتن گزارش‌ها/خلاصه/پیام‌های مشاهده‌شده و لاگ خروجی. مسیرهای نسبی نسبت به `--repo-root` resolve می‌شوند. |
| `--repo-root <path>` | `process.cwd()` | ریشه repository هنگام فراخوانی از یک cwd خنثی. |
| `--sut-account <id>` | `sut` | id حساب موقت داخل پیکربندی Gateway QA. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` یا `live-frontier`؛ مقدار قدیمی `live-openai` همچنان کار می‌کند. |
| `--model <ref>` / `--alt-model <ref>` | پیش‌فرض ارائه‌دهنده | ارجاع‌های مدل اصلی/جایگزین. |
| `--fast` | خاموش | حالت سریع ارائه‌دهنده در جاهایی که پشتیبانی شود. |
| `--model <ref>` / `--alt-model <ref>` | پیش‌فرض provider | refهای model اصلی/جایگزین. |
| `--fast` | خاموش | حالت سریع provider در جاهایی که پشتیبانی می‌شود. |
| `--credential-source <env\|convex>` | `env` | [استخر اعتبارنامه Convex](#convex-credential-pool) را ببینید. |
| `--credential-role <maintainer\|ci>` | `ci` در CI، در غیر این صورت `maintainer` | نقشی که هنگام `--credential-source convex` استفاده می‌شود. |
هر lane در صورت شکست هر سناریو با کد غیرصفر خارج می‌شود. `--allow-failures` آرتیفکت‌ها را بدون تنظیم کد خروجی شکست‌خورده می‌نویسد.
هر lane در صورت شکست هر سناریو با کد غیرصفر خارج می‌شود. `--allow-failures` artifactها را بدون تنظیم کد خروج شکست‌خورده می‌نویسد.
### QA در Telegram
### QA برای Telegram
```bash
pnpm openclaw qa telegram
```
یک گروه خصوصی واقعی Telegram را با دو ربات متمایز هدف می‌گیرد (driver + SUT). ربات SUT باید نام کاربری Telegram داشته باشد؛ مشاهده ربات‌به‌ربات زمانی بهتر کار می‌کند که هر دو ربات **حالت ارتباط ربات‌به‌ربات** را در `@BotFather` فعال کرده باشند.
یک گروه خصوصی واقعی Telegram را با دو bot متمایز (driver + SUT) هدف می‌گیرد. bot مربوط به SUT باید username در Telegram داشته باشد؛ مشاهده bot-to-bot وقتی بهتر کار می‌کند که هر دو bot **Bot-to-Bot Communication Mode** را در `@BotFather` فعال کرده باشند.
env لازم هنگام `--credential-source env`:
envهای لازم هنگام `--credential-source env`:
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — شناسه عددی چت (رشته).
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — chat id عددی (string).
- `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`
اختیاری:
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` بدنه پیام‌ها را در آرتیفکت‌های پیام مشاهده‌شده نگه می‌دارد (پیش‌فرض آن‌ها را ویرایش می‌کند).
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` بدنه پیام‌ها را در artifactهای پیام مشاهده‌شده نگه می‌دارد (پیش‌فرض redact می‌کند).
سناریوها (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`):
@ -223,38 +238,38 @@ env لازم هنگام `--credential-source env`:
- `telegram-whoami-command`
- `telegram-context-command`
آرتیفکت‌های خروجی:
artifactهای خروجی:
- `telegram-qa-report.md`
- `telegram-qa-summary.json` — شامل RTT هر پاسخ (ارسال driver → پاسخ مشاهده‌شده SUT) که از canary شروع می‌شود.
- `telegram-qa-observed-messages.json` — بدنه‌ها ویرایش می‌شوند مگر اینکه `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` باشد.
- `telegram-qa-summary.json` — شامل RTT برای هر reply (ارسال driver → reply مشاهده‌شده SUT) از canary به بعد.
- `telegram-qa-observed-messages.json` — بدنه‌ها redact می‌شوند مگر اینکه `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` باشد.
### QA در Discord
### QA برای Discord
```bash
pnpm openclaw qa discord
```
یک کانال guild خصوصی واقعی Discord را با دو ربات هدف می‌گیرد: یک ربات driver که توسط harness کنترل می‌شود و یک ربات SUT که توسط OpenClaw Gateway فرزند از طریق Plugin داخلی Discord شروع می‌شود. مدیریت mention کانال، اینکه ربات SUT دستور بومی `/help` را در Discord ثبت کرده باشد، و سناریوهای شواهد opt-in مربوط به Mantis را بررسی می‌کند.
یک کانال guild خصوصی واقعی Discord را با دو bot هدف می‌گیرد: یک bot driver که توسط harness کنترل می‌شود و یک bot SUT که توسط Gateway فرزند OpenClaw از طریق Plugin بسته‌بندی‌شده Discord راه‌اندازی می‌شود. مدیریت mention کانال، اینکه bot مربوط به SUT فرمان native `/help` را در Discord ثبت کرده باشد، و سناریوهای شواهد Mantis به‌صورت opt-in را بررسی می‌کند.
env لازم هنگام `--credential-source env`:
envهای لازم هنگام `--credential-source env`:
- `OPENCLAW_QA_DISCORD_GUILD_ID`
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — باید با شناسه کاربر ربات SUT که Discord برمی‌گرداند مطابقت داشته باشد (در غیر این صورت lane سریع شکست می‌خورد).
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — باید با id کاربر bot مربوط به SUT که Discord برمی‌گرداند مطابقت داشته باشد (در غیر این صورت lane زود شکست می‌خورد).
اختیاری:
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` بدنه پیام‌ها را در آرتیفکت‌های پیام مشاهده‌شده نگه می‌دارد.
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` بدنه پیام‌ها را در artifactهای پیام مشاهده‌شده نگه می‌دارد.
سناریوها (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`):
- `discord-canary`
- `discord-mention-gating`
- `discord-native-help-command-registration`
- `discord-status-reactions-tool-only` — سناریوی opt-in مربوط به Mantis. به‌تنهایی اجرا می‌شود، چون SUT را به پاسخ‌های guild همیشه‌فعال و فقط‌ابزاری با `messages.statusReactions.enabled=true` تغییر می‌دهد، سپس یک خط زمانی واکنش REST به‌همراه یک آرتیفکت بصری HTML/PNG ثبت می‌کند.
- `discord-status-reactions-tool-only` — سناریوی opt-in Mantis. به‌تنهایی اجرا می‌شود چون SUT را به replyهای guild همیشه‌فعال و فقط ابزاری با `messages.statusReactions.enabled=true` تغییر می‌دهد، سپس یک timeline واکنش REST به‌همراه یک artifact بصری HTML/PNG ثبت می‌کند.
سناریوی واکنش وضعیت Mantis را صراحتا اجرا کنید:
@ -267,22 +282,22 @@ pnpm openclaw qa discord \
--fast
```
آرتیفکت‌های خروجی:
artifactهای خروجی:
- `discord-qa-report.md`
- `discord-qa-summary.json`
- `discord-qa-observed-messages.json` — بدنه‌ها ویرایش می‌شوند مگر اینکه `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` باشد.
- `discord-qa-reaction-timelines.json` و `discord-status-reactions-tool-only-timeline.png` هنگام اجرای سناریوی واکنش وضعیت.
- `discord-qa-observed-messages.json` — بدنه‌ها redact می‌شوند مگر اینکه `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` باشد.
- `discord-qa-reaction-timelines.json` و `discord-status-reactions-tool-only-timeline.png` وقتی سناریوی واکنش وضعیت اجرا شود.
### QA در Slack
### QA برای Slack
```bash
pnpm openclaw qa slack
```
یک کانال خصوصی واقعی Slack را با دو ربات متمایز هدف می‌گیرد: یک ربات driver که توسط harness کنترل می‌شود و یک ربات SUT که توسط OpenClaw Gateway فرزند از طریق Plugin داخلی Slack شروع می‌شود.
یک کانال خصوصی واقعی Slack را با دو bot متمایز هدف می‌گیرد: یک bot driver که توسط harness کنترل می‌شود و یک bot SUT که توسط Gateway فرزند OpenClaw از طریق Plugin بسته‌بندی‌شده Slack راه‌اندازی می‌شود.
env لازم هنگام `--credential-source env`:
envهای لازم هنگام `--credential-source env`:
- `OPENCLAW_QA_SLACK_CHANNEL_ID`
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
@ -291,143 +306,146 @@ env لازم هنگام `--credential-source env`:
اختیاری:
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` بدنه پیام‌ها را در آرتیفکت‌های پیام مشاهده‌شده نگه می‌دارد.
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` بدنه پیام‌ها را در artifactهای پیام مشاهده‌شده نگه می‌دارد.
سناریوها (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`):
- `slack-canary`
- `slack-mention-gating`
آرتیفکت‌های خروجی:
artifactهای خروجی:
- `slack-qa-report.md`
- `slack-qa-summary.json`
- `slack-qa-observed-messages.json` — بدنه‌ها ویرایش می‌شوند مگر اینکه `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` باشد.
- `slack-qa-observed-messages.json` — بدنه‌ها redact می‌شوند مگر اینکه `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` باشد.
### استخر اعتبارنامه Convex
laneهای Telegram، Discord و Slack می‌توانند به‌جای خواندن env vars بالا، اعتبارنامه‌ها را از یک استخر مشترک Convex اجاره کنند. `--credential-source convex` را پاس دهید (یا `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` را تنظیم کنید)؛ QA Lab یک اجاره انحصاری می‌گیرد، در طول اجرا برای آن Heartbeat می‌فرستد، و هنگام خاموش شدن آن را آزاد می‌کند. انواع استخر `"telegram"`، `"discord"` و `"slack"` هستند.
laneهای Telegram، Discord، و Slack می‌توانند به‌جای خواندن env varهای بالا، اعتبارنامه‌ها را از یک استخر مشترک Convex اجاره کنند. `--credential-source convex` را پاس دهید (یا `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` را تنظیم کنید)؛ QA Lab یک lease انحصاری دریافت می‌کند، در طول اجرا برای آن heartbeat می‌فرستد، و هنگام shutdown آن را آزاد می‌کند. انواع استخر `"telegram"`، `"discord"`، و `"slack"` هستند.
شکل payloadهایی که broker در `admin/add` اعتبارسنجی می‌کند:
شکل payloadهایی که broker روی `admin/add` اعتبارسنجی می‌کند:
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` باید یک رشته chat-id عددی باشد.
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` باید یک string عددی chat-id باشد.
- Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`.
env vars عملیاتی و قرارداد endpoint مربوط به broker در [آزمایش → اعتبارنامه‌های مشترک Telegram از طریق Convex](/fa/help/testing#shared-telegram-credentials-via-convex-v1) قرار دارند (نام بخش به پیش از پشتیبانی Discord برمی‌گردد؛ معناشناسی broker برای هر دو نوع یکسان است).
env varهای عملیاتی و قرارداد endpoint مربوط به broker در Convex در [Testing → اعتبارنامه‌های مشترک Telegram از طریق Convex](/fa/help/testing#shared-telegram-credentials-via-convex-v1) قرار دارند (نام بخش پیش از پشتیبانی Discord انتخاب شده است؛ معناشناسی broker برای هر دو نوع یکسان است).
## seedهای پشتیبانی‌شده توسط مخزن
## seedهای مبتنی بر repo
دارایی‌های seed در `qa/` قرار دارند:
assetهای seed در `qa/` قرار دارند:
- `qa/scenarios/index.md`
- `qa/scenarios/<theme>/*.md`
این‌ها عمدا در git هستند تا طرح QA هم برای انسان‌ها و هم برای
این‌ها عمدا در git هستند تا برنامه QA هم برای انسان‌ها و هم برای
agent قابل مشاهده باشد.
`qa-lab` باید یک اجراکننده markdown عمومی باقی بماند. هر فایل markdown سناریو
منبع حقیقت برای یک اجرای آزمایش است و باید موارد زیر را تعریف کند:
`qa-lab` باید یک runner عمومی markdown باقی بماند. هر فایل markdown سناریو
source of truth برای یک اجرای test است و باید موارد زیر را تعریف کند:
- فراداده سناریو
- فراداده اختیاری category، capability، lane و risk
- ارجاع‌های مستندات و کد
- الزامات اختیاری Plugin
- metadata سناریو
- metadata اختیاری category، capability، lane، و risk
- refهای docs و code
- نیازمندی‌های اختیاری Plugin
- patch اختیاری پیکربندی Gateway
- `qa-flow` اجرایی
- `qa-flow` قابل اجرا
سطح runtime قابل استفاده مجددی که پشتوانه `qa-flow` است مجاز است عمومی
و cross-cutting باقی بماند. برای مثال، سناریوهای markdown می‌توانند helperهای سمت transport
را با helperهای سمت مرورگر ترکیب کنند که Control UI توکار را از طریق seam
`browser.request` مربوط به Gateway هدایت می‌کنند، بدون اینکه runner مورد خاص اضافه شود.
سطح runtime قابل استفاده مجدد که پشتوانه `qa-flow` است اجازه دارد عمومی
و cross-cutting باقی بماند. برای مثال، سناریوهای markdown می‌توانند helperهای سمت transport را
با helperهای سمت browser ترکیب کنند که Control UI جاسازی‌شده را از طریق
درز `browser.request` در Gateway پیش می‌برند، بدون اینکه runner ویژه اضافه شود.
فایل‌های سناریو باید بر اساس قابلیت محصول گروه‌بندی شوند، نه پوشه
درخت منبع. هنگام جابه‌جایی فایل‌ها، شناسه‌های سناریو را پایدار نگه دارید؛ برای traceability پیاده‌سازی از `docsRefs` و `codeRefs`
استفاده کنید.
فایل‌های سناریو باید بر اساس قابلیت محصول گروه‌بندی شوند، نه بر اساس پوشه
source tree. وقتی فایل‌ها جابه‌جا می‌شوند، IDهای سناریو را پایدار نگه دارید؛ از `docsRefs` و `codeRefs`
برای traceability پیاده‌سازی استفاده کنید.
فهرست baseline باید به‌اندازه‌ای گسترده بماند که موارد زیر را پوشش دهد:
فهرست baseline باید به‌اندازه کافی گسترده بماند تا موارد زیر را پوشش دهد:
- چت DM و کانال
- chat در DM و کانال
- رفتار thread
- چرخه عمر action پیام
- callbackهای cron
- recall حافظه
- تغییر مدل
- handoff زیرagent
- خواندن مخزن و خواندن مستندات
- یک وظیفه کوچک build مانند Lobster Invaders
- تغییر model
- تحویل به subagent
- خواندن repo و خواندن docs
- یک task کوچک build مانند Lobster Invaders
## laneهای mock ارائه‌دهنده
## laneهای mock provider
`qa suite` دو lane mock ارائه‌دهنده محلی دارد:
`qa suite` دو lane محلی mock provider دارد:
- `mock-openai` همان mock سناریوآگاه OpenClaw است. این lane به‌عنوان lane mock قطعی پیش‌فرض برای QA پشتیبانی‌شده توسط مخزن و parity gateها باقی می‌ماند.
- `aimock` یک سرور ارائه‌دهنده پشتیبانی‌شده با AIMock را برای پوشش آزمایشی protocol، fixture، record/replay و chaos شروع می‌کند. این مورد افزایشی است و جایگزین dispatcher سناریوی `mock-openai` نمی‌شود.
- `mock-openai` mock سناریوآگاه OpenClaw است. این lane همچنان lane پیش‌فرض
mock قطعی برای QA مبتنی بر repo و parity gateها باقی می‌ماند.
- `aimock` یک server provider مبتنی بر AIMock را برای پوشش آزمایشی protocol،
fixture، record/replay، و chaos شروع می‌کند. این مورد افزایشی است و
dispatcher سناریوی `mock-openai` را جایگزین نمی‌کند.
پیاده‌سازی lane ارائه‌دهنده زیر `extensions/qa-lab/src/providers/` قرار دارد.
هر ارائه‌دهنده مالک پیش‌فرض‌های خود، راه‌اندازی سرور محلی، پیکربندی مدل Gateway،
نیازهای staging مربوط به auth-profile، و پرچم‌های قابلیت live/mock است. کد suite و
Gateway مشترک باید به‌جای branch زدن بر اساس نام‌های ارائه‌دهنده، از طریق registry ارائه‌دهنده route شود.
پیاده‌سازی provider-lane زیر `extensions/qa-lab/src/providers/` قرار دارد.
هر provider مالک پیش‌فرض‌ها، startup server محلی، پیکربندی model در Gateway،
نیازهای staging مربوط به auth-profile، و پرچم‌های capability زنده/mock خودش است. کد suite و
Gateway مشترک باید به‌جای branching بر اساس نام providerها، از registry provider عبور کند.
## adapterهای transport
`qa-lab` مالک یک seam عمومی transport برای سناریوهای QA در markdown است. `qa-channel` نخستین adapter روی این seam است، اما هدف طراحی گسترده‌تر است: کانال‌های واقعی یا مصنوعی آینده باید به‌جای افزودن یک QA runner مخصوص transport، به همان suite runner متصل شوند.
`qa-lab` مالک یک درز عمومی transport برای سناریوهای markdown QA است. `qa-channel` اولین adapter روی آن درز است، اما هدف طراحی گسترده‌تر است: کانال‌های واقعی یا synthetic آینده باید به‌جای افزودن runner مخصوص transport برای QA، به همان runner مجموعه وصل شوند.
در سطح معماری، این تقسیم چنین است:
در سطح معماری، تقسیم به این صورت است:
- `qa-lab` مالک اجرای عمومی سناریو، هم‌زمانی worker، نوشتن آرتیفکت، و گزارش‌دهی است.
- adapter transport مالک پیکربندی Gateway، آمادگی، مشاهده ورودی و خروجی، actionهای transport، و وضعیت normalized transport است.
- فایل‌های سناریوی markdown زیر `qa/scenarios/` اجرای آزمایش را تعریف می‌کنند؛ `qa-lab` سطح runtime قابل استفاده مجددی را فراهم می‌کند که آن‌ها را اجرا می‌کند.
- `qa-lab` مالک اجرای عمومی سناریو، هم‌روندی worker، نوشتن artifact، و reporting است.
- adapter transport مالک پیکربندی Gateway، readiness، مشاهده inbound و outbound، actionهای transport، و وضعیت normalized transport است.
- فایل‌های سناریوی markdown زیر `qa/scenarios/` اجرای test را تعریف می‌کنند؛ `qa-lab` سطح runtime قابل استفاده مجدد را فراهم می‌کند که آن‌ها را اجرا می‌کند.
### افزودن یک کانال
### افزودن کانال
افزودن یک کانال به سامانه QA در markdown دقیقا به دو چیز نیاز دارد:
افزودن یک کانال به سیستم QA مبتنی بر markdown دقیقا به دو چیز نیاز دارد:
1. یک adapter transport برای کانال.
2. یک بسته سناریو که قرارداد کانال را تمرین کند.
2. یک بسته سناریو که قرارداد کانال را تمرین دهد.
وقتی میزبان مشترک `qa-lab` می‌تواند مالک flow باشد، root جدیدی برای فرمان QA در سطح بالا اضافه نکنید.
وقتی host مشترک `qa-lab` می‌تواند مالک flow باشد، ریشه فرمان QA سطح‌بالای جدید اضافه نکنید.
`qa-lab` مالک سازوکارهای میزبان مشترک است:
`qa-lab` مکانیک‌های میزبان مشترک را در اختیار دارد:
- root فرمان `openclaw qa`
- راه‌اندازی و teardown مربوط به suite
- هم‌زمانی worker
- نوشتن آرتیفکت
- ریشه فرمان `openclaw qa`
- راه‌اندازی و پاک‌سازی مجموعه
- هم‌روندی worker
- نوشتن artifact
- تولید گزارش
- اجرای سناریو
- aliasهای سازگاری برای سناریوهای قدیمی‌تر `qa-channel`
Pluginهای runner مالک قرارداد transport هستند:
Pluginهای اجراکننده قرارداد انتقال را در اختیار دارند:
- اینکه `openclaw qa <runner>` چگونه زیر root مشترک `qa` mount می‌شود
- اینکه Gateway چگونه برای آن transport پیکربندی می‌شود
- اینکه `openclaw qa <runner>` چگونه زیر ریشه مشترک `qa` mount می‌شود
- اینکه Gateway برای آن انتقال چگونه پیکربندی می‌شود
- اینکه آمادگی چگونه بررسی می‌شود
- اینکه eventهای ورودی چگونه تزریق می‌شوند
- اینکه رویدادهای ورودی چگونه تزریق می‌شوند
- اینکه پیام‌های خروجی چگونه مشاهده می‌شوند
- اینکه transcriptها و وضعیت normalized transport چگونه در دسترس قرار می‌گیرند
- اینکه actionهای پشتیبانی‌شده با transport چگونه اجرا می‌شوند
- اینکه reset یا cleanup مخصوص transport چگونه مدیریت می‌شود
- اینکه transcriptها و وضعیت نرمال‌سازی‌شده انتقال چگونه عرضه می‌شوند
- اینکه اقدام‌های پشتوانه‌دار با انتقال چگونه اجرا می‌شوند
- اینکه بازنشانی یا پاک‌سازی ویژه انتقال چگونه انجام می‌شود
حداقل سطح پذیرش برای یک کانال جدید:
1. `qa-lab` را مالک ریشهٔ مشترک `qa` نگه دارید.
2. اجراکنندهٔ انتقال را روی seam میزبان مشترک `qa-lab` پیاده‌سازی کنید.
3. سازوکارهای ویژهٔ انتقال را داخل Plugin اجراکننده یا harness کانال نگه دارید.
4. اجراکننده را به‌صورت `openclaw qa <runner>` mount کنید، نه با ثبت یک فرمان ریشهٔ رقیب. Pluginهای اجراکننده باید `qaRunners` را در `openclaw.plugin.json` اعلام کنند و آرایهٔ متناظر `qaRunnerCliRegistrations` را از `runtime-api.ts` export کنند. `runtime-api.ts` را سبک نگه دارید؛ CLI تنبل و اجرای runner باید پشت entrypointهای جداگانه بمانند.
5. سناریوهای markdown را زیر دایرکتوری‌های موضوعی `qa/scenarios/` بنویسید یا تطبیق دهید.
6. برای سناریوهای جدید از helperهای عمومی سناریو استفاده کنید.
1. `qa-lab` را مالک ریشه مشترک `qa` نگه دارید.
2. اجراکننده انتقال را روی seam میزبان مشترک `qa-lab` پیاده‌سازی کنید.
3. مکانیک‌های ویژه انتقال را داخل Plugin اجراکننده یا harness کانال نگه دارید.
4. اجراکننده را به‌صورت `openclaw qa <runner>` mount کنید، نه با ثبت یک فرمان ریشه رقیب. Pluginهای اجراکننده باید `qaRunners` را در `openclaw.plugin.json` اعلام کنند و آرایه مطابق `qaRunnerCliRegistrations` را از `runtime-api.ts` صادر کنند. `runtime-api.ts` را سبک نگه دارید؛ CLI تنبل و اجرای runner باید پشت entrypointهای جداگانه بمانند.
5. سناریوهای Markdown را زیر دایرکتوری‌های موضوعی `qa/scenarios/` بنویسید یا سازگار کنید.
6. برای سناریوهای جدید از helperهای سناریوی عمومی استفاده کنید.
7. aliasهای سازگاری موجود را فعال نگه دارید، مگر اینکه repo در حال انجام یک مهاجرت عمدی باشد.
قاعدهٔ تصمیم‌گیری سخت‌گیرانه است:
قاعده تصمیم‌گیری سخت‌گیرانه است:
- اگر رفتار را می‌توان یک‌بار در `qa-lab` بیان کرد، آن را در `qa-lab` قرار دهید.
- اگر رفتار به انتقال یک کانال وابسته است، آن را در همان Plugin اجراکننده یا harness Plugin نگه دارید.
- اگر یک سناریو به قابلیت جدیدی نیاز دارد که بیش از یک کانال می‌تواند از آن استفاده کند، به‌جای شاخهٔ ویژهٔ کانال در `suite.ts` یک helper عمومی اضافه کنید.
- اگر یک رفتار فقط برای یک انتقال معنادار است، سناریو را ویژهٔ همان انتقال نگه دارید و این را در قرارداد سناریو صریح کنید.
- اگر رفتاری را می‌توان یک‌بار در `qa-lab` بیان کرد، آن را در `qa-lab` قرار دهید.
- اگر رفتاری به انتقال یک کانال وابسته است، آن را در همان Plugin اجراکننده یا harness Plugin نگه دارید.
- اگر سناریویی به قابلیت جدیدی نیاز دارد که بیش از یک کانال می‌تواند از آن استفاده کند، به‌جای شاخه ویژه کانال در `suite.ts` یک helper عمومی اضافه کنید.
- اگر رفتاری فقط برای یک انتقال معنی‌دار است، سناریو را ویژه همان انتقال نگه دارید و این را در قرارداد سناریو صریح کنید.
### نام‌های helper سناریو
helperهای عمومی ترجیحی برای سناریوهای جدید:
helperهای عمومی پیشنهادی برای سناریوهای جدید:
- `waitForTransportReady`
- `waitForChannelReady`
@ -442,21 +460,21 @@ helperهای عمومی ترجیحی برای سناریوهای جدید:
- `formatTransportTranscript`
- `resetTransport`
aliasهای سازگاری برای سناریوهای موجود همچنان در دسترس هستند — `waitForQaChannelReady`، `waitForOutboundMessage`، `waitForNoOutbound`، `formatConversationTranscript`، `resetBus` — اما نوشتن سناریوهای جدید باید از نام‌های عمومی استفاده کند. این aliasها برای جلوگیری از یک مهاجرت flag-day وجود دارند، نه به‌عنوان مدل آینده.
aliasهای سازگاری برای سناریوهای موجود همچنان در دسترس‌اند — `waitForQaChannelReady`، `waitForOutboundMessage`، `waitForNoOutbound`، `formatConversationTranscript`، `resetBus` — اما نگارش سناریوهای جدید باید از نام‌های عمومی استفاده کند. این aliasها برای جلوگیری از یک مهاجرت یک‌باره وجود دارند، نه به‌عنوان الگوی آینده.
## گزارش‌دهی
`qa-lab` یک گزارش پروتکل Markdown را از timeline مشاهده‌شدهٔ bus export می‌کند.
گزارش باید به این موارد پاسخ دهد:
`qa-lab` یک گزارش پروتکل Markdown را از timeline مشاهده‌شده bus صادر می‌کند.
گزارش باید پاسخ دهد:
- چه چیزهایی کار کرد
- چه چیزهایی شکست خورد
- چه چیزهایی همچنان مسدود ماند
- چه سناریوهای پیگیری‌ای ارزش اضافه شدن دارند
- چه چیزی کار کرد
- چه چیزی شکست خورد
- چه چیزی مسدود ماند
- چه سناریوهای پیگیری ارزش اضافه‌شدن دارند
برای فهرست سناریوهای موجود — که هنگام برآورد کارهای پیگیری یا سیم‌کشی یک انتقال جدید مفید است — `pnpm openclaw qa coverage` را اجرا کنید (برای خروجی قابل‌خواندن توسط ماشین، `--json` را اضافه کنید).
برای inventory سناریوهای موجود — که هنگام اندازه‌گیری کار پیگیری یا وصل‌کردن یک انتقال جدید مفید است — `pnpm openclaw qa coverage` را اجرا کنید (`--json` را برای خروجی قابل‌خواندن برای ماشین اضافه کنید).
برای بررسی‌های شخصیت و سبک، همان سناریو را روی چندین ref مدل زنده اجرا کنید
برای بررسی‌های کاراکتر و سبک، همان سناریو را روی چندین ref مدل زنده اجرا کنید
و یک گزارش Markdown داوری‌شده بنویسید:
```bash
@ -476,41 +494,42 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
این فرمان processهای فرزند Gateway محلی QA را اجرا می‌کند، نه Docker. سناریوهای ارزیابی شخصیت
باید persona را از طریق `SOUL.md` تنظیم کنند، سپس turnهای معمول کاربر
مانند chat، کمک workspace، و taskهای کوچک فایل را اجرا کنند. به مدل کاندیدا نباید
گفته شود که در حال ارزیابی شدن است. این فرمان هر transcript کامل را حفظ می‌کند،
آمار پایهٔ اجرا را ثبت می‌کند، سپس از مدل‌های داور در حالت fast با reasoning
`xhigh` در جاهایی که پشتیبانی می‌شود می‌خواهد اجراها را بر اساس طبیعی بودن، vibe، و طنز رتبه‌بندی کنند.
هنگام مقایسهٔ providerها از `--blind-judge-models` استفاده کنید: prompt داور همچنان
هر transcript و وضعیت اجرا را دریافت می‌کند، اما refهای کاندیدا با labelهای خنثی
مانند `candidate-01` جایگزین می‌شوند؛ گزارش پس از parsing رتبه‌بندی‌ها را دوباره به refهای واقعی map می‌کند.
اجراهای کاندیدا به‌طور پیش‌فرض از thinking سطح `high` استفاده می‌کنند، با `medium` برای GPT-5.5 و `xhigh`
برای refهای قدیمی‌تر ارزیابی OpenAI که از آن پشتیبانی می‌کنند. یک کاندیدای مشخص را به‌صورت inline با
این فرمان فرایندهای فرزند Gateway محلی QA را اجرا می‌کند، نه Docker. سناریوهای ارزیابی کاراکتر
باید persona را از طریق `SOUL.md` تنظیم کنند، سپس نوبت‌های عادی کاربر
مانند chat، کمک workspace و کارهای کوچک فایل را اجرا کنند. به مدل candidate نباید
گفته شود که در حال ارزیابی است. این فرمان هر transcript کامل را حفظ می‌کند،
آمار پایه اجرا را ثبت می‌کند، سپس از مدل‌های judge در حالت سریع با
استدلال `xhigh` در جاهایی که پشتیبانی می‌شود می‌خواهد اجراها را بر اساس طبیعی‌بودن، حس‌وحال و شوخ‌طبعی رتبه‌بندی کنند.
هنگام مقایسه providerها از `--blind-judge-models` استفاده کنید: prompt داور همچنان
هر transcript و وضعیت اجرا را دریافت می‌کند، اما refهای candidate با
برچسب‌های خنثی مانند `candidate-01` جایگزین می‌شوند؛ گزارش پس از
parsing رتبه‌بندی‌ها را دوباره به refهای واقعی نگاشت می‌کند.
اجراهای candidate به‌صورت پیش‌فرض از thinking برابر `high` استفاده می‌کنند، با `medium` برای GPT-5.5 و `xhigh`
برای refهای ارزیابی قدیمی‌تر OpenAI که از آن پشتیبانی می‌کنند. یک candidate مشخص را به‌صورت inline با
`--model provider/model,thinking=<level>` override کنید. `--thinking <level>` همچنان یک
fallback سراسری تنظیم می‌کند، و فرم قدیمی‌تر `--model-thinking <provider/model=level>` برای
سازگاری حفظ شده است.
refهای کاندیدای OpenAI به‌طور پیش‌فرض در حالت fast هستند تا در جاهایی که
provider پشتیبانی می‌کند از پردازش اولویت‌دار استفاده شود. وقتی یک
کاندیدا یا داور منفرد به override نیاز دارد، `,fast`، `,no-fast`، یا `,fast=false` را inline اضافه کنید. فقط زمانی `--fast` را pass کنید که می‌خواهید
حالت fast را برای همهٔ مدل‌های کاندیدا force کنید. مدت‌زمان کاندیدا و داور
برای تحلیل benchmark در گزارش ثبت می‌شود، اما promptهای داور صراحتا می‌گویند
که بر اساس سرعت رتبه‌بندی نکنند.
اجراهای مدل کاندیدا و داور هر دو به‌طور پیش‌فرض concurrency 16 دارند. وقتی محدودیت‌های
provider یا فشار Gateway محلی یک اجرا را بیش از حد noisy می‌کند، `--concurrency`
یا `--judge-concurrency` را کاهش دهید.
وقتی هیچ `--model` کاندیدایی pass نشود، character eval به‌طور پیش‌فرض از
سازگاری نگه داشته شده است.
refهای candidate مربوط به OpenAI به‌صورت پیش‌فرض در حالت fast هستند تا در جاهایی که
provider پشتیبانی می‌کند از پردازش priority استفاده شود. وقتی یک
candidate یا judge تکی به override نیاز دارد، `,fast`، `,no-fast` یا `,fast=false` را inline اضافه کنید. فقط وقتی `--fast` را پاس بدهید که می‌خواهید
حالت fast را برای همه مدل‌های candidate اجباری کنید. مدت‌زمان‌های candidate و judge
برای تحلیل benchmark در گزارش ثبت می‌شوند، اما promptهای judge صراحتا می‌گویند
بر اساس سرعت رتبه‌بندی نکنند.
اجرای مدل‌های candidate و judge هر دو به‌صورت پیش‌فرض هم‌روندی 16 دارند. وقتی
محدودیت‌های provider یا فشار Gateway محلی باعث می‌شود یک اجرا بیش از حد noisy شود،
`--concurrency` یا `--judge-concurrency` را کاهش دهید.
وقتی هیچ candidateای با `--model` پاس داده نشود، character eval به‌صورت پیش‌فرض از
`openai/gpt-5.5`، `openai/gpt-5.2`، `openai/gpt-5`، `anthropic/claude-opus-4-6`،
`anthropic/claude-sonnet-4-6`، `zai/glm-5.1`،
`moonshot/kimi-k2.5`، و
`google/gemini-3.1-pro-preview` استفاده می‌کند.
وقتی هیچ `--judge-model`ی pass نشود، داورها به‌طور پیش‌فرض
وقتی هیچ `--judge-model` پاس داده نشود، داورها به‌صورت پیش‌فرض
`openai/gpt-5.5,thinking=xhigh,fast` و
`anthropic/claude-opus-4-6,thinking=high` هستند.
## مستندات مرتبط
- [Matrix QA](/fa/concepts/qa-matrix)
- [QA ماتریسی](/fa/concepts/qa-matrix)
- [کانال QA](/fa/channels/qa-channel)
- [آزمایش](/fa/help/testing)
- [داشبورد](/fa/web/dashboard)

219
docs/fa/concepts/streaming.md
View File

@ -1,29 +1,29 @@
---
read_when:
- توضیح نحوهٔ کار جریان‌سازی یا قطعه‌بندی در کانال‌ها
- تغییر رفتار جریان‌دهی بلوک یا تکه‌بندی کانال
- توضیح نحوهٔ کار پخش جریانی یا قطعه‌بندی در کانال‌ها
- تغییر رفتار پخش جریانی بلوک یا قطعه‌بندی کانال
- اشکال‌زدایی پاسخ‌های بلوکی تکراری/زودهنگام یا پخش جریانی پیش‌نمایش کانال
summary: رفتار پخش جریانی + قطعه‌بندی (پاسخ‌های بلوکی، پخش جریانی پیش‌نمایش کانال، نگاشت حالت)
title: جریان‌سازی و قطعه‌بندی
title: جریان‌دهی و قطعه‌بندی
x-i18n:
generated_at: "2026-05-03T21:32:06Z"
generated_at: "2026-05-04T07:05:50Z"
model: gpt-5.5
provider: openai
source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50
source_hash: ff7b6cd8127255352fe16fb746469e9828e7d5aea183d3799ab10cc768515bd1
source_path: concepts/streaming.md
workflow: 16
---
OpenClaw دو لایهٔ streaming جداگانه دارد:
OpenClaw دو لایه جریان‌دهی جداگانه دارد:
- **streaming بلوکی (کانال‌ها):** هنگام نوشتن دستیار، **بلوک‌های** کامل‌شده را منتشر می‌کند. این‌ها پیام‌های معمولی کانال هستند (نه token delta).
- **streaming پیش‌نمایش (Telegram/Discord/Slack):** هنگام تولید، یک **پیام پیش‌نمایش** موقت را به‌روزرسانی می‌کند.
- **جریان‌دهی بلوکی (کانال‌ها):** هنگام نوشتن دستیار، **بلوک‌های** کامل‌شده را منتشر می‌کند. این‌ها پیام‌های عادی کانال هستند (نه دلتاهای توکن).
- **جریان‌دهی پیش‌نمایش (Telegram/Discord/Slack):** هنگام تولید، یک **پیام پیش‌نمایش** موقت را به‌روزرسانی می‌کند.
امروز **streaming واقعی از نوع token-delta** برای پیام‌های کانال وجود ندارد. streaming پیش‌نمایش مبتنی بر پیام است (ارسال + ویرایش‌ها/افزودن‌ها).
امروز **جریان‌دهی واقعی دلتا-توکن** به پیام‌های کانال وجود ندارد. جریان‌دهی پیش‌نمایش مبتنی بر پیام است (ارسال + ویرایش/افزودن).
## streaming بلوکی (پیام‌های کانال)
## جریان‌دهی بلوکی (پیام‌های کانال)
streaming بلوکی خروجی دستیار را وقتی در دسترس می‌شود، در قطعه‌های درشت ارسال می‌کند.
جریان‌دهی بلوکی خروجی دستیار را به‌صورت قطعه‌های درشت، هم‌زمان با آماده‌شدن، ارسال می‌کند.
```
Model output
@ -37,180 +37,180 @@ Model output
راهنما:
- `text_delta/events`: رویدادهای جریان مدل (ممکن است برای مدل‌های غیرstreaming پراکنده باشند).
- `text_delta/events`: رویدادهای جریان مدل (ممکن است برای مدل‌های غیرجریانی پراکنده باشد).
- `chunker`: `EmbeddedBlockChunker` که کران‌های کمینه/بیشینه + ترجیح شکست را اعمال می‌کند.
- `channel send`: پیام‌های خروجی واقعی (پاسخ‌های بلوکی).
**کنترل‌ها:**
- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (پیش‌فرض خاموش).
- بازنویسی‌های کانال: `*.blockStreaming` (و گونه‌های هر حساب) برای اجبار `"on"`/`"off"` برای هر کانال.
- بازنویسی‌های کانال: `*.blockStreaming` (و گونه‌های هر حساب) برای اجبار `"on"`/`"off"` در هر کانال.
- `agents.defaults.blockStreamingBreak`: `"text_end"` یا `"message_end"`.
- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (ادغام بلوک‌های streaming پیش از ارسال).
- سقف سخت کانال: `*.textChunkLimit` (برای نمونه، `channels.whatsapp.textChunkLimit`).
- حالت قطعه‌بندی کانال: `*.chunkMode` (`length` پیش‌فرض است، `newline` پیش از قطعه‌بندی بر اساس طول، روی خط‌های خالی (مرزهای پاراگراف) تقسیم می‌کند).
- سقف نرم Discord: `channels.discord.maxLinesPerMessage` (پیش‌فرض 17) پاسخ‌های بلند را تقسیم می‌کند تا از بریده‌شدن رابط کاربری جلوگیری شود.
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (ادغام بلوک‌های جریانی پیش از ارسال).
- سقف سخت کانال: `*.textChunkLimit` (مثلاً `channels.whatsapp.textChunkLimit`).
- حالت قطعه‌بندی کانال: `*.chunkMode` (`length` پیش‌فرض است، `newline` پیش از قطعه‌بندی بر اساس طول، روی خطوط خالی (مرزهای پاراگراف) تقسیم می‌کند).
- سقف نرم Discord: `channels.discord.maxLinesPerMessage` (پیش‌فرض 17) پاسخ‌های بلند را تقسیم می‌کند تا از بریده‌شدن UI جلوگیری شود.
**معنای مرزها:**
- `text_end`: به محض اینکه قطعه‌ساز بلوک منتشر کند، بلوک‌ها را streaming کن؛ در هر `text_end` تخلیه کن.
- `message_end`: تا پایان پیام دستیار صبر کن، سپس خروجی بافرشده را تخلیه کن.
- `text_end`: به‌محض انتشار از سوی chunker، بلوک‌ها را جریان می‌دهد؛ در هر `text_end` تخلیه می‌کند.
- `message_end`: تا پایان پیام دستیار صبر می‌کند، سپس خروجی بافرشده را تخلیه می‌کند.
اگر متن بافرشده از `maxChars` بیشتر شود، `message_end` همچنان از قطعه‌ساز استفاده می‌کند، بنابراین می‌تواند در پایان چند قطعه منتشر کند.
`message_end` همچنان اگر متن بافرشده از `maxChars` فراتر برود از chunker استفاده می‌کند، بنابراین می‌تواند در پایان چند قطعه منتشر کند.
### تحویل رسانه با streaming بلوکی
### تحویل رسانه با جریان‌دهی بلوکی
دستورهای `MEDIA:` فرادادهٔ معمول تحویل هستند. وقتی streaming بلوکی یک
بلوک رسانه را زود ارسال کند، OpenClaw آن تحویل را برای آن نوبت به خاطر می‌سپارد. اگر payload نهایی
دستیار همان URL رسانه را تکرار کند، تحویل نهایی به‌جای ارسال دوبارهٔ پیوست،
رسانهٔ تکراری را حذف می‌کند.
دستورهای `MEDIA:` فراداده تحویل عادی هستند. وقتی جریان‌دهی بلوکی یک
بلوک رسانه را زود ارسال می‌کند، OpenClaw آن تحویل را برای آن نوبت به خاطر می‌سپارد. اگر محتوای نهایی
دستیار همان URL رسانه را تکرار کند، تحویل نهایی به‌جای ارسال دوباره پیوست،
رسانه تکراری را حذف می‌کند.
payloadهای نهایی کاملاً تکراری سرکوب می‌شوند. اگر payload نهایی
متن متمایزی پیرامون رسانه‌ای اضافه کند که قبلاً streaming شده است، OpenClaw همچنان
متن جدید را می‌فرستد و رسانه را تک‌تحویلی نگه می‌دارد. این کار از یادداشت‌های صوتی
یا فایل‌های تکراری در کانال‌هایی مثل Telegram جلوگیری می‌کند، وقتی یک عامل هنگام
streaming مقدار `MEDIA:` منتشر می‌کند و provider نیز آن را در پاسخ کامل‌شده وارد می‌کند.
محتواهای نهایی کاملاً تکراری سرکوب می‌شوند. اگر محتوای نهایی متن
متمایزی پیرامون رسانه‌ای که قبلاً جریان داده شده اضافه کند، OpenClaw همچنان
متن جدید را می‌فرستد و رسانه را تک‌تحویلی نگه می‌دارد. این کار از تکرار یادداشت‌های صوتی
یا فایل‌ها در کانال‌هایی مثل Telegram جلوگیری می‌کند، زمانی که یک عامل هنگام
جریان‌دهی `MEDIA:` منتشر می‌کند و ارائه‌دهنده نیز آن را در پاسخ کامل‌شده می‌آورد.
## الگوریتم قطعه‌بندی (کران‌های کم/زیاد)
## الگوریتم قطعه‌بندی (کران‌های پایین/بالا)
قطعه‌بندی بلوک توسط `EmbeddedBlockChunker` پیاده‌سازی شده است:
قطعه‌بندی بلوکی توسط `EmbeddedBlockChunker` پیاده‌سازی شده است:
- **کران کم:** تا زمانی که بافر >= `minChars` نشده است منتشر نکن (مگر اینکه اجباری باشد).
- **کران زیاد:** تقسیم‌ها را پیش از `maxChars` ترجیح بده؛ اگر اجباری شد، در `maxChars` تقسیم کن.
- **کران پایین:** تا زمانی که بافر >= `minChars` نباشد منتشر نکن (مگر با اجبار).
- **کران بالا:** تقسیم پیش از `maxChars` ترجیح داده می‌شود؛ اگر اجباری باشد، در `maxChars` تقسیم کن.
- **ترجیح شکست:** `paragraph` → `newline` → `sentence` → `whitespace` → شکست سخت.
- **حصارهای کد:** هرگز داخل حصارها تقسیم نکن؛ وقتی در `maxChars` اجباراً تقسیم می‌شود، حصار را ببند + دوباره باز کن تا Markdown معتبر بماند.
- **حصارهای کد:** هرگز داخل حصارها تقسیم نکن؛ هنگام اجبار در `maxChars`، حصار را ببند + دوباره باز کن تا Markdown معتبر بماند.
`maxChars` به `textChunkLimit` کانال محدود می‌شود، بنابراین نمی‌توانید از سقف‌های هر کانال فراتر بروید.
## هم‌جوشی (ادغام بلوک‌های streaming)
## هم‌جوشی (ادغام بلوک‌های جریانی)
وقتی streaming بلوکی فعال باشد، OpenClaw می‌تواند **قطعه‌های بلوکی متوالی را**
پیش از ارسال ادغام کند. این کار «هرزپیام تک‌خطی» را کم می‌کند و همچنان
خروجی تدریجی ارائه می‌دهد.
وقتی جریان‌دهی بلوکی فعال است، OpenClaw می‌تواند **قطعه‌های بلوکی پیاپی را**
پیش از ارسال به بیرون **ادغام کند**. این کار «هرزپیام تک‌خطی» را کاهش می‌دهد و همچنان
خروجی تدریجی ارائه می‌کند.
- هم‌جوشی پیش از تخلیه منتظر **فاصله‌های بیکاری** (`idleMs`) می‌ماند.
- هم‌جوشی پیش از تخلیه، منتظر **وقفه‌های بی‌کار** (`idleMs`) می‌ماند.
- بافرها با `maxChars` محدود می‌شوند و اگر از آن فراتر بروند تخلیه خواهند شد.
- `minChars` جلوی ارسال پاره‌های خیلی کوچک را می‌گیرد تا متن کافی جمع شود
(تخلیهٔ نهایی همیشه متن باقی‌مانده را می‌فرستد).
- چسباننده از `blockStreamingChunk.breakPreference` مشتق می‌شود
- `minChars` از ارسال قطعه‌های بسیار کوچک جلوگیری می‌کند تا متن کافی جمع شود
(تخلیه نهایی همیشه متن باقی‌مانده را می‌فرستد).
- اتصال‌دهنده از `blockStreamingChunk.breakPreference` مشتق می‌شود
(`paragraph` → `\n\n`، `newline` → `\n`، `sentence` → فاصله).
- بازنویسی‌های کانال از طریق `*.blockStreamingCoalesce` در دسترس هستند (شامل پیکربندی‌های هر حساب).
- مقدار پیش‌فرض `minChars` برای هم‌جوشی، مگر اینکه بازنویسی شود، برای Signal/Slack/Discord به 1500 افزایش داده می‌شود.
- مقدار پیش‌فرض هم‌جوشی `minChars` برای Signal/Slack/Discord به 1500 افزایش داده می‌شود، مگر اینکه بازنویسی شده باشد.
## آهنگ انسانی بین بلوک‌ها
## مکث انسانی‌مانند بین بلوک‌ها
وقتی streaming بلوکی فعال باشد، می‌توانید بین
وقتی جریان‌دهی بلوکی فعال است، می‌توانید بین
پاسخ‌های بلوکی (پس از بلوک اول) یک **مکث تصادفی‌شده** اضافه کنید. این باعث می‌شود پاسخ‌های چندحبابی
طبیعی‌تر به نظر برسند.
- پیکربندی: `agents.defaults.humanDelay` (برای هر عامل از طریق `agents.list[].humanDelay` بازنویسی کنید).
- پیکربندی: `agents.defaults.humanDelay` (بازنویسی برای هر عامل از طریق `agents.list[].humanDelay`).
- حالت‌ها: `off` (پیش‌فرض)، `natural` (800–2500ms)، `custom` (`minMs`/`maxMs`).
- فقط روی **پاسخ‌های بلوکی** اعمال می‌شود، نه پاسخ‌های نهایی یا خلاصه‌های ابزار.
## «قطعه‌ها را streaming کن یا همه‌چیز را»
## «جریان‌دهی قطعه‌ها یا همه‌چیز»
این به موارد زیر نگاشت می‌شود:
- **قطعه‌ها را streaming کن:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (هم‌زمان با تولید منتشر کن). کانال‌های غیرTelegram همچنین به `*.blockStreaming: true` نیاز دارند.
- **همه‌چیز را در پایان streaming کن:** `blockStreamingBreak: "message_end"` (یک‌بار تخلیه کن، اگر خیلی طولانی باشد احتمالاً چند قطعه).
- **بدون streaming بلوکی:** `blockStreamingDefault: "off"` (فقط پاسخ نهایی).
- **جریان‌دهی قطعه‌ها:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (هم‌زمان با پیشرفت منتشر کن). کانال‌های غیر Telegram همچنین به `*.blockStreaming: true` نیاز دارند.
- **جریان‌دهی همه‌چیز در پایان:** `blockStreamingBreak: "message_end"` (یک‌بار تخلیه، در صورت بسیار طولانی بودن شاید چند قطعه).
- **بدون جریان‌دهی بلوکی:** `blockStreamingDefault: "off"` (فقط پاسخ نهایی).
**نکتهٔ کانال:** streaming بلوکی **خاموش است مگر اینکه**
`*.blockStreaming` صراحتاً روی `true` تنظیم شده باشد. کانال‌ها می‌توانند بدون پاسخ‌های بلوکی،
یک پیش‌نمایش زنده را streaming کنند (`channels.<channel>.streaming`).
**نکته کانال:** جریان‌دهی بلوکی **خاموش است مگر اینکه**
`*.blockStreaming` صریحاً روی `true` تنظیم شود. کانال‌ها می‌توانند بدون پاسخ‌های بلوکی،
یک پیش‌نمایش زنده (`channels.<channel>.streaming`) را جریان دهند.
یادآوری محل پیکربندی: پیش‌فرض‌های `blockStreaming*` زیر
`agents.defaults` قرار دارند، نه پیکربندی ریشه.
## حالت‌های streaming پیش‌نمایش
## حالت‌های جریان‌دهی پیش‌نمایش
کلید معیار: `channels.<channel>.streaming`
کلید canonical: `channels.<channel>.streaming`
حالت‌ها:
- `off`: streaming پیش‌نمایش را غیرفعال می‌کند.
- `partial`: یک پیش‌نمایش واحد که با تازه‌ترین متن جایگزین می‌شود.
- `off`: جریان‌دهی پیش‌نمایش را غیرفعال می‌کند.
- `partial`: یک پیش‌نمایش که با آخرین متن جایگزین می‌شود.
- `block`: پیش‌نمایش در گام‌های قطعه‌بندی‌شده/افزوده‌شده به‌روزرسانی می‌شود.
- `progress`: پیش‌نمایش پیشرفت/وضعیت هنگام تولید، پاسخ نهایی در پایان.
`streaming.mode: "block"` یک حالت streaming پیش‌نمایش برای کانال‌های قابل‌ویرایش
مانند Discord و Telegram است. این حالت تحویل بلوکی کانال را در آنجا فعال نمی‌کند.
وقتی پاسخ‌های بلوکی معمولی می‌خواهید، از `streaming.block.enabled` یا کلید قدیمی کانال `blockStreaming` استفاده کنید. Microsoft Teams استثناست: این کانال
انتقال بلوکی پیش‌نویس-پیش‌نمایش ندارد، بنابراین `streaming.mode: "block"` به‌جای
streaming جزئی/پیشرفت بومی، به تحویل بلوکی Teams نگاشت می‌شود.
`streaming.mode: "block"` یک حالت جریان‌دهی پیش‌نمایش برای کانال‌های قابل ویرایش
مانند Discord و Telegram است. این کار تحویل بلوکی کانال را در آنجا فعال نمی‌کند.
وقتی پاسخ‌های بلوکی عادی می‌خواهید، از `streaming.block.enabled` یا کلید قدیمی کانال `blockStreaming` استفاده کنید.
Microsoft Teams استثناست: انتقال بلوکی پیش‌نمایش پیش‌نویس ندارد، بنابراین `streaming.mode: "block"` به‌جای
جریان‌دهی جزئی/پیشرفت بومی، به تحویل بلوکی Teams نگاشت می‌شود.
### نگاشت کانال
| کانال | `off` | `partial` | `block` | `progress` |
| کانال | `off` | `partial` | `block` | `progress` |
| ---------- | ----- | --------- | ------- | ----------------------- |
| Telegram | ✅ | ✅ | ✅ | پیش‌نویس پیشرفت قابل‌ویرایش |
| Discord | ✅ | ✅ | ✅ | پیش‌نویس پیشرفت قابل‌ویرایش |
| Telegram | ✅ | ✅ | ✅ | پیش‌نویس پیشرفت قابل ویرایش |
| Discord | ✅ | ✅ | ✅ | پیش‌نویس پیشرفت قابل ویرایش |
| Slack | ✅ | ✅ | ✅ | ✅ |
| Mattermost | ✅ | ✅ | ✅ | ✅ |
| MS Teams | ✅ | ✅ | ✅ | جریان پیشرفت بومی |
| MS Teams | ✅ | ✅ | ✅ | جریان پیشرفت بومی |
فقط Slack:
- `channels.slack.streaming.nativeTransport` فراخوانی‌های API streaming بومی Slack را وقتی `channels.slack.streaming.mode="partial"` باشد روشن/خاموش می‌کند (پیش‌فرض: `true`).
- streaming بومی Slack و وضعیت رشتهٔ دستیار Slack به یک هدف رشتهٔ پاسخ نیاز دارند. پیام‌های مستقیم سطح‌بالا آن پیش‌نمایش به سبک رشته را نشان نمی‌دهند، اما همچنان می‌توانند از پست‌های پیش‌نمایش پیش‌نویس Slack و ویرایش‌ها استفاده کنند.
- `channels.slack.streaming.nativeTransport` فراخوانی‌های API جریان‌دهی بومی Slack را زمانی که `channels.slack.streaming.mode="partial"` باشد تغییر وضعیت می‌دهد (پیش‌فرض: `true`).
- جریان‌دهی بومی Slack و وضعیت رشته دستیار Slack به یک هدف رشته پاسخ نیاز دارند. پیام‌های مستقیم سطح بالا آن پیش‌نمایش سبک‌رشته‌ای را نشان نمی‌دهند، اما همچنان می‌توانند از پست‌ها و ویرایش‌های پیش‌نمایش پیش‌نویس Slack استفاده کنند.
مهاجرت کلید قدیمی:
- Telegram: مقدارهای قدیمی `streamMode` و مقدارهای اسکالر/بولی `streaming` توسط مسیرهای سازگاری doctor/config شناسایی و به `streaming.mode` مهاجرت داده می‌شوند.
- Discord: `streamMode` + مقدار بولی `streaming` به‌صورت خودکار به enum ‏`streaming` مهاجرت می‌کنند.
- Telegram: مقادیر قدیمی `streamMode` و مقادیر عددی/بولی `streaming` توسط مسیرهای سازگاری doctor/config به `streaming.mode` شناسایی و مهاجرت می‌شوند.
- Discord: `streamMode` + مقدار بولی `streaming` به‌صورت خودکار به enum `streaming` مهاجرت می‌کنند.
- Slack: `streamMode` به‌صورت خودکار به `streaming.mode` مهاجرت می‌کند؛ مقدار بولی `streaming` به‌صورت خودکار به `streaming.mode` به‌همراه `streaming.nativeTransport` مهاجرت می‌کند؛ `nativeStreaming` قدیمی به‌صورت خودکار به `streaming.nativeTransport` مهاجرت می‌کند.
### رفتار زمان اجرا
Telegram:
- از `sendMessage` + به‌روزرسانی‌های پیش‌نمایش `editMessageText` در پیام‌های مستقیم و گروه‌ها/موضوع‌ها استفاده می‌کند.
- وقتی یک پیش‌نمایش حدود یک دقیقه قابل‌مشاهده بوده است، به‌جای ویرایش درجا یک پیام نهایی تازه می‌فرستد، سپس پیش‌نمایش را پاک می‌کند تا timestamp در Telegram پایان پاسخ را بازتاب دهد.
- وقتی streaming بلوکی Telegram صراحتاً فعال باشد، streaming پیش‌نمایش رد می‌شود (برای جلوگیری از streaming دوگانه).
- `/reasoning stream` می‌تواند reasoning را در پیش‌نمایش بنویسد.
- از به‌روزرسانی‌های پیش‌نمایش `sendMessage` + `editMessageText` در پیام‌های مستقیم و گروه‌ها/موضوعات استفاده می‌کند.
- وقتی یک پیش‌نمایش حدود یک دقیقه قابل مشاهده بوده باشد، به‌جای ویرایش درجا یک پیام نهایی تازه می‌فرستد، سپس پیش‌نمایش را پاک می‌کند تا مُهر زمانی Telegram تکمیل پاسخ را بازتاب دهد.
- وقتی جریان‌دهی بلوکی Telegram صریحاً فعال باشد، جریان‌دهی پیش‌نمایش نادیده گرفته می‌شود (برای جلوگیری از جریان‌دهی دوگانه).
- `/reasoning stream` می‌تواند استدلال را در یک پیش‌نمایش گذرا بنویسد که پس از تحویل نهایی حذف می‌شود.
Discord:
- از پیام‌های پیش‌نمایش ارسال + ویرایش استفاده می‌کند.
- از ارسال + ویرایش پیام‌های پیش‌نمایش استفاده می‌کند.
- حالت `block` از قطعه‌بندی پیش‌نویس (`draftChunk`) استفاده می‌کند.
- وقتی streaming بلوکی Discord صراحتاً فعال باشد، streaming پیش‌نمایش رد می‌شود.
- payloadهای رسانهٔ نهایی، خطا و پاسخ صریح، پیش‌نمایش‌های معلق را بدون تخلیهٔ پیش‌نویس تازه لغو می‌کنند، سپس از تحویل معمول استفاده می‌کنند.
- وقتی جریان‌دهی بلوکی Discord صریحاً فعال باشد، جریان‌دهی پیش‌نمایش نادیده گرفته می‌شود.
- رسانه نهایی، خطا، و محتواهای پاسخ صریح، پیش‌نمایش‌های معلق را بدون تخلیه پیش‌نویس جدید لغو می‌کنند، سپس از تحویل عادی استفاده می‌کنند.
Slack:
- `partial` در صورت در دسترس بودن می‌تواند از streaming بومی Slack (`chat.startStream`/`append`/`stop`) استفاده کند.
- `partial` در صورت در دسترس بودن می‌تواند از جریان‌دهی بومی Slack (`chat.startStream`/`append`/`stop`) استفاده کند.
- `block` از پیش‌نمایش‌های پیش‌نویس به سبک افزودن استفاده می‌کند.
- `progress` از متن پیش‌نمایش وضعیت و سپس پاسخ نهایی استفاده می‌کند.
- پیام‌های مستقیم سطح‌بالا بدون رشتهٔ پاسخ، به‌جای streaming بومی Slack از پست‌های پیش‌نمایش پیش‌نویس و ویرایش‌ها استفاده می‌کنند.
- streaming پیش‌نمایش بومی و پیش‌نویس، پاسخ‌های بلوکی را برای آن نوبت سرکوب می‌کنند، بنابراین یک پاسخ Slack فقط از یک مسیر تحویل streaming می‌شود.
- payloadهای رسانه/خطای نهایی و نهایی‌های پیشرفت، پیام‌های پیش‌نویس دورریختنی ایجاد نمی‌کنند؛ فقط نهایی‌های متنی/بلوکی که می‌توانند پیش‌نمایش را ویرایش کنند، متن پیش‌نویس معلق را تخلیه می‌کنند.
- پیام‌های مستقیم سطح بالا بدون رشته پاسخ، به‌جای جریان‌دهی بومی Slack، از پست‌ها و ویرایش‌های پیش‌نمایش پیش‌نویس استفاده می‌کنند.
- جریان‌دهی بومی و پیش‌نمایش پیش‌نویس، پاسخ‌های بلوکی را برای آن نوبت سرکوب می‌کنند، بنابراین یک پاسخ Slack فقط از یک مسیر تحویل جریان داده می‌شود.
- محتواهای رسانه/خطای نهایی و نهایی‌های پیشرفت، پیام‌های پیش‌نویس دورریختنی ایجاد نمی‌کنند؛ فقط نهایی‌های متنی/بلوکی که می‌توانند پیش‌نمایش را ویرایش کنند، متن پیش‌نویس معلق را تخلیه می‌کنند.
Mattermost:
- فکر کردن، فعالیت ابزار و متن جزئی پاسخ را در یک پست پیش‌نمایش پیش‌نویس واحد streaming می‌کند که وقتی پاسخ نهایی برای ارسال امن باشد، درجا نهایی می‌شود.
- اگر پست پیش‌نمایش حذف شده باشد یا هنگام نهایی‌سازی به هر دلیل در دسترس نباشد، به ارسال یک پست نهایی تازه برمی‌گردد.
- payloadهای رسانه/خطای نهایی پیش از تحویل معمول، به‌جای تخلیهٔ یک پست پیش‌نمایش موقت، به‌روزرسانی‌های پیش‌نمایش معلق را لغو می‌کنند.
- فکرکردن، فعالیت ابزار، و متن پاسخ جزئی را در یک پست پیش‌نمایش پیش‌نویس واحد جریان می‌دهد که وقتی پاسخ نهایی برای ارسال امن باشد، درجا نهایی می‌شود.
- اگر پست پیش‌نمایش حذف شده باشد یا در زمان نهایی‌سازی در دسترس نباشد، به ارسال یک پست نهایی تازه برمی‌گردد.
- محتواهای رسانه/خطای نهایی، پیش از تحویل عادی، به‌جای تخلیه یک پست پیش‌نمایش موقت، به‌روزرسانی‌های پیش‌نمایش معلق را لغو می‌کنند.
Matrix:
- پیش‌نمایش‌های پیش‌نویس وقتی متن نهایی بتواند رویداد پیش‌نمایش را دوباره استفاده کند، درجا نهایی می‌شوند.
- نهایی‌های فقط‌رسانه، خطا و ناهماهنگی هدف پاسخ، پیش از تحویل معمول، به‌روزرسانی‌های پیش‌نمایش معلق را لغو می‌کنند؛ یک پیش‌نمایش کهنه‌ای که از قبل قابل‌مشاهده است حذف می‌شود.
- پیش‌نمایش‌های پیش‌نویس وقتی متن نهایی بتواند از رویداد پیش‌نمایش دوباره استفاده کند، درجا نهایی می‌شوند.
- نهایی‌های فقط رسانه، خطا، و ناسازگاری هدف پاسخ، پیش از تحویل عادی، به‌روزرسانی‌های پیش‌نمایش معلق را لغو می‌کنند؛ یک پیش‌نمایش کهنه که از قبل قابل مشاهده است حذف‌انتشاری می‌شود.
### به‌روزرسانی‌های پیش‌نمایش پیشرفت ابزار
streaming پیش‌نمایش می‌تواند شامل به‌روزرسانی‌های **پیشرفت ابزار** نیز باشد — خط‌های کوتاه وضعیت مانند «در حال جست‌وجوی وب»، «در حال خواندن فایل» یا «در حال فراخوانی ابزار» — که هنگام اجرای ابزارها و پیش از پاسخ نهایی، در همان پیام پیش‌نمایش ظاهر می‌شوند. این کار نوبت‌های چندمرحله‌ای ابزار را به‌جای سکوت بین نخستین پیش‌نمایش فکر کردن و پاسخ نهایی، از نظر بصری زنده نگه می‌دارد.
جریان‌دهی پیش‌نمایش همچنین می‌تواند شامل به‌روزرسانی‌های **پیشرفت ابزار** باشد - خط‌های وضعیت کوتاه مانند «در حال جست‌وجوی وب»، «در حال خواندن فایل»، یا «در حال فراخوانی ابزار» - که هنگام اجرای ابزارها، پیش از پاسخ نهایی، در همان پیام پیش‌نمایش ظاهر می‌شوند. این کار نوبت‌های چندمرحله‌ای ابزار را به‌جای سکوت بین اولین پیش‌نمایش تفکر و پاسخ نهایی، از نظر بصری زنده نگه می‌دارد.
سطح‌های پشتیبانی‌شده:
سطوح پشتیبانی‌شده:
- **Discord**، **Slack**، **Telegram** و **Matrix** وقتی streaming پیش‌نمایش فعال باشد، به‌طور پیش‌فرض پیشرفت ابزار را در ویرایش پیش‌نمایش زنده streaming می‌کنند. Microsoft Teams در گفت‌وگوهای شخصی از جریان پیشرفت بومی خود استفاده می‌کند.
- Telegram از `v2026.4.22` با به‌روزرسانی‌های پیش‌نمایش پیشرفت ابزار فعال منتشر شده است؛ فعال نگه داشتن آن‌ها همان رفتار منتشرشده را حفظ می‌کند.
- **Discord**، **Slack**، **Telegram**، و **Matrix** به‌طور پیش‌فرض وقتی جریان‌دهی پیش‌نمایش فعال باشد، پیشرفت ابزار را در ویرایش پیش‌نمایش زنده جریان می‌دهند. Microsoft Teams در گفت‌وگوهای شخصی از جریان پیشرفت بومی خود استفاده می‌کند.
- Telegram از `v2026.4.22` با به‌روزرسانی‌های پیش‌نمایش پیشرفت ابزار فعال منتشر شده است؛ فعال نگه‌داشتن آن‌ها رفتار منتشرشده را حفظ می‌کند.
- **Mattermost** از قبل فعالیت ابزار را در پست پیش‌نمایش پیش‌نویس واحد خود ادغام می‌کند (بالا را ببینید).
- ویرایش‌های پیشرفت ابزار از حالت فعال streaming پیش‌نمایش پیروی می‌کنند؛ وقتی streaming پیش‌نمایش `off` باشد یا وقتی streaming بلوکی پیام را بر عهده گرفته باشد، رد می‌شوند. در Telegram، `streaming.mode: "off"` فقط نهایی است: گفت‌وگوی عمومی پیشرفت نیز به‌جای تحویل به‌صورت پیام‌های وضعیت مستقل سرکوب می‌شود، درحالی‌که درخواست‌های تأیید، payloadهای رسانه و خطاها همچنان به‌طور معمول مسیریابی می‌شوند.
- برای نگه داشتن streaming پیش‌نمایش اما پنهان کردن خط‌های پیشرفت ابزار، `streaming.preview.toolProgress` را برای آن کانال روی `false` تنظیم کنید. برای غیرفعال کردن کامل ویرایش‌های پیش‌نمایش، `streaming.mode` را روی `off` تنظیم کنید.
- پاسخ‌های نقل‌قول انتخاب‌شدهٔ Telegram یک استثنا هستند: وقتی `replyToMode` مقدار `"off"` نباشد و متن نقل‌قول انتخاب‌شده وجود داشته باشد، OpenClaw جریان پیش‌نمایش پاسخ را برای آن نوبت رد می‌کند، بنابراین خط‌های پیش‌نمایش پیشرفت ابزار نمی‌توانند رندر شوند. پاسخ‌های پیام فعلی بدون متن نقل‌قول انتخاب‌شده همچنان streaming پیش‌نمایش را نگه می‌دارند. برای جزئیات، [مستندات کانال Telegram](/fa/channels/telegram) را ببینید.
- ویرایش‌های پیشرفت ابزار از حالت جریان‌دهی پیش‌نمایش فعال پیروی می‌کنند؛ وقتی جریان‌دهی پیش‌نمایش `off` باشد یا جریان‌دهی بلوکی کنترل پیام را به دست گرفته باشد، نادیده گرفته می‌شوند. در Telegram، `streaming.mode: "off"` فقط-نهایی است: گفت‌وگوی پیشرفت عمومی نیز به‌جای تحویل به‌عنوان پیام‌های وضعیت مستقل، سرکوب می‌شود، در حالی که درخواست‌های تأیید، محتواهای رسانه، و خطاها همچنان به‌طور عادی مسیریابی می‌شوند.
- برای نگه‌داشتن جریان‌دهی پیش‌نمایش اما پنهان‌کردن خط‌های پیشرفت ابزار، `streaming.preview.toolProgress` را برای آن کانال روی `false` تنظیم کنید. برای قابل مشاهده نگه‌داشتن خط‌های پیشرفت ابزار و در عین حال پنهان‌کردن متن command/exec، `streaming.preview.commandText` را روی `"status"` یا `streaming.progress.commandText` را روی `"status"` تنظیم کنید؛ مقدار پیش‌فرض `"raw"` است تا رفتار منتشرشده حفظ شود. این سیاست میان کانال‌های پیش‌نویس/پیشرفت که از رندرکننده پیشرفت فشرده OpenClaw استفاده می‌کنند مشترک است، از جمله Discord، Matrix، Microsoft Teams، Mattermost، پیش‌نمایش‌های پیش‌نویس Slack، و Telegram. برای غیرفعال‌کردن کامل ویرایش‌های پیش‌نمایش، `streaming.mode` را روی `off` تنظیم کنید.
- پاسخ‌های نقل‌قول انتخاب‌شده Telegram یک استثنا هستند: وقتی `replyToMode` برابر `"off"` نیست و متن نقل‌قول انتخاب‌شده وجود دارد، OpenClaw جریان پیش‌نمایش پاسخ را برای آن نوبت نادیده می‌گیرد، بنابراین خط‌های پیش‌نمایش پیشرفت ابزار نمی‌توانند رندر شوند. پاسخ‌های پیام فعلی بدون متن نقل‌قول انتخاب‌شده همچنان جریان‌دهی پیش‌نمایش را نگه می‌دارند. برای جزئیات، [مستندات کانال Telegram](/fa/channels/telegram) را ببینید.
نمونه:
خطوط پیشرفت را قابل مشاهده نگه دارید، اما متن خام فرمان/اجرا را پنهان کنید:
```json
{
@ -219,7 +219,26 @@ streaming پیش‌نمایش می‌تواند شامل به‌روزرسانی
"streaming": {
"mode": "partial",
"preview": {
"toolProgress": false
"toolProgress": true,
"commandText": "status"
}
}
}
}
}
```
همین ساختار را زیر یک کلید فشردهٔ دیگر برای کانال پیشرفت استفاده کنید، برای مثال `channels.discord`، `channels.matrix`، `channels.msteams`، `channels.mattermost`، یا پیش‌نمایش‌های پیش‌نویس Slack. برای حالت پیش‌نویس پیشرفت، همین سیاست را زیر `streaming.progress` قرار دهید:
```json
{
"channels": {
"telegram": {
"streaming": {
"mode": "progress",
"progress": {
"toolProgress": true,
"commandText": "status"
}
}
}
@ -229,7 +248,7 @@ streaming پیش‌نمایش می‌تواند شامل به‌روزرسانی
## مرتبط
- [پیش‌نویس‌های پیشرفت](/fa/concepts/progress-drafts) — پیام‌های قابل‌مشاهدهٔ کار در جریان که هنگام نوبت‌های طولانی به‌روزرسانی می‌شوند
- [پیام‌ها](/fa/concepts/messages) — چرخهٔ عمر و تحویل پیام
- [تلاش دوباره](/fa/concepts/retry) — رفتار تلاش دوباره هنگام شکست تحویل
- [کانال‌ها](/fa/channels) — پشتیبانی streaming برای هر کانال
- [پیش‌نویس‌های پیشرفت](/fa/concepts/progress-drafts) — پیام‌های قابل مشاهدهٔ کار در جریان که در طول نوبت‌های طولانی به‌روزرسانی می‌شوند
- [پیام‌ها](/fa/concepts/messages) — چرخهٔ عمر پیام و تحویل
- [تلاش مجدد](/fa/concepts/retry) — رفتار تلاش مجدد هنگام شکست تحویل
- [کانال‌ها](/fa/channels) — پشتیبانی پخش جریانی به‌ازای هر کانال

920
docs/fa/help/testing.md
View File

File diff suppressed because it is too large Load Diff

85
docs/fa/install/updating.md
View File

@ -1,14 +1,14 @@
---
read_when:
- به‌روزرسانی OpenClaw
- بعد از یک به‌روزرسانی مشکلی پیش می‌آید
summary: به‌روزرسانی ایمن OpenClaw (نصب سراسری یا از سورس)، به‌همراه راهبرد بازگشت
- پس از به‌روزرسانی چیزی خراب می‌شود
summary: به‌روزرسانی ایمن OpenClaw (نصب سراسری یا از منبع)، به‌همراه راهبرد بازگشت به نسخهٔ قبلی
title: به‌روزرسانی
x-i18n:
generated_at: "2026-05-03T21:36:30Z"
generated_at: "2026-05-04T07:05:33Z"
model: gpt-5.5
provider: openai
source_hash: f9e26ea71748dfd1573cdca01126bf29ebc56be56eac604e2b6a009b463820d1
source_hash: 3c9ff1d70d74f45efea3c148718e5cbc74001ce3d924b760edc4d68622d23714
source_path: install/updating.md
workflow: 16
---
@ -17,13 +17,13 @@ OpenClaw را به‌روز نگه دارید.
## توصیه‌شده: `openclaw update`
سریع‌ترین روش برای به‌روزرسانی. نوع نصب شما را تشخیص می‌دهد (npm یا git)، آخرین نسخه را دریافت می‌کند، `openclaw doctor` را اجرا می‌کند و gateway را دوباره راه‌اندازی می‌کند.
سریع‌ترین راه برای به‌روزرسانی. نوع نصب شما را تشخیص می‌دهد (npm یا git)، آخرین نسخه را دریافت می‌کند، `openclaw doctor` را اجرا می‌کند، و Gateway را دوباره راه‌اندازی می‌کند.
```bash
openclaw update
```
برای تغییر کانال‌ها یا هدف‌گیری یک نسخه مشخص:
برای تغییر کانال‌ها یا هدف‌گرفتن یک نسخه مشخص:
```bash
openclaw update --channel beta
@ -34,21 +34,17 @@ openclaw update --dry-run # preview without applying
`openclaw update` گزینه `--verbose` را نمی‌پذیرد. برای عیب‌یابی به‌روزرسانی، از
`--dry-run` برای پیش‌نمایش اقدام‌های برنامه‌ریزی‌شده، از `--json` برای نتایج ساختاریافته، یا از
`openclaw update status --json` برای بررسی کانال و وضعیت دسترس‌پذیری استفاده کنید. نصب‌کننده
`openclaw update status --json` برای بررسی وضعیت کانال و دسترس‌پذیری استفاده کنید. نصب‌کننده
پرچم `--verbose` خودش را دارد، اما آن پرچم بخشی از
`openclaw update` نیست.
`--channel beta` بتا را ترجیح می‌دهد، اما runtime وقتی
تگ بتا وجود نداشته باشد یا از آخرین انتشار پایدار قدیمی‌تر باشد، به stable/latest برمی‌گردد. اگر برای یک به‌روزرسانی موردی بسته، dist-tag خام npm beta را می‌خواهید، از `--tag beta`
استفاده کنید.
`--channel beta` بتا را ترجیح می‌دهد، اما runtime وقتی برچسب بتا وجود نداشته باشد یا از آخرین نسخه پایدار قدیمی‌تر باشد، به stable/latest برمی‌گردد. اگر dist-tag خام بتای npm را برای یک به‌روزرسانی موردی بسته می‌خواهید، از `--tag beta` استفاده کنید.
برای معنای کانال‌ها، [کانال‌های توسعه](/fa/install/development-channels) را ببینید.
## جابه‌جایی بین نصب‌های npm و git
وقتی می‌خواهید نوع نصب را تغییر دهید، از کانال‌ها استفاده کنید. به‌روزرسان وضعیت،
پیکربندی، اعتبارنامه‌ها و workspace شما را در `~/.openclaw` نگه می‌دارد؛ فقط تغییر می‌دهد
که CLI و gateway از کدام نصب کد OpenClaw استفاده کنند.
وقتی می‌خواهید نوع نصب را تغییر دهید از کانال‌ها استفاده کنید. به‌روزرسان وضعیت، پیکربندی، credentials، و workspace شما را در `~/.openclaw` نگه می‌دارد؛ فقط این را تغییر می‌دهد که CLI و Gateway از کدام نصب کد OpenClaw استفاده کنند.
```bash
# npm package install -> editable git checkout
@ -65,10 +61,7 @@ openclaw update --channel dev --dry-run
openclaw update --channel stable --dry-run
```
کانال `dev` وجود یک checkout از git را تضمین می‌کند، آن را می‌سازد و CLI سراسری را
از همان checkout نصب می‌کند. کانال‌های `stable` و `beta` از نصب‌های بسته‌ای استفاده می‌کنند. اگر
gateway از قبل نصب شده باشد، `openclaw update` فراداده سرویس را تازه‌سازی می‌کند
و مگر اینکه `--no-restart` را پاس دهید، آن را دوباره راه‌اندازی می‌کند.
کانال `dev` وجود یک checkout از git را تضمین می‌کند، آن را build می‌کند، و CLI سراسری را از همان checkout نصب می‌کند. کانال‌های `stable` و `beta` از نصب بسته‌ای استفاده می‌کنند. اگر Gateway از قبل نصب شده باشد، `openclaw update` فراداده سرویس را تازه‌سازی می‌کند و آن را دوباره راه‌اندازی می‌کند، مگر اینکه `--no-restart` را پاس دهید.
## جایگزین: اجرای دوباره نصب‌کننده
@ -76,37 +69,30 @@ gateway از قبل نصب شده باشد، `openclaw update` فراداده س
curl -fsSL https://openclaw.ai/install.sh | bash
```
برای رد کردن onboarding، `--no-onboard` را اضافه کنید. برای اجبار یک نوع نصب مشخص از طریق
نصب‌کننده، `--install-method git --no-onboard` یا
برای رد کردن onboarding، `--no-onboard` را اضافه کنید. برای اجبار یک نوع نصب مشخص از طریق نصب‌کننده، `--install-method git --no-onboard` یا
`--install-method npm --no-onboard` را پاس دهید.
اگر `openclaw update` پس از مرحله نصب بسته npm شکست خورد، نصب‌کننده را
دوباره اجرا کنید. نصب‌کننده updater قدیمی را فراخوانی نمی‌کند؛ نصب بسته
سراسری را مستقیما اجرا می‌کند و می‌تواند یک نصب npm را که تا حدی به‌روز شده، بازیابی کند.
اگر `openclaw update` پس از مرحله نصب بسته npm شکست خورد، نصب‌کننده را دوباره اجرا کنید. نصب‌کننده updater قدیمی را فراخوانی نمی‌کند؛ نصب بسته سراسری را مستقیما اجرا می‌کند و می‌تواند یک نصب npm را که بخشی از آن به‌روزرسانی شده بازیابی کند.
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
```
برای سنجاق کردن بازیابی به یک نسخه یا dist-tag مشخص، `--version` را اضافه کنید:
برای ثابت‌کردن بازیابی روی یک نسخه یا dist-tag مشخص، `--version` را اضافه کنید:
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
```
## جایگزین: npm، pnpm یا bun دستی
## جایگزین: npm، pnpm، یا bun به‌صورت دستی
```bash
npm i -g openclaw@latest
```
وقتی `openclaw update` یک نصب سراسری npm را مدیریت می‌کند، ابتدا هدف را در
یک پیشوند موقت npm نصب می‌کند، موجودی `dist` بسته‌بندی‌شده را راستی‌آزمایی می‌کند، سپس
درخت بسته پاک را به پیشوند سراسری واقعی جابه‌جا می‌کند. این کار از هم‌پوشانی npm
یک بسته جدید روی فایل‌های کهنه بسته قدیمی جلوگیری می‌کند. اگر فرمان نصب شکست بخورد،
OpenClaw یک بار با `--omit=optional` دوباره تلاش می‌کند. این تلاش دوباره به میزبان‌هایی کمک می‌کند که در آن‌ها
وابستگی‌های اختیاری native نمی‌توانند کامپایل شوند، در حالی که اگر fallback هم شکست بخورد،
شکست اصلی همچنان قابل مشاهده می‌ماند.
برای نصب‌های تحت نظارت، `openclaw update` را ترجیح دهید، چون می‌تواند جابه‌جایی بسته را با سرویس Gateway در حال اجرا هماهنگ کند. اگر وقتی یک Gateway مدیریت‌شده در حال اجراست به‌صورت دستی به‌روزرسانی می‌کنید، بلافاصله پس از پایان کار مدیر بسته، Gateway را دوباره راه‌اندازی کنید تا فرایند قدیمی همچنان از فایل‌های بسته جایگزین‌شده سرویس‌دهی نکند.
وقتی `openclaw update` یک نصب npm سراسری را مدیریت می‌کند، ابتدا هدف را در یک پیشوند موقت npm نصب می‌کند، موجودی `dist` بسته‌بندی‌شده را راستی‌آزمایی می‌کند، سپس درخت بسته پاک را به پیشوند سراسری واقعی منتقل می‌کند. این کار از قرار دادن بسته جدید توسط npm روی فایل‌های مانده از بسته قدیمی جلوگیری می‌کند. اگر فرمان نصب شکست بخورد، OpenClaw یک بار با `--omit=optional` دوباره تلاش می‌کند. این تلاش دوباره به میزبان‌هایی کمک می‌کند که وابستگی‌های اختیاری native در آن‌ها کامپایل نمی‌شوند، در حالی که اگر fallback هم شکست بخورد، شکست اصلی همچنان قابل مشاهده می‌ماند.
```bash
pnpm add -g openclaw@latest
@ -120,13 +106,13 @@ bun add -g openclaw@latest
<AccordionGroup>
<Accordion title="درخت بسته فقط‌خواندنی">
OpenClaw در runtime با نصب‌های سراسری بسته‌بندی‌شده مانند فقط‌خواندنی رفتار می‌کند، حتی وقتی دایرکتوری بسته سراسری برای کاربر فعلی قابل نوشتن باشد. نصب‌های بسته Plugin در ریشه‌های npm/git متعلق به OpenClaw زیر دایرکتوری پیکربندی کاربر قرار می‌گیرند، و راه‌اندازی Gateway درخت بسته OpenClaw را تغییر نمی‌دهد.
OpenClaw نصب‌های سراسری بسته‌بندی‌شده را در runtime فقط‌خواندنی در نظر می‌گیرد، حتی وقتی دایرکتوری بسته سراسری توسط کاربر فعلی قابل نوشتن باشد. نصب‌های بسته Plugin در ریشه‌های npm/git متعلق به OpenClaw زیر دایرکتوری پیکربندی کاربر قرار می‌گیرند، و راه‌اندازی Gateway درخت بسته OpenClaw را تغییر نمی‌دهد.
برخی تنظیمات npm در Linux بسته‌های سراسری را زیر دایرکتوری‌های متعلق به root مانند `/usr/lib/node_modules/openclaw` نصب می‌کنند. OpenClaw از این چیدمان پشتیبانی می‌کند، چون فرمان‌های نصب/به‌روزرسانی Plugin خارج از آن دایرکتوری بسته سراسری می‌نویسند.
برخی تنظیمات npm در Linux بسته‌های سراسری را زیر دایرکتوری‌های متعلق به root مانند `/usr/lib/node_modules/openclaw` نصب می‌کنند. OpenClaw از این چیدمان پشتیبانی می‌کند، چون فرمان‌های نصب/به‌روزرسانی Plugin بیرون از آن دایرکتوری بسته سراسری می‌نویسند.
</Accordion>
<Accordion title="واحدهای systemd سخت‌سازی‌شده">
به OpenClaw دسترسی نوشتن به ریشه‌های پیکربندی/وضعیتش بدهید تا نصب‌های صریح Plugin، به‌روزرسانی‌های Plugin و پاک‌سازی doctor بتوانند تغییرات خود را پایدار کنند:
به OpenClaw دسترسی نوشتن به ریشه‌های پیکربندی/وضعیت خودش بدهید تا نصب‌های صریح Plugin، به‌روزرسانی‌های Plugin، و پاک‌سازی doctor بتوانند تغییراتشان را پایدار کنند:
```ini
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
@ -134,7 +120,7 @@ bun add -g openclaw@latest
</Accordion>
<Accordion title="پیش‌بررسی فضای دیسک">
پیش از به‌روزرسانی‌های بسته و نصب‌های صریح Plugin، OpenClaw تلاش می‌کند یک بررسی بهترین‌تلاشی فضای دیسک برای volume هدف انجام دهد. فضای کم یک هشدار همراه با مسیر بررسی‌شده تولید می‌کند، اما به‌روزرسانی را مسدود نمی‌کند، چون quotaهای فایل‌سیستم، snapshotها و volumeهای شبکه می‌توانند پس از بررسی تغییر کنند. نصب واقعی package-manager و راستی‌آزمایی پس از نصب همچنان مرجع نهایی هستند.
پیش از به‌روزرسانی بسته‌ها و نصب‌های صریح Plugin، OpenClaw تلاش می‌کند برای حجم هدف یک بررسی best-effort فضای دیسک انجام دهد. فضای کم یک هشدار با مسیر بررسی‌شده ایجاد می‌کند، اما به‌روزرسانی را مسدود نمی‌کند، چون سهمیه‌های فایل‌سیستم، snapshotها، و حجم‌های شبکه‌ای می‌توانند پس از بررسی تغییر کنند. نصب واقعی مدیر بسته و راستی‌آزمایی پس از نصب همچنان مرجع نهایی هستند.
</Accordion>
</AccordionGroup>
@ -156,21 +142,16 @@ bun add -g openclaw@latest
}
```
| کانال | رفتار |
| کانال | رفتار |
| -------- | ------------------------------------------------------------------------------------------------------------- |
| `stable` | `stableDelayHours` صبر می‌کند، سپس با jitter قطعی در سراسر `stableJitterHours` اعمال می‌کند (انتشار پخش‌شده). |
| `beta` | هر `betaCheckIntervalHours` بررسی می‌کند (پیش‌فرض: هر ساعت) و بلافاصله اعمال می‌کند. |
| `dev` | اعمال خودکار ندارد. از `openclaw update` به‌صورت دستی استفاده کنید. |
| `stable` | به اندازه `stableDelayHours` صبر می‌کند، سپس با jitter قطعی در سراسر `stableJitterHours` اعمال می‌کند (rollout پخش‌شده). |
| `beta` | هر `betaCheckIntervalHours` بررسی می‌کند (پیش‌فرض: هر ساعت) و بلافاصله اعمال می‌کند. |
| `dev` | اعمال خودکار ندارد. از `openclaw update` به‌صورت دستی استفاده کنید. |
Gateway همچنین هنگام راه‌اندازی یک راهنمای به‌روزرسانی ثبت می‌کند (با `update.checkOnStart: false` غیرفعال کنید).
برای downgrade یا بازیابی حادثه، `OPENCLAW_NO_AUTO_UPDATE=1` را در محیط gateway تنظیم کنید تا اعمال خودکار حتی وقتی `update.auto.enabled` پیکربندی شده باشد مسدود شود. راهنماهای به‌روزرسانی هنگام راه‌اندازی همچنان می‌توانند اجرا شوند، مگر اینکه `update.checkOnStart` نیز غیرفعال شده باشد.
Gateway همچنین هنگام startup یک راهنمای به‌روزرسانی در log می‌نویسد (با `update.checkOnStart: false` غیرفعال کنید).
برای downgrade یا بازیابی رخداد، `OPENCLAW_NO_AUTO_UPDATE=1` را در محیط Gateway تنظیم کنید تا اعمال خودکار حتی وقتی `update.auto.enabled` پیکربندی شده است مسدود شود. راهنماهای به‌روزرسانی هنگام startup همچنان می‌توانند اجرا شوند، مگر اینکه `update.checkOnStart` نیز غیرفعال شده باشد.
به‌روزرسانی‌های package-manager که از طریق handler زنده control-plane در Gateway درخواست می‌شوند
پس از جابه‌جایی بسته، یک راه‌اندازی مجدد به‌روزرسانی بدون تعویق و بدون cooldown را اجبار می‌کنند. این کار
از باقی ماندن یک پردازش قدیمی در حافظه آن‌قدر طولانی که chunkها را با lazy-load
از درخت بسته‌ای که قبلا جایگزین شده است بار کند، جلوگیری می‌کند. `openclaw update` در Shell
برای نصب‌های تحت نظارت همچنان مسیر ترجیحی است، چون می‌تواند سرویس را اطراف به‌روزرسانی متوقف و
دوباره راه‌اندازی کند.
به‌روزرسانی‌های مدیر بسته که از طریق handler زنده control-plane Gateway درخواست می‌شوند، پس از جابه‌جایی بسته یک restart به‌روزرسانی بدون تعویق و بدون cooldown را اجبار می‌کنند. این کار از باقی ماندن یک فرایند قدیمی در حافظه برای مدتی که بتواند chunkها را از درخت بسته‌ای که قبلا جایگزین شده lazy-load کند جلوگیری می‌کند. مسیر shell یعنی `openclaw update` همچنان برای نصب‌های تحت نظارت ترجیح داده می‌شود، چون می‌تواند سرویس را پیرامون به‌روزرسانی متوقف و دوباره راه‌اندازی کند.
## پس از به‌روزرسانی
@ -182,9 +163,9 @@ Gateway همچنین هنگام راه‌اندازی یک راهنمای به
openclaw doctor
```
پیکربندی را مهاجرت می‌دهد، سیاست‌های DM را audit می‌کند و سلامت gateway را بررسی می‌کند. جزئیات: [Doctor](/fa/gateway/doctor)
پیکربندی را migrate می‌کند، سیاست‌های DM را audit می‌کند، و سلامت Gateway را بررسی می‌کند. جزئیات: [Doctor](/fa/gateway/doctor)
### راه‌اندازی مجدد gateway
### راه‌اندازی دوباره Gateway
```bash
openclaw gateway restart
@ -198,9 +179,9 @@ openclaw health
</Steps>
## بازگشت به نسخه قبلی
## بازگردانی
### سنجاق کردن یک نسخه (npm)
### ثابت‌کردن یک نسخه (npm)
```bash
npm i -g openclaw@<version>
@ -212,7 +193,7 @@ openclaw gateway restart
`npm view openclaw version` نسخه منتشرشده فعلی را نشان می‌دهد.
</Tip>
### سنجاق کردن یک commit (source)
### ثابت‌کردن یک commit (source)
```bash
git fetch origin

1257
docs/fa/plugins/google-meet.md
View File

File diff suppressed because it is too large Load Diff

457
docs/fa/plugins/voice-call.md
View File

@ -1,23 +1,23 @@
---
read_when:
- می‌خواهید از OpenClaw یک تماس صوتی خروجی برقرار کنید
- شما در حال پیکربندی یا توسعه Plugin تماس صوتی هستید
- به صدای بلادرنگ یا رونویسی جریانی در بستر تلفنی نیاز دارید
- می‌خواهید یک تماس صوتی خروجی از OpenClaw برقرار کنید
- در حال پیکربندی یا توسعهٔ Plugin تماس صوتی هستید
- به صدای بلادرنگ یا رونویسی جریانی در ارتباطات تلفنی نیاز دارید
sidebarTitle: Voice call
summary: برقراری تماس‌های صوتی خروجی و پذیرش تماس‌های صوتی ورودی از طریق Twilio، Telnyx یا Plivo، با امکان اختیاری صدای بلادرنگ و رونویسی جریانی
summary: تماس‌های صوتی خروجی برقرار کنید و تماس‌های صوتی ورودی را از طریق Twilio، Telnyx یا Plivo بپذیرید، همراه با صدای بی‌درنگ و رونویسی جریانی اختیاری
title: Plugin تماس صوتی
x-i18n:
generated_at: "2026-05-02T22:24:09Z"
generated_at: "2026-05-04T07:06:59Z"
model: gpt-5.5
provider: openai
source_hash: 18a9a0d7095ec92036b516cc26c69219a0a2fd9bb8e0cb2e7509123bb4f3f65a
source_hash: 8ec2c22dcc9073572963744685a432328787bcedb14025e0326c20d9d842f857
source_path: plugins/voice-call.md
workflow: 16
---
تماس‌های صوتی برای OpenClaw از طریق یک Plugin. از اعلان‌های خروجی،
گفت‌وگوهای چندمرحله‌ای، صدای بلادرنگ تمام‌دوطرفه، رونویسی
جریانی، و تماس‌های ورودی با سیاست‌های فهرست مجاز پشتیبانی می‌کند.
گفت‌وگوهای چندمرحله‌ای، صدای بلادرنگ تمام‌دوطرفه، رونویسی جریانی،
و تماس‌های ورودی با سیاست‌های فهرست مجاز پشتیبانی می‌کند.
**ارائه‌دهندگان فعلی:** `twilio` (Programmable Voice + Media Streams)،
`telnyx` (Call Control v2)، `plivo` (Voice API + XML transfer + GetInput
@ -25,22 +25,21 @@ speech)، `mock` (توسعه/بدون شبکه).
<Note>
Plugin تماس صوتی **داخل فرایند Gateway** اجرا می‌شود. اگر از یک
Gateway راه دور استفاده می‌کنید، Plugin را روی ماشینی که Gateway را اجرا
می‌کند نصب و پیکربندی کنید، سپس Gateway را بازراه‌اندازی کنید تا آن را
بارگذاری کند.
Gateway راه‌دور استفاده می‌کنید، Plugin را روی دستگاهی نصب و پیکربندی کنید
که Gateway را اجرا می‌کند، سپس Gateway را بازراه‌اندازی کنید تا آن را بارگذاری کند.
</Note>
## شروع سریع
<Steps>
<Step title="نصب Plugin">
<Step title="Install the plugin">
<Tabs>
<Tab title="از npm">
<Tab title="From npm">
```bash
openclaw plugins install @openclaw/voice-call
```
</Tab>
<Tab title="از یک پوشه محلی (توسعه)">
<Tab title="From a local folder (dev)">
```bash
PLUGIN_SRC=./path/to/local/voice-call-plugin
openclaw plugins install "$PLUGIN_SRC"
@ -49,37 +48,37 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
</Tab>
</Tabs>
برای دنبال کردن برچسب انتشار رسمی فعلی، از بسته بدون نسخه استفاده کنید.
فقط زمانی یک نسخه دقیق را pin کنید که به نصب بازتولیدپذیر نیاز دارید.
برای دنبال‌کردن برچسب انتشار رسمی فعلی، از بستهٔ بدون نسخه استفاده کنید. فقط زمانی
نسخهٔ دقیق را پین کنید که به نصب بازتولیدپذیر نیاز دارید.
پس از آن Gateway را بازراه‌اندازی کنید تا Plugin بارگذاری شود.
سپس Gateway را بازراه‌اندازی کنید تا Plugin بارگذاری شود.
</Step>
<Step title="پیکربندی ارائه‌دهنده و Webhook">
پیکربندی را زیر `plugins.entries.voice-call.config` تنظیم کنید (برای شکل
کامل، [پیکربندی](#configuration) را در پایین ببینید). حداقل موارد لازم:
`provider`، اعتبارنامه‌های ارائه‌دهنده، `fromNumber`، و یک URL مربوط به
Webhook که به‌صورت عمومی قابل دسترسی باشد.
<Step title="Configure provider and webhook">
پیکربندی را زیر `plugins.entries.voice-call.config` تنظیم کنید (برای شکل کامل،
[پیکربندی](#configuration) را در پایین ببینید). حداقل موارد لازم:
`provider`، اعتبارنامه‌های ارائه‌دهنده، `fromNumber`، و یک URL Webhook
که به‌صورت عمومی قابل دسترسی باشد.
</Step>
<Step title="اعتبارسنجی راه‌اندازی">
<Step title="Verify setup">
```bash
openclaw voicecall setup
```
خروجی پیش‌فرض در لاگ‌های چت و ترمینال‌ها خواناست. فعال بودن
Plugin، اعتبارنامه‌های ارائه‌دهنده، در معرض دسترس بودن Webhook، و این را
بررسی می‌کند که فقط یک حالت صوتی (`streaming` یا `realtime`) فعال باشد.
برای اسکریپت‌ها از `--json` استفاده کنید.
خروجی پیش‌فرض در گزارش‌های چت و ترمینال‌ها خوانا است. فعال‌بودن
Plugin، اعتبارنامه‌های ارائه‌دهنده، در معرض‌بودن Webhook، و اینکه
فقط یک حالت صوتی (`streaming` یا `realtime`) فعال باشد را بررسی می‌کند. برای
اسکریپت‌ها از `--json` استفاده کنید.
</Step>
<Step title="آزمون دود">
<Step title="Smoke test">
```bash
openclaw voicecall smoke
openclaw voicecall smoke --to "+15555550123"
```
هر دو به‌صورت پیش‌فرض اجرای آزمایشی بدون اثر هستند. برای اینکه واقعا یک
تماس اعلان خروجی کوتاه برقرار شود، `--yes` را اضافه کنید:
هر دو به‌صورت پیش‌فرض اجرای خشک هستند. برای برقراری واقعی یک تماس اعلان خروجی
کوتاه، `--yes` را اضافه کنید:
```bash
openclaw voicecall smoke --to "+15555550123" --yes
@ -89,22 +88,21 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
</Steps>
<Warning>
برای Twilio، Telnyx، و Plivo، راه‌اندازی باید به یک **URL عمومی Webhook** resolve شود.
اگر `publicUrl`، URL تونل، URL مربوط به Tailscale، یا fallback سرو، به loopback
یا فضای شبکه خصوصی resolve شود، راه‌اندازی به‌جای شروع ارائه‌دهنده‌ای که
نمی‌تواند Webhookهای اپراتور را دریافت کند، شکست می‌خورد.
برای Twilio، Telnyx، و Plivo، راه‌اندازی باید به یک **URL Webhook عمومی** برسد.
اگر `publicUrl`، URL تونل، URL Tailscale، یا جایگزین سرویس‌دهی
به loopback یا فضای شبکهٔ خصوصی resolve شود، راه‌اندازی به‌جای
شروع ارائه‌دهنده‌ای که نمی‌تواند Webhookهای حامل را دریافت کند، شکست می‌خورد.
</Warning>
## پیکربندی
اگر `enabled: true` باشد اما اعتبارنامه‌های ارائه‌دهنده انتخاب‌شده موجود
نباشد، شروع Gateway یک هشدار setup-incomplete همراه با کلیدهای مفقود لاگ
می‌کند و از شروع runtime صرف‌نظر می‌کند. فرمان‌ها، فراخوانی‌های RPC، و
ابزارهای agent همچنان هنگام استفاده، پیکربندی دقیق مفقود ارائه‌دهنده را
برمی‌گردانند.
اگر `enabled: true` باشد اما ارائه‌دهندهٔ انتخاب‌شده فاقد اعتبارنامه باشد،
شروع Gateway یک هشدار راه‌اندازی ناقص با کلیدهای مفقود ثبت می‌کند و
از شروع runtime صرف‌نظر می‌کند. فرمان‌ها، فراخوانی‌های RPC، و ابزارهای عامل همچنان
هنگام استفاده، پیکربندی دقیق مفقود ارائه‌دهنده را برمی‌گردانند.
<Note>
اعتبارنامه‌های تماس صوتی SecretRefها را می‌پذیرند. `plugins.entries.voice-call.config.twilio.authToken`، `plugins.entries.voice-call.config.realtime.providers.*.apiKey`، `plugins.entries.voice-call.config.streaming.providers.*.apiKey`، و `plugins.entries.voice-call.config.tts.providers.*.apiKey` از طریق سطح استاندارد SecretRef resolve می‌شوند؛ [سطح اعتبارنامه SecretRef](/fa/reference/secretref-credential-surface) را ببینید.
اعتبارنامه‌های voice-call از SecretRefها پشتیبانی می‌کنند. `plugins.entries.voice-call.config.twilio.authToken`، `plugins.entries.voice-call.config.realtime.providers.*.apiKey`، `plugins.entries.voice-call.config.streaming.providers.*.apiKey`، و `plugins.entries.voice-call.config.tts.providers.*.apiKey` از طریق سطح استاندارد SecretRef resolve می‌شوند؛ [سطح اعتبارنامه SecretRef](/fa/reference/secretref-credential-surface) را ببینید.
</Note>
```json5
@ -177,31 +175,31 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
```
<AccordionGroup>
<Accordion title="نکات ارائه و امنیت ارائه‌دهنده">
- Twilio، Telnyx، و Plivo همگی به یک URL مربوط به Webhook نیاز دارند که **به‌صورت عمومی قابل دسترسی** باشد.
- `mock` یک ارائه‌دهنده توسعه محلی است (بدون فراخوانی شبکه).
<Accordion title="Provider exposure and security notes">
- Twilio، Telnyx، و Plivo همگی به یک URL Webhook **قابل دسترسی عمومی** نیاز دارند.
- `mock` یک ارائه‌دهندهٔ توسعهٔ محلی است (بدون فراخوانی شبکه).
- Telnyx به `telnyx.publicKey` (یا `TELNYX_PUBLIC_KEY`) نیاز دارد مگر اینکه `skipSignatureVerification` برابر true باشد.
- `skipSignatureVerification` فقط برای تست محلی است.
- در سطح رایگان ngrok، `publicUrl` را روی URL دقیق ngrok تنظیم کنید؛ اعتبارسنجی امضا همیشه اعمال می‌شود.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` فقط زمانی به Twilio Webhookها با امضاهای نامعتبر اجازه می‌دهد که `tunnel.provider="ngrok"` و `serve.bind` برابر loopback باشد (عامل محلی ngrok). فقط برای توسعه محلی.
- URLهای سطح رایگان Ngrok ممکن است تغییر کنند یا رفتار میان‌صفحه اضافه کنند؛ اگر `publicUrl` جابه‌جا شود، امضاهای Twilio شکست می‌خورند. تولید: یک دامنه پایدار یا یک funnel در Tailscale را ترجیح دهید.
- `skipSignatureVerification` فقط برای آزمون محلی است.
- در سطح رایگان ngrok، `publicUrl` را روی URL دقیق ngrok تنظیم کنید؛ راستی‌آزمایی امضا همیشه اعمال می‌شود.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` به Webhookهای Twilio با امضاهای نامعتبر اجازه می‌دهد **فقط** وقتی `tunnel.provider="ngrok"` و `serve.bind` برابر loopback باشد (عامل محلی ngrok). فقط برای توسعهٔ محلی.
- URLهای سطح رایگان ngrok می‌توانند تغییر کنند یا رفتار میان‌برگه اضافه کنند؛ اگر `publicUrl` منحرف شود، امضاهای Twilio شکست می‌خورند. تولید: یک دامنهٔ پایدار یا funnel در Tailscale را ترجیح دهید.
</Accordion>
<Accordion title="سقف‌های اتصال جریانی">
- `streaming.preStartTimeoutMs` سوکت‌هایی را می‌بندد که هرگز یک قاب `start` معتبر نمی‌فرستند.
- `streaming.maxPendingConnections` سقف کل سوکت‌های pre-start احرازنشده را تعیین می‌کند.
- `streaming.maxPendingConnectionsPerIp` سقف سوکت‌های pre-start احرازنشده را برای هر IP مبدأ تعیین می‌کند.
- `streaming.maxConnections` سقف کل سوکت‌های باز stream رسانه را تعیین می‌کند (در انتظار + فعال).
<Accordion title="Streaming connection caps">
- `streaming.preStartTimeoutMs` سوکت‌هایی را می‌بندد که هرگز یک فریم معتبر `start` ارسال نمی‌کنند.
- `streaming.maxPendingConnections` مجموع سوکت‌های پیش از شروعِ احرازنشده را محدود می‌کند.
- `streaming.maxPendingConnectionsPerIp` سوکت‌های پیش از شروعِ احرازنشده را به‌ازای هر IP مبدأ محدود می‌کند.
- `streaming.maxConnections` مجموع سوکت‌های باز جریان رسانه را محدود می‌کند (در انتظار + فعال).
</Accordion>
<Accordion title="مهاجرت‌های پیکربندی قدیمی">
پیکربندی‌های قدیمی‌تر که از `provider: "log"`، `twilio.from`، یا کلیدهای
قدیمی `streaming.*` مربوط به OpenAI استفاده می‌کنند، با `openclaw doctor --fix`
بازنویسی می‌شوند. fallback زمان اجرا فعلا همچنان کلیدهای قدیمی voice-call را
می‌پذیرد، اما مسیر بازنویسی `openclaw doctor --fix` است و shim سازگاری
<Accordion title="Legacy config migrations">
پیکربندی‌های قدیمی‌تر که از `provider: "log"`، `twilio.from`، یا کلیدهای قدیمی
OpenAI در `streaming.*` استفاده می‌کنند، با `openclaw doctor --fix` بازنویسی می‌شوند.
جایگزین runtime فعلاً همچنان کلیدهای قدیمی voice-call را می‌پذیرد، اما
مسیر بازنویسی `openclaw doctor --fix` است و shim سازگاری
موقتی است.
کلیدهای جریانی مهاجرت‌شده خودکار:
کلیدهای streaming که به‌صورت خودکار مهاجرت می‌شوند:
- `streaming.sttProvider` → `streaming.provider`
- `streaming.openaiApiKey` → `streaming.providers.openai.apiKey`
@ -212,53 +210,56 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
</Accordion>
</AccordionGroup>
## دامنه جلسه
## دامنهٔ نشست
به‌صورت پیش‌فرض، تماس صوتی از `sessionScope: "per-phone"` استفاده می‌کند تا
تماس‌های تکراری از همان تماس‌گیرنده حافظه گفت‌وگو را حفظ کنند. وقتی هر تماس
اپراتور باید با زمینه تازه شروع شود، `sessionScope: "per-call"` را تنظیم کنید؛
برای مثال جریان‌های پذیرش، رزرو، IVR، یا پل Google Meet که در آن‌ها همان
شماره تلفن ممکن است نماینده جلسه‌های متفاوت باشد.
به‌صورت پیش‌فرض، Voice Call از `sessionScope: "per-phone"` استفاده می‌کند تا تماس‌های تکراری از
همان تماس‌گیرنده حافظهٔ گفت‌وگو را حفظ کنند. وقتی هر تماس حامل باید با زمینهٔ تازه شروع شود،
برای نمونه جریان‌های پذیرش، رزرو، IVR، یا پل Google Meet که در آن همان شمارهٔ تلفن ممکن است
نمایندهٔ جلسه‌های متفاوت باشد، `sessionScope: "per-call"` را تنظیم کنید.
## گفت‌وگوهای صوتی بلادرنگ
`realtime` یک ارائه‌دهنده صدای بلادرنگ تمام‌دوطرفه را برای صدای تماس زنده
انتخاب می‌کند. این از `streaming` جداست؛ `streaming` فقط صدا را به
ارائه‌دهندگان رونویسی بلادرنگ می‌فرستد.
`realtime` یک ارائه‌دهندهٔ صوتی بلادرنگ تمام‌دوطرفه را برای صدای تماس زنده
انتخاب می‌کند. این با `streaming` جدا است، که فقط صدا را به
ارائه‌دهندگان رونویسی بلادرنگ ارسال می‌کند.
<Warning>
`realtime.enabled` نمی‌تواند با `streaming.enabled` ترکیب شود. برای هر تماس
یک حالت صوتی انتخاب کنید.
</Warning>
رفتار فعلی runtime:
رفتار runtime فعلی:
- `realtime.enabled` برای Twilio Media Streams پشتیبانی می‌شود.
- `realtime.provider` اختیاری است. اگر تنظیم نشود، Voice Call از اولین ارائه‌دهنده ثبت‌شده صدای بلادرنگ استفاده می‌کند.
- ارائه‌دهندگان همراه صدای بلادرنگ: Google Gemini Live (`google`) و OpenAI (`openai`)، که توسط Pluginهای ارائه‌دهنده خودشان ثبت می‌شوند.
- پیکربندی خام تحت مالکیت ارائه‌دهنده زیر `realtime.providers.<providerId>` قرار می‌گیرد.
- Voice Call به‌صورت پیش‌فرض ابزار بلادرنگ مشترک `openclaw_agent_consult` را ارائه می‌کند. مدل بلادرنگ وقتی تماس‌گیرنده استدلال عمیق‌تر، اطلاعات فعلی، یا ابزارهای عادی OpenClaw را می‌خواهد، می‌تواند آن را فراخوانی کند.
- `realtime.fastContext.enabled` به‌صورت پیش‌فرض خاموش است. وقتی فعال باشد، Voice Call ابتدا حافظه/زمینه جلسه indexشده را برای پرسش consult جست‌وجو می‌کند و پیش از fallback به agent کامل consult فقط در صورتی که `realtime.fastContext.fallbackToConsult` برابر true باشد، آن قطعه‌ها را در بازه `realtime.fastContext.timeoutMs` به مدل بلادرنگ برمی‌گرداند.
- اگر `realtime.provider` به یک ارائه‌دهنده ثبت‌نشده اشاره کند، یا اصلا هیچ ارائه‌دهنده صدای بلادرنگی ثبت نشده باشد، Voice Call به‌جای شکست دادن کل Plugin، یک هشدار لاگ می‌کند و از رسانه بلادرنگ صرف‌نظر می‌کند.
- کلیدهای جلسه consult در صورت وجود از جلسه تماس ذخیره‌شده دوباره استفاده می‌کنند، سپس به `sessionScope` پیکربندی‌شده fallback می‌کنند (`per-phone` به‌صورت پیش‌فرض، یا `per-call` برای تماس‌های ایزوله).
- `realtime.provider` اختیاری است. اگر تنظیم نشود، Voice Call از نخستین ارائه‌دهندهٔ صوتی بلادرنگ ثبت‌شده استفاده می‌کند.
- ارائه‌دهندگان صوتی بلادرنگ همراه: Google Gemini Live (`google`) و OpenAI (`openai`)، که توسط Pluginهای ارائه‌دهندهٔ خود ثبت می‌شوند.
- پیکربندی خام متعلق به ارائه‌دهنده زیر `realtime.providers.<providerId>` قرار دارد.
- Voice Call ابزار بلادرنگ مشترک `openclaw_agent_consult` را به‌صورت پیش‌فرض در معرض می‌گذارد. مدل بلادرنگ می‌تواند وقتی تماس‌گیرنده استدلال عمیق‌تر، اطلاعات فعلی، یا ابزارهای عادی OpenClaw را می‌خواهد، آن را فراخوانی کند.
- `realtime.fastContext.enabled` به‌صورت پیش‌فرض خاموش است. وقتی فعال باشد، Voice Call ابتدا حافظهٔ ایندکس‌شده/زمینهٔ نشست را برای پرسش مشاوره جست‌وجو می‌کند و این قطعه‌ها را ظرف `realtime.fastContext.timeoutMs` به مدل بلادرنگ برمی‌گرداند، پیش از آنکه فقط در صورت true بودن `realtime.fastContext.fallbackToConsult` به عامل کامل مشاوره fallback کند.
- اگر `realtime.provider` به ارائه‌دهنده‌ای ثبت‌نشده اشاره کند، یا هیچ ارائه‌دهندهٔ صوتی بلادرنگی اصلاً ثبت نشده باشد، Voice Call یک هشدار ثبت می‌کند و به‌جای شکست‌دادن کل Plugin، از رسانهٔ بلادرنگ صرف‌نظر می‌کند.
- کلیدهای نشست مشاوره وقتی موجود باشند از نشست تماس ذخیره‌شده دوباره استفاده می‌کنند، سپس به `sessionScope` پیکربندی‌شده fallback می‌کنند (`per-phone` به‌صورت پیش‌فرض، یا `per-call` برای تماس‌های ایزوله).
### سیاست ابزار
`realtime.toolPolicy` اجرای consult را کنترل می‌کند:
`realtime.toolPolicy` اجرای مشاوره را کنترل می‌کند:
| سیاست | رفتار |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `safe-read-only` | ابزار consult را ارائه می‌کند و agent عادی را به `read`، `web_search`، `web_fetch`، `x_search`، `memory_search`، و `memory_get` محدود می‌کند. |
| `owner` | ابزار consult را ارائه می‌کند و به agent عادی اجازه می‌دهد از سیاست ابزار عادی agent استفاده کند. |
| `none` | ابزار consult را ارائه نمی‌کند. `realtime.tools` سفارشی همچنان به ارائه‌دهنده بلادرنگ منتقل می‌شود. |
| `safe-read-only` | ابزار مشاوره را در معرض بگذار و عامل عادی را به `read`، `web_search`، `web_fetch`، `x_search`، `memory_search`، و `memory_get` محدود کن. |
| `owner` | ابزار مشاوره را در معرض بگذار و به عامل عادی اجازه بده از سیاست ابزار عادی عامل استفاده کند. |
| `none` | ابزار مشاوره را در معرض نگذار. `realtime.tools` سفارشی همچنان به ارائه‌دهندهٔ بلادرنگ عبور داده می‌شوند. |
### نمونه‌های ارائه‌دهنده بلادرنگ
### نمونه‌های ارائه‌دهندهٔ بلادرنگ
<Tabs>
<Tab title="Google Gemini Live">
پیش‌فرض‌ها: کلید API از `realtime.providers.google.apiKey`،
`GEMINI_API_KEY`، یا `GOOGLE_GENERATIVE_AI_API_KEY`؛ مدل
`gemini-2.5-flash-native-audio-preview-12-2025`؛ صدا `Kore`.
`sessionResumption` و `contextWindowCompression` برای تماس‌های طولانی‌تر و
قابل اتصال مجدد به‌صورت پیش‌فرض روشن هستند. برای تنظیم نوبت‌گیری سریع‌تر روی صدای تلفنی از
`silenceDurationMs`، `startSensitivity`، و
`endSensitivity` استفاده کنید.
```json5
{
@ -279,6 +280,8 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
apiKey: "${GEMINI_API_KEY}",
model: "gemini-2.5-flash-native-audio-preview-12-2025",
voice: "Kore",
silenceDurationMs: 500,
startSensitivity: "high",
},
},
},
@ -313,26 +316,27 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
</Tab>
</Tabs>
برای گزینه‌های صدای بلادرنگ ویژه هر ارائه‌دهنده، [ارائه‌دهنده Google](/fa/providers/google) و
[ارائه‌دهنده OpenAI](/fa/providers/openai) را ببینید.
به [ارائه‌دهنده Google](/fa/providers/google) و
[ارائه‌دهنده OpenAI](/fa/providers/openai) برای گزینه‌های صدای بی‌درنگ
ویژه ارائه‌دهنده مراجعه کنید.
## رونویسی جریانی
`streaming` یک ارائه‌دهنده رونویسی بلادرنگ را برای صدای تماس زنده انتخاب می‌کند.
`streaming` یک ارائه‌دهنده رونویسی بی‌درنگ را برای صدای زنده تماس انتخاب می‌کند.
رفتار فعلی runtime:
رفتار فعلی در زمان اجرا:
- `streaming.provider` اختیاری است. اگر تنظیم نشده باشد، تماس صوتی از اولین ارائه‌دهنده رونویسی بلادرنگ ثبت‌شده استفاده می‌کند.
- ارائه‌دهندگان رونویسی بلادرنگ همراه: Deepgram (`deepgram`)، ElevenLabs (`elevenlabs`)، Mistral (`mistral`)، OpenAI (`openai`) و xAI (`xai`) که توسط Pluginهای ارائه‌دهنده خود ثبت می‌شوند.
- پیکربندی خام متعلق به ارائه‌دهنده زیر `streaming.providers.<providerId>` قرار می‌گیرد.
- پس از اینکه Twilio پیام `start` یک استریم پذیرفته‌شده را می‌فرستد، تماس صوتی بلافاصله استریم را ثبت می‌کند، رسانه ورودی را تا زمان اتصال ارائه‌دهنده از طریق ارائه‌دهنده رونویسی در صف قرار می‌دهد و سلام اولیه را فقط پس از آماده‌شدن رونویسی بلادرنگ شروع می‌کند.
- اگر `streaming.provider` به ارائه‌دهنده‌ای ثبت‌نشده اشاره کند، یا هیچ ارائه‌دهنده‌ای ثبت نشده باشد، تماس صوتی یک هشدار ثبت می‌کند و به‌جای ناموفق‌کردن کل Plugin، استریم رسانه را رد می‌کند.
- `streaming.provider` اختیاری است. اگر تنظیم نشده باشد، Voice Call از نخستین ارائه‌دهنده رونویسی بی‌درنگ ثبت‌شده استفاده می‌کند.
- ارائه‌دهندگان رونویسی بی‌درنگ همراه: Deepgram (`deepgram`)، ElevenLabs (`elevenlabs`)، Mistral (`mistral`)، OpenAI (`openai`) و xAI (`xai`) که توسط Pluginهای ارائه‌دهنده خودشان ثبت می‌شوند.
- پیکربندی خامِ تحت مالکیت ارائه‌دهنده زیر `streaming.providers.<providerId>` قرار دارد.
- پس از اینکه Twilio پیام `start` جریان پذیرفته‌شده را می‌فرستد، Voice Call جریان را بی‌درنگ ثبت می‌کند، رسانه ورودی را تا زمان اتصال ارائه‌دهنده از طریق ارائه‌دهنده رونویسی در صف می‌گذارد، و خوشامدگویی اولیه را فقط پس از آماده شدن رونویسی بی‌درنگ شروع می‌کند.
- اگر `streaming.provider` به ارائه‌دهنده‌ای ثبت‌نشده اشاره کند، یا هیچ ارائه‌دهنده‌ای ثبت نشده باشد، Voice Call یک هشدار ثبت می‌کند و به‌جای شکست دادن کل Plugin، پخش جریانی رسانه را رد می‌کند.
### نمونه‌های ارائه‌دهنده استریم
### نمونه‌های ارائه‌دهنده جریانی
<Tabs>
<Tab title="OpenAI">
پیش‌فرض‌ها: کلید API `streaming.providers.openai.apiKey` یا
پیش‌فرض‌ها: کلید API در `streaming.providers.openai.apiKey` یا
`OPENAI_API_KEY`؛ مدل `gpt-4o-transcribe`؛ `silenceDurationMs: 800`؛
`vadThreshold: 0.5`.
@ -364,7 +368,7 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
</Tab>
<Tab title="xAI">
پیش‌فرض‌ها: کلید API `streaming.providers.xai.apiKey` یا `XAI_API_KEY`؛
پیش‌فرض‌ها: کلید API در `streaming.providers.xai.apiKey` یا `XAI_API_KEY`؛
نقطه پایانی `wss://api.x.ai/v1/stt`؛ کدگذاری `mulaw`؛ نرخ نمونه‌برداری `8000`؛
`endpointingMs: 800`؛ `interimResults: true`.
@ -398,9 +402,9 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
## TTS برای تماس‌ها
تماس صوتی از پیکربندی هسته `messages.tts` برای استریم گفتار در تماس‌ها
استفاده می‌کند. می‌توانید آن را در پیکربندی Plugin با **همان ساختار** بازنویسی کنید —
این پیکربندی با `messages.tts` به‌صورت عمیق ادغام می‌شود.
Voice Call از پیکربندی هسته‌ای `messages.tts` برای گفتار جریانی
در تماس‌ها استفاده می‌کند. می‌توانید آن را در پیکربندی Plugin با
**همان شکل** بازنویسی کنید — این پیکربندی با `messages.tts` به‌صورت عمیق ادغام می‌شود.
```json5
{
@ -418,21 +422,21 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
<Warning>
**گفتار Microsoft برای تماس‌های صوتی نادیده گرفته می‌شود.** صدای تلفنی به PCM نیاز دارد؛
انتقال فعلی Microsoft خروجی PCM تلفنی را در دسترس نمی‌گذارد.
انتقال فعلی Microsoft خروجی PCM تلفنی را ارائه نمی‌کند.
</Warning>
نکات رفتاری:
- کلیدهای قدیمی `tts.<provider>` داخل پیکربندی Plugin (`openai`، `elevenlabs`، `microsoft`، `edge`) توسط `openclaw doctor --fix` ترمیم می‌شوند؛ پیکربندی ثبت‌شده باید از `tts.providers.<provider>` استفاده کند.
- وقتی استریم رسانه Twilio فعال باشد، TTS هسته استفاده می‌شود؛ در غیر این صورت تماس‌ها به صداهای بومی ارائه‌دهنده برمی‌گردند.
- اگر یک استریم رسانه Twilio از قبل فعال باشد، تماس صوتی به TwiML `<Say>` برنمی‌گردد. اگر TTS تلفنی در آن وضعیت در دسترس نباشد، درخواست پخش به‌جای ترکیب دو مسیر پخش ناموفق می‌شود.
- وقتی TTS تلفنی به یک ارائه‌دهنده ثانویه برمی‌گردد، تماس صوتی برای اشکال‌زدایی هشداری همراه با زنجیره ارائه‌دهنده (`from`، `to`، `attempts`) ثبت می‌کند.
- وقتی ورود هم‌زمان Twilio یا برچیدن استریم صف معلق TTS را پاک می‌کند، درخواست‌های پخش صف‌شده به نتیجه می‌رسند به‌جای اینکه تماس‌گیرندگان را در انتظار تکمیل پخش معلق نگه دارند.
- کلیدهای قدیمی `tts.<provider>` داخل پیکربندی Plugin (`openai`، `elevenlabs`، `microsoft`، `edge`) توسط `openclaw doctor --fix` ترمیم می‌شوند؛ پیکربندی commit‌شده باید از `tts.providers.<provider>` استفاده کند.
- وقتی پخش جریانی رسانه Twilio فعال باشد، از TTS هسته استفاده می‌شود؛ در غیر این صورت تماس‌ها به صداهای بومی ارائه‌دهنده برمی‌گردند.
- اگر یک جریان رسانه Twilio از قبل فعال باشد، Voice Call به TwiML `<Say>` برنمی‌گردد. اگر TTS تلفنی در آن وضعیت در دسترس نباشد، درخواست پخش به‌جای ترکیب دو مسیر پخش شکست می‌خورد.
- وقتی TTS تلفنی به یک ارائه‌دهنده ثانویه برمی‌گردد، Voice Call برای اشکال‌زدایی هشداری با زنجیره ارائه‌دهنده (`from`، `to`، `attempts`) ثبت می‌کند.
- وقتی ورود ناگهانی Twilio یا برچیدن جریان، صف TTS معلق را پاک می‌کند، درخواست‌های پخش صف‌شده به نتیجه می‌رسند و تماس‌گیرندگان در انتظار تکمیل پخش معلق نمی‌مانند.
### نمونه‌های TTS
<Tabs>
<Tab title="Core TTS only">
<Tab title="فقط TTS هسته">
```json5
{
messages: {
@ -446,7 +450,7 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
}
```
</Tab>
<Tab title="Override to ElevenLabs (calls only)">
<Tab title="بازنویسی به ElevenLabs (فقط تماس‌ها)">
```json5
{
plugins: {
@ -470,7 +474,7 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
}
```
</Tab>
<Tab title="OpenAI model override (deep-merge)">
<Tab title="بازنویسی مدل OpenAI (ادغام عمیق)">
```json5
{
plugins: {
@ -496,7 +500,7 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
## تماس‌های ورودی
خط‌مشی ورودی به‌طور پیش‌فرض `disabled` است. برای فعال‌کردن تماس‌های ورودی، تنظیم کنید:
سیاست ورودی به‌صورت پیش‌فرض `disabled` است. برای فعال کردن تماس‌های ورودی، تنظیم کنید:
```json5
{
@ -507,31 +511,29 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش
```
<Warning>
`inboundPolicy: "allowlist"` یک غربال‌گری شناسه تماس‌گیرنده با اطمینان پایین است.
`inboundPolicy: "allowlist"` یک غربالگری کم‌اطمینان شناسه تماس‌گیرنده است. این
Plugin مقدار `From` ارائه‌شده توسط ارائه‌دهنده را نرمال‌سازی می‌کند و آن را با
`allowFrom` مقایسه می‌کند. تأیید Webhook تحویل ارائه‌دهنده و
یکپارچگی payload را احراز می‌کند، اما مالکیت شماره تماس‌گیرنده PSTN/VoIP را
**ثابت نمی‌کند**. با `allowFrom` به‌عنوان فیلتر شناسه تماس‌گیرنده رفتار کنید، نه هویت
قوی تماس‌گیرنده.
`allowFrom` مقایسه می‌کند. راستی‌آزمایی Webhook تحویل ارائه‌دهنده و
یکپارچگی بار داده را احراز می‌کند، اما مالکیت شماره تماس‌گیرنده PSTN/VoIP را
**اثبات نمی‌کند**. با `allowFrom` به‌عنوان فیلتر شناسه تماس‌گیرنده برخورد کنید، نه هویت قوی تماس‌گیرنده.
</Warning>
پاسخ‌های خودکار از سامانه عامل استفاده می‌کنند. با `responseModel`،
پاسخ‌های خودکار از سیستم عامل استفاده می‌کنند. با `responseModel`،
`responseSystemPrompt` و `responseTimeoutMs` تنظیم کنید.
### مسیریابی برای هر شماره
### مسیریابی بر اساس شماره
وقتی یک Plugin تماس صوتی تماس‌های چند شماره تلفن را دریافت می‌کند و هر شماره
باید مانند یک خط متفاوت رفتار کند، از `numbers` استفاده کنید. برای مثال، یک
شماره می‌تواند از یک دستیار شخصی غیررسمی استفاده کند در حالی که شماره‌ای دیگر از یک شخصیت
کاری، یک عامل پاسخ متفاوت و یک صدای TTS متفاوت استفاده می‌کند.
وقتی یک Plugin از نوع Voice Call برای چند شماره تلفن تماس دریافت می‌کند و هر شماره باید مثل یک خط متفاوت رفتار کند، از `numbers` استفاده کنید. برای نمونه، یک
شماره می‌تواند از یک دستیار شخصی خودمانی استفاده کند، در حالی که شماره‌ای دیگر از یک
شخصیت تجاری، عامل پاسخ متفاوت، و صدای TTS متفاوت استفاده می‌کند.
مسیرها از شماره `To` شماره‌گیری‌شده و ارائه‌شده توسط ارائه‌دهنده انتخاب می‌شوند. کلیدها باید
شماره‌های E.164 باشند. وقتی تماسی وارد می‌شود، تماس صوتی مسیر مطابق را یک‌بار حل می‌کند،
مسیر مطابق را در رکورد تماس ذخیره می‌کند و همان پیکربندی مؤثر را برای
سلام، مسیر پاسخ خودکار کلاسیک، مسیر مشاوره بلادرنگ و پخش TTS
بازاستفاده می‌کند. اگر هیچ مسیری مطابق نباشد، پیکربندی سراسری تماس صوتی استفاده می‌شود.
مسیرها از شماره `To` شماره‌گیری‌شده ارائه‌شده توسط ارائه‌دهنده انتخاب می‌شوند. کلیدها باید
شماره‌های E.164 باشند. وقتی تماسی می‌رسد، Voice Call مسیر مطابق را یک بار حل می‌کند،
مسیر مطابق را روی رکورد تماس ذخیره می‌کند، و همان پیکربندی مؤثر را
برای خوشامدگویی، مسیر کلاسیک پاسخ خودکار، مسیر مشاوره بی‌درنگ، و پخش
TTS دوباره استفاده می‌کند. اگر هیچ مسیری مطابق نباشد، از پیکربندی سراسری Voice Call استفاده می‌شود.
تماس‌های خروجی از `numbers` استفاده نمی‌کنند؛ هنگام شروع تماس، مقصد خروجی، پیام و
نشست را صریحاً ارسال کنید.
نشست را به‌صراحت پاس دهید.
بازنویسی‌های مسیر در حال حاضر پشتیبانی می‌کنند از:
@ -542,7 +544,7 @@ Plugin مقدار `From` ارائه‌شده توسط ارائه‌دهنده ر
- `responseSystemPrompt`
- `responseTimeoutMs`
مقدار مسیر `tts` روی پیکربندی سراسری `tts` تماس صوتی به‌صورت عمیق ادغام می‌شود، بنابراین
مقدار مسیر `tts` روی پیکربندی سراسری `tts` در Voice Call به‌صورت عمیق ادغام می‌شود، بنابراین
معمولاً می‌توانید فقط صدای ارائه‌دهنده را بازنویسی کنید:
```json5
@ -571,51 +573,51 @@ Plugin مقدار `From` ارائه‌شده توسط ارائه‌دهنده ر
### قرارداد خروجی گفتاری
برای پاسخ‌های خودکار، تماس صوتی یک قرارداد سخت‌گیرانه خروجی گفتاری را به
پرامپت سیستم اضافه می‌کند:
برای پاسخ‌های خودکار، Voice Call یک قرارداد سخت‌گیرانه خروجی گفتاری را به
اعلان سیستم اضافه می‌کند:
```text
{"spoken":"..."}
```
تماس صوتی متن گفتار را به‌صورت تدافعی استخراج می‌کند:
Voice Call متن گفتار را دفاعی استخراج می‌کند:
- payloadهایی را که به‌عنوان محتوای استدلال/خطا علامت‌گذاری شده‌اند نادیده می‌گیرد.
- JSON مستقیم، JSON حصارگذاری‌شده یا کلیدهای درون‌خطی `"spoken"` را تجزیه می‌کند.
- به متن ساده برمی‌گردد و پاراگراف‌های آغازین محتملِ برنامه‌ریزی/فرا را حذف می‌کند.
- بارهای داده‌ای را که به‌عنوان محتوای استدلال/خطا علامت‌گذاری شده‌اند نادیده می‌گیرد.
- JSON مستقیم، JSON حصارشده، یا کلیدهای درون‌خطی `"spoken"` را تجزیه می‌کند.
- به متن ساده برمی‌گردد و پاراگراف‌های ابتدایی احتمالی برنامه‌ریزی/فراداده را حذف می‌کند.
این کار پخش گفتاری را روی متن روبه‌روی تماس‌گیرنده متمرکز نگه می‌دارد و از
نشت متن برنامه‌ریزی به صدا جلوگیری می‌کند.
### رفتار شروع مکالمه
برای تماس‌های خروجی `conversation`، مدیریت پیام اول به وضعیت پخش زنده
وابسته است:
برای تماس‌های خروجی `conversation`، مدیریت پیام نخست به وضعیت زنده
پخش گره خورده است:
- پاک‌سازی صف ورود هم‌زمان و پاسخ خودکار فقط زمانی سرکوب می‌شوند که سلام اولیه فعالانه در حال صحبت باشد.
- اگر پخش اولیه ناموفق شود، تماس به `listening` برمی‌گردد و پیام اولیه برای تلاش دوباره در صف می‌ماند.
- پخش اولیه برای استریم Twilio هنگام اتصال استریم و بدون تأخیر اضافی شروع می‌شود.
- ورود هم‌زمان پخش فعال را لغو می‌کند و ورودی‌های Twilio TTS صف‌شده اما هنوز پخش‌نشده را پاک می‌کند. ورودی‌های پاک‌شده به‌عنوان ردشده resolve می‌شوند، بنابراین منطق پاسخ بعدی می‌تواند بدون انتظار برای صدایی که هرگز پخش نخواهد شد ادامه دهد.
- مکالمات صوتی بلادرنگ از نوبت آغازین خود استریم بلادرنگ استفاده می‌کنند. تماس صوتی برای آن پیام اولیه، به‌روزرسانی قدیمی TwiML `<Say>` ارسال **نمی‌کند**، بنابراین نشست‌های خروجی `<Connect><Stream>` متصل باقی می‌مانند.
- پاک‌سازی صف ورود ناگهانی و پاسخ خودکار فقط زمانی سرکوب می‌شوند که خوشامدگویی اولیه به‌صورت فعال در حال پخش باشد.
- اگر پخش اولیه شکست بخورد، تماس به `listening` برمی‌گردد و پیام اولیه برای تلاش دوباره در صف می‌ماند.
- پخش اولیه برای جریان Twilio بدون تأخیر اضافه هنگام اتصال جریان شروع می‌شود.
- ورود ناگهانی پخش فعال را لغو می‌کند و ورودی‌های TTS در Twilio را که صف شده‌اند اما هنوز پخش نشده‌اند پاک می‌کند. ورودی‌های پاک‌شده به‌عنوان ردشده حل می‌شوند، بنابراین منطق پاسخ بعدی می‌تواند بدون انتظار برای صدایی که هرگز پخش نخواهد شد ادامه پیدا کند.
- مکالمه‌های صوتی بی‌درنگ از نوبت آغازین خودِ جریان بی‌درنگ استفاده می‌کنند. Voice Call برای آن پیام اولیه یک به‌روزرسانی قدیمی TwiML با `<Say>` ارسال **نمی‌کند**، بنابراین نشست‌های خروجی `<Connect><Stream>` متصل باقی می‌مانند.
### مهلت قطع اتصال استریم Twilio
### مهلت قطع اتصال جریان Twilio
وقتی یک استریم رسانه Twilio قطع می‌شود، تماس صوتی پیش از
پایان خودکار تماس **2000 ms** منتظر می‌ماند:
وقتی جریان رسانه Twilio قطع می‌شود، Voice Call پیش از
پایان‌دهی خودکار تماس **2000 ms** صبر می‌کند:
- اگر استریم در آن بازه دوباره وصل شود، پایان خودکار لغو می‌شود.
- اگر پس از دوره مهلت هیچ استریمی دوباره ثبت نشود، تماس پایان داده می‌شود تا از گیرکردن تماس‌های فعال جلوگیری شود.
- اگر جریان در طول آن بازه دوباره متصل شود، پایان خودکار لغو می‌شود.
- اگر پس از دوره مهلت هیچ جریانی دوباره ثبت نشود، تماس پایان می‌یابد تا از تماس‌های فعال گیرکرده جلوگیری شود.
## پاک‌کننده تماس کهنه
## پاک‌سازی تماس‌های کهنه
از `staleCallReaperSeconds` برای پایان‌دادن به تماس‌هایی استفاده کنید که هرگز یک
Webhook پایانی دریافت نمی‌کنند (برای مثال، تماس‌های حالت اعلان که هرگز کامل نمی‌شوند). مقدار پیش‌فرض
از `staleCallReaperSeconds` برای پایان دادن به تماس‌هایی استفاده کنید که هرگز Webhook پایانی
دریافت نمی‌کنند (برای مثال، تماس‌های حالت اعلان که هرگز کامل نمی‌شوند). مقدار پیش‌فرض
`0` است (غیرفعال).
بازه‌های پیشنهادی:
- **تولید:** `120` تا `300` ثانیه برای جریان‌های سبک اعلان.
- این مقدار را **بالاتر از `maxDurationSeconds`** نگه دارید تا تماس‌های عادی بتوانند تمام شوند. نقطه شروع خوب `maxDurationSeconds + 30–60` ثانیه است.
- این مقدار را **بالاتر از `maxDurationSeconds`** نگه دارید تا تماس‌های عادی بتوانند تمام شوند. نقطه شروع مناسب `maxDurationSeconds + 30–60` ثانیه است.
```json5
{
@ -634,28 +636,28 @@ Webhook پایانی دریافت نمی‌کنند (برای مثال، تما
## امنیت Webhook
وقتی یک پراکسی یا تونل جلوی Gateway قرار دارد، Plugin
نشانی URL عمومی را برای تأیید امضا بازسازی می‌کند. این گزینه‌ها
کنترل می‌کنند کدام سربرگ‌های فورواردشده قابل اعتماد باشند:
وقتی یک پروکسی یا تونل جلوی Gateway قرار می‌گیرد، این Plugin
URL عمومی را برای راستی‌آزمایی امضا بازسازی می‌کند. این گزینه‌ها
کنترل می‌کنند که کدام سرآیندهای فورواردشده قابل اعتماد هستند:
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
میزبان‌های allowlist از سربرگ‌های فورواردینگ.
میزبان‌های فهرست مجاز از سرآیندهای فوروارد را مجاز کنید.
</ParamField>
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
اعتماد به سربرگ‌های فورواردشده بدون allowlist.
به سرآیندهای فورواردشده بدون فهرست مجاز اعتماد کنید.
</ParamField>
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
فقط زمانی به سربرگ‌های فورواردشده اعتماد کنید که IP راه‌دور درخواست با فهرست مطابق باشد.
فقط وقتی IP راه‌دور درخواست با فهرست مطابق باشد به سرآیندهای فورواردشده اعتماد کنید.
</ParamField>
محافظت‌های اضافی:
- **محافظت در برابر بازپخش** Webhook برای Twilio و Plivo فعال است. درخواست‌های معتبر Webhook که بازپخش شده‌اند تأیید می‌شوند اما برای اثرات جانبی رد می‌شوند.
- نوبت‌های مکالمه Twilio در callbackهای `<Gather>` شامل یک توکن برای هر نوبت هستند، بنابراین callbackهای گفتار کهنه/بازپخش‌شده نمی‌توانند یک نوبت transcript معلق جدیدتر را برآورده کنند.
- درخواست‌های Webhook احرازنشده، زمانی که سربرگ‌های امضای الزامی ارائه‌دهنده وجود نداشته باشند، پیش از خواندن بدنه رد می‌شوند.
- Webhook تماس صوتی از پروفایل مشترک بدنه پیش‌از‌احراز (64 KB / 5 ثانیه) به‌همراه سقف درحال‌پرواز برای هر IP پیش از تأیید امضا استفاده می‌کند.
- **محافظت در برابر بازپخش** Webhook برای Twilio و Plivo فعال است. درخواست‌های Webhook معتبرِ بازپخش‌شده تأیید می‌شوند اما برای اثرات جانبی رد می‌شوند.
- نوبت‌های مکالمه Twilio شامل یک توکن ویژه هر نوبت در callbackهای `<Gather>` هستند، بنابراین callbackهای گفتار کهنه/بازپخش‌شده نمی‌توانند یک نوبت رونوشت معلق جدیدتر را برآورده کنند.
- درخواست‌های Webhook احرازنشده وقتی سرآیندهای امضای موردنیاز ارائه‌دهنده وجود نداشته باشند، پیش از خواندن بدنه رد می‌شوند.
- Webhook مربوط به voice-call از پروفایل بدنه پیشااحراز مشترک (64 KB / 5 ثانیه) به‌همراه سقف درحال‌انجام بر اساس هر IP پیش از راستی‌آزمایی امضا استفاده می‌کند.
نمونه با یک میزبان عمومی پایدار:
نمونه با میزبان عمومی پایدار:
```json5
{
@ -689,17 +691,11 @@ openclaw voicecall latency # summarize turn latency from lo
openclaw voicecall expose --mode funnel
```
وقتی Gateway از قبل در حال اجراست، فرمان‌های عملیاتی `voicecall` به
runtime تماس صوتی متعلق به Gateway واگذار می‌شوند تا CLI یک سرور
Webhook دوم را bind نکند. اگر هیچ Gatewayی در دسترس نباشد، فرمان‌ها به یک
runtime مستقل CLI برمی‌گردند.
وقتی Gateway از قبل در حال اجراست، فرمان‌های عملیاتی `voicecall` به runtime تماس صوتی تحت مالکیت Gateway واگذار می‌شوند تا CLI یک سرور webhook دوم را bind نکند. اگر هیچ Gatewayای در دسترس نباشد، فرمان‌ها به runtime مستقل CLI برمی‌گردند.
`latency`، `calls.jsonl` را از مسیر پیش‌فرض ذخیره‌سازی تماس صوتی می‌خواند.
از `--file <path>` برای اشاره به یک گزارش متفاوت و از `--last <n>` برای محدود کردن
تحلیل به آخرین N رکورد استفاده کنید (پیش‌فرض 200). خروجی شامل p50/p90/p99
برای تأخیر نوبت و زمان‌های انتظار شنیدن است.
`latency` فایل `calls.jsonl` را از مسیر پیش‌فرض ذخیره‌سازی تماس صوتی می‌خواند. از `--file <path>` برای اشاره به یک log دیگر و از `--last <n>` برای محدود کردن تحلیل به آخرین N رکورد استفاده کنید (پیش‌فرض 200). خروجی شامل p50/p90/p99 برای تأخیر نوبت و زمان‌های انتظار برای گوش‌دادن است.
## ابزار عامل
## ابزار agent
نام ابزار: `voice_call`.
@ -712,11 +708,11 @@ runtime مستقل CLI برمی‌گردند.
| `end_call` | `callId` |
| `get_status` | `callId` |
این مخزن یک سند skill متناظر را در `skills/voice-call/SKILL.md` ارائه می‌کند.
این repo یک سند skill متناظر را در `skills/voice-call/SKILL.md` ارائه می‌کند.
## RPC Gateway
## RPC مربوط به Gateway
| روش | آرگومان‌ها |
| متد | آرگومان‌ها |
| -------------------- | ------------------------------------------ |
| `voicecall.initiate` | `to?`, `message`, `mode?`, `dtmfSequence?` |
| `voicecall.continue` | `callId`, `message` |
@ -725,13 +721,11 @@ runtime مستقل CLI برمی‌گردند.
| `voicecall.end` | `callId` |
| `voicecall.status` | `callId` |
`dtmfSequence` فقط با `mode: "conversation"` معتبر است. تماس‌های حالت اعلان
اگر پس از اتصال به ارقام نیاز دارند، باید بعد از ایجاد تماس از `voicecall.dtmf`
استفاده کنند.
`dtmfSequence` فقط با `mode: "conversation"` معتبر است. تماس‌های حالت notify، اگر پس از برقراری اتصال به رقم‌ها نیاز دارند، باید بعد از اینکه تماس ایجاد شد از `voicecall.dtmf` استفاده کنند.
## عیب‌یابی
### راه‌اندازی در مواجهه با Webhook ناموفق می‌شود
### راه‌اندازی در معرض‌گذاری webhook ناموفق است
راه‌اندازی را از همان محیطی اجرا کنید که Gateway را اجرا می‌کند:
@ -740,20 +734,11 @@ openclaw voicecall setup
openclaw voicecall setup --json
```
برای `twilio`، `telnyx` و `plivo`، `webhook-exposure` باید سبز باشد. یک
`publicUrl` پیکربندی‌شده همچنان وقتی به فضای شبکه محلی یا خصوصی اشاره کند
ناموفق می‌شود، چون اپراتور نمی‌تواند به آن نشانی‌ها بازتماس انجام دهد. از
`localhost`، `127.0.0.1`، `0.0.0.0`، `10.x`، `172.16.x`-`172.31.x`،
`192.168.x`، `169.254.x`، `fc00::/7`، یا `fd00::/8` به عنوان `publicUrl`
استفاده نکنید.
برای `twilio`، `telnyx`، و `plivo`، `webhook-exposure` باید سبز باشد. یک `publicUrl` پیکربندی‌شده همچنان وقتی به فضای شبکه محلی یا خصوصی اشاره کند شکست می‌خورد، چون carrier نمی‌تواند به آن آدرس‌ها callback کند. از `localhost`، `127.0.0.1`، `0.0.0.0`، `10.x`، `172.16.x`-`172.31.x`، `192.168.x`، `169.254.x`، `fc00::/7`، یا `fd00::/8` به‌عنوان `publicUrl` استفاده نکنید.
تماس‌های خروجی حالت اعلان Twilio، TwiML اولیه `<Say>` خود را مستقیماً در
درخواست ایجاد تماس ارسال می‌کنند، بنابراین نخستین پیام گفتاری به دریافت TwiML
Webhook توسط Twilio وابسته نیست. Webhook عمومی همچنان برای callbackهای وضعیت،
تماس‌های مکالمه، DTMF پیش از اتصال، جریان‌های بلادرنگ و کنترل تماس پس از اتصال
لازم است.
تماس‌های outbound در حالت notify برای Twilio، TwiML اولیه‌ی `<Say>` خود را مستقیماً در درخواست create-call ارسال می‌کنند، بنابراین نخستین پیام گفتاری به دریافت TwiML مربوط به webhook توسط Twilio وابسته نیست. یک webhook عمومی همچنان برای callbackهای وضعیت، تماس‌های مکالمه، DTMF پیش از اتصال، streamهای realtime، و کنترل تماس پس از اتصال لازم است.
از یک مسیر مواجهه عمومی استفاده کنید:
از یک مسیر در معرض‌گذاری عمومی استفاده کنید:
```json5
{
@ -773,38 +758,34 @@ Webhook توسط Twilio وابسته نیست. Webhook عمومی همچنان
}
```
پس از تغییر پیکربندی، Gateway را بازراه‌اندازی یا بازبارگذاری کنید، سپس اجرا کنید:
پس از تغییر config، Gateway را restart یا reload کنید، سپس اجرا کنید:
```bash
openclaw voicecall setup
openclaw voicecall smoke
```
`voicecall smoke` یک اجرای آزمایشی خشک است مگر اینکه `--yes` را بدهید.
`voicecall smoke` یک dry run است مگر اینکه `--yes` را پاس بدهید.
### اعتبارنامه‌های ارائه‌دهنده ناموفق می‌شوند
### credentialهای provider ناموفق هستند
ارائه‌دهنده انتخاب‌شده و فیلدهای اعتبارنامه لازم را بررسی کنید:
provider انتخاب‌شده و fieldهای credential لازم را بررسی کنید:
- Twilio: `twilio.accountSid`، `twilio.authToken` و `fromNumber`، یا
`TWILIO_ACCOUNT_SID`، `TWILIO_AUTH_TOKEN` و `TWILIO_FROM_NUMBER`.
- Telnyx: `telnyx.apiKey`، `telnyx.connectionId`، `telnyx.publicKey` و
`fromNumber`.
- Plivo: `plivo.authId`، `plivo.authToken` و `fromNumber`.
- Twilio: `twilio.accountSid`، `twilio.authToken`، و `fromNumber`، یا `TWILIO_ACCOUNT_SID`، `TWILIO_AUTH_TOKEN`، و `TWILIO_FROM_NUMBER`.
- Telnyx: `telnyx.apiKey`، `telnyx.connectionId`، `telnyx.publicKey`، و `fromNumber`.
- Plivo: `plivo.authId`، `plivo.authToken`، و `fromNumber`.
اعتبارنامه‌ها باید روی میزبان Gateway وجود داشته باشند. ویرایش یک پروفایل پوسته
محلی تا زمانی که Gateway محیط خود را بازراه‌اندازی یا بازبارگذاری نکند، روی
Gateway در حال اجرا اثر نمی‌گذارد.
credentialها باید روی میزبان Gateway وجود داشته باشند. ویرایش یک shell profile محلی تا زمانی که Gateway دوباره راه‌اندازی یا محیطش reload نشود، روی Gatewayای که از قبل در حال اجراست اثری ندارد.
### تماس‌ها شروع می‌شوند اما Webhookهای ارائه‌دهنده نمی‌رسند
### تماس‌ها شروع می‌شوند اما webhookهای provider نمی‌رسند
تأیید کنید کنسول ارائه‌دهنده دقیقاً به URL عمومی Webhook اشاره می‌کند:
تأیید کنید console مربوط به provider به URL دقیق webhook عمومی اشاره می‌کند:
```text
https://voice.example.com/voice/webhook
```
سپس وضعیت زمان اجرا را بررسی کنید:
سپس وضعیت runtime را بررسی کنید:
```bash
openclaw voicecall status --call-id <id>
@ -815,80 +796,64 @@ openclaw logs --follow
علت‌های رایج:
- `publicUrl` به مسیری متفاوت از `serve.path` اشاره می‌کند.
- URL تونل پس از شروع Gateway تغییر کرده است.
- یک پراکسی درخواست را ارسال می‌کند اما سرآیندهای host/proto را حذف یا بازنویسی می‌کند.
- دیوار آتش یا DNS نام میزبان عمومی را به جایی غیر از Gateway مسیریابی می‌کند.
- Gateway بدون فعال بودن Plugin تماس صوتی بازراه‌اندازی شده است.
- URL مربوط به tunnel پس از شروع Gateway تغییر کرده است.
- یک proxy درخواست را forward می‌کند اما headerهای host/proto را حذف یا بازنویسی می‌کند.
- firewall یا DNS نام میزبان عمومی را به جایی غیر از Gateway route می‌کند.
- Gateway بدون فعال بودن Plugin تماس صوتی restart شده است.
وقتی یک پراکسی معکوس یا تونل جلوی Gateway قرار دارد، `webhookSecurity.allowedHosts`
را روی نام میزبان عمومی تنظیم کنید، یا برای نشانی شناخته‌شده پراکسی از
`webhookSecurity.trustedProxyIPs` استفاده کنید. فقط زمانی از
`webhookSecurity.trustForwardingHeaders` استفاده کنید که مرز پراکسی تحت کنترل
شماست.
وقتی یک reverse proxy یا tunnel جلوی Gateway قرار دارد، `webhookSecurity.allowedHosts` را روی hostname عمومی تنظیم کنید، یا برای یک آدرس proxy شناخته‌شده از `webhookSecurity.trustedProxyIPs` استفاده کنید. فقط زمانی از `webhookSecurity.trustForwardingHeaders` استفاده کنید که مرز proxy تحت کنترل شماست.
### راستی‌آزمایی امضا ناموفق می‌شود
### اعتبارسنجی امضا ناموفق است
امضاهای ارائه‌دهنده در برابر URL عمومی‌ای بررسی می‌شوند که OpenClaw از درخواست
ورودی بازسازی می‌کند. اگر امضاها ناموفق شوند:
امضاهای provider در برابر URL عمومی‌ای بررسی می‌شوند که OpenClaw از درخواست ورودی بازسازی می‌کند. اگر امضاها ناموفق باشند:
- تأیید کنید URL Webhook ارائه‌دهنده دقیقاً با `publicUrl` مطابق است، از جمله
scheme، host و path.
- برای URLهای سطح رایگان ngrok، وقتی نام میزبان تونل تغییر می‌کند `publicUrl` را به‌روزرسانی کنید.
- مطمئن شوید پراکسی سرآیندهای اصلی host و proto را حفظ می‌کند، یا
`webhookSecurity.allowedHosts` را پیکربندی کنید.
- خارج از آزمون محلی، `skipSignatureVerification` را فعال نکنید.
- تأیید کنید URL مربوط به webhook provider دقیقاً با `publicUrl` مطابقت دارد، شامل scheme، host، و path.
- برای URLهای سطح رایگان ngrok، وقتی hostname مربوط به tunnel تغییر می‌کند `publicUrl` را به‌روزرسانی کنید.
- مطمئن شوید proxy headerهای host و proto اصلی را حفظ می‌کند، یا `webhookSecurity.allowedHosts` را پیکربندی کنید.
- خارج از تست محلی، `skipSignatureVerification` را فعال نکنید.
### اتصال‌های Google Meet با Twilio ناموفق می‌شوند
### اتصال‌های Google Meet با Twilio ناموفق هستند
Google Meet از این Plugin برای اتصال‌های شماره‌گیری ورودی Twilio استفاده می‌کند. ابتدا Voice Call را تأیید کنید:
Google Meet از این Plugin برای اتصال‌های dial-in با Twilio استفاده می‌کند. ابتدا Voice Call را تأیید کنید:
```bash
openclaw voicecall setup
openclaw voicecall smoke --to "+15555550123"
```
سپس انتقال Google Meet را صراحتاً تأیید کنید:
سپس transport مربوط به Google Meet را صراحتاً تأیید کنید:
```bash
openclaw googlemeet setup --transport twilio
```
اگر Voice Call سبز است اما شرکت‌کننده Meet هرگز وصل نمی‌شود، شماره شماره‌گیری
ورودی Meet، PIN و `--dtmf-sequence` را بررسی کنید. تماس تلفنی می‌تواند سالم باشد
در حالی که جلسه یک دنباله DTMF نادرست را رد یا نادیده می‌گیرد.
اگر Voice Call سبز است اما شرکت‌کننده‌ی Meet هرگز ملحق نمی‌شود، شماره dial-in، PIN، و `--dtmf-sequence` مربوط به Meet را بررسی کنید. تماس تلفنی می‌تواند سالم باشد در حالی که meeting یک توالی DTMF نادرست را رد یا نادیده می‌گیرد.
Google Meet دنباله DTMF و متن مقدمه Meet را به `voicecall.start` می‌فرستد.
برای تماس‌های Twilio، Voice Call ابتدا TwiML مربوط به DTMF را سرو می‌کند، سپس
به Webhook برمی‌گرداند، و بعد جریان رسانه بلادرنگ را باز می‌کند تا مقدمه
ذخیره‌شده پس از پیوستن شرکت‌کننده تلفنی به جلسه تولید شود.
Google Meet توالی DTMF مربوط به Meet و متن intro را به `voicecall.start` پاس می‌دهد. برای تماس‌های Twilio، Voice Call ابتدا TwiML مربوط به DTMF را serve می‌کند، دوباره به webhook redirect می‌کند، سپس stream رسانه‌ی realtime را باز می‌کند تا intro ذخیره‌شده پس از ملحق شدن شرکت‌کننده‌ی تلفنی به meeting تولید شود.
برای ردگیری زنده مرحله از `openclaw logs --follow` استفاده کنید. یک اتصال سالم
Twilio Meet این ترتیب را ثبت می‌کند:
برای trace زنده‌ی phase از `openclaw logs --follow` استفاده کنید. یک اتصال سالم Twilio Meet این ترتیب را log می‌کند:
- Google Meet اتصال Twilio را به Voice Call واگذار می‌کند.
- Voice Call، TwiML مربوط به DTMF پیش از اتصال را ذخیره می‌کند.
- TwiML اولیه Twilio پیش از پردازش بلادرنگ مصرف و سرو می‌شود.
- Voice Call، TwiML بلادرنگ را برای تماس Twilio سرو می‌کند.
- پل بلادرنگ با سلام اولیه در صف شروع می‌شود.
- Voice Call توالی DTMF TwiML پیش از اتصال را ذخیره می‌کند.
- TwiML اولیه‌ی Twilio مصرف و پیش از پردازش realtime serve می‌شود.
- Voice Call برای تماس Twilio، TwiML مربوط به realtime را serve می‌کند.
- bridge مربوط به realtime با greeting اولیه در queue شروع می‌شود.
`openclaw voicecall tail` همچنان رکوردهای تماس پایدارشده را نشان می‌دهد؛ برای
وضعیت تماس و رونوشت‌ها مفید است، اما هر گذار Webhook/بلادرنگ در آن ظاهر نمی‌شود.
`openclaw voicecall tail` همچنان رکوردهای تماس پایدارشده را نشان می‌دهد؛ برای وضعیت تماس و transcriptها مفید است، اما هر گذار webhook/realtime در آن ظاهر نمی‌شود.
### تماس بلادرنگ گفتار ندارد
### تماس realtime گفتار ندارد
تأیید کنید فقط یک حالت صوتی فعال است. `realtime.enabled` و
`streaming.enabled` نمی‌توانند هر دو true باشند.
تأیید کنید فقط یک حالت audio فعال است. `realtime.enabled` و `streaming.enabled` نمی‌توانند هر دو true باشند.
برای تماس‌های بلادرنگ Twilio، این موارد را نیز تأیید کنید:
برای تماس‌های realtime Twilio، همچنین بررسی کنید:
- یک Plugin ارائه‌دهنده بلادرنگ بارگذاری و ثبت شده است.
- `realtime.provider` تنظیم نشده یا نام یک ارائه‌دهنده ثبت‌شده را دارد.
- کلید API ارائه‌دهنده برای فرایند Gateway در دسترس است.
- `openclaw logs --follow` نشان می‌دهد TwiML بلادرنگ سرو شده، پل بلادرنگ
شروع شده، و سلام اولیه در صف قرار گرفته است.
- یک Plugin مربوط به provider realtime load و register شده است.
- `realtime.provider` unset است یا نام یک provider ثبت‌شده را دارد.
- کلید API مربوط به provider در دسترس فرایند Gateway است.
- `openclaw logs --follow` نشان می‌دهد TwiML مربوط به realtime serve شده، bridge مربوط به realtime شروع شده، و greeting اولیه در queue قرار گرفته است.
## مرتبط
- [حالت گفت‌وگو](/fa/nodes/talk)
- [متن به گفتار](/fa/tools/tts)
- [بیدارسازی صوتی](/fa/nodes/voicewake)
- [تبدیل متن به گفتار](/fa/tools/tts)
- [بیدارباش صوتی](/fa/nodes/voicewake)

61
docs/fa/providers/elevenlabs.md
View File

@ -1,27 +1,27 @@
---
read_when:
- می‌خواهید تبدیل متن به گفتار ElevenLabs را در OpenClaw داشته باشید
- به تبدیل گفتار به متن ElevenLabs Scribe برای پیوست‌های صوتی نیاز دارید
- شما رونویسی بلادرنگ ElevenLabs را برای تماس صوتی می‌خواهید
summary: از گفتار ElevenLabs، STT Scribe و رونویسی بلادرنگ با OpenClaw استفاده کنید
- برای پیوست‌های صوتی، تبدیل گفتار به متن ElevenLabs Scribe را می‌خواهید
- شما رونویسی بی‌درنگ ElevenLabs را برای تماس صوتی یا Google Meet می‌خواهید
summary: از گفتار ElevenLabs، Scribe STT و رونویسی بلادرنگ با OpenClaw استفاده کنید
title: ElevenLabs
x-i18n:
generated_at: "2026-04-29T23:24:53Z"
generated_at: "2026-05-04T07:06:58Z"
model: gpt-5.5
provider: openai
source_hash: 1f858a344228c6355cd5fdc3775cddac39e0075f2e9fcf7683271f11be03a31a
source_hash: 4c880bf9dcab01ef70779c74576c70ea5d0203b96b5f739291842fafcb4bdb4b
source_path: providers/elevenlabs.md
workflow: 16
---
OpenClaw از ElevenLabs برای تبدیل متن به گفتار، تبدیل گفتار به متن دسته‌ای با Scribe
v2، و STT جریانی Voice Call با Scribe v2 Realtime استفاده می‌کند.
v2، و STT جریانی با Scribe v2 Realtime استفاده می‌کند.
| قابلیت | سطح OpenClaw | پیش‌فرض |
| ------------------------ | --------------------------------------------- | ------------------------ |
| تبدیل متن به گفتار | `messages.tts` / `talk` | `eleven_multilingual_v2` |
| تبدیل گفتار به متن دسته‌ای | `tools.media.audio` | `scribe_v2` |
| تبدیل گفتار به متن جریانی | Voice Call `streaming.provider: "elevenlabs"` | `scribe_v2_realtime` |
| قابلیت | سطح OpenClaw | پیش‌فرض |
| ---------------------- | -------------------------------------------------------------------- | ----------------------- |
| تبدیل متن به گفتار | `messages.tts` / `talk` | `eleven_multilingual_v2` |
| تبدیل گفتار به متن دسته‌ای | `tools.media.audio` | `scribe_v2` |
| تبدیل گفتار به متن جریانی | پخش جریانی Voice Call یا Google Meet `realtime.transcriptionProvider` | `scribe_v2_realtime` |
## احراز هویت
@ -70,22 +70,23 @@ export ELEVENLABS_API_KEY="..."
}
```
OpenClaw صدای multipart را به `/v1/speech-to-text` در ElevenLabs با
`model_id: "scribe_v2"` ارسال می‌کند. در صورت وجود، راهنمایی‌های زبان به `language_code` نگاشت می‌شوند.
OpenClaw صدای چندبخشی را با `model_id: "scribe_v2"` به
`/v1/speech-to-text` در ElevenLabs ارسال می‌کند. در صورت وجود، راهنمایی‌های زبان به
`language_code` نگاشت می‌شوند.
## STT جریانی Voice Call
## STT جریانی
Plugin همراه `elevenlabs`، Scribe v2 Realtime را برای رونویسی جریانی Voice Call
ثبت می‌کند.
Plugin همراه `elevenlabs`، Scribe v2 Realtime را برای رونویسی جریانی در حالت عامل Voice Call و
Google Meet ثبت می‌کند.
| تنظیم | مسیر پیکربندی | پیش‌فرض |
| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
| کلید API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | به `ELEVENLABS_API_KEY` / `XI_API_KEY` بازمی‌گردد |
| مدل | `...elevenlabs.modelId` | `scribe_v2_realtime` |
| قالب صوتی | `...elevenlabs.audioFormat` | `ulaw_8000` |
| نرخ نمونه‌برداری | `...elevenlabs.sampleRate` | `8000` |
| راهبرد commit | `...elevenlabs.commitStrategy` | `vad` |
| زبان | `...elevenlabs.languageCode` | (تنظیم‌نشده) |
| تنظیم | مسیر پیکربندی | پیش‌فرض |
| --------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
| کلید API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | به `ELEVENLABS_API_KEY` / `XI_API_KEY` بازمی‌گردد |
| مدل | `...elevenlabs.modelId` | `scribe_v2_realtime` |
| قالب صوتی | `...elevenlabs.audioFormat` | `ulaw_8000` |
| نرخ نمونه‌برداری | `...elevenlabs.sampleRate` | `8000` |
| راهبرد ثبت | `...elevenlabs.commitStrategy` | `vad` |
| زبان | `...elevenlabs.languageCode` | (تنظیم‌نشده) |
```json5
{
@ -113,12 +114,18 @@ Plugin همراه `elevenlabs`، Scribe v2 Realtime را برای رونویسی
```
<Note>
Voice Call رسانه Twilio را به‌صورت G.711 u-law با فرکانس ۸ kHz دریافت می‌کند. provider بلادرنگ ElevenLabs
به‌صورت پیش‌فرض از `ulaw_8000` استفاده می‌کند، بنابراین فریم‌های تلفنی می‌توانند بدون
تبدیل کدگذاری ارسال شوند.
Voice Call رسانه Twilio را به‌صورت G.711 u-law با نرخ ۸ kHz دریافت می‌کند. ارائه‌دهنده بلادرنگ ElevenLabs
به‌طور پیش‌فرض از `ulaw_8000` استفاده می‌کند، بنابراین فریم‌های تلفنی می‌توانند بدون
تبدیل کدینگ بازفرستاده شوند.
</Note>
برای حالت عامل Google Meet، مقدار
`plugins.entries.google-meet.config.realtime.transcriptionProvider` را روی
`"elevenlabs"` تنظیم کنید و همان بلوک ارائه‌دهنده را زیر
`plugins.entries.google-meet.config.realtime.providers.elevenlabs` پیکربندی کنید.
## مرتبط
- [تبدیل متن به گفتار](/fa/tools/tts)
- [Google Meet](/fa/plugins/google-meet)
- [انتخاب مدل](/fa/concepts/model-providers)

206
docs/fa/providers/google.md
View File

@ -2,28 +2,28 @@
read_when:
- می‌خواهید از مدل‌های Google Gemini با OpenClaw استفاده کنید
- به کلید API یا جریان احراز هویت OAuth نیاز دارید
summary: راه‌اندازی Google Gemini (کلید API + OAuth، تولید تصویر، درک رسانه، TTS، جست‌وجوی وب)
summary: راه‌اندازی Google Gemini (کلید API + OAuth، تولید تصویر، درک رسانه، TTS، جستجوی وب)
title: Google (Gemini)
x-i18n:
generated_at: "2026-05-02T11:59:14Z"
generated_at: "2026-05-04T07:07:27Z"
model: gpt-5.5
provider: openai
source_hash: 14605b88f0d1d7e01796d429113a73b2b52a48fde6443565dcb3db47653be5e7
source_hash: 3e45627f5d5cd57e858c7590a90435b7fc0e9381509f3312a16fc9e9a4cbd908
source_path: providers/google.md
workflow: 16
---
Plugin Google از طریق Google AI Studio به مدل‌های Gemini دسترسی می‌دهد، به‌علاوه
تولید تصویر، فهم رسانه (تصویر/صوت/ویدیو)، تبدیل متن به گفتار، و جست‌وجوی وب از طریق
Plugin Google دسترسی به مدل‌های Gemini را از طریق Google AI Studio فراهم می‌کند، به‌همراه
تولید تصویر، درک رسانه (تصویر/صدا/ویدیو)، تبدیل متن به گفتار، و جست‌وجوی وب از طریق
Gemini Grounding.
- ارائه‌دهنده: `google`
- احراز هویت: `GEMINI_API_KEY` یا `GOOGLE_API_KEY`
- API: Google Gemini API
- گزینه زمان اجرا: `agents.defaults.agentRuntime.id: "google-gemini-cli"`
از OAuth مربوط به Gemini CLI دوباره استفاده می‌کند و در عین حال ارجاع‌های مدل را به‌صورت متعارف `google/*` نگه می‌دارد.
- گزینهٔ زمان اجرا: `agents.defaults.agentRuntime.id: "google-gemini-cli"`
ضمن نگه‌داشتن ارجاع‌های مدل به‌شکل رسمی `google/*`، OAuth متعلق به Gemini CLI را دوباره استفاده می‌کند.
## شروع به کار
## شروع کار
روش احراز هویت دلخواه خود را انتخاب کنید و مراحل راه‌اندازی را دنبال کنید.
@ -57,7 +57,7 @@ Gemini Grounding.
}
```
</Step>
<Step title="بررسی در دسترس بودن مدل">
<Step title="تأیید در دسترس بودن مدل">
```bash
openclaw models list --provider google
```
@ -71,16 +71,16 @@ Gemini Grounding.
</Tab>
<Tab title="Gemini CLI (OAuth)">
**بهترین گزینه برای:** استفاده دوباره از ورود موجود Gemini CLI از طریق PKCE OAuth به‌جای یک کلید API جداگانه.
**بهترین گزینه برای:** استفادهٔ دوباره از ورود موجود Gemini CLI از طریق PKCE OAuth به‌جای یک کلید API جداگانه.
<Warning>
ارائه‌دهنده `google-gemini-cli` یک یکپارچه‌سازی غیررسمی است. برخی کاربران
هنگام استفاده از OAuth به این روش، محدودیت‌های حساب گزارش کرده‌اند. با مسئولیت خودتان استفاده کنید.
ارائه‌دهندهٔ `google-gemini-cli` یک یکپارچه‌سازی غیررسمی است. برخی کاربران
هنگام استفاده از OAuth به این روش، محدودیت‌های حساب را گزارش کرده‌اند. با مسئولیت خودتان استفاده کنید.
</Warning>
<Steps>
<Step title="نصب Gemini CLI">
فرمان محلی `gemini` باید در `PATH` در دسترس باشد.
دستور محلی `gemini` باید روی `PATH` در دسترس باشد.
```bash
# Homebrew
@ -98,7 +98,7 @@ Gemini Grounding.
openclaw models auth login --provider google-gemini-cli --set-default
```
</Step>
<Step title="بررسی در دسترس بودن مدل">
<Step title="تأیید در دسترس بودن مدل">
```bash
openclaw models list --provider google
```
@ -109,7 +109,7 @@ Gemini Grounding.
- زمان اجرا: `google-gemini-cli`
- نام مستعار: `gemini-cli`
شناسه مدل Gemini API برای Gemini 3.1 Pro برابر با `gemini-3.1-pro-preview` است. OpenClaw شکل کوتاه‌تر `google/gemini-3.1-pro` را به‌عنوان نام مستعار کاربردی می‌پذیرد و پیش از فراخوانی‌های ارائه‌دهنده آن را عادی‌سازی می‌کند.
شناسهٔ مدل Gemini API برای Gemini 3.1 Pro برابر `gemini-3.1-pro-preview` است. OpenClaw نام کوتاه‌تر `google/gemini-3.1-pro` را به‌عنوان یک نام مستعار راحت می‌پذیرد و پیش از فراخوانی‌های ارائه‌دهنده آن را عادی‌سازی می‌کند.
**متغیرهای محیطی:**
@ -119,17 +119,17 @@ Gemini Grounding.
(یا گونه‌های `GEMINI_CLI_*`.)
<Note>
اگر درخواست‌های Gemini CLI OAuth پس از ورود شکست خوردند، `GOOGLE_CLOUD_PROJECT` یا
اگر درخواست‌های OAuth در Gemini CLI پس از ورود ناموفق شدند، `GOOGLE_CLOUD_PROJECT` یا
`GOOGLE_CLOUD_PROJECT_ID` را روی میزبان Gateway تنظیم کنید و دوباره تلاش کنید.
</Note>
<Note>
اگر ورود پیش از شروع جریان مرورگر شکست می‌خورد، مطمئن شوید فرمان محلی `gemini`
نصب شده و در `PATH` قرار دارد.
اگر ورود قبل از شروع جریان مرورگر ناموفق شد، مطمئن شوید دستور محلی `gemini`
نصب شده و روی `PATH` قرار دارد.
</Note>
ارجاع‌های مدل `google-gemini-cli/*` نام‌های مستعار سازگاری قدیمی هستند. پیکربندی‌های
جدید وقتی اجرای محلی Gemini CLI را می‌خواهند، باید از ارجاع‌های مدل `google/*` به‌همراه زمان اجرای `google-gemini-cli`
جدید باید وقتی اجرای محلی Gemini CLI را می‌خواهند، از ارجاع‌های مدل `google/*` به‌همراه زمان اجرای `google-gemini-cli`
استفاده کنند.
</Tab>
@ -137,25 +137,25 @@ Gemini Grounding.
## قابلیت‌ها
| قابلیت | پشتیبانی‌شده |
| قابلیت | پشتیبانی‌شده |
| ---------------------- | ----------------------------- |
| تکمیل‌های چت | بله |
| تولید تصویر | بله |
| تولید موسیقی | بله |
| تبدیل متن به گفتار | بله |
| صدای بی‌درنگ | بله (Google Live API) |
| فهم تصویر | بله |
| رونویسی صوت | بله |
| فهم ویدیو | بله |
| جست‌وجوی وب (Grounding) | بله |
| تفکر/استدلال | بله (Gemini 2.5+ / Gemini 3+) |
| مدل‌های Gemma 4 | بله |
| تکمیل‌های چت | بله |
| تولید تصویر | بله |
| تولید موسیقی | بله |
| تبدیل متن به گفتار | بله |
| صدای بلادرنگ | بله (Google Live API) |
| درک تصویر | بله |
| رونویسی صدا | بله |
| درک ویدیو | بله |
| جست‌وجوی وب (Grounding) | بله |
| فکر کردن/استدلال | بله (Gemini 2.5+ / Gemini 3+) |
| مدل‌های Gemma 4 | بله |
## جست‌وجوی وب
ارائه‌دهنده جست‌وجوی وب همراه `gemini` از Gemini Google Search grounding استفاده می‌کند.
ارائه‌دهندهٔ جست‌وجوی وب همراه `gemini` از grounding جست‌وجوی Google در Gemini استفاده می‌کند.
یک کلید جست‌وجوی اختصاصی را زیر `plugins.entries.google.config.webSearch` پیکربندی کنید،
یا بگذارید پس از `GEMINI_API_KEY` از `models.providers.google.apiKey` دوباره استفاده کند:
یا اجازه دهید پس از `GEMINI_API_KEY`، از `models.providers.google.apiKey` دوباره استفاده کند:
```json5
{
@ -175,38 +175,38 @@ Gemini Grounding.
}
```
اولویت اعتبارنامه‌ها ابتدا `webSearch.apiKey`، سپس `GEMINI_API_KEY`،
اولویت اعتبارنامه‌ها ابتدا `webSearch.apiKey` اختصاصی، سپس `GEMINI_API_KEY`،
و سپس `models.providers.google.apiKey` است. `webSearch.baseUrl` اختیاری است و
برای پراکسی‌های اپراتور یا نقاط پایانی سازگار با Gemini API وجود دارد؛ وقتی حذف شود،
جست‌وجوی وب Gemini از `models.providers.google.baseUrl` دوباره استفاده می‌کند. برای رفتار ابزار اختصاصی ارائه‌دهنده، به
[جست‌وجوی Gemini](/fa/tools/gemini-search) مراجعه کنید.
برای پراکسی‌های اپراتور یا endpointهای سازگار Gemini API وجود دارد؛ وقتی حذف شود،
جست‌وجوی وب Gemini دوباره از `models.providers.google.baseUrl` استفاده می‌کند. برای رفتار ابزار ویژهٔ ارائه‌دهنده،
[جست‌وجوی Gemini](/fa/tools/gemini-search) را ببینید.
<Tip>
مدل‌های Gemini 3 به‌جای `thinkingBudget` از `thinkingLevel` استفاده می‌کنند. OpenClaw کنترل‌های استدلال
Gemini 3، Gemini 3.1، و نام مستعار `gemini-*-latest` را به
`thinkingLevel` نگاشت می‌کند تا اجراهای پیش‌فرض/کم‌تاخیر مقدارهای غیرفعال‌شده
نام‌های مستعار Gemini 3، Gemini 3.1، و `gemini-*-latest` را به
`thinkingLevel` نگاشت می‌کند تا اجراهای پیش‌فرض/کم‌تأخیر مقادیر غیرفعال
`thinkingBudget` را ارسال نکنند.
`/think adaptive` به‌جای انتخاب یک سطح ثابت OpenClaw، معناشناسی تفکر پویای Google را حفظ می‌کند. Gemini 3 و Gemini 3.1 یک `thinkingLevel` ثابت را حذف می‌کنند تا
`/think adaptive` به‌جای انتخاب یک سطح ثابت OpenClaw، معناشناسی فکر کردن پویای Google را حفظ می‌کند. Gemini 3 و Gemini 3.1 یک `thinkingLevel` ثابت را حذف می‌کنند تا
Google بتواند سطح را انتخاب کند؛ Gemini 2.5 sentinel پویای Google یعنی
`thinkingBudget: -1` را ارسال می‌کند.
مدل‌های Gemma 4 (برای مثال `gemma-4-26b-a4b-it`) از حالت تفکر پشتیبانی می‌کنند. OpenClaw
`thinkingBudget` را برای Gemma 4 به یک `thinkingLevel` پشتیبانی‌شده Google بازنویسی می‌کند.
تنظیم تفکر روی `off` به‌جای نگاشت به `MINIMAL`، غیرفعال بودن تفکر را حفظ می‌کند.
مدل‌های Gemma 4 (برای مثال `gemma-4-26b-a4b-it`) از حالت فکر کردن پشتیبانی می‌کنند. OpenClaw
برای Gemma 4، `thinkingBudget` را به یک `thinkingLevel` پشتیبانی‌شدهٔ Google بازنویسی می‌کند.
تنظیم فکر کردن روی `off` به‌جای نگاشت به `MINIMAL`، غیرفعال بودن فکر کردن را حفظ می‌کند.
</Tip>
## تولید تصویر
ارائه‌دهنده تولید تصویر همراه `google` به‌صورت پیش‌فرض از
ارائه‌دهندهٔ تولید تصویر همراه `google` به‌صورت پیش‌فرض از
`google/gemini-3.1-flash-image-preview` استفاده می‌کند.
- همچنین از `google/gemini-3-pro-image-preview` پشتیبانی می‌کند
- از `google/gemini-3-pro-image-preview` نیز پشتیبانی می‌کند
- تولید: تا ۴ تصویر در هر درخواست
- حالت ویرایش: فعال، تا ۵ تصویر ورودی
- کنترل‌های هندسه: `size`، `aspectRatio`، و `resolution`
برای استفاده از Google به‌عنوان ارائه‌دهنده پیش‌فرض تصویر:
برای استفاده از Google به‌عنوان ارائه‌دهندهٔ پیش‌فرض تصویر:
```json5
{
@ -221,7 +221,7 @@ Google بتواند سطح را انتخاب کند؛ Gemini 2.5 sentinel پوی
```
<Note>
برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، به [تولید تصویر](/fa/tools/image-generation) مراجعه کنید.
برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، [تولید تصویر](/fa/tools/image-generation) را ببینید.
</Note>
## تولید ویدیو
@ -230,11 +230,11 @@ Plugin همراه `google` تولید ویدیو را نیز از طریق اب
`video_generate` ثبت می‌کند.
- مدل ویدیوی پیش‌فرض: `google/veo-3.1-fast-generate-preview`
- حالت‌ها: جریان‌های متن به ویدیو، تصویر به ویدیو، و مرجع تک‌ویدیویی
- حالت‌ها: جریان‌های متن به ویدیو، تصویر به ویدیو، و ارجاع تک‌ویدیو
- از `aspectRatio`، `resolution`، و `audio` پشتیبانی می‌کند
- محدودیت مدت فعلی: **۴ تا ۸ ثانیه**
- محدودیت مدت‌زمان فعلی: **۴ تا ۸ ثانیه**
برای استفاده از Google به‌عنوان ارائه‌دهنده پیش‌فرض ویدیو:
برای استفاده از Google به‌عنوان ارائه‌دهندهٔ پیش‌فرض ویدیو:
```json5
{
@ -249,7 +249,7 @@ Plugin همراه `google` تولید ویدیو را نیز از طریق اب
```
<Note>
برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، به [تولید ویدیو](/fa/tools/video-generation) مراجعه کنید.
برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، [تولید ویدیو](/fa/tools/video-generation) را ببینید.
</Note>
## تولید موسیقی
@ -258,13 +258,13 @@ Plugin همراه `google` تولید موسیقی را نیز از طریق ا
`music_generate` ثبت می‌کند.
- مدل موسیقی پیش‌فرض: `google/lyria-3-clip-preview`
- همچنین از `google/lyria-3-pro-preview` پشتیبانی می‌کند
- از `google/lyria-3-pro-preview` نیز پشتیبانی می‌کند
- کنترل‌های prompt: `lyrics` و `instrumental`
- قالب خروجی: به‌صورت پیش‌فرض `mp3`، به‌علاوه `wav` در `google/lyria-3-pro-preview`
- قالب خروجی: به‌صورت پیش‌فرض `mp3`، به‌علاوهٔ `wav` روی `google/lyria-3-pro-preview`
- ورودی‌های مرجع: تا ۱۰ تصویر
- اجراهای مبتنی بر نشست از طریق جریان مشترک کار/وضعیت جدا می‌شوند، از جمله `action: "status"`
- اجراهای متکی به جلسه از طریق جریان مشترک task/status جدا می‌شوند، شامل `action: "status"`
برای استفاده از Google به‌عنوان ارائه‌دهنده پیش‌فرض موسیقی:
برای استفاده از Google به‌عنوان ارائه‌دهندهٔ پیش‌فرض موسیقی:
```json5
{
@ -279,20 +279,20 @@ Plugin همراه `google` تولید موسیقی را نیز از طریق ا
```
<Note>
برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، به [تولید موسیقی](/fa/tools/music-generation) مراجعه کنید.
برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، [تولید موسیقی](/fa/tools/music-generation) را ببینید.
</Note>
## تبدیل متن به گفتار
ارائه‌دهنده گفتار همراه `google` از مسیر TTS مربوط به Gemini API با
ارائه‌دهندهٔ گفتار همراه `google` از مسیر TTS در Gemini API با
`gemini-3.1-flash-tts-preview` استفاده می‌کند.
- صدای پیش‌فرض: `Kore`
- احراز هویت: `messages.tts.providers.google.apiKey`، `models.providers.google.apiKey`، `GEMINI_API_KEY`، یا `GOOGLE_API_KEY`
- خروجی: WAV برای پیوست‌های معمول TTS، Opus برای مقصدهای یادداشت صوتی، PCM برای Talk/تلفنی
- خروجی یادداشت صوتی: PCM Google به‌صورت WAV بسته‌بندی می‌شود و با `ffmpeg` به Opus با فرکانس ۴۸ kHz تبدیل می‌شود
- خروجی: WAV برای پیوست‌های معمول TTS، Opus برای مقصدهای یادداشت صوتی، PCM برای Talk/تلفن
- خروجی یادداشت صوتی: PCM متعلق به Google به‌صورت WAV بسته‌بندی می‌شود و با `ffmpeg` به Opus با نرخ ۴۸ kHz تبدیل می‌شود
برای استفاده از Google به‌عنوان ارائه‌دهنده پیش‌فرض TTS:
برای استفاده از Google به‌عنوان ارائه‌دهندهٔ پیش‌فرض TTS:
```json5
{
@ -312,13 +312,11 @@ Plugin همراه `google` تولید موسیقی را نیز از طریق ا
}
```
Gemini API TTS برای کنترل سبک از prompt به زبان طبیعی استفاده می‌کند. `audioProfile` را تنظیم کنید
تا پیش از متن گفتاری، یک prompt سبک قابل استفاده مجدد اضافه شود. وقتی متن prompt شما به یک گوینده نام‌دار اشاره می‌کند،
`speakerName` را تنظیم کنید.
TTS در Gemini API برای کنترل سبک از prompt زبان طبیعی استفاده می‌کند. `audioProfile` را تنظیم کنید تا یک prompt سبک قابل‌استفادهٔ دوباره پیش از متن گفتاری اضافه شود. وقتی متن prompt شما به یک گویندهٔ نام‌دار اشاره دارد، `speakerName` را تنظیم کنید.
Gemini API TTS همچنین تگ‌های صوتی بیانی در براکت مربع را در متن می‌پذیرد،
مانند `[whispers]` یا `[laughs]`. برای اینکه تگ‌ها در پاسخ چت قابل مشاهده نباشند
اما به TTS ارسال شوند، آن‌ها را داخل یک بلوک `[[tts:text]]...[[/tts:text]]`
TTS در Gemini API همچنین برچسب‌های صوتی بیانی داخل کروشه را در متن می‌پذیرد،
مانند `[whispers]` یا `[laughs]`. برای دور نگه داشتن برچسب‌ها از پاسخ چت قابل‌مشاهده
درحالی‌که آن‌ها را به TTS ارسال می‌کنید، آن‌ها را داخل یک بلوک `[[tts:text]]...[[/tts:text]]`
قرار دهید:
```text
@ -328,27 +326,29 @@ Here is the clean reply text.
```
<Note>
یک کلید API متعلق به Google Cloud Console که به Gemini API محدود شده باشد برای این
ارائه‌دهنده معتبر است. این مسیر جداگانه Cloud Text-to-Speech API نیست.
یک کلید API در Google Cloud Console که به Gemini API محدود شده باشد، برای این
ارائه‌دهنده معتبر است. این مسیر جداگانهٔ Cloud Text-to-Speech API نیست.
</Note>
## صدای بی‌درنگ
## صدای بلادرنگ
Plugin همراه `google` یک ارائه‌دهنده صدای بی‌درنگ مبتنی بر
Gemini Live API را برای پل‌های صوتی backend مانند Voice Call و Google Meet ثبت می‌کند.
Plugin همراه `google` یک ارائه‌دهندهٔ صدای بلادرنگ را ثبت می‌کند که با
Gemini Live API برای پل‌های صوتی backend مانند Voice Call و Google Meet پشتیبانی می‌شود.
| تنظیمات | مسیر پیکربندی | پیش‌فرض |
| تنظیم | مسیر پیکربندی | پیش‌فرض |
| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| مدل | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
| صدا | `...google.voice` | `Kore` |
| دما | `...google.temperature` | (تنظیم‌نشده) |
| مدل | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
| صدا | `...google.voice` | `Kore` |
| دما | `...google.temperature` | (تنظیم‌نشده) |
| حساسیت شروع VAD | `...google.startSensitivity` | (تنظیم‌نشده) |
| حساسیت پایان VAD | `...google.endSensitivity` | (تنظیم‌نشده) |
| مدت سکوت | `...google.silenceDurationMs` | (تنظیم‌نشده) |
| مدت سکوت | `...google.silenceDurationMs` | (تنظیم‌نشده) |
| مدیریت فعالیت | `...google.activityHandling` | پیش‌فرض Google، `start-of-activity-interrupts` |
| پوشش نوبت | `...google.turnCoverage` | پیش‌فرض Google، `only-activity` |
| پوشش نوبت | `...google.turnCoverage` | پیش‌فرض Google، `only-activity` |
| غیرفعال‌سازی VAD خودکار | `...google.automaticActivityDetectionDisabled` | `false` |
| کلید API | `...google.apiKey` | به `models.providers.google.apiKey`، `GEMINI_API_KEY` یا `GOOGLE_API_KEY` برمی‌گردد |
| ازسرگیری نشست | `...google.sessionResumption` | `true` |
| فشرده‌سازی زمینه | `...google.contextWindowCompression` | `true` |
| کلید API | `...google.apiKey` | به `models.providers.google.apiKey`، `GEMINI_API_KEY`، یا `GOOGLE_API_KEY` بازمی‌گردد |
نمونه پیکربندی بلادرنگ تماس صوتی:
@ -380,38 +380,38 @@ Gemini Live API را برای پل‌های صوتی backend مانند Voice Ca
<Note>
Google Live API از صدای دوسویه و فراخوانی تابع از طریق WebSocket استفاده می‌کند.
OpenClaw صدای پل تلفنی/Meet را با جریان PCM Live API متعلق به Gemini سازگار می‌کند و
فراخوانی‌های ابزار را روی قرارداد صدای بلادرنگ مشترک نگه می‌دارد. `temperature` را
تنظیم‌نشده بگذارید، مگر اینکه به تغییرات نمونه‌گیری نیاز داشته باشید؛ OpenClaw مقدارهای غیرمثبت را حذف می‌کند
OpenClaw صدای پل تلفنی/Meet را با جریان PCM Live API در Gemini سازگار می‌کند و
فراخوانی‌های ابزار را روی قرارداد مشترک صدای بلادرنگ نگه می‌دارد. `temperature` را
تنظیم‌نشده بگذارید مگر اینکه به تغییرات نمونه‌گیری نیاز داشته باشید؛ OpenClaw مقدارهای غیرمثبت را حذف می‌کند،
چون Google Live می‌تواند برای `temperature: 0` رونوشت‌ها را بدون صدا برگرداند.
رونویسی Gemini API بدون `languageCodes` فعال می‌شود؛ SDK فعلی Google
راهنمایی‌های کد زبان را در این مسیر API رد می‌کند.
</Note>
<Note>
Control UI Talk از نشست‌های مرورگر Google Live با توکن‌های محدودشده یک‌بارمصرف
پشتیبانی می‌کند. ارائه‌دهندگان صدای بلادرنگ فقط‌پشتیبان نیز می‌توانند از طریق انتقال رله عمومی
Gateway اجرا شوند، که اعتبارنامه‌های ارائه‌دهنده را روی Gateway نگه می‌دارد.
Control UI Talk از نشست‌های مرورگر Google Live با توکن‌های محدود و یک‌بارمصرف
پشتیبانی می‌کند. ارائه‌دهندگان صدای بلادرنگ فقط-بک‌اند همچنین می‌توانند از طریق
انتقال relay عمومی Gateway اجرا شوند که اعتبارنامه‌های ارائه‌دهنده را روی Gateway نگه می‌دارد.
</Note>
برای راستی‌آزمایی زنده توسط نگه‌دارنده، اجرا کنید:
برای راستی‌آزمایی زنده نگه‌دارنده، اجرا کنید:
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`.
شاخه Google همان شکل توکن محدودشده Live API را که Control UI Talk استفاده می‌کند صادر می‌کند،
نقطه پایانی WebSocket مرورگر را باز می‌کند، بار اولیه راه‌اندازی را می‌فرستد،
بخش Google همان شکل توکن محدود Live API را صادر می‌کند که Control
UI Talk از آن استفاده می‌کند، نقطه پایانی WebSocket مرورگر را باز می‌کند، محموله راه‌اندازی اولیه را می‌فرستد،
و منتظر `setupComplete` می‌ماند.
## پیکربندی پیشرفته
<AccordionGroup>
<Accordion title="استفاده دوباره مستقیم از کش Gemini">
<Accordion title="Direct Gemini cache reuse">
برای اجراهای مستقیم Gemini API (`api: "google-generative-ai"`)، OpenClaw
یک هندل پیکربندی‌شده `cachedContent` را به درخواست‌های Gemini منتقل می‌کند.
شناسه `cachedContent` پیکربندی‌شده را به درخواست‌های Gemini عبور می‌دهد.
- پارامترهای هر مدل یا سراسری را با یکی از
- پارامترهای سراسری یا مخصوص هر مدل را با
`cachedContent` یا `cached_content` قدیمی پیکربندی کنید
- اگر هر دو وجود داشته باشند، `cachedContent` برنده است
- اگر هر دو حاضر باشند، `cachedContent` اولویت دارد
- مقدار نمونه: `cachedContents/prebuilt-context`
- مصرف اصابت کش Gemini از
- مصرف cache-hit در Gemini از
`cachedContentTokenCount` بالادستی به `cacheRead` در OpenClaw نرمال‌سازی می‌شود
```json5
@ -432,19 +432,19 @@ Gateway اجرا شوند، که اعتبارنامه‌های ارائه‌ده
</Accordion>
<Accordion title="نکته‌های استفاده JSON در Gemini CLI">
هنگام استفاده از ارائه‌دهنده OAuth متعلق به `google-gemini-cli`، OpenClaw
<Accordion title="Gemini CLI JSON usage notes">
هنگام استفاده از ارائه‌دهنده OAuth به نام `google-gemini-cli`، OpenClaw
خروجی JSON در CLI را به شکل زیر نرمال‌سازی می‌کند:
- متن پاسخ از فیلد `response` در JSON خروجی CLI می‌آید.
- وقتی CLI مقدار `usage` را خالی بگذارد، مصرف به `stats` برمی‌گردد.
- وقتی CLI مقدار `usage` را خالی می‌گذارد، مصرف به `stats` بازمی‌گردد.
- `stats.cached` به `cacheRead` در OpenClaw نرمال‌سازی می‌شود.
- اگر `stats.input` وجود نداشته باشد، OpenClaw توکن‌های ورودی را از
`stats.input_tokens - stats.cached` به دست می‌آورد.
- اگر `stats.input` موجود نباشد، OpenClaw توکن‌های ورودی را از
`stats.input_tokens - stats.cached` استخراج می‌کند.
</Accordion>
<Accordion title="راه‌اندازی محیط و daemon">
<Accordion title="Environment and daemon setup">
اگر Gateway به‌صورت daemon اجرا می‌شود (launchd/systemd)، مطمئن شوید `GEMINI_API_KEY`
برای آن فرایند در دسترس است (برای مثال، در `~/.openclaw/.env` یا از طریق
`env.shellEnv`).
@ -454,16 +454,16 @@ Gateway اجرا شوند، که اعتبارنامه‌های ارائه‌ده
## مرتبط
<CardGroup cols={2}>
<Card title="انتخاب مدل" href="/fa/concepts/model-providers" icon="layers">
<Card title="Model selection" href="/fa/concepts/model-providers" icon="layers">
انتخاب ارائه‌دهندگان، ارجاع‌های مدل، و رفتار failover.
</Card>
<Card title="تولید تصویر" href="/fa/tools/image-generation" icon="image">
<Card title="Image generation" href="/fa/tools/image-generation" icon="image">
پارامترهای ابزار تصویر مشترک و انتخاب ارائه‌دهنده.
</Card>
<Card title="تولید ویدئو" href="/fa/tools/video-generation" icon="video">
پارامترهای ابزار ویدئوی مشترک و انتخاب ارائه‌دهنده.
<Card title="Video generation" href="/fa/tools/video-generation" icon="video">
پارامترهای ابزار ویدیوی مشترک و انتخاب ارائه‌دهنده.
</Card>
<Card title="تولید موسیقی" href="/fa/tools/music-generation" icon="music">
<Card title="Music generation" href="/fa/tools/music-generation" icon="music">
پارامترهای ابزار موسیقی مشترک و انتخاب ارائه‌دهنده.
</Card>
</CardGroup>

599
docs/fa/reference/RELEASING.md
View File

@ -1,190 +1,173 @@
---
read_when:
- در حال جست‌وجوی تعاریف کانال انتشار عمومی
- در حال جست‌وجوی تعاریف کانال‌های انتشار عمومی
- اجرای اعتبارسنجی انتشار یا پذیرش بسته
- در جست‌وجوی نام‌گذاری نسخه‌ها و چرخه انتشار
summary: مسیرهای انتشار، چک‌لیست اپراتور، محیط‌های اعتبارسنجی، نام‌گذاری نسخه‌ها و چرخه زمانی
- در حال جست‌وجوی نام‌گذاری نسخه‌ها و آهنگ انتشار
summary: مسیرهای انتشار، فهرست بررسی اپراتور، محیط‌های اعتبارسنجی، نام‌گذاری نسخه، و آهنگ انتشار
title: سیاست انتشار
x-i18n:
generated_at: "2026-05-03T21:38:42Z"
generated_at: "2026-05-04T07:07:47Z"
model: gpt-5.5
provider: openai
source_hash: 566088d826e1e2bac21b11443b82b62cb73ed1fd9c508c3fb865149cf8a428ba
source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6
source_path: reference/RELEASING.md
workflow: 16
---
OpenClaw سه مسیر انتشار عمومی دارد:
- stable: انتشارهای برچسب‌خورده‌ای که به‌صورت پیش‌فرض در npm `beta` منتشر می‌شوند، یا وقتی صریحا درخواست شود در npm `latest`
- beta: برچسب‌های پیش‌انتشار که در npm `beta` منتشر می‌شوند
- dev: سرِ متحرک `main`
- stable: انتشارهای برچسب‌خورده‌ای که به‌صورت پیش‌فرض در npm با `beta` منتشر می‌شوند، یا وقتی صریحاً درخواست شود در npm با `latest` منتشر می‌شوند
- beta: برچسب‌های پیش‌انتشار که در npm با `beta` منتشر می‌شوند
- dev: سرِ در حال حرکتِ `main`
## نام‌گذاری نسخه
- نسخه انتشار پایدار: `YYYY.M.D`
- نسخهٔ انتشار پایدار: `YYYY.M.D`
- برچسب Git: `vYYYY.M.D`
- نسخه انتشار اصلاحی پایدار: `YYYY.M.D-N`
- نسخهٔ انتشار اصلاحی پایدار: `YYYY.M.D-N`
- برچسب Git: `vYYYY.M.D-N`
- نسخه پیش‌انتشار بتا: `YYYY.M.D-beta.N`
- نسخهٔ پیش‌انتشار بتا: `YYYY.M.D-beta.N`
- برچسب Git: `vYYYY.M.D-beta.N`
- ماه یا روز را با صفر ابتدایی ننویسید
- ماه یا روز را با صفر پر نکنید
- `latest` یعنی انتشار پایدار فعلی npm که ترویج شده است
- `beta` یعنی هدف نصب بتای فعلی
- انتشارهای پایدار و اصلاحی پایدار به‌صورت پیش‌فرض در npm `beta` منتشر می‌شوند؛ گردانندگان انتشار می‌توانند صریحا `latest` را هدف بگیرند، یا بعدا یک ساخت بتای بررسی‌شده را ترویج کنند
- هر انتشار پایدار OpenClaw بسته npm و برنامه macOS را با هم ارائه می‌کند؛
انتشارهای بتا معمولا ابتدا مسیر npm/بسته را اعتبارسنجی و منتشر می‌کنند، و
ساخت/امضا/محضری‌سازی برنامه Mac برای پایدار نگه داشته می‌شود مگر اینکه صریحا درخواست شود
- انتشارهای پایدار و اصلاحی پایدار به‌صورت پیش‌فرض در npm با `beta` منتشر می‌شوند؛ متصدیان انتشار می‌توانند صریحاً `latest` را هدف بگیرند، یا بعداً یک ساخت بتای بررسی‌شده را ترویج کنند
- هر انتشار پایدار OpenClaw بستهٔ npm و برنامهٔ macOS را با هم عرضه می‌کند؛
انتشارهای بتا معمولاً ابتدا مسیر npm/بسته را اعتبارسنجی و منتشر می‌کنند، و
ساخت/امضا/محضری‌سازی برنامهٔ mac برای نسخهٔ پایدار نگه داشته می‌شود مگر آنکه صریحاً درخواست شود
## آهنگ انتشار
## چرخهٔ انتشار
- انتشارها ابتدا از بتا عبور می‌کنند
- پایدار فقط پس از اعتبارسنجی آخرین بتا دنبال می‌شود
- نگه‌دارندگان معمولا انتشارها را از شاخه `release/YYYY.M.D` که
از `main` فعلی ساخته شده است انجام می‌دهند، تا اعتبارسنجی انتشار و اصلاحات مانع
توسعه جدید روی `main` نشود
- نگه‌دارندگان معمولاً انتشارها را از شاخهٔ `release/YYYY.M.D` که از
`main` فعلی ساخته شده است جدا می‌کنند، تا اعتبارسنجی انتشار و رفع اشکال‌ها
توسعهٔ جدید روی `main` را مسدود نکند
- اگر یک برچسب بتا push یا منتشر شده باشد و به اصلاح نیاز داشته باشد، نگه‌دارندگان
به‌جای حذف یا بازآفرینی برچسب بتای قدیمی، برچسب `-beta.N` بعدی را می‌سازند
- رویه تفصیلی انتشار، تاییدیه‌ها، گواهی‌ها و یادداشت‌های بازیابی
فقط مخصوص نگه‌دارندگان است
به‌جای حذف یا بازسازی برچسب بتای قدیمی، برچسب `-beta.N` بعدی را جدا می‌کنند
- رویهٔ تفصیلی انتشار، تأییدها، اعتبارنامه‌ها، و یادداشت‌های بازیابی
فقط مخصوص نگه‌داران است
## چک‌لیست گرداننده انتشار
## چک‌لیست متصدی انتشار
این چک‌لیست شکل عمومی جریان انتشار است. گواهی‌های خصوصی،
امضا، محضری‌سازی، بازیابی dist-tag، و جزئیات بازگردانی اضطراری در
راهنمای اجرای انتشار مخصوص نگه‌دارندگان باقی می‌ماند.
این چک‌لیست شکل عمومی جریان انتشار است. اعتبارنامه‌های خصوصی،
امضا، محضری‌سازی، بازیابی dist-tag، و جزئیات rollback اضطراری در
دستورالعمل اجرایی انتشارِ فقط مخصوص نگه‌داران باقی می‌ماند.
1. از `main` فعلی شروع کنید: آخرین تغییرات را pull کنید، تایید کنید commit هدف push شده است،
و تایید کنید CI فعلی `main` به‌اندازه کافی سبز است که بتوان از آن شاخه ساخت.
2. بخش بالایی `CHANGELOG.md` را از تاریخچه واقعی commitها با
`/changelog` بازنویسی کنید، ورودی‌ها را کاربرمحور نگه دارید، آن را commit کنید، push کنید، و پیش از شاخه‌سازی
یک بار دیگر rebase/pull کنید.
1. از `main` فعلی شروع کنید: آخرین تغییرات را pull کنید، تأیید کنید commit هدف push شده است،
و تأیید کنید CI فعلی `main` به‌اندازهٔ کافی سبز است که بتوان از آن شاخه ساخت.
2. بخش بالایی `CHANGELOG.md` را از تاریخچهٔ واقعی commit با
`/changelog` بازنویسی کنید، ورودی‌ها را کاربرمحور نگه دارید، آن را commit و push کنید، و
پیش از ساخت شاخه یک بار دیگر rebase/pull کنید.
3. رکوردهای سازگاری انتشار را در
`src/plugins/compat/registry.ts` و
`src/commands/doctor/shared/deprecation-compat.ts` بازبینی کنید. سازگاری منقضی‌شده را
فقط وقتی حذف کنید که مسیر ارتقا همچنان پوشش داده شده باشد، یا ثبت کنید چرا
عمدا نگه داشته شده است.
`src/commands/doctor/shared/deprecation-compat.ts` بازبینی کنید. سازگاری منقضی‌شده را فقط وقتی حذف کنید که مسیر ارتقا همچنان پوشش داده شده باشد، یا ثبت کنید چرا
عمداً حفظ شده است.
4. `release/YYYY.M.D` را از `main` فعلی بسازید؛ کار عادی انتشار را
مستقیما روی `main` انجام ندهید.
5. همه محل‌های نسخه لازم را برای برچسب مورد نظر افزایش دهید، `pnpm plugins:sync` را اجرا کنید تا بسته‌های Plugin قابل انتشار نسخه انتشار
و فراداده سازگاری مشترک داشته باشند، سپس پیش‌پرواز قطعی محلی را اجرا کنید:
مستقیماً روی `main` انجام ندهید.
5. همهٔ محل‌های نسخهٔ لازم را برای برچسب مورد نظر افزایش دهید، `pnpm plugins:sync` را اجرا کنید تا بسته‌های Plugin قابل انتشار نسخهٔ انتشار
و فرادادهٔ سازگاری مشترک داشته باشند، سپس پیش‌بررسی قطعی محلی را اجرا کنید:
`pnpm check:test-types`، `pnpm check:architecture`،
`pnpm build && pnpm ui:build`، `pnpm plugins:sync:check`، و
`pnpm release:check`.
6. `OpenClaw NPM Release` را با `preflight_only=true` اجرا کنید. پیش از وجود برچسب،
یک SHA کامل ۴۰کاراکتری شاخه انتشار برای پیش‌پرواز صرفا اعتبارسنجی
یک SHA کامل ۴۰ نویسه‌ای از شاخهٔ انتشار برای پیش‌بررسی صرفاً اعتبارسنجی
مجاز است. `preflight_run_id` موفق را ذخیره کنید.
7. همه آزمون‌های پیش از انتشار را با `Full Release Validation` برای
شاخه انتشار، برچسب، یا SHA کامل commit آغاز کنید. این تنها نقطه ورود دستی
برای چهار جعبه آزمون بزرگ انتشار است: Vitest، Docker، QA Lab، و Package.
8. اگر اعتبارسنجی شکست خورد، روی شاخه انتشار اصلاح کنید و کوچک‌ترین
فایل، مسیر، job گردش‌کار، پروفایل بسته، ارائه‌دهنده، یا allowlist مدل شکست‌خورده را
که اصلاح را اثبات می‌کند دوباره اجرا کنید. چتر کامل را فقط وقتی دوباره اجرا کنید که سطح تغییریافته
7. همهٔ آزمون‌های پیش از انتشار را با `Full Release Validation` برای
شاخهٔ انتشار، برچسب، یا SHA کامل commit آغاز کنید. این تنها نقطهٔ ورود دستی
برای چهار جعبهٔ آزمون بزرگ انتشار است: Vitest، Docker، QA Lab، و Package.
8. اگر اعتبارسنجی شکست خورد، روی شاخهٔ انتشار اصلاح کنید و کوچک‌ترین
فایل، مسیر، job گردش‌کار، پروفایل بسته، provider، یا allowlist مدل شکست‌خورده‌ای را که
اصلاح را اثبات می‌کند دوباره اجرا کنید. چتر کامل را فقط وقتی دوباره اجرا کنید که سطح تغییرکرده
شواهد قبلی را کهنه کند.
9. برای بتا، `vYYYY.M.D-beta.N` را برچسب بزنید، سپس `OpenClaw Release Publish` را از
شاخه منطبق `release/YYYY.M.D` اجرا کنید. این کار `pnpm plugins:sync:check` را تایید می‌کند،
ابتدا همه بسته‌های Plugin قابل انتشار را در npm منتشر می‌کند، همان
مجموعه را در مرحله دوم به‌صورت tarballهای npm-pack مربوط به ClawPack در ClawHub منتشر می‌کند، و سپس
artifact آماده پیش‌پرواز npm مربوط به OpenClaw را با dist-tag منطبق ترویج می‌کند. پس از
انتشار، پذیرش بسته پس از انتشار را
در برابر بسته منتشرشده `openclaw@YYYY.M.D-beta.N` یا
شاخهٔ منطبق `release/YYYY.M.D` اجرا کنید. این کار `pnpm plugins:sync:check` را تأیید می‌کند،
ابتدا همهٔ بسته‌های Plugin قابل انتشار را در npm منتشر می‌کند، سپس همان
مجموعه را به‌عنوان tarballهای ClawPack npm-pack در ClawHub منتشر می‌کند، و بعد
مصنوع پیش‌بررسی npm آمادهٔ OpenClaw را با dist-tag منطبق ترویج می‌کند. پس از
انتشار، پذیرش بستهٔ پس از انتشار را در برابر بستهٔ منتشرشدهٔ
`openclaw@YYYY.M.D-beta.N` یا
`openclaw@beta` اجرا کنید. اگر یک پیش‌انتشار push یا منتشرشده به اصلاح نیاز داشت،
شماره پیش‌انتشار منطبق بعدی را بسازید؛ پیش‌انتشار قدیمی را حذف یا بازنویسی نکنید.
10. برای پایدار، فقط پس از آن ادامه دهید که بتا یا کاندیدای انتشار بررسی‌شده
شواهد اعتبارسنجی لازم را داشته باشد. انتشار npm پایدار نیز از طریق
`OpenClaw Release Publish` انجام می‌شود و با استفاده از
`preflight_run_id` از artifact موفق پیش‌پرواز دوباره استفاده می‌کند؛ آمادگی انتشار پایدار macOS همچنین به
شمارهٔ پیش‌انتشار منطبق بعدی را جدا کنید؛ پیش‌انتشار قدیمی را حذف یا بازنویسی نکنید.
10. برای پایدار، فقط پس از آن ادامه دهید که بتا یا نامزد انتشار بررسی‌شده
شواهد اعتبارسنجی لازم را داشته باشد. انتشار پایدار npm نیز از طریق
`OpenClaw Release Publish` انجام می‌شود، با استفادهٔ دوباره از مصنوع پیش‌بررسی موفق از طریق
`preflight_run_id`؛ آمادگی انتشار پایدار macOS همچنین به
`.zip`، `.dmg`، `.dSYM.zip` بسته‌بندی‌شده، و `appcast.xml` به‌روزشده روی `main` نیاز دارد.
11. پس از انتشار، تاییدکننده پس از انتشار npm، آزمون اختیاری E2E مستقل
Telegram منتشرشده از npm وقتی به اثبات کانال پس از انتشار نیاز دارید،
ترویج dist-tag در صورت نیاز، یادداشت‌های انتشار/پیش‌انتشار GitHub از بخش
کامل و منطبق `CHANGELOG.md`، و گام‌های اعلام انتشار
را اجرا کنید.
11. پس از انتشار، تأییدگر پس از انتشار npm، E2E اختیاری Telegram برای
npm منتشرشدهٔ مستقل وقتی به اثبات کانال پس از انتشار نیاز دارید،
ترویج dist-tag در صورت نیاز، یادداشت‌های انتشار/پیش‌انتشار GitHub از
بخش کامل و منطبق `CHANGELOG.md`، و گام‌های اعلام انتشار را اجرا کنید.
## پیش‌پرواز انتشار
## پیش‌بررسی انتشار
- پیش از پیش‌پرواز انتشار، `pnpm check:test-types` را اجرا کنید تا TypeScript آزمون‌ها بیرون از دروازه سریع‌تر محلی `pnpm check` نیز پوشش داده شود
- پیش از پیش‌پرواز انتشار، `pnpm check:architecture` را اجرا کنید تا بررسی‌های گسترده‌تر چرخه import و مرزهای معماری بیرون از دروازه سریع‌تر محلی سبز باشند
- پیش از `pnpm release:check`، `pnpm build && pnpm ui:build` را اجرا کنید تا آرتیفکت‌های انتشار مورد انتظار `dist/*` و بسته Control UI برای مرحله اعتبارسنجی بسته‌بندی وجود داشته باشند
- پس از افزایش نسخه ریشه و پیش از برچسب‌گذاری، `pnpm plugins:sync` را اجرا کنید. این دستور نسخه‌های بسته‌های Plugin قابل انتشار، فراداده سازگاری peer/API مربوط به OpenClaw، فراداده ساخت، و stubهای changelog مربوط به Plugin را به‌روزرسانی می‌کند تا با نسخه انتشار هسته هماهنگ شوند. `pnpm plugins:sync:check` نگهبان انتشار غیرتغییردهنده است؛ اگر این مرحله فراموش شده باشد، workflow انتشار پیش از هرگونه تغییر در registry شکست می‌خورد.
- پیش از تأیید انتشار، workflow دستی `Full Release Validation` را اجرا کنید تا همه test boxهای پیش از انتشار از یک entrypoint آغاز شوند. این workflow یک شاخه، برچسب، یا SHA کامل commit را می‌پذیرد، `CI` دستی را dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، مجموعه‌های مسیر انتشار Docker، live/E2E، OpenWebUI، برابری QA Lab، Matrix، و laneهای Telegram dispatch می‌کند. با `release_profile=full` و `rerun_group=all`، همچنین Telegram E2E بسته را در برابر آرتیفکت `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، زمانی `npm_telegram_package_spec` را ارائه کنید که همان Telegram E2E باید بسته npm منتشرشده را نیز اثبات کند. پس از انتشار، زمانی `package_acceptance_package_spec` را ارائه کنید که Package Acceptance باید ماتریس package/update خود را به‌جای آرتیفکت ساخته‌شده از SHA، در برابر بسته npm ارسال‌شده اجرا کند. زمانی `evidence_package_spec` را ارائه کنید که گزارش private evidence باید بدون اجبار Telegram E2E اثبات کند که اعتبارسنجی با یک بسته npm منتشرشده مطابقت دارد. مثال:
- پیش از بررسی مقدماتی انتشار، `pnpm check:test-types` را اجرا کنید تا TypeScript تست‌ها خارج از gate سریع‌تر محلی `pnpm check` همچنان پوشش داده شود
- پیش از بررسی مقدماتی انتشار، `pnpm check:architecture` را اجرا کنید تا بررسی‌های گسترده‌تر چرخه‌های import و مرزهای معماری خارج از gate سریع‌تر محلی سبز باشند
- پیش از `pnpm release:check`، `pnpm build && pnpm ui:build` را اجرا کنید تا artifactهای انتشار مورد انتظار `dist/*` و bundle رابط کاربری کنترل برای مرحله اعتبارسنجی pack موجود باشند
- پس از افزایش نسخه ریشه و پیش از tag زدن، `pnpm plugins:sync` را اجرا کنید. این دستور نسخه‌های packageهای Plugin قابل انتشار، فراداده سازگاری peer/API مربوط به OpenClaw، فراداده build، و stubهای changelog Plugin را به‌روزرسانی می‌کند تا با نسخه انتشار core هم‌خوان شوند. `pnpm plugins:sync:check` نگهبان غیرتغییردهنده انتشار است؛ اگر این مرحله فراموش شده باشد، workflow انتشار پیش از هرگونه تغییر در registry شکست می‌خورد.
- پیش از تأیید انتشار، workflow دستی `Full Release Validation` را اجرا کنید تا همه test boxهای پیش از انتشار از یک entrypoint آغاز شوند. این workflow یک branch، tag، یا commit SHA کامل می‌پذیرد، `CI` دستی را dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، suiteهای مسیر انتشار Docker، live/E2E، OpenWebUI، برابری QA Lab، Matrix، و laneهای Telegram dispatch می‌کند. با `release_profile=full` و `rerun_group=all`، همچنین Telegram E2E package را روی artifact `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، وقتی همان Telegram E2E باید package منتشرشده npm را هم اثبات کند، `npm_telegram_package_spec` را ارائه کنید. پس از انتشار، وقتی Package Acceptance باید matrix package/update خود را به‌جای artifact ساخته‌شده از SHA روی package ارسال‌شده npm اجرا کند، `package_acceptance_package_spec` را ارائه کنید. وقتی گزارش evidence خصوصی باید بدون اجبار Telegram E2E اثبات کند که اعتبارسنجی با یک package منتشرشده npm مطابقت دارد، `evidence_package_spec` را ارائه کنید. مثال:
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- workflow دستی `Package Acceptance` را زمانی اجرا کنید که می‌خواهید در حین ادامه کار انتشار، اثبات side-channel برای یک نامزد بسته داشته باشید. از `source=npm` برای `openclaw@beta`، `openclaw@latest`، یا یک نسخه دقیق انتشار استفاده کنید؛ از `source=ref` برای بسته‌بندی یک شاخه/برچسب/SHA مطمئن `package_ref` با harness فعلی `workflow_ref` استفاده کنید؛ از `source=url` برای یک tarball HTTPS با SHA-256 الزامی استفاده کنید؛ یا از `source=artifact` برای tarballی که توسط اجرای دیگری از GitHub Actions آپلود شده است استفاده کنید. این workflow نامزد را به `package-under-test` resolve می‌کند، scheduler انتشار Docker E2E را در برابر همان tarball دوباره استفاده می‌کند، و می‌تواند QA مربوط به Telegram را با `telegram_mode=mock-openai` یا `telegram_mode=live-frontier` در برابر همان tarball اجرا کند. وقتی laneهای انتخاب‌شده Docker شامل `published-upgrade-survivor` باشند، آرتیفکت بسته همان نامزد است و `published_upgrade_survivor_baseline` baseline منتشرشده را انتخاب می‌کند.
- وقتی می‌خواهید در حالی که کار انتشار ادامه دارد برای یک candidate package اثبات جانبی بگیرید، workflow دستی `Package Acceptance` را اجرا کنید. برای `openclaw@beta`، `openclaw@latest`، یا یک نسخه انتشار دقیق از `source=npm` استفاده کنید؛ برای pack کردن یک branch/tag/SHA قابل اعتماد `package_ref` با harness فعلی `workflow_ref` از `source=ref` استفاده کنید؛ برای یک tarball HTTPS با SHA-256 الزامی از `source=url` استفاده کنید؛ یا برای tarball آپلودشده توسط اجرای دیگری از GitHub Actions از `source=artifact` استفاده کنید. این workflow candidate را به `package-under-test` resolve می‌کند، scheduler انتشار Docker E2E را روی آن tarball بازاستفاده می‌کند، و می‌تواند QA Telegram را با `telegram_mode=mock-openai` یا `telegram_mode=live-frontier` روی همان tarball اجرا کند. وقتی laneهای Docker انتخاب‌شده شامل `published-upgrade-survivor` باشند، artifact package همان candidate است و `published_upgrade_survivor_baseline` baseline منتشرشده را انتخاب می‌کند.
مثال: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
پروفایل‌های رایج:
- `smoke`: laneهای نصب/channel/agent، شبکه Gateway، و بارگذاری مجدد config
- `package`: laneهای package/update/plugin بومی آرتیفکت بدون OpenWebUI یا ClawHub زنده
- `product`: پروفایل package به‌همراه channelهای MCP، پاک‌سازی cron/subagent، جست‌وجوی وب OpenAI، و OpenWebUI
profileهای رایج:
- `smoke`: laneهای install/channel/agent، شبکه Gateway، و reload پیکربندی
- `package`: laneهای package/update/plugin بومی artifact بدون OpenWebUI یا ClawHub زنده
- `product`: profile package به‌علاوه channelهای MCP، پاک‌سازی cron/subagent، جست‌وجوی وب OpenAI، و OpenWebUI
- `full`: بخش‌های مسیر انتشار Docker با OpenWebUI
- `custom`: انتخاب دقیق `docker_lanes` برای یک اجرای مجدد متمرکز
- زمانی workflow دستی `CI` را مستقیم اجرا کنید که فقط به پوشش کامل CI عادی برای نامزد انتشار نیاز دارید. dispatchهای دستی CI از scoping تغییرات عبور می‌کنند و shardهای Linux Node، shardهای bundled-plugin، قراردادهای channel، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسی‌های docs، Skills پایتون، Windows، macOS، Android، و laneهای i18n مربوط به Control UI را اجباری اجرا می‌کنند.
- `custom`: انتخاب دقیق `docker_lanes` برای rerun متمرکز
- وقتی فقط به پوشش کامل CI عادی برای candidate انتشار نیاز دارید، workflow دستی `CI` را مستقیم اجرا کنید. dispatchهای CI دستی scoping بر اساس تغییرات را دور می‌زنند و shardهای Linux Node، shardهای bundled-plugin، contractهای channel، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسی‌های docs، Skills پایتون، Windows، macOS، Android، و laneهای i18n رابط کاربری کنترل را اجباری می‌کنند.
مثال: `gh workflow run ci.yml --ref release/YYYY.M.D`
- هنگام اعتبارسنجی telemetry انتشار، `pnpm qa:otel:smoke` را اجرا کنید. این دستور QA-lab را از طریق یک گیرنده محلی OTLP/HTTP تمرین می‌دهد و نام‌های span مربوط به trace خروجی، attributeهای محدودشده، و redaction محتوا/شناسه را بدون نیاز به Opik، Langfuse، یا collector خارجی دیگر بررسی می‌کند.
- پیش از هر انتشار برچسب‌دار، `pnpm release:check` را اجرا کنید
- پس از وجود داشتن برچسب، `OpenClaw Release Publish` را برای توالی انتشار تغییردهنده اجرا کنید. آن را از `release/YYYY.M.D` dispatch کنید، یا زمانی که یک برچسب قابل دسترسی از main را منتشر می‌کنید از `main` dispatch کنید، برچسب انتشار و `preflight_run_id` موفق npm مربوط به OpenClaw را بدهید، و scope پیش‌فرض انتشار Plugin یعنی `all-publishable` را نگه دارید مگر اینکه عمداً یک ترمیم متمرکز را اجرا می‌کنید. این workflow انتشار npm مربوط به Plugin، انتشار Plugin در ClawHub، و انتشار npm مربوط به OpenClaw را به‌صورت ترتیبی انجام می‌دهد تا بسته هسته پیش از Pluginهای externalized خود منتشر نشود.
- بررسی‌های انتشار اکنون در یک workflow دستی جداگانه اجرا می‌شوند:
- هنگام اعتبارسنجی telemetry انتشار، `pnpm qa:otel:smoke` را اجرا کنید. این دستور QA-lab را از طریق یک receiver محلی OTLP/HTTP اجرا می‌کند و نام spanهای trace صادرشده، attributeهای محدود، و redact شدن content/identifier را بدون نیاز به Opik، Langfuse، یا collector خارجی دیگر بررسی می‌کند.
- پیش از هر انتشار tagشده، `pnpm release:check` را اجرا کنید
- پس از وجود tag، برای دنباله انتشار تغییردهنده `OpenClaw Release Publish` را اجرا کنید. آن را از `release/YYYY.M.D` dispatch کنید (یا هنگام انتشار tag قابل دسترسی از main، از `main`)، tag انتشار و `preflight_run_id` موفق OpenClaw npm را پاس بدهید، و scope پیش‌فرض انتشار Plugin یعنی `all-publishable` را نگه دارید مگر اینکه عمداً تعمیر متمرکز اجرا می‌کنید. این workflow انتشار npm مربوط به Plugin، انتشار Plugin در ClawHub، و انتشار OpenClaw در npm را سریالی می‌کند تا package core پیش از Pluginهای externalized خود منتشر نشود.
- اکنون release checks در یک workflow دستی جداگانه اجرا می‌شوند:
`OpenClaw Release Checks`
- `OpenClaw Release Checks` همچنین پیش از تأیید انتشار، lane برابری mock مربوط به QA Lab به‌همراه پروفایل live سریع Matrix و lane QA مربوط به Telegram را اجرا می‌کند. laneهای live از محیط `qa-live-shared` استفاده می‌کنند؛ Telegram همچنین از اجاره credential مربوط به Convex CI استفاده می‌کند. زمانی workflow دستی `QA-Lab - All Lanes` را با `matrix_profile=all` و `matrix_shards=true` اجرا کنید که می‌خواهید موجودی کامل transport، media، و E2EE مربوط به Matrix به‌صورت موازی اجرا شود.
- اعتبارسنجی runtime نصب و ارتقا در سیستم‌عامل‌های مختلف بخشی از workflow عمومی `OpenClaw Release Checks` و `Full Release Validation` است که workflow reusable زیر را مستقیم فراخوانی می‌کنند:
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- این جداسازی عمدی است: مسیر واقعی انتشار npm را کوتاه، قطعی، و متمرکز بر آرتیفکت نگه می‌دارد، در حالی که بررسی‌های live کندتر در lane خودشان می‌مانند تا انتشار را متوقف یا مسدود نکنند
- بررسی‌های انتشار دارای secret باید از طریق `Full Release Validation` یا از ref workflow مربوط به `main`/release dispatch شوند تا منطق workflow و secretها کنترل‌شده بمانند
- `OpenClaw Release Checks` یک شاخه، برچسب، یا SHA کامل commit را می‌پذیرد، به شرطی که commit resolveشده از یک شاخه OpenClaw یا برچسب انتشار قابل دسترسی باشد
- پیش‌پرواز فقط‌اعتبارسنجی `OpenClaw NPM Release` نیز SHA کامل ۴۰ کاراکتری commit شاخه workflow فعلی را بدون نیاز به برچسب pushشده می‌پذیرد
- آن مسیر SHA فقط برای اعتبارسنجی است و نمی‌تواند به انتشار واقعی ارتقا داده شود
- در حالت SHA، workflow فقط برای بررسی فراداده بسته `v<package.json version>` را می‌سازد؛ انتشار واقعی همچنان به یک برچسب انتشار واقعی نیاز دارد
- `OpenClaw Release Checks` همچنین پیش از تأیید انتشار، lane برابری mock در QA Lab به‌علاوه profile سریع Matrix زنده و lane QA Telegram را اجرا می‌کند. laneهای زنده از environment `qa-live-shared` استفاده می‌کنند؛ Telegram همچنین از leaseهای credential مربوط به Convex CI استفاده می‌کند. وقتی inventory کامل transport، media، و E2EE مربوط به Matrix را به‌صورت موازی می‌خواهید، workflow دستی `QA-Lab - All Lanes` را با `matrix_profile=all` و `matrix_shards=true` اجرا کنید.
- اعتبارسنجی runtime نصب و upgrade میان سیستم‌عامل‌ها بخشی از `OpenClaw Release Checks` عمومی و `Full Release Validation` است، که workflow قابل بازاستفاده `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` را مستقیم فراخوانی می‌کنند
- این تفکیک عمدی است: مسیر واقعی انتشار npm را کوتاه، قطعی، و متمرکز بر artifact نگه دارید، در حالی که بررسی‌های زنده کندتر در lane خودشان باقی می‌مانند تا انتشار را متوقف یا block نکنند
- release checkهایی که secret دارند باید از طریق `Full Release Validation` یا از workflow ref مربوط به `main`/release dispatch شوند تا logic workflow و secretها کنترل‌شده بمانند
- `OpenClaw Release Checks` یک branch، tag، یا commit SHA کامل را می‌پذیرد تا زمانی که commit resolveشده از یک branch یا tag انتشار OpenClaw قابل دسترسی باشد
- بررسی مقدماتی فقط-اعتبارسنجی `OpenClaw NPM Release` نیز commit SHA کامل ۴۰ کاراکتری branch workflow فعلی را بدون نیاز به tag pushشده می‌پذیرد
- آن مسیر SHA فقط برای اعتبارسنجی است و نمی‌تواند به یک انتشار واقعی promote شود
- در حالت SHA، workflow فقط برای بررسی فراداده package مقدار `v<package.json version>` را synthesize می‌کند؛ انتشار واقعی همچنان به tag واقعی انتشار نیاز دارد
- هر دو workflow مسیر واقعی انتشار و promotion را روی runnerهای GitHub-hosted نگه می‌دارند، در حالی که مسیر اعتبارسنجی غیرتغییردهنده می‌تواند از runnerهای بزرگ‌تر Blacksmith Linux استفاده کند
- آن workflow دستور
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
را با استفاده از secretهای workflow یعنی `OPENAI_API_KEY` و `ANTHROPIC_API_KEY` اجرا می‌کند
- پیش‌پرواز انتشار npm دیگر منتظر lane جداگانه release checks نمی‌ماند
- پیش از تأیید، `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` را اجرا کنید
(یا برچسب beta/correction متناظر را)
- پس از انتشار npm، دستور
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
را اجرا کنید
(یا نسخه beta/correction متناظر را) تا مسیر نصب registry منتشرشده در یک prefix موقت تازه بررسی شود
- پس از انتشار beta، دستور `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
را اجرا کنید تا onboarding بسته نصب‌شده، راه‌اندازی Telegram، و Telegram E2E واقعی در برابر بسته npm منتشرشده با استفاده از pool مشترک credential اجاره‌ای Telegram بررسی شود. maintainerها برای اجراهای موردی محلی می‌توانند متغیرهای Convex را حذف کنند و سه credential محیطی `OPENCLAW_QA_TELEGRAM_*` را مستقیم بدهند.
- maintainerها می‌توانند همین بررسی پس از انتشار را از GitHub Actions از طریق workflow دستی `NPM Telegram Beta E2E` اجرا کنند. این workflow عمداً فقط دستی است و روی هر merge اجرا نمی‌شود.
- اتوماسیون انتشار maintainer اکنون از preflight-then-promote استفاده می‌کند:
- انتشار واقعی npm باید یک `preflight_run_id` موفق npm داشته باشد
- انتشار واقعی npm باید از همان شاخه `main` یا `release/YYYY.M.D` dispatch شود که اجرای پیش‌پرواز موفق از آن بوده است
- انتشارهای پایدار npm به‌طور پیش‌فرض روی `beta` هستند
- انتشار پایدار npm می‌تواند از طریق ورودی workflow به‌صورت صریح `latest` را هدف بگیرد
- تغییر npm dist-tag مبتنی بر token اکنون برای امنیت در
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
قرار دارد، چون `npm dist-tag add` همچنان به `NPM_TOKEN` نیاز دارد در حالی که repo عمومی انتشار فقط OIDC را نگه می‌دارد
- `macOS Release` عمومی فقط‌اعتبارسنجی است؛ وقتی یک برچسب فقط روی شاخه release وجود دارد اما workflow از `main` dispatch می‌شود، `public_release_branch=release/YYYY.M.D` را تنظیم کنید
- انتشار واقعی خصوصی mac باید `preflight_run_id` و `validate_run_id` موفق خصوصی mac را داشته باشد
- مسیرهای واقعی انتشار، آرتیفکت‌های آماده‌شده را promote می‌کنند به‌جای اینکه دوباره آن‌ها را build کنند
- برای انتشارهای correction پایدار مانند `YYYY.M.D-N`، verifier پس از انتشار مسیر ارتقای temp-prefix یکسان را از `YYYY.M.D` به `YYYY.M.D-N` نیز بررسی می‌کند تا correctionهای انتشار نتوانند بی‌صدا نصب‌های global قدیمی‌تر را روی payload پایدار پایه باقی بگذارند
- پیش‌پرواز انتشار npm به‌صورت fail-closed شکست می‌خورد مگر اینکه tarball شامل هر دو payload یعنی `dist/control-ui/index.html` و `dist/control-ui/assets/` غیرخالی باشد، تا دوباره یک dashboard مرورگر خالی ارسال نکنیم
- اعتبارسنجی پس از انتشار همچنین بررسی می‌کند که entrypointهای Plugin منتشرشده و فراداده package در layout نصب‌شده registry وجود داشته باشند. انتشاری که payloadهای runtime مربوط به Plugin را ناقص ارسال کند در verifier پس از انتشار شکست می‌خورد و نمی‌تواند به `latest` promote شود.
- `pnpm test:install:smoke` همچنین بودجه `unpackedSize` مربوط به npm pack را روی tarball به‌روزرسانی نامزد enforce می‌کند، بنابراین installer e2e پیش از مسیر انتشار release، pack bloat تصادفی را می‌گیرد
- اگر کار انتشار به برنامه‌ریزی CI، manifestهای زمان‌بندی extension، یا ماتریس‌های آزمون extension دست زده است، پیش از تأیید خروجی‌های ماتریس `plugin-prerelease-extension-shard` متعلق به planner را از `.github/workflows/plugin-prerelease.yml` دوباره تولید و بازبینی کنید تا release notes یک layout قدیمی CI را توصیف نکند
- آمادگی انتشار پایدار macOS همچنین شامل سطح‌های updater است:
- انتشار GitHub باید در نهایت `.zip`، `.dmg`، و `.dSYM.zip` بسته‌بندی‌شده را داشته باشد
- پس از انتشار، `appcast.xml` روی `main` باید به zip پایدار جدید اشاره کند
- اپ بسته‌بندی‌شده باید bundle id غیرdebug، URL غیرخالی Sparkle feed، و `CFBundleVersion` برابر یا بالاتر از کف canonical build مربوط به Sparkle برای آن نسخه انتشار را حفظ کند
- آن workflow دستور `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` را با استفاده از هر دو secret workflow یعنی `OPENAI_API_KEY` و `ANTHROPIC_API_KEY` اجرا می‌کند
- بررسی مقدماتی انتشار npm دیگر منتظر lane جداگانه release checks نمی‌ماند
- پیش از تأیید، `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` را اجرا کنید (یا tag متناظر beta/correction)
- پس از انتشار npm، برای بررسی مسیر نصب registry منتشرشده در یک temp prefix تازه، `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` را اجرا کنید (یا نسخه متناظر beta/correction)
- پس از انتشار beta، برای بررسی onboarding package نصب‌شده، راه‌اندازی Telegram، و Telegram E2E واقعی روی package منتشرشده npm با استفاده از pool مشترک credentialهای اجاره‌ای Telegram، `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` را اجرا کنید. اجرای موردی محلی توسط maintainer می‌تواند vars مربوط به Convex را حذف کند و سه credential env یعنی `OPENCLAW_QA_TELEGRAM_*` را مستقیم پاس بدهد.
- برای اجرای smoke کامل beta پس از انتشار از ماشین maintainer، از `pnpm release:beta-smoke -- --beta betaN` استفاده کنید. helper اعتبارسنجی Parallels برای npm update/fresh-target را اجرا می‌کند، `NPM Telegram Beta E2E` را dispatch می‌کند، اجرای دقیق workflow را poll می‌کند، artifact را دانلود می‌کند، و گزارش Telegram را چاپ می‌کند.
- maintainers می‌توانند همان بررسی پس از انتشار را از GitHub Actions از طریق workflow دستی `NPM Telegram Beta E2E` اجرا کنند. این workflow عمداً فقط دستی است و روی هر merge اجرا نمی‌شود.
- automation انتشار maintainer اکنون از preflight-then-promote استفاده می‌کند:
- انتشار واقعی npm باید از یک `preflight_run_id` موفق npm عبور کند
- انتشار واقعی npm باید از همان branch `main` یا `release/YYYY.M.D` اجرا شود که preflight موفق از آن اجرا شده است
- انتشارهای stable npm به‌طور پیش‌فرض روی `beta` قرار می‌گیرند
- انتشار stable npm می‌تواند از طریق ورودی workflow صراحتاً `latest` را هدف بگیرد
- تغییر token-based در dist-tagهای npm اکنون برای امنیت در `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` قرار دارد، زیرا `npm dist-tag add` همچنان به `NPM_TOKEN` نیاز دارد در حالی که repo عمومی انتشار فقط با OIDC را نگه می‌دارد
- `macOS Release` عمومی فقط اعتبارسنجی است؛ وقتی یک tag فقط روی branch انتشار وجود دارد اما workflow از `main` dispatch می‌شود، `public_release_branch=release/YYYY.M.D` را تنظیم کنید
- انتشار واقعی private mac باید از `preflight_run_id` و `validate_run_id` موفق private mac عبور کند
- مسیرهای واقعی انتشار artifactهای آماده‌شده را promote می‌کنند به‌جای اینکه دوباره آن‌ها را rebuild کنند
- برای انتشارهای correction پایدار مانند `YYYY.M.D-N`، verifier پس از انتشار همچنین همان مسیر upgrade با temp-prefix از `YYYY.M.D` به `YYYY.M.D-N` را بررسی می‌کند تا correctionهای انتشار نتوانند بی‌سروصدا نصب‌های global قدیمی‌تر را روی payload پایدار پایه باقی بگذارند
- بررسی مقدماتی انتشار npm به‌صورت fail-closed شکست می‌خورد مگر اینکه tarball هم `dist/control-ui/index.html` و هم payload غیرخالی `dist/control-ui/assets/` را شامل شود تا دوباره dashboard مرورگر خالی ارسال نکنیم
- اعتبارسنجی پس از انتشار همچنین بررسی می‌کند که entrypointهای Plugin منتشرشده و فراداده package در layout نصب‌شده registry وجود داشته باشند. انتشاری که payloadهای runtime مربوط به Plugin را ناقص ارسال کند، verifier پس از انتشار را fail می‌کند و نمی‌تواند به `latest` promote شود.
- `pnpm test:install:smoke` همچنین budget مربوط به `unpackedSize` در npm pack را روی tarball candidate update اعمال می‌کند، بنابراین installer e2e پیش از مسیر انتشار release، افزایش ناخواسته حجم pack را می‌گیرد
- اگر کار انتشار به برنامه‌ریزی CI، manifestهای زمان‌بندی extension، یا matrixهای تست extension دست زده است، پیش از تأیید، outputهای matrix مربوط به `plugin-prerelease-extension-shard` متعلق به planner را از `.github/workflows/plugin-prerelease.yml` دوباره generate و review کنید تا release notes layout کهنه CI را توصیف نکند
- آمادگی انتشار stable macOS همچنین شامل سطوح updater است:
- GitHub release باید در نهایت شامل `.zip`، `.dmg`، و `.dSYM.zip` packageشده باشد
- `appcast.xml` روی `main` باید پس از انتشار به zip پایدار جدید اشاره کند
- app بسته‌بندی‌شده باید bundle id غیر-debug، URL feed غیرخالی Sparkle، و `CFBundleVersion` در حداقل کف build canonical Sparkle یا بالاتر برای آن نسخه انتشار را حفظ کند
## جعبه‌های آزمون انتشار
## test boxهای انتشار
`Full Release Validation` روشی است که operatorها با آن همه آزمون‌های پیش از انتشار را از
یک entrypoint آغاز می‌کنند. برای اثبات commit پین‌شده روی شاخه‌ای که سریع تغییر می‌کند، از
helper استفاده کنید تا هر workflow فرزند از یک شاخه موقت ثابت‌شده روی SHA هدف اجرا شود:
`Full Release Validation` روشی است که operatorها با آن همه تست‌های پیش از انتشار را از یک entrypoint آغاز می‌کنند. برای اثبات commit pinشده روی branch پرتحرک، از helper استفاده کنید تا هر workflow فرزند از یک branch موقت ثابت‌شده روی SHA هدف اجرا شود:
```bash
pnpm ci:full-release --sha <full-sha>
```
این helper شاخه `release-ci/<sha>-...` را push می‌کند، `Full Release Validation`
را از آن شاخه با `ref=<sha>` dispatch می‌کند، بررسی می‌کند که `headSha`
هر workflow فرزند با هدف مطابقت داشته باشد، سپس شاخه موقت را حذف می‌کند. این کار از اثبات تصادفی
اجرای فرزند جدیدتر `main` جلوگیری می‌کند.
helper مقدار `release-ci/<sha>-...` را push می‌کند، `Full Release Validation` را از آن branch با `ref=<sha>` dispatch می‌کند، بررسی می‌کند که `headSha` هر workflow فرزند با هدف مطابقت داشته باشد، سپس branch موقت را حذف می‌کند. این کار از اثبات تصادفی یک اجرای فرزند جدیدتر روی `main` جلوگیری می‌کند.
برای اعتبارسنجی شاخه یا برچسب انتشار، آن را از ref workflow مطمئن `main` اجرا کنید
و شاخه یا برچسب انتشار را به‌عنوان `ref` بدهید:
برای اعتبارسنجی branch یا tag انتشار، آن را از workflow ref قابل اعتماد `main` اجرا کنید و branch یا tag انتشار را به‌عنوان `ref` پاس بدهید:
```bash
gh workflow run full-release-validation.yml \
@ -196,45 +179,47 @@ gh workflow run full-release-validation.yml \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
گردش‌کار ref هدف را resolve می‌کند، `CI` دستی را با
`target_ref=<release-ref>` dispatch می‌کند، `OpenClaw Release Checks` را dispatch می‌کند، artifact والد
`release-package-under-test` را برای بررسی‌های ناظر به package آماده می‌کند، و
E2E مستقل Telegram برای package را وقتی `release_profile=full` با
`rerun_group=all` باشد یا وقتی `npm_telegram_package_spec` تنظیم شده باشد dispatch می‌کند. سپس `OpenClaw Release
Checks` به install smoke، بررسی‌های انتشار میان‌سیستم‌عاملی، پوشش live/E2E Docker
در مسیر انتشار، Package Acceptance با QA برای package Telegram، هم‌ارزی QA Lab،
Matrix زنده، و Telegram زنده fan out می‌شود. اجرای کامل فقط وقتی قابل قبول است که
خلاصه `Full Release Validation`
، `normal_ci` و `release_checks` را موفق نشان دهد. در حالت full/all،
گردش‌کار، ref هدف را resolve می‌کند، `CI` دستی را با
`target_ref=<release-ref>` dispatch می‌کند، `OpenClaw Release Checks` را dispatch می‌کند، یک
artifact والد `release-package-under-test` را برای بررسی‌های مرتبط با بسته آماده می‌کند، و
وقتی `release_profile=full` با `rerun_group=all` باشد یا وقتی
`npm_telegram_package_spec` تنظیم شده باشد، E2E مستقل بسته Telegram را dispatch می‌کند. سپس `OpenClaw Release
Checks` بررسی‌های install smoke، بررسی‌های انتشار cross-OS، پوشش مسیر انتشار live/E2E Docker،
Package Acceptance با QA بسته Telegram، برابری QA Lab،
Matrix زنده، و Telegram زنده را fan out می‌کند. یک اجرای کامل فقط زمانی قابل قبول است که
خلاصه‌ی `Full Release Validation`
`normal_ci` و `release_checks` را موفق نشان دهد. در حالت full/all،
فرزند `npm_telegram` نیز باید موفق باشد؛ خارج از full/all، مگر اینکه
`npm_telegram_package_spec` منتشرشده ارائه شده باشد، skip می‌شود. خلاصه نهایی
verifier شامل جدول‌های کندترین job برای هر اجرای فرزند است، تا release manager
بتواند مسیر بحرانی فعلی را بدون دانلود logها ببیند.
برای ماتریس کامل stage، نام دقیق jobهای workflow، تفاوت‌های profile پایدار در برابر کامل،
یک `npm_telegram_package_spec` منتشرشده ارائه شده باشد، skip می‌شود. خلاصه‌ی نهایی
verifier شامل جدول‌های کندترین job برای هر اجرای فرزند است، تا مدیر انتشار بتواند
مسیر بحرانی فعلی را بدون دانلود logها ببیند.
برای matrix کامل مرحله‌ها، نام دقیق jobهای workflow، تفاوت‌های پروفایل stable در برابر full،
artifactها، و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید.
گردش‌کارهای فرزند از ref مورد اعتمادی dispatch می‌شوند که `Full Release
Validation` را اجرا می‌کند، معمولا `--ref main`، حتی وقتی ref هدف به branch یا tag
انتشار قدیمی‌تری اشاره کند. ورودی جداگانه‌ای برای workflow-ref مربوط به Full Release Validation
workflowهای فرزند از ref مورد اعتماد که `Full Release
Validation` را اجرا می‌کند dispatch می‌شوند، معمولاً `--ref main`، حتی وقتی target `ref` به یک
شاخه یا tag انتشار قدیمی‌تر اشاره کند. ورودی جداگانه‌ای برای workflow-ref در Full Release Validation
وجود ندارد؛ harness مورد اعتماد را با انتخاب ref اجرای workflow انتخاب کنید.
برای proof دقیق commit روی `main` متحرک از `--ref main -f ref=<sha>` استفاده نکنید؛
SHAهای خام commit نمی‌توانند workflow dispatch ref باشند، بنابراین از
`pnpm ci:full-release --sha <sha>` برای ایجاد branch موقت pinned استفاده کنید.
برای اثبات commit دقیق روی `main` متحرک از `--ref main -f ref=<sha>` استفاده نکنید؛
SHAهای خام commit نمی‌توانند refهای workflow dispatch باشند، پس از
`pnpm ci:full-release --sha <sha>` برای ساخت شاخه‌ی موقت pinned استفاده کنید.
برای انتخاب گستره live/provider از `release_profile` استفاده کنید:
برای انتخاب گستره‌ی live/provider از `release_profile` استفاده کنید:
- `minimum`: سریع‌ترین مسیر live و Docker حیاتی برای انتشار، مربوط به OpenAI/core
- `stable`: minimum به‌علاوه پوشش provider/backend پایدار برای تأیید انتشار
- `full`: stable به‌علاوه پوشش گسترده advisory provider/media
- `minimum`: سریع‌ترین مسیر live و Docker حیاتی برای انتشار OpenAI/core
- `stable`: minimum به‌علاوه‌ی پوشش provider/backend پایدار برای تأیید انتشار
- `full`: stable به‌علاوه‌ی پوشش گسترده‌ی advisory provider/media
`OpenClaw Release Checks` از workflow ref مورد اعتماد استفاده می‌کند تا ref هدف را
یک‌بار به‌صورت `release-package-under-test` resolve کند و از همان artifact هم در
بررسی‌های Docker مسیر انتشار و هم در Package Acceptance دوباره استفاده می‌کند. این کار همه boxهای ناظر به package را روی همان byteها نگه می‌دارد و از buildهای تکراری package جلوگیری می‌کند.
install smoke میان‌سیستم‌عاملی OpenAI وقتی متغیر repo/org تنظیم شده باشد از
`OPENCLAW_CROSS_OS_OPENAI_MODEL` استفاده می‌کند، وگرنه از `openai/gpt-5.4`، زیرا این lane
در حال اثبات نصب package، onboarding، راه‌اندازی Gateway، و یک نوبت agent زنده است
نه benchmark کردن کندترین model پیش‌فرض. ماتریس گسترده‌تر provider زنده همچنان محل پوشش model-specific است.
`OpenClaw Release Checks` از ref مورد اعتماد workflow استفاده می‌کند تا ref هدف را
یک‌بار به‌عنوان `release-package-under-test` resolve کند و همان artifact را هم در
بررسی‌های Docker مسیر انتشار و هم در Package Acceptance دوباره به کار ببرد. این کار همه‌ی
boxهای مرتبط با بسته را روی byteهای یکسان نگه می‌دارد و از ساخت‌های تکراری بسته جلوگیری می‌کند.
install smoke مربوط به cross-OS OpenAI وقتی متغیر repo/org تنظیم شده باشد از
`OPENCLAW_CROSS_OS_OPENAI_MODEL` استفاده می‌کند، وگرنه از `openai/gpt-5.4`، چون این lane در حال
اثبات نصب بسته، onboarding، راه‌اندازی Gateway، و یک نوبت agent زنده است
نه benchmark کردن کندترین مدل پیش‌فرض. matrix گسترده‌تر provider زنده همچنان محل
پوشش اختصاصی مدل‌ها باقی می‌ماند.
بسته به stage انتشار از این variantها استفاده کنید:
بسته به مرحله‌ی انتشار از این variantها استفاده کنید:
```bash
# Validate an unpublished release candidate branch.
@ -264,39 +249,41 @@ gh workflow run full-release-validation.yml \
-f npm_telegram_provider_mode=mock-openai
```
از umbrella کامل به‌عنوان نخستین rerun پس از یک اصلاح متمرکز استفاده نکنید. اگر یک box
fail شد، برای proof بعدی از workflow فرزند fail‌شده، job، lane Docker، profile package، provider model، یا lane QA استفاده کنید. umbrella کامل را فقط وقتی دوباره اجرا کنید که
اصلاح، orchestration مشترک انتشار را تغییر داده باشد یا شواهد all-box قبلی را stale کرده باشد.
verifier نهایی umbrella شناسه‌های ضبط‌شده اجرای workflow فرزند را دوباره بررسی می‌کند، بنابراین پس از rerun موفق یک workflow فرزند، فقط job والد fail‌شده
پس از یک fix متمرکز، از umbrella کامل به‌عنوان اولین rerun استفاده نکنید. اگر یک box
fail شود، برای اثبات بعدی از workflow فرزند fail‌شده، job، Docker lane، پروفایل بسته، provider مدل،
یا QA lane استفاده کنید. umbrella کامل را فقط وقتی دوباره اجرا کنید که
fix، orchestration مشترک انتشار را تغییر داده باشد یا شواهد قبلی همه‌ی boxها را
کهنه کرده باشد. verifier نهایی umbrella دوباره idهای ثبت‌شده‌ی اجرای workflow فرزند
را بررسی می‌کند، پس بعد از اینکه یک workflow فرزند با موفقیت rerun شد، فقط job والد fail‌شده‌ی
`Verify full validation` را rerun کنید.
برای بازیابی محدود، `rerun_group` را به umbrella پاس بدهید. `all` اجرای واقعی
release-candidate است، `ci` فقط فرزند CI عادی را اجرا می‌کند، `plugin-prerelease`
فقط فرزند Plugin مخصوص انتشار را اجرا می‌کند، `release-checks` همه boxهای انتشار را اجرا می‌کند،
و گروه‌های انتشار باریک‌تر عبارت‌اند از `install-smoke`، `cross-os`،
برای بازیابی bounded، `rerun_group` را به umbrella پاس دهید. `all` اجرای واقعی
release-candidate است، `ci` فقط فرزند CI معمولی را اجرا می‌کند، `plugin-prerelease`
فقط فرزند مخصوص انتشار Plugin را اجرا می‌کند، `release-checks` همه‌ی boxهای انتشار
را اجرا می‌کند، و گروه‌های محدودتر انتشار عبارت‌اند از `install-smoke`، `cross-os`،
`live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، و `npm-telegram`.
rerunهای متمرکز `npm-telegram` به `npm_telegram_package_spec` نیاز دارند؛ اجراهای full/all
با `release_profile=full` از artifact package مربوط به release-checks استفاده می‌کنند.
با `release_profile=full` از artifact بسته‌ی release-checks استفاده می‌کنند.
### Vitest
box مربوط به Vitest همان workflow فرزند `CI` دستی است. CI دستی عمدا
scoping مبتنی بر changed را دور می‌زند و graph تست عادی را برای release candidate اجباری می‌کند:
shardهای Linux Node، shardهای bundled-plugin، قراردادهای channel، سازگاری Node 22،
box مربوط به Vitest همان workflow فرزند `CI` دستی است. CI دستی عمداً
scoping تغییرات را دور می‌زند و graph معمول test را برای release candidate اجبار می‌کند:
shardهای Linux Node، shardهای Pluginهای bundled، contractهای channel، سازگاری Node 22،
`check`، `check-additional`، build smoke، بررسی‌های docs، Skills پایتون، Windows،
macOS، Android، و i18n مربوط به Control UI.
macOS، Android، و Control UI i18n.
از این box برای پاسخ به این پرسش استفاده کنید: «آیا source tree کل test suite عادی را پاس کرده است؟»
این همان اعتبارسنجی product در مسیر انتشار نیست. شواهدی که باید نگه دارید:
از این box برای پاسخ به این پرسش استفاده کنید: «آیا source tree کل test suite معمول را پاس کرده است؟»
این با اعتبارسنجی محصول در مسیر انتشار یکسان نیست. شواهدی که باید نگه دارید:
- خلاصه `Full Release Validation` که URL اجرای dispatch‌شده `CI` را نشان می‌دهد
- اجرای سبز `CI` روی SHA دقیق هدف
- خلاصه‌ی `Full Release Validation` که URL اجرای `CI` dispatch‌شده را نشان می‌دهد
- اجرای `CI` سبز روی SHA دقیق هدف
- نام shardهای fail‌شده یا کند از jobهای CI هنگام بررسی regressionها
- artifactهای timing مربوط به Vitest مانند `.artifacts/vitest-shard-timings.json` وقتی
یک اجرا به تحلیل performance نیاز دارد
- artifactهای timing Vitest مانند `.artifacts/vitest-shard-timings.json` وقتی
یک اجرا به تحلیل کارایی نیاز دارد
CI دستی را فقط وقتی مستقیم اجرا کنید که انتشار به CI عادی deterministic نیاز دارد اما
به boxهای Docker، QA Lab، live، cross-OS، یا package نیاز ندارد:
CI دستی را مستقیماً فقط وقتی اجرا کنید که انتشار به CI معمول deterministic نیاز داشته باشد اما
به boxهای Docker، QA Lab، live، cross-OS، یا package نیاز نداشته باشد:
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -304,16 +291,16 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
box مربوط به Docker در `OpenClaw Release Checks` از طریق
`openclaw-live-and-e2e-checks-reusable.yml`، به‌علاوه workflow
`install-smoke` در حالت release قرار دارد. این box release candidate را از طریق محیط‌های packaged
Docker اعتبارسنجی می‌کند، نه فقط تست‌های سطح source.
box مربوط به Docker درون `OpenClaw Release Checks` از طریق
`openclaw-live-and-e2e-checks-reusable.yml`، به‌علاوه‌ی workflow
`install-smoke` در حالت release قرار دارد. این box، release candidate را از طریق محیط‌های
Docker بسته‌بندی‌شده اعتبارسنجی می‌کند، نه فقط testهای سطح source.
پوشش Docker انتشار شامل موارد زیر است:
- install smoke کامل با فعال بودن smoke نصب global کند Bun
- آماده‌سازی/استفاده مجدد از image smoke برای Dockerfile ریشه بر اساس SHA هدف، با jobهای smoke مربوط به QR،
root/gateway، و installer/Bun که به‌صورت shardهای install-smoke جداگانه اجرا می‌شوند
- آماده‌سازی/استفاده‌ی دوباره از image smoke ریشه‌ی Dockerfile براساس SHA هدف، با jobهای QR،
root/gateway، و installer/Bun smoke که به‌عنوان shardهای جداگانه‌ی install-smoke اجرا می‌شوند
- laneهای E2E repository
- chunkهای Docker مسیر انتشار: `core`، `package-update-openai`،
`package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`،
@ -322,75 +309,88 @@ Docker اعتبارسنجی می‌کند، نه فقط تست‌های سطح s
`plugins-runtime-install-c`، `plugins-runtime-install-d`،
`plugins-runtime-install-e`، `plugins-runtime-install-f`،
`plugins-runtime-install-g`، و `plugins-runtime-install-h`
- پوشش OpenWebUI داخل chunk `plugins-runtime-services` در صورت درخواست
- laneهای split نصب/حذف نصب bundled Plugin
- پوشش OpenWebUI داخل chunk `plugins-runtime-services` وقتی درخواست شده باشد
- laneهای جداشده‌ی نصب/حذف Plugin bundled
`bundled-plugin-install-uninstall-0` تا
`bundled-plugin-install-uninstall-23`
- suiteهای provider live/E2E و پوشش model زنده Docker وقتی release checks
شامل suiteهای live باشد
- suiteهای provider زنده/E2E و پوشش مدل زنده‌ی Docker وقتی release checks
شامل suiteهای live باشند
پیش از rerun از artifactهای Docker استفاده کنید. scheduler مسیر انتشار،
پیش از rerun از artifactهای Docker استفاده کنید. scheduler مسیر انتشار
`.artifacts/docker-tests/` را با logهای lane، `summary.json`، `failures.json`,
timingهای phase، JSON طرح scheduler، و دستورهای rerun upload می‌کند. برای بازیابی متمرکز،
به‌جای rerun کردن همه chunkهای انتشار، از `docker_lanes=<lane[,lane]>` روی workflow قابل استفاده مجدد live/E2E استفاده کنید. دستورهای rerun تولیدشده در صورت موجود بودن شامل
`package_artifact_run_id` قبلی و ورودی‌های image آماده‌شده Docker هستند، تا یک
به‌جای rerun کردن همه‌ی chunkهای انتشار، روی workflow live/E2E قابل استفاده‌مجدد از
`docker_lanes=<lane[,lane]>` استفاده کنید. دستورهای rerun تولیدشده وقتی موجود باشند شامل
`package_artifact_run_id` قبلی و ورودی‌های image آماده‌شده‌ی Docker هستند، تا یک
lane fail‌شده بتواند از همان tarball و imageهای GHCR دوباره استفاده کند.
### QA Lab
box مربوط به QA Lab نیز بخشی از `OpenClaw Release Checks` است. این gate رفتار agentic
و سطح channel برای انتشار است، جدا از Vitest و مکانیک package در Docker.
box مربوط به QA Lab نیز بخشی از `OpenClaw Release Checks` است. این gate انتشار مربوط به
رفتار agentic و سطح channel است، جدا از Vitest و سازوکارهای package Docker.
پوشش QA Lab انتشار شامل موارد زیر است:
- lane هم‌ارزی mock که lane کاندیدای OpenAI را با baseline مربوط به Opus 4.6
با استفاده از pack هم‌ارزی agentic مقایسه می‌کند
- profile سریع QA برای Matrix زنده با استفاده از محیط `qa-live-shared`
- lane QA برای Telegram زنده با استفاده از leaseهای credential مربوط به Convex CI
- `pnpm qa:otel:smoke` وقتی telemetry انتشار به proof محلی صریح نیاز دارد
- lane برابری mock که lane candidate OpenAI را با baseline Opus 4.6
با استفاده از agentic parity pack مقایسه می‌کند
- پروفایل سریع QA زنده‌ی Matrix با استفاده از محیط `qa-live-shared`
- lane QA زنده‌ی Telegram با استفاده از leaseهای credential مربوط به Convex CI
- `pnpm qa:otel:smoke` وقتی telemetry انتشار به اثبات محلی صریح نیاز داشته باشد
از این box برای پاسخ به این پرسش استفاده کنید: «آیا انتشار در سناریوهای QA و
flowهای channel زنده درست رفتار می‌کند؟» هنگام تأیید انتشار، URLهای artifact مربوط به laneهای parity، Matrix، و Telegram را نگه دارید. پوشش کامل Matrix همچنان به‌صورت اجرای دستی sharded QA-Lab در دسترس است، نه lane پیش‌فرض حیاتی برای انتشار.
flowهای channel زنده درست رفتار می‌کند؟» هنگام تأیید انتشار، URLهای artifact برای laneهای برابری،
Matrix، و Telegram را نگه دارید. پوشش کامل Matrix همچنان به‌عنوان اجرای دستی sharded QA-Lab
در دسترس است، نه lane حیاتی پیش‌فرض برای انتشار.
### Package
box مربوط به Package، gate محصول قابل نصب است. پشتوانه آن
box مربوط به Package همان gate محصول قابل‌نصب است. این box با
`Package Acceptance` و resolver
`scripts/resolve-openclaw-package-candidate.mjs` است. resolver یک candidate را به tarball
`package-under-test` که توسط Docker E2E مصرف می‌شود normalize می‌کند، inventory package را اعتبارسنجی می‌کند،
نسخه package و SHA-256 را ثبت می‌کند، و ref مربوط به workflow harness را از ref منبع package جدا نگه می‌دارد.
`scripts/resolve-openclaw-package-candidate.mjs` پشتیبانی می‌شود. resolver یک
candidate را به tarball `package-under-test` مصرف‌شده توسط Docker E2E normalize می‌کند،
inventory بسته را اعتبارسنجی می‌کند، نسخه‌ی بسته و SHA-256 را ثبت می‌کند، و ref
harness workflow را از ref source بسته جدا نگه می‌دارد.
منابع candidate پشتیبانی‌شده:
sourceهای candidate پشتیبانی‌شده:
- `source=npm`: `openclaw@beta`، `openclaw@latest`، یا یک نسخه دقیق انتشار OpenClaw
- `source=ref`: pack کردن branch، tag، یا SHA کامل commit مربوط به `package_ref` مورد اعتماد
با harness انتخاب‌شده `workflow_ref`
- `source=url`: دانلود یک `.tgz` مبتنی بر HTTPS با `package_sha256` الزامی
- `source=artifact`: استفاده مجدد از یک `.tgz` که توسط اجرای دیگری از GitHub Actions upload شده است
- `source=npm`: `openclaw@beta`، `openclaw@latest`، یا یک نسخه‌ی دقیق انتشار OpenClaw
- `source=ref`: بسته‌بندی یک شاخه، tag، یا SHA کامل commit مربوط به `package_ref` مورد اعتماد
با harness انتخاب‌شده‌ی `workflow_ref`
- `source=url`: دانلود یک `.tgz` از HTTPS با `package_sha256` الزامی
- `source=artifact`: استفاده‌ی دوباره از یک `.tgz` uploadشده توسط اجرای دیگری از GitHub Actions
`OpenClaw Release Checks`، Package Acceptance را با `source=artifact`،
artifact آماده‌شده package انتشار، `suite_profile=custom`,
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`,
`published_upgrade_survivor_baselines=all-since-2026.4.23`,
`OpenClaw Release Checks`، Package Acceptance را با `source=artifact`، artifact
بسته‌ی آماده‌شده‌ی انتشار، `suite_profile=custom`،
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`،
`published_upgrade_survivor_baselines=all-since-2026.4.23`،
`published_upgrade_survivor_scenarios=reported-issues`، و
`telegram_mode=mock-openai` اجرا می‌کند. Package Acceptance مهاجرت، update، پاک‌سازی dependencyهای stale Plugin، fixtureهای offline Plugin، update Plugin، و QA برای package Telegram را در برابر همان tarball resolve‌شده نگه می‌دارد. ماتریس upgrade هر baseline پایدار منتشرشده در npm از `2026.4.23` تا `latest` را پوشش می‌دهد؛ برای candidateای که قبلا shipped شده است از Package Acceptance با `source=npm` استفاده کنید، یا
برای tarball محلی npm با پشتوانه SHA پیش از publish از `source=ref`/`source=artifact` استفاده کنید. این جایگزین GitHub-native
برای بیشتر پوشش package/update است که قبلا به Parallels نیاز داشت.
بررسی‌های انتشار cross-OS همچنان برای رفتارهای onboarding، installer، و platform خاص OS مهم هستند، اما اعتبارسنجی product مربوط به package/update باید Package Acceptance را ترجیح دهد.
`telegram_mode=mock-openai` اجرا می‌کند. Package Acceptance، migration، update، پاک‌سازی
وابستگی stale Plugin، fixtureهای Plugin offline، update Plugin، و QA بسته Telegram
را در برابر همان tarball resolve‌شده نگه می‌دارد. matrix upgrade هر baseline پایدار منتشرشده در npm را از `2026.4.23` تا `latest` پوشش می‌دهد؛ برای یک candidate که قبلاً منتشر شده است از
Package Acceptance با `source=npm` استفاده کنید، یا برای یک tarball محلی npm مبتنی بر SHA پیش از
publish از `source=ref`/`source=artifact` استفاده کنید. این جایگزین native در GitHub
برای بیشتر پوشش package/update است که قبلاً به Parallels نیاز داشت.
بررسی‌های انتشار cross-OS همچنان برای onboarding، installer، و رفتار platform خاص OS مهم‌اند،
اما اعتبارسنجی محصول package/update باید Package Acceptance را ترجیح دهد.
چک‌لیست canonical برای اعتبارسنجی update و Plugin، [تست updateها و Pluginها](/fa/help/testing-updates-plugins) است. هنگام تصمیم‌گیری درباره اینکه کدام lane محلی، Docker، Package Acceptance، یا release-check یک تغییر نصب/update Plugin، پاک‌سازی doctor، یا مهاجرت package منتشرشده را اثبات می‌کند، از آن استفاده کنید.
مهاجرت exhaustive published update از هر package پایدار `2026.4.23+` یک workflow دستی جداگانه `Update Migration` است، نه بخشی از Full Release CI.
checklist canonical برای اعتبارسنجی update و Plugin این است:
[آزمایش updateها و Pluginها](/fa/help/testing-updates-plugins). هنگام تصمیم‌گیری درباره‌ی اینکه
کدام lane محلی، Docker، Package Acceptance، یا release-check یک تغییر نصب/update Plugin،
پاک‌سازی doctor، یا migration بسته‌ی منتشرشده را اثبات می‌کند، از آن استفاده کنید.
migration کامل update منتشرشده از هر بسته‌ی پایدار `2026.4.23+`
یک workflow دستی جداگانه‌ی `Update Migration` است، نه بخشی از Full Release CI.
leniency قدیمی package-acceptance عمدا زمان‌بندی محدود دارد. packageها تا
`2026.4.25` می‌توانند برای gapهای metadata که قبلا در npm منتشر شده‌اند از مسیر سازگاری استفاده کنند:
entryهای خصوصی inventory مربوط به QA که در tarball نیستند، نبود
`gateway install --wrapper`، نبود patch fileها در fixture git مشتق‌شده از tarball،
نبود `update.channel` persisted، محل‌های legacy برای install-record مربوط به Plugin،
نبود persistence برای marketplace install-record، و مهاجرت metadata پیکربندی طی `plugins update`. package منتشرشده `2026.4.26` ممکن است
برای فایل‌های stamp مربوط به metadata build محلی که قبلا shipped شده‌اند warning بدهد. packageهای بعدی
باید قراردادهای package مدرن را برآورده کنند؛ همان gapها در اعتبارسنجی انتشار fail می‌شوند.
leniency قدیمی package-acceptance عمداً time boxed است. بسته‌ها تا
`2026.4.25` می‌توانند برای gapهای metadata که قبلاً در npm منتشر شده‌اند
از مسیر compatibility استفاده کنند: entryهای private QA inventory که در tarball وجود ندارند،
نبود `gateway install --wrapper`، نبود patch fileها در fixture git مشتق‌شده از tarball،
نبود `update.channel` persisted، محل‌های قدیمی install-record مربوط به Plugin،
نبود persistence برای install-record marketplace، و migration metadata config
در طول `plugins update`. بسته‌ی منتشرشده‌ی `2026.4.26` ممکن است برای فایل‌های stamp
metadata ساخت محلی که قبلاً ship شده‌اند warning بدهد. بسته‌های بعدی باید
contractهای مدرن package را برآورده کنند؛ همان gapها باعث fail شدن اعتبارسنجی انتشار می‌شوند.
وقتی پرسش انتشار درباره یک package واقعا قابل نصب است، از profileهای گسترده‌تر Package Acceptance استفاده کنید:
وقتی پرسش انتشار درباره‌ی یک بسته‌ی واقعاً قابل‌نصب است، از پروفایل‌های گسترده‌تر Package Acceptance استفاده کنید:
```bash
gh workflow run package-acceptance.yml \
@ -402,34 +402,33 @@ gh workflow run package-acceptance.yml \
-f published_upgrade_survivor_baseline=openclaw@2026.4.26
```
profileهای رایج package:
پروفایل‌های رایج package:
- `smoke`: مسیرهای سریع نصب بسته/کانال/agent، شبکهٔ Gateway، و بارگذاری دوبارهٔ پیکربندی
- `package`: قراردادهای نصب/به‌روزرسانی/بستهٔ Plugin بدون ClawHub زنده؛ این پیش‌فرض بررسی انتشار است
- `product`: `package` به‌همراه کانال‌های MCP، پاک‌سازی cron/subagent، جست‌وجوی وب OpenAI، و OpenWebUI
- `smoke`: مسیرهای سریع نصب package/channel/agent، شبکه Gateway، و بارگذاری دوباره config
- `package`: قراردادهای نصب/به‌روزرسانی/Plugin package بدون ClawHub زنده؛ این پیش‌فرض release-check است
- `product`: `package` به‌همراه channelهای MCP، پاک‌سازی Cron/زیرعامل، جست‌وجوی وب OpenAI، و OpenWebUI
- `full`: بخش‌های مسیر انتشار Docker با OpenWebUI
- `custom`: فهرست دقیق `docker_lanes` برای اجرای دوبارهٔ متمرکز
- `custom`: فهرست دقیق `docker_lanes` برای اجرای دوباره متمرکز
برای اثبات Telegram نامزد بسته، `telegram_mode=mock-openai` یا
`telegram_mode=live-frontier` را در Package Acceptance فعال کنید. این گردش‌کار فایل tarball حل‌شدهٔ
`package-under-test` را به مسیر Telegram می‌دهد؛ گردش‌کار مستقل
Telegram همچنان برای بررسی‌های پس از انتشار، یک مشخصات npm منتشرشده را می‌پذیرد.
برای اثبات Telegram نامزد package، `telegram_mode=mock-openai` یا
`telegram_mode=live-frontier` را در Package Acceptance فعال کنید. workflow، فایل tarball حل‌شده
`package-under-test` را به مسیر Telegram می‌دهد؛ workflow مستقل
Telegram همچنان یک مشخصه منتشرشده npm را برای بررسی‌های پس از انتشار می‌پذیرد.
## خودکارسازی انتشار نسخه
## خودکارسازی انتشار release
`OpenClaw Release Publish` نقطهٔ ورود عادی انتشار تغییردهنده است. این گردش‌کار،
گردش‌کارهای ناشر معتمد را به ترتیبی که انتشار نیاز دارد هماهنگ می‌کند:
`OpenClaw Release Publish` نقطه ورود معمول انتشار تغییردهنده است. این workflowهای trusted-publisher را به ترتیبی که release نیاز دارد هماهنگ می‌کند:
1. tag انتشار را check out کنید و SHA کامیت آن را حل کنید.
2. تأیید کنید که tag از `main` یا `release/*` قابل دسترسی است.
3. `pnpm plugins:sync:check` را اجرا کنید.
1. تگ release را check out می‌کند و commit SHA آن را حل می‌کند.
2. بررسی می‌کند که تگ از `main` یا `release/*` قابل دسترسی باشد.
3. `pnpm plugins:sync:check` را اجرا می‌کند.
4. `Plugin NPM Release` را با `publish_scope=all-publishable` و
`ref=<release-sha>` dispatch کنید.
5. `Plugin ClawHub Release` را با همان دامنه و SHA dispatch کنید.
6. `OpenClaw NPM Release` را با tag انتشار، dist-tag در npm، و
`preflight_run_id` ذخیره‌شده dispatch کنید.
`ref=<release-sha>` dispatch می‌کند.
5. `Plugin ClawHub Release` را با همان scope و SHA dispatch می‌کند.
6. `OpenClaw NPM Release` را با تگ release، dist-tag مربوط به npm، و
`preflight_run_id` ذخیره‌شده dispatch می‌کند.
نمونهٔ انتشار Beta:
نمونه انتشار beta:
```bash
gh workflow run openclaw-release-publish.yml \
@ -439,7 +438,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
انتشار Stable به dist-tag پیش‌فرض beta:
انتشار پایدار به dist-tag پیش‌فرض beta:
```bash
gh workflow run openclaw-release-publish.yml \
@ -449,7 +448,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
ارتقای Stable مستقیماً به `latest` صریح است:
ارتقای پایدار مستقیما به `latest` صریح است:
```bash
gh workflow run openclaw-release-publish.yml \
@ -459,76 +458,68 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=latest
```
از گردش‌کارهای سطح پایین‌تر `Plugin NPM Release` و `Plugin ClawHub Release`
فقط برای کارهای تعمیر یا انتشار دوبارهٔ متمرکز استفاده کنید. برای تعمیر یک Plugin انتخاب‌شده،
از workflowهای سطح پایین‌تر `Plugin NPM Release` و `Plugin ClawHub Release` فقط برای کار تعمیر یا بازنشر متمرکز استفاده کنید. برای تعمیر یک Plugin انتخاب‌شده،
`plugin_publish_scope=selected` و `plugins=@openclaw/name` را به
`OpenClaw Release Publish` بدهید، یا هنگامی که بستهٔ
OpenClaw نباید منتشر شود، گردش‌کار فرزند را مستقیماً dispatch کنید.
`OpenClaw Release Publish` بدهید، یا وقتی package مربوط به OpenClaw نباید منتشر شود، workflow فرزند را مستقیما dispatch کنید.
## ورودی‌های گردش‌کار NPM
## ورودی‌های workflow مربوط به NPM
`OpenClaw NPM Release` این ورودی‌های کنترل‌شده توسط اپراتور را می‌پذیرد:
`OpenClaw NPM Release` این ورودی‌های کنترل‌شده توسط operator را می‌پذیرد:
- `tag`: tag انتشار الزامی مانند `v2026.4.2`، `v2026.4.2-1`، یا
`v2026.4.2-beta.1`؛ هنگامی که `preflight_only=true` است، می‌تواند SHA کامل ۴۰نویسه‌ای کامیت شاخهٔ گردش‌کار فعلی برای preflight فقط اعتبارسنجی نیز باشد
- `preflight_only`: `true` برای فقط اعتبارسنجی/ساخت/بسته، `false` برای مسیر انتشار واقعی
- `preflight_run_id`: در مسیر انتشار واقعی الزامی است تا گردش‌کار از tarball آماده‌شدهٔ اجرای موفق preflight دوباره استفاده کند
- `npm_dist_tag`: tag هدف npm برای مسیر انتشار؛ مقدار پیش‌فرض `beta` است
- `tag`: تگ release الزامی مانند `v2026.4.2`، `v2026.4.2-1`، یا
`v2026.4.2-beta.1`؛ وقتی `preflight_only=true` باشد، برای preflight فقط اعتبارسنجی می‌تواند SHA کامل ۴۰ کاراکتری commit فعلی شاخه workflow هم باشد
- `preflight_only`: مقدار `true` فقط برای اعتبارسنجی/ساخت/package، و `false` برای مسیر انتشار واقعی
- `preflight_run_id`: در مسیر انتشار واقعی الزامی است تا workflow از tarball آماده‌شده اجرای preflight موفق دوباره استفاده کند
- `npm_dist_tag`: تگ هدف npm برای مسیر انتشار؛ پیش‌فرض آن `beta` است
`OpenClaw Release Publish` این ورودی‌های کنترل‌شده توسط اپراتور را می‌پذیرد:
`OpenClaw Release Publish` این ورودی‌های کنترل‌شده توسط operator را می‌پذیرد:
- `tag`: tag انتشار الزامی؛ باید از قبل وجود داشته باشد
- `preflight_run_id`: شناسهٔ اجرای موفق preflight از `OpenClaw NPM Release`؛
هنگامی که `publish_openclaw_npm=true` است الزامی است
- `npm_dist_tag`: tag هدف npm برای بستهٔ OpenClaw
- `plugin_publish_scope`: مقدار پیش‌فرض `all-publishable` است؛ فقط
برای کار تعمیر متمرکز از `selected` استفاده کنید
- `plugins`: نام‌های بستهٔ `@openclaw/*` جداشده با کاما هنگامی که
`plugin_publish_scope=selected` است
- `publish_openclaw_npm`: مقدار پیش‌فرض `true` است؛ فقط هنگامی آن را `false` تنظیم کنید که از گردش‌کار به‌عنوان هماهنگ‌کنندهٔ تعمیر فقط Plugin استفاده می‌کنید
- `tag`: تگ release الزامی؛ باید از قبل وجود داشته باشد
- `preflight_run_id`: شناسه اجرای preflight موفق `OpenClaw NPM Release`؛
وقتی `publish_openclaw_npm=true` باشد الزامی است
- `npm_dist_tag`: تگ هدف npm برای package مربوط به OpenClaw
- `plugin_publish_scope`: پیش‌فرض آن `all-publishable` است؛ فقط برای کار تعمیر متمرکز از `selected` استفاده کنید
- `plugins`: نام‌های package با جداکننده ویرگول از نوع `@openclaw/*` وقتی
`plugin_publish_scope=selected` باشد
- `publish_openclaw_npm`: پیش‌فرض آن `true` است؛ فقط وقتی workflow را به‌عنوان هماهنگ‌کننده تعمیر صرفا Plugin استفاده می‌کنید، آن را `false` تنظیم کنید
`OpenClaw Release Checks` این ورودی‌های کنترل‌شده توسط اپراتور را می‌پذیرد:
`OpenClaw Release Checks` این ورودی‌های کنترل‌شده توسط operator را می‌پذیرد:
- `ref`: شاخه، tag، یا SHA کامل کامیت برای اعتبارسنجی. بررسی‌های دارای secret نیاز دارند کامیت حل‌شده از یک شاخهٔ OpenClaw یا tag انتشار قابل دسترسی باشد.
- `ref`: شاخه، تگ، یا SHA کامل commit برای اعتبارسنجی. بررسی‌های دارای secret نیاز دارند commit حل‌شده از یک شاخه OpenClaw یا تگ release قابل دسترسی باشد.
قواعد:
- tagهای Stable و اصلاحی می‌توانند به `beta` یا `latest` منتشر شوند
- tagهای پیش‌انتشار Beta فقط می‌توانند به `beta` منتشر شوند
- برای `OpenClaw NPM Release`، ورودی SHA کامل کامیت فقط هنگامی مجاز است که
- تگ‌های پایدار و اصلاحی می‌توانند در `beta` یا `latest` منتشر شوند
- تگ‌های پیش‌انتشار beta فقط می‌توانند در `beta` منتشر شوند
- برای `OpenClaw NPM Release`، ورودی SHA کامل commit فقط وقتی مجاز است که
`preflight_only=true` باشد
- `OpenClaw Release Checks` و `Full Release Validation` همیشه فقط اعتبارسنجی هستند
- مسیر انتشار واقعی باید از همان `npm_dist_tag` استفاده کند که هنگام preflight استفاده شده است؛
گردش‌کار پیش از ادامهٔ انتشار آن metadata را تأیید می‌کند
- مسیر انتشار واقعی باید از همان `npm_dist_tag` استفاده کند که در preflight استفاده شده است؛ workflow پیش از ادامه انتشار، آن metadata را بررسی می‌کند
## توالی انتشار Stable در npm
## توالی release پایدار npm
هنگام ساخت یک انتشار Stable در npm:
هنگام ایجاد یک release پایدار npm:
1. `OpenClaw NPM Release` را با `preflight_only=true` اجرا کنید
- پیش از وجود tag، می‌توانید از SHA کامل کامیت شاخهٔ گردش‌کار فعلی برای اجرای آزمایشی فقط اعتبارسنجی گردش‌کار preflight استفاده کنید
2. برای جریان عادی beta-first، `npm_dist_tag=beta` را انتخاب کنید، یا فقط هنگامی `latest` را انتخاب کنید که عمداً انتشار مستقیم Stable می‌خواهید
3. هنگامی که پوشش عادی CI به‌همراه prompt cache زنده، Docker، QA Lab،
Matrix، و Telegram را از یک گردش‌کار دستی می‌خواهید، `Full Release Validation` را روی شاخهٔ انتشار، tag انتشار، یا SHA کامل کامیت اجرا کنید
4. اگر عمداً فقط به گراف آزمون عادی قطعی نیاز دارید، به‌جای آن گردش‌کار دستی `CI` را روی ref انتشار اجرا کنید
- پیش از وجود تگ، می‌توانید از SHA کامل commit فعلی شاخه workflow برای اجرای آزمایشی فقط اعتبارسنجی workflow مربوط به preflight استفاده کنید
2. برای جریان عادی beta-first، `npm_dist_tag=beta` را انتخاب کنید، یا فقط وقتی عمدا انتشار پایدار مستقیم می‌خواهید `latest` را انتخاب کنید
3. وقتی می‌خواهید CI عادی به‌همراه پوشش live prompt cache، Docker، QA Lab،
Matrix، و Telegram را از یک workflow دستی داشته باشید، `Full Release Validation` را روی شاخه release، تگ release، یا SHA کامل commit اجرا کنید
4. اگر عمدا فقط به گراف تست عادی قطعی نیاز دارید، به‌جای آن workflow دستی `CI` را روی ref مربوط به release اجرا کنید
5. `preflight_run_id` موفق را ذخیره کنید
6. `OpenClaw Release Publish` را با همان `tag`، همان `npm_dist_tag`،
و `preflight_run_id` ذخیره‌شده اجرا کنید؛ این کار Pluginهای externalized را پیش از ارتقای بستهٔ npm مربوط به OpenClaw در npm و ClawHub منتشر می‌کند
7. اگر انتشار روی `beta` قرار گرفت، از گردش‌کار خصوصی
و `preflight_run_id` ذخیره‌شده اجرا کنید؛ این کار Pluginهای externalized را پیش از ارتقای package npm مربوط به OpenClaw در npm و ClawHub منتشر می‌کند
7. اگر release روی `beta` فرود آمد، از workflow خصوصی
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
برای ارتقای آن نسخهٔ Stable از `beta` به `latest` استفاده کنید
8. اگر انتشار عمداً مستقیماً روی `latest` منتشر شد و `beta`
باید فوراً همان ساخت Stable را دنبال کند، از همان گردش‌کار خصوصی استفاده کنید تا هر دو dist-tag را به نسخهٔ Stable اشاره دهید، یا اجازه دهید همگام‌سازی خودترمیمی زمان‌بندی‌شدهٔ آن بعداً `beta` را جابه‌جا کند
برای ارتقای آن نسخه پایدار از `beta` به `latest` استفاده کنید
8. اگر release عمدا مستقیما روی `latest` منتشر شد و `beta` باید بلافاصله همان build پایدار را دنبال کند، از همان workflow خصوصی استفاده کنید تا هر دو dist-tag را به نسخه پایدار اشاره دهد، یا اجازه دهید همگام‌سازی خودترمیم زمان‌بندی‌شده آن بعدا `beta` را جابه‌جا کند
جهش dist-tag به‌دلایل امنیتی در مخزن خصوصی قرار دارد، چون همچنان به
`NPM_TOKEN` نیاز دارد، در حالی که مخزن عمومی انتشار فقط OIDC را نگه می‌دارد.
تغییر dist-tag به دلایل امنیتی در repo خصوصی قرار دارد، چون همچنان به
`NPM_TOKEN` نیاز دارد، در حالی که repo عمومی انتشار فقط با OIDC را حفظ می‌کند.
این کار هر دو مسیر انتشار مستقیم و مسیر ارتقای beta-first را مستند و برای اپراتور قابل مشاهده نگه می‌دارد.
این کار هر دو مسیر انتشار مستقیم و مسیر ارتقای beta-first را مستند و برای operator قابل مشاهده نگه می‌دارد.
اگر یک maintainer ناچار است به احراز هویت محلی npm برگردد، هر فرمان 1Password
CLI (`op`) را فقط داخل یک نشست اختصاصی tmux اجرا کند. `op` را
مستقیماً از پوستهٔ اصلی agent فراخوانی نکنید؛ نگه‌داشتن آن داخل tmux باعث می‌شود promptها،
هشدارها، و مدیریت OTP قابل مشاهده باشند و از هشدارهای تکراری میزبان جلوگیری شود.
اگر یک maintainer ناچار شود به احراز هویت محلی npm برگردد، هر دستور CLI مربوط به 1Password (`op`) را فقط داخل یک نشست tmux اختصاصی اجرا کنید. `op` را مستقیما از shell اصلی agent فراخوانی نکنید؛ نگه داشتن آن داخل tmux باعث می‌شود promptها، هشدارها، و مدیریت OTP قابل مشاهده باشند و از هشدارهای تکراری میزبان جلوگیری می‌کند.
## ارجاع‌های عمومی
@ -542,10 +533,10 @@ CLI (`op`) را فقط داخل یک نشست اختصاصی tmux اجرا کن
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
maintainerها برای runbook واقعی از مستندات انتشار خصوصی در
maintainerها برای runbook واقعی از مستندات خصوصی release در
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
استفاده می‌کنند.
## مرتبط
- [کانال‌های انتشار](/fa/install/development-channels)
- [کانال‌های release](/fa/install/development-channels)

149
docs/fa/security/network-proxy.md
View File

@ -1,40 +1,40 @@
---
read_when:
- می‌خواهید در برابر حملات SSRF و بازاتصال DNS دفاع در عمق داشته باشید
- پیکربندی یک پروکسی فوروارد خارجی برای ترافیک زمان اجرای OpenClaw
summary: نحوهٔ مسیریابی ترافیک HTTP و WebSocket زمان اجرای OpenClaw از طریق یک پروکسی فیلترکنندهٔ مدیریت‌شده توسط اپراتور
- شما به دفاع در عمق در برابر حملات SSRF و بازپیوند DNS نیاز دارید
- پیکربندی یک پروکسی رو به جلو خارجی برای ترافیک زمان اجرای OpenClaw
summary: نحوهٔ هدایت ترافیک HTTP و WebSocket زمان اجرای OpenClaw از طریق یک پروکسی فیلترکنندهٔ تحت مدیریت اپراتور
title: پروکسی شبکه
x-i18n:
generated_at: "2026-05-04T02:27:21Z"
generated_at: "2026-05-04T07:07:45Z"
model: gpt-5.5
provider: openai
source_hash: cd5594324e8c6b7da51d903e98fda0feacb8970e0b15d980f7a249d6641461c9
source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0
source_path: security/network-proxy.md
workflow: 16
---
# پراکسی شبکه
# پروکسی شبکه
OpenClaw می‌تواند ترافیک HTTP و WebSocket زمان اجرا را از طریق یک پراکسی رو‌به‌جلو که توسط اپراتور مدیریت می‌شود مسیریابی کند. این یک دفاع در عمق اختیاری برای استقرارهایی است که کنترل مرکزی خروجی شبکه، محافظت قوی‌تر در برابر SSRF، و قابلیت ممیزی بهتر شبکه می‌خواهند.
OpenClaw می‌تواند ترافیک HTTP و WebSocket زمان اجرا را از طریق یک پروکسی ارسالِ مدیریت‌شده توسط اپراتور مسیریابی کند. این یک دفاع اختیاریِ چندلایه برای استقرارهایی است که کنترل مرکزی خروجی، حفاظت قوی‌تر در برابر SSRF، و قابلیت ممیزی بهتر شبکه می‌خواهند.
OpenClaw هیچ پراکسی‌ای را همراه خود ارائه، دانلود، راه‌اندازی، پیکربندی، یا تأیید نمی‌کند. شما فناوری پراکسی متناسب با محیط خود را اجرا می‌کنید، و OpenClaw کلاینت‌های معمول HTTP و WebSocket محلیِ فرایند را از طریق آن مسیریابی می‌کند.
OpenClaw هیچ پروکسی‌ای را همراه خود ارائه، دانلود، راه‌اندازی، پیکربندی یا تأیید نمی‌کند. شما فناوری پروکسی متناسب با محیط خود را اجرا می‌کنید، و OpenClaw کلاینت‌های معمول HTTP و WebSocket محلیِ فرایند را از طریق آن مسیریابی می‌کند.
## چرا از پراکسی استفاده کنیم؟
## چرا از پروکسی استفاده کنیم؟
پراکسی به اپراتورها یک نقطه کنترل شبکه برای ترافیک خروجی HTTP و WebSocket می‌دهد. این حتی خارج از سخت‌سازی SSRF هم می‌تواند مفید باشد:
پروکسی به اپراتورها یک نقطه کنترل شبکه برای ترافیک خروجی HTTP و WebSocket می‌دهد. این موضوع حتی خارج از سخت‌سازی SSRF هم می‌تواند مفید باشد:
- سیاست مرکزی: به‌جای اتکا به اینکه هر محل فراخوانی HTTP در برنامه قوانین شبکه را درست اعمال کند، یک سیاست خروجی واحد نگه دارید.
- بررسی‌های زمان اتصال: مقصد را پس از حل DNS و بلافاصله پیش از آنکه پراکسی اتصال بالادستی را باز کند ارزیابی کنید.
- سیاست مرکزی: به‌جای تکیه بر اینکه هر محل فراخوانی HTTP در برنامه قواعد شبکه را درست اعمال کند، یک سیاست خروجی واحد را نگه‌داری کنید.
- بررسی‌های زمان اتصال: مقصد را پس از حل DNS و درست پیش از اینکه پروکسی اتصال بالادستی را باز کند ارزیابی کنید.
- دفاع در برابر DNS rebinding: فاصله بین بررسی DNS در سطح برنامه و اتصال خروجی واقعی را کاهش دهید.
- پوشش گسترده‌تر JavaScript: کلاینت‌های معمول `fetch`، `node:http`، `node:https`، WebSocket، axios، got، node-fetch و کلاینت‌های مشابه را از همان مسیر عبور دهید.
- پوشش گسترده‌تر JavaScript: کلاینت‌های معمول `fetch`، `node:http`، `node:https`، WebSocket، axios، got، node-fetch، و کلاینت‌های مشابه را از همان مسیر عبور دهید.
- قابلیت ممیزی: مقصدهای مجاز و ردشده را در مرز خروجی ثبت کنید.
- کنترل عملیاتی: قوانین مقصد، جداسازی شبکه، محدودیت نرخ، یا فهرست‌های مجاز خروجی را بدون بازسازی OpenClaw اعمال کنید.
- کنترل عملیاتی: قواعد مقصد، جداسازی شبکه، محدودیت‌های نرخ، یا فهرست‌های مجاز خروجی را بدون بازسازی OpenClaw اعمال کنید.
مسیریابی پراکسی یک محافظ در سطح فرایند برای خروجی معمول HTTP و WebSocket است. این به اپراتورها یک مسیر fail-closed برای مسیریابی کلاینت‌های HTTP پشتیبانی‌شده JavaScript از طریق پراکسی فیلترکننده خودشان می‌دهد، اما یک سندباکس شبکه در سطح سیستم‌عامل نیست و باعث نمی‌شود OpenClaw سیاست مقصد پراکسی را تأیید کند.
مسیریابی پروکسی یک حفاظ در سطح فرایند برای خروجی معمول HTTP و WebSocket است. این قابلیت به اپراتورها یک مسیر fail-closed برای مسیریابی کلاینت‌های HTTP پشتیبانی‌شده JavaScript از طریق پروکسی فیلترکننده خودشان می‌دهد، اما یک سندباکس شبکه در سطح سیستم‌عامل نیست و باعث نمی‌شود OpenClaw سیاست مقصد پروکسی را تأیید کند.
## OpenClaw چگونه ترافیک را مسیریابی می‌کند
وقتی `proxy.enabled=true` باشد و یک URL پراکسی پیکربندی شده باشد، فرایندهای محافظت‌شده زمان اجرا مانند `openclaw gateway run`، `openclaw node run`، و `openclaw agent --local` خروجی معمول HTTP و WebSocket را از طریق پراکسی پیکربندی‌شده مسیریابی می‌کنند:
وقتی `proxy.enabled=true` و یک URL پروکسی پیکربندی شده باشد، فرایندهای محافظت‌شده زمان اجرا مانند `openclaw gateway run`، `openclaw node run`، و `openclaw agent --local` خروجی معمول HTTP و WebSocket را از طریق پروکسی پیکربندی‌شده مسیریابی می‌کنند:
```text
OpenClaw process
@ -43,27 +43,27 @@ OpenClaw process
WebSocket clients -> operator-managed filtering proxy -> public internet
```
قرارداد عمومی، رفتار مسیریابی است، نه hookهای داخلی Node که برای پیاده‌سازی آن استفاده می‌شوند. کلاینت‌های WebSocket سطح کنترل OpenClaw Gateway وقتی URL Gateway از `localhost` یا یک IP loopback لفظی مانند `127.0.0.1` یا `[::1]` استفاده می‌کند، برای ترافیک RPC مربوط به Gateway در local loopback از یک مسیر مستقیم محدود استفاده می‌کنند. این مسیر سطح کنترل باید بتواند به Gatewayهای loopback دسترسی داشته باشد، حتی وقتی پراکسی اپراتور مقصدهای loopback را مسدود می‌کند. درخواست‌های معمول HTTP و WebSocket زمان اجرا همچنان از پراکسی پیکربندی‌شده استفاده می‌کنند.
قرارداد عمومی، رفتار مسیریابی است، نه هوک‌های داخلی Node که برای پیاده‌سازی آن استفاده می‌شوند. کلاینت‌های WebSocket صفحه کنترل OpenClaw Gateway برای ترافیک RPC مربوط به local loopback Gateway، وقتی URL Gateway از `localhost` یا یک IP لوپ‌بک صریح مانند `127.0.0.1` یا `[::1]` استفاده می‌کند، از یک مسیر مستقیم محدود استفاده می‌کنند. آن مسیر صفحه کنترل باید بتواند به Gatewayهای لوپ‌بک برسد، حتی زمانی که پروکسی اپراتور مقصدهای لوپ‌بک را مسدود می‌کند. درخواست‌های معمول HTTP و WebSocket زمان اجرا همچنان از پروکسی پیکربندی‌شده استفاده می‌کنند.
در داخل، OpenClaw برای این قابلیت از دو hook مسیریابی در سطح فرایند استفاده می‌کند:
در داخل، OpenClaw برای این قابلیت از دو هوک مسیریابی در سطح فرایند استفاده می‌کند:
- مسیریابی dispatcher در Undici شامل `fetch`، کلاینت‌های مبتنی بر undici، و transportهایی می‌شود که dispatcher undici خودشان را فراهم می‌کنند.
- مسیریابی `global-agent` شامل فراخوان‌های هسته Node برای `node:http` و `node:https` می‌شود، از جمله بسیاری از کتابخانه‌هایی که روی `http.request`، `https.request`، `http.get`، و `https.get` ساخته شده‌اند. حالت پراکسی مدیریت‌شده آن global agent را اجباری می‌کند تا عامل‌های HTTP صریح Node تصادفاً پراکسی اپراتور را دور نزنند.
- مسیریابی dispatcher در Undici شامل `fetch`، کلاینت‌های مبتنی بر undici، و انتقال‌هایی می‌شود که dispatcher اختصاصی undici خود را ارائه می‌کنند.
- مسیریابی `global-agent` فراخوان‌های هسته Node یعنی `node:http` و `node:https` را پوشش می‌دهد، از جمله بسیاری از کتابخانه‌هایی که روی `http.request`، `https.request`، `http.get`، و `https.get` ساخته شده‌اند. حالت پروکسی مدیریت‌شده آن عامل سراسری را اجبار می‌کند تا عامل‌های صریح HTTP در Node به‌طور تصادفی پروکسی اپراتور را دور نزنند.
برخی Pluginها transportهای سفارشی خودشان را دارند که حتی وقتی مسیریابی در سطح فرایند وجود دارد، به سیم‌کشی صریح پراکسی نیاز دارند. برای مثال، transport مربوط به Bot API در Telegram از dispatcher اختصاصی HTTP/1 undici خودش استفاده می‌کند و بنابراین env پراکسی فرایند به‌علاوه fallback مدیریت‌شده `OPENCLAW_PROXY_URL` را در آن مسیر transport مالک‌محور رعایت می‌کند.
برخی Pluginها انتقال‌های سفارشی خود را دارند که حتی با وجود مسیریابی در سطح فرایند، به سیم‌کشی صریح پروکسی نیاز دارند. برای مثال، انتقال Bot API در Telegram از dispatcher اختصاصی HTTP/1 در undici استفاده می‌کند و بنابراین env پروکسی فرایند به‌همراه جایگزین مدیریت‌شده `OPENCLAW_PROXY_URL` را در آن مسیر انتقال مالک‌محور رعایت می‌کند.
خود URL پراکسی باید از `http://` استفاده کند. مقصدهای HTTPS همچنان از طریق پراکسی با HTTP `CONNECT` پشتیبانی می‌شوند؛ این فقط یعنی OpenClaw انتظار یک listener ساده HTTP برای پراکسی رو‌به‌جلو مانند `http://127.0.0.1:3128` را دارد.
خود URL پروکسی باید از `http://` استفاده کند. مقصدهای HTTPS همچنان از طریق پروکسی با HTTP `CONNECT` پشتیبانی می‌شوند؛ این فقط یعنی OpenClaw انتظار یک شنونده پروکسی ارسال HTTP ساده مانند `http://127.0.0.1:3128` را دارد.
وقتی پراکسی فعال است، OpenClaw مقدارهای `no_proxy`، `NO_PROXY`، و `GLOBAL_AGENT_NO_PROXY` را پاک می‌کند. این فهرست‌های دورزدن مبتنی بر مقصد هستند، بنابراین باقی‌ماندن `localhost` یا `127.0.0.1` در آن‌ها باعث می‌شود مقصدهای پرریسک SSRF از پراکسی فیلترکننده عبور نکنند.
وقتی پروکسی فعال است، OpenClaw مقادیر `no_proxy`، `NO_PROXY`، و `GLOBAL_AGENT_NO_PROXY` را پاک می‌کند. این فهرست‌های دورزدن مبتنی بر مقصد هستند، بنابراین باقی گذاشتن `localhost` یا `127.0.0.1` در آن‌ها باعث می‌شود هدف‌های پرخطر SSRF از پروکسی فیلترکننده عبور نکنند.
هنگام خاموش شدن، OpenClaw محیط قبلی پراکسی را بازیابی می‌کند و وضعیت مسیریابی کش‌شده فرایند را بازنشانی می‌کند.
در زمان خاموشی، OpenClaw محیط پروکسی قبلی را بازیابی می‌کند و وضعیت مسیریابی فرایندِ کش‌شده را بازنشانی می‌کند.
## اصطلاحات مرتبط با پراکسی
## اصطلاحات مرتبط با پروکسی
- `proxy.enabled` / `proxy.proxyUrl`: مسیریابی پراکسی رو‌به‌جلو خروجی برای خروجی زمان اجرای OpenClaw. این صفحه آن قابلیت را مستند می‌کند.
- `gateway.auth.mode: "trusted-proxy"`: احراز هویت پراکسی معکوس ورودیِ آگاه از هویت برای دسترسی Gateway. [احراز هویت پراکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) را ببینید.
- `openclaw proxy`: پراکسی اشکال‌زدایی محلی و بازرس capture برای توسعه و پشتیبانی. [openclaw proxy](/fa/cli/proxy) را ببینید.
- تنظیمات پراکسی ویژه کانال یا ارائه‌دهنده: overrideهای مالک‌محور برای یک transport خاص. وقتی هدف کنترل مرکزی خروجی در سراسر زمان اجرا است، پراکسی شبکه مدیریت‌شده را ترجیح دهید.
- `proxy.enabled` / `proxy.proxyUrl`: مسیریابی پروکسی ارسال خروجی برای خروجی زمان اجرای OpenClaw. این صفحه همین قابلیت را مستند می‌کند.
- `gateway.auth.mode: "trusted-proxy"`: احراز هویت پروکسی معکوسِ آگاه از هویت برای دسترسی به Gateway. [احراز هویت پروکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) را ببینید.
- `openclaw proxy`: پروکسی اشکال‌زدایی محلی و بازرس ثبت ترافیک برای توسعه و پشتیبانی. [openclaw proxy](/fa/cli/proxy) را ببینید.
- تنظیمات پروکسی مخصوص کانال یا ارائه‌دهنده: بازنویسی‌های مالک‌محور برای یک انتقال مشخص. وقتی هدف کنترل مرکزی خروجی در سراسر زمان اجرا است، پروکسی شبکه مدیریت‌شده را ترجیح دهید.
## پیکربندی
@ -73,7 +73,7 @@ proxy:
proxyUrl: http://127.0.0.1:3128
```
همچنین می‌توانید URL را از طریق محیط ارائه کنید، در حالی که `proxy.enabled=true` را در پیکربندی نگه می‌دارید:
همچنین می‌توانید URL را از طریق محیط ارائه کنید، درحالی‌که `proxy.enabled=true` را در پیکربندی نگه می‌دارید:
```bash
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
@ -81,7 +81,7 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
`proxy.proxyUrl` بر `OPENCLAW_PROXY_URL` اولویت دارد.
اگر `enabled=true` باشد اما هیچ URL پراکسی معتبری پیکربندی نشده باشد، فرمان‌های محافظت‌شده به‌جای بازگشت به دسترسی مستقیم شبکه، در شروع اجرا شکست می‌خورند.
اگر `enabled=true` باشد اما هیچ URL معتبر پروکسی پیکربندی نشده باشد، فرمان‌های محافظت‌شده به‌جای بازگشت به دسترسی مستقیم شبکه، در شروع به‌کار شکست می‌خورند.
برای سرویس‌های Gateway مدیریت‌شده که با `openclaw gateway start` شروع می‌شوند، بهتر است URL را در پیکربندی ذخیره کنید:
@ -92,63 +92,63 @@ openclaw gateway install --force
openclaw gateway start
```
fallback محیط برای اجراهای foreground مناسب‌تر است. اگر از آن با یک سرویس نصب‌شده استفاده می‌کنید، `OPENCLAW_PROXY_URL` را در محیط پایدار سرویس، مانند `$OPENCLAW_STATE_DIR/.env` یا `~/.openclaw/.env`، قرار دهید و سپس سرویس را دوباره نصب کنید تا launchd، systemd، یا Scheduled Tasks، gateway را با آن مقدار شروع کند.
جایگزین محیطی برای اجراهای پیش‌زمینه مناسب‌تر است. اگر از آن با یک سرویس نصب‌شده استفاده می‌کنید، `OPENCLAW_PROXY_URL` را در محیط پایدار سرویس، مانند `$OPENCLAW_STATE_DIR/.env` یا `~/.openclaw/.env` قرار دهید، سپس سرویس را دوباره نصب کنید تا launchd، systemd، یا Scheduled Tasks، Gateway را با آن مقدار شروع کند.
برای فرمان‌های `openclaw --container ...`، OpenClaw وقتی `OPENCLAW_PROXY_URL` تنظیم شده باشد آن را به CLI فرزند هدف‌گیری‌شده برای کانتینر ارسال می‌کند. URL باید از داخل کانتینر قابل دسترسی باشد؛ `127.0.0.1` به خود کانتینر اشاره می‌کند، نه میزبان. OpenClaw برای فرمان‌های هدف‌گیری‌شده به کانتینر، URLهای پراکسی loopback را رد می‌کند مگر اینکه آن بررسی ایمنی را صریحاً override کنید.
برای فرمان‌های `openclaw --container ...`، وقتی `OPENCLAW_PROXY_URL` تنظیم شده باشد، OpenClaw آن را به CLI فرزند هدف‌گیری‌شده برای کانتینر ارسال می‌کند. URL باید از داخل کانتینر قابل دسترسی باشد؛ `127.0.0.1` به خود کانتینر اشاره می‌کند، نه میزبان. OpenClaw برای فرمان‌های هدف‌گیری‌شده برای کانتینر، URLهای پروکسی لوپ‌بک را رد می‌کند، مگر اینکه آن بررسی ایمنی را به‌صورت صریح بازنویسی کنید.
## الزامات پراکسی
## الزامات پروکسی
سیاست پراکسی مرز امنیتی است. OpenClaw نمی‌تواند تأیید کند که پراکسی مقصدهای درست را مسدود می‌کند.
سیاست پروکسی مرز امنیتی است. OpenClaw نمی‌تواند تأیید کند که پروکسی هدف‌های درست را مسدود می‌کند.
پراکسی را طوری پیکربندی کنید که:
پروکسی را طوری پیکربندی کنید که:
- فقط به loopback یا یک interface خصوصی و مورد اعتماد bind شود.
- فقط به لوپ‌بک یا یک رابط خصوصی مورد اعتماد bind شود.
- دسترسی را محدود کند تا فقط فرایند، میزبان، کانتینر، یا حساب سرویس OpenClaw بتواند از آن استفاده کند.
- مقصدها را خودش resolve کند و IPهای مقصد را پس از حل DNS مسدود کند.
- سیاست را هنگام اتصال، هم برای درخواست‌های HTTP ساده و هم برای تونل‌های HTTPS `CONNECT`، اعمال کند.
- دورزدن‌های مبتنی بر مقصد را برای محدوده‌های loopback، خصوصی، link-local، metadata، multicast، reserved، یا documentation رد کند.
- از فهرست‌های مجاز hostname پرهیز کند مگر اینکه به مسیر حل DNS کاملاً اعتماد دارید.
- مقصد، تصمیم، وضعیت، و دلیل را بدون ثبت بدنه‌های درخواست، headerهای authorization، cookieها، یا سایر secretها ثبت کند.
- سیاست پراکسی را تحت کنترل نسخه نگه دارد و تغییرات را مانند پیکربندی حساس امنیتی بازبینی کند.
- سیاست را در زمان اتصال، هم برای درخواست‌های HTTP ساده و هم برای تونل‌های HTTPS `CONNECT` اعمال کند.
- دورزدن‌های مبتنی بر مقصد را برای محدوده‌های لوپ‌بک، خصوصی، link-local، metadata، multicast، reserved، یا documentation رد کند.
- از فهرست‌های مجاز نام میزبان پرهیز کند، مگر اینکه مسیر حل DNS را کاملاً قابل اعتماد بدانید.
- مقصد، تصمیم، وضعیت، و دلیل را بدون ثبت بدنه درخواست‌ها، سرآیندهای مجوز، کوکی‌ها، یا سایر اسرار ثبت کند.
- سیاست پروکسی را تحت کنترل نسخه نگه دارد و تغییرات را مانند پیکربندی حساس امنیتی بازبینی کند.
## مقصدهای مسدودشده پیشنهادی
از این denylist به‌عنوان نقطه شروع برای هر پراکسی رو‌به‌جلو، firewall، یا سیاست خروجی استفاده کنید.
از این فهرست انکار به‌عنوان نقطه شروع برای هر پروکسی ارسال، فایروال، یا سیاست خروجی استفاده کنید.
منطق classifier سطح برنامه OpenClaw در `src/infra/net/ssrf.ts` و `src/shared/net/ip.ts` قرار دارد. hookهای parity مرتبط عبارت‌اند از `BLOCKED_HOSTNAMES`، `BLOCKED_IPV4_SPECIAL_USE_RANGES`، `BLOCKED_IPV6_SPECIAL_USE_RANGES`، `RFC2544_BENCHMARK_PREFIX`، و مدیریت sentinel تعبیه‌شده IPv4 برای NAT64، 6to4، Teredo، ISATAP، و فرم‌های IPv4-mapped. این فایل‌ها هنگام نگهداری یک سیاست پراکسی خارجی مرجع‌های مفیدی هستند، اما OpenClaw آن قوانین را به‌صورت خودکار در پراکسی شما صادر یا اعمال نمی‌کند.
منطق طبقه‌بندی در سطح برنامه OpenClaw در `src/infra/net/ssrf.ts` و `src/shared/net/ip.ts` قرار دارد. هوک‌های هم‌ارزی مرتبط `BLOCKED_HOSTNAMES`، `BLOCKED_IPV4_SPECIAL_USE_RANGES`، `BLOCKED_IPV6_SPECIAL_USE_RANGES`، `RFC2544_BENCHMARK_PREFIX`، و مدیریت sentinel داخلی IPv4 برای NAT64، 6to4، Teredo، ISATAP، و فرم‌های نگاشت‌شده به IPv4 هستند. این فایل‌ها هنگام نگه‌داری سیاست پروکسی خارجی منابع مفیدی هستند، اما OpenClaw آن قواعد را به‌طور خودکار در پروکسی شما صادر یا اعمال نمی‌کند.
| محدوده یا میزبان | دلیل مسدود کردن |
| محدوده یا میزبان | دلیل مسدودسازی |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback |
| `::1/128` | IPv6 loopback |
| `0.0.0.0/8`, `::/128` | آدرس‌های نامشخص و این-شبکه |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | شبکه‌های خصوصی RFC1918 |
| `169.254.0.0/16`, `fe80::/10` | آدرس‌های link-local و مسیرهای رایج metadata ابری |
| `169.254.169.254`, `metadata.google.internal` | سرویس‌های metadata ابری |
| `100.64.0.0/10` | فضای آدرس مشترک NAT در سطح carrier |
| `198.18.0.0/15`, `2001:2::/48` | محدوده‌های benchmarking |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | محدوده‌های special-use و documentation |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | IPv4 رزرو‌شده |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | لوپ‌بک IPv4 |
| `::1/128` | لوپ‌بک IPv6 |
| `0.0.0.0/8`, `::/128` | نشانی‌های نامشخص و این-شبکه |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | شبکه‌های خصوصی RFC1918 |
| `169.254.0.0/16`, `fe80::/10` | نشانی‌های Link-local و مسیرهای رایج metadata ابری |
| `169.254.169.254`, `metadata.google.internal` | سرویس‌های metadata ابری |
| `100.64.0.0/10` | فضای نشانی مشترک NAT در سطح حامل |
| `198.18.0.0/15`, `2001:2::/48` | محدوده‌های بنچمارک |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | محدوده‌های استفاده ویژه و مستندسازی |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | IPv4 رزروشده |
| `fc00::/7`, `fec0::/10` | محدوده‌های محلی/خصوصی IPv6 |
| `100::/64`, `2001:20::/28` | محدوده‌های IPv6 discard و ORCHIDv2 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | پیشوندهای NAT64 با IPv4 تعبیه‌شده |
| `2002::/16`, `2001::/32` | 6to4 و Teredo با IPv4 تعبیه‌شده |
| `::/96`, `::ffff:0:0/96` | IPv6 سازگار با IPv4 و IPv4-mapped |
| `100::/64`, `2001:20::/28` | محدوده‌های discard و ORCHIDv2 در IPv6 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | پیشوندهای NAT64 با IPv4 جاسازی‌شده |
| `2002::/16`, `2001::/32` | 6to4 و Teredo با IPv4 جاسازی‌شده |
| `::/96`, `::ffff:0:0/96` | IPv6 سازگار با IPv4 و IPv6 نگاشت‌شده به IPv4 |
اگر ارائه‌دهنده ابر یا پلتفرم شبکه شما میزبان‌های metadata یا محدوده‌های رزروشده بیشتری را مستند کرده است، آن‌ها را هم اضافه کنید.
اگر ارائه‌دهنده ابر یا پلتفرم شبکه شما میزبان‌های metadata یا محدوده‌های رزروشده بیشتری را مستند کرده است، آن‌ها را نیز اضافه کنید.
## اعتبارسنجی
پراکسی را از همان میزبان، کانتینر، یا حساب سرویسی که OpenClaw را اجرا می‌کند اعتبارسنجی کنید:
پروکسی را از همان میزبان، کانتینر، یا حساب سرویسی که OpenClaw را اجرا می‌کند اعتبارسنجی کنید:
```bash
openclaw proxy validate --proxy-url http://127.0.0.1:3128
```
به‌صورت پیش‌فرض، وقتی مقصدهای سفارشی ارائه نشده باشند، فرمان بررسی می‌کند که `https://example.com/` موفق شود و یک canary موقت loopback را شروع می‌کند که پراکسی نباید به آن برسد. بررسی ردشده پیش‌فرض وقتی موفق است که پراکسی یک پاسخ denial غیر-2xx برگرداند یا canary را با شکست transport مسدود کند؛ اگر پاسخ موفق به canary برسد، شکست می‌خورد. اگر هیچ پراکسی‌ای فعال و پیکربندی نشده باشد، اعتبارسنجی یک مشکل پیکربندی گزارش می‌کند؛ برای یک preflight یک‌باره پیش از تغییر پیکربندی از `--proxy-url` استفاده کنید. برای آزمودن انتظارهای ویژه استقرار از `--allowed-url` و `--denied-url` استفاده کنید. مقصدهای ردشده سفارشی fail-closed هستند: هر پاسخ HTTP یعنی مقصد از طریق پراکسی قابل دسترسی بوده است، و هر خطای transport به‌عنوان نامشخص گزارش می‌شود چون OpenClaw نمی‌تواند ثابت کند پراکسی یک origin قابل دسترسی را مسدود کرده است. در صورت شکست اعتبارسنجی، فرمان با کد 1 خارج می‌شود.
به‌طور پیش‌فرض، وقتی مقصدهای سفارشی ارائه نشده باشند، فرمان بررسی می‌کند که `https://example.com/` موفق شود و یک قناری موقت لوپ‌بک را شروع می‌کند که پروکسی نباید به آن برسد. بررسی ردشده پیش‌فرض زمانی قبول می‌شود که پروکسی یک پاسخ رد غیر 2xx برگرداند یا قناری را با شکست انتقال مسدود کند؛ اگر یک پاسخ موفق به قناری برسد، شکست می‌خورد. اگر هیچ پروکسی‌ای فعال و پیکربندی نشده باشد، اعتبارسنجی یک مشکل پیکربندی را گزارش می‌کند؛ برای یک preflight یک‌باره پیش از تغییر پیکربندی از `--proxy-url` استفاده کنید. برای آزمون انتظارهای مخصوص استقرار از `--allowed-url` و `--denied-url` استفاده کنید. مقصدهای ردشده سفارشی fail-closed هستند: هر پاسخ HTTP یعنی مقصد از طریق پروکسی قابل دسترسی بوده است، و هر خطای انتقال به‌عنوان نامشخص گزارش می‌شود، چون OpenClaw نمی‌تواند ثابت کند که پروکسی یک origin قابل دسترسی را مسدود کرده است. در صورت شکست اعتبارسنجی، فرمان با کد 1 خارج می‌شود.
برای automation از `--json` استفاده کنید. خروجی JSON شامل نتیجه کلی، منبع مؤثر پیکربندی پراکسی، هرگونه خطای پیکربندی، و بررسی هر مقصد است. credentialهای URL پراکسی در خروجی متنی و JSON پنهان می‌شوند:
برای خودکارسازی از `--json` استفاده کنید. خروجی JSON شامل نتیجه کلی، منبع مؤثر پیکربندی پروکسی، هر خطای پیکربندی، و هر بررسی مقصد است. اعتبارنامه‌های URL پروکسی در خروجی متنی و JSON پنهان‌سازی می‌شوند:
```json
{
@ -170,7 +170,7 @@ openclaw proxy validate --proxy-url http://127.0.0.1:3128
}
```
می‌توانید به‌صورت دستی نیز با `curl` اعتبارسنجی کنید:
همچنین می‌توانید با `curl` به‌صورت دستی اعتبارسنجی کنید:
```bash
curl -x http://127.0.0.1:3128 https://example.com/
@ -178,9 +178,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/
```
درخواست عمومی باید موفق شود. درخواست‌های لوپ‌بک و فراداده باید توسط پراکسی مسدود شوند. برای `openclaw proxy validate`، قناری لوپ‌بک داخلی می‌تواند رد شدن توسط پراکسی را از مبدا قابل دسترس تشخیص دهد. بررسی‌های سفارشی `--denied-url` این قناری را ندارند، بنابراین هم پاسخ‌های HTTP و هم شکست‌های مبهم انتقال را به‌عنوان شکست اعتبارسنجی در نظر بگیرید، مگر اینکه پراکسی شما سیگنال رد ویژه استقرار را ارائه دهد که بتوانید جداگانه آن را راستی‌آزمایی کنید.
درخواست عمومی باید موفق شود. درخواست‌های لوپ‌بک و فراداده باید توسط پروکسی مسدود شوند. برای `openclaw proxy validate`، قناری داخلی لوپ‌بک می‌تواند رد شدن توسط پروکسی را از یک مبدا قابل دسترسی تشخیص دهد. بررسی‌های سفارشی `--denied-url` آن قناری را ندارند، بنابراین هم پاسخ‌های HTTP و هم شکست‌های مبهم انتقال را شکست اعتبارسنجی در نظر بگیرید، مگر اینکه پروکسی شما سیگنال رد مخصوص استقراری را آشکار کند که بتوانید جداگانه آن را تأیید کنید.
سپس مسیریابی پراکسی OpenClaw را فعال کنید:
سپس مسیریابی پروکسی OpenClaw را فعال کنید:
```bash
openclaw config set proxy.enabled true
@ -198,10 +198,11 @@ proxy:
## محدودیت‌ها
- پراکسی پوشش را برای کلاینت‌های HTTP و WebSocket جاوااسکریپتی محلیِ فرایند بهبود می‌دهد، اما یک محیط ایزوله شبکه‌ای در سطح سیستم‌عامل نیست.
- سوکت‌های خام `net`، `tls` و `http2`، افزونه‌های بومی و فرایندهای فرزند ممکن است از مسیریابی پراکسی در سطح Node عبور کنند، مگر اینکه متغیرهای محیطی پراکسی را به ارث ببرند و رعایت کنند.
- IRC یک کانال خام TCP/TLS خارج از مسیریابی پراکسی پیش‌روی مدیریت‌شده توسط اپراتور است. در استقرارهایی که نیاز دارند همه خروجی‌ها از طریق آن پراکسی پیش‌رو عبور کنند، `channels.irc.enabled=false` را تنظیم کنید، مگر اینکه خروج مستقیم IRC صراحتا تایید شده باشد.
- رابط‌های وب محلی کاربر و سرورهای مدل محلی باید در صورت نیاز در سیاست پراکسی اپراتور در فهرست مجاز قرار گیرند؛ OpenClaw برای آن‌ها یک میان‌بر عمومی شبکه محلی ارائه نمی‌کند.
- میان‌بر پراکسی برای صفحه کنترل Gateway عمدا به `localhost` و نشانی‌های URL با IP لوپ‌بک صریح محدود است. برای اتصال‌های مستقیم محلی به صفحه کنترل Gateway از `ws://127.0.0.1:18789`، `ws://[::1]:18789` یا `ws://localhost:18789` استفاده کنید؛ نام‌های میزبان دیگر مانند ترافیک معمول مبتنی بر نام میزبان مسیریابی می‌شوند.
- OpenClaw سیاست پراکسی شما را بازرسی، آزمایش یا گواهی نمی‌کند.
- تغییرات سیاست پراکسی را به‌عنوان تغییرات عملیاتی حساس از نظر امنیتی در نظر بگیرید.
- پروکسی پوشش را برای کلاینت‌های HTTP و WebSocket جاوااسکریپتِ محلیِ پردازه بهبود می‌دهد، اما سندباکس شبکه در سطح سیستم‌عامل نیست.
- سوکت‌های خام `net`، `tls` و `http2`، افزونه‌های بومی و پردازه‌های فرزند ممکن است مسیریابی پروکسی در سطح Node را دور بزنند، مگر اینکه متغیرهای محیطی پروکسی را به ارث ببرند و رعایت کنند.
- IRC یک کانال TCP/TLS خام خارج از مسیریابی پروکسی روبه‌جلوی مدیریت‌شده توسط اپراتور است. در استقرارهایی که نیاز دارند همه خروجی‌ها از طریق آن پروکسی روبه‌جلو عبور کنند، `channels.irc.enabled=false` را تنظیم کنید، مگر اینکه خروجی مستقیم IRC صراحتاً تأیید شده باشد.
- پروکسی اشکال‌زدایی محلی ابزار تشخیصی است و ارسال مستقیم بالادستی آن برای درخواست‌های پروکسی و تونل‌های CONNECT به‌طور پیش‌فرض هنگامی که حالت پروکسی مدیریت‌شده فعال است غیرفعال می‌شود؛ ارسال مستقیم را فقط برای تشخیص‌های محلی تأییدشده فعال کنید.
- WebUIهای محلی کاربر و سرورهای مدل محلی باید در صورت نیاز در سیاست پروکسی اپراتور در فهرست مجاز قرار گیرند؛ OpenClaw یک دورزدن عمومی شبکه محلی برای آن‌ها ارائه نمی‌کند.
- دورزدن پروکسی صفحه کنترل Gateway عمداً به URLهای `localhost` و IPهای لفظی لوپ‌بک محدود شده است. برای اتصال‌های مستقیم محلی صفحه کنترل Gateway از `ws://127.0.0.1:18789`، `ws://[::1]:18789` یا `ws://localhost:18789` استفاده کنید؛ نام‌های میزبان دیگر مانند ترافیک معمولی مبتنی بر نام میزبان مسیریابی می‌شوند.
- OpenClaw سیاست پروکسی شما را بازرسی، آزمایش یا گواهی نمی‌کند.
- تغییرات سیاست پروکسی را تغییرات عملیاتی حساس از نظر امنیتی در نظر بگیرید.

448
docs/fa/tools/subagents.md
View File

@ -1,40 +1,47 @@
---
read_when:
- می‌خواهید کار پس‌زمینه یا موازی را از طریق عامل انجام دهید
- شما در حال تغییر sessions_spawn یا خط‌مشی ابزار زیردستیار هستید
- شما در حال پیاده‌سازی یا عیب‌یابی نشست‌های زیرعامل وابسته به رشتهٔ گفتگو هستید
- می‌خواهید کار پس‌زمینه یا موازی از طریق عامل انجام شود
- شما در حال تغییر خط‌مشی sessions_spawn یا ابزار زیرعامل هستید
- در حال پیاده‌سازی یا عیب‌یابی نشست‌های زیردستیارِ وابسته به رشته هستید
sidebarTitle: Sub-agents
summary: اجراهای ایزولهٔ عامل در پس‌زمینه را راه‌اندازی کنید که نتایج را به گفت‌وگوی درخواست‌دهنده اعلام می‌کنند
title: عامل‌های فرعی
summary: اجراهای ایزولهٔ عامل در پس‌زمینه را راه‌اندازی کنید که نتایج را به چت درخواست‌کننده اعلام می‌کنند
title: زیرعامل‌ها
x-i18n:
generated_at: "2026-05-04T02:28:54Z"
generated_at: "2026-05-04T07:08:28Z"
model: gpt-5.5
provider: openai
source_hash: d0df39e06b952def3eb0b296f36c7dc8c0b0a115785d865236a970c5d453fc37
source_hash: 65d60bf6813d667b7311aa28109d4bd6be012a16e638c64cfff130831db88cd8
source_path: tools/subagents.md
workflow: 16
---
زیرعامل‌ها اجراهای پس‌زمینهٔ عامل هستند که از یک اجرای عامل موجود ایجاد می‌شوند.
زیرعامل‌ها اجرای عامل‌های پس‌زمینه هستند که از یک اجرای عامل موجود ایجاد می‌شوند.
آن‌ها در نشست خودشان (`agent:<agentId>:subagent:<uuid>`) اجرا می‌شوند و،
پس از پایان، نتیجهٔ خود را به کانال گفت‌وگوی درخواست‌کننده **اعلام** می‌کنند.
پس از پایان، نتیجه خود را در کانال چت درخواست‌کننده **اعلام** می‌کنند.
هر اجرای زیرعامل به‌عنوان یک
[وظیفهٔ پس‌زمینه](/fa/automation/tasks) پیگیری می‌شود.
[کار پس‌زمینه](/fa/automation/tasks) ردیابی می‌شود.
اهداف اصلی:
- موازی‌سازی کارهای «پژوهش / وظیفهٔ طولانی / ابزار کند» بدون مسدود کردن اجرای اصلی.
- جدا نگه داشتن پیش‌فرض زیرعامل‌ها (جداسازی نشست + sandboxing اختیاری).
- دشوار کردن سوءاستفاده از سطح ابزار: زیرعامل‌ها به‌صورت پیش‌فرض ابزارهای نشست را دریافت نمی‌کنند.
- پشتیبانی از عمق تودرتوی قابل‌پیکربندی برای الگوهای orchestrator.
- موازی‌سازی کارهای «پژوهش / وظیفه طولانی / ابزار کند» بدون مسدود کردن اجرای اصلی.
- ایزوله نگه داشتن زیرعامل‌ها به‌صورت پیش‌فرض (جداسازی نشست + sandboxing اختیاری).
- سخت کردن سطح ابزار برای سوءاستفاده: زیرعامل‌ها به‌صورت پیش‌فرض ابزارهای نشست را دریافت نمی‌کنند.
- پشتیبانی از عمق تودرتوی قابل پیکربندی برای الگوهای هماهنگ‌کننده.
<Note>
**یادداشت هزینه:** هر زیرعامل به‌صورت پیش‌فرض context و مصرف token خودش را دارد. برای وظایف سنگین یا تکراری، یک مدل ارزان‌تر برای زیرعامل‌ها تنظیم کنید و عامل اصلی خود را روی مدلی باکیفیت‌تر نگه دارید. از طریق `agents.defaults.subagents.model` یا overrideهای هر عامل پیکربندی کنید. وقتی یک فرزند واقعاً به transcript فعلی درخواست‌کننده نیاز دارد، عامل می‌تواند برای همان یک spawn مقدار `context: "fork"` را درخواست کند. نشست‌های subagent وابسته به thread به‌صورت پیش‌فرض `context: "fork"` دارند، چون مکالمهٔ فعلی را به یک thread پیگیری منشعب می‌کنند.
**نکته هزینه:** هر زیرعامل به‌صورت پیش‌فرض context و مصرف توکن خودش را دارد.
برای وظایف سنگین یا تکراری، یک مدل ارزان‌تر برای زیرعامل‌ها تنظیم کنید
و عامل اصلی خود را روی یک مدل باکیفیت‌تر نگه دارید. از طریق
`agents.defaults.subagents.model` یا بازنویسی‌های هر عامل پیکربندی کنید. وقتی یک فرزند
واقعاً به رونوشت فعلی درخواست‌کننده نیاز دارد، عامل می‌تواند برای همان یک ایجاد
`context: "fork"` را درخواست کند. نشست‌های زیرعامل وابسته به thread به‌صورت پیش‌فرض
`context: "fork"` هستند، زیرا گفت‌وگوی فعلی را به یک thread پیگیری منشعب می‌کنند.
</Note>
## فرمان Slash
## دستور Slash
از `/subagents` برای بررسی یا کنترل اجراهای زیرعامل برای **نشست فعلی** استفاده کنید:
از `/subagents` برای بررسی یا کنترل اجراهای زیرعامل برای **نشست فعلی**
استفاده کنید:
```text
/subagents list
@ -46,15 +53,15 @@ x-i18n:
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]
```
برای هدایت اجرای فعال نشست درخواست‌کنندهٔ فعلی، از [`/steer <message>`](/fa/tools/steer) در سطح بالا استفاده کنید. وقتی هدف یک اجرای فرزند است، از `/subagents steer <id|#> <message>` استفاده کنید.
از [`/steer <message>`](/fa/tools/steer) سطح بالا برای هدایت اجرای فعال نشست درخواست‌کننده فعلی استفاده کنید. وقتی هدف یک اجرای فرزند است، از `/subagents steer <id|#> <message>` استفاده کنید.
`/subagents info` فرادادهٔ اجرا را نشان می‌دهد (وضعیت، timestampها، شناسهٔ نشست،
مسیر transcript، پاک‌سازی). برای یک نمای یادآوری محدود و فیلترشده از نظر ایمنی، از `sessions_history` استفاده کنید؛ وقتی به transcript کامل خام نیاز دارید، مسیر transcript را روی دیسک بررسی کنید.
`/subagents info` فراداده اجرا را نشان می‌دهد (وضعیت، timestampها، شناسه نشست،
مسیر رونوشت، پاک‌سازی). برای نمای یادآوری محدود و فیلترشده از نظر ایمنی از `sessions_history` استفاده کنید؛ وقتی به رونوشت خام کامل نیاز دارید، مسیر رونوشت را روی دیسک بررسی کنید.
### کنترل‌های اتصال thread
این فرمان‌ها روی کانال‌هایی کار می‌کنند که از اتصال‌های thread پایدار پشتیبانی می‌کنند.
بخش [کانال‌های پشتیبان thread](#thread-supporting-channels) را در پایین ببینید.
این دستورها روی کانال‌هایی کار می‌کنند که از اتصال‌های thread پایدار پشتیبانی می‌کنند.
در ادامه [کانال‌های پشتیبان thread](#thread-supporting-channels) را ببینید.
```text
/focus <subagent-label|session-key|session-id|session-label>
@ -64,71 +71,80 @@ x-i18n:
/session max-age <duration|off>
```
### رفتار spawn
### رفتار ایجاد
`/subagents spawn` یک زیرعامل پس‌زمینه را به‌عنوان فرمان کاربر (نه relay داخلی) شروع می‌کند و پس از پایان اجرا، یک به‌روزرسانی نهایی تکمیل را به گفت‌وگوی درخواست‌کننده می‌فرستد.
`/subagents spawn` یک زیرعامل پس‌زمینه را به‌عنوان دستور کاربر (نه یک
بازرسانی داخلی) شروع می‌کند و پس از پایان اجرا، یک به‌روزرسانی نهایی تکمیل را به
چت درخواست‌کننده می‌فرستد.
<AccordionGroup>
<Accordion title="تکمیل push-based و غیرمسدودکننده">
- فرمان spawn غیرمسدودکننده است؛ فوراً یک شناسهٔ اجرا برمی‌گرداند.
- پس از تکمیل، زیرعامل یک پیام خلاصه/نتیجه را به کانال گفت‌وگوی درخواست‌کننده اعلام می‌کند.
- تکمیل push-based است. پس از spawn شدن، فقط برای انتظار تا پایان آن، `/subagents list`، `sessions_list` یا `sessions_history` را در یک حلقه poll نکنید؛ وضعیت را فقط هنگام نیاز برای اشکال‌زدایی یا مداخله بررسی کنید.
- پس از تکمیل، OpenClaw به‌صورت best-effort برگه‌ها/فرآیندهای مرورگری را که توسط آن نشست زیرعامل باز شده‌اند، پیش از ادامهٔ جریان پاک‌سازی اعلام، می‌بندد.
<Accordion title="تکمیل غیرمسدودکننده و مبتنی بر push">
- دستور ایجاد غیرمسدودکننده است؛ بلافاصله یک شناسه اجرا برمی‌گرداند.
- هنگام تکمیل، زیرعامل یک پیام خلاصه/نتیجه را به کانال چت درخواست‌کننده اعلام می‌کند.
- تکمیل مبتنی بر push است. پس از ایجاد، فقط برای انتظار تا پایان، `/subagents list`، `sessions_list` یا `sessions_history` را در یک حلقه polling نکنید؛ وضعیت را فقط هنگام نیاز برای اشکال‌زدایی یا مداخله بررسی کنید.
- هنگام تکمیل، OpenClaw تا حد امکان tabها/فرایندهای مرورگر را که توسط آن نشست زیرعامل باز شده‌اند، پیش از ادامه جریان پاک‌سازی اعلام می‌بندد.
</Accordion>
<Accordion title="تاب‌آوری تحویل spawn دستی">
<Accordion title="تاب‌آوری تحویل ایجاد دستی">
- OpenClaw ابتدا تحویل مستقیم `agent` را با یک کلید idempotency پایدار امتحان می‌کند.
- اگر تحویل مستقیم شکست بخورد، به مسیریابی صف fallback می‌کند.
- اگر مسیریابی صف همچنان در دسترس نباشد، اعلام با backoff نمایی کوتاه، پیش از انصراف نهایی، دوباره امتحان می‌شود.
- تحویل تکمیل، مسیر حل‌شدهٔ درخواست‌کننده را نگه می‌دارد: مسیرهای تکمیل وابسته به thread یا وابسته به مکالمه، وقتی در دسترس باشند، اولویت دارند؛ اگر مبدأ تکمیل فقط یک کانال ارائه کند، OpenClaw هدف/حساب گم‌شده را از مسیر حل‌شدهٔ نشست درخواست‌کننده (`lastChannel` / `lastTo` / `lastAccountId`) پر می‌کند تا تحویل مستقیم همچنان کار کند.
- اگر نوبت تکمیل عامل درخواست‌کننده شکست بخورد، خروجی قابل‌مشاهده تولید نکند، یا یک پیشوند آشکارا ناقص از نتیجه فرزند ثبت‌شده برگرداند، OpenClaw به تحویل مستقیم تکمیل از نتیجه فرزند ثبت‌شده بازمی‌گردد.
- اگر تحویل مستقیم قابل استفاده نباشد، به مسیریابی صف بازمی‌گردد.
- اگر مسیریابی صف همچنان در دسترس نباشد، اعلام با یک backoff نمایی کوتاه پیش از صرف‌نظر نهایی دوباره تلاش می‌شود.
- تحویل تکمیل مسیر حل‌شده درخواست‌کننده را نگه می‌دارد: مسیرهای تکمیل وابسته به thread یا وابسته به گفت‌وگو، وقتی در دسترس باشند، برنده می‌شوند؛ اگر مبدأ تکمیل فقط یک کانال ارائه کند، OpenClaw هدف/حساب گم‌شده را از مسیر حل‌شده نشست درخواست‌کننده (`lastChannel` / `lastTo` / `lastAccountId`) پر می‌کند تا تحویل مستقیم همچنان کار کند.
</Accordion>
<Accordion title="فرادادهٔ تحویل تکمیل">
تحویل تکمیل به نشست درخواست‌کننده، context داخلی تولیدشده در runtime است (نه متن نوشته‌شده توسط کاربر) و شامل موارد زیر است:
<Accordion title="فراداده واگذاری تکمیل">
واگذاری تکمیل به نشست درخواست‌کننده context داخلی تولیدشده در زمان اجرا است
(نه متن نوشته‌شده توسط کاربر) و شامل موارد زیر است:
- `Result` — آخرین متن پاسخ قابل‌مشاهدهٔ `assistant`، وگرنه آخرین متن پاک‌سازی‌شدهٔ tool/toolResult. اجراهای نهاییِ شکست‌خورده از متن پاسخ captureشده دوباره استفاده نمی‌کنند.
- `Result` — آخرین متن پاسخ قابل‌مشاهده `assistant`، وگرنه آخرین متن ابزار/toolResult پاک‌سازی‌شده. اجراهای ناموفق پایانی از متن پاسخ ثبت‌شده دوباره استفاده نمی‌کنند.
- `Status` — `completed successfully` / `failed` / `timed out` / `unknown`.
- آمار فشردهٔ runtime/token.
- دستور تحویل که به عامل درخواست‌کننده می‌گوید با صدای عادی assistant بازنویسی کند (نه اینکه فرادادهٔ داخلی خام را forward کند).
- آمار فشرده زمان اجرا/توکن.
- یک دستور تحویل که به عامل درخواست‌کننده می‌گوید با صدای عادی دستیار بازنویسی کند (نه اینکه فراداده خام داخلی را ارسال کند).
</Accordion>
<Accordion title="حالت‌ها و runtime مربوط به ACP">
- `--model` و `--thinking` پیش‌فرض‌ها را برای همان اجرای مشخص override می‌کنند.
- از `info`/`log` برای بررسی جزئیات و خروجی پس از تکمیل استفاده کنید.
<Accordion title="حالت‌ها و runtime ACP">
- `--model` و `--thinking` پیش‌فرض‌ها را برای همان اجرای مشخص بازنویسی می‌کنند.
- برای بررسی جزئیات و خروجی پس از تکمیل، از `info`/`log` استفاده کنید.
- `/subagents spawn` حالت یک‌باره است (`mode: "run"`). برای نشست‌های پایدار وابسته به thread، از `sessions_spawn` با `thread: true` و `mode: "session"` استفاده کنید.
- برای نشست‌های harness مربوط به ACP (Claude Code، Gemini CLI، OpenCode، یا Codex ACP/acpx صریح)، وقتی ابزار آن runtime را تبلیغ می‌کند، از `sessions_spawn` با `runtime: "acp"` استفاده کنید. هنگام اشکال‌زدایی تکمیل‌ها یا حلقه‌های عامل به عامل، [مدل تحویل ACP](/fa/tools/acp-agents#delivery-model) را ببینید. وقتی Plugin `codex` فعال است، کنترل گفت‌وگو/thread مربوط به Codex باید `/codex ...` را به ACP ترجیح دهد، مگر اینکه کاربر صریحاً ACP/acpx را درخواست کند.
- OpenClaw مقدار `runtime: "acp"` را پنهان می‌کند تا وقتی ACP فعال باشد، درخواست‌کننده sandboxed نباشد، و یک Plugin پشتیبان مانند `acpx` بارگذاری شده باشد. `runtime: "acp"` انتظار یک شناسهٔ harness خارجی ACP، یا یک ورودی `agents.list[]` با `runtime.type="acp"` را دارد؛ برای عامل‌های عادی پیکربندی OpenClaw از `agents_list`، از runtime پیش‌فرض زیرعامل استفاده کنید.
- برای نشست‌های harness ACP (Claude Code، Gemini CLI، OpenCode، یا Codex ACP/acpx صریح)، وقتی ابزار آن runtime را اعلام می‌کند، از `sessions_spawn` با `runtime: "acp"` استفاده کنید. هنگام اشکال‌زدایی تکمیل‌ها یا حلقه‌های عامل‌به‌عامل، [مدل تحویل ACP](/fa/tools/acp-agents#delivery-model) را ببینید. وقتی Plugin `codex` فعال است، کنترل چت/thread Codex باید `/codex ...` را به ACP ترجیح دهد، مگر اینکه کاربر صراحتاً ACP/acpx را بخواهد.
- OpenClaw تا زمانی که ACP فعال نشده، درخواست‌کننده sandbox نشده، و یک Plugin backend مانند `acpx` بارگذاری نشده باشد، `runtime: "acp"` را پنهان می‌کند. `runtime: "acp"` انتظار یک شناسه harness خارجی ACP، یا یک ورودی `agents.list[]` با `runtime.type="acp"` را دارد؛ برای عامل‌های پیکربندی عادی OpenClaw از `agents_list`، از runtime پیش‌فرض زیرعامل استفاده کنید.
</Accordion>
</AccordionGroup>
## حالت‌های context
زیرعامل‌های native جدا شروع می‌شوند، مگر اینکه فراخواننده صریحاً درخواست fork کردن transcript فعلی را بدهد.
زیرعامل‌های بومی به‌صورت ایزوله شروع می‌شوند، مگر اینکه فراخواننده صراحتاً درخواست کند
رونوشت فعلی fork شود.
| حالت | زمان استفاده | رفتار |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `isolated` | پژوهش تازه، پیاده‌سازی مستقل، کار ابزار کند، یا هر چیزی که بتوان در متن وظیفه مختصر توضیح داد | یک transcript فرزند پاک می‌سازد. این حالت پیش‌فرض است و مصرف token را پایین‌تر نگه می‌دارد. |
| `fork` | کاری که به مکالمهٔ فعلی، نتایج ابزارهای قبلی، یا دستورالعمل‌های ظریف موجود در transcript درخواست‌کننده وابسته است | transcript درخواست‌کننده را پیش از شروع فرزند، به نشست فرزند منشعب می‌کند. |
| `isolated` | پژوهش تازه، پیاده‌سازی مستقل، کار ابزار کند، یا هر چیزی که بتوان آن را در متن وظیفه خلاصه کرد | یک رونوشت فرزند پاک ایجاد می‌کند. این پیش‌فرض است و مصرف توکن را پایین‌تر نگه می‌دارد. |
| `fork` | کاری که به گفت‌وگوی فعلی، نتایج قبلی ابزار، یا دستورهای ظریف موجود در رونوشت درخواست‌کننده وابسته است | رونوشت درخواست‌کننده را پیش از شروع فرزند، به نشست فرزند منشعب می‌کند. |
از `fork` با احتیاط استفاده کنید. این حالت برای واگذاری context-sensitive است، نه جایگزینی برای نوشتن یک task prompt روشن.
از `fork` با صرفه‌جویی استفاده کنید. این برای واگذاری حساس به context است، نه
جایگزینی برای نوشتن یک prompt وظیفه روشن.
## ابزار: `sessions_spawn`
یک اجرای زیرعامل را با `deliver: false` روی lane سراسری `subagent` شروع می‌کند،
سپس یک مرحلهٔ اعلام اجرا می‌کند و پاسخ اعلام را به کانال گفت‌وگوی درخواست‌کننده post می‌کند.
سپس یک گام اعلام را اجرا می‌کند و پاسخ اعلام را به کانال چت درخواست‌کننده
ارسال می‌کند.
دسترس‌پذیری به سیاست ابزار مؤثر فراخواننده بستگی دارد. پروفایل‌های `coding` و
`full` به‌صورت پیش‌فرض `sessions_spawn` را ارائه می‌کنند. پروفایل `messaging`
این کار را نمی‌کند؛ برای عامل‌هایی که باید کار را واگذار کنند، `tools.alsoAllow: ["sessions_spawn", "sessions_yield",
این کار را نمی‌کند؛ برای عامل‌هایی که باید کار را واگذار کنند،
`tools.alsoAllow: ["sessions_spawn", "sessions_yield",
"subagents"]` را اضافه کنید یا از `tools.profile: "coding"` استفاده کنید.
سیاست‌های allow/deny مربوط به کانال/گروه، provider، sandbox، و هر عامل، همچنان می‌توانند ابزار را پس از مرحلهٔ پروفایل حذف کنند. برای تأیید فهرست ابزار مؤثر، از همان نشست `/tools` را اجرا کنید.
سیاست‌های کانال/گروه، provider، sandbox و allow/deny هر عامل همچنان می‌توانند
ابزار را پس از مرحله پروفایل حذف کنند. از همان نشست، برای تأیید فهرست مؤثر ابزارها از `/tools` استفاده کنید.
**پیش‌فرض‌ها:**
- **مدل:** از فراخواننده به ارث می‌برد، مگر اینکه `agents.defaults.subagents.model` (یا `agents.list[].subagents.model` برای هر عامل) را تنظیم کنید؛ مقدار صریح `sessions_spawn.model` همچنان اولویت دارد.
- **Thinking:** از فراخواننده به ارث می‌برد، مگر اینکه `agents.defaults.subagents.thinking` (یا `agents.list[].subagents.thinking` برای هر عامل) را تنظیم کنید؛ مقدار صریح `sessions_spawn.thinking` همچنان اولویت دارد.
- **مهلت اجرای run:** اگر `sessions_spawn.runTimeoutSeconds` حذف شود، OpenClaw در صورت تنظیم بودن از `agents.defaults.subagents.runTimeoutSeconds` استفاده می‌کند؛ در غیر این صورت به `0` fallback می‌کند (بدون timeout).
- **مدل:** از فراخواننده ارث‌بری می‌کند، مگر اینکه `agents.defaults.subagents.model` (یا `agents.list[].subagents.model` هر عامل) را تنظیم کنید؛ یک `sessions_spawn.model` صریح همچنان اولویت دارد.
- **Thinking:** از فراخواننده ارث‌بری می‌کند، مگر اینکه `agents.defaults.subagents.thinking` (یا `agents.list[].subagents.thinking` هر عامل) را تنظیم کنید؛ یک `sessions_spawn.thinking` صریح همچنان اولویت دارد.
- **مهلت اجرای اجرا:** اگر `sessions_spawn.runTimeoutSeconds` حذف شود، OpenClaw وقتی `agents.defaults.subagents.runTimeoutSeconds` تنظیم شده باشد از آن استفاده می‌کند؛ در غیر این صورت به `0` (بدون مهلت) بازمی‌گردد.
### پارامترهای ابزار
@ -136,58 +152,60 @@ x-i18n:
شرح وظیفه برای زیرعامل.
</ParamField>
<ParamField path="label" type="string">
برچسب اختیاری و خوانا برای انسان.
برچسب اختیاری قابل خواندن برای انسان.
</ParamField>
<ParamField path="agentId" type="string">
وقتی `subagents.allowAgents` اجازه بدهد، زیر یک شناسهٔ عامل دیگر spawn کنید.
وقتی توسط `subagents.allowAgents` مجاز باشد، زیر یک شناسه عامل دیگر ایجاد کنید.
</ParamField>
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
`acp` فقط برای harnessهای خارجی ACP (`claude`، `droid`، `gemini`، `opencode`، یا Codex ACP/acpx که صریحاً درخواست شده باشد) و برای ورودی‌های `agents.list[]` است که `runtime.type` آن‌ها `acp` است.
`acp` فقط برای harnessهای خارجی ACP (`claude`، `droid`، `gemini`، `opencode`، یا Codex ACP/acpx که صراحتاً درخواست شده) و برای ورودی‌های `agents.list[]` است که `runtime.type` آن‌ها `acp` است.
</ParamField>
<ParamField path="resumeSessionId" type="string">
فقط ACP. وقتی `runtime: "acp"` باشد، یک نشست harness موجود ACP را از سر می‌گیرد؛ برای spawnهای زیرعامل native نادیده گرفته می‌شود.
فقط ACP. وقتی `runtime: "acp"` است یک نشست harness ACP موجود را از سر می‌گیرد؛ برای ایجادهای زیرعامل بومی نادیده گرفته می‌شود.
</ParamField>
<ParamField path="streamTo" type='"parent"'>
فقط ACP. وقتی `runtime: "acp"` باشد، خروجی اجرای ACP را به نشست والد stream می‌کند؛ برای spawnهای زیرعامل native حذف کنید.
فقط ACP. وقتی `runtime: "acp"` است خروجی اجرای ACP را به نشست والد stream می‌کند؛ برای ایجادهای زیرعامل بومی حذف کنید.
</ParamField>
<ParamField path="model" type="string">
مدل زیرعامل را override کنید. مقدارهای نامعتبر رد می‌شوند و زیرعامل با مدل پیش‌فرض اجرا می‌شود و در نتیجهٔ ابزار یک هشدار می‌آید.
مدل زیرعامل را بازنویسی کنید. مقدارهای نامعتبر رد می‌شوند و زیرعامل روی مدل پیش‌فرض با یک هشدار در نتیجه ابزار اجرا می‌شود.
</ParamField>
<ParamField path="thinking" type="string">
سطح thinking را برای اجرای زیرعامل override کنید.
سطح thinking را برای اجرای زیرعامل بازنویسی کنید.
</ParamField>
<ParamField path="runTimeoutSeconds" type="number">
وقتی تنظیم شده باشد، به‌صورت پیش‌فرض `agents.defaults.subagents.runTimeoutSeconds` است، وگرنه `0`. وقتی تنظیم شود، اجرای زیرعامل پس از N ثانیه abort می‌شود.
وقتی تنظیم شده باشد به‌صورت پیش‌فرض `agents.defaults.subagents.runTimeoutSeconds` است، وگرنه `0`. وقتی تنظیم شود، اجرای زیرعامل پس از N ثانیه لغو می‌شود.
</ParamField>
<ParamField path="thread" type="boolean" default="false">
وقتی `true` باشد، اتصال thread کانال را برای این نشست زیرعامل درخواست می‌کند.
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
اگر `thread: true` باشد و `mode` حذف شده باشد، پیش‌فرض `session` می‌شود. `mode: "session"` به `thread: true` نیاز دارد.
اگر `thread: true` باشد و `mode` حذف شود، پیش‌فرض به `session` تبدیل می‌شود. `mode: "session"` به `thread: true` نیاز دارد.
</ParamField>
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
`"delete"` بلافاصله پس از اعلام archive می‌کند (هنوز transcript را از طریق rename نگه می‌دارد).
`"delete"` بلافاصله پس از اعلام archive می‌کند (همچنان رونوشت را از طریق rename نگه می‌دارد).
</ParamField>
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
`require` مگر اینکه runtime فرزند هدف sandboxed باشد، spawn را رد می‌کند.
`require` ایجاد را رد می‌کند، مگر اینکه runtime فرزند هدف sandbox شده باشد.
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
`fork` transcript فعلی درخواست‌کننده را به نشست فرزند منشعب می‌کند. فقط زیرعامل‌های native. spawnهای وابسته به thread به‌صورت پیش‌فرض `fork` هستند؛ spawnهای غیر thread به‌صورت پیش‌فرض `isolated` هستند.
`fork` رونوشت فعلی درخواست‌کننده را به نشست فرزند منشعب می‌کند. فقط زیرعامل‌های بومی. ایجادهای وابسته به thread به‌صورت پیش‌فرض `fork` هستند؛ ایجادهای غیر thread به‌صورت پیش‌فرض `isolated` هستند.
</ParamField>
<Warning>
`sessions_spawn` پارامترهای تحویل کانال (`target`,
`channel`, `to`, `threadId`, `replyTo`, `transport`) را نمی‌پذیرد. برای تحویل، از
`message`/`sessions_send` از اجرای spawnشده استفاده کنید.
`sessions_spawn` پارامترهای تحویل کانال (`target`،
`channel`، `to`، `threadId`، `replyTo`، `transport`) را نمی‌پذیرد. برای تحویل، از
`message`/`sessions_send` از اجرای ایجادشده استفاده کنید.
</Warning>
## نشست‌های وابسته به thread
وقتی اتصال‌های thread برای یک کانال فعال باشند، یک زیرعامل می‌تواند به یک thread متصل بماند تا پیام‌های پیگیری کاربر در آن thread همچنان به همان نشست زیرعامل route شوند.
وقتی اتصال‌های thread برای یک کانال فعال هستند، یک زیرعامل می‌تواند به یک thread متصل بماند
تا پیام‌های پیگیری کاربر در آن thread همچنان به همان نشست زیرعامل مسیریابی شوند.
### کانال‌های پشتیبان thread
**Discord** در حال حاضر تنها کانال پشتیبانی‌شده است. این کانال از نشست‌های subagent وابسته به thread پایدار (`sessions_spawn` با
**Discord** در حال حاضر تنها کانال پشتیبانی‌شده است. این کانال از
نشست‌های زیرعامل پایدار وابسته به thread (`sessions_spawn` با
`thread: true`)، کنترل‌های دستی thread (`/focus`، `/unfocus`، `/agents`،
`/session idle`، `/session max-age`) و کلیدهای adapter
`channels.discord.threadBindings.enabled`,
@ -199,77 +217,78 @@ x-i18n:
<Steps>
<Step title="Spawn">
`sessions_spawn` با `thread: true` (و در صورت تمایل `mode: "session"`).
`sessions_spawn` با `thread: true` (و در صورت نیاز `mode: "session"`).
</Step>
<Step title="اتصال">
OpenClaw یک thread را به آن هدف نشست در کانال فعال ایجاد یا متصل می‌کند.
<Step title="Bind">
OpenClaw یک رشته را برای هدف آن نشست در کانال فعال ایجاد می‌کند یا به آن متصل می‌کند.
</Step>
<Step title="مسیریابی پیگیری‌ها">
پاسخ‌ها و پیام‌های پیگیری در آن thread به نشست متصل route می‌شوند.
<Step title="Route follow-ups">
پاسخ‌ها و پیام‌های پیگیری در آن رشته به نشست متصل‌شده مسیریابی می‌شوند.
</Step>
<Step title="بررسی timeoutها">
از `/session idle` برای بررسی/به‌روزرسانی auto-unfocus هنگام عدم فعالیت و
<Step title="Inspect timeouts">
از `/session idle` برای بررسی/به‌روزرسانی خروج خودکار از فوکوس بر اثر عدم فعالیت و
از `/session max-age` برای کنترل سقف سخت استفاده کنید.
</Step>
<Step title="جدا کردن">
برای جدا کردن دستی، از `/unfocus` استفاده کنید.
<Step title="Detach">
از `/unfocus` برای جدا کردن دستی استفاده کنید.
</Step>
</Steps>
### کنترل‌های دستی
| دستور | اثر |
| ------------------ | --------------------------------------------------------------------- |
| `/focus <target>` | رشتهٔ فعلی را (یا یک رشته ایجاد کند و آن را) به هدف زیرعامل/نشست پیوند می‌دهد |
| `/unfocus` | پیوند رشتهٔ مقید فعلی را حذف می‌کند |
| `/agents` | اجراهای فعال و وضعیت پیوند (`thread:<id>` یا `unbound`) را فهرست می‌کند |
| `/session idle` | لغو تمرکز خودکار در حالت بیکار را بررسی/به‌روزرسانی می‌کند (فقط رشته‌های مقیدِ متمرکز) |
| `/session max-age` | سقف سخت را بررسی/به‌روزرسانی می‌کند (فقط رشته‌های مقیدِ متمرکز) |
| فرمان | اثر |
| ----------------- | -------------------------------------------------------------------- |
| `/focus <target>` | رشته فعلی را به یک هدف زیرعامل/نشست متصل می‌کند (یا یکی ایجاد می‌کند) |
| `/unfocus` | اتصال رشته متصل فعلی را حذف می‌کند |
| `/agents` | اجراهای فعال و وضعیت اتصال را فهرست می‌کند (`thread:<id>` یا `unbound`) |
| `/session idle` | فوکوس‌برداری خودکار در حالت بیکاری را بررسی/به‌روزرسانی می‌کند (فقط رشته‌های متصلِ در فوکوس) |
| `/session max-age` | سقف سخت را بررسی/به‌روزرسانی می‌کند (فقط رشته‌های متصلِ در فوکوس) |
### سوییچ‌های پیکربندی
- **پیش‌فرض سراسری:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
- **کلیدهای بازنویسی کانال و اتصال خودکار هنگام ایجاد** به آداپتور وابسته‌اند. بخش [کانال‌های پشتیبان رشته](#thread-supporting-channels) در بالا را ببینید.
- **پیش‌فرض سراسری:** `session.threadBindings.enabled`، `session.threadBindings.idleHours`، `session.threadBindings.maxAgeHours`.
- **بازنویسی کانال و کلیدهای اتصال خودکار هنگام ایجاد** به آداپتر وابسته‌اند. به [کانال‌های پشتیبان رشته](#thread-supporting-channels) در بالا مراجعه کنید.
برای جزئیات فعلی آداپتور، [مرجع پیکربندی](/fa/gateway/configuration-reference) و
[دستورهای اسلش](/fa/tools/slash-commands) را ببینید.
برای جزئیات فعلی آداپتر، [مرجع پیکربندی](/fa/gateway/configuration-reference) و
[فرمان‌های اسلش](/fa/tools/slash-commands) را ببینید.
### فهرست مجاز
<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
فهرست شناسه‌های عامل که می‌توانند از طریق `agentId` صریح هدف قرار بگیرند (`["*"]` هر موردی را مجاز می‌کند). پیش‌فرض: فقط عامل درخواست‌دهنده. اگر فهرستی تنظیم می‌کنید و همچنان می‌خواهید درخواست‌دهنده خودش را با `agentId` ایجاد کند، شناسهٔ درخواست‌دهنده را در فهرست وارد کنید.
فهرست شناسه‌های عامل که می‌توانند از طریق `agentId` صریح هدف قرار بگیرند (`["*"]` هر موردی را مجاز می‌کند). پیش‌فرض: فقط عامل درخواست‌کننده. اگر فهرستی تنظیم می‌کنید و همچنان می‌خواهید درخواست‌کننده بتواند خودش را با `agentId` ایجاد کند، شناسه درخواست‌کننده را در فهرست قرار دهید.
</ParamField>
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
فهرست مجاز پیش‌فرض عامل‌های هدف که وقتی عامل درخواست‌دهنده `subagents.allowAgents` خودش را تنظیم نکرده باشد استفاده می‌شود.
فهرست مجاز پیش‌فرض عامل‌های هدف که وقتی عامل درخواست‌کننده `subagents.allowAgents` اختصاصی خود را تنظیم نکرده باشد استفاده می‌شود.
</ParamField>
<ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
فراخوانی‌های `sessions_spawn` را که `agentId` را حذف می‌کنند مسدود می‌کند (انتخاب صریح پروفایل را اجباری می‌کند). بازنویسی برای هر عامل: `agents.list[].subagents.requireAgentId`.
</ParamField>
اگر نشست درخواست‌دهنده sandbox شده باشد، `sessions_spawn` هدف‌هایی را که
بدون sandbox اجرا می‌شوند رد می‌کند.
اگر نشست درخواست‌کننده در سندباکس باشد، `sessions_spawn` هدف‌هایی را رد می‌کند
که بدون سندباکس اجرا شوند.
### کشف
از `agents_list` استفاده کنید تا ببینید کدام شناسه‌های عامل در حال حاضر برای
`sessions_spawn` مجاز هستند. پاسخ شامل مدل مؤثر هر عامل فهرست‌شده و فرادادهٔ
اجرای تعبیه‌شده است تا فراخواننده‌ها بتوانند Pi، سرور برنامهٔ Codex
و سایر اجراهای بومی پیکربندی‌شده را از هم تشخیص دهند.
`sessions_spawn` مجاز هستند. پاسخ، مدل مؤثر هر عامل فهرست‌شده و فراداده
اجرای جاسازی‌شده را شامل می‌شود تا فراخواننده‌ها بتوانند Pi، سرور برنامه Codex
و اجراهای بومی پیکربندی‌شده دیگر را از هم تشخیص دهند.
### بایگانی خودکار
- نشست‌های زیرعامل پس از `agents.defaults.subagents.archiveAfterMinutes` به‌طور خودکار بایگانی می‌شوند (پیش‌فرض `60`).
- بایگانی از `sessions.delete` استفاده می‌کند و متن نشست را به `*.deleted.<timestamp>` تغییر نام می‌دهد (در همان پوشه).
- `cleanup: "delete"` بلافاصله پس از اعلان بایگانی می‌کند (همچنان متن نشست را از طریق تغییر نام نگه می‌دارد).
- بایگانی خودکار با بهترین تلاش انجام می‌شود؛ اگر Gateway دوباره راه‌اندازی شود، تایمرهای معلق از دست می‌روند.
- نشست‌های زیرعامل پس از `agents.defaults.subagents.archiveAfterMinutes` به‌صورت خودکار بایگانی می‌شوند (پیش‌فرض `60`).
- بایگانی از `sessions.delete` استفاده می‌کند و رونوشت را به `*.deleted.<timestamp>` تغییر نام می‌دهد (در همان پوشه).
- `cleanup: "delete"` بلافاصله پس از اعلام، بایگانی می‌کند (همچنان رونوشت را از طریق تغییر نام نگه می‌دارد).
- بایگانی خودکار به‌صورت بهترین تلاش انجام می‌شود؛ اگر Gateway راه‌اندازی مجدد شود، تایمرهای معلق از دست می‌روند.
- `runTimeoutSeconds` بایگانی خودکار انجام نمی‌دهد؛ فقط اجرا را متوقف می‌کند. نشست تا زمان بایگانی خودکار باقی می‌ماند.
- بایگانی خودکار به‌طور یکسان برای نشست‌های عمق ۱ و عمق ۲ اعمال می‌شود.
- پاک‌سازی مرورگر از پاک‌سازی بایگانی جداست: تب‌ها/فرایندهای مرورگر ردیابی‌شده هنگام پایان اجرا با بهترین تلاش بسته می‌شوند، حتی اگر رکورد متن نشست/نشست نگه داشته شود.
- پاک‌سازی مرورگر از پاک‌سازی بایگانی جداست: برگه‌ها/فرایندهای مرورگرِ ردیابی‌شده هنگام پایان اجرا با بهترین تلاش بسته می‌شوند، حتی اگر رونوشت/رکورد نشست نگه داشته شود.
## زیرعامل‌های تودرتو
به‌طور پیش‌فرض، زیرعامل‌ها نمی‌توانند زیرعامل‌های خودشان را ایجاد کنند
(`maxSpawnDepth: 1`). برای فعال‌کردن یک سطح تودرتویی، `maxSpawnDepth: 2` را تنظیم کنید — **الگوی هماهنگ‌کننده**: اصلی → زیرعامل هماهنگ‌کننده →
(`maxSpawnDepth: 1`). برای فعال کردن یک سطح تودرتویی، `maxSpawnDepth: 2`
را تنظیم کنید — **الگوی هماهنگ‌کننده**: عامل اصلی → زیرعامل هماهنگ‌کننده →
زیر-زیرعامل‌های کارگر.
```json5
@ -289,151 +308,152 @@ x-i18n:
### سطح‌های عمق
| عمق | شکل کلید نشست | نقش | می‌تواند ایجاد کند؟ |
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | عامل اصلی | همیشه |
| 1 | `agent:<id>:subagent:<uuid>` | زیرعامل (هماهنگ‌کننده وقتی عمق ۲ مجاز باشد) | فقط اگر `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | زیر-زیرعامل (کارگر برگ) | هرگز |
| عمق | شکل کلید نشست | نقش | می‌تواند ایجاد کند؟ |
| --- | ------------------------------------------ | --------------------------------------------- | ----------------------------- |
| 0 | `agent:<id>:main` | عامل اصلی | همیشه |
| 1 | `agent:<id>:subagent:<uuid>` | زیرعامل (هماهنگ‌کننده وقتی عمق ۲ مجاز باشد) | فقط اگر `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | زیر-زیرعامل (کارگر برگ) | هرگز |
### زنجیرهٔ اعلان
### زنجیره اعلام
نتایج در زنجیره به بالا جریان می‌یابند:
نتایج در زنجیره به بالا برمی‌گردند:
1. کارگر عمق ۲ پایان می‌یابد → به والد خود (هماهنگ‌کنندهٔ عمق ۱) اعلان می‌کند.
2. هماهنگ‌کنندهٔ عمق ۱ اعلان را دریافت می‌کند، نتایج را ترکیب می‌کند، پایان می‌یابد → به اصلی اعلان می‌کند.
3. عامل اصلی اعلان را دریافت می‌کند و به کاربر تحویل می‌دهد.
1. کارگر عمق ۲ تمام می‌کند → به والد خود اعلام می‌کند (هماهنگ‌کننده عمق ۱).
2. هماهنگ‌کننده عمق ۱ اعلام را دریافت می‌کند، نتایج را ترکیب می‌کند، تمام می‌کند → به اصلی اعلام می‌کند.
3. عامل اصلی اعلام را دریافت می‌کند و به کاربر تحویل می‌دهد.
هر سطح فقط اعلان‌های فرزندان مستقیم خود را می‌بیند.
هر سطح فقط اعلام‌های فرزندان مستقیم خود را می‌بیند.
<Note>
**راهنمای عملیاتی:** کار فرزند را یک‌بار شروع کنید و به‌جای ساختن حلقه‌های نظرسنجی حول `sessions_list`،
`sessions_history`، `/subagents list` یا دستورهای خواب `exec`، منتظر رویدادهای تکمیل بمانید.
**راهنمای عملیاتی:** کار فرزند را یک‌بار شروع کنید و به‌جای ساختن حلقه‌های نظرسنجی پیرامون `sessions_list`،
`sessions_history`، `/subagents list` یا فرمان‌های خواب `exec`، منتظر رویدادهای تکمیل بمانید.
`sessions_list` و `/subagents list` رابطه‌های نشست فرزند را
متمرکز بر کار زنده نگه می‌دارند — فرزندان زنده متصل می‌مانند، فرزندان پایان‌یافته
برای یک پنجرهٔ کوتاه اخیر قابل مشاهده می‌مانند، و پیوندهای فرزندِ فقط-ذخیرهٔ کهنه
پس از پنجرهٔ تازگی‌شان نادیده گرفته می‌شوند. این کار مانع می‌شود فرادادهٔ قدیمی `spawnedBy` /
`parentSessionKey` پس از راه‌اندازی دوباره، فرزندان شبحی را دوباره زنده کند.
اگر رویداد تکمیل فرزند پس از اینکه پاسخ نهایی را فرستاده‌اید برسد،
پیگیری درست همان توکن خاموش دقیق
بر کار زنده متمرکز نگه می‌دارند — فرزندان زنده متصل می‌مانند، فرزندان پایان‌یافته
برای یک بازه کوتاه اخیر قابل مشاهده می‌مانند، و پیوندهای فرزندِ فقط ذخیره‌شده و کهنه
پس از پنجره تازگی خود نادیده گرفته می‌شوند. این کار از زنده شدن دوباره فرزندان شبح‌گونه بر اثر فراداده قدیمی `spawnedBy` /
`parentSessionKey` پس از
راه‌اندازی مجدد جلوگیری می‌کند. اگر رویداد تکمیل فرزند پس از ارسال پاسخ نهایی شما برسد، پیگیری درست همان توکن خاموش دقیق
`NO_REPLY` / `no_reply` است.
</Note>
### سیاست ابزار بر اساس عمق
- نقش و دامنهٔ کنترل هنگام ایجاد در فرادادهٔ نشست نوشته می‌شوند. این کار از بازیابی تصادفی امتیازهای هماهنگ‌کننده توسط کلیدهای نشست تخت یا بازیابی‌شده جلوگیری می‌کند.
- **عمق ۱ (هماهنگ‌کننده، وقتی `maxSpawnDepth >= 2`):** `sessions_spawn`، `subagents`، `sessions_list`، `sessions_history` را دریافت می‌کند تا بتواند فرزندانش را مدیریت کند. سایر ابزارهای نشست/سیستم همچنان رد می‌شوند.
- **عمق ۱ (برگ، وقتی `maxSpawnDepth == 1`):** بدون ابزار نشست (رفتار پیش‌فرض فعلی).
- **عمق ۲ (کارگر برگ):** بدون ابزار نشست — `sessions_spawn` همیشه در عمق ۲ رد می‌شود. نمی‌تواند فرزندان بیشتری ایجاد کند.
- نقش و محدوده کنترل در زمان ایجاد در فراداده نشست نوشته می‌شوند. این کار مانع می‌شود کلیدهای نشست تخت یا بازیابی‌شده به‌طور تصادفی امتیازهای هماهنگ‌کننده را دوباره به دست آورند.
- **عمق ۱ (هماهنگ‌کننده، وقتی `maxSpawnDepth >= 2`):** `sessions_spawn`، `subagents`، `sessions_list`، `sessions_history` را دریافت می‌کند تا بتواند فرزندان خود را مدیریت کند. سایر ابزارهای نشست/سیستم همچنان رد می‌شوند.
- **عمق ۱ (برگ، وقتی `maxSpawnDepth == 1`):** هیچ ابزار نشستی ندارد (رفتار پیش‌فرض فعلی).
- **عمق ۲ (کارگر برگ):** هیچ ابزار نشستی ندارد — `sessions_spawn` همیشه در عمق ۲ رد می‌شود. نمی‌تواند فرزندان بیشتری ایجاد کند.
### محدودیت ایجاد برای هر عامل
### حد ایجاد برای هر عامل
هر نشست عامل (در هر عمقی) می‌تواند در هر زمان حداکثر `maxChildrenPerAgent`
هر نشست عامل (در هر عمقی) می‌تواند هم‌زمان حداکثر `maxChildrenPerAgent`
فرزند فعال داشته باشد (پیش‌فرض `5`). این کار از گسترش مهارنشده
از سوی یک هماهنگ‌کنندهٔ واحد جلوگیری می‌کند.
از یک هماهنگ‌کننده واحد جلوگیری می‌کند.
### توقف آبشاری
توقف یک هماهنگ‌کنندهٔ عمق ۱ به‌طور خودکار همهٔ فرزندان عمق ۲ آن را متوقف می‌کند:
متوقف کردن یک هماهنگ‌کننده عمق ۱ به‌صورت خودکار همه فرزندان عمق ۲ آن را
متوقف می‌کند:
- `/stop` در گفت‌وگوی اصلی همهٔ عامل‌های عمق ۱ را متوقف می‌کند و به فرزندان عمق ۲ آن‌ها آبشار می‌شود.
- `/subagents kill <id>` یک زیرعامل مشخص را متوقف می‌کند و به فرزندان آن آبشار می‌شود.
- `/subagents kill all` همهٔ زیرعامل‌های درخواست‌دهنده را متوقف می‌کند و آبشار می‌شود.
- `/stop` در گفت‌وگوی اصلی همه عامل‌های عمق ۱ را متوقف می‌کند و به فرزندان عمق ۲ آن‌ها سرایت می‌کند.
- `/subagents kill <id>` یک زیرعامل مشخص را متوقف می‌کند و به فرزندان آن سرایت می‌کند.
- `/subagents kill all` همه زیرعامل‌های درخواست‌کننده را متوقف می‌کند و سرایت می‌کند.
## احراز هویت
احراز هویت زیرعامل بر اساس **شناسهٔ عامل** حل می‌شود، نه بر اساس نوع نشست:
احراز هویت زیرعامل بر اساس **شناسه عامل** حل می‌شود، نه بر اساس نوع نشست:
- کلید نشست زیرعامل `agent:<agentId>:subagent:<uuid>` است.
- ذخیرهٔ احراز هویت از `agentDir` آن عامل بارگذاری می‌شود.
- پروفایل‌های احراز هویت عامل اصلی به‌عنوان **جایگزین** ادغام می‌شوند؛ پروفایل‌های عامل در تعارض‌ها پروفایل‌های اصلی را بازنویسی می‌کنند.
- ذخیره‌گاه احراز هویت از `agentDir` آن عامل بارگذاری می‌شود.
- پروفایل‌های احراز هویت عامل اصلی به‌عنوان **پشتیبان** ادغام می‌شوند؛ پروفایل‌های عامل در تعارض‌ها بر پروفایل‌های اصلی اولویت دارند.
ادغام افزایشی است، بنابراین پروفایل‌های اصلی همیشه به‌عنوان
جایگزین در دسترس هستند. احراز هویت کاملاً ایزوله برای هر عامل هنوز پشتیبانی نمی‌شود.
پشتیبان در دسترس هستند. احراز هویت کاملاً ایزوله برای هر عامل هنوز پشتیبانی نمی‌شود.
## اعلان
## اعلام
زیرعامل‌ها از طریق یک گام اعلان گزارش می‌دهند:
زیرعامل‌ها از طریق یک گام اعلام گزارش می‌دهند:
- گام اعلان داخل نشست زیرعامل اجرا می‌شود (نه نشست درخواست‌دهنده).
- گام اعلام داخل نشست زیرعامل اجرا می‌شود (نه نشست درخواست‌کننده).
- اگر زیرعامل دقیقاً `ANNOUNCE_SKIP` پاسخ دهد، چیزی ارسال نمی‌شود.
- اگر آخرین متن دستیار همان توکن خاموش دقیق `NO_REPLY` / `no_reply` باشد، خروجی اعلان حتی اگر پیشرفت قابل مشاهدهٔ قبلی وجود داشته باشد سرکوب می‌شود.
- اگر آخرین متن دستیار همان توکن خاموش دقیق `NO_REPLY` / `no_reply` باشد، خروجی اعلام حتی اگر پیشرفت قابل مشاهده قبلی وجود داشته باشد سرکوب می‌شود.
تحویل به عمق درخواست‌دهنده وابسته است:
تحویل به عمق درخواست‌کننده بستگی دارد:
- نشست‌های درخواست‌دهندهٔ سطح بالا از یک فراخوانی پیگیری `agent` با تحویل خارجی (`deliver=true`) استفاده می‌کنند.
- نشست‌های زیرعامل درخواست‌دهندهٔ تودرتو یک تزریق پیگیری داخلی (`deliver=false`) دریافت می‌کنند تا هماهنگ‌کننده بتواند نتایج فرزند را در همان نشست ترکیب کند.
- اگر نشست زیرعامل درخواست‌دهندهٔ تودرتو از بین رفته باشد، OpenClaw در صورت وجود، به درخواست‌دهندهٔ آن نشست برمی‌گردد.
- نشست‌های درخواست‌کننده سطح بالا از یک فراخوانی پیگیری `agent` با تحویل بیرونی (`deliver=true`) استفاده می‌کنند.
- نشست‌های زیرعامل درخواست‌کننده تودرتو یک تزریق پیگیری داخلی دریافت می‌کنند (`deliver=false`) تا هماهنگ‌کننده بتواند نتایج فرزند را درون نشست ترکیب کند.
- اگر نشست زیرعامل درخواست‌کننده تودرتو از بین رفته باشد، OpenClaw در صورت وجود به درخواست‌کننده آن نشست برمی‌گردد.
برای نشست‌های درخواست‌دهندهٔ سطح بالا، تحویل مستقیم در حالت تکمیل ابتدا
هر مسیر گفت‌وگو/رشتهٔ مقید و بازنویسی hook را حل می‌کند، سپس
فیلدهای هدف کانالِ جاافتاده را از مسیر ذخیره‌شدهٔ نشست درخواست‌دهنده پر می‌کند.
این کار تکمیل‌ها را در گفت‌وگو/موضوع درست نگه می‌دارد، حتی وقتی مبدأ تکمیل
برای نشست‌های درخواست‌کننده سطح بالا، تحویل مستقیم در حالت تکمیل ابتدا
هر مسیر گفت‌وگو/رشته متصل و بازنویسی قلاب را حل می‌کند، سپس
فیلدهای هدف-کانالِ گم‌شده را از مسیر ذخیره‌شده نشست درخواست‌کننده پر می‌کند.
این کار تکمیل‌ها را روی گفت‌وگو/موضوع درست نگه می‌دارد، حتی وقتی مبدأ تکمیل
فقط کانال را شناسایی می‌کند.
تجمیع تکمیل فرزند هنگام ساخت یافته‌های تکمیل تودرتو به اجرای فعلی درخواست‌دهنده
محدود می‌شود و از نشت خروجی‌های فرزندِ اجرای قبلی کهنه
به اعلان فعلی جلوگیری می‌کند. پاسخ‌های اعلان در صورت وجود در آداپتورهای کانال،
مسیر‌یابی رشته/موضوع را حفظ می‌کنند.
تجمیع تکمیل فرزند هنگام ساختن یافته‌های تکمیل تودرتو به اجرای فعلی درخواست‌کننده
محدود می‌شود و از نشت خروجی‌های فرزندِ اجرای قبلیِ کهنه
به اعلام فعلی جلوگیری می‌کند. پاسخ‌های اعلام، وقتی در آداپترهای کانال در دسترس باشند،
مسیریابی رشته/موضوع را حفظ می‌کنند.
### زمینهٔ اعلان
### زمینه اعلام
زمینهٔ اعلان به یک بلوک رویداد داخلی پایدار عادی‌سازی می‌شود:
زمینه اعلام به یک بلوک رویداد داخلی پایدار نرمال‌سازی می‌شود:
| فیلد | منبع |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| منبع | `subagent` یا `cron` |
| شناسه‌های نشست | کلید/شناسهٔ نشست فرزند |
| نوع | نوع اعلان + برچسب وظیفه |
| وضعیت | برگرفته از نتیجهٔ زمان اجرا (`success`، `error`، `timeout` یا `unknown`) — **نه** استنباط‌شده از متن مدل |
| محتوای نتیجه | آخرین متن قابل مشاهدهٔ دستیار، در غیر این صورت آخرین متن پاک‌سازی‌شدهٔ ابزار/toolResult |
| پیگیری | دستورالعملی که توضیح می‌دهد چه زمانی پاسخ دهد و چه زمانی خاموش بماند |
| ------------- | ----------------------------------------------------------------------------------------------------------- |
| منبع | `subagent` یا `cron` |
| شناسه‌های نشست | کلید/شناسه نشست فرزند |
| نوع | نوع اعلام + برچسب کار |
| وضعیت | مشتق‌شده از نتیجه اجرا (`success`، `error`، `timeout` یا `unknown`) — **نه** استنتاج‌شده از متن مدل |
| محتوای نتیجه | آخرین متن قابل مشاهده دستیار، در غیر این صورت آخرین متن ابزار/نتیجه‌ابزار پاک‌سازی‌شده |
| پیگیری | دستورالعملی که توضیح می‌دهد چه زمانی پاسخ داده شود و چه زمانی خاموش بماند |
اجراهای شکست‌خوردهٔ پایانی وضعیت شکست را بدون بازپخش متن پاسخ
گرفته‌شده گزارش می‌کنند. هنگام timeout، اگر فرزند فقط تا فراخوانی‌های ابزار پیش رفته باشد،
اعلان می‌تواند آن تاریخچه را به‌جای بازپخش خروجی خام ابزار،
به یک خلاصهٔ کوتاه از پیشرفت جزئی فشرده کند.
اجراهای ناموفق پایانی، وضعیت شکست را بدون بازپخش متن پاسخ
ثبت‌شده گزارش می‌کنند. در زمان پایان مهلت، اگر فرزند فقط تا فراخوانی ابزارها پیش رفته باشد، اعلام
می‌تواند به‌جای بازپخش خروجی خام ابزار، آن تاریخچه را به یک خلاصه کوتاه از پیشرفت جزئی
فرو بکاهد.
### خط آمار
بار اعلان‌ها در پایان یک خط آمار دارد (حتی وقتی پیچیده شده باشد):
بارهای اعلام یک خط آمار در پایان دارند (حتی وقتی بسته‌بندی شده باشند):
- زمان اجرا (برای مثال `runtime 5m12s`).
- زمان اجرا (مثلاً `runtime 5m12s`).
- مصرف توکن (ورودی/خروجی/کل).
- هزینهٔ تخمینی وقتی قیمت‌گذاری مدل پیکربندی شده باشد (`models.providers.*.models[].cost`).
- `sessionKey`، `sessionId` و مسیر متن نشست تا عامل اصلی بتواند تاریخچه را از طریق `sessions_history` واکشی کند یا فایل روی دیسک را بررسی کند.
- هزینه برآوردی وقتی قیمت‌گذاری مدل پیکربندی شده باشد (`models.providers.*.models[].cost`).
- `sessionKey`، `sessionId` و مسیر رونوشت تا عامل اصلی بتواند تاریخچه را از طریق `sessions_history` بگیرد یا فایل روی دیسک را بررسی کند.
فرادادهٔ داخلی فقط برای هماهنگ‌سازی است؛ پاسخ‌های کاربرنما
فراداده داخلی فقط برای هماهنگ‌سازی در نظر گرفته شده است؛ پاسخ‌های کاربرمحور
باید با صدای عادی دستیار بازنویسی شوند.
### چرا `sessions_history` ترجیح داده می‌شود
`sessions_history` مسیر هماهنگ‌سازی امن‌تری است:
- یادآوری دستیار ابتدا عادی‌سازی می‌شود: برچسب‌های تفکر حذف می‌شوند؛ داربست `<relevant-memories>` / `<relevant_memories>` حذف می‌شود؛ بلوک‌های بار XML فراخوانی ابزار در متن ساده (`<tool_call>`، `<function_call>`، `<tool_calls>`، `<function_calls>`) حذف می‌شوند، از جمله بارهای کوتاه‌شده‌ای که هرگز تمیز بسته نمی‌شوند؛ داربست تنزل‌یافتهٔ فراخوانی/نتیجهٔ ابزار و نشانگرهای زمینهٔ تاریخی حذف می‌شوند؛ توکن‌های کنترل مدلِ نشت‌کرده (`<|assistant|>`، سایر ASCII `<|...|>`، تمام‌عرض `<｜...｜>`) حذف می‌شوند؛ XML فراخوانی ابزار MiniMax ناقص حذف می‌شود.
- متن‌های شبیه اعتبارنامه/توکن پوشانده می‌شوند.
- یادآوری دستیار ابتدا نرمال‌سازی می‌شود: برچسب‌های تفکر حذف می‌شوند؛ چارچوب‌های `<relevant-memories>` / `<relevant_memories>` حذف می‌شوند؛ بلوک‌های بار XML فراخوانی ابزار در متن ساده (`<tool_call>`، `<function_call>`، `<tool_calls>`، `<function_calls>`) حذف می‌شوند، شامل بارهای کوتاه‌شده‌ای که هرگز تمیز بسته نمی‌شوند؛ چارچوب‌های تنزل‌یافته فراخوانی/نتیجه ابزار و نشانگرهای زمینه تاریخی حذف می‌شوند؛ توکن‌های کنترلی نشت‌کرده مدل (`<|assistant|>`، سایر `<|...|>`های ASCII، `<｜...｜>` تمام‌عرض) حذف می‌شوند؛ XML فراخوانی ابزار بدشکل MiniMax حذف می‌شود.
- متن‌هایی شبیه اعتبارنامه/توکن ویرایش می‌شوند.
- بلوک‌های طولانی می‌توانند کوتاه شوند.
- تاریخچه‌های بسیار بزرگ می‌توانند ردیف‌های قدیمی‌تر را حذف کنند یا یک ردیف بیش‌ازحد بزرگ را با `[sessions_history omitted: message too large]` جایگزین کنند.
- بررسی متن نشست خام روی دیسک گزینهٔ جایگزین است وقتی به متن نشست کاملِ بایت‌به‌بایت نیاز دارید.
- بررسی رونوشت خام روی دیسک، گزینه پشتیبان وقتی است که به رونوشت کامل و بایت‌به‌بایت نیاز دارید.
## سیاست ابزار
زیرعامل‌ها ابتدا از همان پروفایل و خط لولهٔ سیاست ابزار والد یا
عامل هدف استفاده می‌کنند. پس از آن، OpenClaw لایهٔ محدودیت زیرعامل را اعمال می‌کند.
عامل‌های فرعی ابتدا از همان پروفایل و خط لولهٔ سیاست ابزارِ عامل والد یا
عامل هدف استفاده می‌کنند. پس از آن، OpenClaw لایهٔ محدودیت عامل فرعی را
اعمال می‌کند.
بدون `tools.profile` محدودکننده، زیرعامل‌ها **همهٔ ابزارها به‌جز
ابزارهای نشست** و ابزارهای سیستم را دریافت می‌کنند:
بدون `tools.profile` محدودکننده، عامل‌های فرعی **همهٔ ابزارها به‌جز
ابزارهای جلسه** و ابزارهای سامانه را دریافت می‌کنند:
- `sessions_list`
- `sessions_history`
- `sessions_send`
- `sessions_spawn`
`sessions_history` در اینجا نیز یک نمای یادآوری محدود و پاک‌سازی‌شده باقی می‌ماند —
ریزگردان خام متن نشست نیست.
`sessions_history` اینجا نیز یک نمای یادآوری محدود و پاک‌سازی‌شده باقی می‌ماند؛
یک dump خام از transcript نیست.
وقتی `maxSpawnDepth >= 2` باشد، زیرعامل‌های هماهنگ‌کنندهٔ عمق ۱ علاوه بر این
`sessions_spawn`، `subagents`، `sessions_list` و
`sessions_history` را دریافت می‌کنند تا بتوانند فرزندانشان را مدیریت کنند.
وقتی `maxSpawnDepth >= 2` باشد، عامل‌های فرعیِ هماهنگ‌کننده در عمق ۱ علاوه بر آن
`sessions_spawn`، `subagents`، `sessions_list`، و
`sessions_history` را دریافت می‌کنند تا بتوانند فرزندان خود را مدیریت کنند.
### بازنویسی از طریق پیکربندی
@ -459,7 +479,12 @@ x-i18n:
}
```
`tools.subagents.tools.allow` یک فیلتر نهایی فقط-مجاز است. این گزینه می‌تواند مجموعه ابزارهای از پیش حل‌شده را محدودتر کند، اما نمی‌تواند ابزاری را که با `tools.profile` حذف شده است **دوباره اضافه کند**. برای مثال، `tools.profile: "coding"` شامل `web_search`/`web_fetch` است اما ابزار `browser` را شامل نمی‌شود. برای اینکه زیرعامل‌های پروفایل کدنویسی بتوانند از اتوماسیون مرورگر استفاده کنند، browser را در مرحله پروفایل اضافه کنید:
`tools.subagents.tools.allow` یک فیلتر نهایی فقط-مجاز است. می‌تواند
مجموعهٔ ابزار ازپیش‌حل‌شده را محدودتر کند، اما نمی‌تواند ابزاری را که
توسط `tools.profile` حذف شده است **دوباره اضافه کند**. برای مثال، `tools.profile: "coding"`
شامل `web_search`/`web_fetch` است اما ابزار `browser` را شامل نمی‌شود. برای اینکه
عامل‌های فرعیِ دارای پروفایل کدنویسی بتوانند از خودکارسازی مرورگر استفاده کنند،
مرورگر را در مرحلهٔ پروفایل اضافه کنید:
```json5
{
@ -470,44 +495,65 @@ x-i18n:
}
```
وقتی فقط یک عامل باید اتوماسیون مرورگر داشته باشد، از `agents.list[].tools.alsoAllow: ["browser"]` برای همان عامل استفاده کنید.
وقتی فقط یک عامل باید خودکارسازی مرورگر داشته باشد، از
`agents.list[].tools.alsoAllow: ["browser"]` برای همان عامل استفاده کنید.
## هم‌زمانی
زیرعامل‌ها از یک صف اختصاصی درون‌فرایندی استفاده می‌کنند:
عامل‌های فرعی از یک مسیر صف اختصاصی درون‌فرآیندی استفاده می‌کنند:
- **نام مسیر:** `subagent`
- **هم‌زمانی:** `agents.defaults.subagents.maxConcurrent` (پیش‌فرض `8`)
## زنده‌بودن و بازیابی
OpenClaw نبود `endedAt` را اثبات دائمی زنده‌بودن یک زیرعامل در نظر نمی‌گیرد. اجراهای پایان‌نیافته‌ای که از پنجره اجرای کهنه قدیمی‌تر هستند، دیگر در `/subagents list`، خلاصه‌های وضعیت، گیت‌گذاری تکمیل فرزندان، و بررسی‌های هم‌زمانی هر نشست به‌عنوان فعال/در انتظار شمارش نمی‌شوند.
OpenClaw نبودِ `endedAt` را مدرک دائمی برای زنده بودن یک
عامل فرعی در نظر نمی‌گیرد. اجراهای پایان‌نیافته‌ای که از پنجرهٔ اجرای کهنه
قدیمی‌تر باشند، دیگر در `/subagents list`، خلاصه‌های وضعیت،
دروازه‌گذاری تکمیل فرزندان، و بررسی‌های هم‌زمانی هر جلسه به‌عنوان فعال/در انتظار
شمرده نمی‌شوند.
پس از راه‌اندازی مجدد Gateway، اجراهای بازیابی‌شده پایان‌نیافته و کهنه حذف می‌شوند، مگر اینکه نشست فرزند آن‌ها با `abortedLastRun: true` علامت‌گذاری شده باشد. این نشست‌های فرزندی که بر اثر راه‌اندازی مجدد قطع شده‌اند، از طریق جریان بازیابی یتیم زیرعامل همچنان قابل بازیابی می‌مانند؛ این جریان پیش از پاک کردن نشانگر قطع‌شده، یک پیام ازسرگیری مصنوعی ارسال می‌کند.
پس از راه‌اندازی مجدد Gateway، اجراهای بازیابی‌شدهٔ پایان‌نیافتهٔ کهنه حذف می‌شوند مگر اینکه
جلسهٔ فرزند آن‌ها با `abortedLastRun: true` علامت‌گذاری شده باشد. آن
جلسه‌های فرزندِ قطع‌شده در راه‌اندازی مجدد، همچنان از طریق جریان بازیابی یتیمِ عامل فرعی
قابل بازیابی می‌مانند؛ این جریان پیش از پاک کردن نشانگر قطع‌شده،
یک پیام resume مصنوعی ارسال می‌کند.
بازیابی خودکار پس از راه‌اندازی مجدد برای هر نشست فرزند محدود است. اگر همان فرزند زیرعامل بارها در پنجره سریع گیرکردن دوباره برای بازیابی یتیم پذیرفته شود، OpenClaw یک سنگ‌نشان بازیابی روی آن نشست ثبت می‌کند و در راه‌اندازی‌های مجدد بعدی از ازسرگیری خودکار آن جلوگیری می‌کند. برای همگام‌سازی رکورد وظیفه، `openclaw tasks maintenance --apply` را اجرا کنید، یا برای پاک کردن پرچم‌های بازیابی قطع‌شده کهنه روی نشست‌های دارای سنگ‌نشان، `openclaw doctor --fix` را اجرا کنید.
بازیابی خودکار پس از راه‌اندازی مجدد برای هر جلسهٔ فرزند محدود است. اگر همان
فرزندِ عامل فرعی در بازهٔ گیرکردن دوبارهٔ سریع، بارها برای بازیابی یتیم پذیرفته شود،
OpenClaw یک tombstone بازیابی را روی آن جلسه ماندگار می‌کند و
در راه‌اندازی‌های مجدد بعدی، ادامهٔ خودکار آن را متوقف می‌کند. برای سازگار کردن رکورد task،
`openclaw tasks maintenance --apply` را اجرا کنید، یا برای پاک کردن پرچم‌های کهنهٔ بازیابیِ قطع‌شده
روی جلسه‌های tombstone‌شده، `openclaw doctor --fix` را اجرا کنید.
<Note>
اگر ایجاد زیرعامل با خطای Gateway `PAIRING_REQUIRED` / `scope-upgrade` شکست خورد، پیش از ویرایش وضعیت جفت‌سازی، فراخوان RPC را بررسی کنید. هماهنگی داخلی `sessions_spawn` باید از طریق احراز هویت مستقیم local loopback با توکن/گذرواژه مشترک، با `client.id: "gateway-client"` و `client.mode: "backend"` متصل شود؛ این مسیر به خط مبنای دامنه دستگاه جفت‌شده CLI وابسته نیست. فراخوان‌های راه دور، `deviceIdentity` صریح، مسیرهای صریح توکن دستگاه، و کلاینت‌های مرورگر/Node همچنان برای ارتقای دامنه به تأیید عادی دستگاه نیاز دارند.
اگر ایجاد عامل فرعی با Gateway `PAIRING_REQUIRED` /
`scope-upgrade` شکست خورد، پیش از ویرایش وضعیت pairing، فراخوان RPC را بررسی کنید.
هماهنگی داخلی `sessions_spawn` باید به‌صورت
`client.id: "gateway-client"` با `client.mode: "backend"` از طریق
auth مستقیم با shared-token/password روی local loopback وصل شود؛ آن مسیر به
خط پایهٔ scope دستگاه paired شدهٔ CLI وابسته نیست. فراخوان‌های remote، `deviceIdentity`
صریح، مسیرهای صریح device-token، و کلاینت‌های browser/node همچنان برای ارتقای scope
به تأیید عادی دستگاه نیاز دارند.
</Note>
## توقف
## متوقف کردن
- ارسال `/stop` در گفت‌وگوی درخواست‌دهنده، نشست درخواست‌دهنده را قطع می‌کند و هر اجرای فعال زیرعامل را که از آن ایجاد شده باشد متوقف می‌کند و این توقف به فرزندان تودرتو نیز سرایت می‌کند.
- `/subagents kill <id>` یک زیرعامل مشخص را متوقف می‌کند و این توقف به فرزندان آن نیز سرایت می‌کند.
- ارسال `/stop` در گفت‌وگوی درخواست‌کننده، جلسهٔ درخواست‌کننده را قطع می‌کند و هر اجرای فعال عامل فرعیِ ایجادشده از آن را متوقف می‌کند و این توقف به فرزندان تودرتو نیز آبشاری اعمال می‌شود.
- `/subagents kill <id>` یک عامل فرعی مشخص را متوقف می‌کند و این توقف به فرزندان آن نیز آبشاری اعمال می‌شود.
## محدودیت‌ها
- اعلام زیرعامل **در حد بهترین تلاش** است. اگر Gateway دوباره راه‌اندازی شود، کارهای در انتظار «اعلام بازگشتی» از دست می‌روند.
- زیرعامل‌ها همچنان منابع همان فرایند Gateway را به‌اشتراک می‌گذارند؛ `maxConcurrent` را به‌عنوان یک شیر ایمنی در نظر بگیرید.
- `sessions_spawn` همیشه غیرمسدودکننده است: بلافاصله `{ status: "accepted", runId, childSessionKey }` را برمی‌گرداند.
- زمینه زیرعامل فقط `AGENTS.md` + `TOOLS.md` را تزریق می‌کند (بدون `SOUL.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، یا `BOOTSTRAP.md`).
- بیشینه عمق تودرتوسازی 5 است (بازه `maxSpawnDepth`: 1 تا 5). عمق 2 برای بیشتر موارد استفاده توصیه می‌شود.
- `maxChildrenPerAgent` تعداد فرزندان فعال برای هر نشست را محدود می‌کند (پیش‌فرض `5`، بازه `1–20`).
- اعلام عامل فرعی **بهترین تلاش** است. اگر Gateway دوباره راه‌اندازی شود، کارهای در انتظار «اعلام برگشتی» از دست می‌روند.
- عامل‌های فرعی همچنان همان منابع فرآیند Gateway را به اشتراک می‌گذارند؛ `maxConcurrent` را به‌عنوان یک شیر اطمینان در نظر بگیرید.
- `sessions_spawn` همیشه non-blocking است: بلافاصله `{ status: "accepted", runId, childSessionKey }` را برمی‌گرداند.
- زمینهٔ عامل فرعی فقط `AGENTS.md` + `TOOLS.md` را تزریق می‌کند (بدون `SOUL.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، یا `BOOTSTRAP.md`).
- بیشینهٔ عمق تودرتویی ۵ است (بازهٔ `maxSpawnDepth`: ۱–۵). عمق ۲ برای بیشتر موارد استفاده توصیه می‌شود.
- `maxChildrenPerAgent` تعداد فرزندان فعال برای هر جلسه را محدود می‌کند (پیش‌فرض `5`، بازهٔ `1–20`).
## مرتبط
- [عامل‌های ACP](/fa/tools/acp-agents)
- [ارسال عامل](/fa/tools/agent-send)
- [وظیفه‌های پس‌زمینه](/fa/automation/tasks)
- [ابزارهای سندباکس چندعاملی](/fa/tools/multi-agent-sandbox-tools)
- [taskهای پس‌زمینه](/fa/automation/tasks)
- [ابزارهای sandbox چندعاملی](/fa/tools/multi-agent-sandbox-tools)

340
docs/fa/web/control-ui.md
View File

@ -1,239 +1,239 @@
---
read_when:
- می‌خواهید Gateway را از طریق یک مرورگر مدیریت کنید
- می‌خواهید Gateway را از طریق مرورگر مدیریت کنید
- دسترسی به Tailnet را بدون تونل‌های SSH می‌خواهید
sidebarTitle: Control UI
summary: رابط کاربری کنترل مبتنی بر مرورگر برای Gateway (چت، گره‌ها، پیکربندی)
summary: رابط کاربری کنترل مبتنی بر مرورگر برای Gateway (گفتگو، گره‌ها، پیکربندی)
title: رابط کاربری کنترل
x-i18n:
generated_at: "2026-05-04T02:29:06Z"
generated_at: "2026-05-04T07:08:30Z"
model: gpt-5.5
provider: openai
source_hash: c890d83da2c296b600e4b5a00a538f37e6bd54da31fbe62113ecd6177b15626e
source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5
source_path: web/control-ui.md
workflow: 16
---
رابط کاربری کنترل یک برنامه تک‌صفحه‌ای کوچک **Vite + Lit** است که توسط Gateway ارائه می‌شود:
رابط کاربری کنترل یک برنامه تک‌صفحه‌ای کوچک با **Vite + Lit** است که توسط Gateway ارائه می‌شود:
- پیش‌فرض: `http://<host>:18789/`
- پیشوند اختیاری: `gateway.controlUi.basePath` را تنظیم کنید (مثلاً `/openclaw`)
این رابط **مستقیماً با Gateway WebSocket** روی همان پورت ارتباط برقرار می‌کند.
این برنامه **مستقیماً با Gateway WebSocket** روی همان پورت ارتباط برقرار می‌کند.
## باز کردن سریع (محلی)
اگر Gateway روی همان رایانه در حال اجرا است، باز کنید:
اگر Gateway روی همان رایانه در حال اجراست، باز کنید:
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (یا [http://localhost:18789/](http://localhost:18789/))
اگر صفحه بارگذاری نشد، ابتدا Gateway را راه‌اندازی کنید: `openclaw gateway`.
احراز هویت هنگام دست‌دهی WebSocket از طریق موارد زیر ارائه می‌شود:
احراز هویت هنگام دست‌دهی WebSocket از این طریق ارائه می‌شود:
- `connect.params.auth.token`
- `connect.params.auth.password`
- سرآیندهای هویت Tailscale Serve وقتی `gateway.auth.allowTailscale: true` باشد
- سرآیندهای هویت پراکسی مورد اعتماد وقتی `gateway.auth.mode: "trusted-proxy"` باشد
- هدرهای هویت Tailscale Serve وقتی `gateway.auth.allowTailscale: true` باشد
- هدرهای هویت پراکسی مورد اعتماد وقتی `gateway.auth.mode: "trusted-proxy"` باشد
پنل تنظیمات داشبورد یک توکن را برای نشست زبانه فعلی مرورگر و نشانی Gateway انتخاب‌شده نگه می‌دارد؛ گذرواژه‌ها ذخیره نمی‌شوند. راه‌اندازی اولیه معمولاً در اولین اتصال، یک توکن Gateway برای احراز هویت با راز مشترک تولید می‌کند، اما احراز هویت با گذرواژه هم وقتی `gateway.auth.mode` برابر `"password"` باشد کار می‌کند.
پنل تنظیمات داشبورد یک توکن را برای نشست تب فعلی مرورگر و URL انتخاب‌شده Gateway نگه می‌دارد؛ گذرواژه‌ها ذخیره نمی‌شوند. راه‌اندازی اولیه معمولاً در اولین اتصال، یک توکن Gateway برای احراز هویت با راز مشترک تولید می‌کند، اما احراز هویت با گذرواژه نیز وقتی `gateway.auth.mode` برابر `"password"` باشد کار می‌کند.
## جفت‌سازی دستگاه (اتصال نخست)
## جفت‌سازی دستگاه (اولین اتصال)
وقتی از یک مرورگر یا دستگاه جدید به رابط کاربری کنترل وصل می‌شوید، Gateway معمولاً به **تأیید جفت‌سازی یک‌باره** نیاز دارد. این یک اقدام امنیتی برای جلوگیری از دسترسی غیرمجاز است.
وقتی از یک مرورگر یا دستگاه جدید به رابط کاربری کنترل وصل می‌شوید، Gateway معمولاً به **تأیید یک‌باره جفت‌سازی** نیاز دارد. این یک اقدام امنیتی برای جلوگیری از دسترسی غیرمجاز است.
**چیزی که می‌بینید:** "disconnected (1008): pairing required"
**چیزی که خواهید دید:** "disconnected (1008): pairing required"
<Steps>
<Step title="فهرست کردن درخواست‌های در انتظار">
<Step title="List pending requests">
```bash
openclaw devices list
```
</Step>
<Step title="تأیید با شناسه درخواست">
<Step title="Approve by request ID">
```bash
openclaw devices approve <requestId>
```
</Step>
</Steps>
اگر مرورگر با جزئیات احراز هویت تغییرکرده دوباره جفت‌سازی را تلاش کند (نقش/دامنه‌ها/کلید عمومی)، درخواست در انتظار قبلی جایگزین می‌شود و یک `requestId` جدید ساخته می‌شود. پیش از تأیید دوباره `openclaw devices list` را اجرا کنید.
اگر مرورگر جفت‌سازی را با جزئیات احراز هویت تغییرکرده (نقش/دامنه‌ها/کلید عمومی) دوباره امتحان کند، درخواست معلق قبلی جایگزین می‌شود و یک `requestId` جدید ایجاد می‌شود. پیش از تأیید، دوباره `openclaw devices list` را اجرا کنید.
اگر مرورگر از قبل جفت شده باشد و شما دسترسی آن را از خواندن به نوشتن/مدیریت تغییر دهید، این به‌عنوان ارتقای تأیید در نظر گرفته می‌شود، نه اتصال مجدد بی‌صدا. OpenClaw تأیید قبلی را فعال نگه می‌دارد، اتصال مجدد گسترده‌تر را مسدود می‌کند و از شما می‌خواهد مجموعه دامنه جدید را صریحاً تأیید کنید.
اگر مرورگر از قبل جفت شده باشد و آن را از دسترسی خواندن به دسترسی نوشتن/مدیر تغییر دهید، این کار به‌عنوان ارتقای تأیید در نظر گرفته می‌شود، نه اتصال مجدد بی‌صدا. OpenClaw تأیید قبلی را فعال نگه می‌دارد، اتصال مجدد با دامنه گسترده‌تر را مسدود می‌کند و از شما می‌خواهد مجموعه دامنه جدید را صریحاً تأیید کنید.
پس از تأیید، دستگاه به خاطر سپرده می‌شود و دیگر به تأیید دوباره نیاز ندارد مگر اینکه آن را با `openclaw devices revoke --device <id> --role <role>` لغو کنید. برای چرخش توکن و لغو، [CLI دستگاه‌ها](/fa/cli/devices) را ببینید.
پس از تأیید، دستگاه به خاطر سپرده می‌شود و تا زمانی که آن را با `openclaw devices revoke --device <id> --role <role>` لغو نکنید، به تأیید دوباره نیاز ندارد. برای چرخش و لغو توکن، [CLI دستگاه‌ها](/fa/cli/devices) را ببینید.
<Note>
- اتصال‌های مستقیم مرورگر از طریق local loopback (`127.0.0.1` / `localhost`) به‌طور خودکار تأیید می‌شوند.
- وقتی `gateway.auth.allowTailscale: true` باشد، هویت Tailscale تأیید شود، و مرورگر هویت دستگاه خود را ارائه کند، Tailscale Serve می‌تواند رفت‌وبرگشت جفت‌سازی را برای نشست‌های اپراتور رابط کاربری کنترل رد کند.
- اتصال‌های مستقیم مرورگر با local loopback (`127.0.0.1` / `localhost`) به‌طور خودکار تأیید می‌شوند.
- Tailscale Serve می‌تواند رفت‌وبرگشت جفت‌سازی را برای نشست‌های اپراتور رابط کاربری کنترل رد کند، وقتی `gateway.auth.allowTailscale: true` باشد، هویت Tailscale تأیید شود و مرورگر هویت دستگاه خود را ارائه کند.
- اتصال‌های مستقیم Tailnet، اتصال‌های مرورگر در LAN، و پروفایل‌های مرورگر بدون هویت دستگاه همچنان به تأیید صریح نیاز دارند.
- هر پروفایل مرورگر یک شناسه دستگاه یکتا تولید می‌کند، بنابراین تغییر مرورگر یا پاک کردن داده‌های مرورگر به جفت‌سازی دوباره نیاز خواهد داشت.
- هر پروفایل مرورگر یک شناسه دستگاه یکتا تولید می‌کند، بنابراین تغییر مرورگر یا پاک کردن داده‌های مرورگر نیازمند جفت‌سازی دوباره خواهد بود.
</Note>
## هویت شخصی (محلی مرورگر)
رابط کاربری کنترل از یک هویت شخصی به‌ازای هر مرورگر پشتیبانی می‌کند (نام نمایشی و آواتار) که برای انتساب در نشست‌های مشترک به پیام‌های خروجی پیوست می‌شود. این هویت در فضای ذخیره‌سازی مرورگر قرار دارد، به پروفایل مرورگر فعلی محدود است، و به دستگاه‌های دیگر همگام‌سازی نمی‌شود یا فراتر از فراداده معمول نویسندگی رونوشت برای پیام‌هایی که واقعاً ارسال می‌کنید، در سمت سرور ماندگار نمی‌شود. پاک کردن داده‌های سایت یا تغییر مرورگر آن را دوباره خالی می‌کند.
رابط کاربری کنترل از یک هویت شخصی برای هر مرورگر پشتیبانی می‌کند (نام نمایشی و آواتار) که برای انتساب در نشست‌های مشترک به پیام‌های خروجی پیوست می‌شود. این هویت در فضای ذخیره‌سازی مرورگر قرار دارد، به پروفایل مرورگر فعلی محدود است، و فراتر از فراداده معمول نویسندگی رونوشت پیام‌هایی که واقعاً ارسال می‌کنید، با دستگاه‌های دیگر همگام‌سازی یا در سمت سرور ماندگار نمی‌شود. پاک کردن داده‌های سایت یا تغییر مرورگر آن را به حالت خالی بازمی‌گرداند.
همین الگوی محلی مرورگر برای بازنویسی آواتار دستیار هم اعمال می‌شود. آواتارهای بارگذاری‌شده دستیار فقط در مرورگر محلی روی هویت حل‌شده توسط Gateway قرار می‌گیرند و هرگز از مسیر `config.patch` رفت‌وبرگشت نمی‌کنند. فیلد پیکربندی مشترک `ui.assistant.avatar` همچنان برای کلاینت‌های غیر UI که مستقیماً این فیلد را می‌نویسند در دسترس است (مانند Gatewayهای اسکریپتی یا داشبوردهای سفارشی).
همین الگوی محلی مرورگر برای جایگزینی آواتار دستیار نیز اعمال می‌شود. آواتارهای بارگذاری‌شده دستیار فقط در مرورگر محلی روی هویت حل‌شده توسط Gateway قرار می‌گیرند و هرگز از طریق `config.patch` رفت‌وبرگشت نمی‌شوند. فیلد پیکربندی مشترک `ui.assistant.avatar` همچنان برای کلاینت‌های غیر UI که فیلد را مستقیماً می‌نویسند در دسترس است (مانند Gatewayهای اسکریپتی یا داشبوردهای سفارشی).
## نقطه پایانی پیکربندی زمان اجرا
رابط کاربری کنترل تنظیمات زمان اجرای خود را از `/__openclaw/control-ui-config.json` دریافت می‌کند. آن نقطه پایانی با همان احراز هویت Gateway مانند بقیه سطح HTTP محافظت می‌شود: مرورگرهای احراز هویت‌نشده نمی‌توانند آن را دریافت کنند، و دریافت موفق به یک توکن/گذرواژه معتبر Gateway از قبل موجود، هویت Tailscale Serve، یا هویت پراکسی مورد اعتماد نیاز دارد.
رابط کاربری کنترل تنظیمات زمان اجرای خود را از `/__openclaw/control-ui-config.json` دریافت می‌کند. این نقطه پایانی با همان احراز هویت Gateway که برای بقیه سطح HTTP استفاده می‌شود محافظت می‌شود: مرورگرهای احراز هویت‌نشده نمی‌توانند آن را دریافت کنند، و دریافت موفق به یکی از این موارد نیاز دارد: توکن/گذرواژه Gateway که از قبل معتبر است، هویت Tailscale Serve، یا هویت پراکسی مورد اعتماد.
## پشتیبانی زبان
رابط کاربری کنترل می‌تواند در اولین بارگذاری بر اساس زبان مرورگر شما خود را بومی‌سازی کند. برای بازنویسی آن در آینده، **Overview -> Gateway Access -> Language** را باز کنید. انتخابگر زبان در کارت Gateway Access قرار دارد، نه زیر Appearance.
رابط کاربری کنترل می‌تواند در اولین بارگذاری بر اساس زبان مرورگر شما محلی‌سازی شود. برای بازنویسی آن در آینده، **Overview -> Gateway Access -> Language** را باز کنید. انتخابگر زبان در کارت Gateway Access قرار دارد، نه زیر Appearance.
- زبان‌های پشتیبانی‌شده: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
- ترجمه‌های غیرانگلیسی در مرورگر به‌صورت تنبل بارگذاری می‌شوند.
- زبان انتخاب‌شده در فضای ذخیره‌سازی مرورگر ذخیره می‌شود و در بازدیدهای آینده دوباره استفاده می‌شود.
- کلیدهای ترجمه موجودنباشد به انگلیسی برمی‌گردند.
- کلیدهای ترجمه گمشده به انگلیسی بازمی‌گردند.
ترجمه‌های مستندات برای همان مجموعه زبان‌های غیرانگلیسی تولید می‌شوند، اما انتخابگر زبان داخلی سایت مستندات Mintlify به کدهای زبانی محدود است که Mintlify می‌پذیرد. مستندات تایلندی (`th`) و فارسی (`fa`) همچنان در مخزن انتشار تولید می‌شوند؛ ممکن است تا زمانی که Mintlify از این کدها پشتیبانی نکند در آن انتخابگر ظاهر نشوند.
ترجمه‌های مستندات برای همان مجموعه زبان‌های غیرانگلیسی تولید می‌شوند، اما انتخابگر زبان داخلی سایت مستندات در Mintlify به کدهای زبانی محدود است که Mintlify می‌پذیرد. مستندات تایلندی (`th`) و فارسی (`fa`) همچنان در مخزن انتشار تولید می‌شوند؛ ممکن است تا زمانی که Mintlify از این کدها پشتیبانی کند در آن انتخابگر ظاهر نشوند.
## تم‌های ظاهری
## تم‌های ظاهر
پنل Appearance تم‌های داخلی Claw، Knot و Dash را به‌همراه یک جایگاه واردسازی tweakcn محلی مرورگر نگه می‌دارد. برای وارد کردن یک تم، [تم‌های tweakcn](https://tweakcn.com/themes) را باز کنید، یک تم انتخاب کنید یا بسازید، روی **Share** کلیک کنید و پیوند تم کپی‌شده را در Appearance بچسبانید. واردکننده همچنین URLهای رجیستری `https://tweakcn.com/r/themes/<id>`، URLهای ویرایشگر مانند `https://tweakcn.com/editor/theme?theme=amethyst-haze`، مسیرهای نسبی `/themes/<id>`، شناسه‌های خام تم، و نام‌های تم پیش‌فرض مانند `amethyst-haze` را می‌پذیرد.
پنل Appearance تم‌های داخلی Claw، Knot و Dash، به‌علاوه یک جایگاه واردسازی tweakcn محلی مرورگر را نگه می‌دارد. برای وارد کردن یک تم، [ویرایشگر tweakcn](https://tweakcn.com/editor/theme) را باز کنید، یک تم را انتخاب یا ایجاد کنید، روی **Share** کلیک کنید، و پیوند تم کپی‌شده را در Appearance جای‌گذاری کنید. واردکننده همچنین URLهای رجیستری `https://tweakcn.com/r/themes/<id>`، URLهای ویرایشگر مانند `https://tweakcn.com/editor/theme?theme=amethyst-haze`، مسیرهای نسبی `/themes/<id>`، شناسه‌های خام تم، و نام‌های تم پیش‌فرض مانند `amethyst-haze` را می‌پذیرد.
تم‌های واردشده فقط در پروفایل مرورگر فعلی ذخیره می‌شوند. آن‌ها در پیکربندی Gateway نوشته نمی‌شوند و بین دستگاه‌ها همگام‌سازی نمی‌شوند. جایگزین کردن تم واردشده همان یک جایگاه محلی را به‌روزرسانی می‌کند؛ پاک کردن آن اگر تم واردشده انتخاب شده باشد، تم فعال را به Claw برمی‌گرداند.
تم‌های واردشده فقط در پروفایل مرورگر فعلی ذخیره می‌شوند. آن‌ها در پیکربندی Gateway نوشته نمی‌شوند و بین دستگاه‌ها همگام‌سازی نمی‌شوند. جایگزین کردن تم واردشده همان یک جایگاه محلی را به‌روزرسانی می‌کند؛ پاک کردن آن، اگر تم واردشده انتخاب شده باشد، تم فعال را به Claw برمی‌گرداند.
## کارهایی که می‌تواند انجام دهد (امروز)
<AccordionGroup>
<Accordion title="چت و گفت‌وگو">
- گفت‌وگو با مدل از طریق Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
- گفت‌وگو از طریق نشست‌های بی‌درنگ مرورگر. OpenAI از WebRTC مستقیم استفاده می‌کند، Google Live از یک توکن محدود یک‌بارمصرف مرورگر روی WebSocket استفاده می‌کند، و Pluginهای صوتی بی‌درنگ فقط بک‌اند از انتقال رله Gateway استفاده می‌کنند. رله اطلاعات اعتبار ارائه‌دهنده را روی Gateway نگه می‌دارد، در حالی که مرورگر PCM میکروفون را از طریق RPCهای `talk.realtime.relay*` پخش می‌کند و فراخوانی‌های ابزار `openclaw_agent_consult` را از طریق `chat.send` به مدل OpenClaw بزرگ‌تر پیکربندی‌شده برمی‌گرداند.
- پخش فراخوانی‌های ابزار + کارت‌های خروجی زنده ابزار در چت (رویدادهای عامل).
<Accordion title="Chat and Talk">
- از طریق Gateway WS با مدل چت کنید (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
- از طریق نشست‌های بی‌درنگ مرورگر صحبت کنید. OpenAI از WebRTC مستقیم استفاده می‌کند، Google Live از یک توکن مرورگر یک‌بارمصرف محدود روی WebSocket استفاده می‌کند، و Pluginهای صوتی بی‌درنگ فقط-بک‌اند از انتقال رله Gateway استفاده می‌کنند. رله اعتبارنامه‌های ارائه‌دهنده را روی Gateway نگه می‌دارد، در حالی که مرورگر PCM میکروفن را از طریق RPCهای `talk.realtime.relay*` پخش می‌کند و فراخوانی‌های ابزار `openclaw_agent_consult` را برای مدل بزرگ‌تر پیکربندی‌شده OpenClaw از طریق `chat.send` برمی‌گرداند.
- فراخوانی‌های ابزار + کارت‌های خروجی زنده ابزار را در Chat پخش کنید (رویدادهای عامل).
</Accordion>
<Accordion title="کانال‌ها، نمونه‌ها، نشست‌ها، رویاها">
- کانال‌ها: داخلی به‌علاوه وضعیت کانال‌های Plugin بسته‌بندی‌شده/خارجی، ورود QR، و پیکربندی به‌ازای هر کانال (`channels.status`, `web.login.*`, `config.patch`).
- نمونه‌ها: فهرست حضور + تازه‌سازی (`system-presence`).
- نشست‌ها: فهرست + بازنویسی‌های مدل/تفکر/سریع/پرحرف/ردیابی/استدلال به‌ازای هر نشست (`sessions.list`, `sessions.patch`).
- رویاها: وضعیت dreaming، کلید فعال/غیرفعال، و خواننده دفترچه Dream (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
<Accordion title="Channels, instances, sessions, dreams">
- کانال‌ها: داخلی به‌علاوه وضعیت کانال‌های Plugin بسته‌بندی‌شده/خارجی، ورود QR، و پیکربندی برای هر کانال (`channels.status`, `web.login.*`, `config.patch`).
- نمونه‌ها: فهرست حضور + بازخوانی (`system-presence`).
- نشست‌ها: فهرست + بازنویسی‌های مدل/تفکر/سریع/پرحرف/ردیابی/استدلال برای هر نشست (`sessions.list`, `sessions.patch`).
- رویاها: وضعیت Dreaming، کلید فعال/غیرفعال، و خواننده دفترچه رویا (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
</Accordion>
<Accordion title="Cron، Skills، Nodeها، تأییدهای اجرا">
- کارهای Cron: فهرست/افزودن/ویرایش/اجرا/فعال‌سازی/غیرفعال‌سازی + تاریخچه اجرا (`cron.*`).
<Accordion title="Cron, skills, nodes, exec approvals">
- کارهای Cron: فهرست/افزودن/ویرایش/اجرا/فعال/غیرفعال + تاریخچه اجرا (`cron.*`).
- Skills: وضعیت، فعال/غیرفعال، نصب، به‌روزرسانی‌های کلید API (`skills.*`).
- Nodeها: فهرست + قابلیت‌ها (`node.list`).
- تأییدهای اجرا: ویرایش فهرست‌های مجاز Gateway یا Node + سیاست درخواست برای `exec host=gateway/node` (`exec.approvals.*`).
- گره‌ها: فهرست + قابلیت‌ها (`node.list`).
- تأییدهای اجرا: ویرایش فهرست‌های مجاز Gateway یا گره + سیاست پرسش برای `exec host=gateway/node` (`exec.approvals.*`).
</Accordion>
<Accordion title="پیکربندی">
<Accordion title="Config">
- مشاهده/ویرایش `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
- اعمال + راه‌اندازی مجدد همراه با اعتبارسنجی (`config.apply`) و بیدار کردن آخرین نشست فعال.
- نوشتن‌ها شامل یک محافظ هش پایه برای جلوگیری از بازنویسی و از بین بردن ویرایش‌های هم‌زمان است.
- نوشتن‌ها (`config.set`/`config.apply`/`config.patch`) پیش از اجرا، تفکیک SecretRefهای فعال را برای ارجاع‌های موجود در بار پیکربندی ارسالی بررسی می‌کنند؛ ارجاع‌های فعال ارسالی که قابل تفکیک نباشند پیش از نوشتن رد می‌شوند.
- رندر طرح‌واره + فرم (`config.schema` / `config.schema.lookup`، شامل `title` / `description` فیلد، راهنمایی‌های UI منطبق، خلاصه‌های فرزند بلافاصله، فراداده مستندات روی گره‌های شیء تو‌در‌تو/وایلدکارت/آرایه/ترکیب، به‌علاوه طرح‌واره‌های Plugin + کانال در صورت موجود بودن)؛ ویرایشگر Raw JSON فقط وقتی در دسترس است که عکس‌برداری یک رفت‌وبرگشت خام امن داشته باشد.
- اگر یک عکس‌برداری نتواند متن خام را با ایمنی رفت‌وبرگشت کند، رابط کاربری کنترل حالت Form را اجباری می‌کند و حالت Raw را برای آن عکس‌برداری غیرفعال می‌کند.
- گزینه "Reset to saved" در ویرایشگر Raw JSON شکل نوشته‌شده خام را حفظ می‌کند (قالب‌بندی، نظرها، چیدمان `$include`) به‌جای اینکه یک عکس‌برداری تخت‌شده را دوباره رندر کند، بنابراین ویرایش‌های خارجی وقتی عکس‌برداری بتواند با ایمنی رفت‌وبرگشت کند پس از بازنشانی باقی می‌مانند.
- مقدارهای شیء ساختاریافته SecretRef در ورودی‌های متنی فرم فقط‌خواندنی رندر می‌شوند تا از خراب‌شدن تصادفی شیء به رشته جلوگیری شود.
- نوشتن‌ها شامل محافظ هش پایه برای جلوگیری از بازنویسی ناخواسته ویرایش‌های هم‌زمان هستند.
- نوشتن‌ها (`config.set`/`config.apply`/`config.patch`) پیش از اجرا، حل SecretRef فعال را برای ارجاع‌های موجود در بار پیکربندی ارسال‌شده بررسی می‌کنند؛ ارجاع‌های فعال ارسال‌شده که حل‌نشده باشند پیش از نوشتن رد می‌شوند.
- طرح‌واره + رندر فرم (`config.schema` / `config.schema.lookup`، شامل فیلد `title` / `description`، راهنمایی‌های UI منطبق، خلاصه‌های فرزند مستقیم، فراداده مستندات روی گره‌های تو در توی شیء/وایلدکارت/آرایه/ترکیب، به‌علاوه طرح‌واره‌های Plugin + کانال وقتی در دسترس باشند)؛ ویرایشگر JSON خام فقط وقتی در دسترس است که نماگرفت یک رفت‌وبرگشت خام ایمن داشته باشد.
- اگر یک نماگرفت نتواند متن خام را به‌طور ایمن رفت‌وبرگشت کند، رابط کاربری کنترل حالت Form را اجباری می‌کند و حالت Raw را برای آن نماگرفت غیرفعال می‌کند.
- گزینه "Reset to saved" در ویرایشگر JSON خام، شکل نوشته‌شده خام را حفظ می‌کند (قالب‌بندی، دیدگاه‌ها، چیدمان `$include`) به‌جای اینکه یک نماگرفت تخت‌شده را دوباره رندر کند، بنابراین وقتی نماگرفت بتواند به‌طور ایمن رفت‌وبرگشت کند، ویرایش‌های خارجی پس از بازنشانی باقی می‌مانند.
- مقادیر شیء ساختاریافته SecretRef در ورودی‌های متنی فرم فقط-خواندنی رندر می‌شوند تا از خراب شدن تصادفی شیء به رشته جلوگیری شود.
</Accordion>
<Accordion title="اشکال‌زدایی، گزارش‌ها، به‌روزرسانی">
- اشکال‌زدایی: عکس‌برداری‌های وضعیت/سلامت/مدل‌ها + گزارش رویداد + فراخوانی‌های دستی RPC (`status`, `health`, `models.list`).
- گزارش‌ها: دنبال‌کردن زنده گزارش‌های فایل Gateway همراه با فیلتر/صدور (`logs.tail`).
- به‌روزرسانی: اجرای به‌روزرسانی بسته/git + راه‌اندازی مجدد (`update.run`) همراه با گزارش راه‌اندازی مجدد، سپس نظرسنجی `update.status` پس از اتصال مجدد برای تأیید نسخه Gateway در حال اجرا.
<Accordion title="Debug, logs, update">
- اشکال‌زدایی: نماگرفت‌های وضعیت/سلامت/مدل‌ها + گزارش رویداد + فراخوانی‌های دستی RPC (`status`, `health`, `models.list`).
- گزارش‌ها: دنبال‌کردن زنده گزارش‌های فایل Gateway با فیلتر/خروجی‌گیری (`logs.tail`).
- به‌روزرسانی: اجرای به‌روزرسانی بسته/git + راه‌اندازی مجدد (`update.run`) همراه با گزارش راه‌اندازی مجدد، سپس نظرسنجی `update.status` پس از اتصال دوباره برای تأیید نسخه Gateway در حال اجرا.
</Accordion>
<Accordion title="نکات پنل کارهای Cron">
- برای کارهای ایزوله، تحویل به‌طور پیش‌فرض اعلام خلاصه است. اگر اجراهای فقط داخلی می‌خواهید می‌توانید آن را به none تغییر دهید.
- وقتی announce انتخاب شده باشد، فیلدهای کانال/هدف ظاهر می‌شوند.
- حالت Webhook از `delivery.mode = "webhook"` استفاده می‌کند و `delivery.to` روی یک URL معتبر HTTP(S) Webhook تنظیم می‌شود.
- برای کارهای نشست اصلی، حالت‌های تحویل webhook و none در دسترس هستند.
- کنترل‌های ویرایش پیشرفته شامل حذف پس از اجرا، پاک کردن بازنویسی عامل، گزینه‌های exact/stagger برای cron، بازنویسی‌های مدل/تفکر عامل، و کلیدهای تحویل best-effort هستند.
- اعتبارسنجی فرم به‌صورت درون‌خطی همراه با خطاهای سطح فیلد است؛ مقدارهای نامعتبر دکمه ذخیره را تا زمان اصلاح غیرفعال می‌کنند.
- `cron.webhookToken` را تنظیم کنید تا یک توکن bearer اختصاصی ارسال شود؛ اگر حذف شود Webhook بدون سرآیند احراز هویت ارسال می‌شود.
- جایگزین منسوخ: کارهای قدیمی ذخیره‌شده با `notify: true` همچنان تا زمان مهاجرت می‌توانند از `cron.webhook` استفاده کنند.
<Accordion title="Cron jobs panel notes">
- برای کارهای ایزوله، تحویل به‌طور پیش‌فرض روی اعلام خلاصه است. اگر اجراهای فقط داخلی می‌خواهید، می‌توانید آن را به هیچ تغییر دهید.
- وقتی اعلام انتخاب شود، فیلدهای کانال/هدف ظاهر می‌شوند.
- حالت Webhook از `delivery.mode = "webhook"` با `delivery.to` تنظیم‌شده روی یک URL معتبر Webhook با HTTP(S) استفاده می‌کند.
- برای کارهای نشست اصلی، حالت‌های تحویل Webhook و هیچ در دسترس هستند.
- کنترل‌های ویرایش پیشرفته شامل حذف پس از اجرا، پاک کردن بازنویسی عامل، گزینه‌های دقیق/پراکنده Cron، بازنویسی‌های مدل/تفکر عامل، و کلیدهای تحویل با بهترین تلاش هستند.
- اعتبارسنجی فرم به‌صورت درون‌خطی با خطاهای سطح فیلد انجام می‌شود؛ مقادیر نامعتبر تا زمان اصلاح، دکمه ذخیره را غیرفعال می‌کنند.
- برای ارسال یک توکن حامل اختصاصی، `cron.webhookToken` را تنظیم کنید؛ اگر حذف شود، Webhook بدون هدر احراز هویت ارسال می‌شود.
- جایگزین منسوخ: کارهای قدیمی ذخیره‌شده با `notify: true` همچنان می‌توانند تا زمان مهاجرت از `cron.webhook` استفاده کنند.
</Accordion>
</AccordionGroup>
## رفتار چت
## رفتار Chat
<AccordionGroup>
<Accordion title="معنای ارسال و تاریخچه">
- `chat.send` **غیرمسدودکننده** است: بلافاصله با `{ runId, status: "started" }` تأیید می‌کند و پاسخ از طریق رویدادهای `chat` پخش می‌شود.
- بارگذاری‌های چت تصویرها و فایل‌های غیر ویدیویی را می‌پذیرد. تصویرها مسیر تصویر بومی را حفظ می‌کنند؛ فایل‌های دیگر به‌عنوان رسانه مدیریت‌شده ذخیره می‌شوند و در تاریخچه به‌صورت لینک‌های پیوست نمایش داده می‌شوند.
- ارسال دوباره با همان `idempotencyKey` هنگام اجرا `{ status: "in_flight" }` و پس از تکمیل `{ status: "ok" }` را برمی‌گرداند.
- پاسخ‌های `chat.history` برای ایمنی UI از نظر اندازه محدود می‌شوند. وقتی ورودی‌های رونوشت بیش از حد بزرگ باشند، Gateway ممکن است فیلدهای متنی طولانی را کوتاه کند، بلوک‌های فراداده سنگین را حذف کند، و پیام‌های بیش از حد بزرگ را با یک جای‌نگهدار (`[chat.history omitted: message too large]`) جایگزین کند.
- تصویرهای دستیار/تولیدشده به‌صورت ارجاع‌های رسانه مدیریت‌شده پایدار می‌شوند و از طریق URLهای رسانه احرازهویت‌شده Gateway دوباره ارائه می‌شوند، بنابراین بارگذاری‌های مجدد به ماندن بارهای تصویر base64 خام در پاسخ تاریخچه چت وابسته نیستند.
- `chat.history` همچنین برچسب‌های دستور درون‌خطی فقط‌نمایشی را از متن قابل‌مشاهده دستیار حذف می‌کند (برای مثال `[[reply_to_*]]` و `[[audio_as_voice]]`)، بارهای XML فراخوانی ابزار به‌صورت متن ساده (شامل `<tool_call>...</tool_call>`، `<function_call>...</function_call>`، `<tool_calls>...</tool_calls>`، `<function_calls>...</function_calls>`، و بلوک‌های فراخوانی ابزار کوتاه‌شده)، و توکن‌های کنترل مدل ASCII/تمام‌عرض نشت‌کرده را حذف می‌کند، و ورودی‌های دستیار را که کل متن قابل‌مشاهده آن‌ها فقط توکن خاموش دقیق `NO_REPLY` / `no_reply` است کنار می‌گذارد.
- هنگام یک ارسال فعال و تازه‌سازی نهایی تاریخچه، اگر `chat.history` برای مدت کوتاهی یک اسنپ‌شات قدیمی‌تر برگرداند، نمای چت پیام‌های خوش‌بینانه محلی کاربر/دستیار را قابل‌مشاهده نگه می‌دارد؛ رونوشت مرجع پس از همگام شدن تاریخچه Gateway آن پیام‌های محلی را جایگزین می‌کند.
- رویدادهای زنده `chat` وضعیت تحویل هستند، در حالی که `chat.history` از رونوشت پایدار نشست دوباره ساخته می‌شود. پس از رویدادهای نهایی ابزار، Control UI تاریخچه را دوباره بارگذاری می‌کند و فقط یک دنباله خوش‌بینانه کوچک را ادغام می‌کند؛ مرز رونوشت در [WebChat](/fa/web/webchat) مستند شده است.
- `chat.send` **غیرمسدودکننده** است: بلافاصله با `{ runId, status: "started" }` تأیید می‌کند و پاسخ از طریق رویدادهای `chat` جریان می‌یابد.
- بارگذاری‌های چت تصویرها را همراه با فایل‌های غیر ویدیویی می‌پذیرند. تصویرها مسیر تصویر بومی را حفظ می‌کنند؛ فایل‌های دیگر به‌عنوان رسانهٔ مدیریت‌شده ذخیره می‌شوند و در تاریخچه به‌صورت لینک‌های پیوست نمایش داده می‌شوند.
- ارسال دوباره با همان `idempotencyKey` در زمان اجرا `{ status: "in_flight" }` و پس از تکمیل `{ status: "ok" }` را برمی‌گرداند.
- پاسخ‌های `chat.history` برای ایمنی UI از نظر اندازه محدود هستند. وقتی ورودی‌های رونوشت بیش از حد بزرگ باشند، Gateway ممکن است فیلدهای متنی طولانی را کوتاه کند، بلوک‌های فرادادهٔ سنگین را حذف کند، و پیام‌های بیش‌ازحد بزرگ را با یک جانگهدار (`[chat.history omitted: message too large]`) جایگزین کند.
- تصویرهای دستیار/تولیدشده به‌صورت ارجاع‌های رسانهٔ مدیریت‌شده پایدار می‌شوند و از طریق URLهای رسانهٔ احرازهویت‌شدهٔ Gateway دوباره ارائه می‌شوند، بنابراین بارگذاری‌های مجدد به باقی‌ماندن payloadهای خام تصویر base64 در پاسخ تاریخچهٔ چت وابسته نیستند.
- `chat.history` همچنین برچسب‌های دستور درون‌خطیِ صرفاً نمایشی را از متن قابل‌مشاهدهٔ دستیار حذف می‌کند (برای مثال `[[reply_to_*]]` و `[[audio_as_voice]]`)، payloadهای XML فراخوانی ابزار در متن ساده (از جمله `<tool_call>...</tool_call>`، `<function_call>...</function_call>`، `<tool_calls>...</tool_calls>`، `<function_calls>...</function_calls>`، و بلوک‌های کوتاه‌شدهٔ فراخوانی ابزار)، و توکن‌های کنترل مدل ASCII/تمام‌عرضِ نشت‌کرده را حذف می‌کند، و ورودی‌های دستیار را که کل متن قابل‌مشاهدهٔ آن‌ها فقط توکن سکوت دقیق `NO_REPLY` / `no_reply` است کنار می‌گذارد.
- در طول یک ارسال فعال و تازه‌سازی نهایی تاریخچه، اگر `chat.history` برای لحظه‌ای یک snapshot قدیمی‌تر برگرداند، نمای چت پیام‌های خوش‌بینانهٔ محلی کاربر/دستیار را قابل‌مشاهده نگه می‌دارد؛ وقتی تاریخچهٔ Gateway به‌روز شد، رونوشت رسمی جای آن پیام‌های محلی را می‌گیرد.
- رویدادهای زندهٔ `chat` وضعیت تحویل هستند، در حالی که `chat.history` از رونوشت پایدار نشست بازسازی می‌شود. پس از رویدادهای نهایی ابزار، Control UI تاریخچه را دوباره بارگذاری می‌کند و فقط یک دنبالهٔ خوش‌بینانهٔ کوچک را ادغام می‌کند؛ مرز رونوشت در [WebChat](/fa/web/webchat) مستند شده است.
- `chat.inject` یک یادداشت دستیار را به رونوشت نشست اضافه می‌کند و یک رویداد `chat` را برای به‌روزرسانی‌های فقط UI پخش می‌کند (بدون اجرای عامل، بدون تحویل کانال).
- انتخابگرهای مدل و تفکر در سرآیند چت، نشست فعال را بلافاصله از طریق `sessions.patch` وصله می‌کنند؛ آن‌ها بازنویسی‌های پایدار نشست هستند، نه گزینه‌های ارسال فقط برای یک نوبت.
- تایپ `/new` در Control UI همان نشست داشبورد تازه New Chat را ایجاد می‌کند و به آن جابه‌جا می‌شود. تایپ `/reset` بازنشانی صریح درجا Gateway را برای نشست فعلی نگه می‌دارد.
- انتخابگر مدل چت نمای مدل پیکربندی‌شده Gateway را درخواست می‌کند. اگر `agents.defaults.models` وجود داشته باشد، همان فهرست مجاز انتخابگر را هدایت می‌کند. در غیر این صورت انتخابگر ورودی‌های صریح `models.providers.*.models` را به‌همراه ارائه‌دهندگانی که احراز هویت قابل‌استفاده دارند نشان می‌دهد. کاتالوگ کامل از طریق RPC اشکال‌زدایی `models.list` با `view: "all"` همچنان در دسترس می‌ماند.
- وقتی گزارش‌های استفاده نشست تازه Gateway فشار بالای زمینه را نشان دهند، ناحیه نوشتن چت یک اعلان زمینه نشان می‌دهد و، در سطح‌های پیشنهادی Compaction، یک دکمه فشرده که مسیر عادی Compaction نشست را اجرا می‌کند. اسنپ‌شات‌های توکن کهنه تا زمانی که Gateway دوباره استفاده تازه را گزارش کند پنهان می‌شوند.
- انتخابگرهای مدل و تفکر در سربرگ چت، نشست فعال را بلافاصله از طریق `sessions.patch` وصله می‌کنند؛ آن‌ها overrideهای پایدار نشست هستند، نه گزینه‌های ارسال فقط برای یک نوبت.
- تایپ `/new` در Control UI همان نشست تازهٔ داشبورد را مثل New Chat ایجاد کرده و به آن جابه‌جا می‌شود. تایپ `/reset` ریست صریح درجا برای نشست فعلی Gateway را حفظ می‌کند.
- انتخابگر مدل چت نمای مدل پیکربندی‌شدهٔ Gateway را درخواست می‌کند. اگر `agents.defaults.models` وجود داشته باشد، همان allowlist انتخابگر را هدایت می‌کند. در غیر این صورت انتخابگر ورودی‌های صریح `models.providers.*.models` را به‌همراه providerهایی که auth قابل‌استفاده دارند نشان می‌دهد. کاتالوگ کامل از طریق RPC اشکال‌زدایی `models.list` با `view: "all"` در دسترس می‌ماند.
- وقتی گزارش‌های تازهٔ مصرف نشست Gateway فشار بالای context را نشان دهند، ناحیهٔ composer چت یک اعلان context نشان می‌دهد و در سطح‌های پیشنهادی Compaction، دکمه‌ای فشرده که مسیر معمول Compaction نشست را اجرا می‌کند. snapshotهای قدیمی توکن تا زمانی که Gateway دوباره مصرف تازه را گزارش کند پنهان می‌شوند.
</Accordion>
<Accordion title="حالت گفت‌وگو (بی‌درنگ در مرورگر)">
حالت گفت‌وگو از یک ارائه‌دهنده صوتی بی‌درنگ ثبت‌شده استفاده می‌کند. OpenAI را با `talk.provider: "openai"` به‌همراه `talk.providers.openai.apiKey` پیکربندی کنید، یا Google را با `talk.provider: "google"` به‌همراه `talk.providers.google.apiKey` پیکربندی کنید؛ پیکربندی ارائه‌دهنده بی‌درنگ Voice Call همچنان می‌تواند به‌عنوان جایگزین دوباره استفاده شود. مرورگر هرگز یک کلید API استاندارد ارائه‌دهنده را دریافت نمی‌کند. OpenAI یک راز کلاینت Realtime موقت برای WebRTC دریافت می‌کند. Google Live یک توکن احراز هویت Live API محدود و یک‌بارمصرف برای یک نشست WebSocket مرورگر دریافت می‌کند که دستورالعمل‌ها و اعلان‌های ابزار توسط Gateway در توکن قفل شده‌اند. ارائه‌دهندگانی که فقط یک پل بی‌درنگ بک‌اند ارائه می‌کنند از طریق انتقال رله Gateway اجرا می‌شوند، بنابراین اعتبارنامه‌ها و سوکت‌های فروشنده سمت سرور می‌مانند در حالی که صدای مرورگر از طریق RPCهای احرازهویت‌شده Gateway جابه‌جا می‌شود. پرامپت نشست Realtime توسط Gateway مونتاژ می‌شود؛ `talk.realtime.session` بازنویسی دستورالعمل ارائه‌شده توسط فراخواننده را نمی‌پذیرد.
<Accordion title="حالت گفت‌وگو (بلادرنگ مرورگر)">
حالت گفت‌وگو از یک provider صدای بلادرنگ ثبت‌شده استفاده می‌کند. OpenAI را با `talk.provider: "openai"` به‌همراه `talk.providers.openai.apiKey` پیکربندی کنید، یا Google را با `talk.provider: "google"` به‌همراه `talk.providers.google.apiKey` پیکربندی کنید؛ پیکربندی provider بلادرنگ Voice Call همچنان می‌تواند به‌عنوان fallback دوباره استفاده شود. مرورگر هرگز یک کلید API استاندارد provider دریافت نمی‌کند. OpenAI یک secret موقت Realtime client برای WebRTC دریافت می‌کند. Google Live یک توکن auth محدود و یک‌بارمصرف Live API برای نشست WebSocket مرورگر دریافت می‌کند، با دستورالعمل‌ها و اعلان‌های ابزار که توسط Gateway داخل توکن قفل شده‌اند. providerهایی که فقط یک پل بلادرنگ backend ارائه می‌کنند از طریق انتقال relay در Gateway اجرا می‌شوند، بنابراین credentialها و socketهای فروشنده سمت سرور می‌مانند، در حالی که صدای مرورگر از طریق RPCهای احرازهویت‌شدهٔ Gateway جابه‌جا می‌شود. prompt نشست Realtime توسط Gateway مونتاژ می‌شود؛ `talk.realtime.session` overrideهای دستورالعملِ ارائه‌شده توسط caller را نمی‌پذیرد.
در سازنده چت، کنترل گفت‌وگو دکمه موج‌ها کنار دکمه دیکته میکروفون است. وقتی گفت‌وگو شروع می‌شود، ردیف وضعیت سازنده ابتدا `Connecting Talk...` را نشان می‌دهد، سپس وقتی صدا متصل است `Talk live`، یا وقتی یک فراخوانی ابزار بی‌درنگ از طریق `chat.send` در حال مشورت با مدل بزرگ‌تر پیکربندی‌شده است `Asking OpenClaw...` را نشان می‌دهد.
در composer چت، کنترل Talk دکمهٔ موج‌ها کنار دکمهٔ دیکتهٔ میکروفون است. وقتی Talk شروع می‌شود، ردیف وضعیت composer ابتدا `Connecting Talk...`، سپس هنگام اتصال صدا `Talk live`، یا هنگام مشورت یک فراخوانی ابزار بلادرنگ با مدل بزرگ‌تر پیکربندی‌شده از طریق `chat.send`، `Asking OpenClaw...` را نشان می‌دهد.
دودآزمون زنده نگه‌دارنده: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` تبادل SDP مرورگر WebRTC برای OpenAI، راه‌اندازی WebSocket مرورگر با توکن محدود Google Live، و آداپتور مرورگر رله Gateway با رسانه میکروفون جعلی را راستی‌آزمایی می‌کند. فرمان فقط وضعیت ارائه‌دهنده را چاپ می‌کند و رازها را ثبت نمی‌کند.
smoke زندهٔ maintainer: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` تبادل SDP مربوط به WebRTC مرورگر OpenAI، راه‌اندازی WebSocket مرورگر Google Live با توکن محدود، و adapter مرورگر relay Gateway با رسانهٔ میکروفون جعلی را تأیید می‌کند. این دستور فقط وضعیت provider را چاپ می‌کند و secretها را log نمی‌کند.
</Accordion>
<Accordion title="توقف و لغو">
- روی **توقف** کلیک کنید (`chat.abort` را فراخوانی می‌کند).
- وقتی یک اجرا فعال است، پیگیری‌های عادی در صف قرار می‌گیرند. روی **هدایت** در یک پیام صف‌شده کلیک کنید تا آن پیگیری در نوبت در حال اجرا تزریق شود.
- برای لغو خارج از باند، `/stop` را تایپ کنید (یا عبارت‌های مستقل لغو مانند `stop`، `stop action`، `stop run`، `stop openclaw`، `please stop`).
- `chat.abort` از `{ sessionKey }` (بدون `runId`) پشتیبانی می‌کند تا همه اجراهای فعال آن نشست را لغو کند.
- وقتی یک اجرا فعال است، follow-upهای عادی در صف قرار می‌گیرند. روی **Steer** در یک پیام صف‌شده کلیک کنید تا آن follow-up به نوبت در حال اجرا تزریق شود.
- برای لغو خارج از باند، `/stop` را تایپ کنید (یا عبارت‌های لغو مستقل مثل `stop`، `stop action`، `stop run`، `stop openclaw`، `please stop`).
- `chat.abort` از `{ sessionKey }` (بدون `runId`) برای لغو همهٔ اجراهای فعال آن نشست پشتیبانی می‌کند.
</Accordion>
<Accordion title="نگهداری بخش جزئی پس از لغو">
<Accordion title="نگه‌داری جزئی پس از لغو">
- وقتی یک اجرا لغو می‌شود، متن جزئی دستیار همچنان می‌تواند در UI نشان داده شود.
- Gateway وقتی خروجی بافرشده وجود داشته باشد، متن جزئی دستیار لغوشده را در تاریخچه رونوشت پایدار می‌کند.
- ورودی‌های پایدارشده شامل فراداده لغو هستند تا مصرف‌کنندگان رونوشت بتوانند بخش‌های جزئی لغو را از خروجی تکمیل عادی تشخیص دهند.
- Gateway متن جزئی لغوشدهٔ دستیار را وقتی خروجی bufferشده وجود داشته باشد در تاریخچهٔ رونوشت پایدار می‌کند.
- ورودی‌های پایدارشده شامل فرادادهٔ لغو هستند تا مصرف‌کنندگان رونوشت بتوانند جزئیات لغوشده را از خروجی تکمیل عادی تشخیص دهند.
</Accordion>
</AccordionGroup>
## نصب PWA و Web Push
Control UI یک `manifest.webmanifest` و یک service worker ارائه می‌کند، بنابراین مرورگرهای مدرن می‌توانند آن را به‌عنوان یک PWA مستقل نصب کنند. Web Push به Gateway امکان می‌دهد PWA نصب‌شده را حتی وقتی تب یا پنجره مرورگر باز نیست، با اعلان‌ها بیدار کند.
Control UI یک `manifest.webmanifest` و یک service worker عرضه می‌کند، بنابراین مرورگرهای مدرن می‌توانند آن را به‌عنوان یک PWA مستقل نصب کنند. Web Push به Gateway اجازه می‌دهد حتی وقتی تب یا پنجرهٔ مرورگر باز نیست، PWA نصب‌شده را با اعلان‌ها بیدار کند.
| سطح | کاری که انجام می‌دهد |
| سطح | کاری که انجام می‌دهد |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| `ui/public/manifest.webmanifest` | مانیفست PWA. مرورگرها وقتی قابل دسترسی شود، «نصب برنامه» را پیشنهاد می‌کنند. |
| `ui/public/manifest.webmanifest` | manifest مربوط به PWA. مرورگرها پس از قابل‌دسترس شدن آن، «Install app» را پیشنهاد می‌کنند. |
| `ui/public/sw.js` | service worker که رویدادهای `push` و کلیک‌های اعلان را مدیریت می‌کند. |
| `push/vapid-keys.json` (در دایرکتوری وضعیت OpenClaw) | جفت‌کلید VAPID خودکار تولیدشده که برای امضای بارهای Web Push استفاده می‌شود. |
| `push/web-push-subscriptions.json` | endpointهای اشتراک مرورگر پایدارشده. |
| `push/vapid-keys.json` (زیر دایرکتوری state مربوط به OpenClaw) | جفت‌کلید VAPID تولیدشده به‌صورت خودکار که برای امضای payloadهای Web Push استفاده می‌شود. |
| `push/web-push-subscriptions.json` | endpointهای اشتراک مرورگرِ پایدارشده. |
وقتی می‌خواهید کلیدها را ثابت نگه دارید (برای استقرارهای چندمیزبانه، چرخش رازها، یا آزمایش‌ها)، جفت‌کلید VAPID را از طریق متغیرهای محیطی روی فرایند Gateway بازنویسی کنید:
وقتی می‌خواهید کلیدها را ثابت کنید (برای استقرارهای چندمیزبانه، چرخش secretها، یا تست‌ها)، جفت‌کلید VAPID را از طریق env varها روی پردازش Gateway override کنید:
- `OPENCLAW_VAPID_PUBLIC_KEY`
- `OPENCLAW_VAPID_PRIVATE_KEY`
- `OPENCLAW_VAPID_SUBJECT` (پیش‌فرض `mailto:openclaw@localhost`)
- `OPENCLAW_VAPID_SUBJECT` (پیش‌فرض `mailto:openclaw@localhost` است)
Control UI از این روش‌های Gateway محدودشده با دامنه برای ثبت و آزمایش اشتراک‌های مرورگر استفاده می‌کند:
Control UI از این متدهای Gateway محدودشده با scope برای ثبت و تست اشتراک‌های مرورگر استفاده می‌کند:
- `push.web.vapidPublicKey` — کلید عمومی VAPID فعال را دریافت می‌کند.
- `push.web.subscribe` — یک `endpoint` را به‌همراه `keys.p256dh`/`keys.auth` ثبت می‌کند.
- `push.web.unsubscribe` — یک endpoint ثبت‌شده را حذف می‌کند.
- `push.web.test` — یک اعلان آزمایشی به اشتراک فراخواننده می‌فرستد.
- `push.web.test` — یک اعلان تستی به اشتراک caller می‌فرستد.
<Note>
Web Push مستقل از مسیر رله APNS در iOS است (برای push پشتیبانی‌شده با رله، [پیکربندی](/fa/gateway/configuration) را ببینید) و از روش موجود `push.test` که جفت‌سازی موبایل بومی را هدف می‌گیرد نیز مستقل است.
Web Push مستقل از مسیر relay مربوط به iOS APNS است (برای push مبتنی بر relay، [پیکربندی](/fa/gateway/configuration) را ببینید) و همچنین مستقل از متد موجود `push.test` است، که pairing موبایل بومی را هدف می‌گیرد.
</Note>
## جاسازی‌های میزبانی‌شده
## embedهای میزبانی‌شده
پیام‌های دستیار می‌توانند محتوای وب میزبانی‌شده را به‌صورت درون‌خطی با shortcode `[embed ...]` رندر کنند. سیاست sandbox iframe با `gateway.controlUi.embedSandbox` کنترل می‌شود:
پیام‌های دستیار می‌توانند محتوای وب میزبانی‌شده را به‌صورت درون‌خطی با shortcode `[embed ...]` رندر کنند. سیاست sandbox مربوط به iframe توسط `gateway.controlUi.embedSandbox` کنترل می‌شود:
<Tabs>
<Tab title="strict">
اجرای اسکریپت را داخل جاسازی‌های میزبانی‌شده غیرفعال می‌کند.
اجرای script را داخل embedهای میزبانی‌شده غیرفعال می‌کند.
</Tab>
<Tab title="scripts (پیش‌فرض)">
جاسازی‌های تعاملی را مجاز می‌کند و در عین حال جداسازی مبدا را حفظ می‌کند؛ این پیش‌فرض است و معمولاً برای بازی‌ها/ویجت‌های مرورگری خودبسنده کافی است.
<Tab title="scripts (default)">
embedهای تعاملی را مجاز می‌کند و در عین حال جداسازی origin را حفظ می‌کند؛ این پیش‌فرض است و معمولاً برای بازی‌ها/widgetهای مرورگرِ خودبسنده کافی است.
</Tab>
<Tab title="trusted">
برای سندهای هم‌سایتی که عمداً به امتیازهای قوی‌تر نیاز دارند، `allow-same-origin` را علاوه بر `allow-scripts` اضافه می‌کند.
برای سندهای همان‌سایت که عمداً به privilegeهای قوی‌تر نیاز دارند، `allow-same-origin` را روی `allow-scripts` اضافه می‌کند.
</Tab>
</Tabs>
@ -250,14 +250,14 @@ Web Push مستقل از مسیر رله APNS در iOS است (برای push پ
```
<Warning>
از `trusted` فقط زمانی استفاده کنید که سند جاسازی‌شده واقعاً به رفتار هم‌مبدا نیاز دارد. برای بیشتر بازی‌ها و canvasهای تعاملی تولیدشده توسط عامل، `scripts` گزینه امن‌تری است.
از `trusted` فقط زمانی استفاده کنید که سند embedشده واقعاً به رفتار same-origin نیاز داشته باشد. برای بیشتر بازی‌ها و canvasهای تعاملی تولیدشده توسط عامل، `scripts` گزینهٔ امن‌تری است.
</Warning>
URLهای جاسازی خارجی مطلق `http(s)` به‌طور پیش‌فرض مسدود می‌مانند. اگر عمداً می‌خواهید `[embed url="https://..."]` صفحه‌های شخص ثالث را بارگذاری کند، `gateway.controlUi.allowExternalEmbedUrls: true` را تنظیم کنید.
URLهای embed خارجی مطلق `http(s)` به‌صورت پیش‌فرض مسدود می‌مانند. اگر عمداً می‌خواهید `[embed url="https://..."]` صفحه‌های شخص ثالث را بارگذاری کند، `gateway.controlUi.allowExternalEmbedUrls: true` را تنظیم کنید.
## پهنای پیام چت
## عرض پیام چت
پیام‌های چت گروه‌بندی‌شده از یک حداکثر پهنای پیش‌فرض خوانا استفاده می‌کنند. استقرارهای نمایشگر عریض می‌توانند بدون وصله کردن CSS همراه، آن را با تنظیم `gateway.controlUi.chatMessageMaxWidth` بازنویسی کنند:
پیام‌های چت گروه‌بندی‌شده از یک max-width پیش‌فرض خوانا استفاده می‌کنند. استقرارهای مانیتور عریض می‌توانند بدون وصله‌کردن CSS باندل‌شده، با تنظیم `gateway.controlUi.chatMessageMaxWidth` آن را override کنند:
```json5
{
@ -269,13 +269,13 @@ URLهای جاسازی خارجی مطلق `http(s)` به‌طور پیش‌فر
}
```
مقدار پیش از رسیدن به مرورگر اعتبارسنجی می‌شود. مقدارهای پشتیبانی‌شده شامل طول‌ها و درصدهای ساده مانند `960px` یا `82%`، به‌علاوه عبارت‌های پهنای محدودشده `min(...)`، `max(...)`، `clamp(...)`، `calc(...)`، و `fit-content(...)` است.
مقدار پیش از رسیدن به مرورگر اعتبارسنجی می‌شود. مقدارهای پشتیبانی‌شده شامل طول‌ها و درصدهای ساده مانند `960px` یا `82%`، به‌علاوهٔ عبارت‌های عرض محدودشدهٔ `min(...)`، `max(...)`، `clamp(...)`، `calc(...)`، و `fit-content(...)` هستند.
## دسترسی Tailnet (توصیه‌شده)
## دسترسی tailnet (پیشنهادی)
<Tabs>
<Tab title="Tailscale Serve یکپارچه (ترجیحی)">
Gateway را روی loopback نگه دارید و اجازه دهید Tailscale Serve آن را با HTTPS پروکسی کند:
Gateway را روی local loopback نگه دارید و بگذارید Tailscale Serve آن را با HTTPS proxy کند:
```bash
openclaw gateway --tailscale serve
@ -283,48 +283,48 @@ URLهای جاسازی خارجی مطلق `http(s)` به‌طور پیش‌فر
باز کنید:
- `https://<magicdns>/` (یا `gateway.controlUi.basePath` پیکربندی‌شده شما)
- `https://<magicdns>/` (یا `gateway.controlUi.basePath` پیکربندی‌شدهٔ شما)
به‌طور پیش‌فرض، درخواست‌های Control UI/WebSocket Serve می‌توانند از طریق سرآیندهای هویت Tailscale (`tailscale-user-login`) احراز هویت کنند وقتی `gateway.auth.allowTailscale` برابر `true` باشد. OpenClaw هویت را با resolve کردن نشانی `x-forwarded-for` با `tailscale whois` و تطبیق آن با سرآیند راستی‌آزمایی می‌کند، و فقط وقتی این‌ها را می‌پذیرد که درخواست با سرآیندهای `x-forwarded-*` متعلق به Tailscale به loopback برسد. برای نشست‌های اپراتور Control UI با هویت دستگاه مرورگر، این مسیر Serve راستی‌آزمایی‌شده همچنین رفت‌وبرگشت جفت‌سازی دستگاه را رد می‌کند؛ مرورگرهای بدون دستگاه و اتصال‌های با نقش node همچنان بررسی‌های عادی دستگاه را دنبال می‌کنند. اگر می‌خواهید حتی برای ترافیک Serve هم اعتبارنامه‌های صریح راز مشترک را الزامی کنید، `gateway.auth.allowTailscale: false` را تنظیم کنید. سپس از `gateway.auth.mode: "token"` یا `"password"` استفاده کنید.
به‌صورت پیش‌فرض، درخواست‌های Control UI/WebSocket Serve می‌توانند وقتی `gateway.auth.allowTailscale` برابر `true` است از طریق headerهای هویت Tailscale (`tailscale-user-login`) احراز هویت کنند. OpenClaw هویت را با resolve کردن نشانی `x-forwarded-for` از طریق `tailscale whois` و تطبیق آن با header تأیید می‌کند، و فقط وقتی این‌ها را می‌پذیرد که درخواست با headerهای `x-forwarded-*` مربوط به Tailscale به local loopback برسد. برای نشست‌های operator در Control UI با هویت دستگاه مرورگر، این مسیر Serve تأییدشده همچنین رفت‌وبرگشت device-pairing را رد می‌کند؛ مرورگرهای بدون دستگاه و اتصال‌های با نقش node همچنان بررسی‌های معمول دستگاه را دنبال می‌کنند. اگر می‌خواهید حتی برای ترافیک Serve هم credentialهای shared-secret صریح لازم باشد، `gateway.auth.allowTailscale: false` را تنظیم کنید. سپس از `gateway.auth.mode: "token"` یا `"password"` استفاده کنید.
برای آن مسیر ناهمگام هویت Serve، تلاش‌های احراز هویت ناموفق برای همان IP کلاینت و دامنه احراز هویت، پیش از نوشتن‌های محدودسازی نرخ به‌صورت ترتیبی انجام می‌شوند. بنابراین تلاش‌های بد هم‌زمان از همان مرورگر می‌توانند روی درخواست دوم به‌جای دو عدم‌تطابق ساده که موازی رقابت کنند، `retry later` را نشان دهند.
برای آن مسیر async هویت Serve، تلاش‌های auth ناموفق برای همان IP کلاینت و scope احراز هویت پیش از نوشتن rate-limit سریال می‌شوند. بنابراین retryهای بد همزمان از همان مرورگر می‌توانند روی درخواست دوم به‌جای دو mismatch ساده که موازی رقابت می‌کنند، `retry later` را نشان دهند.
<Warning>
احراز هویت Serve بدون توکن فرض می‌کند میزبان gateway مورد اعتماد است. اگر کد محلی غیرقابل‌اعتماد ممکن است روی آن میزبان اجرا شود، احراز هویت token/password را الزامی کنید.
احراز هویت Serve بدون token فرض می‌کند میزبان gateway مورد اعتماد است. اگر کد محلی نامطمئن ممکن است روی آن میزبان اجرا شود، auth مبتنی بر token/password را الزامی کنید.
</Warning>
</Tab>
<Tab title="اتصال به tailnet + توکن">
<Tab title="Bind به tailnet + token">
```bash
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
```
سپس باز کنید:
- `http://<tailscale-ip>:18789/` (یا `gateway.controlUi.basePath` پیکربندی‌شده شما)
- `http://<tailscale-ip>:18789/` (یا `gateway.controlUi.basePath` پیکربندی‌شدهٔ شما)
راز مشترک متناظر را در تنظیمات UI جای‌گذاری کنید (به‌صورت `connect.params.auth.token` یا `connect.params.auth.password` ارسال می‌شود).
shared secret مطابق را در تنظیمات UI بچسبانید (به‌صورت `connect.params.auth.token` یا `connect.params.auth.password` ارسال می‌شود).
</Tab>
</Tabs>
## HTTP ناامن
اگر داشبورد را از طریق HTTP ساده (`http://<lan-ip>` یا `http://<tailscale-ip>`) باز کنید، مرورگر در یک **زمینه ناامن** اجرا می‌شود و WebCrypto را مسدود می‌کند. به‌طور پیش‌فرض، OpenClaw اتصال‌های Control UI بدون هویت دستگاه را **مسدود** می‌کند.
اگر داشبورد را از طریق HTTP ساده باز کنید (`http://<lan-ip>` یا `http://<tailscale-ip>`)، مرورگر در یک **context غیرامن** اجرا می‌شود و WebCrypto را مسدود می‌کند. به‌صورت پیش‌فرض، OpenClaw اتصال‌های Control UI بدون هویت دستگاه را **مسدود** می‌کند.
استثناهای مستندشده:
- سازگاری HTTP ناامن فقط برای localhost با `gateway.controlUi.allowInsecureAuth=true`
- احراز هویت موفق اپراتور Control UI از طریق `gateway.auth.mode: "trusted-proxy"`
- حالت اضطراری `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
- auth موفق operator در Control UI از طریق `gateway.auth.mode: "trusted-proxy"`
- break-glass `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**راهکار پیشنهادی:** از HTTPS (Tailscale Serve) استفاده کنید یا رابط کاربری را به‌صورت محلی باز کنید:
**راه‌حل پیشنهادی:** از HTTPS (Tailscale Serve) استفاده کنید یا رابط کاربری را به‌صورت محلی باز کنید:
- `https://<magicdns>/` (Serve)
- `http://127.0.0.1:18789/` (روی میزبان Gateway)
- `http://127.0.0.1:18789/` (روی میزبان gateway)
<AccordionGroup>
<Accordion title="Insecure-auth toggle behavior">
<Accordion title="رفتار کلید تغییر احراز هویت ناامن">
```json5
{
gateway: {
@ -335,14 +335,14 @@ URLهای جاسازی خارجی مطلق `http(s)` به‌طور پیش‌فر
}
```
`allowInsecureAuth` فقط یک گزینهٔ سازگاری محلی است:
`allowInsecureAuth` فقط یک کلید سازگاری محلی است:
- به نشست‌های localhost رابط کاربری کنترل اجازه می‌دهد در زمینه‌های HTTP غیرامن، بدون هویت دستگاه ادامه پیدا کنند.
- بررسی‌های جفت‌سازی را دور نمی‌زند.
- الزامات هویت دستگاه راه دور (غیر از localhost) را کاهش نمی‌دهد.
- الزامات هویت دستگاه از راه دور (غیر از localhost) را آسان‌تر نمی‌کند.
</Accordion>
<Accordion title="Break-glass only">
<Accordion title="فقط برای وضعیت اضطراری">
```json5
{
gateway: {
@ -354,42 +354,52 @@ URLهای جاسازی خارجی مطلق `http(s)` به‌طور پیش‌فر
```
<Warning>
`dangerouslyDisableDeviceAuth` بررسی‌های هویت دستگاه در رابط کاربری کنترل را غیرفعال می‌کند و یک کاهش شدید امنیتی است. پس از استفادهٔ اضطراری، سریعاً آن را برگردانید.
`dangerouslyDisableDeviceAuth` بررسی‌های هویت دستگاه رابط کاربری کنترل را غیرفعال می‌کند و یک کاهش امنیتی شدید است. پس از استفاده اضطراری، سریع آن را برگردانید.
</Warning>
</Accordion>
<Accordion title="Trusted-proxy note">
- احراز هویت موفق trusted-proxy می‌تواند نشست‌های رابط کاربری کنترل **اپراتور** را بدون هویت دستگاه بپذیرد.
- این مورد به نشست‌های رابط کاربری کنترل با نقش node گسترش پیدا نمی‌کند.
- reverse proxyهای loopback روی همان میزبان همچنان احراز هویت trusted-proxy را برآورده نمی‌کنند؛ [احراز هویت پراکسی معتمد](/fa/gateway/trusted-proxy-auth) را ببینید.
<Accordion title="نکته پروکسی مورد اعتماد">
- احراز هویت موفق پروکسی مورد اعتماد می‌تواند نشست‌های رابط کاربری کنترل **اپراتور** را بدون هویت دستگاه بپذیرد.
- این موضوع به نشست‌های رابط کاربری کنترل با نقش node گسترش پیدا نمی‌کند.
- پروکسی‌های معکوس loopback روی همان میزبان همچنان احراز هویت پروکسی مورد اعتماد را برآورده نمی‌کنند؛ [احراز هویت پروکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) را ببینید.
</Accordion>
</AccordionGroup>
برای راهنمایی تنظیم HTTPS، [Tailscale](/fa/gateway/tailscale) را ببینید.
برای راهنمایی راه‌اندازی HTTPS، [Tailscale](/fa/gateway/tailscale) را ببینید.
## سیاست امنیت محتوا
رابط کاربری کنترل با یک سیاست سخت‌گیرانهٔ `img-src` عرضه می‌شود: فقط دارایی‌های **هم‌مبدأ**، URLهای `data:` و URLهای `blob:` تولیدشده به‌صورت محلی مجاز هستند. URLهای تصویر راه دور `http(s)` و URLهای نسبیِ پروتکل توسط مرورگر رد می‌شوند و هیچ واکشی شبکه‌ای صادر نمی‌کنند.
رابط کاربری کنترل با سیاست سخت‌گیرانه `img-src` ارائه می‌شود: فقط دارایی‌های **هم‌مبدا**، URLهای `data:` و URLهای `blob:` تولیدشده به‌صورت محلی مجاز هستند. URLهای تصویر از راه دور `http(s)` و نسبی به پروتکل توسط مرورگر رد می‌شوند و درخواست شبکه‌ای ارسال نمی‌کنند.
معنای عملی این موضوع:
معنای عملی این رفتار:
- آواتارها و تصویرهایی که تحت مسیرهای نسبی ارائه می‌شوند (برای مثال `/avatars/<id>`) همچنان رندر می‌شوند، از جمله مسیرهای آواتار احراز هویت‌شده که رابط کاربری آن‌ها را واکشی و به URLهای محلی `blob:` تبدیل می‌کند.
- URLهای درون‌خطی `data:image/...` همچنان رندر می‌شوند (برای payloadهای داخل پروتکل مفید است).
- URLهای محلی `blob:` که توسط رابط کاربری کنترل ساخته می‌شوند همچنان رندر می‌شوند.
- URLهای آواتار راه دور که توسط فرادادهٔ کانال منتشر می‌شوند، در helperهای آواتار رابط کاربری کنترل حذف و با لوگو/نشان داخلی جایگزین می‌شوند؛ بنابراین یک کانال compromiseشده یا مخرب نمی‌تواند مرورگر اپراتور را مجبور به واکشی دلخواه تصویر راه دور کند.
- آواتارها و تصویرهایی که زیر مسیرهای نسبی ارائه می‌شوند (برای مثال `/avatars/<id>`) همچنان نمایش داده می‌شوند، از جمله مسیرهای آواتار احرازشده که رابط کاربری آن‌ها را دریافت می‌کند و به URLهای محلی `blob:` تبدیل می‌کند.
- URLهای درون‌خطی `data:image/...` همچنان نمایش داده می‌شوند (برای payloadهای درون پروتکل مفید است).
- URLهای محلی `blob:` که توسط رابط کاربری کنترل ساخته شده‌اند همچنان نمایش داده می‌شوند.
- URLهای آواتار از راه دور که توسط فراداده کانال صادر می‌شوند در helperهای آواتار رابط کاربری کنترل حذف و با لوگو/نشان داخلی جایگزین می‌شوند، بنابراین یک کانال به‌خطر‌افتاده یا مخرب نمی‌تواند مرورگر اپراتور را مجبور به دریافت تصویر دلخواه از راه دور کند.
برای دریافت این رفتار لازم نیست چیزی را تغییر دهید — همیشه فعال است و قابل پیکربندی نیست.
## احراز هویت مسیر آواتار
وقتی احراز هویت Gateway پیکربندی شده باشد، endpoint آواتار رابط کاربری کنترل همان token Gateway را مثل بقیهٔ API لازم دارد:
وقتی احراز هویت Gateway پیکربندی شده باشد، endpoint آواتار رابط کاربری کنترل به همان توکن Gateway نیاز دارد که بقیه API استفاده می‌کند:
- `GET /avatar/<agentId>` تصویر آواتار را فقط به فراخوان‌های احراز هویت‌شده برمی‌گرداند. `GET /avatar/<agentId>?meta=1` فرادادهٔ آواتار را تحت همان قاعده برمی‌گرداند.
- درخواست‌های احراز هویت‌نشده به هرکدام از مسیرها رد می‌شوند (همسو با مسیر هم‌ردهٔ assistant-media). این کار از نشت هویت agent از مسیر آواتار روی میزبان‌هایی که در غیر این صورت محافظت شده‌اند جلوگیری می‌کند.
- خود رابط کاربری کنترل هنگام واکشی آواتارها token Gateway را به‌صورت header bearer ارسال می‌کند و از URLهای blob احراز هویت‌شده استفاده می‌کند تا تصویر همچنان در داشبوردها رندر شود.
- `GET /avatar/<agentId>` تصویر آواتار را فقط به فراخواننده‌های احرازشده برمی‌گرداند. `GET /avatar/<agentId>?meta=1` فراداده آواتار را با همان قاعده برمی‌گرداند.
- درخواست‌های احرازنشده به هرکدام از مسیرها رد می‌شوند (مطابق مسیر هم‌سطح assistant-media). این کار مانع می‌شود مسیر آواتار، هویت agent را روی میزبان‌هایی که در غیر این صورت محافظت شده‌اند، افشا کند.
- خود رابط کاربری کنترل هنگام دریافت آواتارها، توکن Gateway را به‌عنوان هدر bearer ارسال می‌کند و از URLهای blob احرازشده استفاده می‌کند تا تصویر همچنان در داشبوردها نمایش داده شود.
اگر احراز هویت Gateway را غیرفعال کنید (روی میزبان‌های اشتراکی توصیه نمی‌شود)، مسیر آواتار نیز همانند بقیهٔ Gateway بدون احراز هویت می‌شود.
اگر احراز هویت Gateway را غیرفعال کنید (روی میزبان‌های مشترک توصیه نمی‌شود)، مسیر آواتار نیز مطابق بقیه Gateway بدون احراز هویت می‌شود.
## احراز هویت مسیر رسانه assistant
وقتی احراز هویت Gateway پیکربندی شده باشد، پیش‌نمایش‌های رسانه محلی assistant از یک مسیر دومرحله‌ای استفاده می‌کنند:
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` به احراز هویت عادی اپراتور رابط کاربری کنترل نیاز دارد. مرورگر هنگام بررسی دسترس‌پذیری، توکن Gateway را به‌عنوان هدر bearer ارسال می‌کند.
- پاسخ‌های فراداده موفق شامل یک `mediaTicket` کوتاه‌عمر هستند که فقط به همان مسیر منبع دقیق محدود شده است.
- URLهای تصویر، صدا، ویدئو و سند که در مرورگر نمایش داده می‌شوند، به‌جای توکن یا گذرواژه فعال Gateway از `mediaTicket=<ticket>` استفاده می‌کنند. ticket به‌سرعت منقضی می‌شود و نمی‌تواند منبع دیگری را مجاز کند.
این کار نمایش عادی رسانه را با عناصر رسانه بومی مرورگر سازگار نگه می‌دارد، بدون اینکه اعتبارنامه‌های قابل‌استفاده مجدد Gateway را در URLهای قابل‌مشاهده رسانه قرار دهد.
## ساخت رابط کاربری
@ -399,36 +409,36 @@ Gateway فایل‌های ایستا را از `dist/control-ui` ارائه می
pnpm ui:build
```
base مطلق اختیاری (وقتی URLهای ثابت دارایی می‌خواهید):
مبنای مطلق اختیاری (وقتی URLهای ثابت دارایی می‌خواهید):
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
```
برای توسعهٔ محلی (dev server جداگانه):
برای توسعه محلی (سرور توسعه جداگانه):
```bash
pnpm ui:dev
```
سپس رابط کاربری را به URL مربوط به Gateway WS خودتان اشاره دهید (مثلاً `ws://127.0.0.1:18789`).
سپس رابط کاربری را به URL WS مربوط به Gateway خود اشاره دهید (مثلاً `ws://127.0.0.1:18789`).
## اشکال‌زدایی/آزمایش: dev server + Gateway راه دور
## اشکال‌زدایی/آزمایش: سرور توسعه + Gateway راه دور
رابط کاربری کنترل فایل‌های ایستا است؛ هدف WebSocket قابل پیکربندی است و می‌تواند با مبدأ HTTP متفاوت باشد. این زمانی مفید است که dev server مربوط به Vite را به‌صورت محلی می‌خواهید اما Gateway جای دیگری اجرا می‌شود.
رابط کاربری کنترل فایل‌های ایستا است؛ هدف WebSocket قابل پیکربندی است و می‌تواند با مبدا HTTP متفاوت باشد. این برای زمانی مفید است که سرور توسعه Vite را به‌صورت محلی می‌خواهید اما Gateway جای دیگری اجرا می‌شود.
<Steps>
<Step title="Start the UI dev server">
<Step title="سرور توسعه رابط کاربری را شروع کنید">
```bash
pnpm ui:dev
```
</Step>
<Step title="Open with gatewayUrl">
<Step title="با gatewayUrl باز کنید">
```text
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
```
احراز هویت یک‌بارهٔ اختیاری (در صورت نیاز):
احراز هویت یک‌باره اختیاری (در صورت نیاز):
```text
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
@ -438,18 +448,18 @@ pnpm ui:dev
</Steps>
<AccordionGroup>
<Accordion title="Notes">
<Accordion title="نکته‌ها">
- `gatewayUrl` پس از بارگذاری در localStorage ذخیره و از URL حذف می‌شود.
- اگر یک endpoint کامل `ws://` یا `wss://` را از طریق `gatewayUrl` ارسال می‌کنید، مقدار `gatewayUrl` را URL-encode کنید تا مرورگر query string را درست parse کند.
- هر زمان ممکن است، `token` باید از طریق fragment URL (`#token=...`) ارسال شود. fragmentها به سرور ارسال نمی‌شوند و این کار از نشت در request-log و Referer جلوگیری می‌کند. پارامترهای query قدیمی `?token=` همچنان برای سازگاری یک‌بار import می‌شوند، اما فقط به‌عنوان fallback، و بلافاصله پس از bootstrap حذف می‌شوند.
- اگر یک endpoint کامل `ws://` یا `wss://` را از طریق `gatewayUrl` ارسال می‌کنید، مقدار `gatewayUrl` را URL-encode کنید تا مرورگر رشته query را درست تجزیه کند.
- هر زمان ممکن است، `token` باید از طریق fragment URL (`#token=...`) ارسال شود. fragmentها به سرور فرستاده نمی‌شوند و این از نشت در لاگ درخواست و Referer جلوگیری می‌کند. پارامترهای query قدیمی `?token=` همچنان برای سازگاری یک‌بار وارد می‌شوند، اما فقط به‌عنوان fallback، و بلافاصله پس از bootstrap حذف می‌شوند.
- `password` فقط در حافظه نگه داشته می‌شود.
- وقتی `gatewayUrl` تنظیم شده باشد، رابط کاربری به credentialهای config یا environment fallback نمی‌کند. `token` (یا `password`) را صریحاً ارائه کنید. نبود credentialهای صریح یک خطا است.
- وقتی Gateway پشت TLS است (Tailscale Serve، پراکسی HTTPS، و غیره)، از `wss://` استفاده کنید.
- `gatewayUrl` فقط در یک پنجرهٔ سطح بالا پذیرفته می‌شود (نه embedded) تا از clickjacking جلوگیری شود.
- استقرارهای غیر loopback رابط کاربری کنترل باید `gateway.controlUi.allowedOrigins` را صریحاً تنظیم کنند (originهای کامل). این شامل setupهای dev راه دور هم می‌شود.
- راه‌اندازی Gateway ممکن است originهای محلی مانند `http://localhost:<port>` و `http://127.0.0.1:<port>` را از bind و port مؤثر زمان اجرا seed کند، اما originهای مرورگر راه دور همچنان به entryهای صریح نیاز دارند.
- از `gateway.controlUi.allowedOrigins: ["*"]` استفاده نکنید مگر برای آزمایش محلی کاملاً کنترل‌شده. این یعنی اجازه دادن به هر origin مرورگر، نه «مطابقت با هر میزبانی که استفاده می‌کنم.»
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` حالت fallback مبدأ بر اساس Host-header را فعال می‌کند، اما این یک حالت امنیتی خطرناک است.
- وقتی `gatewayUrl` تنظیم شده باشد، رابط کاربری به اعتبارنامه‌های پیکربندی یا محیط fallback نمی‌کند. `token` (یا `password`) را صریح ارائه کنید. نبود اعتبارنامه صریح یک خطا است.
- وقتی Gateway پشت TLS است (Tailscale Serve، پروکسی HTTPS و غیره)، از `wss://` استفاده کنید.
- `gatewayUrl` فقط در یک پنجره سطح بالا پذیرفته می‌شود (نه به‌صورت embedded) تا از clickjacking جلوگیری شود.
- استقرارهای رابط کاربری کنترل غیر loopback باید `gateway.controlUi.allowedOrigins` را به‌صورت صریح تنظیم کنند (originهای کامل). این شامل راه‌اندازی‌های توسعه از راه دور هم می‌شود.
- راه‌اندازی Gateway ممکن است originهای محلی مانند `http://localhost:<port>` و `http://127.0.0.1:<port>` را از bind و پورت موثر runtime seed کند، اما originهای مرورگر راه دور همچنان به ورودی‌های صریح نیاز دارند.
- جز برای آزمایش محلی کاملاً کنترل‌شده، از `gateway.controlUi.allowedOrigins: ["*"]` استفاده نکنید. این یعنی اجازه دادن به هر origin مرورگر، نه «مطابقت با هر میزبانی که استفاده می‌کنم».
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` حالت fallback مبدا بر اساس هدر Host را فعال می‌کند، اما این یک حالت امنیتی خطرناک است.
</Accordion>
</AccordionGroup>
@ -466,11 +476,11 @@ pnpm ui:dev
}
```
جزئیات setup دسترسی راه دور: [دسترسی راه دور](/fa/gateway/remote).
جزئیات راه‌اندازی دسترسی از راه دور: [دسترسی از راه دور](/fa/gateway/remote).
## مرتبط
- [داشبورد](/fa/web/dashboard) — داشبورد Gateway
- [بررسی‌های سلامت](/fa/gateway/health) — پایش سلامت Gateway
- [TUI](/fa/web/tui) — رابط کاربری ترمینال
- [داشبورد](/fa/web/dashboard) — داشبورد gateway
- [بررسی‌های سلامت](/fa/gateway/health) — پایش سلامت gateway
- [TUI](/fa/web/tui) — رابط کاربری terminal
- [WebChat](/fa/web/webchat) — رابط چت مبتنی بر مرورگر