---
read_when:
    - در حال ساخت یک برنامه خارجی، اسکریپت، داشبورد، کار CI یا افزونه IDE هستید که با OpenClaw ارتباط برقرار می‌کند
    - شما در حال انتخاب بین RPC ‏Gateway و SDK ‏Plugin هستید
    - در حال یکپارچه‌سازی با اجراهای عامل، نشست‌ها، رویدادها، تأییدها، مدل‌ها یا ابزارهای Gateway هستید
    - شما یک کنترل‌کنندهٔ میزبانی را با یک زمان‌بند بیدارباش خارجی جفت می‌کنید
sidebarTitle: External apps
summary: مسیر یکپارچه‌سازی فعلی برای برنامه‌های خارجی، اسکریپت‌ها، داشبوردها، کارهای CI و افزونه‌های IDE
title: یکپارچه‌سازی‌های Gateway برای برنامه‌های خارجی
x-i18n:
    generated_at: "2026-07-27T14:08:52Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 276c6f4173197683a60770327e131e6ab2fa4d33f416ba96c170539df7246f83
    source_path: gateway/external-apps.md
    workflow: 16
---

اپ‌های خارجی از طریق پروتکل Gateway با OpenClaw ارتباط برقرار می‌کنند: انتقال
WebSocket به‌همراه متدهای RPC. وقتی یک اسکریپت، داشبورد، کار CI، افزونهٔ IDE
یا فرایند دیگری می‌خواهد اجرای عامل‌ها را آغاز کند، رویدادها را به‌صورت جریانی دریافت کند، منتظر
نتایج بماند، کار را لغو کند یا منابع Gateway را بررسی کند، از آن استفاده کنید.

<Note>
  برای بسته‌های npm، جفت‌سازی دستگاه، بازیابی اتصال مجدد، تاریخچه، اشتراک‌ها
  و تأییدها، با
  [ساخت یک کلاینت Gateway](https://docs.openclaw.ai/gateway/clients) شروع کنید. اگر
  اپ شما بر Gateway به‌عنوان یک فرایند فرزند نظارت می‌کند، همچنین
  [تعبیهٔ OpenClaw](https://docs.openclaw.ai/gateway/embedding) را بخوانید. در طول
  عرضهٔ اولیهٔ بسته، ممکن است npm تا زمان انتشار نخستین نسخهٔ OpenClaw
  حاوی بسته، `E404` را برگرداند.
</Note>

<Note>
  این صفحه برای کدی است که بیرون از فرایند OpenClaw قرار دارد. کد Plugin که
  درون OpenClaw اجرا می‌شود باید به‌جای آن از زیرمسیرهای مستندشدهٔ `openclaw/plugin-sdk/*`
  استفاده کند.
</Note>

## آنچه امروز در دسترس است

| سطح                                                              | وضعیت          | کاربرد                                                                                         |
| ---------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
| [راهنمای کلاینت Gateway](https://docs.openclaw.ai/gateway/clients) | چرخهٔ انتشار   | بسته‌های npm، احراز هویت، اتصال مجدد، تاریخچه، رویدادها، تأییدها و سیاست نسخه.                |
| [راهنمای تعبیه](https://docs.openclaw.ai/gateway/embedding)        | چرخهٔ انتشار   | محیط فرایند فرزند، آمادگی، چرخهٔ حیات، بازیابی، مالکیت RPC و بسته‌بندی.                       |
| [پروتکل Gateway](/fa/gateway/protocol)                               | آماده          | انتقال WebSocket، دست‌دهی اتصال، دامنه‌های احراز هویت، نسخه‌بندی پروتکل و رویدادها.          |
| [مرجع RPC ‏Gateway](/fa/reference/rpc)                               | آماده          | متدهای فعلی Gateway برای عامل‌ها، نشست‌ها، وظایف، مدل‌ها، ابزارها، مصنوعات و تأییدها.         |
| [`openclaw agent`](/fa/cli/agent)                                  | آماده          | یکپارچه‌سازی تک‌مرحله‌ای اسکریپت، هنگامی که فراخوانی CLI از پوسته کافی است.                   |
| [`openclaw message`](/fa/cli/message)                                | آماده          | ارسال پیام‌ها یا کنش‌های کانال از اسکریپت‌ها.                                                  |

## مسیر پیشنهادی

1. یک Gateway را اجرا یا کشف کنید.
2. از طریق [پروتکل Gateway](/fa/gateway/protocol) متصل شوید.
3. متدهای مستندشدهٔ RPC را از [مرجع RPC ‏Gateway](/fa/reference/rpc) فراخوانی کنید.
4. نسخهٔ OpenClaw را که با آن آزمایش می‌کنید ثابت نگه دارید.
5. هنگام ارتقای OpenClaw، مرجع RPC را دوباره بررسی کنید.

برای اجرای عامل‌ها، با RPC ‏`agent` شروع کنید و برای دریافت نتیجهٔ
نهایی، آن را با `agent.wait` همراه کنید. برای وضعیت پایدار مکالمه، از متدهای
`sessions.*` استفاده کنید. برای یکپارچه‌سازی‌های رابط کاربری، در رویدادهای Gateway
مشترک شوید و فقط خانواده‌های رویدادی را رندر کنید که اپ شما می‌شناسد.

## تعلیق هماهنگ میزبان

کنترل‌کننده‌های میزبانی که یک فرایند در حال اجرا را منجمد می‌کنند یا از آن
اسنپ‌شات می‌گیرند، می‌توانند از دست‌دهی تعلیق مستقل از میزبان استفاده کنند:

1. پذیرش ورودی خارجی تحت کنترل میزبان را متوقف کنید.
2. متد `gateway.suspend.prepare` را با یک `requestId` پایدار و یکتا فراخوانی کنید.
3. اگر پاسخ `busy` است، فرایند را در حال اجرا نگه دارید و بعداً دوباره تلاش کنید.
4. اگر پاسخ `ready` است، مقدار بازگشتی `suspensionId` را ذخیره کنید، سپس
   پیش از `expiresAtMs` فرایند را منجمد کنید یا از آن اسنپ‌شات بگیرید.
5. پس از رفع انجماد، یا اگر تعلیق کنار گذاشته شد، متد `gateway.suspend.resume`
   را با همان `suspensionId` از طریق WebSocket موجود یا مسیر کنترل Admin HTTP
   فراخوانی کنید.

یک Gateway آماده‌شده دست‌دهی‌های جدید WebSocket را رد می‌کند. کنترل‌کنندهٔ WebSocket
باید اتصال احرازشدهٔ خود را در سراسر عملیات میزبان باز نگه دارد. اگر تضمین این
موضوع ممکن نیست، پیش از آماده‌سازی
[Plugin ‏RPC ‏Admin HTTP](/fa/plugins/admin-http-rpc) را فعال و استفاده کنید. اگر
مسیر کنترل از دست برود، پیش از اتصال مجدد منتظر انقضای اجارهٔ دو‌دقیقه‌ای
بمانید؛ انقضا پذیرش را به‌طور خودکار دوباره باز می‌کند.

قرارداد RPC به این صورت است:

- `gateway.suspend.prepare` — `operator.admin`؛ پارامترها
  `{ "requestId": "stable-host-operation-id" }`
- `gateway.suspend.status` — `operator.read`؛ پارامترها
  `{ "suspensionId": "id-from-prepare" }`
- `gateway.suspend.resume` — `operator.admin`؛ پارامترها
  `{ "suspensionId": "id-from-prepare" }`

فاصله‌های ابتدا و انتهای شناسه‌ها حذف می‌شوند، شناسه‌ها باید دست‌کم یک نویسهٔ
غیرفاصله داشته باشند و حداکثر به 128 نویسه محدودند. نتیجهٔ آماده‌سازی مشغول دارای
`status: "busy"`، `reason`،
`retryAfterMs`، `activeCount` و `blockers` است. نتیجهٔ آماده این ساختار را دارد:

```json
{
  "status": "ready",
  "suspensionId": "2c3f...",
  "expiresAtMs": 1770000000000,
  "activeCount": 0,
  "blockers": []
}
```

وضعیت، `{"status":"running"}` یا یک نتیجهٔ آماده همراه با `expiresAtMs` را برمی‌گرداند.
ازسرگیری `{"ok":true,"status":"running","resumed":true}` را برمی‌گرداند؛ تکرار آن
پس از ازسرگیری موفق، `resumed: false` را برمی‌گرداند.

یک شناسهٔ درخواست رقیب یا شکست موقت در ازسرگیری زمان‌بند، خطای قابل‌تلاش‌مجدد
`UNAVAILABLE` را همراه با `retryAfterMs` برمی‌گرداند. هنگام بازیابی زمان‌بند، آماده‌سازی، وضعیت
و ازسرگیری همگی آن خطا را برمی‌گردانند، Gateway آماده باقی نمی‌ماند و
به‌صورت بسته در برابر خطا عمل می‌کند، و میزبان نباید آن را منجمد کند یا از آن اسنپ‌شات بگیرد. OpenClaw
به‌طور خودکار زمان‌بند را دوباره امتحان می‌کند و تنها پس از موفقیت بازیابی، پذیرش را
دوباره باز می‌کند. شناسهٔ نامطابق ازسرگیری، `INVALID_REQUEST` را برمی‌گرداند. آماده‌سازی از بودجهٔ
نوشتن صفحهٔ کنترل Gateway با سه تلاش در دقیقه استفاده می‌کند؛ تأخیر بازگشتی
برای تلاش مجدد را رعایت کنید. کلاینت‌های WebSocket بر پایهٔ دستگاه و IP دسته‌بندی می‌شوند. کنترل‌کننده‌های
Admin HTTP بر پایهٔ IP حل‌شدهٔ کلاینت دسته‌بندی می‌شوند، بنابراین کنترل‌کننده‌های پشت یک
پراکسی می‌توانند بودجه‌ای مشترک داشته باشند.

آماده‌سازی فقط مبتنی بر امتناع است: OpenClaw پذیرش جدید ریشه/نشست/فرمان را می‌بندد،
تیک‌های خودکار Cron را مکث می‌کند و کار را به‌صورت هم‌زمان بررسی می‌کند. اگر چیزی
فعال باشد، پیش از بازگرداندن `busy` زمان‌بند را از سر می‌گیرد و پذیرش را
دوباره باز می‌کند؛ آن کار را قطع یا تخلیه نمی‌کند. اجارهٔ آماده دو
دقیقه دوام دارد. تکرار `prepare` با همان `requestId` آن را تمدید می‌کند؛ انقضا پیش از
بازگشایی پذیرش، زمان‌بند را از سر می‌گیرد.
انتشار راه‌اندازی مجدد که موعد آن در طول اجارهٔ آماده فرا می‌رسد تا ازسرگیری اجاره
منتظر می‌ماند؛ راه‌اندازی مجدد در حال انجام باعث می‌شود آماده‌سازی `busy` را برگرداند.

در حالت آماده، `/healthz` فعال می‌ماند و `/readyz` مقدار `503` را برمی‌گرداند. پاسخ‌های
آمادگی محلی یا احرازشده شامل `gateway-draining` هستند؛ پروب‌های راه دور
احرازنشده فقط `{ "ready": false }` را دریافت می‌کنند. پروب سلامت HTTP،
متدهای تعلیق روی اتصال‌های WebSocket موجود و مسیر RPC ‏Admin HTTP که از قبل
فعال شده است، در دسترس می‌مانند. سایر RPCها خطای قابل‌تلاش‌مجدد
`UNAVAILABLE` را برمی‌گردانند. مسیرهای داخلی HTTP برای کار کاربر و مسیرهای عادی HTTP ‏Plugin،
از جمله APIهای سازگار با OpenAI، عملیات ابزار/نشست، پایش‌های Node و
هوک‌های پیکربندی‌شده، `503` را همراه با `error.code: "gateway_unavailable"` برمی‌گردانند. ارتقاهای جدید
WebSocket تحت مالکیت Plugin نیز `503` را برمی‌گردانند؛ این مورد مالکیت ارتقا
را پوشش می‌دهد، نه کاری را که بعداً از طریق سوکت تثبیت‌شدهٔ Plugin انجام می‌شود.

این دست‌دهی پیام‌های ورودی را پایدار نمی‌کند، انتقال‌های کانال شخص ثالث را
متوقف نمی‌کند و پلتفرم میزبانی را کنترل نمی‌کند. میزبان باید پیش از آماده‌سازی
ورودی خود را مسدود کند و همچنان مسئول بیدارسازی، اسنپ‌شات/انجماد و
توقف باقی می‌ماند. `activeCount` شمار کل کارهای رهگیری‌شده است، درحالی‌که `blockers`
شمار دسته‌های غیرصفر و جزئیات محدود وظایف را در بر دارد. این یک
مانع عمومی سکون فرایند نیست. مسدودکنندهٔ `background-exec` فقط تجمیعی
است: متن فرمان، شناسه‌های فرایند، خروجی و شناسه‌های نشست یا دامنه هرگز
از پروتکل عبور نمی‌کنند. سلامت کانال، نگه‌داری، نوسازی کش، نشست‌های
تثبیت‌شدهٔ WebSocket ‏Plugin و کار پس‌زمینهٔ ثبت‌نشدهٔ تحت مالکیت Plugin می‌توانند
فعال باقی بمانند.
پلتفرم میزبانی باید کل درخت فرایند و سیستم فایل آن را به‌طور سازگار منجمد کند
یا از آن اسنپ‌شات بگیرد؛ با این قرارداد اولیه نمی‌توان بی‌کاری کار ثبت‌نشده را
اثبات کرد.

<Tip>
  برای زمان‌بندی بیدارسازی میزبان، بخش روبه‌روی OpenClaw را در یک Plugin درون‌فرایندی
  نگه دارید و اسنپ‌شات‌های کامل و هم‌توان را به سازگارگر میزبان خارجی انتقال دهید.
  کنترل‌کنندهٔ میزبانی نباید Plugin SDK را وارد کند یا وضعیت Cron را از دلتاهای
  رویداد بازسازی کند. به [فرافکنی امن Cron خارجی
  ](/fa/plugins/hooks#safe-external-cron-projection) مراجعه کنید.
</Tip>

## کد اپ در برابر کد Plugin

وقتی کد بیرون از OpenClaw قرار دارد، از RPC ‏Gateway استفاده کنید:

- اسکریپت‌های Node که اجرای عامل‌ها را آغاز یا مشاهده می‌کنند
- کارهای CI که یک Gateway را فراخوانی می‌کنند
- داشبوردها و پنل‌های مدیریت
- افزونه‌های IDE
- پل‌های خارجی که لازم نیست به Plugin کانال تبدیل شوند
- آزمون‌های یکپارچه‌سازی با انتقال‌های ساختگی یا واقعی Gateway

وقتی کد درون OpenClaw اجرا می‌شود، از Plugin SDK استفاده کنید:

- Pluginهای ارائه‌دهنده
- Pluginهای کانال
- هوک‌های ابزار یا چرخهٔ حیات
- Pluginهای چارچوب اجرای عامل
- کمک‌ابزارهای قابل‌اعتماد زمان اجرا

اپ‌های خارجی نباید `openclaw/plugin-sdk/*` را وارد کنند؛ آن زیرمسیرها برای
Pluginهایی هستند که OpenClaw بارگذاری می‌کند.

## مرتبط

- [ساخت یک کلاینت Gateway](https://docs.openclaw.ai/gateway/clients)
- [تعبیهٔ OpenClaw](https://docs.openclaw.ai/gateway/embedding)
- [پروتکل Gateway](/fa/gateway/protocol)
- [مرجع RPC ‏Gateway](/fa/reference/rpc)
- [فرمان عامل CLI](/fa/cli/agent)
- [فرمان پیام CLI](/fa/cli/message)
- [حلقهٔ عامل](/fa/concepts/agent-loop)
- [زمان‌های اجرای عامل](/fa/concepts/agent-runtimes)
- [نشست‌ها](/fa/concepts/session)
- [وظایف پس‌زمینه](/fa/automation/tasks)
- [عامل‌های ACP](/fa/tools/acp-agents)
- [نمای کلی Plugin SDK](/fa/plugins/sdk-overview)