RPC and API
یکپارچهسازیهای Gateway برای برنامههای خارجی
برنامههای خارجی از طریق پروتکل Gateway با OpenClaw ارتباط برقرار میکنند: انتقال WebSocket بههمراه متدهای RPC. زمانی از آن استفاده کنید که یک اسکریپت، داشبورد، وظیفه CI، افزونه IDE یا فرایند دیگری بخواهد اجرای عاملها را آغاز کند، رویدادها را بهصورت جریانی دریافت کند، منتظر نتایج بماند، کار را لغو کند یا منابع Gateway را بررسی کند.
آنچه امروز در دسترس است
| سطح | وضعیت | کاربرد |
|---|---|---|
| پروتکل 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" }
شناسهها از دو طرف بریده میشوند، باید حداقل یک نویسه غیرسفید داشته باشند و به
۱۲۸ نویسه محدود هستند. نتیجه آمادهسازی مشغول دارای 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 بارگذاری میکند.
