Gateway

ساخت کلاینت Gateway

از بسته‌های منتشرشده Gateway برای ساخت داشبوردهای اپراتور، کلاینت‌های WebChat و دیگر برنامه‌های شخص ثالث استفاده کنید. این راهنما چرخهٔ عمر کلاینت پیرامون قرارداد ارتباطی را پوشش می‌دهد: احراز هویت، قابلیت‌ها، بازیابی پس از اتصال مجدد، تاریخچه، اشتراک‌ها و ارتقای نسخه‌ها.

برای شکل فریم‌ها، دست‌دهی، خطاها و سطح کامل متدها، مشخصات پروتکل Gateway را بخوانید.

نصب بسته‌ها

bash

npm install @openclaw/gateway-client @openclaw/gateway-protocol

@openclaw/gateway-protocol طرح‌واره‌ها، اعتبارسنج‌های زمان اجرا، نوع‌های TypeScript، رجیستری‌های هویت و قابلیت کلاینت، خوانشگرهای خطای ساختاریافته و ثابت‌های نسخهٔ پروتکل را فراهم می‌کند. بستهٔ tar آن در npm همچنین قرارداد ماشین‌خوان تولیدشدهٔ protocol.schema.json را در بر می‌گیرد.
@openclaw/gateway-client پیاده‌سازی مرجع اتصال است. برای کلاینت Node، ریشهٔ بسته و برای پروتکل ایمن برای مرورگر، احراز هویت دستگاه و ابزارهای اتصال مجدد، @openclaw/gateway-client/browser را وارد کنید.

نقطهٔ ورودی Node انتقال WebSocket خود را مدیریت می‌کند. میزبان مرورگر یک آداپتور WebSocket به‌همراه ذخیره‌سازی پایدار و callbackهای امضا برای هویت دستگاه و توکن دستگاه فراهم می‌کند.

انتخاب دامنه‌ها و جفت‌کردن دستگاه

یک کلاینت کامل گفت‌وگوی تعاملی که اعلان‌های تأیید را نیز نمایش می‌دهد، باید role: "operator" را با این دامنه‌ها درخواست کند:

دامنه	کاربرد
`operator.read`	`chat.history`، `sessions.list`، `sessions.subscribe`، وضعیت مدل و رویدادهای فقط‌خواندنی
`operator.write`	`chat.send` و تغییرات معمول نشست
`operator.approvals`	فهرست‌کردن، نمایش و رفع تأییدهای exec یا Plugin

فقط اگر کلاینت پرسش‌های تعاملی را مدیریت می‌کند، operator.questions را اضافه کنید؛ فقط اگر دستگاه‌ها یا Nodeهای جفت‌شده را مدیریت می‌کند، operator.pairing را اضافه کنید؛ و operator.admin را تنها برای عملیات مدیریتی مانند config.patch اضافه کنید. مرجع دامنه‌های اپراتور قواعد کامل متدها و زمان تأیید را تعریف می‌کند.

با ویرایش دستی openclaw.json برای هر کلاینت توکن حامل نسازید. احراز هویت راه‌اندازی مشترک Gateway را با openclaw configure --section gateway یا گزینه‌های openclaw onboard --gateway-auth ... پیکربندی کنید، سپس اجازه دهید جفت‌سازی دستگاه توکن کلاینت را صادر کند:

یک هویت دستگاه Ed25519 را در کلاینت به‌طور پایدار ذخیره کنید.
منتظر connect.challenge بمانید، محتوای دستگاه مقید به چالش را امضا کنید و connect را با نقش اپراتور و دامنه‌های درخواستی، و توکن مشترک Gateway یا گذرواژه برای احراز هویت راه‌اندازی ارسال کنید.
اگر Gateway جزئیات ساختاریافتهٔ PAIRING_REQUIRED را برگرداند، شناسهٔ درخواست را نمایش دهید و مطابق error.details.recommendedNextStep مکث یا تلاش مجدد کنید.
در میزبان Gateway، درخواست را با openclaw devices list بازبینی کنید، سپس دقیقاً همان درخواست جاری را با openclaw devices approve <requestId> تأیید کنید.
دوباره متصل شوید و hello-ok.auth.deviceToken را همراه با نقش و دامنه‌های توافق‌شده به‌طور پایدار ذخیره کنید. برای اتصال‌های بعدی از آن توکن دستگاه استفاده کنید.

ارتقای دامنه یا نقش، درخواست جفت‌سازی معلق جدیدی ایجاد می‌کند. چرخش توکن نمی‌تواند قرارداد جفت‌سازی تأییدشده را گسترش دهد. برای فرمان‌های تأیید، چرخش و لغو، به CLI دستگاه‌ها مراجعه کنید.

اعلام قابلیت‌های کلاینت

connect.params.caps رفتار اختیاری قابل‌استفاده برای کلاینت را توصیف می‌کند. این مورد مجوز اعطا نمی‌کند. به‌جای تکرار رشته‌های ثابت، نام‌ها را از GATEWAY_CLIENT_CAPS وارد کنید:

 const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];

رجیستری کنونی شامل approvals، exec-approvals، inline-widgets، run-tool-bindings، session-scoped-events، plugin-approvals، task-suggestions، terminal-offset-seq، tool-events و ui-commands است. فقط قابلیت‌هایی را اعلام کنید که کلاینت واقعاً پیاده‌سازی می‌کند.

ابزارهای عاملِ مقید به قابلیت، کاربرد جداگانه‌ای از همین اعلان هستند. اگر یک ابزار عامل به قابلیتی از کلاینت نیاز داشته باشد، Gateway آن ابزار را حذف می‌کند، مگر آنکه کلاینت مبدأ همهٔ قابلیت‌های لازم را اعلام کرده باشد.

بازیابی وضعیت پس از اتصال مجدد

هر اتصال مجدد موفق را به‌عنوان تصویری جدید بر تاریخچهٔ پایدار و وضعیت جاری اجرای درون حافظه در نظر بگیرید:

sessions.subscribe و اشتراک sessions.messages.subscribe نشست انتخاب‌شده را دوباره برقرار کنید.
برای sessionKey انتخاب‌شده، chat.history را فراخوانی کنید و ردیف‌های پایدار محلی را با تصویر messages برگشتی جایگزین کنید.
اگر inFlightRun موجود است، runId، text بافرشده و plan اختیاری آن را بپذیرید. حتی وقتی text خالی است، اجرا را بپذیرید.
sessionInfo.hasActiveRun و sessionInfo.activeRunIds را بخوانید. هنگام تصمیم‌گیری دربارهٔ اینکه آیا یک اجرای نگه‌داشته‌شده همچنان مالک رابط کاربری پخش است، عضویت دقیق در activeRunIds را ترجیح دهید. مقدار درست hasActiveRun بدون شناسهٔ فهرست‌شده می‌تواند نمایانگر تصویر فعال زمان اجرای دیگری باشد.
رویدادهای بعدی agent را با payload.runId و payload.seq تطبیق دهید. بالاترین توالی پذیرفته‌شده را برای هر اجرا به‌طور مستقل نگه دارید، توالی دیده‌شده یا پایین‌تر را نادیده بگیرید و فاصلهٔ رو به جلو را دلیلی برای بارگذاری مجدد تاریخچهٔ مرجع در نظر بگیرید.

فریم بیرونی رویداد نیز یک seq اختیاری دارد که رویدادها را در اتصال WebSocket جاری مرتب می‌کند. این مقدار با اتصال جدید بازنشانی می‌شود. seq داخل محتوای رویداد agent به‌ازای هر اجرا تخصیص می‌یابد و چرخهٔ عمر، دستیار، طرح، ابزار و دیگر رویدادهای جریان آن اجرا را مرتب می‌کند.

استفاده از فرادادهٔ تاریخچه و لنگرهای پایدار

ردیف‌های برگشتی از chat.history می‌توانند یک پوشش فرادادهٔ __openclaw داشته باشند:

id هویت ورودی رونوشت است. از آن برای درخواست‌های تاریخچهٔ لنگرشده استفاده کنید، اما نه به‌عنوان کلید یکتای ردیف نمایش.
seq توالی مثبت رکورد رونوشت است. یک رکورد ذخیره‌شده می‌تواند به بیش از یک ردیف نمایش تبدیل شود؛ بنابراین ردیف‌های هم‌خانواده با id و توالی یکسان را کنار هم نگه دارید.
kind ردیف‌های مصنوعی را مشخص می‌کند. یک مرز Compaction از kind: "compaction" استفاده می‌کند و اگر checkpoint متناظری آن سنجه‌ها را ثبت کرده باشد، ممکن است شامل tokensBefore و tokensAfter باشد.

با مقادیر hasMore و nextOffset پاسخ، به عقب صفحه‌بندی کنید. offsetهای عددی تصویر جاری رونوشت را توصیف می‌کنند، بنابراین آن‌ها را در طول بازنشانی یا Compaction به‌عنوان نشانک‌های بلندمدت ذخیره نکنید. در عوض __openclaw.id را ذخیره کنید. برای بازیابی پیرامون یک ردیف شناخته‌شده، chat.history را با messageId و sessionIdای که آن را برگردانده است فراخوانی کنید. Gateway می‌تواند آن لنگر را از تاریخچهٔ بایگانی بازنشانی پیدا کند؛ پاسخ‌های لنگرشده عمداً فرادادهٔ صفحه‌بندی عددی را حذف می‌کنند.

اشتراک به‌جای پایش دوره‌ای مصرف

فهرست اولیه را با sessions.list بارگذاری کنید، سپس sessions.subscribe را برای هر اتصال یک‌بار فراخوانی کنید. رویدادهای sessions.changed را بر اساس sessionKey ادغام کنید. محتوای تغییر نشست می‌تواند شامل inputTokens، outputTokens، totalTokens، totalTokensFresh، contextTokens، estimatedCostUsd، تنظیمات مصرف پاسخ و وضعیت اجرای فعال باشد.

برخی اعلان‌های تغییر فقط سیگنال بی‌اعتبارسازی هستند. اگر رویدادی فیلدهای ردیف موردنیاز نمای شما را ندارد، sessions.list را تازه‌سازی کنید. برای به‌روز نگه‌داشتن فهرست زندهٔ نشست‌ها، usage.cost یا sessions.usage را به‌طور دوره‌ای پایش نکنید؛ این متدها را برای گزارش‌های تجمیعی یا تفصیلی برحسب تقاضا نگه دارید.

تکمیل تأییدهای exec

کلاینتی با operator.approvals باید به‌محض تکمیل hello-ok شنوندهٔ رویداد خود را نصب کند، سپس exec.approval.list را برای تکمیل درخواست‌هایی که پیش از اتصال بوده‌اند فراخوانی کند. فهرست و رویدادهای زندهٔ exec.approval.requested / exec.approval.resolved را بر اساس شناسهٔ تأیید تطبیق دهید تا انتقالی که با درخواست فهرست رقابت می‌کند نه از دست برود و نه دوباره زنده شود.

پیگیری نسخه‌های پروتکل

نسخهٔ جاری ارتباطی 4 است. کلاینت‌های عمومی اپراتور و WebChat باید نسخهٔ جاری دقیق را با minProtocol: 4 و maxProtocol: 4 مذاکره کنند. فقط کلاینت‌های Node احرازهویت‌شده و کاوشگرهای سبک بازهٔ پذیرش N-1 را دارند که در حال حاضر پروتکل 3 تا 4 است.

تغییرات پروتکل ابتدا افزایشی هستند. protocol.schema.json شامل فرادادهٔ قدمت انتشار since و فرادادهٔ دامنهٔ الزامی برای متدهای اصلی است، اما افزایش نسخهٔ ارتباطی همچنان یک رویداد ناسازگار صریح برای کلاینت‌های شخص ثالث است. نسخه‌های بسته‌ای را که آزمایش می‌کنید ثابت نگه دارید، هنگام تغییر نسخهٔ ارتباطی کلاینت و Gateway را با هم ارتقا دهید و پیش از هر ارتقا تغییرات OpenClaw را بازبینی کنید.

مرتبط

Was this useful?