RPC and API
یکپارچهسازیهای Gateway برای برنامههای خارجی
اپهای خارجی از طریق پروتکل Gateway با OpenClaw ارتباط برقرار میکنند: انتقال WebSocket بههمراه متدهای RPC. وقتی یک اسکریپت، داشبورد، کار CI، افزونهٔ IDE یا فرایند دیگری میخواهد اجرای عاملها را آغاز کند، رویدادها را بهصورت جریانی دریافت کند، منتظر نتایج بماند، کار را لغو کند یا منابع Gateway را بررسی کند، از آن استفاده کنید.
آنچه امروز در دسترس است
| سطح | وضعیت | کاربرد |
|---|---|---|
| راهنمای کلاینت Gateway | چرخهٔ انتشار | بستههای npm، احراز هویت، اتصال مجدد، تاریخچه، رویدادها، تأییدها و سیاست نسخه. |
| راهنمای تعبیه | چرخهٔ انتشار | محیط فرایند فرزند، آمادگی، چرخهٔ حیات، بازیابی، مالکیت RPC و بستهبندی. |
| پروتکل Gateway | آماده | انتقال WebSocket، دستدهی اتصال، دامنههای احراز هویت، نسخهبندی پروتکل و رویدادها. |
| مرجع RPC Gateway | آماده | متدهای فعلی Gateway برای عاملها، نشستها، وظایف، مدلها، ابزارها، مصنوعات و تأییدها. |
openclaw agent |
آماده | یکپارچهسازی تکمرحلهای اسکریپت، هنگامی که فراخوانی CLI از پوسته کافی است. |
openclaw message |
آماده | ارسال پیامها یا کنشهای کانال از اسکریپتها. |
مسیر پیشنهادی
- یک Gateway را اجرا یا کشف کنید.
- از طریق پروتکل Gateway متصل شوید.
- متدهای مستندشدهٔ RPC را از مرجع RPC Gateway فراخوانی کنید.
- نسخهٔ OpenClaw را که با آن آزمایش میکنید ثابت نگه دارید.
- هنگام ارتقای OpenClaw، مرجع RPC را دوباره بررسی کنید.
برای اجرای عاملها، با RPC agent شروع کنید و برای دریافت نتیجهٔ
نهایی، آن را با agent.wait همراه کنید. برای وضعیت پایدار مکالمه، از متدهای
sessions.* استفاده کنید. برای یکپارچهسازیهای رابط کاربری، در رویدادهای Gateway
مشترک شوید و فقط خانوادههای رویدادی را رندر کنید که اپ شما میشناسد.
تعلیق هماهنگ میزبان
کنترلکنندههای میزبانی که یک فرایند در حال اجرا را منجمد میکنند یا از آن اسنپشات میگیرند، میتوانند از دستدهی تعلیق مستقل از میزبان استفاده کنند:
- پذیرش ورودی خارجی تحت کنترل میزبان را متوقف کنید.
- متد
gateway.suspend.prepareرا با یکrequestIdپایدار و یکتا فراخوانی کنید. - اگر پاسخ
busyاست، فرایند را در حال اجرا نگه دارید و بعداً دوباره تلاش کنید. - اگر پاسخ
readyاست، مقدار بازگشتیsuspensionIdرا ذخیره کنید، سپس پیش ازexpiresAtMsفرایند را منجمد کنید یا از آن اسنپشات بگیرید. - پس از رفع انجماد، یا اگر تعلیق کنار گذاشته شد، متد
gateway.suspend.resumeرا با همانsuspensionIdاز طریق WebSocket موجود یا مسیر کنترل Admin HTTP فراخوانی کنید.
یک Gateway آمادهشده دستدهیهای جدید WebSocket را رد میکند. کنترلکنندهٔ WebSocket باید اتصال احرازشدهٔ خود را در سراسر عملیات میزبان باز نگه دارد. اگر تضمین این موضوع ممکن نیست، پیش از آمادهسازی Plugin RPC Admin HTTP را فعال و استفاده کنید. اگر مسیر کنترل از دست برود، پیش از اتصال مجدد منتظر انقضای اجارهٔ دودقیقهای بمانید؛ انقضا پذیرش را بهطور خودکار دوباره باز میکند.
قرارداد 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 است. نتیجهٔ آماده این ساختار را دارد:
{ "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 میتوانند
فعال باقی بمانند.
پلتفرم میزبانی باید کل درخت فرایند و سیستم فایل آن را بهطور سازگار منجمد کند
یا از آن اسنپشات بگیرد؛ با این قرارداد اولیه نمیتوان بیکاری کار ثبتنشده را
اثبات کرد.
کد اپ در برابر کد Plugin
وقتی کد بیرون از OpenClaw قرار دارد، از RPC Gateway استفاده کنید:
- اسکریپتهای Node که اجرای عاملها را آغاز یا مشاهده میکنند
- کارهای CI که یک Gateway را فراخوانی میکنند
- داشبوردها و پنلهای مدیریت
- افزونههای IDE
- پلهای خارجی که لازم نیست به Plugin کانال تبدیل شوند
- آزمونهای یکپارچهسازی با انتقالهای ساختگی یا واقعی Gateway
وقتی کد درون OpenClaw اجرا میشود، از Plugin SDK استفاده کنید:
- Pluginهای ارائهدهنده
- Pluginهای کانال
- هوکهای ابزار یا چرخهٔ حیات
- Pluginهای چارچوب اجرای عامل
- کمکابزارهای قابلاعتماد زمان اجرا
اپهای خارجی نباید openclaw/plugin-sdk/* را وارد کنند؛ آن زیرمسیرها برای
Pluginهایی هستند که OpenClaw بارگذاری میکند.
