chore(i18n): refresh fa translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
2d2cb8ef74
commit
5b98570536
@ -1,19 +1,19 @@
|
||||
---
|
||||
read_when:
|
||||
- راهاندازی Zalo Personal برای OpenClaw
|
||||
- اشکالزدایی جریان ورود یا پیامرسانی Zalo Personal
|
||||
- اشکالزدایی ورود به Zalo Personal یا جریان پیام
|
||||
summary: پشتیبانی از حساب شخصی Zalo از طریق zca-js بومی (ورود با QR)، قابلیتها و پیکربندی
|
||||
title: Zalo شخصی
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:17:43Z"
|
||||
generated_at: "2026-05-04T18:23:31Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 0096775e0017e504130f2e19e05ab8114eadb873a9e11f79ea8f0dd91297567f
|
||||
source_hash: 0f6d27f0ca502e6426abe21d609efd0a168a0b6b0fafe8d52d59f1a717da1ed5
|
||||
source_path: channels/zalouser.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
وضعیت: آزمایشی. این یکپارچهسازی یک **حساب شخصی Zalo** را از طریق `zca-js` بومی داخل OpenClaw خودکار میکند.
|
||||
وضعیت: آزمایشی. این یکپارچهسازی یک **حساب شخصی Zalo** را از طریق `zca-js` بومی درون OpenClaw خودکار میکند.
|
||||
|
||||
<Warning>
|
||||
این یکپارچهسازی غیررسمی است و ممکن است به تعلیق یا مسدود شدن حساب منجر شود. با مسئولیت خودتان استفاده کنید.
|
||||
@ -21,11 +21,9 @@ x-i18n:
|
||||
|
||||
## Plugin همراه
|
||||
|
||||
Zalo Personal در نسخههای فعلی OpenClaw بهصورت Plugin همراه ارائه میشود، بنابراین بیلدهای
|
||||
بستهبندیشده معمولی به نصب جداگانه نیاز ندارند.
|
||||
Zalo Personal بهعنوان یک Plugin همراه در انتشارهای فعلی OpenClaw ارائه میشود، بنابراین بیلدهای بستهبندیشده معمولی به نصب جداگانه نیاز ندارند.
|
||||
|
||||
اگر از یک بیلد قدیمیتر یا نصب سفارشی استفاده میکنید که Zalo Personal را شامل نمیشود،
|
||||
بسته npm را مستقیما نصب کنید:
|
||||
اگر از یک بیلد قدیمیتر یا نصب سفارشیای استفاده میکنید که Zalo Personal را شامل نمیشود، بسته npm را مستقیماً نصب کنید:
|
||||
|
||||
- نصب از طریق CLI: `openclaw plugins install @openclaw/zalouser`
|
||||
- نسخه پینشده: `openclaw plugins install @openclaw/zalouser@2026.5.2`
|
||||
@ -36,10 +34,10 @@ Zalo Personal در نسخههای فعلی OpenClaw بهصورت Plugin ه
|
||||
|
||||
## راهاندازی سریع (مبتدی)
|
||||
|
||||
1. مطمئن شوید Plugin Zalo Personal در دسترس است.
|
||||
- نسخههای بستهبندیشده فعلی OpenClaw از قبل آن را همراه دارند.
|
||||
- نصبهای قدیمیتر/سفارشی میتوانند آن را با فرمانهای بالا بهصورت دستی اضافه کنند.
|
||||
2. وارد شوید (QR، روی دستگاه Gateway):
|
||||
1. مطمئن شوید Plugin مربوط به Zalo Personal در دسترس است.
|
||||
- انتشارهای بستهبندیشده فعلی OpenClaw از قبل آن را همراه خود دارند.
|
||||
- نصبهای قدیمیتر/سفارشی میتوانند آن را با دستورهای بالا بهصورت دستی اضافه کنند.
|
||||
2. ورود (QR، روی ماشین Gateway):
|
||||
- `openclaw channels login --channel zalouser`
|
||||
- کد QR را با برنامه موبایل Zalo اسکن کنید.
|
||||
3. کانال را فعال کنید:
|
||||
@ -55,23 +53,23 @@ Zalo Personal در نسخههای فعلی OpenClaw بهصورت Plugin ه
|
||||
}
|
||||
```
|
||||
|
||||
4. Gateway را راهاندازی مجدد کنید (یا راهاندازی را تمام کنید).
|
||||
5. دسترسی DM بهطور پیشفرض از pairing استفاده میکند؛ در اولین تماس کد pairing را تأیید کنید.
|
||||
4. Gateway را راهاندازی مجدد کنید (یا راهاندازی را کامل کنید).
|
||||
5. دسترسی DM بهطور پیشفرض روی pairing است؛ در اولین تماس، کد pairing را تأیید کنید.
|
||||
|
||||
## چیست
|
||||
## چیستی آن
|
||||
|
||||
- کاملا درونفرآیندی از طریق `zca-js` اجرا میشود.
|
||||
- کاملاً درون فرایند و از طریق `zca-js` اجرا میشود.
|
||||
- از شنوندههای رویداد بومی برای دریافت پیامهای ورودی استفاده میکند.
|
||||
- پاسخها را مستقیما از طریق API جاوااسکریپت ارسال میکند (متن/رسانه/پیوند).
|
||||
- برای موارد استفاده «حساب شخصی» طراحی شده است، جایی که Zalo Bot API در دسترس نیست.
|
||||
- پاسخها را مستقیماً از طریق API جاوااسکریپت ارسال میکند (متن/رسانه/پیوند).
|
||||
- برای موارد استفاده «حساب شخصی» طراحی شده است که در آنها Zalo Bot API در دسترس نیست.
|
||||
|
||||
## نامگذاری
|
||||
|
||||
شناسه کانال `zalouser` است تا صراحتا مشخص کند که این مورد یک **حساب کاربر شخصی Zalo** را خودکار میکند (غیررسمی). ما `zalo` را برای یکپارچهسازی رسمی احتمالی آینده با Zalo API رزرو نگه میداریم.
|
||||
شناسه کانال `zalouser` است تا صریح باشد که این مورد یک **حساب کاربر شخصی Zalo** را خودکار میکند (غیررسمی). ما `zalo` را برای یک یکپارچهسازی احتمالی رسمی Zalo API در آینده رزرو نگه میداریم.
|
||||
|
||||
## یافتن شناسهها (دایرکتوری)
|
||||
|
||||
برای پیدا کردن همتاها/گروهها و شناسههایشان از CLI دایرکتوری استفاده کنید:
|
||||
از CLI دایرکتوری برای کشف همتاها/گروهها و شناسههای آنها استفاده کنید:
|
||||
|
||||
```bash
|
||||
openclaw directory self --channel zalouser
|
||||
@ -81,34 +79,36 @@ openclaw directory groups list --channel zalouser --query "work"
|
||||
|
||||
## محدودیتها
|
||||
|
||||
- متن خروجی به قطعههایی با حدود ۲۰۰۰ نویسه تقسیم میشود (محدودیتهای کلاینت Zalo).
|
||||
- متن خروجی به قطعههای حدوداً ۲۰۰۰ نویسهای تقسیم میشود (محدودیتهای کلاینت Zalo).
|
||||
- Streaming بهطور پیشفرض مسدود است.
|
||||
|
||||
## کنترل دسترسی (DMها)
|
||||
|
||||
`channels.zalouser.dmPolicy` از این موارد پشتیبانی میکند: `pairing | allowlist | open | disabled` (پیشفرض: `pairing`).
|
||||
|
||||
`channels.zalouser.allowFrom` شناسههای کاربر یا نامها را میپذیرد. هنگام راهاندازی، نامها با استفاده از جستوجوی مخاطب درونفرآیندی Plugin به شناسه تبدیل میشوند.
|
||||
`channels.zalouser.allowFrom` باید از شناسههای پایدار کاربران Zalo استفاده کند. هنگام راهاندازی تعاملی، نامهای واردشده میتوانند با استفاده از جستوجوی مخاطب درونفرایندی Plugin به شناسه تبدیل شوند.
|
||||
|
||||
اگر یک نام خام در پیکربندی باقی بماند، هنگام راهاندازی فقط وقتی resolve میشود که `channels.zalouser.dangerouslyAllowNameMatching: true` فعال باشد. بدون این opt-in، بررسیهای فرستنده در زمان اجرا فقط مبتنی بر شناسه هستند و نامهای خام برای مجوزدهی نادیده گرفته میشوند.
|
||||
|
||||
تأیید از طریق:
|
||||
|
||||
- `openclaw pairing list zalouser`
|
||||
- `openclaw pairing approve zalouser <code>`
|
||||
|
||||
## دسترسی گروه (اختیاری)
|
||||
## دسترسی گروهی (اختیاری)
|
||||
|
||||
- پیشفرض: `channels.zalouser.groupPolicy = "open"` (گروهها مجاز هستند). برای بازنویسی مقدار پیشفرض هنگام تنظیمنبودن، از `channels.defaults.groupPolicy` استفاده کنید.
|
||||
- محدود کردن به allowlist با:
|
||||
- پیشفرض: `channels.zalouser.groupPolicy = "open"` (گروهها مجاز هستند). برای بازنویسی مقدار پیشفرض در حالت تنظیمنشده، از `channels.defaults.groupPolicy` استفاده کنید.
|
||||
- محدود کردن به یک allowlist با:
|
||||
- `channels.zalouser.groupPolicy = "allowlist"`
|
||||
- `channels.zalouser.groups` (کلیدها باید شناسههای پایدار گروه باشند؛ نامها در صورت امکان هنگام راهاندازی به شناسه تبدیل میشوند)
|
||||
- `channels.zalouser.groupAllowFrom` (کنترل میکند کدام فرستندهها در گروههای مجاز میتوانند bot را فعال کنند)
|
||||
- `channels.zalouser.groups` (کلیدها باید شناسههای پایدار گروه باشند؛ نامها فقط هنگام راهاندازی و فقط وقتی `channels.zalouser.dangerouslyAllowNameMatching: true` فعال باشد به شناسه تبدیل میشوند)
|
||||
- `channels.zalouser.groupAllowFrom` (کنترل میکند کدام فرستندهها در گروههای مجاز میتوانند بات را فعال کنند)
|
||||
- مسدود کردن همه گروهها: `channels.zalouser.groupPolicy = "disabled"`.
|
||||
- راهنمای پیکربندی میتواند برای allowlistهای گروه سؤال کند.
|
||||
- هنگام راهاندازی، OpenClaw نامهای گروه/کاربر در allowlistها را به شناسه تبدیل میکند و نگاشت را در لاگ ثبت میکند.
|
||||
- تطبیق allowlist گروه بهطور پیشفرض فقط بر اساس شناسه است. نامهای حلنشده برای احراز مجوز نادیده گرفته میشوند، مگر اینکه `channels.zalouser.dangerouslyAllowNameMatching: true` فعال باشد.
|
||||
- `channels.zalouser.dangerouslyAllowNameMatching: true` یک حالت سازگاری اضطراری است که تطبیق تغییرپذیر نام گروه را دوباره فعال میکند.
|
||||
- اگر `groupAllowFrom` تنظیم نشده باشد، زمان اجرا برای بررسیهای فرستنده گروه به `allowFrom` برمیگردد.
|
||||
- بررسیهای فرستنده هم روی پیامهای عادی گروه و هم روی فرمانهای کنترل اعمال میشوند (برای مثال `/new`، `/reset`).
|
||||
- ویزارد پیکربندی میتواند برای allowlistهای گروهی درخواست ورودی کند.
|
||||
- هنگام راهاندازی، OpenClaw نامهای گروه/کاربر در allowlistها را به شناسهها تبدیل میکند و نگاشت را فقط وقتی `channels.zalouser.dangerouslyAllowNameMatching: true` فعال باشد در لاگ ثبت میکند.
|
||||
- تطبیق allowlist گروه بهطور پیشفرض فقط مبتنی بر شناسه است. نامهای resolveنشده برای احراز مجوز نادیده گرفته میشوند مگر اینکه `channels.zalouser.dangerouslyAllowNameMatching: true` فعال باشد.
|
||||
- `channels.zalouser.dangerouslyAllowNameMatching: true` یک حالت سازگاری اضطراری است که resolve نامهای متغیر هنگام راهاندازی و تطبیق نام گروه در زمان اجرا را دوباره فعال میکند.
|
||||
- اگر `groupAllowFrom` تنظیم نشده باشد، زمان اجرا برای بررسی فرستندههای گروهی به `allowFrom` برمیگردد.
|
||||
- بررسیهای فرستنده هم برای پیامهای عادی گروهی و هم برای فرمانهای کنترلی اعمال میشوند (برای مثال `/new`، `/reset`).
|
||||
|
||||
مثال:
|
||||
|
||||
@ -127,15 +127,15 @@ openclaw directory groups list --channel zalouser --query "work"
|
||||
}
|
||||
```
|
||||
|
||||
### دروازهگذاری mention در گروه
|
||||
### گیتگذاری اشاره در گروه
|
||||
|
||||
- `channels.zalouser.groups.<group>.requireMention` کنترل میکند که آیا پاسخهای گروه به mention نیاز دارند یا نه.
|
||||
- ترتیب حل: شناسه/نام دقیق گروه -> slug نرمالشده گروه -> `*` -> پیشفرض (`true`).
|
||||
- این هم برای گروههای allowlistشده و هم حالت گروه باز اعمال میشود.
|
||||
- نقلقول کردن پیام bot بهعنوان mention ضمنی برای فعالسازی گروه محسوب میشود.
|
||||
- فرمانهای کنترل مجاز (برای مثال `/new`) میتوانند از دروازهگذاری mention عبور کنند.
|
||||
- وقتی پیام گروه به دلیل نیاز به mention نادیده گرفته میشود، OpenClaw آن را بهعنوان تاریخچه گروه در انتظار ذخیره میکند و در پیام گروه پردازششده بعدی آن را لحاظ میکند.
|
||||
- حد تاریخچه گروه بهطور پیشفرض `messages.groupChat.historyLimit` است (fallback `50`). میتوانید برای هر حساب با `channels.zalouser.historyLimit` آن را بازنویسی کنید.
|
||||
- `channels.zalouser.groups.<group>.requireMention` کنترل میکند که آیا پاسخهای گروهی به اشاره نیاز دارند یا نه.
|
||||
- ترتیب resolve: شناسه/نام دقیق گروه -> slug نرمالشده گروه -> `*` -> پیشفرض (`true`).
|
||||
- این هم برای گروههای allowlistشده و هم برای حالت گروه باز اعمال میشود.
|
||||
- نقلقول کردن پیام بات بهعنوان یک اشاره ضمنی برای فعالسازی گروه حساب میشود.
|
||||
- فرمانهای کنترلی مجاز (برای مثال `/new`) میتوانند گیتگذاری اشاره را دور بزنند.
|
||||
- وقتی یک پیام گروهی به این دلیل رد میشود که اشاره لازم است، OpenClaw آن را بهعنوان تاریخچه گروهی معلق ذخیره میکند و در پیام گروهی پردازششده بعدی آن را لحاظ میکند.
|
||||
- حد تاریخچه گروه بهطور پیشفرض `messages.groupChat.historyLimit` است (fallback `50`). میتوانید آن را برای هر حساب با `channels.zalouser.historyLimit` بازنویسی کنید.
|
||||
|
||||
مثال:
|
||||
|
||||
@ -155,7 +155,7 @@ openclaw directory groups list --channel zalouser --query "work"
|
||||
|
||||
## چندحسابی
|
||||
|
||||
حسابها به پروفایلهای `zalouser` در وضعیت OpenClaw نگاشت میشوند. مثال:
|
||||
حسابها در state مربوط به OpenClaw به پروفایلهای `zalouser` نگاشت میشوند. مثال:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -171,34 +171,34 @@ openclaw directory groups list --channel zalouser --query "work"
|
||||
}
|
||||
```
|
||||
|
||||
## تایپ کردن، واکنشها و تأییدیههای تحویل
|
||||
## تایپ کردن، واکنشها، و تأییدهای تحویل
|
||||
|
||||
- OpenClaw پیش از ارسال پاسخ، یک رویداد typing میفرستد (در حد تلاش).
|
||||
- کنش واکنش پیام `react` برای `zalouser` در کنشهای کانال پشتیبانی میشود.
|
||||
- OpenClaw پیش از ارسال پاسخ، یک رویداد typing میفرستد (best-effort).
|
||||
- عمل واکنش پیام `react` برای `zalouser` در اقدامهای کانال پشتیبانی میشود.
|
||||
- برای حذف یک ایموجی واکنش مشخص از پیام، از `remove: true` استفاده کنید.
|
||||
- معناشناسی واکنش: [واکنشها](/fa/tools/reactions)
|
||||
- برای پیامهای ورودیای که شامل فراداده رویداد هستند، OpenClaw تأییدیههای delivered + seen را ارسال میکند (در حد تلاش).
|
||||
- معناشناسی واکنشها: [Reactions](/fa/tools/reactions)
|
||||
- برای پیامهای ورودی که شامل فراداده رویداد هستند، OpenClaw تأییدهای delivered + seen را ارسال میکند (best-effort).
|
||||
|
||||
## عیبیابی
|
||||
|
||||
**ورود ماندگار نمیشود:**
|
||||
**ورود پایدار نمیماند:**
|
||||
|
||||
- `openclaw channels status --probe`
|
||||
- ورود دوباره: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
|
||||
|
||||
**نام allowlist/گروه حل نشد:**
|
||||
**نام allowlist/گروه resolve نشد:**
|
||||
|
||||
- از شناسههای عددی در `allowFrom`/`groupAllowFrom`/`groups`، یا نامهای دقیق دوست/گروه استفاده کنید.
|
||||
- از شناسههای عددی در `allowFrom`/`groupAllowFrom` و شناسههای پایدار گروه در `groups` استفاده کنید. اگر عمداً به نامهای دقیق دوست/گروه نیاز دارید، `channels.zalouser.dangerouslyAllowNameMatching: true` را فعال کنید.
|
||||
|
||||
**از راهاندازی قدیمی مبتنی بر CLI ارتقا دادهاید:**
|
||||
|
||||
- هرگونه فرض قدیمی درباره فرایند خارجی `zca` را حذف کنید.
|
||||
- اکنون کانال بدون باینریهای CLI خارجی کاملا در OpenClaw اجرا میشود.
|
||||
- هر فرض قدیمی درباره فرایند خارجی `zca` را حذف کنید.
|
||||
- کانال اکنون بهطور کامل در OpenClaw و بدون باینریهای CLI خارجی اجرا میشود.
|
||||
|
||||
## مرتبط
|
||||
|
||||
- [مرور کلی کانالها](/fa/channels) — همه کانالهای پشتیبانیشده
|
||||
- [نمای کلی کانالها](/fa/channels) — همه کانالهای پشتیبانیشده
|
||||
- [Pairing](/fa/channels/pairing) — احراز هویت DM و جریان pairing
|
||||
- [گروهها](/fa/channels/groups) — رفتار چت گروهی و دروازهگذاری mention
|
||||
- [مسیریابی کانال](/fa/channels/channel-routing) — مسیریابی جلسه برای پیامها
|
||||
- [امنیت](/fa/gateway/security) — مدل دسترسی و مقاومسازی
|
||||
- [گروهها](/fa/channels/groups) — رفتار گفتوگوی گروهی و گیتگذاری اشاره
|
||||
- [مسیریابی کانال](/fa/channels/channel-routing) — مسیریابی نشست برای پیامها
|
||||
- [امنیت](/fa/gateway/security) — مدل دسترسی و سختسازی
|
||||
|
||||
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- هنوز از `openclaw daemon ...` در اسکریپتها استفاده میکنید
|
||||
- شما هنوز از `openclaw daemon ...` در اسکریپتها استفاده میکنید
|
||||
- به دستورهای چرخهٔ عمر سرویس نیاز دارید (install/start/stop/restart/status)
|
||||
summary: مرجع CLI برای `openclaw daemon` (نام مستعار قدیمی برای مدیریت سرویس Gateway)
|
||||
title: دیمون
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:17:53Z"
|
||||
generated_at: "2026-05-04T18:23:43Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 3f11b75bf2781e69f6f59b23364f06cf359f9f24407f25f19b9d2186f7158512
|
||||
source_hash: f84e11fc50bdf38da518a8fcf415ae461a2688c2299f996eee384357c0d04a05
|
||||
source_path: cli/daemon.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw daemon`
|
||||
|
||||
نام مستعار قدیمی برای فرمانهای مدیریت سرویس Gateway.
|
||||
نام مستعار قدیمی برای دستورهای مدیریت سرویس Gateway.
|
||||
|
||||
`openclaw daemon ...` به همان سطح کنترل سرویس نگاشت میشود که فرمانهای سرویس `openclaw gateway ...` از آن استفاده میکنند.
|
||||
`openclaw daemon ...` به همان سطح کنترل سرویس نگاشت میشود که دستورهای سرویس `openclaw gateway ...` استفاده میکنند.
|
||||
|
||||
## نحوه استفاده
|
||||
## کاربرد
|
||||
|
||||
```bash
|
||||
openclaw daemon status
|
||||
@ -30,36 +30,37 @@ openclaw daemon restart
|
||||
openclaw daemon uninstall
|
||||
```
|
||||
|
||||
## زیرفرمانها
|
||||
## زیردستورها
|
||||
|
||||
- `status`: وضعیت نصب سرویس را نشان میدهد و سلامت Gateway را بررسی میکند
|
||||
- `install`: سرویس را نصب میکند (`launchd`/`systemd`/`schtasks`)
|
||||
- `uninstall`: سرویس را حذف میکند
|
||||
- `start`: سرویس را شروع میکند
|
||||
- `stop`: سرویس را متوقف میکند
|
||||
- `restart`: سرویس را بازراهاندازی میکند
|
||||
- `status`: نمایش وضعیت نصب سرویس و بررسی سلامت Gateway
|
||||
- `install`: نصب سرویس (`launchd`/`systemd`/`schtasks`)
|
||||
- `uninstall`: حذف سرویس
|
||||
- `start`: راهاندازی سرویس
|
||||
- `stop`: توقف سرویس
|
||||
- `restart`: راهاندازی دوباره سرویس
|
||||
|
||||
## گزینههای رایج
|
||||
|
||||
- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
|
||||
- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
|
||||
- `restart`: `--force`, `--wait <duration>`, `--json`
|
||||
- `restart`: `--safe`, `--force`, `--wait <duration>`, `--json`
|
||||
- چرخه عمر (`uninstall|start|stop`): `--json`
|
||||
|
||||
نکات:
|
||||
یادداشتها:
|
||||
|
||||
- `status` در صورت امکان، SecretRefهای احراز هویت پیکربندیشده را برای احراز هویت بررسی حل میکند.
|
||||
- اگر یک SecretRef احراز هویت الزامی در این مسیر فرمان حل نشود، وقتی اتصالپذیری/احراز هویت بررسی شکست بخورد، `daemon status --json` مقدار `rpc.authWarning` را گزارش میکند؛ `--token`/`--password` را صریحا پاس دهید یا ابتدا منبع secret را حل کنید.
|
||||
- اگر بررسی موفق شود، هشدارهای auth-ref حلنشده برای جلوگیری از مثبت کاذب سرکوب میشوند.
|
||||
- `status --deep` یک اسکن سرویس در سطح سیستم و در حد بهترین تلاش اضافه میکند. وقتی سرویسهای دیگری شبیه Gateway پیدا کند، خروجی انسانی راهنماییهای پاکسازی را چاپ میکند و هشدار میدهد که همچنان توصیه معمول، یک Gateway برای هر ماشین است.
|
||||
- در نصبهای systemd روی Linux، بررسیهای انحراف توکن `status` هم منبعهای واحد `Environment=` و هم `EnvironmentFile=` را شامل میشوند.
|
||||
- بررسیهای انحراف، SecretRefهای `gateway.auth.token` را با استفاده از env زمان اجرا ادغامشده حل میکنند (ابتدا env فرمان سرویس، سپس fallback به env فرایند).
|
||||
- اگر احراز هویت توکنی عملا فعال نباشد (`gateway.auth.mode` صریح با مقدار `password`/`none`/`trusted-proxy`، یا حالتی که mode تنظیم نشده باشد و password بتواند برنده شود و هیچ گزینه توکنی نتواند برنده شود)، بررسیهای انحراف توکن از حل توکن پیکربندی عبور میکنند.
|
||||
- وقتی احراز هویت توکنی به توکن نیاز دارد و `gateway.auth.token` با SecretRef مدیریت میشود، `install` اعتبارسنجی میکند که SecretRef قابل حل باشد، اما توکن حلشده را در فراداده محیط سرویس ماندگار نمیکند.
|
||||
- اگر احراز هویت توکنی به توکن نیاز داشته باشد و SecretRef توکن پیکربندیشده حلنشده باشد، نصب با حالت بسته شکست میخورد.
|
||||
- اگر هم `gateway.auth.token` و هم `gateway.auth.password` پیکربندی شده باشند و `gateway.auth.mode` تنظیم نشده باشد، نصب تا زمانی که mode بهصراحت تنظیم شود مسدود میشود.
|
||||
- در macOS، `install` فایلهای plist مربوط به LaunchAgent را فقط برای مالک نگه میدارد و بهجای سریالسازی API keyها یا env refهای auth-profile در `EnvironmentVariables`، مقادیر محیط سرویس مدیریتشده را از طریق یک فایل و wrapper فقط برای مالک بارگذاری میکند.
|
||||
- اگر عمدا چند Gateway را روی یک میزبان اجرا میکنید، پورتها، پیکربندی/وضعیت، و workspaceها را جدا کنید؛ [/gateway#multiple-gateways-same-host](/fa/gateway#multiple-gateways-same-host) را ببینید.
|
||||
- `status` در صورت امکان SecretRefهای احراز هویت پیکربندیشده را برای احراز هویت بررسی حل میکند.
|
||||
- اگر یک SecretRef احراز هویت ضروری در این مسیر دستور حل نشده باشد، `daemon status --json` هنگام شکست اتصال/احراز هویت بررسی، `rpc.authWarning` را گزارش میکند؛ `--token`/`--password` را صریحا ارسال کنید یا ابتدا منبع secret را حل کنید.
|
||||
- اگر بررسی موفق شود، هشدارهای auth-ref حلنشده برای جلوگیری از مثبتهای کاذب سرکوب میشوند.
|
||||
- `status --deep` یک اسکن سرویس در سطح سیستم و بر پایه بهترین تلاش اضافه میکند. وقتی سرویسهای دیگری شبیه gateway پیدا کند، خروجی انسانی نکتههای پاکسازی را چاپ میکند و هشدار میدهد که همچنان توصیه معمول، یک gateway برای هر ماشین است.
|
||||
- در نصبهای systemd لینوکس، بررسیهای token-drift شامل هر دو منبع unit یعنی `Environment=` و `EnvironmentFile=` میشود.
|
||||
- بررسیهای drift، SecretRefهای `gateway.auth.token` را با استفاده از env زمان اجرای ادغامشده حل میکنند؛ ابتدا env دستور سرویس و سپس بهعنوان جایگزین env فرایند.
|
||||
- اگر احراز هویت توکنی عملا فعال نباشد (`gateway.auth.mode` صریح برابر با `password`/`none`/`trusted-proxy`، یا mode تنظیم نشده باشد و password بتواند برنده شود و هیچ نامزد توکنی نتواند برنده شود)، بررسیهای token-drift از حل توکن پیکربندی صرفنظر میکنند.
|
||||
- وقتی احراز هویت توکنی به یک توکن نیاز داشته باشد و `gateway.auth.token` با SecretRef مدیریت شود، `install` اعتبارسنجی میکند که SecretRef قابل حل باشد، اما توکن حلشده را در فراداده محیط سرویس پایدار نمیکند.
|
||||
- اگر احراز هویت توکنی به یک توکن نیاز داشته باشد و SecretRef توکن پیکربندیشده حل نشده باشد، نصب بهصورت بسته شکست میخورد.
|
||||
- اگر هر دو `gateway.auth.token` و `gateway.auth.password` پیکربندی شده باشند و `gateway.auth.mode` تنظیم نشده باشد، نصب تا زمانی که mode صریحا تنظیم شود مسدود میماند.
|
||||
- در macOS، `install` plistهای LaunchAgent را فقط برای مالک نگه میدارد و مقدارهای محیط سرویس مدیریتشده را بهجای سریالسازی API keyها یا ارجاعهای env پروفایل احراز هویت در `EnvironmentVariables`، از طریق یک فایل فقطمالک و wrapper بارگذاری میکند.
|
||||
- اگر عمدا چند gateway را روی یک میزبان اجرا میکنید، پورتها، پیکربندی/وضعیت، و workspaceها را جدا کنید؛ [/gateway#multiple-gateways-same-host](/fa/gateway#multiple-gateways-same-host) را ببینید.
|
||||
- `restart --safe` از Gateway در حال اجرا میخواهد کار فعال را پیشبررسی کند و پس از تخلیه کار فعال، یک راهاندازی دوباره ادغامشده زمانبندی کند. `restart` ساده رفتار موجود service-manager را حفظ میکند؛ `--force` همچنان مسیر override فوری است.
|
||||
|
||||
## ترجیح دهید
|
||||
|
||||
|
||||
@ -1,37 +1,37 @@
|
||||
---
|
||||
read_when:
|
||||
- اجرای Gateway از CLI (توسعه یا سرورها)
|
||||
- اشکالزدایی احراز هویت Gateway، حالتهای bind و اتصالپذیری
|
||||
- کشف Gatewayها از طریق Bonjour (DNS-SD محلی + گستردهناحیه)
|
||||
- عیبیابی احراز هویت Gateway، حالتهای bind، و اتصالپذیری
|
||||
- کشف Gatewayها از طریق Bonjour (محلی + DNS-SD گسترده)
|
||||
sidebarTitle: Gateway
|
||||
summary: OpenClaw Gateway CLI (`openclaw gateway`) — اجرای Gatewayها، پرسوجوی آنها و کشفشان
|
||||
summary: OpenClaw Gateway CLI (`openclaw gateway`) — اجرای Gatewayها، پرسوجو از آنها و کشف آنها
|
||||
title: Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:18:10Z"
|
||||
generated_at: "2026-05-04T18:23:43Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f7f948a8f0ee6e065afa02f354e690ad5cc4f71bdb8b8674f1b0396c439ab242
|
||||
source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d
|
||||
source_path: cli/gateway.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Gateway سرور WebSocket مربوط به OpenClaw است (کانالها، گرهها، نشستها، هوکها). زیرفرمانهای این صفحه زیر `openclaw gateway …` قرار دارند.
|
||||
Gateway سرور WebSocket متعلق به OpenClaw است (کانالها، Nodeها، نشستها، hookها). زیردستورهای این صفحه زیر `openclaw gateway …` قرار دارند.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Bonjour discovery" href="/fa/gateway/bonjour">
|
||||
راهاندازی mDNS محلی + DNS-SD گسترده.
|
||||
</Card>
|
||||
<Card title="Discovery overview" href="/fa/gateway/discovery">
|
||||
اینکه OpenClaw چگونه Gatewayها را معرفی و پیدا میکند.
|
||||
اینکه OpenClaw چگونه gatewayها را معرفی و پیدا میکند.
|
||||
</Card>
|
||||
<Card title="Configuration" href="/fa/gateway/configuration">
|
||||
کلیدهای پیکربندی سطح بالای Gateway.
|
||||
کلیدهای پیکربندی gateway در سطح بالا.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## اجرای Gateway
|
||||
|
||||
یک فرایند Gateway محلی را اجرا کنید:
|
||||
یک فرایند Gateway محلی اجرا کنید:
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -45,12 +45,12 @@ openclaw gateway run
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Startup behavior">
|
||||
- بهطور پیشفرض، Gateway از شروع به کار خودداری میکند مگر اینکه `gateway.mode=local` در `~/.openclaw/openclaw.json` تنظیم شده باشد. برای اجراهای موردی/توسعه از `--allow-unconfigured` استفاده کنید.
|
||||
- انتظار میرود `openclaw onboard --mode local` و `openclaw setup` مقدار `gateway.mode=local` را بنویسند. اگر فایل وجود دارد اما `gateway.mode` وجود ندارد، آن را پیکربندی خراب یا بازنویسیشده در نظر بگیرید و بهجای فرض ضمنی حالت محلی، آن را تعمیر کنید.
|
||||
- اگر فایل وجود دارد و `gateway.mode` وجود ندارد، Gateway این وضعیت را آسیب مشکوک پیکربندی تلقی میکند و برای شما «محلی بودن را حدس» نمیزند.
|
||||
- اتصال فراتر از loopback بدون احراز هویت مسدود میشود (محافظ ایمنی).
|
||||
- `SIGUSR1` در صورت مجاز بودن، یک راهاندازی مجدد درونفرایندی را فعال میکند (`commands.restart` بهطور پیشفرض فعال است؛ برای مسدود کردن راهاندازی مجدد دستی، `commands.restart: false` را تنظیم کنید، در حالی که ابزار Gateway/اعمال پیکربندی/بهروزرسانی همچنان مجاز میمانند).
|
||||
- کنترلگرهای `SIGINT`/`SIGTERM` فرایند Gateway را متوقف میکنند، اما هیچ وضعیت سفارشی ترمینال را بازگردانی نمیکنند. اگر CLI را با یک TUI یا ورودی raw-mode پوشش میدهید، پیش از خروج ترمینال را بازگردانی کنید.
|
||||
- بهطور پیشفرض، Gateway شروع به کار نمیکند مگر اینکه `gateway.mode=local` در `~/.openclaw/openclaw.json` تنظیم شده باشد. برای اجراهای موقت/توسعه از `--allow-unconfigured` استفاده کنید.
|
||||
- انتظار میرود `openclaw onboard --mode local` و `openclaw setup` مقدار `gateway.mode=local` را بنویسند. اگر فایل وجود دارد اما `gateway.mode` وجود ندارد، آن را بهعنوان پیکربندی خراب یا بازنویسیشده در نظر بگیرید و بهجای فرض ضمنی حالت محلی، آن را تعمیر کنید.
|
||||
- اگر فایل وجود دارد و `gateway.mode` وجود ندارد، Gateway این وضعیت را آسیب مشکوک به پیکربندی تلقی میکند و حاضر نیست برای شما «محلی را حدس بزند».
|
||||
- اتصال فراتر از loopback بدون احراز هویت مسدود میشود (ریل ایمنی).
|
||||
- `SIGUSR1` وقتی مجاز باشد یک راهاندازی مجدد درونفرایندی را فعال میکند (`commands.restart` بهطور پیشفرض فعال است؛ برای مسدود کردن راهاندازی مجدد دستی، `commands.restart: false` را تنظیم کنید، در حالی که اعمال/بهروزرسانی ابزار/پیکربندی gateway همچنان مجاز میماند).
|
||||
- handlerهای `SIGINT`/`SIGTERM` فرایند gateway را متوقف میکنند، اما هیچ وضعیت سفارشی ترمینال را بازیابی نمیکنند. اگر CLI را با TUI یا ورودی raw-mode بستهبندی میکنید، پیش از خروج ترمینال را بازیابی کنید.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -58,7 +58,7 @@ openclaw gateway run
|
||||
### گزینهها
|
||||
|
||||
<ParamField path="--port <port>" type="number">
|
||||
پورت WebSocket (پیشفرض از پیکربندی/env میآید؛ معمولاً `18789`).
|
||||
پورت WebSocket (پیشفرض از پیکربندی/env میآید؛ معمولا `18789`).
|
||||
</ParamField>
|
||||
<ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
|
||||
حالت bind شنونده.
|
||||
@ -70,81 +70,91 @@ openclaw gateway run
|
||||
بازنویسی توکن (همچنین `OPENCLAW_GATEWAY_TOKEN` را برای فرایند تنظیم میکند).
|
||||
</ParamField>
|
||||
<ParamField path="--password <password>" type="string">
|
||||
بازنویسی رمز عبور.
|
||||
بازنویسی گذرواژه.
|
||||
</ParamField>
|
||||
<ParamField path="--password-file <path>" type="string">
|
||||
رمز عبور Gateway را از یک فایل بخوانید.
|
||||
گذرواژه gateway را از یک فایل بخوانید.
|
||||
</ParamField>
|
||||
<ParamField path="--tailscale <off|serve|funnel>" type="string">
|
||||
Gateway را از طریق Tailscale در دسترس قرار دهید.
|
||||
</ParamField>
|
||||
<ParamField path="--tailscale-reset-on-exit" type="boolean">
|
||||
پیکربندی serve/funnel مربوط به Tailscale را هنگام خاموشی بازنشانی کنید.
|
||||
پیکربندی serve/funnel مربوط به Tailscale را هنگام خاموششدن بازنشانی کنید.
|
||||
</ParamField>
|
||||
<ParamField path="--allow-unconfigured" type="boolean">
|
||||
اجازه دهید Gateway بدون `gateway.mode=local` در پیکربندی شروع شود. فقط برای راهاندازی موقت/توسعه، محافظ شروع را دور میزند؛ فایل پیکربندی را نمینویسد یا تعمیر نمیکند.
|
||||
اجازه دهید gateway بدون `gateway.mode=local` در پیکربندی شروع شود. فقط برای bootstrap موقت/توسعه، guard شروع را دور میزند؛ فایل پیکربندی را نمینویسد یا تعمیر نمیکند.
|
||||
</ParamField>
|
||||
<ParamField path="--dev" type="boolean">
|
||||
اگر موجود نباشد، یک پیکربندی توسعه + workspace ایجاد کنید (از BOOTSTRAP.md عبور میکند).
|
||||
اگر وجود ندارد، پیکربندی توسعه + workspace بسازید (`BOOTSTRAP.md` را رد میکند).
|
||||
</ParamField>
|
||||
<ParamField path="--reset" type="boolean">
|
||||
پیکربندی توسعه + اعتبارنامهها + نشستها + workspace را بازنشانی کنید (نیازمند `--dev`).
|
||||
پیکربندی توسعه + credentials + نشستها + workspace را بازنشانی کنید (به `--dev` نیاز دارد).
|
||||
</ParamField>
|
||||
<ParamField path="--force" type="boolean">
|
||||
پیش از شروع، هر شنونده موجود روی پورت انتخابشده را متوقف کنید.
|
||||
پیش از شروع، هر شنونده موجود روی پورت انتخابشده را بکشید.
|
||||
</ParamField>
|
||||
<ParamField path="--verbose" type="boolean">
|
||||
گزارشهای مفصل.
|
||||
لاگهای پرجزئیات.
|
||||
</ParamField>
|
||||
<ParamField path="--cli-backend-logs" type="boolean">
|
||||
فقط گزارشهای backend مربوط به CLI را در کنسول نشان دهید (و stdout/stderr را فعال کنید).
|
||||
فقط لاگهای backend مربوط به CLI را در کنسول نشان دهید (و stdout/stderr را فعال کنید).
|
||||
</ParamField>
|
||||
<ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
|
||||
سبک گزارش Websocket.
|
||||
سبک لاگ Websocket.
|
||||
</ParamField>
|
||||
<ParamField path="--compact" type="boolean">
|
||||
نام مستعار برای `--ws-log compact`.
|
||||
</ParamField>
|
||||
<ParamField path="--raw-stream" type="boolean">
|
||||
رویدادهای خام جریان مدل را در jsonl ثبت کنید.
|
||||
رویدادهای خام stream مدل را در jsonl لاگ کنید.
|
||||
</ParamField>
|
||||
<ParamField path="--raw-stream-path <path>" type="string">
|
||||
مسیر jsonl جریان خام.
|
||||
مسیر jsonl مربوط به stream خام.
|
||||
</ParamField>
|
||||
|
||||
## راهاندازی مجدد Gateway
|
||||
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
openclaw gateway restart --safe
|
||||
openclaw gateway restart --force
|
||||
```
|
||||
|
||||
`openclaw gateway restart --safe` از Gateway در حال اجرا میخواهد پیش از راهاندازی مجدد، کارهای فعال OpenClaw را پیشبررسی کند. اگر عملیات صفشده، تحویل پاسخ، اجراهای embedded، یا اجرای taskها فعال باشند، Gateway مسدودکنندهها را گزارش میکند، درخواستهای تکراری راهاندازی مجدد امن را ادغام میکند، و پس از تخلیه کار فعال راهاندازی مجدد میشود. `restart` ساده برای سازگاری، رفتار موجود service-manager را نگه میدارد. فقط زمانی از `--force` استفاده کنید که صراحتا مسیر بازنویسی فوری را میخواهید.
|
||||
|
||||
<Warning>
|
||||
`--password` درونخطی ممکن است در فهرست فرایندهای محلی آشکار شود. `--password-file`، env، یا `gateway.auth.password` مبتنی بر SecretRef را ترجیح دهید.
|
||||
`--password` درونخطی میتواند در فهرستهای فرایند محلی آشکار شود. `--password-file`، env، یا `gateway.auth.password` مبتنی بر SecretRef را ترجیح دهید.
|
||||
</Warning>
|
||||
|
||||
### پروفایلگیری شروع
|
||||
|
||||
- `OPENCLAW_GATEWAY_STARTUP_TRACE=1` را تنظیم کنید تا زمانبندی مرحلهها هنگام شروع Gateway ثبت شود، از جمله تأخیر `eventLoopMax` برای هر مرحله و زمانبندیهای جدول جستوجوی Plugin برای installed-index، manifest registry، برنامهریزی شروع، و کارهای owner-map.
|
||||
- `OPENCLAW_DIAGNOSTICS=timeline` را همراه با `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` تنظیم کنید تا یک timeline تشخیصی شروع با بهترین تلاش در قالب JSONL برای harnessهای QA خارجی نوشته شود. همچنین میتوانید این پرچم را با `diagnostics.flags: ["timeline"]` در پیکربندی فعال کنید؛ مسیر همچنان از env فراهم میشود. برای گنجاندن نمونههای event-loop، `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` را اضافه کنید.
|
||||
- برای benchmark شروع Gateway، `pnpm test:startup:gateway -- --runs 5 --warmup 1` را اجرا کنید. benchmark نخستین خروجی فرایند، `/healthz`، `/readyz`، زمانبندیهای trace شروع، تأخیر event-loop، و جزئیات زمانبندی جدول جستوجوی Plugin را ثبت میکند.
|
||||
- `OPENCLAW_GATEWAY_STARTUP_TRACE=1` را تنظیم کنید تا زمانبندی فازها هنگام شروع Gateway لاگ شود، از جمله تاخیر `eventLoopMax` برای هر فاز و زمانبندیهای جدول lookup مربوط به Plugin برای installed-index، manifest registry، برنامهریزی شروع، و کار owner-map.
|
||||
- `OPENCLAW_DIAGNOSTICS=timeline` را همراه با `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` تنظیم کنید تا یک timeline تشخیصی شروع JSONL بهصورت best-effort برای harnessهای QA خارجی نوشته شود. همچنین میتوانید این پرچم را با `diagnostics.flags: ["timeline"]` در پیکربندی فعال کنید؛ مسیر همچنان از env تامین میشود. برای افزودن نمونههای event-loop، `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` را اضافه کنید.
|
||||
- برای benchmark کردن شروع Gateway، `pnpm test:startup:gateway -- --runs 5 --warmup 1` را اجرا کنید. benchmark نخستین خروجی فرایند، `/healthz`، `/readyz`، زمانبندیهای trace شروع، تاخیر event-loop، و جزئیات زمانبندی جدول lookup مربوط به Plugin را ثبت میکند.
|
||||
|
||||
## پرسوجوی یک Gateway در حال اجرا
|
||||
## پرسوجو از یک Gateway در حال اجرا
|
||||
|
||||
همه فرمانهای پرسوجو از WebSocket RPC استفاده میکنند.
|
||||
همه دستورهای پرسوجو از RPC روی WebSocket استفاده میکنند.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Output modes">
|
||||
- پیشفرض: خوانا برای انسان (در TTY رنگی).
|
||||
- `--json`: JSON خوانا برای ماشین (بدون styling/spinner).
|
||||
- `--no-color` (یا `NO_COLOR=1`): ANSI را غیرفعال میکند و در عین حال چیدمان انسانی را حفظ میکند.
|
||||
- پیشفرض: خوانا برای انسان (رنگی در TTY).
|
||||
- `--json`: JSON خوانا برای ماشین (بدون سبکدهی/spinner).
|
||||
- `--no-color` (یا `NO_COLOR=1`): ANSI را غیرفعال میکند و چیدمان انسانی را نگه میدارد.
|
||||
|
||||
</Tab>
|
||||
<Tab title="Shared options">
|
||||
- `--url <url>`: URL مربوط به WebSocket Gateway.
|
||||
- `--url <url>`: URL WebSocket مربوط به Gateway.
|
||||
- `--token <token>`: توکن Gateway.
|
||||
- `--password <password>`: رمز عبور Gateway.
|
||||
- `--timeout <ms>`: timeout/budget (بسته به فرمان متفاوت است).
|
||||
- `--password <password>`: گذرواژه Gateway.
|
||||
- `--timeout <ms>`: timeout/budget (بسته به دستور متفاوت است).
|
||||
- `--expect-final`: منتظر پاسخ "final" بمانید (فراخوانیهای agent).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
وقتی `--url` را تنظیم میکنید، CLI به اعتبارنامههای پیکربندی یا محیط fallback نمیکند. `--token` یا `--password` را صریحاً ارسال کنید. نبود اعتبارنامههای صریح خطاست.
|
||||
وقتی `--url` را تنظیم میکنید، CLI به credentials موجود در پیکربندی یا محیط fallback نمیکند. `--token` یا `--password` را صراحتا پاس دهید. نبودن credentials صریح یک خطاست.
|
||||
</Note>
|
||||
|
||||
### `gateway health`
|
||||
@ -153,11 +163,11 @@ openclaw gateway run
|
||||
openclaw gateway health --url ws://127.0.0.1:18789
|
||||
```
|
||||
|
||||
endpoint HTTP مربوط به `/healthz` یک probe زندهبودن است: وقتی سرور بتواند به HTTP پاسخ دهد، برمیگردد. endpoint HTTP مربوط به `/readyz` سختگیرانهتر است و تا زمانی که sidecarهای Plugin شروع، کانالها، یا hookهای پیکربندیشده هنوز در حال پایدار شدن هستند، قرمز میماند. پاسخهای readiness محلی یا احراز هویتشده شامل یک بلوک تشخیصی `eventLoop` با تأخیر event-loop، بهرهبرداری event-loop، نسبت هسته CPU، و یک پرچم `degraded` هستند.
|
||||
endpoint HTTP `/healthz` یک liveness probe است: وقتی سرور بتواند به HTTP پاسخ دهد، خروجی برمیگرداند. endpoint HTTP `/readyz` سختگیرتر است و تا زمانی که sidecarهای Plugin شروع، کانالها، یا hookهای پیکربندیشده هنوز در حال پایدار شدن باشند، قرمز میماند. پاسخهای detailed readiness محلی یا احراز هویتشده شامل یک بلوک diagnostic به نام `eventLoop` هستند که تاخیر event-loop، میزان استفاده event-loop، نسبت هسته CPU، و یک پرچم `degraded` را دارد.
|
||||
|
||||
### `gateway usage-cost`
|
||||
|
||||
خلاصههای هزینه مصرف را از گزارشهای نشست دریافت کنید.
|
||||
خلاصههای usage-cost را از لاگهای نشست دریافت کنید.
|
||||
|
||||
```bash
|
||||
openclaw gateway usage-cost
|
||||
@ -166,12 +176,12 @@ openclaw gateway usage-cost --json
|
||||
```
|
||||
|
||||
<ParamField path="--days <days>" type="number" default="30">
|
||||
تعداد روزهایی که باید گنجانده شوند.
|
||||
تعداد روزهایی که باید لحاظ شوند.
|
||||
</ParamField>
|
||||
|
||||
### `gateway stability`
|
||||
|
||||
ثبتکننده پایداری تشخیصی اخیر را از یک Gateway در حال اجرا دریافت کنید.
|
||||
recorder تشخیصی پایداری اخیر را از یک Gateway در حال اجرا دریافت کنید.
|
||||
|
||||
```bash
|
||||
openclaw gateway stability
|
||||
@ -182,19 +192,19 @@ openclaw gateway stability --json
|
||||
```
|
||||
|
||||
<ParamField path="--limit <limit>" type="number" default="25">
|
||||
حداکثر تعداد رویدادهای اخیر برای گنجاندن (حداکثر `1000`).
|
||||
حداکثر تعداد رویدادهای اخیر برای لحاظ کردن (حداکثر `1000`).
|
||||
</ParamField>
|
||||
<ParamField path="--type <type>" type="string">
|
||||
فیلتر بر اساس نوع رویداد تشخیصی، مانند `payload.large` یا `diagnostic.memory.pressure`.
|
||||
</ParamField>
|
||||
<ParamField path="--since-seq <seq>" type="number">
|
||||
فقط رویدادهای پس از یک شماره توالی تشخیصی را شامل کنید.
|
||||
فقط رویدادهای پس از یک شماره توالی تشخیصی را لحاظ کنید.
|
||||
</ParamField>
|
||||
<ParamField path="--bundle [path]" type="string">
|
||||
بهجای فراخوانی Gateway در حال اجرا، یک bundle پایداری ذخیرهشده را بخوانید. برای جدیدترین bundle زیر دایرکتوری وضعیت از `--bundle latest` (یا فقط `--bundle`) استفاده کنید، یا مسیر JSON یک bundle را مستقیماً ارسال کنید.
|
||||
بهجای فراخوانی Gateway در حال اجرا، یک bundle پایداری persisted را بخوانید. برای جدیدترین bundle زیر دایرکتوری state از `--bundle latest` (یا فقط `--bundle`) استفاده کنید، یا مسیر JSON یک bundle را مستقیما پاس دهید.
|
||||
</ParamField>
|
||||
<ParamField path="--export" type="boolean">
|
||||
بهجای چاپ جزئیات پایداری، یک zip تشخیصی پشتیبانی قابل اشتراکگذاری بنویسید.
|
||||
بهجای چاپ جزئیات پایداری، یک zip تشخیصی قابل اشتراکگذاری برای پشتیبانی بنویسید.
|
||||
</ParamField>
|
||||
<ParamField path="--output <path>" type="string">
|
||||
مسیر خروجی برای `--export`.
|
||||
@ -202,15 +212,15 @@ openclaw gateway stability --json
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Privacy and bundle behavior">
|
||||
- رکوردها metadata عملیاتی را نگه میدارند: نام رویدادها، شمارشها، اندازههای byte، خوانشهای حافظه، وضعیت صف/نشست، نام کانال/Plugin، و خلاصههای نشست ویرایششده. آنها متن chat، بدنههای webhook، خروجیهای ابزار، بدنههای خام درخواست یا پاسخ، tokenها، cookieها، مقادیر secret، hostnameها، یا شناسههای خام نشست را نگه نمیدارند. برای غیرفعال کردن کامل ثبتکننده، `diagnostics.enabled: false` را تنظیم کنید.
|
||||
- هنگام خروجهای fatal از Gateway، timeoutهای خاموشی، و شکستهای شروع پس از restart، وقتی ثبتکننده رویداد داشته باشد، OpenClaw همان snapshot تشخیصی را در `~/.openclaw/logs/stability/openclaw-stability-*.json` مینویسد. جدیدترین bundle را با `openclaw gateway stability --bundle latest` بررسی کنید؛ `--limit`، `--type`، و `--since-seq` نیز روی خروجی bundle اعمال میشوند.
|
||||
- رکوردها metadata عملیاتی را نگه میدارند: نام رویدادها، شمارشها، اندازههای بایتی، خوانشهای حافظه، وضعیت صف/نشست، نام کانال/Plugin، و خلاصههای نشست redactشده. آنها متن گفتوگو، بدنههای webhook، خروجیهای ابزار، بدنههای خام درخواست یا پاسخ، توکنها، کوکیها، مقادیر محرمانه، hostnames، یا شناسههای خام نشست را نگه نمیدارند. برای غیرفعال کردن کامل recorder، `diagnostics.enabled: false` را تنظیم کنید.
|
||||
- هنگام خروجهای fatal از Gateway، timeoutهای خاموشی، و شکستهای شروع پس از راهاندازی مجدد، وقتی recorder رویدادهایی داشته باشد، OpenClaw همان snapshot تشخیصی را در `~/.openclaw/logs/stability/openclaw-stability-*.json` مینویسد. جدیدترین bundle را با `openclaw gateway stability --bundle latest` بررسی کنید؛ `--limit`، `--type`، و `--since-seq` نیز روی خروجی bundle اعمال میشوند.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### `gateway diagnostics export`
|
||||
|
||||
یک zip تشخیصی محلی بنویسید که برای پیوست شدن به گزارشهای bug طراحی شده است. برای مدل privacy و محتوای bundle، [Diagnostics Export](/fa/gateway/diagnostics) را ببینید.
|
||||
یک zip تشخیصی محلی بنویسید که برای پیوست کردن به گزارشهای bug طراحی شده است. برای مدل حریم خصوصی و محتوای bundle، [Diagnostics Export](/fa/gateway/diagnostics) را ببینید.
|
||||
|
||||
```bash
|
||||
openclaw gateway diagnostics export
|
||||
@ -219,36 +229,36 @@ openclaw gateway diagnostics export --json
|
||||
```
|
||||
|
||||
<ParamField path="--output <path>" type="string">
|
||||
مسیر zip خروجی. پیشفرض، یک export پشتیبانی زیر دایرکتوری وضعیت است.
|
||||
مسیر zip خروجی. پیشفرض، یک export پشتیبانی زیر دایرکتوری state است.
|
||||
</ParamField>
|
||||
<ParamField path="--log-lines <count>" type="number" default="5000">
|
||||
حداکثر خطوط log پاکسازیشده برای گنجاندن.
|
||||
حداکثر تعداد خطوط لاگ sanitizeشده برای لحاظ کردن.
|
||||
</ParamField>
|
||||
<ParamField path="--log-bytes <bytes>" type="number" default="1000000">
|
||||
حداکثر byteهای log برای بررسی.
|
||||
حداکثر بایتهای لاگ برای بررسی.
|
||||
</ParamField>
|
||||
<ParamField path="--url <url>" type="string">
|
||||
URL مربوط به WebSocket Gateway برای snapshot سلامت.
|
||||
URL WebSocket مربوط به Gateway برای snapshot سلامت.
|
||||
</ParamField>
|
||||
<ParamField path="--token <token>" type="string">
|
||||
توکن Gateway برای snapshot سلامت.
|
||||
</ParamField>
|
||||
<ParamField path="--password <password>" type="string">
|
||||
رمز عبور Gateway برای snapshot سلامت.
|
||||
گذرواژه Gateway برای snapshot سلامت.
|
||||
</ParamField>
|
||||
<ParamField path="--timeout <ms>" type="number" default="3000">
|
||||
timeout برای snapshot وضعیت/سلامت.
|
||||
timeout مربوط به snapshot وضعیت/سلامت.
|
||||
</ParamField>
|
||||
<ParamField path="--no-stability-bundle" type="boolean">
|
||||
جستوجوی bundle پایداری ذخیرهشده را رد کنید.
|
||||
lookup مربوط به bundle پایداری persisted را رد کنید.
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
مسیر نوشتهشده، اندازه، و manifest را بهصورت JSON چاپ کنید.
|
||||
</ParamField>
|
||||
|
||||
export شامل یک manifest، یک خلاصه Markdown، شکل پیکربندی، جزئیات پیکربندی پاکسازیشده، خلاصههای log پاکسازیشده، snapshotهای وضعیت/سلامت پاکسازیشده Gateway، و جدیدترین bundle پایداری در صورت وجود است.
|
||||
export شامل یک manifest، یک خلاصه Markdown، شکل پیکربندی، جزئیات پیکربندی sanitizeشده، خلاصههای لاگ sanitizeشده، snapshotهای وضعیت/سلامت Gateway بهصورت sanitizeشده، و در صورت وجود، جدیدترین bundle پایداری است.
|
||||
|
||||
هدف آن اشتراکگذاری است. جزئیات عملیاتی مفید برای debugging را نگه میدارد، مانند فیلدهای امن log مربوط به OpenClaw، نامهای subsystem، کدهای وضعیت، durationها، حالتهای پیکربندیشده، پورتها، شناسههای Plugin، شناسههای provider، تنظیمات feature غیرمحرمانه، و پیامهای log عملیاتی ویرایششده. متن chat، بدنههای webhook، خروجیهای ابزار، اعتبارنامهها، cookieها، شناسههای account/message، متن prompt/instruction، hostnameها، و مقادیر secret را حذف یا ویرایش میکند. وقتی یک پیام با سبک LogTape شبیه متن payload کاربر/chat/tool باشد، export فقط این را نگه میدارد که یک پیام حذف شده است بههمراه شمار byte آن.
|
||||
قرار است قابل اشتراکگذاری باشد. جزئیات عملیاتی کمککننده به debugging را نگه میدارد، مانند فیلدهای امن لاگ OpenClaw، نامهای subsystem، کدهای وضعیت، مدتزمانها، حالتهای پیکربندیشده، پورتها، شناسههای Plugin، شناسههای provider، تنظیمات feature غیرمحرمانه، و پیامهای لاگ عملیاتی redactشده. متن گفتوگو، بدنههای webhook، خروجیهای ابزار، credentials، کوکیها، شناسههای حساب/پیام، متن prompt/instruction، hostnames، و مقادیر محرمانه را حذف یا redact میکند. وقتی یک پیام سبک LogTape شبیه متن payload کاربر/گفتوگو/ابزار باشد، export فقط این را نگه میدارد که پیام حذف شده است، بههمراه تعداد بایت آن.
|
||||
|
||||
### `gateway status`
|
||||
|
||||
@ -261,63 +271,63 @@ openclaw gateway status --require-rpc
|
||||
```
|
||||
|
||||
<ParamField path="--url <url>" type="string">
|
||||
یک هدف probe صریح اضافه کنید. remote پیکربندیشده + localhost همچنان probe میشوند.
|
||||
یک هدف پروب صریح اضافه کنید. راه دور پیکربندیشده + localhost همچنان پروب میشوند.
|
||||
</ParamField>
|
||||
<ParamField path="--token <token>" type="string">
|
||||
احراز هویت token برای probe.
|
||||
احراز هویت با توکن برای پروب.
|
||||
</ParamField>
|
||||
<ParamField path="--password <password>" type="string">
|
||||
احراز هویت password برای probe.
|
||||
احراز هویت با گذرواژه برای پروب.
|
||||
</ParamField>
|
||||
<ParamField path="--timeout <ms>" type="number" default="10000">
|
||||
timeout مربوط به probe.
|
||||
مهلت زمانی پروب.
|
||||
</ParamField>
|
||||
<ParamField path="--no-probe" type="boolean">
|
||||
probe اتصال را رد کنید (نمای فقط سرویس).
|
||||
پروب اتصال را رد کنید (نمای فقط سرویس).
|
||||
</ParamField>
|
||||
<ParamField path="--deep" type="boolean">
|
||||
سرویسهای سطح سیستم را نیز scan کنید.
|
||||
سرویسهای سطح سیستم را هم اسکن کنید.
|
||||
</ParamField>
|
||||
<ParamField path="--require-rpc" type="boolean">
|
||||
probe اتصال پیشفرض را به یک probe خواندن ارتقا دهید و وقتی آن probe خواندن شکست بخورد، با مقدار غیرصفر خارج شوید. نمیتواند با `--no-probe` ترکیب شود.
|
||||
پروب اتصال پیشفرض را به پروب خواندن ارتقا دهید و وقتی آن پروب خواندن شکست میخورد با کد غیرصفر خارج شوید. نمیتوان آن را با `--no-probe` ترکیب کرد.
|
||||
</ParamField>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="معنای وضعیت">
|
||||
- `gateway status` حتی وقتی پیکربندی CLI محلی موجود نیست یا نامعتبر است، برای عیبیابی در دسترس میماند.
|
||||
- `gateway status` پیشفرض، وضعیت سرویس، اتصال WebSocket و قابلیت احراز هویت قابل مشاهده در زمان دستدهی را اثبات میکند. عملیات خواندن/نوشتن/مدیریت را اثبات نمیکند.
|
||||
- کاوشهای عیبیابی برای احراز هویت دستگاه برای اولین بار، بدون تغییر هستند: وقتی توکن دستگاه ذخیرهشدهای وجود داشته باشد از آن دوباره استفاده میکنند، اما فقط برای بررسی وضعیت، هویت دستگاه CLI جدید یا رکورد جفتسازی دستگاه فقطخواندنی ایجاد نمیکنند.
|
||||
- `gateway status` در صورت امکان SecretRefهای احراز هویت پیکربندیشده را برای احراز هویت کاوش حل میکند.
|
||||
- اگر یک SecretRef احراز هویت موردنیاز در این مسیر فرمان حل نشود، `gateway status --json` هنگام شکست اتصال/احراز هویت کاوش، `rpc.authWarning` را گزارش میکند؛ `--token`/`--password` را صریحا بدهید یا ابتدا منبع secret را حل کنید.
|
||||
- اگر کاوش موفق شود، هشدارهای auth-ref حلنشده برای جلوگیری از مثبتهای کاذب پنهان میشوند.
|
||||
- وقتی سرویس در حال گوش دادن کافی نیست و لازم است فراخوانیهای RPC با محدوده خواندن نیز سالم باشند، در اسکریپتها و خودکارسازی از `--require-rpc` استفاده کنید.
|
||||
- `--deep` یک اسکن best-effort برای نصبهای اضافی launchd/systemd/schtasks اضافه میکند. وقتی چند سرویس شبیه Gateway شناسایی شود، خروجی انسانی نکات پاکسازی را چاپ میکند و هشدار میدهد که بیشتر راهاندازیها باید روی هر ماشین یک Gateway اجرا کنند.
|
||||
- خروجی انسانی شامل مسیر فایل لاگ حلشده بههمراه تصویر لحظهای مسیرها/اعتبار پیکربندی CLI در برابر سرویس است تا به عیبیابی drift پروفایل یا state-dir کمک کند.
|
||||
<Accordion title="معناشناسی وضعیت">
|
||||
- `gateway status` حتی وقتی پیکربندی CLI محلی وجود ندارد یا نامعتبر است، برای تشخیص عیب در دسترس میماند.
|
||||
- `gateway status` پیشفرض وضعیت سرویس، اتصال وبسوکت، و قابلیت احراز هویت قابل مشاهده هنگام دستدهی را اثبات میکند. عملیات خواندن/نوشتن/مدیریت را اثبات نمیکند.
|
||||
- پروبهای تشخیصی برای احراز هویت دستگاه در نخستین استفاده تغییردهنده نیستند: وقتی توکن دستگاه کششدهای وجود داشته باشد، همان را دوباره استفاده میکنند، اما صرفاً برای بررسی وضعیت، هویت جدید دستگاه CLI یا رکورد جفتسازی فقطخواندنی دستگاه ایجاد نمیکنند.
|
||||
- `gateway status` در صورت امکان SecretRefهای احراز هویت پیکربندیشده را برای احراز هویت پروب حل میکند.
|
||||
- اگر یک SecretRef احراز هویت الزامی در این مسیر فرمان حلنشده باشد، `gateway status --json` هنگام شکست اتصال/احراز هویت پروب، `rpc.authWarning` را گزارش میکند؛ `--token`/`--password` را صریحاً بدهید یا ابتدا منبع secret را حل کنید.
|
||||
- اگر پروب موفق شود، هشدارهای ارجاع احراز هویت حلنشده برای جلوگیری از مثبتهای کاذب سرکوب میشوند.
|
||||
- وقتی سرویس در حال گوش دادن کافی نیست و لازم است فراخوانیهای RPC با محدوده خواندن هم سالم باشند، در اسکریپتها و خودکارسازی از `--require-rpc` استفاده کنید.
|
||||
- `--deep` یک اسکن با بهترین تلاش برای نصبهای اضافی launchd/systemd/schtasks اضافه میکند. وقتی چند سرویس شبیه Gateway شناسایی شوند، خروجی انسانی نکتههای پاکسازی را چاپ میکند و هشدار میدهد که بیشتر راهاندازیها باید روی هر دستگاه یک Gateway اجرا کنند.
|
||||
- خروجی انسانی مسیر حلشده فایل لاگ بهعلاوه نمای لحظهای مسیرها/اعتبار پیکربندی CLI در برابر سرویس را شامل میشود تا به تشخیص drift پروفایل یا دایرکتوری وضعیت کمک کند.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="بررسیهای drift احراز هویت systemd در Linux">
|
||||
- در نصبهای Linux systemd، بررسیهای drift احراز هویت سرویس هر دو مقدار `Environment=` و `EnvironmentFile=` را از unit میخوانند (شامل `%h`، مسیرهای نقلقولشده، چند فایل، و فایلهای اختیاری `-`).
|
||||
- بررسیهای drift، SecretRefهای `gateway.auth.token` را با استفاده از env زمان اجرا ادغامشده حل میکنند (ابتدا env فرمان سرویس، سپس env فرایند بهعنوان fallback).
|
||||
- اگر احراز هویت توکنی عملا فعال نباشد (`gateway.auth.mode` صریح با مقدار `password`/`none`/`trusted-proxy`، یا mode تنظیم نشده باشد که در آن password میتواند برنده شود و هیچ کاندیدای token نمیتواند برنده شود)، بررسیهای token-drift از حل token پیکربندی صرفنظر میکنند.
|
||||
<Accordion title="بررسیهای drift احراز هویت در systemd لینوکس">
|
||||
- در نصبهای systemd لینوکس، بررسیهای drift احراز هویت سرویس مقدارهای `Environment=` و `EnvironmentFile=` را از unit میخوانند (از جمله `%h`، مسیرهای نقلقولشده، چند فایل، و فایلهای اختیاری `-`).
|
||||
- بررسیهای drift، SecretRefهای `gateway.auth.token` را با استفاده از محیط زمان اجرای ادغامشده حل میکنند (ابتدا محیط فرمان سرویس، سپس محیط فرایند بهعنوان جایگزین).
|
||||
- اگر احراز هویت با توکن عملاً فعال نباشد (`gateway.auth.mode` صریحِ `password`/`none`/`trusted-proxy`، یا حالتی که تنظیم نشده و در آن گذرواژه میتواند انتخاب شود و هیچ نامزد توکنی نمیتواند انتخاب شود)، بررسیهای drift توکن از حل توکن پیکربندی صرفنظر میکنند.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### `gateway probe`
|
||||
|
||||
`gateway probe` فرمان «عیبیابی همهچیز» است. همیشه این موارد را کاوش میکند:
|
||||
`gateway probe` فرمان «اشکالزدایی همهچیز» است. همیشه این موارد را پروب میکند:
|
||||
|
||||
- Gateway راه دور پیکربندیشده شما (اگر تنظیم شده باشد)، و
|
||||
- localhost (loopback) **حتی اگر remote پیکربندی شده باشد**.
|
||||
- localhost (loopback) **حتی اگر راه دور پیکربندی شده باشد**.
|
||||
|
||||
اگر `--url` را بدهید، آن هدف صریح پیش از هر دو اضافه میشود. خروجی انسانی هدفها را اینگونه برچسبگذاری میکند:
|
||||
اگر `--url` را بدهید، آن هدف صریح پیش از هر دوی آنها اضافه میشود. خروجی انسانی هدفها را اینگونه برچسب میزند:
|
||||
|
||||
- `URL (explicit)`
|
||||
- `Remote (configured)` یا `Remote (configured, inactive)`
|
||||
- `Local loopback`
|
||||
|
||||
<Note>
|
||||
اگر چند Gateway قابل دسترسی باشند، همه آنها را چاپ میکند. وقتی از پروفایلها/پورتهای جداگانه استفاده میکنید (مثلا یک ربات نجات)، چند Gateway پشتیبانی میشود، اما بیشتر نصبها همچنان یک Gateway واحد اجرا میکنند.
|
||||
اگر چند Gateway در دسترس باشند، همه آنها را چاپ میکند. چند Gateway وقتی از پروفایلها/پورتهای ایزوله استفاده میکنید (مثلاً یک ربات نجات) پشتیبانی میشوند، اما بیشتر نصبها همچنان یک Gateway واحد اجرا میکنند.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
@ -327,51 +337,51 @@ openclaw gateway probe --json
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="تفسیر">
|
||||
- `Reachable: yes` یعنی دستکم یک هدف اتصال WebSocket را پذیرفته است.
|
||||
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` گزارش میکند که کاوش چه چیزی را درباره احراز هویت توانسته اثبات کند. این از قابل دسترس بودن جداست.
|
||||
- `Read probe: ok` یعنی فراخوانیهای RPC جزئیات با محدوده خواندن (`health`/`status`/`system-presence`/`config.get`) نیز موفق بودهاند.
|
||||
- `Read probe: limited - missing scope: operator.read` یعنی اتصال موفق بوده اما RPC با محدوده خواندن محدود است. این بهعنوان قابل دسترس بودن **تنزلیافته** گزارش میشود، نه شکست کامل.
|
||||
- `Read probe: failed` پس از `Connect: ok` یعنی Gateway اتصال WebSocket را پذیرفته، اما عیبیابیهای خواندن بعدی timeout شده یا شکست خوردهاند. این نیز قابل دسترس بودن **تنزلیافته** است، نه یک Gateway غیرقابل دسترس.
|
||||
- مانند `gateway status`، probe از احراز هویت دستگاه ذخیرهشده موجود دوباره استفاده میکند اما هویت دستگاه برای اولین بار یا وضعیت جفتسازی ایجاد نمیکند.
|
||||
- کد خروج فقط زمانی غیرصفر است که هیچ هدف کاوششدهای قابل دسترسی نباشد.
|
||||
- `Reachable: yes` یعنی حداقل یک هدف اتصال وبسوکت را پذیرفته است.
|
||||
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` گزارش میکند که پروب درباره احراز هویت چه چیزی را توانسته اثبات کند. این از دسترسپذیری جداست.
|
||||
- `Read probe: ok` یعنی فراخوانیهای RPC جزئیات با محدوده خواندن (`health`/`status`/`system-presence`/`config.get`) نیز موفق شدهاند.
|
||||
- `Read probe: limited - missing scope: operator.read` یعنی اتصال موفق شده اما RPC با محدوده خواندن محدود است. این بهعنوان دسترسپذیری **تنزلیافته** گزارش میشود، نه شکست کامل.
|
||||
- `Read probe: failed` پس از `Connect: ok` یعنی Gateway اتصال وبسوکت را پذیرفته، اما تشخیصهای خواندن بعدی timeout شدهاند یا شکست خوردهاند. این هم دسترسپذیری **تنزلیافته** است، نه Gateway غیرقابل دسترس.
|
||||
- مانند `gateway status`، پروب از احراز هویت دستگاه کششده موجود دوباره استفاده میکند اما هویت دستگاه یا وضعیت جفتسازی نخستینبار ایجاد نمیکند.
|
||||
- کد خروج تنها زمانی غیرصفر است که هیچ هدف پروبشدهای در دسترس نباشد.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="خروجی JSON">
|
||||
سطح بالا:
|
||||
|
||||
- `ok`: دستکم یک هدف قابل دسترسی است.
|
||||
- `degraded`: دستکم یک هدف اتصال را پذیرفته اما عیبیابیهای RPC جزئیات کامل را کامل نکرده است.
|
||||
- `capability`: بهترین قابلیت مشاهدهشده در میان هدفهای قابل دسترسی (`read_only`، `write_capable`، `admin_capable`، `pairing_pending`، `connected_no_operator_scope`، یا `unknown`).
|
||||
- `primaryTargetId`: بهترین هدف برای در نظر گرفتن بهعنوان برنده فعال، به این ترتیب: URL صریح، SSH tunnel، remote پیکربندیشده، سپس local loopback.
|
||||
- `warnings[]`: رکوردهای هشدار best-effort با `code`، `message` و `targetIds` اختیاری.
|
||||
- `network`: راهنمای URLهای local loopback/tailnet مشتقشده از پیکربندی فعلی و شبکه میزبان.
|
||||
- `discovery.timeoutMs` و `discovery.count`: بودجه/تعداد نتیجه واقعی discovery استفادهشده برای این گذر probe.
|
||||
- `ok`: حداقل یک هدف در دسترس است.
|
||||
- `degraded`: حداقل یک هدف اتصال را پذیرفته اما تشخیصهای RPC جزئیات کامل را تکمیل نکرده است.
|
||||
- `capability`: بهترین قابلیت دیدهشده در میان اهداف در دسترس (`read_only`، `write_capable`، `admin_capable`، `pairing_pending`، `connected_no_operator_scope`، یا `unknown`).
|
||||
- `primaryTargetId`: بهترین هدف برای در نظر گرفتن بهعنوان برنده فعال با این ترتیب: URL صریح، تونل SSH، راه دور پیکربندیشده، سپس local loopback.
|
||||
- `warnings[]`: رکوردهای هشدار با بهترین تلاش همراه با `code`، `message`، و `targetIds` اختیاری.
|
||||
- `network`: راهنماهای URL برای local loopback/tailnet که از پیکربندی فعلی و شبکهبندی میزبان استخراج شدهاند.
|
||||
- `discovery.timeoutMs` و `discovery.count`: بودجه/تعداد نتیجه واقعی کشف که برای این گذر پروب استفاده شده است.
|
||||
|
||||
برای هر هدف (`targets[].connect`):
|
||||
|
||||
- `ok`: قابل دسترس بودن پس از اتصال + طبقهبندی تنزلیافته.
|
||||
- `rpcOk`: موفقیت RPC جزئیات کامل.
|
||||
- `scopeLimited`: شکست RPC جزئیات بهدلیل نبود محدوده operator.
|
||||
- `ok`: دسترسپذیری پس از اتصال + طبقهبندی تنزلیافته.
|
||||
- `rpcOk`: موفقیت کامل RPC جزئیات.
|
||||
- `scopeLimited`: RPC جزئیات به دلیل نبود محدوده operator شکست خورده است.
|
||||
|
||||
برای هر هدف (`targets[].auth`):
|
||||
|
||||
- `role`: نقش احراز هویت گزارششده در `hello-ok` وقتی در دسترس باشد.
|
||||
- `scopes`: محدودههای اعطاشده گزارششده در `hello-ok` وقتی در دسترس باشند.
|
||||
- `role`: نقش احراز هویت گزارششده در `hello-ok`، وقتی موجود باشد.
|
||||
- `scopes`: محدودههای اعطاشده گزارششده در `hello-ok`، وقتی موجود باشد.
|
||||
- `capability`: طبقهبندی قابلیت احراز هویت نمایشدادهشده برای آن هدف.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="کدهای هشدار رایج">
|
||||
- `ssh_tunnel_failed`: راهاندازی SSH tunnel شکست خورد؛ فرمان به probeهای مستقیم fallback کرد.
|
||||
- `multiple_gateways`: بیش از یک هدف قابل دسترسی بود؛ این غیرمعمول است مگر اینکه عمدا پروفایلهای جداگانه، مانند ربات نجات، اجرا کنید.
|
||||
- `auth_secretref_unresolved`: یک SecretRef احراز هویت پیکربندیشده برای یک هدف شکستخورده قابل حل نبود.
|
||||
- `probe_scope_limited`: اتصال WebSocket موفق بود، اما read probe بهدلیل نبود `operator.read` محدود شد.
|
||||
- `ssh_tunnel_failed`: راهاندازی تونل SSH شکست خورد؛ فرمان به پروبهای مستقیم برگشت.
|
||||
- `multiple_gateways`: بیش از یک هدف در دسترس بود؛ این غیرمعمول است مگر اینکه عمداً پروفایلهای ایزوله، مانند یک ربات نجات، اجرا کنید.
|
||||
- `auth_secretref_unresolved`: یک SecretRef احراز هویت پیکربندیشده برای یک هدف ناموفق قابل حل نبود.
|
||||
- `probe_scope_limited`: اتصال وبسوکت موفق شد، اما پروب خواندن به دلیل نبود `operator.read` محدود شد.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
#### Remote روی SSH (همارزی برنامه Mac)
|
||||
#### راه دور از طریق SSH (همارزی با اپ Mac)
|
||||
|
||||
حالت "Remote over SSH" در برنامه macOS از یک port-forward محلی استفاده میکند تا Gateway راه دور (که ممکن است فقط به loopback متصل باشد) در `ws://127.0.0.1:<port>` قابل دسترسی شود.
|
||||
حالت «راه دور از طریق SSH» در اپ macOS از یک فوروارد پورت محلی استفاده میکند تا Gateway راه دور (که ممکن است فقط به loopback متصل شده باشد) در `ws://127.0.0.1:<port>` در دسترس شود.
|
||||
|
||||
معادل CLI:
|
||||
|
||||
@ -386,17 +396,17 @@ openclaw gateway probe --ssh user@gateway-host
|
||||
فایل هویت.
|
||||
</ParamField>
|
||||
<ParamField path="--ssh-auto" type="boolean">
|
||||
نخستین میزبان Gateway کشفشده را از endpoint حلشده discovery (`local.` بهعلاوه دامنه wide-area پیکربندیشده، اگر وجود داشته باشد) بهعنوان هدف SSH انتخاب میکند. راهنماهای فقط TXT نادیده گرفته میشوند.
|
||||
اولین میزبان Gateway کشفشده را از نقطه پایانی کشف حلشده (`local.` بهعلاوه دامنه گسترهوسیع پیکربندیشده، اگر وجود داشته باشد) بهعنوان هدف SSH انتخاب کنید. راهنماهای فقط TXT نادیده گرفته میشوند.
|
||||
</ParamField>
|
||||
|
||||
پیکربندی (اختیاری، استفاده بهعنوان پیشفرض):
|
||||
پیکربندی (اختیاری، بهعنوان پیشفرض استفاده میشود):
|
||||
|
||||
- `gateway.remote.sshTarget`
|
||||
- `gateway.remote.sshIdentity`
|
||||
|
||||
### `gateway call <method>`
|
||||
|
||||
کمککار RPC سطح پایین.
|
||||
کمکرسان سطحپایین RPC.
|
||||
|
||||
```bash
|
||||
openclaw gateway call status
|
||||
@ -404,22 +414,22 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
|
||||
```
|
||||
|
||||
<ParamField path="--params <json>" type="string" default="{}">
|
||||
رشته شیء JSON برای params.
|
||||
رشته شیء JSON برای پارامترها.
|
||||
</ParamField>
|
||||
<ParamField path="--url <url>" type="string">
|
||||
URL WebSocket مربوط به Gateway.
|
||||
URL وبسوکت Gateway.
|
||||
</ParamField>
|
||||
<ParamField path="--token <token>" type="string">
|
||||
token مربوط به Gateway.
|
||||
توکن Gateway.
|
||||
</ParamField>
|
||||
<ParamField path="--password <password>" type="string">
|
||||
password مربوط به Gateway.
|
||||
گذرواژه Gateway.
|
||||
</ParamField>
|
||||
<ParamField path="--timeout <ms>" type="number">
|
||||
بودجه timeout.
|
||||
بودجه مهلت زمانی.
|
||||
</ParamField>
|
||||
<ParamField path="--expect-final" type="boolean">
|
||||
عمدتا برای RPCهای سبک agent که پیش از payload نهایی، رویدادهای میانی را stream میکنند.
|
||||
عمدتاً برای RPCهای سبک عامل که رویدادهای میانی را پیش از محموله نهایی بهصورت جریان ارسال میکنند.
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
خروجی JSON قابل خواندن توسط ماشین.
|
||||
@ -439,9 +449,9 @@ openclaw gateway restart
|
||||
openclaw gateway uninstall
|
||||
```
|
||||
|
||||
### نصب با wrapper
|
||||
### نصب با یک پوششدهنده
|
||||
|
||||
وقتی سرویس مدیریتشده باید از طریق executable دیگری شروع شود، مثلا یک shim مدیریت secrets یا کمککار run-as، از `--wrapper` استفاده کنید. wrapper آرگومانهای معمول Gateway را دریافت میکند و مسئول است در نهایت `openclaw` یا Node را با آن آرگومانها exec کند.
|
||||
وقتی سرویس مدیریتشده باید از طریق اجرایی دیگری شروع شود، از `--wrapper` استفاده کنید؛ برای مثال یک شیم مدیر اسرار یا کمکرسان اجرای با کاربر دیگر. پوششدهنده آرگومانهای عادی Gateway را دریافت میکند و مسئول است در نهایت `openclaw` یا Node را با آن آرگومانها اجرا کند.
|
||||
|
||||
```bash
|
||||
cat > ~/.local/bin/openclaw-doppler <<'EOF'
|
||||
@ -455,14 +465,14 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
همچنین میتوانید wrapper را از طریق environment تنظیم کنید. `gateway install` اعتبارسنجی میکند که مسیر یک فایل executable باشد، wrapper را در `ProgramArguments` سرویس مینویسد، و `OPENCLAW_WRAPPER` را در environment سرویس برای نصب مجدد اجباری، بهروزرسانیها، و تعمیرهای doctor بعدی پایدار میکند.
|
||||
همچنین میتوانید پوششدهنده را از طریق محیط تنظیم کنید. `gateway install` اعتبارسنجی میکند که مسیر یک فایل اجرایی باشد، پوششدهنده را در `ProgramArguments` سرویس مینویسد، و `OPENCLAW_WRAPPER` را در محیط سرویس برای نصبهای اجباری دوباره، بهروزرسانیها، و تعمیرهای doctor بعدی پایدار میکند.
|
||||
|
||||
```bash
|
||||
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
برای حذف wrapper پایدارشده، هنگام نصب مجدد `OPENCLAW_WRAPPER` را پاک کنید:
|
||||
برای حذف یک پوششدهنده پایدارشده، هنگام نصب دوباره `OPENCLAW_WRAPPER` را پاک کنید:
|
||||
|
||||
```bash
|
||||
OPENCLAW_WRAPPER= openclaw gateway install --force
|
||||
@ -471,47 +481,47 @@ openclaw gateway restart
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="گزینههای فرمان">
|
||||
- `gateway status`: `--url`، `--token`، `--password`، `--timeout`، `--no-probe`، `--require-rpc`، `--deep`، `--json`
|
||||
- `gateway install`: `--port`، `--runtime <node|bun>`، `--token`، `--wrapper <path>`، `--force`، `--json`
|
||||
- `gateway restart`: `--force`، `--wait <duration>`، `--json`
|
||||
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
|
||||
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--wrapper <path>`, `--force`, `--json`
|
||||
- `gateway restart`: `--force`, `--wait <duration>`, `--json`
|
||||
- `gateway uninstall|start|stop`: `--json`
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="رفتار چرخه عمر">
|
||||
- برای راهاندازی مجدد یک سرویس مدیریتشده از `gateway restart` استفاده کنید. `gateway stop` و `gateway start` را بهعنوان جایگزین restart زنجیره نکنید؛ در macOS، `gateway stop` عمدا پیش از توقف LaunchAgent، آن را غیرفعال میکند.
|
||||
- `gateway restart --wait 30s` بودجه drain راهاندازی مجدد پیکربندیشده را برای آن restart override میکند. عددهای بدون واحد میلیثانیه هستند؛ واحدهایی مانند `s`، `m` و `h` پذیرفته میشوند. `--wait 0` بهطور نامحدود منتظر میماند.
|
||||
- `gateway restart --force` از drain کار فعال صرفنظر میکند و بلافاصله restart میکند. وقتی operator مسدودکنندههای task فهرستشده را قبلا بررسی کرده و اکنون میخواهد Gateway برگردد، از آن استفاده کنید.
|
||||
- برای restart کردن یک سرویس مدیریتشده از `gateway restart` استفاده کنید. `gateway stop` و `gateway start` را بهعنوان جایگزین restart زنجیره نکنید؛ در macOS، `gateway stop` عمداً LaunchAgent را پیش از توقف آن غیرفعال میکند.
|
||||
- `gateway restart --wait 30s` بودجه تخلیه restart پیکربندیشده را برای آن restart بازنویسی میکند. عددهای تنها میلیثانیه هستند؛ واحدهایی مانند `s`، `m`، و `h` پذیرفته میشوند. `--wait 0` بهطور نامحدود منتظر میماند.
|
||||
- `gateway restart --force` تخلیه کار فعال را رد میکند و فوراً restart میکند. وقتی یک اپراتور مسدودکنندههای وظیفه فهرستشده را از قبل بررسی کرده و اکنون میخواهد gateway برگردد، از آن استفاده کنید.
|
||||
- فرمانهای چرخه عمر برای اسکریپتنویسی `--json` را میپذیرند.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="احراز هویت و SecretRefها هنگام نصب">
|
||||
- وقتی احراز هویت توکنی به token نیاز دارد و `gateway.auth.token` با SecretRef مدیریت میشود، `gateway install` اعتبارسنجی میکند که SecretRef قابل حل باشد اما token حلشده را در metadata مربوط به environment سرویس پایدار نمیکند.
|
||||
- اگر احراز هویت توکنی به token نیاز داشته باشد و SecretRef توکن پیکربندیشده حلنشده باشد، نصب بهجای پایدار کردن fallback plaintext بهصورت بسته شکست میخورد.
|
||||
- برای احراز هویت password در `gateway run`، `OPENCLAW_GATEWAY_PASSWORD`، `--password-file`، یا `gateway.auth.password` پشتیبانیشده با SecretRef را به inline `--password` ترجیح دهید.
|
||||
- در حالت احراز هویت استنباطی، `OPENCLAW_GATEWAY_PASSWORD` فقط در shell الزامات token نصب را آسانتر نمیکند؛ هنگام نصب یک سرویس مدیریتشده از پیکربندی بادوام (`gateway.auth.password` یا config `env`) استفاده کنید.
|
||||
- اگر هم `gateway.auth.token` و هم `gateway.auth.password` پیکربندی شده باشند و `gateway.auth.mode` تنظیم نشده باشد، نصب تا زمانی که mode صریحا تنظیم شود مسدود میشود.
|
||||
- وقتی احراز هویت با توکن به توکن نیاز دارد و `gateway.auth.token` با SecretRef مدیریت میشود، `gateway install` اعتبارسنجی میکند که SecretRef قابل حل باشد اما توکن حلشده را در فراداده محیط سرویس پایدار نمیکند.
|
||||
- اگر احراز هویت با توکن به توکن نیاز داشته باشد و SecretRef توکن پیکربندیشده حلنشده باشد، نصب بهصورت بسته شکست میخورد به جای اینکه متن ساده جایگزین را پایدار کند.
|
||||
- برای احراز هویت با گذرواژه در `gateway run`، `OPENCLAW_GATEWAY_PASSWORD`، `--password-file`، یا `gateway.auth.password` مبتنی بر SecretRef را به `--password` درونخطی ترجیح دهید.
|
||||
- در حالت احراز هویت استنباطی، `OPENCLAW_GATEWAY_PASSWORD` فقط در پوسته الزامات توکن نصب را کاهش نمیدهد؛ هنگام نصب یک سرویس مدیریتشده از پیکربندی پایدار (`gateway.auth.password` یا `env` پیکربندی) استفاده کنید.
|
||||
- اگر هر دو `gateway.auth.token` و `gateway.auth.password` پیکربندی شده باشند و `gateway.auth.mode` تنظیم نشده باشد، نصب تا زمانی که mode صریحاً تنظیم شود مسدود میشود.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## کشف Gatewayها (Bonjour)
|
||||
|
||||
`gateway discover` beaconهای Gateway (`_openclaw-gw._tcp`) را اسکن میکند.
|
||||
`gateway discover` بیکنهای Gateway (`_openclaw-gw._tcp`) را اسکن میکند.
|
||||
|
||||
- DNS-SD چندپخشی: `local.`
|
||||
- DNS-SD تکپخشی (Wide-Area Bonjour): یک دامنه انتخاب کنید (مثال: `openclaw.internal.`) و split DNS + یک سرور DNS راهاندازی کنید؛ [Bonjour](/fa/gateway/bonjour) را ببینید.
|
||||
|
||||
فقط Gatewayهایی که discovery مربوط به Bonjour در آنها فعال است (پیشفرض)، beacon را تبلیغ میکنند.
|
||||
فقط Gatewayهایی که کشف Bonjour در آنها فعال است (پیشفرض) beacon را تبلیغ میکنند.
|
||||
|
||||
رکوردهای Wide-Area discovery شامل (TXT) هستند:
|
||||
رکوردهای کشف Wide-Area شامل این موارد هستند (TXT):
|
||||
|
||||
- `role` (راهنمای نقش Gateway)
|
||||
- `transport` (راهنمای transport، مثلا `gateway`)
|
||||
- `gatewayPort` (پورت WebSocket، معمولا `18789`)
|
||||
- `sshPort` (اختیاری؛ clientها وقتی وجود نداشته باشد هدفهای SSH را بهطور پیشفرض `22` میگیرند)
|
||||
- `tailnetDns` (نام میزبان MagicDNS، وقتی در دسترس باشد)
|
||||
- `gatewayTls` / `gatewayTlsSha256` (TLS فعال + اثر انگشت گواهی)
|
||||
- `cliPath` (راهنمای remote-install نوشتهشده در ناحیه wide-area)
|
||||
- `transport` (راهنمای transport، مثلاً `gateway`)
|
||||
- `gatewayPort` (پورت WebSocket، معمولاً `18789`)
|
||||
- `sshPort` (اختیاری؛ وقتی وجود نداشته باشد، کلاینتها هدفهای پیشفرض SSH را `22` در نظر میگیرند)
|
||||
- `tailnetDns` (نام میزبان MagicDNS، در صورت موجود بودن)
|
||||
- `gatewayTls` / `gatewayTlsSha256` (TLS فعال + اثرانگشت گواهی)
|
||||
- `cliPath` (راهنمای نصب از راه دور که در zone گستردهمحدوده نوشته میشود)
|
||||
|
||||
### `gateway discover`
|
||||
|
||||
@ -520,13 +530,13 @@ openclaw gateway discover
|
||||
```
|
||||
|
||||
<ParamField path="--timeout <ms>" type="number" default="2000">
|
||||
مهلت زمانی برای هر فرمان (مرور/حلکردن).
|
||||
مهلت زمانی هر فرمان (browse/resolve).
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
خروجی قابل خواندن برای ماشین (همچنین سبکدهی/نشانگر چرخان را غیرفعال میکند).
|
||||
خروجی قابل خواندن توسط ماشین (همچنین استایلدهی/چرخنده را غیرفعال میکند).
|
||||
</ParamField>
|
||||
|
||||
نمونهها:
|
||||
مثالها:
|
||||
|
||||
```bash
|
||||
openclaw gateway discover --timeout 4000
|
||||
@ -534,9 +544,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
|
||||
```
|
||||
|
||||
<Note>
|
||||
- CLI دامنهی `local.` را بههمراه دامنهی پهنهگستردهی پیکربندیشده، وقتی فعال باشد، پویش میکند.
|
||||
- `wsUrl` در خروجی JSON از نقطهی پایانی سرویسِ حلشده بهدست میآید، نه از راهنماییهای فقط TXT مانند `lanHost` یا `tailnetDns`.
|
||||
- در mDNS مربوط به `local.`، `sshPort` و `cliPath` فقط وقتی پخش میشوند که `discovery.mdns.mode` برابر با `full` باشد. DNS-SD پهنهگسترده همچنان `cliPath` را مینویسد؛ `sshPort` آنجا هم اختیاری میماند.
|
||||
- CLI علاوه بر `local.`، دامنه گستردهمحدوده پیکربندیشده را نیز هنگام فعال بودن اسکن میکند.
|
||||
- `wsUrl` در خروجی JSON از endpoint سرویس resolveشده مشتق میشود، نه از راهنماهای فقط-TXT مانند `lanHost` یا `tailnetDns`.
|
||||
- در mDNS مربوط به `local.`، `sshPort` و `cliPath` فقط وقتی broadcast میشوند که `discovery.mdns.mode` برابر `full` باشد. DNS-SD گستردهمحدوده همچنان `cliPath` را مینویسد؛ `sshPort` آنجا هم اختیاری میماند.
|
||||
|
||||
</Note>
|
||||
|
||||
|
||||
@ -1,46 +1,42 @@
|
||||
---
|
||||
read_when:
|
||||
- وقتی ارائهدهندگان API شکست میخورند، یک راهکار پشتیبان قابلاعتماد میخواهید
|
||||
- در حال اجرای Codex CLI یا دیگر CLIهای هوش مصنوعی محلی هستید و میخواهید دوباره از آنها استفاده کنید
|
||||
- وقتی ارائهدهندگان API دچار خطا میشوند، به یک راهکار جایگزین قابل اعتماد نیاز دارید
|
||||
- شما Codex CLI یا CLIهای محلی دیگر هوش مصنوعی را اجرا میکنید و میخواهید دوباره از آنها استفاده کنید
|
||||
- میخواهید پل لوپبک MCP را برای دسترسی ابزارهای بکاند CLI درک کنید
|
||||
summary: 'بکاندهای CLI: جایگزین CLI هوش مصنوعی محلی با پل ابزار اختیاری MCP'
|
||||
summary: 'بکاندهای CLI: جایگزین CLI هوش مصنوعی محلی با پل ابزار MCP اختیاری'
|
||||
title: بکاندهای CLI
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T11:44:36Z"
|
||||
generated_at: "2026-05-04T18:23:50Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f343469d6a42dc6146196355dc2ba3feed045515c3d8446941b90971aadc9a16
|
||||
source_hash: 55534c48c5e226857b9320fd369416583e5c2efc80eabd4746f939afdd027dc1
|
||||
source_path: gateway/cli-backends.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw میتواند **CLIهای هوش مصنوعی محلی** را بهعنوان یک **مسیر جایگزین فقط متنی** اجرا کند، وقتی ارائهدهندگان API از دسترس خارجاند،
|
||||
با محدودیت نرخ مواجهاند، یا موقتاً رفتار نادرستی دارند. این طراحی عمداً محافظهکارانه است:
|
||||
OpenClaw میتواند **CLIهای هوش مصنوعی محلی** را بهعنوان یک **مسیر جایگزین فقط متنی** اجرا کند، زمانی که ارائهدهندگان API از دسترس خارج شدهاند، محدودیت نرخ دارند، یا موقتاً درست رفتار نمیکنند. این رفتار عمداً محافظهکارانه است:
|
||||
|
||||
- **ابزارهای OpenClaw مستقیماً تزریق نمیشوند**، اما backendهایی با `bundleMcp: true`
|
||||
میتوانند ابزارهای Gateway را از طریق یک پل MCP loopback دریافت کنند.
|
||||
- **جریاندهی JSONL** برای CLIهایی که از آن پشتیبانی میکنند.
|
||||
- **Sessionها پشتیبانی میشوند** (بنابراین نوبتهای بعدی منسجم میمانند).
|
||||
- **ابزارهای OpenClaw مستقیماً تزریق نمیشوند**، اما پشتیبانهایی با `bundleMcp: true`
|
||||
میتوانند ابزارهای Gateway را از طریق یک پل MCP روی loopback دریافت کنند.
|
||||
- **استریم JSONL** برای CLIهایی که از آن پشتیبانی میکنند.
|
||||
- **Sessionها پشتیبانی میشوند** (پس نوبتهای پیگیری منسجم میمانند).
|
||||
- **تصاویر میتوانند عبور داده شوند** اگر CLI مسیرهای تصویر را بپذیرد.
|
||||
|
||||
این بیشتر بهعنوان یک **شبکه ایمنی** طراحی شده است تا یک مسیر اصلی. زمانی از آن استفاده کنید که
|
||||
پاسخهای متنی «همیشه کار میکند» میخواهید بدون تکیه بر APIهای خارجی.
|
||||
این قابلیت بهجای یک مسیر اصلی، بهعنوان یک **شبکه ایمنی** طراحی شده است. وقتی پاسخهای متنی «همیشه کار میکند» را بدون اتکا به APIهای خارجی میخواهید، از آن استفاده کنید.
|
||||
|
||||
اگر runtime کامل harness با کنترلهای session در ACP، وظایف پسزمینه،
|
||||
اتصال thread/conversation و sessionهای کدنویسی خارجی پایدار میخواهید، بهجای آن از
|
||||
[Agentهای ACP](/fa/tools/acp-agents) استفاده کنید. backendهای CLI، ACP نیستند.
|
||||
اگر یک runtime کامل harness با کنترلهای session مربوط به ACP، وظایف پسزمینه، اتصال thread/conversation، و sessionهای کدنویسی خارجی پایدار میخواهید، بهجای آن از
|
||||
[ACP Agents](/fa/tools/acp-agents) استفاده کنید. پشتیبانهای CLI، ACP نیستند.
|
||||
|
||||
## شروع سریع مناسب مبتدیان
|
||||
|
||||
میتوانید از Codex CLI **بدون هیچ configای** استفاده کنید (Plugin بستهبندیشده OpenAI
|
||||
میتوانید از Codex CLI **بدون هیچ تنظیماتی** استفاده کنید (Plugin همراه OpenAI
|
||||
یک backend پیشفرض ثبت میکند):
|
||||
|
||||
```bash
|
||||
openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
```
|
||||
|
||||
اگر Gateway شما زیر launchd/systemd اجرا میشود و PATH حداقلی است، فقط
|
||||
مسیر command را اضافه کنید:
|
||||
اگر Gateway شما زیر launchd/systemd اجرا میشود و PATH حداقلی است، فقط مسیر command را اضافه کنید:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -56,13 +52,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
}
|
||||
```
|
||||
|
||||
همین است. هیچ کلید یا config احراز هویت اضافی فراتر از خود CLI لازم نیست.
|
||||
همین کافی است. هیچ key یا تنظیمات auth اضافهای فراتر از خود CLI لازم نیست.
|
||||
|
||||
اگر از یک backend بستهبندیشده CLI بهعنوان **ارائهدهنده اصلی پیام** روی یک
|
||||
میزبان Gateway استفاده میکنید، OpenClaw اکنون وقتی config شما بهطور صریح به آن backend در یک model ref یا زیر
|
||||
`agents.defaults.cliBackends` ارجاع دهد، Plugin بستهبندیشده مالک آن را بهصورت خودکار بارگذاری میکند.
|
||||
اگر از یک backend همراه CLI بهعنوان **ارائهدهنده اصلی پیام** روی یک میزبان Gateway استفاده میکنید، OpenClaw اکنون وقتی config شما صراحتاً به آن backend در یک model ref یا زیر
|
||||
`agents.defaults.cliBackends`
|
||||
ارجاع میدهد، Plugin همراه مالک آن را بهصورت خودکار بارگذاری میکند.
|
||||
|
||||
## استفاده از آن بهعنوان fallback
|
||||
## استفاده بهعنوان fallback
|
||||
|
||||
یک backend CLI را به فهرست fallback خود اضافه کنید تا فقط وقتی مدلهای اصلی شکست میخورند اجرا شود:
|
||||
|
||||
@ -83,22 +79,22 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
}
|
||||
```
|
||||
|
||||
نکتهها:
|
||||
نکات:
|
||||
|
||||
- اگر از `agents.defaults.models` (allowlist) استفاده میکنید، باید مدلهای backend CLI خود را هم آنجا اضافه کنید.
|
||||
- اگر ارائهدهنده اصلی شکست بخورد (احراز هویت، محدودیت نرخ، timeoutها)، OpenClaw
|
||||
بعداً backend CLI را امتحان میکند.
|
||||
- اگر از `agents.defaults.models` (allowlist) استفاده میکنید، باید مدلهای backend CLI خود را هم آنجا وارد کنید.
|
||||
- اگر ارائهدهنده اصلی شکست بخورد (auth، محدودیت نرخ، timeoutها)، OpenClaw
|
||||
سپس backend CLI را امتحان میکند.
|
||||
|
||||
## نمای کلی پیکربندی
|
||||
|
||||
همه backendهای CLI زیر این بخش قرار دارند:
|
||||
همه backendهای CLI زیر این مسیر قرار دارند:
|
||||
|
||||
```
|
||||
agents.defaults.cliBackends
|
||||
```
|
||||
|
||||
هر ورودی با یک **provider id** کلید میشود (مثلاً `codex-cli`، `my-cli`).
|
||||
provider id سمت چپ model ref شما میشود:
|
||||
هر ورودی با یک **شناسه ارائهدهنده** کلیدگذاری میشود (مثلاً `codex-cli`، `my-cli`).
|
||||
شناسه ارائهدهنده سمت چپ model ref شما میشود:
|
||||
|
||||
```
|
||||
<provider>/<model>
|
||||
@ -144,48 +140,39 @@ provider id سمت چپ model ref شما میشود:
|
||||
}
|
||||
```
|
||||
|
||||
## نحوه کار
|
||||
## سازوکار
|
||||
|
||||
1. **یک backend را انتخاب میکند** بر اساس پیشوند provider (`codex-cli/...`).
|
||||
1. **یک backend را انتخاب میکند** بر اساس پیشوند ارائهدهنده (`codex-cli/...`).
|
||||
2. **یک system prompt میسازد** با استفاده از همان prompt و زمینه workspace در OpenClaw.
|
||||
3. **CLI را اجرا میکند** با یک session id (اگر پشتیبانی شود) تا تاریخچه سازگار بماند.
|
||||
backend بستهبندیشده `claude-cli` برای هر session در OpenClaw یک فرایند Claude stdio را زنده نگه میدارد
|
||||
و نوبتهای بعدی را از طریق stream-json stdin میفرستد.
|
||||
backend همراه `claude-cli` برای هر session در OpenClaw یک فرایند stdio مربوط به Claude را زنده نگه میدارد و نوبتهای پیگیری را از طریق stdin بهصورت stream-json میفرستد.
|
||||
4. **خروجی را parse میکند** (JSON یا متن ساده) و متن نهایی را برمیگرداند.
|
||||
5. **session idها را ذخیره میکند** برای هر backend، تا پیگیریها همان session در CLI را دوباره استفاده کنند.
|
||||
5. **session idها را نگه میدارد** برای هر backend، تا پیگیریها همان session CLI را دوباره استفاده کنند.
|
||||
|
||||
<Note>
|
||||
backend بستهبندیشده Anthropic به نام `claude-cli` دوباره پشتیبانی میشود. کارکنان Anthropic
|
||||
به ما گفتهاند استفاده از Claude CLI به سبک OpenClaw دوباره مجاز است، بنابراین OpenClaw
|
||||
استفاده از `claude -p` را برای این integration مجاز تلقی میکند، مگر اینکه Anthropic
|
||||
سیاست جدیدی منتشر کند.
|
||||
backend همراه Anthropic یعنی `claude-cli` دوباره پشتیبانی میشود. کارکنان Anthropic
|
||||
به ما گفتند استفاده Claude CLI به سبک OpenClaw دوباره مجاز است، بنابراین OpenClaw استفاده از
|
||||
`claude -p` را برای این integration مجاز تلقی میکند، مگر اینکه Anthropic سیاست تازهای منتشر کند.
|
||||
</Note>
|
||||
|
||||
backend بستهبندیشده OpenAI به نام `codex-cli`، system prompt متعلق به OpenClaw را از طریق
|
||||
override در config مربوط به `model_instructions_file` در Codex عبور میدهد (`-c
|
||||
model_instructions_file="..."`). Codex یک flag به سبک Claude مثل
|
||||
`--append-system-prompt` ارائه نمیکند، بنابراین OpenClaw prompt مونتاژشده را برای هر
|
||||
session تازه Codex CLI در یک فایل موقت مینویسد.
|
||||
backend همراه OpenAI یعنی `codex-cli`، system prompt مربوط به OpenClaw را از طریق override تنظیمات
|
||||
`model_instructions_file` در Codex عبور میدهد (`-c
|
||||
model_instructions_file="..."`). Codex فلگی شبیه Claude با نام
|
||||
`--append-system-prompt` ارائه نمیکند، بنابراین OpenClaw prompt مونتاژشده را برای هر session تازه Codex CLI در یک فایل موقت مینویسد.
|
||||
|
||||
backend بستهبندیشده Anthropic به نام `claude-cli` snapshot مربوط به OpenClaw skills را
|
||||
از دو مسیر دریافت میکند: کاتالوگ فشرده Skills در OpenClaw در system prompt افزودهشده، و
|
||||
یک Plugin موقت Claude Code که با `--plugin-dir` فرستاده میشود. Plugin فقط
|
||||
skills واجد شرایط برای آن agent/session را شامل میشود، بنابراین resolver بومی skill در Claude Code
|
||||
همان مجموعه فیلترشدهای را میبیند که OpenClaw در غیر این صورت در
|
||||
prompt اعلام میکرد. overrideهای env/API key مربوط به Skill همچنان توسط OpenClaw روی
|
||||
محیط فرایند child برای اجرا اعمال میشوند.
|
||||
backend همراه Anthropic یعنی `claude-cli`، snapshot مربوط به Skills در OpenClaw را از دو راه دریافت میکند: کاتالوگ فشرده Skills در OpenClaw در system prompt افزودهشده، و یک Plugin موقت Claude Code که با `--plugin-dir` ارسال میشود. Plugin فقط شامل skillهای واجد شرایط برای آن agent/session است، بنابراین resolver بومی skill در Claude Code همان مجموعه فیلترشدهای را میبیند که OpenClaw در غیر این صورت در prompt اعلام میکرد. overrideهای env/API key مربوط به skill همچنان توسط OpenClaw روی محیط child process برای اجرا اعمال میشوند.
|
||||
|
||||
Claude CLI همچنین mode مجوز غیرتعاملی خودش را دارد. OpenClaw آن را
|
||||
به policy موجود exec نگاشت میکند بهجای افزودن config ویژه Claude: وقتی
|
||||
policy مؤثر درخواستشده exec، YOLO باشد (`tools.exec.security: "full"` و
|
||||
`tools.exec.ask: "off"`)، OpenClaw گزینه `--permission-mode bypassPermissions` را اضافه میکند.
|
||||
تنظیمات agent-specific در `agents.list[].tools.exec`، مقدار global `tools.exec` را برای
|
||||
آن agent override میکنند. برای اجبار یک mode متفاوت در Claude، raw backend args صریحی
|
||||
مثل `--permission-mode default` یا `--permission-mode acceptEdits` را زیر
|
||||
Claude CLI حالت permission غیرتعاملی خودش را هم دارد. OpenClaw آن را بهجای اضافه کردن config مخصوص Claude، به policy موجود exec نگاشت میکند: وقتی policy مؤثر درخواستشده exec برابر YOLO باشد (`tools.exec.security: "full"` و
|
||||
`tools.exec.ask: "off"`)، OpenClaw مقدار `--permission-mode bypassPermissions` را اضافه میکند.
|
||||
تنظیمات per-agent در `agents.list[].tools.exec` مقدار global `tools.exec` را برای آن agent override میکند. برای اجبار یک حالت متفاوت Claude، raw backend args صریحی مانند `--permission-mode default` یا `--permission-mode acceptEdits` را زیر
|
||||
`agents.defaults.cliBackends.claude-cli.args` و `resumeArgs` متناظر تنظیم کنید.
|
||||
|
||||
پیش از اینکه OpenClaw بتواند از backend بستهبندیشده `claude-cli` استفاده کند، خود Claude Code
|
||||
باید از قبل روی همان میزبان وارد شده باشد:
|
||||
backend همراه Anthropic یعنی `claude-cli` همچنین سطحهای `/think` در OpenClaw را برای سطحهای غیر off به فلگ بومی `--effort` در Claude Code نگاشت میکند. `minimal` و
|
||||
`low` به `low` نگاشت میشوند، `adaptive` و `medium` به `medium` نگاشت میشوند، و `high`،
|
||||
`xhigh`، و `max` مستقیماً نگاشت میشوند. دیگر backendهای CLI نیاز دارند Plugin مالکشان یک argv mapper معادل اعلام کند تا `/think` بتواند روی CLI ایجادشده اثر بگذارد.
|
||||
|
||||
پیش از اینکه OpenClaw بتواند از backend همراه `claude-cli` استفاده کند، خود Claude Code
|
||||
باید از قبل روی همان میزبان login شده باشد:
|
||||
|
||||
```bash
|
||||
claude auth login
|
||||
@ -194,67 +181,55 @@ openclaw models auth login --provider anthropic --method cli --set-default
|
||||
```
|
||||
|
||||
فقط زمانی از `agents.defaults.cliBackends.claude-cli.command` استفاده کنید که binary مربوط به `claude`
|
||||
از قبل روی `PATH` نباشد.
|
||||
از قبل در `PATH` نباشد.
|
||||
|
||||
## Sessionها
|
||||
|
||||
- اگر CLI از sessionها پشتیبانی میکند، `sessionArg` (مثلاً `--session-id`) یا
|
||||
`sessionArgs` (placeholder `{sessionId}`) را زمانی تنظیم کنید که ID باید در
|
||||
چند flag درج شود.
|
||||
- اگر CLI از sessionها پشتیبانی میکند، `sessionArg` را تنظیم کنید (مثلاً `--session-id`) یا
|
||||
`sessionArgs` را (placeholder `{sessionId}`) وقتی ID باید در چند flag درج شود.
|
||||
- اگر CLI از یک **resume subcommand** با flagهای متفاوت استفاده میکند،
|
||||
`resumeArgs` را تنظیم کنید (هنگام resume جایگزین `args` میشود) و در صورت نیاز `resumeOutput`
|
||||
را هم تنظیم کنید (برای resumeهای غیر JSON).
|
||||
- `sessionMode`:
|
||||
- `always`: همیشه یک session id بفرستد (اگر چیزی ذخیره نشده باشد UUID جدید).
|
||||
- `existing`: فقط اگر قبلاً session id ذخیره شده باشد، آن را بفرستد.
|
||||
- `none`: هرگز session id نفرستد.
|
||||
- `claude-cli` بهطور پیشفرض روی `liveSession: "claude-stdio"`، `output: "jsonl"`،
|
||||
و `input: "stdin"` تنظیم است، تا نوبتهای بعدی تا وقتی فرایند زنده Claude فعال است
|
||||
آن را دوباره استفاده کنند. stdio گرم اکنون پیشفرض است، حتی برای configهای سفارشی
|
||||
که فیلدهای transport را حذف کردهاند. اگر Gateway restart شود یا فرایند idle
|
||||
خارج شود، OpenClaw از session id ذخیرهشده Claude ادامه میدهد. session
|
||||
idهای ذخیرهشده پیش از resume در برابر یک transcript پروژه موجود و خواندنی
|
||||
تأیید میشوند، بنابراین bindingهای phantom با `reason=transcript-missing`
|
||||
پاک میشوند بهجای اینکه بیصدا یک session تازه Claude CLI زیر `--resume` شروع شود.
|
||||
- `always`: همیشه یک session id بفرست (اگر ذخیره نشده باشد، UUID جدید).
|
||||
- `existing`: فقط اگر قبلاً ذخیره شده باشد، session id بفرست.
|
||||
- `none`: هرگز session id نفرست.
|
||||
- `claude-cli` بهصورت پیشفرض روی `liveSession: "claude-stdio"`، `output: "jsonl"`،
|
||||
و `input: "stdin"` تنظیم شده تا نوبتهای پیگیری تا وقتی فعال است همان فرایند زنده Claude را دوباره استفاده کنند. اکنون stdio گرم پیشفرض است، حتی برای configهای سفارشی که فیلدهای transport را حذف میکنند. اگر Gateway restart شود یا فرایند idle خارج شود، OpenClaw از session id ذخیرهشده Claude ادامه میدهد. session idهای ذخیرهشده پیش از resume در برابر transcript پروژه موجود و خواندنی بررسی میشوند، بنابراین bindingهای phantom با `reason=transcript-missing` پاک میشوند، بهجای اینکه بیصدا یک session تازه Claude CLI زیر `--resume` شروع شود.
|
||||
- sessionهای زنده Claude محافظهای محدودکننده خروجی JSONL دارند. پیشفرضها تا
|
||||
8 MiB و 20,000 خط خام JSONL در هر turn را مجاز میکنند. turnهای Claude با ابزارهای زیاد میتوانند
|
||||
آنها را برای هر backend با
|
||||
8 MiB و 20,000 خط خام JSONL برای هر نوبت اجازه میدهند. نوبتهای Claude با tool زیاد میتوانند آنها را برای هر backend با
|
||||
`agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars`
|
||||
و `maxTurnLines` افزایش دهند؛ OpenClaw این تنظیمات را به 64 MiB و 100,000
|
||||
و `maxTurnLines` بالا ببرند؛ OpenClaw این تنظیمات را به 64 MiB و 100,000
|
||||
خط محدود میکند.
|
||||
- sessionهای ذخیرهشده CLI تداومِ متعلق به provider هستند. reset ضمنی روزانه session
|
||||
- sessionهای CLI ذخیرهشده تداومِ مالکیتشده توسط provider هستند. reset ضمنی روزانه session
|
||||
آنها را قطع نمیکند؛ `/reset` و policyهای صریح `session.reset` همچنان
|
||||
این کار را انجام میدهند.
|
||||
|
||||
نکتههای serialization:
|
||||
نکات serialization:
|
||||
|
||||
- `serialize: true` اجراهای همان lane را مرتب نگه میدارد.
|
||||
- بیشتر CLIها روی یک lane مربوط به provider serialize میشوند.
|
||||
- OpenClaw استفاده دوباره از session ذخیرهشده CLI را وقتی identity احراز هویت انتخابشده تغییر کند کنار میگذارد،
|
||||
از جمله تغییر auth profile id، static API key، static token، یا identity حساب OAuth
|
||||
وقتی CLI آن را expose کند. چرخش access token و refresh token در OAuth
|
||||
session ذخیرهشده CLI را قطع نمیکند. اگر یک CLI یک OAuth account id
|
||||
پایدار expose نکند، OpenClaw اجازه میدهد همان CLI مجوزهای resume را enforce کند.
|
||||
- `serialize: true` اجراهای همlane را مرتب نگه میدارد.
|
||||
- بیشتر CLIها روی یک lane ارائهدهنده serialize میشوند.
|
||||
- وقتی هویت auth انتخابشده تغییر کند، OpenClaw استفاده دوباره از session ذخیرهشده CLI را کنار میگذارد،
|
||||
از جمله auth profile id تغییرکرده، static API key، static token، یا هویت account در OAuth
|
||||
وقتی CLI یکی را expose کند. چرخش OAuth access و refresh token
|
||||
session ذخیرهشده CLI را قطع نمیکند. اگر یک CLI شناسه پایدار account در OAuth
|
||||
expose نکند، OpenClaw اجازه میدهد همان CLI مجوزهای resume را enforce کند.
|
||||
|
||||
## پیشدرآمد fallback از sessionهای claude-cli
|
||||
|
||||
وقتی یک تلاش `claude-cli` به یک candidate غیر CLI در
|
||||
[`agents.defaults.model.fallbacks`](/fa/concepts/model-failover) fail over میکند، OpenClaw
|
||||
تلاش بعدی را با یک context prelude که از transcript محلی JSONL در Claude Code
|
||||
در `~/.claude/projects/` برداشت شده seed میکند. بدون این seed، ارائهدهنده fallback
|
||||
از صفر شروع میکرد، چون transcript session خود OpenClaw برای اجراهای `claude-cli`
|
||||
خالی است.
|
||||
تلاش بعدی را با یک پیشدرآمد زمینهای seed میکند که از transcript محلی JSONL در Claude Code
|
||||
در `~/.claude/projects/` برداشت شده است. بدون این seed، ارائهدهنده fallback
|
||||
سرد شروع میکرد چون transcript session خود OpenClaw برای اجراهای `claude-cli` خالی است.
|
||||
|
||||
- prelude آخرین summary مربوط به `/compact` یا marker مربوط به `compact_boundary` را ترجیح میدهد،
|
||||
سپس جدیدترین turnهای پس از boundary را تا سقف بودجه char اضافه میکند.
|
||||
turnهای پیش از boundary حذف میشوند، چون summary از قبل نماینده آنهاست.
|
||||
- بلوکهای tool به hintهای فشرده `(tool call: name)` و
|
||||
`(tool result: …)` ادغام میشوند تا بودجه prompt واقعگرایانه بماند. اگر summary
|
||||
از سقف عبور کند با `(truncated)` برچسب میخورد.
|
||||
- fallbackهای `claude-cli` به `claude-cli` در همان provider به
|
||||
`--resume` خود Claude تکیه میکنند و prelude را رد میکنند.
|
||||
- seed همان validation مسیر فایل session در Claude موجود را دوباره استفاده میکند، بنابراین
|
||||
مسیرهای دلخواه قابل خواندن نیستند.
|
||||
سپس تازهترین نوبتهای پس از boundary را تا سقف بودجه char اضافه میکند. نوبتهای پیش از boundary حذف میشوند چون summary از قبل نماینده آنهاست.
|
||||
- blockهای tool به hintهای فشرده `(tool call: name)` و
|
||||
`(tool result: …)` ادغام میشوند تا بودجه prompt واقعی بماند. اگر summary سرریز شود با
|
||||
`(truncated)` برچسبگذاری میشود.
|
||||
- fallbackهای همارائهدهنده از `claude-cli` به `claude-cli` به `--resume` خود Claude متکی هستند و prelude را رد میکنند.
|
||||
- این seed همان اعتبارسنجی موجود مسیر session-file در Claude را دوباره استفاده میکند، بنابراین مسیرهای arbitrary نمیتوانند خوانده شوند.
|
||||
|
||||
## تصاویر (عبور مستقیم)
|
||||
|
||||
@ -265,29 +240,25 @@ imageArg: "--image",
|
||||
imageMode: "repeat"
|
||||
```
|
||||
|
||||
OpenClaw تصاویر base64 را در فایلهای temp مینویسد. اگر `imageArg` تنظیم شده باشد، آن
|
||||
مسیرها بهعنوان argهای CLI فرستاده میشوند. اگر `imageArg` وجود نداشته باشد، OpenClaw
|
||||
مسیرهای فایل را به prompt اضافه میکند (path injection)، که برای CLIهایی که بهصورت خودکار
|
||||
فایلهای local را از مسیرهای ساده بارگذاری میکنند کافی است.
|
||||
OpenClaw تصاویر base64 را در فایلهای temp مینویسد. اگر `imageArg` تنظیم شده باشد، آن مسیرها بهعنوان args به CLI پاس داده میشوند. اگر `imageArg` وجود نداشته باشد، OpenClaw مسیرهای فایل را به prompt اضافه میکند (path injection)، که برای CLIهایی که فایلهای محلی را بهصورت خودکار از مسیرهای ساده بارگذاری میکنند کافی است.
|
||||
|
||||
## ورودیها / خروجیها
|
||||
|
||||
- `output: "json"` (پیشفرض) تلاش میکند JSON را parse کند و متن + session id را استخراج کند.
|
||||
- برای خروجی JSON در Gemini CLI، OpenClaw متن پاسخ را از `response` و
|
||||
usage را از `stats` وقتی `usage` وجود ندارد یا خالی است میخواند.
|
||||
- `output: "jsonl"` جریانهای JSONL را parse میکند (برای مثال Codex CLI `--json`) و پیام نهایی agent بههمراه شناسههای session
|
||||
را در صورت وجود استخراج میکند.
|
||||
- برای خروجی JSON در Gemini CLI، وقتی `usage` وجود ندارد یا خالی است، OpenClaw متن پاسخ را از `response` و
|
||||
usage را از `stats` میخواند.
|
||||
- `output: "jsonl"` استریمهای JSONL را parse میکند (برای مثال Codex CLI `--json`) و پیام نهایی agent بهعلاوه شناسههای session را در صورت وجود استخراج میکند.
|
||||
- `output: "text"` stdout را پاسخ نهایی در نظر میگیرد.
|
||||
|
||||
modeهای ورودی:
|
||||
حالتهای ورودی:
|
||||
|
||||
- `input: "arg"` (پیشفرض) prompt را بهعنوان آخرین arg در CLI عبور میدهد.
|
||||
- `input: "arg"` (پیشفرض) prompt را بهعنوان آخرین arg در CLI پاس میدهد.
|
||||
- `input: "stdin"` prompt را از طریق stdin میفرستد.
|
||||
- اگر prompt بسیار طولانی باشد و `maxPromptArgChars` تنظیم شده باشد، از stdin استفاده میشود.
|
||||
|
||||
## پیشفرضها (متعلق به Plugin)
|
||||
## پیشفرضها (مالکیتشده توسط Plugin)
|
||||
|
||||
Plugin بستهبندیشده OpenAI همچنین یک پیشفرض برای `codex-cli` ثبت میکند:
|
||||
Plugin همراه OpenAI همچنین یک پیشفرض برای `codex-cli` ثبت میکند:
|
||||
|
||||
- `command: "codex"`
|
||||
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
|
||||
@ -298,7 +269,7 @@ Plugin بستهبندیشده OpenAI همچنین یک پیشفرض ب
|
||||
- `imageArg: "--image"`
|
||||
- `sessionMode: "existing"`
|
||||
|
||||
Plugin بستهبندیشده Google نیز یک پیشفرض برای `google-gemini-cli` ثبت میکند:
|
||||
Plugin همراه Google نیز یک پیشفرض برای `google-gemini-cli` ثبت میکند:
|
||||
|
||||
- `command: "gemini"`
|
||||
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
|
||||
@ -309,32 +280,32 @@ Plugin بستهبندیشده Google نیز یک پیشفرض برای
|
||||
- `sessionMode: "existing"`
|
||||
- `sessionIdFields: ["session_id", "sessionId"]`
|
||||
|
||||
پیشنیاز: Gemini CLI محلی باید نصب باشد و بهعنوان
|
||||
پیشنیاز: Gemini CLI محلی باید نصب شده و بهصورت
|
||||
`gemini` روی `PATH` در دسترس باشد (`brew install gemini-cli` یا
|
||||
`npm install -g @google/gemini-cli`).
|
||||
|
||||
نکتههای JSON در Gemini CLI:
|
||||
نکات JSON در Gemini CLI:
|
||||
|
||||
- متن پاسخ از فیلد JSON به نام `response` خوانده میشود.
|
||||
- وقتی `usage` وجود ندارد یا خالی است، usage به `stats` fallback میکند.
|
||||
- `stats.cached` به `cacheRead` در OpenClaw normalize میشود.
|
||||
- اگر `stats.input` وجود نداشته باشد، OpenClaw توکنهای ورودی را از
|
||||
`stats.input_tokens - stats.cached` استخراج میکند.
|
||||
- متن پاسخ از فیلد JSON `response` خوانده میشود.
|
||||
- وقتی `usage` وجود ندارد یا خالی است، مصرف به `stats` برمیگردد.
|
||||
- `stats.cached` به `cacheRead` در OpenClaw نرمالسازی میشود.
|
||||
- اگر `stats.input` موجود نباشد، OpenClaw توکنهای ورودی را از
|
||||
`stats.input_tokens - stats.cached` به دست میآورد.
|
||||
|
||||
فقط در صورت نیاز override کنید (مورد رایج: مسیر absolute برای `command`).
|
||||
فقط در صورت نیاز بازنویسی کنید (رایج: مسیر مطلق `command`).
|
||||
|
||||
## پیشفرضهای متعلق به Plugin
|
||||
|
||||
پیشفرضهای backendهای CLI اکنون بخشی از سطح Plugin هستند:
|
||||
پیشفرضهای backend مربوط به CLI اکنون بخشی از سطح Plugin هستند:
|
||||
|
||||
- Pluginها آنها را با `api.registerCliBackend(...)` ثبت میکنند.
|
||||
- `id` پشتیبان به پیشوند ارائهدهنده در ارجاعهای مدل تبدیل میشود.
|
||||
- `id` مربوط به backend به پیشوند provider در ارجاعهای مدل تبدیل میشود.
|
||||
- پیکربندی کاربر در `agents.defaults.cliBackends.<id>` همچنان پیشفرض Plugin را بازنویسی میکند.
|
||||
- پاکسازی پیکربندی اختصاصی پشتیبان از طریق قلاب اختیاری
|
||||
`normalizeConfig` همچنان در مالکیت Plugin میماند.
|
||||
- پاکسازی پیکربندی ویژهی backend از طریق hook اختیاری
|
||||
`normalizeConfig` همچنان متعلق به Plugin میماند.
|
||||
|
||||
Pluginهایی که به شیمهای کوچک سازگاری پرامپت/پیام نیاز دارند، میتوانند
|
||||
تبدیلهای متنی دوسویه را بدون جایگزینکردن ارائهدهنده یا پشتیبان CLI اعلام کنند:
|
||||
Pluginهایی که به shimهای کوچک سازگاری prompt/message نیاز دارند، میتوانند
|
||||
تبدیلهای متنی دوسویه را بدون جایگزین کردن provider یا backend مربوط به CLI تعریف کنند:
|
||||
|
||||
```typescript
|
||||
api.registerTextTransforms({
|
||||
@ -351,65 +322,65 @@ api.registerTextTransforms({
|
||||
});
|
||||
```
|
||||
|
||||
`input` پرامپت سیستم و پرامپت کاربر ارسالشده به CLI را بازنویسی میکند. `output`
|
||||
دلتاهای دستیارِ استریمشده و متن نهایی تجزیهشده را پیش از آنکه OpenClaw
|
||||
نشانگرهای کنترلی و تحویل کانال خودش را مدیریت کند، بازنویسی میکند.
|
||||
`input`، system prompt و user prompt ارسالشده به CLI را بازنویسی میکند. `output`
|
||||
دلتاهای جاریشوندهی دستیار و متن نهایی تجزیهشده را پیش از آنکه OpenClaw
|
||||
نشانگرهای کنترلی و تحویل به کانال خودش را مدیریت کند، بازنویسی میکند.
|
||||
|
||||
برای CLIهایی که JSONL سازگار با Claude Code stream-json منتشر میکنند،
|
||||
`jsonlDialect: "claude-stream-json"` را در پیکربندی آن پشتیبان تنظیم کنید.
|
||||
برای CLIهایی که JSONL سازگار با Claude Code stream-json تولید میکنند، در پیکربندی همان backend مقدار
|
||||
`jsonlDialect: "claude-stream-json"` را تنظیم کنید.
|
||||
|
||||
## همپوشانیهای MCP بستهای
|
||||
## پوششهای MCP همراه
|
||||
|
||||
پشتیبانهای CLI فراخوانیهای ابزار OpenClaw را بهطور مستقیم دریافت **نمیکنند**، اما یک پشتیبان میتواند
|
||||
با `bundleMcp: true` به همپوشانی پیکربندی MCP تولیدشده بپیوندد.
|
||||
backendهای CLI فراخوانی ابزار OpenClaw را بهطور مستقیم دریافت نمیکنند، اما یک backend میتواند
|
||||
با `bundleMcp: true` از پوشش پیکربندی MCP تولیدشده استفاده کند.
|
||||
|
||||
رفتار بستهای فعلی:
|
||||
رفتار همراه فعلی:
|
||||
|
||||
- `claude-cli`: فایل پیکربندی سختگیرانه MCP تولیدشده
|
||||
- `codex-cli`: بازنویسیهای پیکربندی درونخطی برای `mcp_servers`؛ سرور
|
||||
local loopback تولیدشده OpenClaw با حالت تأیید ابزارِ بهازای هر سرورِ Codex علامتگذاری میشود
|
||||
تا فراخوانیهای MCP نتوانند روی پرامپتهای تأیید محلی متوقف شوند
|
||||
- `claude-cli`: فایل پیکربندی MCP سختگیرانهی تولیدشده
|
||||
- `codex-cli`: بازنویسیهای پیکربندی درونخطی برای `mcp_servers`؛ سرور loopback تولیدشدهی
|
||||
OpenClaw با حالت تأیید ابزارِ هر سرور در Codex علامتگذاری میشود
|
||||
تا فراخوانیهای MCP روی promptهای تأیید محلی متوقف نشوند
|
||||
- `google-gemini-cli`: فایل تنظیمات سیستم Gemini تولیدشده
|
||||
|
||||
وقتی MCP بستهای فعال باشد، OpenClaw:
|
||||
وقتی MCP همراه فعال باشد، OpenClaw:
|
||||
|
||||
- یک سرور HTTP MCP از نوع loopback ایجاد میکند که ابزارهای Gateway را در اختیار فرایند CLI میگذارد
|
||||
- پل را با یک توکن بهازای هر نشست (`OPENCLAW_MCP_TOKEN`) احراز هویت میکند
|
||||
- دسترسی ابزار را به بافت نشست، حساب و کانال فعلی محدود میکند
|
||||
- سرورهای bundle-MCP فعال را برای فضای کاری فعلی بارگذاری میکند
|
||||
- آنها را با هر شکل موجود از پیکربندی/تنظیمات MCP پشتیبان ادغام میکند
|
||||
- پیکربندی اجرا را با استفاده از حالت ادغامِ متعلق به پشتیبان از extension مالک بازنویسی میکند
|
||||
- یک سرور MCP مبتنی بر HTTP loopback راهاندازی میکند که ابزارهای gateway را در اختیار فرایند CLI میگذارد
|
||||
- پل را با یک توکن ویژهی هر نشست (`OPENCLAW_MCP_TOKEN`) احراز هویت میکند
|
||||
- دسترسی ابزار را به نشست، حساب و زمینهی کانال فعلی محدود میکند
|
||||
- سرورهای MCP همراه فعالشده را برای workspace فعلی بارگذاری میکند
|
||||
- آنها را با هر شکل موجود از پیکربندی/تنظیمات MCP مربوط به backend ادغام میکند
|
||||
- پیکربندی اجرا را با استفاده از حالت یکپارچهسازی متعلق به backend از extension مالک بازنویسی میکند
|
||||
|
||||
اگر هیچ سرور MCP فعالی وجود نداشته باشد، OpenClaw همچنان وقتی یک
|
||||
پشتیبان به MCP بستهای بپیوندد، پیکربندی سختگیرانهای تزریق میکند تا اجراهای پسزمینه ایزوله بمانند.
|
||||
backend استفاده از MCP همراه را انتخاب کرده باشد، یک پیکربندی سختگیرانه تزریق میکند تا اجراهای پسزمینه ایزوله بمانند.
|
||||
|
||||
زماناجراهای MCP بستهایِ محدود به نشست برای استفاده دوباره درون یک نشست کش میشوند و سپس
|
||||
پس از `mcp.sessionIdleTtlMs` میلیثانیه زمان بیکاری جمعآوری میشوند (پیشفرض 10
|
||||
دقیقه؛ برای غیرفعالکردن `0` را تنظیم کنید). اجراهای توکار تکمرحلهای مانند پروبهای احراز هویت،
|
||||
تولید slug، و active-memory recall در پایان اجرا درخواست پاکسازی میکنند تا فرزندان stdio
|
||||
و استریمهای Streamable HTTP/SSE فراتر از اجرای جاری زنده نمانند.
|
||||
runtimeهای MCP همراهِ محدود به نشست برای استفادهی دوباره در همان نشست cache میشوند و سپس
|
||||
پس از `mcp.sessionIdleTtlMs` میلیثانیه زمان بیکاری پاکسازی میشوند (پیشفرض ۱۰
|
||||
دقیقه؛ برای غیرفعال کردن `0` را تنظیم کنید). اجراهای تعبیهشدهی یکباره مانند بررسیهای auth،
|
||||
تولید slug و یادآوری active-memory در پایان اجرا درخواست پاکسازی میکنند تا فرزندان stdio
|
||||
و جریانهای Streamable HTTP/SSE پس از اجرا باقی نمانند.
|
||||
|
||||
## محدودیتها
|
||||
|
||||
- **بدون فراخوانی مستقیم ابزار OpenClaw.** OpenClaw فراخوانیهای ابزار را به
|
||||
پروتکل پشتیبان CLI تزریق نمیکند. پشتیبانها فقط وقتی به
|
||||
`bundleMcp: true` بپیوندند، ابزارهای Gateway را میبینند.
|
||||
- **استریمکردن به پشتیبان وابسته است.** برخی پشتیبانها JSONL را استریم میکنند؛ برخی دیگر تا زمان
|
||||
خروج بافر میکنند.
|
||||
- **خروجیهای ساختیافته** به قالب JSON متعلق به CLI وابستهاند.
|
||||
- **نشستهای Codex CLI** از طریق خروجی متنی ادامه پیدا میکنند (بدون JSONL)، که نسبت به اجرای اولیه
|
||||
`--json` ساختار کمتری دارد. نشستهای OpenClaw همچنان
|
||||
بهطور معمول کار میکنند.
|
||||
- **بدون فراخوانی مستقیم ابزار OpenClaw.** OpenClaw فراخوانی ابزار را به
|
||||
پروتکل backend مربوط به CLI تزریق نمیکند. backendها فقط وقتی ابزارهای gateway را میبینند که استفاده از
|
||||
`bundleMcp: true` را انتخاب کرده باشند.
|
||||
- **Streaming وابسته به backend است.** برخی backendها JSONL را stream میکنند؛ برخی دیگر
|
||||
تا زمان خروج، buffer میکنند.
|
||||
- **خروجیهای ساختیافته** به قالب JSON در CLI بستگی دارند.
|
||||
- **نشستهای Codex CLI** از طریق خروجی متنی از سر گرفته میشوند (بدون JSONL)، که نسبت به اجرای اولیهی `--json`
|
||||
ساختار کمتری دارد. نشستهای OpenClaw همچنان
|
||||
بهطور عادی کار میکنند.
|
||||
|
||||
## عیبیابی
|
||||
|
||||
- **CLI پیدا نشد**: `command` را روی یک مسیر کامل تنظیم کنید.
|
||||
- **نام مدل اشتباه است**: از `modelAliases` برای نگاشت `provider/model` → مدل CLI استفاده کنید.
|
||||
- **نبود پیوستگی نشست**: مطمئن شوید `sessionArg` تنظیم شده و `sessionMode`
|
||||
برابر `none` نیست (Codex CLI در حال حاضر نمیتواند با خروجی JSON ادامه دهد).
|
||||
- **نام مدل نادرست**: از `modelAliases` برای نگاشت `provider/model` → مدل CLI استفاده کنید.
|
||||
- **نبود پیوستگی نشست**: مطمئن شوید `sessionArg` تنظیم شده و `sessionMode` برابر
|
||||
`none` نیست (Codex CLI در حال حاضر نمیتواند با خروجی JSON از سر گرفته شود).
|
||||
- **تصاویر نادیده گرفته میشوند**: `imageArg` را تنظیم کنید (و بررسی کنید CLI از مسیرهای فایل پشتیبانی میکند).
|
||||
|
||||
## مرتبط
|
||||
|
||||
- [راهنمای اجرایی Gateway](/fa/gateway)
|
||||
- [راهنمای عملیاتی Gateway](/fa/gateway)
|
||||
- [مدلهای محلی](/fa/gateway/local-models)
|
||||
|
||||
@ -1,30 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- در حال ساخت یک Plugin هستید که به before_tool_call، before_agent_reply، هوکهای پیام یا هوکهای چرخهٔ عمر نیاز دارد
|
||||
- باید فراخوانیهای ابزار از یک Plugin را مسدود کنید، بازنویسی کنید، یا برای آنها تأیید الزامی کنید.
|
||||
- در حال انتخاب بین هوکهای داخلی و هوکهای Plugin هستید
|
||||
summary: 'هوکهای Plugin: رویدادهای چرخهٔ حیات عامل، ابزار، پیام، نشست و Gateway را رهگیری کنید'
|
||||
- شما در حال ساخت یک Plugin هستید که به before_tool_call، before_agent_reply، هوکهای پیام یا هوکهای چرخهٔ حیات نیاز دارد
|
||||
- باید فراخوانیهای ابزار از یک Plugin را مسدود یا بازنویسی کنید، یا برای آنها تأیید لازم بدانید.
|
||||
- در حال تصمیمگیری بین هوکهای داخلی و هوکهای Plugin هستید
|
||||
summary: 'هوکهای Plugin: رویدادهای چرخهٔ عمر عامل، ابزار، پیام، جلسه و Gateway را رهگیری کنید'
|
||||
title: هوکهای Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:38:38Z"
|
||||
generated_at: "2026-05-04T18:23:47Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2c4ed060f1b89917e1f2f46d2da9448cd562edbcd6ce03bc9b1a83da3ed9a591
|
||||
source_hash: 37c7273036463c87e478db5678822b676c89447caee65f2f3f47a45194d1e37b
|
||||
source_path: plugins/hooks.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
هوکهای Plugin نقاط توسعه درونفرایندی برای Pluginهای OpenClaw هستند. از آنها
|
||||
زمانی استفاده کنید که یک Plugin باید اجرای عامل، فراخوانیهای ابزار، جریان پیام،
|
||||
چرخه عمر نشست، مسیریابی زیرعامل، نصبها، یا راهاندازی Gateway را بررسی یا تغییر دهد.
|
||||
هوکهای Plugin نقاط توسعهٔ درونفرآیندی برای Pluginهای OpenClaw هستند. وقتی از آنها استفاده کنید که یک Plugin باید اجرای عاملها، فراخوانی ابزارها، جریان پیام، چرخهٔ عمر نشست، مسیریابی زیرعامل، نصبها، یا راهاندازی Gateway را بررسی یا تغییر دهد.
|
||||
|
||||
در عوض، زمانی از [هوکهای داخلی](/fa/automation/hooks) استفاده کنید که یک اسکریپت
|
||||
کوچک `HOOK.md` نصبشده توسط اپراتور برای رویدادهای فرمان و Gateway مانند
|
||||
`/new`، `/reset`، `/stop`، `agent:bootstrap`، یا `gateway:startup` میخواهید.
|
||||
وقتی یک اسکریپت کوچک `HOOK.md` نصبشده توسط اپراتور برای رویدادهای فرمان و Gateway مانند `/new`، `/reset`، `/stop`، `agent:bootstrap`، یا `gateway:startup` میخواهید، بهجای آن از [هوکهای داخلی](/fa/automation/hooks) استفاده کنید.
|
||||
|
||||
## شروع سریع
|
||||
|
||||
هوکهای Plugin نوعدار را با `api.on(...)` از ورودی Plugin خود ثبت کنید:
|
||||
هوکهای تایپشدهٔ Plugin را با `api.on(...)` از ورودی Plugin خود ثبت کنید:
|
||||
|
||||
```typescript
|
||||
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
@ -56,19 +52,14 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
مدیریتکنندههای هوک بهترتیب نزولی `priority` اجرا میشوند. هوکهایی با اولویت
|
||||
یکسان، ترتیب ثبت را حفظ میکنند.
|
||||
گردانندههای هوک بهترتیب نزولی `priority` اجرا میشوند. هوکهای دارای اولویت یکسان ترتیب ثبت را حفظ میکنند.
|
||||
|
||||
`api.on(name, handler, opts?)` این موارد را میپذیرد:
|
||||
|
||||
- `priority` — ترتیب مدیریتکنندهها (عدد بالاتر زودتر اجرا میشود).
|
||||
- `timeoutMs` — بودجه اختیاری برای هر هوک. وقتی تنظیم شود، اجراکننده هوک آن
|
||||
مدیریتکننده را پس از پایان بودجه لغو میکند و به مورد بعدی ادامه میدهد، بهجای
|
||||
اینکه راهاندازی کند یا کار یادآوری کند بتواند مهلت مدل پیکربندیشده فراخواننده
|
||||
را مصرف کند. آن را حذف کنید تا از مهلت پیشفرض مشاهده/تصمیمگیری استفاده شود که
|
||||
اجراکننده هوک بهصورت عمومی اعمال میکند.
|
||||
- `priority` — ترتیب گردانندهها (مقدار بالاتر زودتر اجرا میشود).
|
||||
- `timeoutMs` — بودجهٔ اختیاری برای هر هوک. وقتی تنظیم شود، اجراکنندهٔ هوک پس از پایان این بودجه آن گرداننده را متوقف میکند و به مورد بعدی ادامه میدهد، بهجای اینکه راهاندازی کند یا کار بازیابی کند و زمانسنج مدل پیکربندیشدهٔ فراخوان را مصرف کند. آن را حذف کنید تا از زمانسنج پیشفرض مشاهده/تصمیم استفاده شود که اجراکنندهٔ هوک بهصورت عمومی اعمال میکند.
|
||||
|
||||
اپراتورها همچنین میتوانند بودجه هوکها را بدون وصلهکردن کد Plugin تنظیم کنند:
|
||||
اپراتورها همچنین میتوانند بدون وصله کردن کد Plugin، بودجههای هوک را تنظیم کنند:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -88,71 +79,62 @@ export default definePluginEntry({
|
||||
}
|
||||
```
|
||||
|
||||
`hooks.timeouts.<hookName>` مقدار `hooks.timeoutMs` را بازنویسی میکند، و آن نیز
|
||||
مقدار نوشتهشده توسط Plugin در `api.on(..., { timeoutMs })` را بازنویسی میکند.
|
||||
هر مقدار پیکربندیشده باید یک عدد صحیح مثبت و حداکثر 600000 میلیثانیه باشد.
|
||||
برای هوکهای کند شناختهشده، بازنویسیهای مخصوص هر هوک را ترجیح دهید تا یک Plugin
|
||||
در همهجا بودجه طولانیتری نگیرد.
|
||||
`hooks.timeouts.<hookName>` مقدار `hooks.timeoutMs` را بازنویسی میکند، و آن نیز مقدار نوشتهشده توسط Plugin در `api.on(..., { timeoutMs })` را بازنویسی میکند. هر مقدار پیکربندیشده باید یک عدد صحیح مثبت و حداکثر 600000 میلیثانیه باشد. برای هوکهای کندِ شناختهشده، بازنویسیهای مختص هر هوک را ترجیح دهید تا یک Plugin همهجا بودجهٔ طولانیتری نگیرد.
|
||||
|
||||
هر هوک `event.context.pluginConfig` را دریافت میکند؛ یعنی پیکربندی حلشده برای
|
||||
Pluginی که آن مدیریتکننده را ثبت کرده است. از آن برای تصمیمهای هوکی استفاده کنید
|
||||
که به گزینههای فعلی Plugin نیاز دارند؛ OpenClaw آن را برای هر مدیریتکننده تزریق
|
||||
میکند بدون اینکه شیء رویداد مشترک دیدهشده توسط Pluginهای دیگر را تغییر دهد.
|
||||
هر هوک `event.context.pluginConfig` را دریافت میکند؛ یعنی پیکربندی حلشده برای Pluginی که آن گرداننده را ثبت کرده است. از آن برای تصمیمهای هوک استفاده کنید که به گزینههای فعلی Plugin نیاز دارند؛ OpenClaw آن را برای هر گرداننده تزریق میکند بدون اینکه شیء رویداد مشترکی را که سایر Pluginها میبینند تغییر دهد.
|
||||
|
||||
## فهرست هوکها
|
||||
|
||||
هوکها بر اساس سطحی که توسعه میدهند گروهبندی شدهاند. نامهای **پررنگ** نتیجه
|
||||
تصمیم را میپذیرند (مسدودسازی، لغو، بازنویسی، یا نیاز به تأیید)؛ همه موارد دیگر
|
||||
فقط برای مشاهده هستند.
|
||||
هوکها بر اساس سطحی که توسعه میدهند گروهبندی شدهاند. نامهای **پررنگ** نتیجهٔ تصمیم میپذیرند (مسدود کردن، لغو کردن، بازنویسی، یا درخواست تأیید)؛ بقیه فقط برای مشاهده هستند.
|
||||
|
||||
**نوبت عامل**
|
||||
|
||||
- `before_model_resolve` — بازنویسی ارائهدهنده یا مدل پیش از بارگذاری پیامهای نشست
|
||||
- `agent_turn_prepare` — مصرف تزریقهای نوبت Plugin در صف و افزودن زمینه همان نوبت پیش از هوکهای پرامپت
|
||||
- `before_prompt_build` — افزودن زمینه پویا یا متن پرامپت سیستمی پیش از فراخوانی مدل
|
||||
- `agent_turn_prepare` — مصرف تزریقهای نوبت Plugin در صف و افزودن زمینهٔ همان نوبت پیش از هوکهای پرامپت
|
||||
- `before_prompt_build` — افزودن زمینهٔ پویا یا متن پرامپت سیستمی پیش از فراخوانی مدل
|
||||
- `before_agent_start` — فاز ترکیبی فقط برای سازگاری؛ دو هوک بالا را ترجیح دهید
|
||||
- **`before_agent_reply`** — میانبُر زدن نوبت مدل با پاسخ مصنوعی یا سکوت
|
||||
- **`before_agent_finalize`** — بررسی پاسخ نهایی طبیعی و درخواست یک گذر مدل دیگر
|
||||
- `agent_end` — مشاهده پیامهای نهایی، وضعیت موفقیت، و مدت اجرای کار
|
||||
- `heartbeat_prompt_contribution` — افزودن زمینه فقط برای Heartbeat برای Pluginهای پایش پسزمینه و چرخه عمر
|
||||
- **`before_agent_reply`** — کوتاهکردن نوبت مدل با یک پاسخ ساختگی یا سکوت
|
||||
- **`before_agent_finalize`** — بررسی پاسخ نهایی طبیعی و درخواست یک گذر دیگر مدل
|
||||
- `agent_end` — مشاهدهٔ پیامهای نهایی، وضعیت موفقیت، و مدت اجرای نوبت
|
||||
- `heartbeat_prompt_contribution` — افزودن زمینهٔ فقط Heartbeat برای Pluginهای پایش پسزمینه و چرخهٔ عمر
|
||||
|
||||
**مشاهده گفتگو**
|
||||
**مشاهدهٔ مکالمه**
|
||||
|
||||
- `model_call_started` / `model_call_ended` — مشاهده فراداده پاکسازیشده فراخوانی ارائهدهنده/مدل، زمانبندی، نتیجه، و هشهای محدود شناسه درخواست بدون محتوای پرامپت یا پاسخ
|
||||
- `llm_input` — مشاهده ورودی ارائهدهنده (پرامپت سیستمی، پرامپت، تاریخچه)
|
||||
- `llm_output` — مشاهده خروجی ارائهدهنده
|
||||
- `model_call_started` / `model_call_ended` — مشاهدهٔ فرادادهٔ پاکسازیشدهٔ فراخوانی ارائهدهنده/مدل، زمانبندی، نتیجه، و هشهای محدود شناسهٔ درخواست بدون محتوای پرامپت یا پاسخ
|
||||
- `llm_input` — مشاهدهٔ ورودی ارائهدهنده (پرامپت سیستمی، پرامپت، تاریخچه)
|
||||
- `llm_output` — مشاهدهٔ خروجی ارائهدهنده
|
||||
|
||||
**ابزارها**
|
||||
|
||||
- **`before_tool_call`** — بازنویسی پارامترهای ابزار، مسدودکردن اجرا، یا نیازمند کردن تأیید
|
||||
- `after_tool_call` — مشاهده نتایج ابزار، خطاها، و مدتزمان
|
||||
- **`tool_result_persist`** — بازنویسی پیام دستیار تولیدشده از نتیجه ابزار
|
||||
- **`before_message_write`** — بررسی یا مسدودکردن نوشتن پیام در حال انجام (نادر)
|
||||
- **`before_tool_call`** — بازنویسی پارامترهای ابزار، مسدود کردن اجرا، یا درخواست تأیید
|
||||
- `after_tool_call` — مشاهدهٔ نتایج ابزار، خطاها، و مدتزمان
|
||||
- **`tool_result_persist`** — بازنویسی پیام دستیار تولیدشده از نتیجهٔ ابزار
|
||||
- **`before_message_write`** — بررسی یا مسدود کردن نوشتن پیام درحالانجام (نادر)
|
||||
|
||||
**پیامها و تحویل**
|
||||
|
||||
- **`inbound_claim`** — مالکیت یک پیام ورودی پیش از مسیریابی عامل (پاسخهای مصنوعی)
|
||||
- `message_received` — مشاهده محتوای ورودی، فرستنده، رشته گفتگو، و فراداده
|
||||
- **`inbound_claim`** — تصاحب یک پیام ورودی پیش از مسیریابی عامل (پاسخهای ساختگی)
|
||||
- `message_received` — مشاهدهٔ محتوای ورودی، فرستنده، رشته، و فراداده
|
||||
- **`message_sending`** — بازنویسی محتوای خروجی یا لغو تحویل
|
||||
- `message_sent` — مشاهده موفقیت یا شکست تحویل خروجی
|
||||
- `message_sent` — مشاهدهٔ موفقیت یا شکست تحویل خروجی
|
||||
- **`before_dispatch`** — بررسی یا بازنویسی یک ارسال خروجی پیش از واگذاری به کانال
|
||||
- **`reply_dispatch`** — مشارکت در خط لوله نهایی ارسال پاسخ
|
||||
- **`reply_dispatch`** — مشارکت در خط لولهٔ نهایی ارسال پاسخ
|
||||
|
||||
**نشستها و Compaction**
|
||||
|
||||
- `session_start` / `session_end` — ردیابی مرزهای چرخه عمر نشست
|
||||
- `session_start` / `session_end` — ردیابی مرزهای چرخهٔ عمر نشست
|
||||
- `before_compaction` / `after_compaction` — مشاهده یا حاشیهنویسی چرخههای Compaction
|
||||
- `before_reset` — مشاهده رویدادهای بازنشانی نشست (`/reset`، بازنشانیهای برنامهای)
|
||||
- `before_reset` — مشاهدهٔ رویدادهای بازنشانی نشست (`/reset`، بازنشانیهای برنامهای)
|
||||
|
||||
**زیرعاملها**
|
||||
|
||||
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — هماهنگکردن مسیریابی زیرعامل و تحویل تکمیل
|
||||
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — هماهنگی مسیریابی زیرعامل و تحویل تکمیل
|
||||
|
||||
**چرخه عمر**
|
||||
**چرخهٔ عمر**
|
||||
|
||||
- `gateway_start` / `gateway_stop` — شروع یا توقف سرویسهای تحت مالکیت Plugin همراه با Gateway
|
||||
- `cron_changed` — مشاهده تغییرات چرخه عمر Cron تحت مالکیت Gateway (افزودهشده، بهروزشده، حذفشده، شروعشده، پایانیافته، زمانبندیشده)
|
||||
- **`before_install`** — بررسی اسکنهای نصب skill یا Plugin و مسدودسازی اختیاری
|
||||
- `gateway_start` / `gateway_stop` — شروع یا توقف سرویسهای متعلق به Plugin همراه با Gateway
|
||||
- `cron_changed` — مشاهدهٔ تغییرات چرخهٔ عمر Cron متعلق به Gateway (افزودهشده، بهروزرسانیشده، حذفشده، شروعشده، پایانیافته، زمانبندیشده)
|
||||
- **`before_install`** — بررسی اسکنهای نصب Skills یا Plugin و در صورت نیاز مسدود کردن
|
||||
|
||||
## سیاست فراخوانی ابزار
|
||||
|
||||
@ -162,11 +144,9 @@ Pluginی که آن مدیریتکننده را ثبت کرده است. از
|
||||
- `event.params`
|
||||
- `event.runId` اختیاری
|
||||
- `event.toolCallId` اختیاری
|
||||
- فیلدهای زمینه مانند `ctx.agentId`، `ctx.sessionKey`، `ctx.sessionId`،
|
||||
`ctx.runId`، `ctx.jobId` (روی اجراهای مبتنی بر Cron تنظیم میشود)، و
|
||||
`ctx.trace` تشخیصی
|
||||
- فیلدهای زمینه مانند `ctx.agentId`، `ctx.sessionKey`، `ctx.sessionId`، `ctx.runId`، `ctx.jobId` (در اجراهای مبتنی بر Cron تنظیم میشود)، و `ctx.trace` تشخیصی
|
||||
|
||||
میتواند این مورد را برگرداند:
|
||||
میتواند این را برگرداند:
|
||||
|
||||
```typescript
|
||||
type BeforeToolCallResult = {
|
||||
@ -189,91 +169,58 @@ type BeforeToolCallResult = {
|
||||
|
||||
قواعد:
|
||||
|
||||
- `block: true` نهایی است و مدیریتکنندههای با اولویت پایینتر را رد میکند.
|
||||
- `block: true` نهایی است و گردانندههای با اولویت پایینتر را رد میکند.
|
||||
- `block: false` بهعنوان نبود تصمیم در نظر گرفته میشود.
|
||||
- `params` پارامترهای ابزار را برای اجرا بازنویسی میکند.
|
||||
- `requireApproval` اجرای عامل را متوقف میکند و از کاربر از طریق تأییدهای Plugin
|
||||
سؤال میپرسد. فرمان `/approve` میتواند هم تأییدهای exec و هم تأییدهای Plugin را تأیید کند.
|
||||
- یک `block: true` با اولویت پایینتر همچنان میتواند پس از اینکه یک هوک با اولویت
|
||||
بالاتر درخواست تأیید کرد، مسدود کند.
|
||||
- `onResolution` تصمیم تأیید حلشده را دریافت میکند — `allow-once`،
|
||||
`allow-always`، `deny`، `timeout`، یا `cancelled`.
|
||||
- `requireApproval` اجرای عامل را مکث میکند و از طریق تأییدهای Plugin از کاربر میپرسد. فرمان `/approve` میتواند هم تأییدهای exec و هم تأییدهای Plugin را تأیید کند.
|
||||
- یک `block: true` با اولویت پایینتر همچنان میتواند پس از اینکه یک هوک با اولویت بالاتر درخواست تأیید کرده است مسدود کند.
|
||||
- `onResolution` تصمیم تأیید حلشده را دریافت میکند — `allow-once`، `allow-always`، `deny`، `timeout`، یا `cancelled`.
|
||||
|
||||
Pluginهای همراهی که به سیاست سطح میزبان نیاز دارند میتوانند سیاستهای ابزار
|
||||
مورداعتماد را با `api.registerTrustedToolPolicy(...)` ثبت کنند. اینها پیش از
|
||||
هوکهای عادی `before_tool_call` و پیش از تصمیمهای Plugin خارجی اجرا میشوند.
|
||||
فقط برای دروازههای مورداعتماد میزبان مانند سیاست فضای کاری، اعمال بودجه، یا
|
||||
ایمنی گردشکارهای رزروشده از آنها استفاده کنید. Pluginهای خارجی باید از هوکهای
|
||||
عادی `before_tool_call` استفاده کنند.
|
||||
Pluginهای همراه که به سیاست سطح میزبان نیاز دارند میتوانند سیاستهای ابزار مورد اعتماد را با `api.registerTrustedToolPolicy(...)` ثبت کنند. اینها پیش از هوکهای معمولی `before_tool_call` و پیش از تصمیمهای Pluginهای خارجی اجرا میشوند. از آنها فقط برای دروازههای مورد اعتماد میزبان مانند سیاست فضای کاری، اعمال بودجه، یا ایمنی گردشکارهای رزروشده استفاده کنید. Pluginهای خارجی باید از هوکهای عادی `before_tool_call` استفاده کنند.
|
||||
|
||||
### ماندگاری نتیجه ابزار
|
||||
### ماندگارسازی نتیجهٔ ابزار
|
||||
|
||||
نتایج ابزار میتوانند `details` ساختاریافته برای رندر UI، عیبیابی، مسیریابی رسانه،
|
||||
یا فراداده تحت مالکیت Plugin داشته باشند. با `details` بهعنوان فراداده زمان اجرا
|
||||
رفتار کنید، نه محتوای پرامپت:
|
||||
نتایج ابزار میتوانند شامل `details` ساختاریافته برای رندر UI، تشخیص، مسیریابی رسانه، یا فرادادهٔ متعلق به Plugin باشند. با `details` بهعنوان فرادادهٔ زمان اجرا رفتار کنید، نه محتوای پرامپت:
|
||||
|
||||
- OpenClaw پیش از بازپخش ارائهدهنده و ورودی Compaction، `toolResult.details` را
|
||||
حذف میکند تا فراداده به زمینه مدل تبدیل نشود.
|
||||
- ورودیهای نشست ماندگار فقط `details` محدود را نگه میدارند. details بیشازحد
|
||||
بزرگ با خلاصهای فشرده و `persistedDetailsTruncated: true` جایگزین میشوند.
|
||||
- `tool_result_persist` و `before_message_write` پیش از سقف نهایی ماندگاری اجرا
|
||||
میشوند. هوکها همچنان باید `details` برگشتی را کوچک نگه دارند و از قراردادن
|
||||
متن مرتبط با پرامپت فقط در `details` پرهیز کنند؛ خروجی ابزار قابلمشاهده برای
|
||||
مدل را در `content` قرار دهید.
|
||||
- OpenClaw پیش از بازپخش ارائهدهنده و ورودی Compaction، `toolResult.details` را حذف میکند تا فراداده به زمینهٔ مدل تبدیل نشود.
|
||||
- ورودیهای نشست ماندگارشده فقط `details` محدود را نگه میدارند. جزئیات بیشازحد بزرگ با یک خلاصهٔ فشرده و `persistedDetailsTruncated: true` جایگزین میشوند.
|
||||
- `tool_result_persist` و `before_message_write` پیش از سقف نهایی ماندگارسازی اجرا میشوند. هوکها همچنان باید `details` برگشتی را کوچک نگه دارند و از قرار دادن متن مرتبط با پرامپت فقط در `details` پرهیز کنند؛ خروجی ابزار قابل مشاهده برای مدل را در `content` قرار دهید.
|
||||
|
||||
## هوکهای پرامپت و مدل
|
||||
|
||||
برای Pluginهای جدید از هوکهای مخصوص فاز استفاده کنید:
|
||||
برای Pluginهای جدید از هوکهای مختص فاز استفاده کنید:
|
||||
|
||||
- `before_model_resolve`: فقط پرامپت فعلی و فراداده پیوست را دریافت میکند.
|
||||
`providerOverride` یا `modelOverride` برگردانید.
|
||||
- `agent_turn_prepare`: پرامپت فعلی، پیامهای نشست آمادهشده، و هر تزریق صفشده
|
||||
دقیقاً یکبار را که برای این نشست تخلیه شدهاند دریافت میکند. `prependContext`
|
||||
یا `appendContext` برگردانید.
|
||||
- `before_prompt_build`: پرامپت فعلی و پیامهای نشست را دریافت میکند.
|
||||
`prependContext`، `appendContext`، `systemPrompt`،
|
||||
`prependSystemContext`، یا `appendSystemContext` برگردانید.
|
||||
- `heartbeat_prompt_contribution`: فقط برای نوبتهای Heartbeat اجرا میشود و
|
||||
`prependContext` یا `appendContext` برمیگرداند. برای پایشگرهای پسزمینهای
|
||||
در نظر گرفته شده است که باید وضعیت فعلی را بدون تغییر نوبتهای آغازشده توسط
|
||||
کاربر خلاصه کنند.
|
||||
- `before_model_resolve`: فقط پرامپت فعلی و فرادادهٔ پیوست را دریافت میکند. `providerOverride` یا `modelOverride` را برگردانید.
|
||||
- `agent_turn_prepare`: پرامپت فعلی، پیامهای نشست آمادهشده، و هر تزریق صفشدهٔ دقیقاً یکبار مصرفشده برای این نشست را دریافت میکند. `prependContext` یا `appendContext` را برگردانید.
|
||||
- `before_prompt_build`: پرامپت فعلی و پیامهای نشست را دریافت میکند. `prependContext`، `appendContext`، `systemPrompt`، `prependSystemContext`، یا `appendSystemContext` را برگردانید.
|
||||
- `heartbeat_prompt_contribution`: فقط برای نوبتهای Heartbeat اجرا میشود و `prependContext` یا `appendContext` را برمیگرداند. برای پایشگرهای پسزمینهای در نظر گرفته شده است که باید وضعیت فعلی را بدون تغییر دادن نوبتهای آغازشده توسط کاربر خلاصه کنند.
|
||||
|
||||
`before_agent_start` برای سازگاری باقی میماند. هوکهای صریح بالا را ترجیح دهید
|
||||
تا Plugin شما به یک فاز ترکیبی قدیمی وابسته نشود.
|
||||
`before_agent_start` برای سازگاری باقی مانده است. هوکهای صریح بالا را ترجیح دهید تا Plugin شما به یک فاز ترکیبی قدیمی وابسته نباشد.
|
||||
|
||||
`before_agent_start` و `agent_end` زمانی شامل `event.runId` میشوند که OpenClaw
|
||||
بتواند اجرای فعال را شناسایی کند. همان مقدار روی `ctx.runId` نیز در دسترس است.
|
||||
اجراهای مبتنی بر Cron همچنین `ctx.jobId` (شناسه کار Cron مبدأ) را آشکار میکنند
|
||||
تا هوکهای Plugin بتوانند معیارها، اثرات جانبی، یا وضعیت را به یک کار زمانبندیشده
|
||||
خاص محدود کنند.
|
||||
`before_agent_start` و `agent_end` وقتی OpenClaw بتواند اجرای فعال را شناسایی کند، شامل `event.runId` هستند. همان مقدار روی `ctx.runId` نیز در دسترس است. اجراهای مبتنی بر Cron همچنین `ctx.jobId` (شناسهٔ کار Cron مبدأ) را نمایش میدهند تا هوکهای Plugin بتوانند معیارها، اثرات جانبی، یا وضعیت را به یک کار زمانبندیشدهٔ مشخص محدود کنند.
|
||||
|
||||
برای اجراهایی که از کانال سرچشمه میگیرند، `ctx.messageProvider` سطح ارائهدهنده
|
||||
مانند `discord` یا `telegram` است، در حالی که `ctx.channelId` شناسه مقصد گفتگو
|
||||
است وقتی OpenClaw بتواند آن را از کلید نشست یا فراداده تحویل استخراج کند.
|
||||
برای اجراهای منشأگرفته از کانال، `ctx.messageProvider` سطح ارائهدهنده مانند `discord` یا `telegram` است، درحالیکه `ctx.channelId` شناسهٔ هدف مکالمه است، وقتی OpenClaw بتواند آن را از کلید نشست یا فرادادهٔ تحویل استخراج کند.
|
||||
|
||||
`agent_end` یک هوک مشاهده است و پس از نوبت بهصورت fire-and-forget اجرا میشود.
|
||||
اجراکننده هوک مهلت 30 ثانیهای اعمال میکند تا یک Plugin یا نقطه پایانی embedding
|
||||
گیرکرده نتواند promise هوک را برای همیشه معلق بگذارد. مهلت ثبت میشود و OpenClaw
|
||||
ادامه میدهد؛ این کار شبکه تحت مالکیت Plugin را لغو نمیکند مگر اینکه خود Plugin
|
||||
نیز از سیگنال abort خودش استفاده کند.
|
||||
`agent_end` یک هوک مشاهده است و پس از نوبت بهصورت fire-and-forget اجرا میشود. اجراکنندهٔ هوک یک زمانسنج 30 ثانیهای اعمال میکند تا یک Plugin گیرکرده یا endpoint جاسازی نتواند promise هوک را برای همیشه معلق بگذارد. زمانسنج در لاگ ثبت میشود و OpenClaw ادامه میدهد؛ این کار عملیات شبکهٔ متعلق به Plugin را لغو نمیکند مگر اینکه خود Plugin نیز از سیگنال لغو خودش استفاده کند.
|
||||
|
||||
برای دورسنجی فراخوانی ارائهدهنده که نباید پرامپتهای خام، تاریخچه، پاسخها،
|
||||
سرآیندها، بدنههای درخواست، یا شناسههای درخواست ارائهدهنده را دریافت کند، از
|
||||
`model_call_started` و `model_call_ended` استفاده کنید. این هوکها فراداده پایدار
|
||||
مانند `runId`، `callId`، `provider`، `model`، `api`/`transport` اختیاری،
|
||||
`durationMs`/`outcome` پایانی، و `upstreamRequestIdHash` را زمانی شامل میشوند
|
||||
که OpenClaw بتواند یک هش محدود شناسه درخواست ارائهدهنده استخراج کند.
|
||||
برای تلهمتری فراخوانی ارائهدهنده که نباید پرامپتهای خام، تاریخچه، پاسخها، سرآیندها، بدنههای درخواست، یا شناسههای درخواست ارائهدهنده را دریافت کند، از `model_call_started` و `model_call_ended` استفاده کنید. این هوکها شامل فرادادهٔ پایدار مانند `runId`، `callId`، `provider`، `model`، `api`/`transport` اختیاری، `durationMs`/`outcome` پایانی، و `upstreamRequestIdHash` هستند وقتی OpenClaw بتواند یک هش محدود از شناسهٔ درخواست ارائهدهنده استخراج کند.
|
||||
|
||||
`before_agent_finalize` فقط زمانی اجرا میشود که یک harness در آستانه پذیرش پاسخ
|
||||
نهایی طبیعی دستیار باشد. این مسیر لغو `/stop` نیست و وقتی کاربر یک نوبت را abort
|
||||
میکند اجرا نمیشود. برای درخواست یک گذر مدل دیگر پیش از نهاییسازی
|
||||
`{ action: "revise", reason }` را برگردانید، برای اجبار نهاییسازی `{ action:
|
||||
"finalize", reason? }` را برگردانید، یا برای ادامه نتیجهای برنگردانید. هوکهای
|
||||
بومی `Stop` در Codex بهعنوان تصمیمهای `before_agent_finalize` در OpenClaw به
|
||||
این هوک منتقل میشوند.
|
||||
`before_agent_finalize` فقط وقتی اجرا میشود که یک harness در آستانهٔ پذیرش پاسخ نهایی طبیعی دستیار باشد. این مسیر لغو `/stop` نیست و وقتی کاربر یک نوبت را لغو میکند اجرا نمیشود. برای درخواست یک گذر دیگر مدل پیش از نهاییسازی، `{ action: "revise", reason }` را برگردانید؛ برای اجبار نهاییسازی، `{ action:
|
||||
"finalize", reason? }` را برگردانید؛ یا برای ادامه، نتیجهای حذف کنید. هوکهای native `Stop` در Codex بهعنوان تصمیمهای `before_agent_finalize` در OpenClaw به این هوک منتقل میشوند.
|
||||
|
||||
Pluginهای غیرهمراهی که به `llm_input`، `llm_output`،
|
||||
`before_agent_finalize`، یا `agent_end` نیاز دارند باید این را تنظیم کنند:
|
||||
هنگام برگرداندن `action: "revise"`، Pluginها میتوانند فرادادهٔ `retry` را اضافه کنند تا گذر اضافی مدل محدود و برای بازپخش ایمن باشد:
|
||||
|
||||
```typescript
|
||||
type BeforeAgentFinalizeRetry = {
|
||||
instruction: string;
|
||||
idempotencyKey?: string;
|
||||
maxAttempts?: number;
|
||||
};
|
||||
```
|
||||
|
||||
`instruction` به دلیل بازبینی ارسالشده به harness افزوده میشود. `idempotencyKey` به میزبان اجازه میدهد تلاشهای دوباره را برای همان درخواست Plugin در تصمیمهای نهاییسازی معادل بشمارد، و `maxAttempts` سقف تعداد گذرهای اضافی را تعیین میکند که میزبان پیش از ادامه با پاسخ نهایی طبیعی اجازه خواهد داد.
|
||||
|
||||
Pluginهای غیرهمراه که به `llm_input`، `llm_output`، `before_agent_finalize`، یا `agent_end` نیاز دارند باید این را تنظیم کنند:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -289,32 +236,48 @@ Pluginهای غیرهمراهی که به `llm_input`، `llm_output`،
|
||||
}
|
||||
```
|
||||
|
||||
هوکهای تغییردهنده پرامپت و تزریقهای ماندگار نوبت بعدی را میتوان برای هر Plugin
|
||||
با `plugins.entries.<id>.hooks.allowPromptInjection=false` غیرفعال کرد.
|
||||
هوکهای تغییردهندهٔ پرامپت و تزریقهای بادوام نوبت بعدی را میتوان برای هر Plugin با `plugins.entries.<id>.hooks.allowPromptInjection=false` غیرفعال کرد.
|
||||
|
||||
### افزونههای نشست و تزریقهای نوبت بعدی
|
||||
|
||||
Pluginهای گردشکار میتوانند وضعیت نشست کوچک سازگار با JSON را با
|
||||
`api.registerSessionExtension(...)` ماندگار کنند و آن را از طریق متد Gateway
|
||||
`sessions.pluginPatch` بهروزرسانی کنند. ردیفهای نشست، وضعیت افزونه ثبتشده را
|
||||
از طریق `pluginExtensions` نمایش میدهند و به Control UI و دیگر کلاینتها اجازه
|
||||
میدهند وضعیت تحت مالکیت Plugin را بدون شناخت داخلیات Plugin رندر کنند.
|
||||
Pluginهای گردش کار میتوانند وضعیت نشست کوچکِ سازگار با JSON را با
|
||||
`api.registerSessionExtension(...)` پایدار کنند و آن را از طریق متد
|
||||
`sessions.pluginPatch` در Gateway بهروزرسانی کنند. ردیفهای نشست، وضعیت افزونهٔ ثبتشده را
|
||||
از طریق `pluginExtensions` نمایش میدهند و به رابط کاربری کنترل و دیگر کلاینتها اجازه میدهند
|
||||
وضعیت متعلق به Plugin را بدون دانستن جزئیات داخلی Plugin رندر کنند.
|
||||
|
||||
از `api.enqueueNextTurnInjection(...)` زمانی استفاده کنید که یک Plugin به زمینهٔ پایدار نیاز دارد تا دقیقاً یکبار به نوبت بعدی مدل برسد. OpenClaw تزریقهای صفشده را پیش از قلابهای پرامپت تخلیه میکند، تزریقهای منقضیشده را کنار میگذارد، و بر اساس `idempotencyKey` برای هر Plugin موارد تکراری را حذف میکند. این درز مناسب برای ازسرگیریهای تأیید، خلاصههای سیاست، دلتاهای پایش پسزمینه، و ادامههای فرمان است که باید در نوبت بعدی برای مدل قابل مشاهده باشند اما نباید به متن دائمی پرامپت سیستم تبدیل شوند.
|
||||
وقتی یک Plugin نیاز دارد زمینهٔ پایدار دقیقاً یکبار به نوبت بعدی مدل برسد، از
|
||||
`api.enqueueNextTurnInjection(...)` استفاده کنید. OpenClaw تزریقهای صفشده را پیش از
|
||||
قلابهای پرامپت تخلیه میکند، تزریقهای منقضیشده را حذف میکند، و بر اساس `idempotencyKey`
|
||||
برای هر Plugin موارد تکراری را حذف میکند. این درز مناسب برای ادامهٔ تاییدها، خلاصههای سیاست،
|
||||
دلتاهای پایشگر پسزمینه، و ادامههای دستور است که باید در نوبت بعدی برای مدل قابل مشاهده باشند
|
||||
اما نباید به متن دائمی پرامپت سیستم تبدیل شوند.
|
||||
|
||||
معناشناسی پاکسازی بخشی از قرارداد است. پاکسازی افزونهٔ نشست و فراخوانهای پاکسازی چرخهٔ حیات زمان اجرا، `reset`، `delete`، `disable`، یا `restart` را دریافت میکنند. میزبان، وضعیت پایدار افزونهٔ نشست متعلق به Plugin و تزریقهای معلق نوبت بعدی را برای reset/delete/disable حذف میکند؛ restart وضعیت پایدار نشست را نگه میدارد، در حالی که فراخوانهای پاکسازی به Pluginها اجازه میدهند کارهای زمانبند، زمینهٔ اجرا، و دیگر منابع خارج از باند مربوط به نسل قدیمی زمان اجرا را آزاد کنند.
|
||||
معناشناسی پاکسازی بخشی از قرارداد است. پاکسازی افزونهٔ نشست و
|
||||
کالبکهای پاکسازی چرخهٔ عمر زمان اجرا، `reset`، `delete`، `disable`، یا
|
||||
`restart` را دریافت میکنند. میزبان، وضعیت پایدار افزونهٔ نشست متعلق به Plugin و
|
||||
تزریقهای معلق نوبت بعدی را برای reset/delete/disable حذف میکند؛ restart
|
||||
وضعیت پایدار نشست را نگه میدارد، در حالی که کالبکهای پاکسازی به Pluginها اجازه میدهند
|
||||
کارهای زمانبند، زمینهٔ اجرا، و دیگر منابع خارج از باند را برای نسل قدیمی زمان اجرا آزاد کنند.
|
||||
|
||||
## قلابهای پیام
|
||||
|
||||
از قلابهای پیام برای مسیریابی و سیاست تحویل در سطح کانال استفاده کنید:
|
||||
|
||||
- `message_received`: محتوای ورودی، فرستنده، `threadId`، `messageId`، `senderId`، همبستگی اختیاری اجرا/نشست، و فراداده را مشاهده میکند.
|
||||
- `message_sending`: `content` را بازنویسی میکند یا `{ cancel: true }` برمیگرداند.
|
||||
- `message_sent`: موفقیت یا شکست نهایی را مشاهده میکند.
|
||||
- `message_received`: محتوای ورودی، فرستنده، `threadId`، `messageId`،
|
||||
`senderId`، همبستگی اختیاری اجرا/نشست، و فراداده را مشاهده کنید.
|
||||
- `message_sending`: `content` را بازنویسی کنید یا `{ cancel: true }` برگردانید.
|
||||
- `message_sent`: موفقیت یا شکست نهایی را مشاهده کنید.
|
||||
|
||||
برای پاسخهای TTS فقط-صوتی، `content` میتواند شامل رونوشت گفتاری پنهان باشد، حتی زمانی که payload کانال هیچ متن/زیرنویس قابل مشاهدهای ندارد. بازنویسی آن `content` فقط رونوشت قابل مشاهده برای قلاب را بهروزرسانی میکند؛ این متن بهعنوان زیرنویس رسانه رندر نمیشود.
|
||||
برای پاسخهای TTS فقط صوتی، `content` ممکن است شامل رونوشت گفتاری پنهان باشد
|
||||
حتی وقتی payload کانال متن/زیرنویس قابل مشاهدهای ندارد. بازنویسی آن
|
||||
`content` فقط رونوشت قابل مشاهده برای قلاب را بهروزرسانی میکند؛ بهعنوان
|
||||
زیرنویس رسانه رندر نمیشود.
|
||||
|
||||
زمینههای قلاب پیام، در صورت در دسترس بودن، فیلدهای همبستگی پایدار را آشکار میکنند: `ctx.sessionKey`، `ctx.runId`، `ctx.messageId`، `ctx.senderId`، `ctx.trace`، `ctx.traceId`، `ctx.spanId`، `ctx.parentSpanId`، و `ctx.callDepth`. پیش از خواندن فرادادهٔ قدیمی، این فیلدهای درجهاول را ترجیح دهید.
|
||||
زمینههای قلاب پیام، وقتی در دسترس باشند، فیلدهای همبستگی پایدار را ارائه میکنند:
|
||||
`ctx.sessionKey`، `ctx.runId`، `ctx.messageId`، `ctx.senderId`، `ctx.trace`،
|
||||
`ctx.traceId`، `ctx.spanId`، `ctx.parentSpanId`، و `ctx.callDepth`. پیش از خواندن
|
||||
فرادادهٔ قدیمی، این فیلدهای درجهاول را ترجیح دهید.
|
||||
|
||||
پیش از استفاده از فرادادهٔ اختصاصی کانال، فیلدهای تایپشدهٔ `threadId` و `replyToId` را ترجیح دهید.
|
||||
|
||||
@ -322,38 +285,57 @@ Pluginهای گردشکار میتوانند وضعیت نشست کوچک
|
||||
|
||||
- `message_sending` با `cancel: true` نهایی است.
|
||||
- `message_sending` با `cancel: false` بهعنوان نبود تصمیم در نظر گرفته میشود.
|
||||
- `content` بازنویسیشده به قلابهای با اولویت پایینتر ادامه مییابد، مگر اینکه قلابی بعدی تحویل را لغو کند.
|
||||
- `content` بازنویسیشده به قلابهای با اولویت پایینتر ادامه میدهد، مگر اینکه قلابی بعدی تحویل را لغو کند.
|
||||
|
||||
## قلابهای نصب
|
||||
|
||||
`before_install` پس از اسکن داخلی برای نصب Skills و Plugin اجرا میشود. یافتههای اضافی یا `{ block: true, blockReason }` را برگردانید تا نصب متوقف شود.
|
||||
`before_install` پس از اسکن داخلی برای نصبهای skill و Plugin اجرا میشود.
|
||||
برای توقف نصب، یافتههای اضافی یا `{ block: true, blockReason }` را برگردانید.
|
||||
|
||||
`block: true` نهایی است. `block: false` بهعنوان نبود تصمیم در نظر گرفته میشود.
|
||||
|
||||
## چرخهٔ حیات Gateway
|
||||
## چرخهٔ عمر Gateway
|
||||
|
||||
از `gateway_start` برای سرویسهای Plugin که به وضعیت متعلق به Gateway نیاز دارند استفاده کنید. زمینه، `ctx.config`، `ctx.workspaceDir`، و `ctx.getCron?.()` را برای بازرسی و بهروزرسانیهای cron آشکار میکند. از `gateway_stop` برای پاکسازی منابع بلندمدت استفاده کنید.
|
||||
برای سرویسهای Plugin که به وضعیت متعلق به Gateway نیاز دارند، از `gateway_start` استفاده کنید. زمینه،
|
||||
`ctx.config`، `ctx.workspaceDir`، و `ctx.getCron?.()` را برای بازرسی و بهروزرسانی Cron
|
||||
ارائه میکند. برای پاکسازی منابع طولانیمدت از `gateway_stop` استفاده کنید.
|
||||
|
||||
برای سرویسهای زمان اجرای متعلق به Plugin به قلاب داخلی `gateway:startup` تکیه نکنید.
|
||||
برای سرویسهای زمان اجرای متعلق به Plugin به قلاب داخلی `gateway:startup` متکی نباشید.
|
||||
|
||||
`cron_changed` برای رویدادهای چرخهٔ حیات cron متعلق به gateway با payload رویداد تایپشدهای فعال میشود که دلیلهای `added`، `updated`، `removed`، `started`، `finished`، و `scheduled` را پوشش میدهد. رویداد یک snapshot از `PluginHookGatewayCronJob` را حمل میکند (شامل `state.nextRunAtMs`، `state.lastRunStatus`، و `state.lastError` در صورت وجود) بههمراه یک `PluginHookGatewayCronDeliveryStatus` از `not-requested` | `delivered` | `not-delivered` | `unknown`. رویدادهای حذفشده همچنان snapshot کار حذفشده را حمل میکنند تا زمانبندهای خارجی بتوانند وضعیت را همگام کنند. هنگام همگامسازی زمانبندهای بیدارسازی خارجی، از `ctx.getCron?.()` و `ctx.config` از زمینهٔ زمان اجرا استفاده کنید و OpenClaw را منبع حقیقت برای بررسیهای موعد و اجرا نگه دارید.
|
||||
`cron_changed` برای رویدادهای چرخهٔ عمر Cron متعلق به gateway با payload رویداد تایپشده
|
||||
فعال میشود که دلایل `added`، `updated`، `removed`، `started`، `finished`،
|
||||
و `scheduled` را پوشش میدهد. رویداد، یک snapshot از `PluginHookGatewayCronJob`
|
||||
(شامل `state.nextRunAtMs`، `state.lastRunStatus`، و
|
||||
`state.lastError` در صورت وجود) بههمراه یک `PluginHookGatewayCronDeliveryStatus`
|
||||
از `not-requested` | `delivered` | `not-delivered` | `unknown` حمل میکند. رویدادهای حذفشده
|
||||
همچنان snapshot کار حذفشده را حمل میکنند تا زمانبندهای خارجی بتوانند
|
||||
وضعیت را سازگار کنند. هنگام همگامسازی زمانبندهای بیدارسازی خارجی، از `ctx.getCron?.()` و
|
||||
`ctx.config` در زمینهٔ زمان اجرا استفاده کنید، و OpenClaw را
|
||||
منبع حقیقت برای بررسیهای موعددار و اجرا نگه دارید.
|
||||
|
||||
## منسوخشدنهای آینده
|
||||
## منسوخسازیهای آینده
|
||||
|
||||
چند سطح مجاور قلاب منسوخ شدهاند اما همچنان پشتیبانی میشوند. پیش از انتشار اصلی بعدی مهاجرت کنید:
|
||||
|
||||
- **پاکتهای کانال متن ساده** در handlerهای `inbound_claim` و `message_received`. بهجای تجزیهٔ متن تخت پاکت، `BodyForAgent` و بلوکهای ساختاریافتهٔ زمینهٔ کاربر را بخوانید. ببینید
|
||||
[پاکتهای کانال متن ساده → BodyForAgent](/fa/plugins/sdk-migration#active-deprecations).
|
||||
- **`before_agent_start`** برای سازگاری باقی میماند. Pluginهای جدید باید بهجای فاز ترکیبی از `before_model_resolve` و `before_prompt_build` استفاده کنند.
|
||||
- **`onResolution` در `before_tool_call`** اکنون بهجای یک `string` آزاد، از union تایپشدهٔ `PluginApprovalResolution` استفاده میکند (`allow-once` / `allow-always` / `deny` /
|
||||
- **envelopeهای کانال متن ساده** در handlerهای `inbound_claim` و `message_received`.
|
||||
بهجای parse کردن متن تخت envelope، `BodyForAgent` و بلوکهای ساختاریافتهٔ زمینهٔ کاربر
|
||||
را بخوانید. ببینید
|
||||
[envelopeهای کانال متن ساده → BodyForAgent](/fa/plugins/sdk-migration#active-deprecations).
|
||||
- **`before_agent_start`** برای سازگاری باقی مانده است. Pluginهای جدید باید بهجای فاز
|
||||
ترکیبی، از `before_model_resolve` و `before_prompt_build` استفاده کنند.
|
||||
- **`onResolution` در `before_tool_call`** اکنون بهجای یک `string` آزاد،
|
||||
از union تایپشدهٔ `PluginApprovalResolution` استفاده میکند
|
||||
(`allow-once` / `allow-always` / `deny` /
|
||||
`timeout` / `cancelled`).
|
||||
|
||||
برای فهرست کامل — ثبت قابلیت حافظه، پروفایل تفکر ارائهدهنده، ارائهدهندگان احراز هویت خارجی، انواع کشف ارائهدهنده، دسترسیدهندههای زمان اجرای وظیفه، و تغییر نام `command-auth` به `command-status` — ببینید
|
||||
[مهاجرت Plugin SDK → منسوخشدنهای فعال](/fa/plugins/sdk-migration#active-deprecations).
|
||||
برای فهرست کامل، شامل ثبت قابلیت حافظه، پروفایل تفکر ارائهدهنده،
|
||||
ارائهدهندگان احراز هویت خارجی، انواع کشف ارائهدهنده، accessorهای زمان اجرای وظیفه،
|
||||
و تغییر نام `command-auth` → `command-status`، ببینید
|
||||
[مهاجرت Plugin SDK → منسوخسازیهای فعال](/fa/plugins/sdk-migration#active-deprecations).
|
||||
|
||||
## مرتبط
|
||||
|
||||
- [مهاجرت Plugin SDK](/fa/plugins/sdk-migration) — منسوخشدنهای فعال و زمانبندی حذف
|
||||
- [مهاجرت Plugin SDK](/fa/plugins/sdk-migration) — منسوخسازیهای فعال و جدول زمانی حذف
|
||||
- [ساخت Pluginها](/fa/plugins/building-plugins)
|
||||
- [نمای کلی Plugin SDK](/fa/plugins/sdk-overview)
|
||||
- [نقاط ورود Plugin](/fa/plugins/sdk-entrypoints)
|
||||
|
||||
@ -1,33 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- باید بدانید از کدام زیرمسیر SDK وارد کنید
|
||||
- یک مرجع برای همهٔ متدهای ثبت در OpenClawPluginApi میخواهید
|
||||
- باید بدانید از کدام زیرمسیر SDK واردسازی کنید
|
||||
- به مرجعی برای همهٔ روشهای ثبت در OpenClawPluginApi نیاز دارید
|
||||
- در حال جستوجوی یک خروجی مشخص از SDK هستید
|
||||
sidebarTitle: Plugin SDK overview
|
||||
summary: نقشهٔ واردسازی، مرجع رابط برنامهنویسی کاربردی ثبت، و معماری کیت توسعهٔ نرمافزار
|
||||
title: نمای کلی Plugin SDK
|
||||
summary: نقشهٔ واردسازی، مرجع API ثبت، و معماری SDK
|
||||
title: نمای کلی SDK Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T11:58:34Z"
|
||||
generated_at: "2026-05-04T18:23:57Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: be5fa531e603fb6d87f84e3193ebd61be1431b57b8f284871ae15f34ca93fc69
|
||||
source_hash: 8187e7d4cfb9d6fb19bbdebfbaea0bb4d98fa5cea4742d0f82a765ae5bc60127
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
SDKِ Plugin قرارداد تایپشده میان Pluginها و هسته است. این صفحه مرجع
|
||||
**چیزهایی که باید import کنید** و **چیزهایی که میتوانید ثبت کنید** است.
|
||||
Plugin SDK قرارداد تایپشده بین Pluginها و هسته است. این صفحه مرجع **آنچه باید import کنید** و **آنچه میتوانید ثبت کنید** است.
|
||||
|
||||
<Note>
|
||||
این صفحه برای نویسندگان Plugin است که از `openclaw/plugin-sdk/*` درون
|
||||
این صفحه برای نویسندگان Plugin است که از `openclaw/plugin-sdk/*` داخل
|
||||
OpenClaw استفاده میکنند. برای برنامههای خارجی، اسکریپتها، داشبوردها، کارهای CI و افزونههای IDE
|
||||
که میخواهند agentها را از طریق Gateway اجرا کنند، بهجای آن از
|
||||
[SDK برنامه OpenClaw](/fa/concepts/openclaw-sdk) و بسته `@openclaw/sdk`
|
||||
[OpenClaw App SDK](/fa/concepts/openclaw-sdk) و بسته `@openclaw/sdk`
|
||||
استفاده کنید.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
بهدنبال یک راهنمای عملی هستید؟ از [ساخت Pluginها](/fa/plugins/building-plugins) شروع کنید، برای Pluginهای کانال از [Pluginهای کانال](/fa/plugins/sdk-channel-plugins)، برای Pluginهای provider از [Pluginهای provider](/fa/plugins/sdk-provider-plugins)، و برای Pluginهای هوک ابزار یا چرخه عمر از [هوکهای Plugin](/fa/plugins/hooks) استفاده کنید.
|
||||
بهجای آن دنبال یک راهنمای چگونگی انجام کار هستید؟ با [ساخت Pluginها](/fa/plugins/building-plugins) شروع کنید، برای Pluginهای کانال از [Channel plugins](/fa/plugins/sdk-channel-plugins)، برای Pluginهای provider از [Provider plugins](/fa/plugins/sdk-provider-plugins)، و برای Pluginهای hook ابزار یا چرخه عمر از [Plugin hooks](/fa/plugins/hooks) استفاده کنید.
|
||||
</Tip>
|
||||
|
||||
## قرارداد import
|
||||
@ -39,62 +38,62 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
هر زیرمسیر یک ماژول کوچک و خودبسنده است. این کار راهاندازی را سریع نگه میدارد و
|
||||
از مشکلات وابستگی چرخهای جلوگیری میکند. برای helperهای ورود/ساخت ویژه کانال،
|
||||
هر زیرمسیر یک ماژول کوچک و مستقل است. این کار شروعبهکار را سریع نگه میدارد و
|
||||
از مشکلات وابستگی چرخهای جلوگیری میکند. برای helperهای entry/build ویژه کانال،
|
||||
`openclaw/plugin-sdk/channel-core` را ترجیح دهید؛ `openclaw/plugin-sdk/core` را برای
|
||||
سطح چتری گستردهتر و helperهای مشترک مانند
|
||||
سطح چتری گستردهتر و helperهای مشترکی مانند
|
||||
`buildChannelConfigSchema` نگه دارید.
|
||||
|
||||
برای پیکربندی کانال، JSON Schema متعلق به کانال را از طریق
|
||||
`openclaw.plugin.json#channelConfigs` منتشر کنید. زیرمسیر `plugin-sdk/channel-config-schema`
|
||||
برای primitiveهای schema مشترک و سازنده عمومی است. Pluginهای همراه OpenClaw
|
||||
برای primitiveهای schema مشترک و builder عمومی است. Pluginهای همراه OpenClaw
|
||||
برای schemaهای حفظشده کانالهای همراه از `plugin-sdk/bundled-channel-config-schema` استفاده میکنند.
|
||||
exportهای سازگاری منسوخشده روی
|
||||
`plugin-sdk/channel-config-schema-legacy` باقی میمانند؛ هیچکدام از زیرمسیرهای schema همراه
|
||||
الگویی برای Pluginهای جدید نیستند.
|
||||
exportهای سازگاری منسوخ روی
|
||||
`plugin-sdk/channel-config-schema-legacy` باقی میمانند؛ هیچکدام از زیرمسیرهای schema همراه الگویی
|
||||
برای Pluginهای جدید نیستند.
|
||||
|
||||
<Warning>
|
||||
seamهای convenience دارای برند provider یا کانال را import نکنید (برای مثال
|
||||
`openclaw/plugin-sdk/slack`، `.../discord`، `.../signal`، `.../whatsapp`).
|
||||
Pluginهای همراه، زیرمسیرهای عمومی SDK را در barrelهای `api.ts` /
|
||||
seamهای راحتی با نام provider یا کانال را import نکنید (برای مثال
|
||||
`openclaw/plugin-sdk/slack`، `.../discord`، `.../signal`، `.../whatsapp`).
|
||||
Pluginهای همراه زیرمسیرهای عمومی SDK را داخل barrelهای `api.ts` /
|
||||
`runtime-api.ts` خودشان ترکیب میکنند؛ مصرفکنندگان هسته باید یا از همان barrelهای محلی Plugin
|
||||
استفاده کنند یا وقتی نیاز واقعا
|
||||
میانکانالی است، یک قرارداد عمومی باریک SDK اضافه کنند.
|
||||
استفاده کنند یا وقتی نیاز واقعا میانکانالی است، یک قرارداد عمومی SDK باریک اضافه کنند.
|
||||
|
||||
مجموعه کوچکی از seamهای helper متعلق به Pluginهای همراه همچنان در map خروجی تولیدشده
|
||||
ظاهر میشوند وقتی کاربرد مالک آنها ردیابی شده باشد. آنها فقط برای نگهداری Pluginهای همراه
|
||||
وجود دارند و مسیرهای import توصیهشده برای Pluginهای شخص ثالث جدید نیستند.
|
||||
مجموعه کوچکی از seamهای helper مربوط به Pluginهای همراه، وقتی استفاده مالک پیگیریشده دارند،
|
||||
همچنان در نقشه export تولیدشده ظاهر میشوند. آنها فقط برای نگهداری Pluginهای همراه وجود دارند
|
||||
و مسیرهای import پیشنهادی برای Pluginهای شخص ثالث جدید نیستند.
|
||||
|
||||
`openclaw/plugin-sdk/discord` و `openclaw/plugin-sdk/telegram-account` همچنین
|
||||
بهعنوان facadeهای سازگاری منسوخشده برای کاربرد مالک ردیابیشده نگه داشته شدهاند. این
|
||||
مسیرهای import را در Pluginهای جدید کپی نکنید؛ بهجای آن از helperهای runtime تزریقشده و
|
||||
زیرمسیرهای عمومی SDK کانال استفاده کنید.
|
||||
`openclaw/plugin-sdk/discord` و `openclaw/plugin-sdk/telegram-account` نیز
|
||||
بهعنوان facadeهای سازگاری منسوخ برای استفاده مالک پیگیریشده نگه داشته شدهاند. این مسیرهای import را
|
||||
در Pluginهای جدید کپی نکنید؛ بهجای آن از helperهای runtime تزریقشده و
|
||||
زیرمسیرهای عمومی channel SDK استفاده کنید.
|
||||
</Warning>
|
||||
|
||||
## مرجع زیرمسیر
|
||||
## مرجع زیرمسیرها
|
||||
|
||||
SDKِ Plugin بهصورت مجموعهای از زیرمسیرهای باریک که بر اساس حوزه گروهبندی شدهاند ارائه میشود (ورود Plugin،
|
||||
کانال، provider، احراز هویت، runtime، capability، حافظه، و helperهای رزروشده Pluginهای همراه).
|
||||
برای فهرست کامل، گروهبندیشده و لینکشده، [زیرمسیرهای SDKِ Plugin](/fa/plugins/sdk-subpaths) را ببینید.
|
||||
Plugin SDK بهصورت مجموعهای از زیرمسیرهای باریک ارائه میشود که بر اساس حوزه گروهبندی شدهاند (entry
|
||||
Plugin، کانال، provider، auth، runtime، قابلیت، memory، و helperهای رزروشده
|
||||
Pluginهای همراه). برای فهرست کامل، گروهبندیشده و لینکشده، ببینید
|
||||
[زیرمسیرهای Plugin SDK](/fa/plugins/sdk-subpaths).
|
||||
|
||||
فهرست تولیدشده بیش از ۲۰۰ زیرمسیر در `scripts/lib/plugin-sdk-entrypoints.json` قرار دارد.
|
||||
فهرست تولیدشده بیش از 200 زیرمسیر در `scripts/lib/plugin-sdk-entrypoints.json` قرار دارد.
|
||||
|
||||
## API ثبت
|
||||
|
||||
callbackِ `register(api)` یک شیء `OpenClawPluginApi` با این
|
||||
callback `register(api)` یک شیء `OpenClawPluginApi` با این
|
||||
متدها دریافت میکند:
|
||||
|
||||
### ثبت capability
|
||||
### ثبت قابلیت
|
||||
|
||||
| متد | آنچه ثبت میکند |
|
||||
| ------------------------------------------------ | ------------------------------------- |
|
||||
| `api.registerProvider(...)` | استنتاج متنی (LLM) |
|
||||
| `api.registerAgentHarness(...)` | اجراکننده سطحپایین آزمایشی agent |
|
||||
| `api.registerProvider(...)` | استنتاج متن (LLM) |
|
||||
| `api.registerAgentHarness(...)` | اجراکننده agent سطح پایین آزمایشی |
|
||||
| `api.registerCliBackend(...)` | backend استنتاج CLI محلی |
|
||||
| `api.registerChannel(...)` | کانال پیامرسانی |
|
||||
| `api.registerSpeechProvider(...)` | متنبهگفتار / ساخت STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | رونویسی بلادرنگ streaming |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | نشستهای صدای بلادرنگ دوطرفه |
|
||||
| `api.registerSpeechProvider(...)` | تبدیل متن به گفتار / سنتز STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | رونویسی realtime جریانی |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | نشستهای صدای realtime دوسویه |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | تحلیل تصویر/صدا/ویدئو |
|
||||
| `api.registerImageGenerationProvider(...)` | تولید تصویر |
|
||||
| `api.registerMusicGenerationProvider(...)` | تولید موسیقی |
|
||||
@ -104,94 +103,95 @@ callbackِ `register(api)` یک شیء `OpenClawPluginApi` با این
|
||||
|
||||
### ابزارها و فرمانها
|
||||
|
||||
| متد | آنچه ثبت میکند |
|
||||
| متد | آنچه ثبت میکند |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | ابزار agent (الزامی یا `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | فرمان سفارشی (LLM را دور میزند) |
|
||||
| `api.registerTool(tool, opts?)` | ابزار agent (الزامی یا `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | فرمان سفارشی (LLM را دور میزند) |
|
||||
|
||||
فرمانهای Plugin میتوانند وقتی agent به یک راهنمای کوتاه routing متعلق به فرمان نیاز دارد
|
||||
فرمانهای Plugin میتوانند زمانی که agent به یک راهنمای کوتاه routing متعلق به فرمان نیاز دارد،
|
||||
`agentPromptGuidance` را تنظیم کنند. آن متن را درباره خود فرمان نگه دارید؛
|
||||
سیاست ویژه provider یا Plugin را به سازندههای prompt هسته اضافه نکنید.
|
||||
policy ویژه provider یا Plugin را به سازندههای prompt هسته اضافه نکنید.
|
||||
|
||||
### زیرساخت
|
||||
|
||||
| متد | آنچه ثبت میکند |
|
||||
| متد | آنچه ثبت میکند |
|
||||
| ---------------------------------------------- | --------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | هوک رویداد |
|
||||
| `api.registerHook(events, handler, opts?)` | hook رویداد |
|
||||
| `api.registerHttpRoute(params)` | endpoint HTTP در Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | متد RPC در Gateway |
|
||||
| `api.registerGatewayDiscoveryService(service)` | تبلیغکننده discovery محلی Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | زیرفرمان CLI |
|
||||
| `api.registerGatewayDiscoveryService(service)` | آگهیدهنده کشف Gateway محلی |
|
||||
| `api.registerCli(registrar, opts?)` | زیرفرمان CLI |
|
||||
| `api.registerService(service)` | سرویس پسزمینه |
|
||||
| `api.registerInteractiveHandler(registration)` | handler تعاملی |
|
||||
| `api.registerAgentToolResultMiddleware(...)` | middleware نتیجه ابزار در runtime |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | بخش prompt افزایشی مجاور حافظه |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | corpus افزایشی جستوجو/خواندن حافظه |
|
||||
| `api.registerAgentToolResultMiddleware(...)` | middleware نتیجه ابزار runtime |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | بخش prompt افزایشی مجاور memory |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | corpus افزایشی جستوجو/خواندن memory |
|
||||
|
||||
### هوکهای میزبان برای Pluginهای workflow
|
||||
### hookهای میزبان برای Pluginهای workflow
|
||||
|
||||
هوکهای میزبان، seamهای SDK برای Pluginهایی هستند که باید در چرخه عمر میزبان مشارکت کنند
|
||||
نه اینکه فقط provider، کانال، یا ابزار اضافه کنند. آنها
|
||||
قراردادهای عمومی هستند؛ Plan Mode میتواند از آنها استفاده کند، اما workflowهای تأیید،
|
||||
gateهای سیاست workspace، مانیتورهای پسزمینه، wizardهای راهاندازی، و Pluginهای همراه UI نیز میتوانند.
|
||||
hookهای میزبان seamهای SDK برای Pluginهایی هستند که باید در چرخه عمر میزبان مشارکت کنند،
|
||||
نه اینکه فقط یک provider، کانال، یا ابزار اضافه کنند. آنها
|
||||
قراردادهای عمومی هستند؛ Plan Mode میتواند از آنها استفاده کند، اما workflowهای approval،
|
||||
دروازههای policy workspace، مانیتورهای پسزمینه، wizardهای setup، و Pluginهای همراه UI
|
||||
نیز میتوانند.
|
||||
|
||||
| متد | قراردادی که مالک آن است |
|
||||
| متد | قراردادی که مالک آن است |
|
||||
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerSessionExtension(...)` | state نشست متعلق به Plugin و سازگار با JSON که از طریق نشستهای Gateway project میشود |
|
||||
| `api.enqueueNextTurnInjection(...)` | context پایدار exactly-once که برای یک نشست در نوبت بعدی agent تزریق میشود |
|
||||
| `api.registerTrustedToolPolicy(...)` | سیاست ابزار پیشا-Plugin همراه/مورداعتماد که میتواند پارامترهای ابزار را مسدود یا بازنویسی کند |
|
||||
| `api.registerToolMetadata(...)` | metadata نمایش کاتالوگ ابزار بدون تغییر پیادهسازی ابزار |
|
||||
| `api.registerCommand(...)` | فرمانهای Plugin با دامنه محدود؛ نتایج فرمان میتوانند `continueAgent: true` تنظیم کنند؛ فرمانهای native در Discord از `descriptionLocalizations` پشتیبانی میکنند |
|
||||
| `api.registerControlUiDescriptor(...)` | descriptorهای contribution برای Control UI در سطحهای نشست، ابزار، اجرا، یا تنظیمات |
|
||||
| `api.registerRuntimeLifecycle(...)` | callbackهای پاکسازی برای منابع runtime متعلق به Plugin در مسیرهای reset/delete/reload |
|
||||
| `api.registerAgentEventSubscription(...)` | subscriptionهای رویداد پالایششده برای state workflow و مانیتورها |
|
||||
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | state موقت Plugin برای هر اجرا که در چرخه عمر پایانی اجرا پاک میشود |
|
||||
| `api.registerSessionSchedulerJob(...)` | رکوردهای job زمانبند نشست متعلق به Plugin با پاکسازی قطعی |
|
||||
| `api.registerSessionExtension(...)` | وضعیت session متعلق به Plugin و سازگار با JSON که از طریق sessionهای Gateway بازنمایی میشود |
|
||||
| `api.enqueueNextTurnInjection(...)` | context پایدار دقیقا-یکبار که برای یک session در turn بعدی agent تزریق میشود |
|
||||
| `api.registerTrustedToolPolicy(...)` | policy ابزار پیش از Plugin همراه/قابلاعتماد که میتواند params ابزار را مسدود یا بازنویسی کند |
|
||||
| `api.registerToolMetadata(...)` | metadata نمایشی کاتالوگ ابزار بدون تغییر پیادهسازی ابزار |
|
||||
| `api.registerCommand(...)` | فرمانهای scoped متعلق به Plugin؛ نتایج فرمان میتوانند `continueAgent: true` تنظیم کنند؛ فرمانهای native در Discord از `descriptionLocalizations` پشتیبانی میکنند |
|
||||
| `api.registerControlUiDescriptor(...)` | descriptorهای مشارکت Control UI برای سطحهای session، ابزار، run، یا settings |
|
||||
| `api.registerRuntimeLifecycle(...)` | callbackهای پاکسازی برای منابع runtime متعلق به Plugin در مسیرهای reset/delete/reload |
|
||||
| `api.registerAgentEventSubscription(...)` | subscriptionهای رویداد sanitized برای وضعیت workflow و مانیتورها |
|
||||
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | وضعیت scratch متعلق به Plugin برای هر run که در چرخه عمر پایانی run پاک میشود |
|
||||
| `api.registerSessionSchedulerJob(...)` | رکوردهای job زمانبند session متعلق به Plugin با پاکسازی deterministic |
|
||||
|
||||
قراردادها عمدا اختیار را جدا میکنند:
|
||||
این قراردادها عمدا اختیار را تفکیک میکنند:
|
||||
|
||||
- Pluginهای خارجی میتوانند مالک extensionهای نشست، descriptorهای UI، فرمانها، metadata ابزار،
|
||||
تزریقهای نوبت بعدی، و هوکهای عادی باشند.
|
||||
- سیاستهای ابزار مورداعتماد پیش از هوکهای عادی `before_tool_call` اجرا میشوند و
|
||||
فقط همراه هستند، چون در سیاست ایمنی میزبان مشارکت دارند.
|
||||
- Pluginهای خارجی میتوانند مالک session extensionها، descriptorهای UI، فرمانها، metadata ابزار،
|
||||
تزریقهای turn بعدی، و hookهای عادی باشند.
|
||||
- policyهای ابزار قابلاعتماد پیش از hookهای معمولی `before_tool_call` اجرا میشوند و
|
||||
فقط همراه هستند، چون در policy ایمنی میزبان مشارکت دارند.
|
||||
- مالکیت فرمان رزروشده فقط همراه است. Pluginهای خارجی باید از
|
||||
نامها یا aliasهای فرمان خودشان استفاده کنند.
|
||||
- `allowPromptInjection=false` هوکهای تغییردهنده prompt را غیرفعال میکند، از جمله
|
||||
`agent_turn_prepare`، `before_prompt_build`، `heartbeat_prompt_contribution`،
|
||||
- `allowPromptInjection=false`، hookهای تغییردهنده prompt از جمله
|
||||
`agent_turn_prepare`، `before_prompt_build`، `heartbeat_prompt_contribution`،
|
||||
فیلدهای prompt از `before_agent_start` قدیمی، و
|
||||
`enqueueNextTurnInjection`.
|
||||
`enqueueNextTurnInjection` را غیرفعال میکند.
|
||||
|
||||
نمونههایی از مصرفکنندگان غیر Plan:
|
||||
|
||||
| الگوی Plugin | هوکهای استفادهشده |
|
||||
| الگوی Plugin | hookهای استفادهشده |
|
||||
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| workflow تأیید | extension نشست، ادامه فرمان، تزریق نوبت بعدی، descriptor UI |
|
||||
| gate سیاست بودجه/workspace | سیاست ابزار مورداعتماد، metadata ابزار، projection نشست |
|
||||
| مانیتور چرخه عمر پسزمینه | پاکسازی چرخه عمر runtime، subscription رویداد agent، مالکیت/پاکسازی زمانبند نشست، contribution prompt در Heartbeat، descriptor UI |
|
||||
| wizard راهاندازی یا onboarding | extension نشست، فرمانهای scoped، descriptor در Control UI |
|
||||
| workflow approval | session extension، ادامه فرمان، تزریق turn بعدی، descriptor UI |
|
||||
| دروازه policy بودجه/workspace | policy ابزار قابلاعتماد، metadata ابزار، projection session |
|
||||
| مانیتور چرخه عمر پسزمینه | پاکسازی چرخه عمر runtime، subscription رویداد agent، مالکیت/پاکسازی scheduler session، مشارکت prompt heartbeat، descriptor UI |
|
||||
| wizard setup یا onboarding | session extension، فرمانهای scoped، descriptor در Control UI |
|
||||
|
||||
<Note>
|
||||
namespaceهای مدیریتی رزروشده هسته (`config.*`، `exec.approvals.*`، `wizard.*`،
|
||||
`update.*`) همیشه `operator.admin` میمانند، حتی اگر یک Plugin تلاش کند scope محدودتری برای
|
||||
متد gateway تعیین کند. برای متدهای متعلق به Plugin،
|
||||
namespaceهای ادمین هسته رزروشده (`config.*`، `exec.approvals.*`، `wizard.*`،
|
||||
`update.*`) همیشه `operator.admin` میمانند، حتی اگر یک Plugin تلاش کند
|
||||
scope متد gateway باریکتری اختصاص دهد. برای متدهای متعلق به Plugin،
|
||||
prefixهای ویژه Plugin را ترجیح دهید.
|
||||
</Note>
|
||||
|
||||
<Accordion title="چه زمانی از middleware نتیجه ابزار استفاده کنیم">
|
||||
Pluginهای همراه میتوانند وقتی لازم است پس از اجرا و پیش از اینکه runtime
|
||||
نتیجه را دوباره به مدل بدهد، یک نتیجه ابزار را بازنویسی کنند، از `api.registerAgentToolResultMiddleware(...)` استفاده کنند.
|
||||
این seam مورداعتماد و runtime-neutral برای reducerهای خروجی async مانند tokenjuice است.
|
||||
<Accordion title="چه زمانی از middleware نتیجه ابزار استفاده کنید">
|
||||
Pluginهای همراه میتوانند وقتی لازم است نتیجه ابزار را بعد از اجرا و پیش از اینکه runtime
|
||||
آن نتیجه را به مدل برگرداند بازنویسی کنند، از `api.registerAgentToolResultMiddleware(...)` استفاده کنند.
|
||||
این seam قابلاعتماد و مستقل از runtime برای reducerهای خروجی async مانند tokenjuice است.
|
||||
|
||||
Pluginهای همراه باید برای هر runtime هدف، `contracts.agentToolResultMiddleware` را declare کنند،
|
||||
برای مثال `["pi", "codex"]`. Pluginهای خارجی
|
||||
نمیتوانند این middleware را ثبت کنند؛ برای کاری که به timing نتیجه ابزار پیش از مدل نیاز ندارد،
|
||||
هوکهای عادی Plugin در OpenClaw را نگه دارید. مسیر قدیمی ثبت factory در extension تعبیهشده فقط-Pi
|
||||
Pluginهای همراه باید برای هر runtime هدف،
|
||||
`contracts.agentToolResultMiddleware` را declare کنند، برای مثال `["pi", "codex"]`. Pluginهای خارجی
|
||||
نمیتوانند این middleware را ثبت کنند؛ برای کاری که به زمانبندی نتیجه ابزار پیش از مدل نیاز ندارد،
|
||||
hookهای عادی Plugin در OpenClaw را نگه دارید. مسیر ثبت factory افزونه embedشده قدیمی فقط برای Pi
|
||||
حذف شده است.
|
||||
</Accordion>
|
||||
|
||||
### ثبت discovery در Gateway
|
||||
### ثبت کشف Gateway
|
||||
|
||||
`api.registerGatewayDiscoveryService(...)` به یک Plugin اجازه میدهد Gateway فعال را روی یک انتقال کشف محلی مانند mDNS/Bonjour اعلام کند. OpenClaw هنگام راهاندازی Gateway، وقتی کشف محلی فعال است، این سرویس را فراخوانی میکند، پورتهای فعلی Gateway و دادههای راهنمای TXT غیرمحرمانه را پاس میدهد، و هنگام خاموش شدن Gateway هندلر بازگشتی `stop` را فراخوانی میکند.
|
||||
`api.registerGatewayDiscoveryService(...)` به یک Plugin اجازه میدهد Gateway فعال را روی یک انتقال کشف محلی مانند mDNS/Bonjour اعلام کند. OpenClaw هنگام راهاندازی Gateway و وقتی کشف محلی فعال باشد، این سرویس را فراخوانی میکند، پورتهای Gateway فعلی و دادههای راهنمای TXT غیرمحرمانه را پاس میدهد، و هنگام خاموششدن Gateway هندلر `stop` برگرداندهشده را فراخوانی میکند.
|
||||
|
||||
```typescript
|
||||
api.registerGatewayDiscoveryService({
|
||||
@ -207,19 +207,17 @@ api.registerGatewayDiscoveryService({
|
||||
});
|
||||
```
|
||||
|
||||
Pluginهای کشف Gateway نباید مقدارهای TXT اعلامشده را راز یا احراز هویت تلقی کنند. کشف یک راهنمای مسیریابی است؛ احراز هویت Gateway و سنجاقکردن TLS همچنان مالک اعتماد هستند.
|
||||
Pluginهای کشف Gateway نباید مقادیر TXT اعلامشده را بهعنوان اسرار یا احراز هویت در نظر بگیرند. کشف فقط یک راهنمای مسیریابی است؛ اعتماد همچنان بر عهده احراز هویت Gateway و pinning مربوط به TLS است.
|
||||
|
||||
### فراداده ثبت CLI
|
||||
|
||||
`api.registerCli(registrar, opts?)` دو نوع فراداده سطح بالا را میپذیرد:
|
||||
|
||||
- `commands`: ریشههای فرمان صریح که متعلق به ثبتکننده هستند
|
||||
- `descriptors`: توصیفگرهای فرمان در زمان تجزیه که برای راهنمای CLI ریشه،
|
||||
- `commands`: ریشههای فرمان صریح که در مالکیت ثبتکننده هستند
|
||||
- `descriptors`: توصیفگرهای فرمان در زمان parse که برای راهنمای CLI ریشه،
|
||||
مسیریابی، و ثبت CLI تنبل Plugin استفاده میشوند
|
||||
|
||||
اگر میخواهید یک فرمان Plugin در مسیر عادی CLI ریشه بهصورت تنبل بارگذاری شود،
|
||||
`descriptors` را ارائه کنید که هر ریشه فرمان سطح بالای نمایانشده توسط آن
|
||||
ثبتکننده را پوشش دهد.
|
||||
اگر میخواهید یک فرمان Plugin در مسیر عادی CLI ریشه بهصورت تنبل بارگذاری شود، `descriptors`ای ارائه کنید که هر ریشه فرمان سطح بالایی را که آن ثبتکننده در معرض استفاده قرار میدهد پوشش دهد.
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -239,90 +237,87 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
از `commands` بهتنهایی فقط زمانی استفاده کنید که به ثبت CLI ریشه تنبل نیاز ندارید.
|
||||
آن مسیر سازگاری مشتاق همچنان پشتیبانی میشود، اما جایگیرهای مبتنی بر توصیفگر را
|
||||
برای بارگذاری تنبل در زمان تجزیه نصب نمیکند.
|
||||
فقط زمانی `commands` را بهتنهایی استفاده کنید که به ثبت تنبل CLI ریشه نیاز ندارید. آن مسیر سازگاری eager همچنان پشتیبانی میشود، اما placeholderهای مبتنی بر توصیفگر را برای بارگذاری تنبل در زمان parse نصب نمیکند.
|
||||
|
||||
### ثبت backend CLI
|
||||
|
||||
`api.registerCliBackend(...)` به یک Plugin اجازه میدهد پیکربندی پیشفرض یک backend
|
||||
محلی CLI هوش مصنوعی مانند `codex-cli` را مالک شود.
|
||||
`api.registerCliBackend(...)` به یک Plugin اجازه میدهد پیکربندی پیشفرض یک backend محلی CLI هوش مصنوعی مانند `codex-cli` را مالک شود.
|
||||
|
||||
- `id` مربوط به backend به پیشوند ارائهدهنده در ارجاعهای مدل مانند `codex-cli/gpt-5` تبدیل میشود.
|
||||
- `config` مربوط به backend از همان شکل `agents.defaults.cliBackends.<id>` استفاده میکند.
|
||||
- پیکربندی کاربر همچنان اولویت دارد. OpenClaw پیشفرض Plugin را پیش از اجرای CLI با `agents.defaults.cliBackends.<id>` ادغام میکند.
|
||||
- وقتی یک backend پس از ادغام به بازنویسیهای سازگاری نیاز دارد، از `normalizeConfig` استفاده کنید
|
||||
(برای مثال عادیسازی شکلهای قدیمی پرچم).
|
||||
- `id` مربوط به backend در ارجاعهای مدل مانند `codex-cli/gpt-5` به پیشوند provider تبدیل میشود.
|
||||
- `config` مربوط به backend همان شکل `agents.defaults.cliBackends.<id>` را استفاده میکند.
|
||||
- پیکربندی کاربر همچنان برنده است. OpenClaw پیش از اجرای CLI، `agents.defaults.cliBackends.<id>` را روی پیشفرض Plugin merge میکند.
|
||||
- وقتی یک backend پس از merge به بازنویسیهای سازگاری نیاز دارد، از `normalizeConfig` استفاده کنید
|
||||
(برای مثال عادیسازی شکلهای قدیمی flag).
|
||||
- برای بازنویسیهای argv در محدوده درخواست که به dialect مربوط به CLI تعلق دارند، از `resolveExecutionArgs` استفاده کنید؛ مانند نگاشت سطوح تفکر OpenClaw به یک flag بومی effort.
|
||||
|
||||
### اسلاتهای انحصاری
|
||||
|
||||
| متد | چیزی که ثبت میکند |
|
||||
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | موتور زمینه (هر بار یکی فعال است). callback با نام `assemble()` مقدارهای `availableTools` و `citationsMode` را دریافت میکند تا موتور بتواند افزودنیهای prompt را تنظیم کند. |
|
||||
| `api.registerMemoryCapability(capability)` | قابلیت یکپارچه حافظه |
|
||||
| `api.registerMemoryPromptSection(builder)` | سازنده بخش prompt حافظه |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | حلکننده برنامه تخلیه حافظه |
|
||||
| `api.registerMemoryRuntime(runtime)` | آداپتر زمان اجرای حافظه |
|
||||
| متد | آنچه ثبت میکند |
|
||||
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `api.registerContextEngine(id, factory)` | موتور زمینه (هر بار فقط یکی فعال است). callback مربوط به `assemble()` مقدارهای `availableTools` و `citationsMode` را دریافت میکند تا موتور بتواند افزودههای prompt را تنظیم کند. |
|
||||
| `api.registerMemoryCapability(capability)` | قابلیت حافظه یکپارچه |
|
||||
| `api.registerMemoryPromptSection(builder)` | سازنده بخش prompt حافظه |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | resolver برنامه flush حافظه |
|
||||
| `api.registerMemoryRuntime(runtime)` | adapter runtime حافظه |
|
||||
|
||||
### آداپترهای embedding حافظه
|
||||
### adapterهای embedding حافظه
|
||||
|
||||
| متد | چیزی که ثبت میکند |
|
||||
| ---------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | آداپتر embedding حافظه برای Plugin فعال |
|
||||
| متد | آنچه ثبت میکند |
|
||||
| -------------------------------------------- | ------------------------------------------------ |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | adapter embedding حافظه برای Plugin فعال |
|
||||
|
||||
- `registerMemoryCapability` API انحصاری ترجیحی برای Plugin حافظه است.
|
||||
- `registerMemoryCapability` همچنین ممکن است `publicArtifacts.listArtifacts(...)` را نمایان کند
|
||||
تا Pluginهای همراه بتوانند artifactهای صادرشده حافظه را از طریق
|
||||
`openclaw/plugin-sdk/memory-host-core` مصرف کنند، بهجای اینکه به چیدمان خصوصی
|
||||
یک Plugin حافظه مشخص دسترسی مستقیم داشته باشند.
|
||||
- `registerMemoryPromptSection`، `registerMemoryFlushPlan` و
|
||||
`registerMemoryRuntime` APIهای انحصاری سازگار با گذشته برای Plugin حافظه هستند.
|
||||
- `MemoryFlushPlan.model` میتواند نوبت تخلیه را به یک ارجاع دقیق `provider/model`
|
||||
مانند `ollama/qwen3:8b` سنجاق کند، بدون اینکه زنجیره fallback فعال را به ارث ببرد.
|
||||
- `registerMemoryEmbeddingProvider` به Plugin حافظه فعال اجازه میدهد یک یا چند شناسه آداپتر
|
||||
embedding را ثبت کند (برای مثال `openai`، `gemini`، یا یک شناسه سفارشی تعریفشده توسط Plugin).
|
||||
- `registerMemoryCapability` API ترجیحی انحصاری Plugin حافظه است.
|
||||
- `registerMemoryCapability` همچنین ممکن است `publicArtifacts.listArtifacts(...)` را در معرض استفاده قرار دهد
|
||||
تا Pluginهای همراه بتوانند artifactهای حافظه صادرشده را از طریق
|
||||
`openclaw/plugin-sdk/memory-host-core` مصرف کنند، بهجای اینکه وارد چیدمان خصوصی یک Plugin حافظه مشخص شوند.
|
||||
- `registerMemoryPromptSection`، `registerMemoryFlushPlan`، و
|
||||
`registerMemoryRuntime` APIهای انحصاری سازگار با legacy برای Plugin حافظه هستند.
|
||||
- `MemoryFlushPlan.model` میتواند نوبت flush را بدون بهارثبردن زنجیره fallback فعال، به یک ارجاع دقیق `provider/model`
|
||||
مانند `ollama/qwen3:8b` pin کند.
|
||||
- `registerMemoryEmbeddingProvider` به Plugin حافظه فعال اجازه میدهد یک یا چند شناسه adapter embedding ثبت کند
|
||||
(برای مثال `openai`، `gemini`، یا یک شناسه سفارشی تعریفشده توسط Plugin).
|
||||
- پیکربندی کاربر مانند `agents.defaults.memorySearch.provider` و
|
||||
`agents.defaults.memorySearch.fallback` در برابر همان شناسههای آداپتر ثبتشده resolve میشود.
|
||||
`agents.defaults.memorySearch.fallback` در برابر همان شناسههای adapter ثبتشده resolve میشود.
|
||||
|
||||
### رویدادها و چرخه عمر
|
||||
|
||||
| متد | کاری که انجام میدهد |
|
||||
| -------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | hook تایپشده چرخه عمر |
|
||||
| `api.onConversationBindingResolved(handler)` | callback پیوند مکالمه |
|
||||
| متد | کاری که انجام میدهد |
|
||||
| ------------------------------------------ | --------------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | hook چرخه عمر تایپشده |
|
||||
| `api.onConversationBindingResolved(handler)` | callback مربوط به binding مکالمه |
|
||||
|
||||
برای مثالها، نامهای رایج hook، و معناشناسی guard به [hookهای Plugin](/fa/plugins/hooks) مراجعه کنید.
|
||||
برای نمونهها، نامهای رایج hook، و معناشناسی guard به [hookهای Plugin](/fa/plugins/hooks) مراجعه کنید.
|
||||
|
||||
### معناشناسی تصمیم hook
|
||||
|
||||
- `before_tool_call`: بازگرداندن `{ block: true }` پایانی است. پس از اینکه هر هندلری آن را تنظیم کند، هندلرهای با اولویت پایینتر نادیده گرفته میشوند.
|
||||
- `before_tool_call`: بازگرداندن `{ block: false }` بهعنوان نبود تصمیم تلقی میشود (همانند حذف `block`)، نه بهعنوان override.
|
||||
- `before_install`: بازگرداندن `{ block: true }` پایانی است. پس از اینکه هر هندلری آن را تنظیم کند، هندلرهای با اولویت پایینتر نادیده گرفته میشوند.
|
||||
- `before_install`: بازگرداندن `{ block: false }` بهعنوان نبود تصمیم تلقی میشود (همانند حذف `block`)، نه بهعنوان override.
|
||||
- `reply_dispatch`: بازگرداندن `{ handled: true, ... }` پایانی است. پس از اینکه هر هندلری dispatch را claim کند، هندلرهای با اولویت پایینتر و مسیر dispatch پیشفرض مدل نادیده گرفته میشوند.
|
||||
- `message_sending`: بازگرداندن `{ cancel: true }` پایانی است. پس از اینکه هر هندلری آن را تنظیم کند، هندلرهای با اولویت پایینتر نادیده گرفته میشوند.
|
||||
- `message_sending`: بازگرداندن `{ cancel: false }` بهعنوان نبود تصمیم تلقی میشود (همانند حذف `cancel`)، نه بهعنوان override.
|
||||
- `message_received`: وقتی به مسیریابی thread/topic ورودی نیاز دارید، از فیلد تایپشده `threadId` استفاده کنید. `metadata` را برای موارد اضافه اختصاصی کانال نگه دارید.
|
||||
- `message_sending`: پیش از fallback به `metadata` اختصاصی کانال، از فیلدهای مسیریابی تایپشده `replyToId` / `threadId` استفاده کنید.
|
||||
- `gateway_start`: برای وضعیت راهاندازی متعلق به Gateway از `ctx.config`، `ctx.workspaceDir` و `ctx.getCron?.()` استفاده کنید، بهجای اتکا به hookهای داخلی `gateway:startup`.
|
||||
- `cron_changed`: تغییرات چرخه عمر Cron متعلق به Gateway را مشاهده کنید. هنگام همگامسازی زمانبندهای بیدارسازی خارجی، از `event.job?.state?.nextRunAtMs` و `ctx.getCron?.()` استفاده کنید، و OpenClaw را بهعنوان منبع حقیقت برای بررسیهای موعد و اجرا نگه دارید.
|
||||
- `before_tool_call`: برگرداندن `{ block: true }` نهایی است. وقتی هر handler آن را تنظیم کند، handlerهای با اولویت پایینتر رد میشوند.
|
||||
- `before_tool_call`: برگرداندن `{ block: false }` بهعنوان نبود تصمیم در نظر گرفته میشود (همانند حذف `block`)، نه بهعنوان override.
|
||||
- `before_install`: برگرداندن `{ block: true }` نهایی است. وقتی هر handler آن را تنظیم کند، handlerهای با اولویت پایینتر رد میشوند.
|
||||
- `before_install`: برگرداندن `{ block: false }` بهعنوان نبود تصمیم در نظر گرفته میشود (همانند حذف `block`)، نه بهعنوان override.
|
||||
- `reply_dispatch`: برگرداندن `{ handled: true, ... }` نهایی است. وقتی هر handler مسئولیت dispatch را claim کند، handlerهای با اولویت پایینتر و مسیر dispatch پیشفرض مدل رد میشوند.
|
||||
- `message_sending`: برگرداندن `{ cancel: true }` نهایی است. وقتی هر handler آن را تنظیم کند، handlerهای با اولویت پایینتر رد میشوند.
|
||||
- `message_sending`: برگرداندن `{ cancel: false }` بهعنوان نبود تصمیم در نظر گرفته میشود (همانند حذف `cancel`)، نه بهعنوان override.
|
||||
- `message_received`: وقتی به مسیریابی thread/topic ورودی نیاز دارید، از فیلد تایپشده `threadId` استفاده کنید. `metadata` را برای جزئیات اضافه مختص کانال نگه دارید.
|
||||
- `message_sending`: پیش از fallback به `metadata` مختص کانال، از فیلدهای مسیریابی تایپشده `replyToId` / `threadId` استفاده کنید.
|
||||
- `gateway_start`: بهجای تکیه بر hookهای داخلی `gateway:startup`، برای وضعیت راهاندازی متعلق به Gateway از `ctx.config`، `ctx.workspaceDir`، و `ctx.getCron?.()` استفاده کنید.
|
||||
- `cron_changed`: تغییرات چرخه عمر Cron متعلق به Gateway را مشاهده کنید. هنگام همگامسازی زمانبندهای بیدارسازی خارجی از `event.job?.state?.nextRunAtMs` و `ctx.getCron?.()` استفاده کنید، و OpenClaw را بهعنوان منبع حقیقت برای بررسیهای موعد و اجرا نگه دارید.
|
||||
|
||||
### فیلدهای شیء API
|
||||
|
||||
| فیلد | نوع | توضیح |
|
||||
| فیلد | نوع | توضیح |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | شناسه Plugin |
|
||||
| `api.name` | `string` | نام نمایشی |
|
||||
| `api.version` | `string?` | نسخه Plugin (اختیاری) |
|
||||
| `api.description` | `string?` | توضیح Plugin (اختیاری) |
|
||||
| `api.source` | `string` | مسیر منبع Plugin |
|
||||
| `api.rootDir` | `string?` | دایرکتوری ریشه Plugin (اختیاری) |
|
||||
| `api.config` | `OpenClawConfig` | snapshot پیکربندی فعلی (snapshot زمان اجرای درونحافظهای فعال، در صورت موجود بودن) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | پیکربندی اختصاصی Plugin از `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [کمککنندههای زمان اجرا](/fa/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | logger محدود به دامنه (`debug`، `info`، `warn`، `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | حالت بارگذاری فعلی؛ `"setup-runtime"` پنجره سبک راهاندازی/آمادهسازی پیش از ورود کامل است |
|
||||
| `api.resolvePath(input)` | `(string) => string` | resolve کردن مسیر نسبت به ریشه Plugin |
|
||||
| `api.id` | `string` | شناسه Plugin |
|
||||
| `api.name` | `string` | نام نمایشی |
|
||||
| `api.version` | `string?` | نسخه Plugin (اختیاری) |
|
||||
| `api.description` | `string?` | توضیح Plugin (اختیاری) |
|
||||
| `api.source` | `string` | مسیر منبع Plugin |
|
||||
| `api.rootDir` | `string?` | دایرکتوری ریشه Plugin (اختیاری) |
|
||||
| `api.config` | `OpenClawConfig` | snapshot پیکربندی فعلی (snapshot runtime فعال در حافظه، وقتی در دسترس باشد) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | پیکربندی مختص Plugin از `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [helperهای runtime](/fa/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | logger محدودهبندیشده (`debug`، `info`، `warn`، `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | حالت بارگذاری فعلی؛ `"setup-runtime"` پنجره سبک راهاندازی/setup پیش از full-entry است |
|
||||
| `api.resolvePath(input)` | `(string) => string` | resolve مسیر نسبت به ریشه Plugin |
|
||||
|
||||
## قرارداد ماژول داخلی
|
||||
|
||||
@ -337,35 +332,26 @@ my-plugin/
|
||||
```
|
||||
|
||||
<Warning>
|
||||
هرگز Plugin خودتان را از کد production از طریق `openclaw/plugin-sdk/<your-plugin>`
|
||||
import نکنید. importهای داخلی را از طریق `./api.ts` یا
|
||||
`./runtime-api.ts` مسیریابی کنید. مسیر SDK فقط قرارداد خارجی است.
|
||||
هرگز از کد production، Plugin خودتان را از طریق `openclaw/plugin-sdk/<your-plugin>`
|
||||
import نکنید. importهای داخلی را از مسیر `./api.ts` یا
|
||||
`./runtime-api.ts` عبور دهید. مسیر SDK فقط قرارداد خارجی است.
|
||||
</Warning>
|
||||
|
||||
سطحهای عمومی Pluginهای bundled که با facade بارگذاری میشوند (`api.ts`، `runtime-api.ts`،
|
||||
`index.ts`، `setup-entry.ts` و فایلهای ورودی عمومی مشابه)، وقتی OpenClaw از قبل در حال اجرا باشد،
|
||||
snapshot پیکربندی runtime فعال را ترجیح میدهند. اگر هنوز snapshot runtime وجود نداشته باشد،
|
||||
به فایل پیکربندی resolveشده روی دیسک fallback میکنند.
|
||||
facadeهای Pluginهای bundled بستهبندیشده باید از طریق loaderهای facade مربوط به Plugin در OpenClaw بارگذاری شوند؛
|
||||
importهای مستقیم از `dist/extensions/...` بررسیهای manifest و sidecar زمان اجرا را که نصبهای بستهبندیشده
|
||||
برای کد متعلق به Plugin استفاده میکنند دور میزنند.
|
||||
سطحهای عمومی Pluginهای bundled که از طریق facade بارگذاری میشوند (`api.ts`، `runtime-api.ts`،
|
||||
`index.ts`، `setup-entry.ts`، و فایلهای ورودی عمومی مشابه)، وقتی OpenClaw از قبل در حال اجرا باشد، snapshot پیکربندی runtime فعال را ترجیح میدهند. اگر هنوز snapshot runtime وجود نداشته باشد، به فایل پیکربندی resolveشده روی دیسک fallback میکنند. facadeهای Pluginهای bundled بستهبندیشده باید از طریق loaderهای facade Plugin در OpenClaw بارگذاری شوند؛ import مستقیم از `dist/extensions/...` بررسیهای manifest و sidecar runtime را که نصبهای بستهبندیشده برای کد متعلق به Plugin استفاده میکنند دور میزند.
|
||||
|
||||
Pluginهای ارائهدهنده میتوانند یک barrel قرارداد باریک و محلی برای Plugin را زمانی نمایان کنند که یک
|
||||
کمککننده عمداً اختصاصی ارائهدهنده است و هنوز به یک زیرمسیر عمومی SDK تعلق ندارد.
|
||||
مثالهای bundled:
|
||||
Pluginهای provider میتوانند یک barrel قرارداد باریک و محلیِ Plugin را در معرض استفاده قرار دهند، وقتی یک helper عمداً مختص provider است و هنوز به یک زیرمسیر generic در SDK تعلق ندارد. نمونههای bundled:
|
||||
|
||||
- **Anthropic**: seam عمومی `api.ts` / `contract-api.ts` برای کمککنندههای
|
||||
beta-header مربوط به Claude و stream مربوط به `service_tier`.
|
||||
- **`@openclaw/openai-provider`**: `api.ts` سازندههای ارائهدهنده،
|
||||
کمککنندههای مدل پیشفرض، و سازندههای ارائهدهنده realtime را export میکند.
|
||||
- **`@openclaw/openrouter-provider`**: `api.ts` سازنده ارائهدهنده
|
||||
بههمراه کمککنندههای onboarding/پیکربندی را export میکند.
|
||||
- **Anthropic**: seam عمومی `api.ts` / `contract-api.ts` برای helperهای stream مربوط به beta-header و `service_tier` در Claude.
|
||||
- **`@openclaw/openai-provider`**: `api.ts` سازندههای provider،
|
||||
helperهای default-model، و سازندههای provider realtime را export میکند.
|
||||
- **`@openclaw/openrouter-provider`**: `api.ts` سازنده provider
|
||||
بهعلاوه helperهای onboarding/config را export میکند.
|
||||
|
||||
<Warning>
|
||||
کد production مربوط به extension نیز باید از importهای `openclaw/plugin-sdk/<other-plugin>`
|
||||
پرهیز کند. اگر یک کمککننده واقعاً مشترک است، آن را به یک زیرمسیر خنثی SDK
|
||||
مانند `openclaw/plugin-sdk/speech`، `.../provider-model-shared`، یا یک سطح
|
||||
capability-oriented دیگر ارتقا دهید، بهجای اینکه دو Plugin را به هم couple کنید.
|
||||
کد production مربوط به Extension نیز باید از importهای `openclaw/plugin-sdk/<other-plugin>`
|
||||
پرهیز کند. اگر یک helper واقعاً مشترک است، بهجای coupling دو Plugin به یکدیگر، آن را به یک زیرمسیر خنثی SDK
|
||||
مانند `openclaw/plugin-sdk/speech`، `.../provider-model-shared`، یا سطح دیگری با محوریت قابلیت ارتقا دهید.
|
||||
</Warning>
|
||||
|
||||
## مرتبط
|
||||
@ -378,15 +364,15 @@ Pluginهای ارائهدهنده میتوانند یک barrel قرارد
|
||||
مرجع کامل فضای نام `api.runtime`.
|
||||
</Card>
|
||||
<Card title="راهاندازی و پیکربندی" icon="sliders" href="/fa/plugins/sdk-setup">
|
||||
بستهبندی، مانیفستها، و طرحوارههای پیکربندی.
|
||||
بستهبندی، مانیفستها، و اسکیماهای پیکربندی.
|
||||
</Card>
|
||||
<Card title="آزمون" icon="vial" href="/fa/plugins/sdk-testing">
|
||||
ابزارهای آزمون و قواعد lint.
|
||||
</Card>
|
||||
<Card title="مهاجرت SDK" icon="arrows-turn-right" href="/fa/plugins/sdk-migration">
|
||||
مهاجرت از سطحهای منسوخشده.
|
||||
مهاجرت از سطحهای منسوخ.
|
||||
</Card>
|
||||
<Card title="جزئیات داخلی Plugin" icon="diagram-project" href="/fa/plugins/architecture">
|
||||
معماری عمیق و مدل قابلیت.
|
||||
<Card title="درونیات Plugin" icon="diagram-project" href="/fa/plugins/architecture">
|
||||
معماری تفصیلی و مدل قابلیتها.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,119 +1,120 @@
|
||||
---
|
||||
read_when:
|
||||
- تنظیم تجزیه یا پیشفرضهای تفکر، حالت سریع، یا دستورالعملهای پرجزئیات
|
||||
summary: نحو دستورها برای /think، /fast، /verbose، /trace و نمایشپذیری استدلال
|
||||
- تنظیم تجزیه یا پیشفرضهای دستورالعملهای تفکر، حالت سریع یا پرجزئیات
|
||||
summary: نحو دستورالعملها برای /think، /fast، /verbose، /trace و قابلیت مشاهدهٔ استدلال
|
||||
title: سطوح تفکر
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:28:42Z"
|
||||
generated_at: "2026-05-04T18:23:34Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f
|
||||
source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
|
||||
source_path: tools/thinking.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
## چه کاری انجام میدهد
|
||||
|
||||
- دستور درونخطی در هر بدنه ورودی: `/t <level>`، `/think:<level>`، یا `/thinking <level>`.
|
||||
- دستور درونخطی در هر بدنهٔ ورودی: `/t <level>`، `/think:<level>` یا `/thinking <level>`.
|
||||
- سطحها (نامهای مستعار): `off | minimal | low | medium | high | xhigh | adaptive | max`
|
||||
- minimal → «فکر کن»
|
||||
- low → «سخت فکر کن»
|
||||
- medium → «سختتر فکر کن»
|
||||
- high → «فوقالعاده فکر کن» (حداکثر بودجه)
|
||||
- xhigh → «فوقالعاده فکر کن+» (مدلهای GPT-5.2+ و Codex، بهعلاوه effort مدل Anthropic Claude Opus 4.7)
|
||||
- adaptive → تفکر تطبیقیِ مدیریتشده توسط ارائهدهنده (برای Claude 4.6 روی Anthropic/Bedrock، Anthropic Claude Opus 4.7، و تفکر پویا در Google Gemini پشتیبانی میشود)
|
||||
- max → حداکثر استدلال ارائهدهنده (Anthropic Claude Opus 4.7؛ Ollama این را به بالاترین effort بومی `think` خود نگاشت میکند)
|
||||
- `x-high`، `x_high`، `extra-high`، `extra high`، و `extra_high` به `xhigh` نگاشت میشوند.
|
||||
- high → «بسیار عمیق فکر کن» (حداکثر بودجه)
|
||||
- xhigh → «بسیار عمیق فکر کن+» (مدلهای GPT-5.2+ و Codex، بهعلاوهٔ تلاش Anthropic Claude Opus 4.7)
|
||||
- adaptive → تفکر تطبیقی مدیریتشده توسط ارائهدهنده (برای Claude 4.6 روی Anthropic/Bedrock، Anthropic Claude Opus 4.7 و تفکر پویا در Google Gemini پشتیبانی میشود)
|
||||
- max → حداکثر استدلال ارائهدهنده (Anthropic Claude Opus 4.7؛ Ollama این را به بالاترین تلاش بومی `think` خود نگاشت میکند)
|
||||
- `x-high`، `x_high`، `extra-high`، `extra high` و `extra_high` به `xhigh` نگاشت میشوند.
|
||||
- `highest` به `high` نگاشت میشود.
|
||||
- نکتههای ارائهدهنده:
|
||||
- منوها و انتخابگرهای تفکر بر اساس پروفایل ارائهدهنده هدایت میشوند. Pluginهای ارائهدهنده مجموعه سطح دقیق را برای مدل انتخابشده، شامل برچسبهایی مانند `on` دودویی، اعلام میکنند.
|
||||
- `adaptive`، `xhigh`، و `max` فقط برای پروفایلهای ارائهدهنده/مدلی نمایش داده میشوند که از آنها پشتیبانی میکنند. دستورهای تایپشده برای سطحهای پشتیبانینشده با گزینههای معتبر همان مدل رد میشوند.
|
||||
- سطحهای پشتیبانینشده ذخیرهشده موجود بر اساس رتبه پروفایل ارائهدهنده بازنگاشت میشوند. `adaptive` در مدلهای غیرتطبیقی به `medium` برمیگردد، در حالی که `xhigh` و `max` برای مدل انتخابشده به بزرگترین سطح پشتیبانیشده غیر از `off` برمیگردند.
|
||||
- مدلهای Anthropic Claude 4.6 وقتی هیچ سطح تفکر صریحی تنظیم نشده باشد، بهطور پیشفرض از `adaptive` استفاده میکنند.
|
||||
- Anthropic Claude Opus 4.7 بهطور پیشفرض از تفکر تطبیقی استفاده نمیکند. پیشفرض effort در API آن همچنان در مالکیت ارائهدهنده میماند مگر اینکه صراحتا یک سطح تفکر تنظیم کنید.
|
||||
- Anthropic Claude Opus 4.7 دستور `/think xhigh` را به تفکر تطبیقی بهعلاوه `output_config.effort: "xhigh"` نگاشت میکند، چون `/think` یک دستور تفکر است و `xhigh` تنظیم effort در Opus 4.7 است.
|
||||
- Anthropic Claude Opus 4.7 همچنین `/think max` را ارائه میکند؛ این دستور به همان مسیر effort حداکثریِ در مالکیت ارائهدهنده نگاشت میشود.
|
||||
- مدلهای DeepSeek V4 دستورهای `/think xhigh|max` را ارائه میکنند؛ هر دو به DeepSeek `reasoning_effort: "max"` نگاشت میشوند، در حالی که سطحهای پایینتر غیر از `off` به `high` نگاشت میشوند.
|
||||
- مدلهای Ollama با قابلیت تفکر دستور `/think low|medium|high|max` را ارائه میکنند؛ `max` به `think: "high"` بومی نگاشت میشود، چون API بومی Ollama رشتههای effort شامل `low`، `medium`، و `high` را میپذیرد.
|
||||
- مدلهای OpenAI GPT دستور `/think` را از طریق پشتیبانی effort اختصاصی مدل در Responses API نگاشت میکنند. `/think off` فقط وقتی مدل هدف از آن پشتیبانی کند `reasoning.effort: "none"` را ارسال میکند؛ در غیر این صورت OpenClaw بهجای ارسال مقدار پشتیبانینشده، بار مفید استدلال غیرفعالشده را حذف میکند.
|
||||
- ورودیهای کاتالوگ سازگار با OpenAI سفارشی میتوانند با تنظیم `models.providers.<provider>.models[].compat.supportedReasoningEfforts` برای شامل کردن `"xhigh"`، در `/think xhigh` مشارکت کنند. این از همان فراداده سازگاری استفاده میکند که بارهای مفید effort استدلال خروجی OpenAI را نگاشت میکند، بنابراین منوها، اعتبارسنجی نشست، CLI عامل، و `llm-task` با رفتار انتقال هماهنگ میمانند.
|
||||
- ارجاعهای پیکربندیشده کهنه OpenRouter Hunter Alpha تزریق استدلال پراکسی را نادیده میگیرند، چون آن مسیر بازنشسته میتوانست متن پاسخ نهایی را از طریق فیلدهای استدلال برگرداند.
|
||||
- Google Gemini دستور `/think adaptive` را به تفکر پویای در مالکیت ارائهدهنده Gemini نگاشت میکند. درخواستهای Gemini 3 یک `thinkingLevel` ثابت را حذف میکنند، در حالی که درخواستهای Gemini 2.5 مقدار `thinkingBudget: -1` را ارسال میکنند؛ سطحهای ثابت همچنان برای همان خانواده مدل به نزدیکترین `thinkingLevel` یا بودجه Gemini نگاشت میشوند.
|
||||
- MiniMax (`minimax/*`) در مسیر پخش سازگار با Anthropic بهطور پیشفرض از `thinking: { type: "disabled" }` استفاده میکند، مگر اینکه تفکر را صراحتا در پارامترهای مدل یا پارامترهای درخواست تنظیم کنید. این کار از نشت دلتاهای `reasoning_content` از قالب پخش غیر بومی Anthropic در MiniMax جلوگیری میکند.
|
||||
- Z.AI (`zai/*`) فقط از تفکر دودویی (`on`/`off`) پشتیبانی میکند. هر سطحی غیر از `off` بهعنوان `on` در نظر گرفته میشود (به `low` نگاشت میشود).
|
||||
- Moonshot (`moonshot/*`) دستور `/think off` را به `thinking: { type: "disabled" }` و هر سطحی غیر از `off` را به `thinking: { type: "enabled" }` نگاشت میکند. وقتی تفکر فعال باشد، Moonshot فقط `tool_choice` با مقدارهای `auto|none` را میپذیرد؛ OpenClaw مقدارهای ناسازگار را به `auto` نرمالسازی میکند.
|
||||
- یادداشتهای ارائهدهنده:
|
||||
- منوها و انتخابگرهای تفکر بر اساس پروفایل ارائهدهنده هدایت میشوند. Pluginهای ارائهدهنده مجموعهٔ دقیق سطحها را برای مدل انتخابشده اعلام میکنند، از جمله برچسبهایی مانند `on` دودویی.
|
||||
- `adaptive`، `xhigh` و `max` فقط برای پروفایلهای ارائهدهنده/مدلی نمایش داده میشوند که از آنها پشتیبانی میکنند. دستورهای تایپشده برای سطحهای پشتیبانینشده با گزینههای معتبر همان مدل رد میشوند.
|
||||
- سطحهای پشتیبانینشدهٔ ذخیرهشدهٔ موجود بر اساس رتبهٔ پروفایل ارائهدهنده دوباره نگاشت میشوند. `adaptive` در مدلهای غیرتطبیقی به `medium` برمیگردد، در حالی که `xhigh` و `max` به بزرگترین سطح غیر `off` پشتیبانیشده برای مدل انتخابشده برمیگردند.
|
||||
- مدلهای Anthropic Claude 4.6 وقتی سطح تفکر صریحی تنظیم نشده باشد، بهطور پیشفرض `adaptive` هستند.
|
||||
- Anthropic Claude Opus 4.7 بهطور پیشفرض از تفکر تطبیقی استفاده نمیکند. پیشفرض تلاش API آن متعلق به ارائهدهنده میماند، مگر اینکه صراحتاً سطح تفکر تنظیم کنید.
|
||||
- Anthropic Claude Opus 4.7 دستور `/think xhigh` را به تفکر تطبیقی بههمراه `output_config.effort: "xhigh"` نگاشت میکند، چون `/think` یک دستور تفکر است و `xhigh` تنظیم تلاش Opus 4.7 است.
|
||||
- Anthropic Claude Opus 4.7 همچنین `/think max` را ارائه میکند؛ این دستور به همان مسیر حداکثر تلاش متعلق به ارائهدهنده نگاشت میشود.
|
||||
- مدلهای DeepSeek V4 دستور `/think xhigh|max` را ارائه میکنند؛ هر دو به `reasoning_effort: "max"` در DeepSeek نگاشت میشوند، در حالی که سطحهای پایینتر غیر `off` به `high` نگاشت میشوند.
|
||||
- مدلهای دارای قابلیت تفکر Ollama دستور `/think low|medium|high|max` را ارائه میکنند؛ `max` به `think: "high"` بومی نگاشت میشود، چون API بومی Ollama رشتههای تلاش `low`، `medium` و `high` را میپذیرد.
|
||||
- مدلهای OpenAI GPT دستور `/think` را از طریق پشتیبانی تلاش مختص مدل در Responses API نگاشت میکنند. `/think off` فقط وقتی مدل هدف از آن پشتیبانی کند `reasoning.effort: "none"` را میفرستد؛ در غیر این صورت OpenClaw بهجای فرستادن مقدار پشتیبانینشده، بار دادهٔ استدلال غیرفعالشده را حذف میکند.
|
||||
- ورودیهای کاتالوگ سفارشی سازگار با OpenAI میتوانند با تنظیم `models.providers.<provider>.models[].compat.supportedReasoningEfforts` برای شامل کردن `"xhigh"`، از `/think xhigh` پشتیبانی کنند. این از همان فرادادهٔ سازگاری استفاده میکند که بارهای دادهٔ تلاش استدلال خروجی OpenAI را نگاشت میکند، بنابراین منوها، اعتبارسنجی نشست، CLI عامل و `llm-task` با رفتار انتقال همنظر میمانند.
|
||||
- ارجاعهای پیکربندیشدهٔ قدیمی OpenRouter Hunter Alpha تزریق استدلال پروکسی را رد میکنند، چون آن مسیر بازنشسته میتوانست متن پاسخ نهایی را از طریق فیلدهای استدلال برگرداند.
|
||||
- Google Gemini دستور `/think adaptive` را به تفکر پویای متعلق به ارائهدهندهٔ Gemini نگاشت میکند. درخواستهای Gemini 3 یک `thinkingLevel` ثابت را حذف میکنند، در حالی که درخواستهای Gemini 2.5 مقدار `thinkingBudget: -1` را میفرستند؛ سطحهای ثابت همچنان به نزدیکترین `thinkingLevel` یا بودجهٔ Gemini برای آن خانوادهٔ مدل نگاشت میشوند.
|
||||
- MiniMax (`minimax/*`) در مسیر استریم سازگار با Anthropic بهطور پیشفرض `thinking: { type: "disabled" }` است، مگر اینکه صراحتاً تفکر را در پارامترهای مدل یا پارامترهای درخواست تنظیم کنید. این کار از نشت دلتاهای `reasoning_content` از قالب استریم غیر بومی Anthropic در MiniMax جلوگیری میکند.
|
||||
- Z.AI (`zai/*`) فقط از تفکر دودویی (`on`/`off`) پشتیبانی میکند. هر سطح غیر `off` بهعنوان `on` در نظر گرفته میشود (به `low` نگاشت میشود).
|
||||
- Moonshot (`moonshot/*`) دستور `/think off` را به `thinking: { type: "disabled" }` و هر سطح غیر `off` را به `thinking: { type: "enabled" }` نگاشت میکند. وقتی تفکر فعال باشد، Moonshot فقط `tool_choice` با مقدار `auto|none` را میپذیرد؛ OpenClaw مقدارهای ناسازگار را به `auto` نرمالسازی میکند.
|
||||
|
||||
## ترتیب تفکیک
|
||||
## ترتیب حلوفصل
|
||||
|
||||
1. دستور درونخطی روی پیام (فقط برای همان پیام اعمال میشود).
|
||||
1. دستور درونخطی روی پیام (فقط روی همان پیام اعمال میشود).
|
||||
2. بازنویسی نشست (با ارسال یک پیام فقط شامل دستور تنظیم میشود).
|
||||
3. پیشفرض هر عامل (`agents.list[].thinkingDefault` در پیکربندی).
|
||||
4. پیشفرض سراسری (`agents.defaults.thinkingDefault` در پیکربندی).
|
||||
5. گزینه جایگزین: پیشفرض اعلامشده توسط ارائهدهنده در صورت وجود؛ در غیر این صورت مدلهای دارای قابلیت استدلال به `medium` یا نزدیکترین سطح پشتیبانیشده غیر از `off` برای آن مدل تفکیک میشوند، و مدلهای بدون استدلال روی `off` میمانند.
|
||||
5. پشتیبان: پیشفرض اعلامشده توسط ارائهدهنده، اگر موجود باشد؛ در غیر این صورت مدلهای دارای قابلیت استدلال به `medium` یا نزدیکترین سطح غیر `off` پشتیبانیشده برای آن مدل حل میشوند و مدلهای بدون استدلال روی `off` میمانند.
|
||||
|
||||
## تنظیم پیشفرض نشست
|
||||
|
||||
- پیامی ارسال کنید که **فقط** شامل دستور باشد (فضای خالی مجاز است)، برای نمونه `/think:medium` یا `/t high`.
|
||||
- پیامی بفرستید که **فقط** دستور باشد (فاصلهٔ سفید مجاز است)، برای مثال `/think:medium` یا `/t high`.
|
||||
- این تنظیم برای نشست فعلی باقی میماند (بهطور پیشفرض برای هر فرستنده)؛ با `/think:off` یا بازنشانی نشست پس از بیکاری پاک میشود.
|
||||
- پاسخ تأیید ارسال میشود (`Thinking level set to high.` / `Thinking disabled.`). اگر سطح نامعتبر باشد (مثلا `/thinking big`)، فرمان با یک راهنما رد میشود و وضعیت نشست بدون تغییر باقی میماند.
|
||||
- برای دیدن سطح تفکر فعلی، `/think` (یا `/think:`) را بدون آرگومان ارسال کنید.
|
||||
- پاسخ تأیید فرستاده میشود (`Thinking level set to high.` / `Thinking disabled.`). اگر سطح نامعتبر باشد (مثلاً `/thinking big`)، فرمان با یک راهنما رد میشود و وضعیت نشست بدون تغییر میماند.
|
||||
- برای دیدن سطح تفکر فعلی، `/think` (یا `/think:`) را بدون آرگومان بفرستید.
|
||||
|
||||
## اعمال بر اساس عامل
|
||||
|
||||
- **Pi جاسازیشده**: سطح تفکیکشده به زمان اجرای عامل Pi درونپردازشی پاس داده میشود.
|
||||
- **Pi جاسازیشده**: سطح حلشده به زماناجرای عامل Pi درونفرایندی پاس داده میشود.
|
||||
- **بکاند Claude CLI**: سطحهای غیر off هنگام استفاده از `claude-cli` بهعنوان `--effort` به Claude Code پاس داده میشوند؛ [بکاندهای CLI](/fa/gateway/cli-backends) را ببینید.
|
||||
|
||||
## حالت سریع (/fast)
|
||||
|
||||
- سطحها: `on|off`.
|
||||
- پیام فقط شامل دستور، بازنویسی حالت سریع نشست را تغییر میدهد و پاسخ `Fast mode enabled.` / `Fast mode disabled.` را میدهد.
|
||||
- برای دیدن وضعیت مؤثر فعلی حالت سریع، `/fast` (یا `/fast status`) را بدون حالت ارسال کنید.
|
||||
- OpenClaw حالت سریع را به این ترتیب تفکیک میکند:
|
||||
- پیام فقط شامل دستور، بازنویسی حالت سریع نشست را تغییر میدهد و پاسخ `Fast mode enabled.` / `Fast mode disabled.` میدهد.
|
||||
- برای دیدن وضعیت مؤثر فعلی حالت سریع، `/fast` (یا `/fast status`) را بدون حالت بفرستید.
|
||||
- OpenClaw حالت سریع را به این ترتیب حل میکند:
|
||||
1. `/fast on|off` درونخطی/فقط شامل دستور
|
||||
2. بازنویسی نشست
|
||||
3. پیشفرض هر عامل (`agents.list[].fastModeDefault`)
|
||||
4. پیکربندی هر مدل: `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
5. گزینه جایگزین: `off`
|
||||
- برای `openai/*`، حالت سریع با ارسال `service_tier=priority` در درخواستهای Responses پشتیبانیشده به پردازش اولویتدار OpenAI نگاشت میشود.
|
||||
- برای `openai-codex/*`، حالت سریع همان پرچم `service_tier=priority` را در Codex Responses ارسال میکند. OpenClaw یک تغییر وضعیت مشترک `/fast` را در هر دو مسیر احراز هویت نگه میدارد.
|
||||
- برای درخواستهای عمومی مستقیم `anthropic/*`، شامل ترافیک احرازهویتشده با OAuth که به `api.anthropic.com` ارسال میشود، حالت سریع به سطحهای سرویس Anthropic نگاشت میشود: `/fast on` مقدار `service_tier=auto` را تنظیم میکند، `/fast off` مقدار `service_tier=standard_only` را تنظیم میکند.
|
||||
5. پشتیبان: `off`
|
||||
- برای `openai/*`، حالت سریع با ارسال `service_tier=priority` روی درخواستهای Responses پشتیبانیشده به پردازش اولویتدار OpenAI نگاشت میشود.
|
||||
- برای `openai-codex/*`، حالت سریع همان پرچم `service_tier=priority` را روی Codex Responses میفرستد. OpenClaw یک کلید مشترک `/fast` را در هر دو مسیر احراز هویت نگه میدارد.
|
||||
- برای درخواستهای عمومی مستقیم `anthropic/*`، از جمله ترافیک احراز هویتشده با OAuth که به `api.anthropic.com` فرستاده میشود، حالت سریع به سطحهای سرویس Anthropic نگاشت میشود: `/fast on` مقدار `service_tier=auto` را تنظیم میکند، `/fast off` مقدار `service_tier=standard_only` را تنظیم میکند.
|
||||
- برای `minimax/*` در مسیر سازگار با Anthropic، `/fast on` (یا `params.fastMode: true`) مقدار `MiniMax-M2.7` را به `MiniMax-M2.7-highspeed` بازنویسی میکند.
|
||||
- پارامترهای صریح مدل Anthropic شامل `serviceTier` / `service_tier` وقتی هر دو تنظیم شده باشند، پیشفرض حالت سریع را بازنویسی میکنند. OpenClaw همچنان تزریق سطح سرویس Anthropic را برای نشانیهای پایه پراکسی غیر Anthropic نادیده میگیرد.
|
||||
- پارامترهای صریح مدل Anthropic با نام `serviceTier` / `service_tier` وقتی هر دو تنظیم باشند، پیشفرض حالت سریع را بازنویسی میکنند. OpenClaw همچنان تزریق سطح سرویس Anthropic را برای URLهای پایهٔ پروکسی غیر Anthropic رد میکند.
|
||||
- `/status` فقط وقتی حالت سریع فعال باشد `Fast` را نشان میدهد.
|
||||
|
||||
## دستورهای پرجزئیات (/verbose یا /v)
|
||||
|
||||
- سطحها: `on` (حداقلی) | `full` | `off` (پیشفرض).
|
||||
- پیام فقط شامل دستور، حالت پرجزئیات نشست را تغییر میدهد و پاسخ `Verbose logging enabled.` / `Verbose logging disabled.` را میدهد؛ سطحهای نامعتبر بدون تغییر وضعیت یک راهنما برمیگردانند.
|
||||
- `/verbose off` یک بازنویسی صریح نشست ذخیره میکند؛ آن را از طریق UI نشستها با انتخاب `inherit` پاک کنید.
|
||||
- دستور درونخطی فقط همان پیام را تحت تأثیر قرار میدهد؛ در غیر این صورت پیشفرضهای نشست/سراسری اعمال میشوند.
|
||||
- برای دیدن سطح پرجزئیات فعلی، `/verbose` (یا `/verbose:`) را بدون آرگومان ارسال کنید.
|
||||
- وقتی حالت پرجزئیات روشن است، عاملهایی که نتایج ابزار ساختیافته منتشر میکنند (Pi و عاملهای JSON دیگر) هر فراخوانی ابزار را بهصورت پیام جداگانه فقط-فراداده برمیگردانند، و در صورت وجود با `<emoji> <tool-name>: <arg>` پیشوندگذاری میکنند. این خلاصههای ابزار بهمحض شروع هر ابزار ارسال میشوند (حبابهای جداگانه)، نه بهصورت دلتاهای پخش.
|
||||
- خلاصههای شکست ابزار در حالت عادی قابل مشاهده میمانند، اما پسوندهای جزئیات خطای خام پنهان میشوند مگر اینکه حالت پرجزئیات `on` یا `full` باشد.
|
||||
- وقتی حالت پرجزئیات `full` باشد، خروجیهای ابزار نیز پس از تکمیل ارسال میشوند (حباب جداگانه، کوتاهشده تا طول ایمن). اگر هنگام در جریان بودن یک اجرا `/verbose on|full|off` را تغییر دهید، حبابهای ابزار بعدی تنظیم جدید را رعایت میکنند.
|
||||
- `agents.defaults.toolProgressDetail` شکل خلاصههای ابزار `/verbose` و خطهای ابزار پیشنویس پیشرفت را کنترل میکند. از `"explain"` (پیشفرض) برای برچسبهای انسانی فشرده مانند `🛠️ Exec: checking JS syntax` استفاده کنید؛ وقتی میخواهید فرمان/جزئیات خام نیز برای اشکالزدایی افزوده شود، از `"raw"` استفاده کنید. مقدار هر عامل در `agents.list[].toolProgressDetail` پیشفرض را بازنویسی میکند.
|
||||
- پیام فقط شامل دستور، حالت پرجزئیات نشست را تغییر میدهد و پاسخ `Verbose logging enabled.` / `Verbose logging disabled.` میدهد؛ سطحهای نامعتبر بدون تغییر وضعیت، یک راهنما برمیگردانند.
|
||||
- `/verbose off` یک بازنویسی صریح نشست ذخیره میکند؛ آن را از طریق رابط کاربری Sessions با انتخاب `inherit` پاک کنید.
|
||||
- دستور درونخطی فقط روی همان پیام اثر میگذارد؛ در غیر این صورت پیشفرضهای نشست/سراسری اعمال میشوند.
|
||||
- برای دیدن سطح پرجزئیات فعلی، `/verbose` (یا `/verbose:`) را بدون آرگومان بفرستید.
|
||||
- وقتی حالت پرجزئیات روشن است، عاملهایی که نتایج ابزار ساختاریافته منتشر میکنند (Pi، سایر عاملهای JSON)، هر فراخوانی ابزار را بهعنوان پیام جداگانهٔ فقط فراداده، با پیشوند `<emoji> <tool-name>: <arg>` در صورت وجود، برمیگردانند. این خلاصههای ابزار بهمحض شروع هر ابزار فرستاده میشوند (حبابهای جداگانه)، نه بهعنوان دلتاهای استریم.
|
||||
- خلاصههای شکست ابزار در حالت عادی همچنان قابل مشاهده میمانند، اما پسوندهای جزئیات خطای خام پنهان میشوند مگر اینکه حالت پرجزئیات `on` یا `full` باشد.
|
||||
- وقتی حالت پرجزئیات `full` باشد، خروجیهای ابزار نیز پس از تکمیل ارسال میشوند (حباب جداگانه، کوتاهشده تا طول امن). اگر هنگام در جریان بودن یک اجرا `/verbose on|full|off` را تغییر دهید، حبابهای ابزار بعدی از تنظیم جدید پیروی میکنند.
|
||||
- `agents.defaults.toolProgressDetail` شکل خلاصههای ابزار `/verbose` و خطوط ابزار پیشنویس پیشرفت را کنترل میکند. از `"explain"` (پیشفرض) برای برچسبهای انسانی فشرده مانند `🛠️ Exec: checking JS syntax` استفاده کنید؛ وقتی میخواهید فرمان/جزئیات خام نیز برای اشکالزدایی افزوده شود، از `"raw"` استفاده کنید. مقدار هر عامل در `agents.list[].toolProgressDetail` پیشفرض را بازنویسی میکند.
|
||||
- `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
|
||||
- `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
|
||||
|
||||
## دستورهای ردیابی Plugin (/trace)
|
||||
## دستورهای رهگیری Plugin (/trace)
|
||||
|
||||
- سطحها: `on` | `off` (پیشفرض).
|
||||
- پیام فقط شامل دستور، خروجی ردیابی Plugin نشست را تغییر میدهد و پاسخ `Plugin trace enabled.` / `Plugin trace disabled.` را میدهد.
|
||||
- دستور درونخطی فقط همان پیام را تحت تأثیر قرار میدهد؛ در غیر این صورت پیشفرضهای نشست/سراسری اعمال میشوند.
|
||||
- برای دیدن سطح ردیابی فعلی، `/trace` (یا `/trace:`) را بدون آرگومان ارسال کنید.
|
||||
- `/trace` محدودتر از `/verbose` است: فقط خطهای ردیابی/اشکالزدایی در مالکیت Plugin مانند خلاصههای اشکالزدایی Active Memory را آشکار میکند.
|
||||
- خطهای ردیابی میتوانند در `/status` و بهصورت یک پیام تشخیصی پیگیری پس از پاسخ عادی دستیار ظاهر شوند.
|
||||
- پیام فقط شامل دستور، خروجی رهگیری Plugin نشست را تغییر میدهد و پاسخ `Plugin trace enabled.` / `Plugin trace disabled.` میدهد.
|
||||
- دستور درونخطی فقط روی همان پیام اثر میگذارد؛ در غیر این صورت پیشفرضهای نشست/سراسری اعمال میشوند.
|
||||
- برای دیدن سطح رهگیری فعلی، `/trace` (یا `/trace:`) را بدون آرگومان بفرستید.
|
||||
- `/trace` محدودتر از `/verbose` است: فقط خطوط رهگیری/اشکالزدایی متعلق به Plugin مانند خلاصههای اشکالزدایی Active Memory را آشکار میکند.
|
||||
- خطوط رهگیری میتوانند در `/status` و بهعنوان پیام تشخیصی پیرو پس از پاسخ عادی دستیار ظاهر شوند.
|
||||
|
||||
## نمایانی استدلال (/reasoning)
|
||||
## نمایان بودن استدلال (/reasoning)
|
||||
|
||||
- سطحها: `on|off|stream`.
|
||||
- پیام فقط شامل دستور، نمایش یا عدم نمایش بلوکهای تفکر در پاسخها را تغییر میدهد.
|
||||
- وقتی فعال باشد، استدلال بهصورت یک **پیام جداگانه** با پیشوند `Reasoning:` ارسال میشود.
|
||||
- `stream` (فقط Telegram): هنگام تولید پاسخ، استدلال را در حباب پیشنویس Telegram پخش میکند، سپس پاسخ نهایی را بدون استدلال ارسال میکند.
|
||||
- پیام فقط شامل دستور تعیین میکند که بلوکهای تفکر در پاسخها نشان داده شوند یا نه.
|
||||
- وقتی فعال باشد، استدلال بهعنوان یک **پیام جداگانه** با پیشوند `Reasoning:` فرستاده میشود.
|
||||
- `stream` (فقط Telegram): هنگام تولید پاسخ، استدلال را در حباب پیشنویس Telegram استریم میکند، سپس پاسخ نهایی را بدون استدلال میفرستد.
|
||||
- نام مستعار: `/reason`.
|
||||
- برای دیدن سطح استدلال فعلی، `/reasoning` (یا `/reasoning:`) را بدون آرگومان ارسال کنید.
|
||||
- ترتیب تفکیک: دستور درونخطی، سپس بازنویسی نشست، سپس پیشفرض هر عامل (`agents.list[].reasoningDefault`)، سپس گزینه جایگزین (`off`).
|
||||
- برای دیدن سطح استدلال فعلی، `/reasoning` (یا `/reasoning:`) را بدون آرگومان بفرستید.
|
||||
- ترتیب حلوفصل: دستور درونخطی، سپس بازنویسی نشست، سپس پیشفرض هر عامل (`agents.list[].reasoningDefault`)، سپس پشتیبان (`off`).
|
||||
|
||||
برچسبهای استدلال مدل محلی که بدشکل هستند محافظهکارانه مدیریت میشوند. بلوکهای بستهشده `<think>...</think>` در پاسخهای عادی پنهان میمانند، و استدلال بستهنشده پس از متنِ از پیش قابل مشاهده نیز پنهان میشود. اگر یک پاسخ کاملا در یک تکبرچسب بازِ بستهنشده قرار گرفته باشد و در غیر این صورت بهصورت متن خالی تحویل شود، OpenClaw برچسب باز بدشکل را حذف میکند و متن باقیمانده را تحویل میدهد.
|
||||
برچسبهای استدلال مدل محلیِ بدشکل بهصورت محافظهکارانه مدیریت میشوند. بلوکهای بستهٔ `<think>...</think>` در پاسخهای عادی پنهان میمانند، و استدلال بستهنشده پس از متنِ از قبل قابل مشاهده نیز پنهان میشود. اگر پاسخی کاملاً در یک برچسب آغازینِ بستهنشدهٔ واحد پیچیده شده باشد و در غیر این صورت بهعنوان متن خالی تحویل داده شود، OpenClaw برچسب آغازین بدشکل را حذف میکند و متن باقیمانده را تحویل میدهد.
|
||||
|
||||
## مرتبط
|
||||
|
||||
@ -121,23 +122,23 @@ x-i18n:
|
||||
|
||||
## Heartbeatها
|
||||
|
||||
- بدنه کاوش Heartbeat همان اعلان Heartbeat پیکربندیشده است (پیشفرض: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). دستورهای درونخطی در پیام Heartbeat طبق معمول اعمال میشوند (اما از تغییر پیشفرضهای نشست از Heartbeatها خودداری کنید).
|
||||
- تحویل Heartbeat بهطور پیشفرض فقط شامل بار مفید نهایی است. برای ارسال پیام جداگانه `Reasoning:` نیز (در صورت وجود)، `agents.defaults.heartbeat.includeReasoning: true` یا مقدار هر عامل `agents.list[].heartbeat.includeReasoning: true` را تنظیم کنید.
|
||||
- بدنهٔ پروب Heartbeat همان پرامپت Heartbeat پیکربندیشده است (پیشفرض: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). دستورهای درونخطی در پیام Heartbeat طبق معمول اعمال میشوند (اما از تغییر پیشفرضهای نشست از Heartbeatها خودداری کنید).
|
||||
- تحویل Heartbeat بهطور پیشفرض فقط شامل بار دادهٔ نهایی است. برای ارسال پیام جداگانهٔ `Reasoning:` نیز (در صورت وجود)، `agents.defaults.heartbeat.includeReasoning: true` یا مقدار هر عامل `agents.list[].heartbeat.includeReasoning: true` را تنظیم کنید.
|
||||
|
||||
## UI چت وب
|
||||
## رابط کاربری چت وب
|
||||
|
||||
- انتخابگر تفکر چت وب هنگام بارگذاری صفحه، سطح ذخیرهشده نشست را از فروشگاه/پیکربندی نشست ورودی بازتاب میدهد.
|
||||
- انتخاب سطحی دیگر، بازنویسی نشست را بلافاصله از طریق `sessions.patch` مینویسد؛ منتظر ارسال بعدی نمیماند و یک بازنویسی یکباره `thinkingOnce` نیست.
|
||||
- گزینه اول همیشه `Default (<resolved level>)` است، که در آن پیشفرض تفکیکشده از پروفایل تفکر ارائهدهنده مدل نشست فعال بهعلاوه همان منطق جایگزینی میآید که `/status` و `session_status` استفاده میکنند.
|
||||
- انتخابگر از `thinkingLevels` بازگرداندهشده توسط ردیف نشست/پیشفرضهای Gateway استفاده میکند، و `thinkingOptions` بهعنوان فهرست برچسب قدیمی نگه داشته میشود. UI مرورگر فهرست regex ارائهدهنده خودش را نگه نمیدارد؛ Pluginها مالک مجموعه سطحهای اختصاصی مدل هستند.
|
||||
- `/think:<level>` همچنان کار میکند و همان سطح نشست ذخیرهشده را بهروزرسانی میکند، بنابراین دستورهای چت و انتخابگر همگام میمانند.
|
||||
- انتخابگر تفکر چت وب هنگام بارگذاری صفحه، سطح ذخیرهشدهٔ نشست را از مخزن/پیکربندی نشست ورودی بازتاب میدهد.
|
||||
- انتخاب سطحی دیگر، بازنویسی نشست را بلافاصله از طریق `sessions.patch` مینویسد؛ منتظر ارسال بعدی نمیماند و یک بازنویسی یکبارهٔ `thinkingOnce` نیست.
|
||||
- گزینهٔ اول همیشه `Default (<resolved level>)` است، که در آن پیشفرض حلشده از پروفایل تفکر ارائهدهندهٔ مدل نشست فعال بههمراه همان منطق پشتیبانیای میآید که `/status` و `session_status` استفاده میکنند.
|
||||
- انتخابگر از `thinkingLevels` برگشتی از ردیف/پیشفرضهای نشست Gateway استفاده میکند، و `thinkingOptions` بهعنوان فهرست برچسب قدیمی نگه داشته میشود. رابط کاربری مرورگر فهرست regex ارائهدهندهٔ خودش را نگه نمیدارد؛ Pluginها مالک مجموعه سطحهای مختص مدل هستند.
|
||||
- `/think:<level>` همچنان کار میکند و همان سطح نشست ذخیرهشده را بهروزرسانی میکند، بنابراین دستورهای چت و انتخابگر همگام میمانند.
|
||||
|
||||
## پروفایلهای ارائهدهنده
|
||||
|
||||
- Pluginهای ارائهدهنده میتوانند `resolveThinkingProfile(ctx)` را در معرض دسترس قرار دهند تا سطحهای پشتیبانیشدهٔ مدل و مقدار پیشفرض را تعریف کنند.
|
||||
- Pluginهای ارائهدهندهای که مدلهای Claude را پروکسی میکنند باید از `resolveClaudeThinkingProfile(modelId)` در `openclaw/plugin-sdk/provider-model-shared` دوباره استفاده کنند تا کاتالوگهای مستقیم Anthropic و پروکسی همراستا بمانند.
|
||||
- هر سطح نمایه یک `id` متعارف ذخیرهشده دارد (`off`، `minimal`، `low`، `medium`، `high`، `xhigh`، `adaptive` یا `max`) و ممکن است یک `label` نمایشی داشته باشد. ارائهدهندههای دودویی از `{ id: "low", label: "on" }` استفاده میکنند.
|
||||
- Pluginهای ابزاری که باید یک بازنویسی صریح تفکر را اعتبارسنجی کنند، باید از `api.runtime.agent.resolveThinkingPolicy({ provider, model })` بههمراه `api.runtime.agent.normalizeThinkingLevel(...)` استفاده کنند؛ آنها نباید فهرستهای سطح ارائهدهنده/مدل خودشان را نگه دارند.
|
||||
- Pluginهای ابزاری که به فرادادهٔ مدل سفارشی پیکربندیشده دسترسی دارند میتوانند `catalog` را به `resolveThinkingPolicy` بدهند تا اعلام پشتیبانیهای `compat.supportedReasoningEfforts` در اعتبارسنجی سمت Plugin بازتاب داده شود.
|
||||
- هوکهای قدیمی منتشرشده (`supportsXHighThinking`، `isBinaryThinking` و `resolveDefaultThinkingLevel`) بهعنوان آداپتورهای سازگاری باقی میمانند، اما مجموعههای سطح سفارشی جدید باید از `resolveThinkingProfile` استفاده کنند.
|
||||
- ردیفها/پیشفرضهای Gateway، `thinkingLevels`، `thinkingOptions` و `thinkingDefault` را در معرض دسترس قرار میدهند تا کلاینتهای ACP/چت همان شناسهها و برچسبهای نمایهای را رندر کنند که اعتبارسنجی زمان اجرا استفاده میکند.
|
||||
- Pluginهای ارائهدهنده میتوانند `resolveThinkingProfile(ctx)` را در معرض دسترس قرار دهند تا سطوح پشتیبانیشده مدل و مقدار پیشفرض را تعریف کنند.
|
||||
- Pluginهای ارائهدهندهای که مدلهای Claude را پروکسی میکنند باید از `resolveClaudeThinkingProfile(modelId)` از `openclaw/plugin-sdk/provider-model-shared` دوباره استفاده کنند تا کاتالوگهای مستقیم Anthropic و پروکسی همتراز بمانند.
|
||||
- هر سطح پروفایل یک `id` متعارف ذخیرهشده دارد (`off`، `minimal`، `low`، `medium`، `high`، `xhigh`، `adaptive`، یا `max`) و میتواند یک `label` نمایشی داشته باشد. ارائهدهندگان دودویی از `{ id: "low", label: "on" }` استفاده میکنند.
|
||||
- Pluginهای ابزار که نیاز دارند یک بازنویسی صریح تفکر را اعتبارسنجی کنند باید از `api.runtime.agent.resolveThinkingPolicy({ provider, model })` بههمراه `api.runtime.agent.normalizeThinkingLevel(...)` استفاده کنند؛ آنها نباید فهرستهای سطح ارائهدهنده/مدل خودشان را نگه دارند.
|
||||
- Pluginهای ابزار که به فراداده پیکربندیشده مدل سفارشی دسترسی دارند میتوانند `catalog` را به `resolveThinkingPolicy` پاس بدهند تا opt-inهای `compat.supportedReasoningEfforts` در اعتبارسنجی سمت Plugin منعکس شوند.
|
||||
- هوکهای قدیمی منتشرشده (`supportsXHighThinking`، `isBinaryThinking`، و `resolveDefaultThinkingLevel`) بهعنوان آداپترهای سازگاری باقی میمانند، اما مجموعههای سطح سفارشی جدید باید از `resolveThinkingProfile` استفاده کنند.
|
||||
- ردیفها/پیشفرضهای Gateway، `thinkingLevels`، `thinkingOptions`، و `thinkingDefault` را در معرض دسترس قرار میدهند تا کلاینتهای ACP/چت همان شناسهها و برچسبهای پروفایلی را رندر کنند که اعتبارسنجی زمان اجرا استفاده میکند.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user