Gateway
جاسازی OpenClaw
یک میزبان تعبیهکننده باید بر فایل اجرایی نصبشدهٔ openclaw نظارت کند، از پروتکل WebSocket متعلق به Gateway بهعنوان صفحهٔ کنترل خود استفاده کند و فرایند فرزند را یک زماناجرای قابلجایگزینی در نظر بگیرد. این رویکرد، مالکیت فرایند، آمادگی، بازیابی پس از خرابی و ارتقاها را بدون وابستگی به چیدمان خصوصی وضعیت OpenClaw صریح نگه میدارد.
برای احراز هویت کلاینت و وضعیت اتصال مجدد، ساخت یک کلاینت Gateway را بخوانید.
فرایند فرزند را با یک پیشتنظیم تعبیهسازی آغاز کنید
از یک نصب واقعی node_modules استفاده کنید و فایل اجرایی بسته را اجرا کنید. یک خط مبنای مناسب برای میزبانی که مالک کشف، راهاندازی مجدد و چرخهٔ عمر کانال است، چنین است:
// یک مسیر مطلق به زماناجرای واقعی Node که برنامهٔ میزبان آن را مدیریت میکند، ارائه دهید.declare const hostNodeExecutable: string; const packageEntry = fileURLToPath(import.meta.resolve("openclaw"));const openclawEntry = resolve(dirname(packageEntry), "..", "openclaw.mjs");const gateway = spawn(hostNodeExecutable, [openclawEntry, "gateway", "--allow-unconfigured"], { env: { ...process.env, OPENCLAW_DISABLE_BONJOUR: "1", OPENCLAW_EXEC_SHELL_SNAPSHOT: "0", OPENCLAW_NO_RESPAWN: "1", OPENCLAW_SKIP_CHANNELS: "1", }, stdio: ["ignore", "inherit", "inherit"],});همانطور که نشان داده شده است، OpenClaw را از طریق بستهٔ نصبشده resolve کنید؛ فرض نکنید که یک فایل باینری محلی پروژه با نام openclaw در PATH فرایند میزبان قرار دارد. مثال، خروجی را به ارث میبرد تا فرایند فرزند بر اثر پرشدن پایپهای stdout یا stderr مسدود نشود. اگر میزبان بهجای آن این جریانها را دریافت میکند، بلافاصله پس از ایجاد فرایند، مصرفکنندهها را متصل کنید.
| تنظیم | اثر تعبیهسازی |
|---|---|
OPENCLAW_DISABLE_BONJOUR=1 |
وقتی میزبان مالک کشف است، تبلیغات multicast شبکهٔ LAN تحت مالکیت Gateway را غیرفعال میکند. |
OPENCLAW_NO_RESPAWN=1 |
در یک فرایند فرزند تعبیهشده و مدیریتنشده، مانع از آن میشود که OpenClaw راهاندازی مجدد پس از بهروزرسانی را به یک فرایند فرزند جداشده واگذار کند. راهاندازیهای مجدد عادی در همان فرایند باقی میمانند، بنابراین میزبان مالکیت PID تحت پیگیری را حفظ میکند. |
OPENCLAW_EXEC_SHELL_SNAPSHOT=0 |
ثبت snapshot پوستهٔ ورود برای فرمانهای exec میزبان را غیرفعال میکند. |
OPENCLAW_SKIP_CHANNELS=1 |
راهاندازی و بارگذاری مجدد کانال را رد میکند. آن را فقط زمانی تنظیم کنید که برنامهٔ تعبیهکننده یک Gateway صرفاً برای صفحهٔ کنترل یا WebChat میخواهد. |
--allow-unconfigured فقط محافظ راهاندازی gateway.mode=local را دور میزند. این گزینه پیکربندی را نمینویسد و فایل نامعتبر را اصلاح نمیکند. وقتی برنامهٔ تعبیهکننده از طریق فرایند onboarding، CLI پیکربندی یا RPC متعلق به Gateway یک پیکربندی محلی عادی فراهم میکند، آن را حذف کنید.
هشدار snapshot پوسته در Electron
ثبت snapshot پوسته، process.execPath -e <script> را از یک پوستهٔ ورود اجرا میکند. در یک فرایند عادی Node، process.execPath فایل اجرایی Node است. در Electron، این مقدار فایل باینری Electron است که ممکن است فراخوانی را بهعنوان اجرای برنامه تفسیر کند و پنجرهٔ بازشوی «Unable to find Electron app» را نمایش دهد. OPENCLAW_EXEC_SHELL_SNAPSHOT=0 را در محیط فرایند فرزند Gateway تنظیم کنید، نه فقط در فرایند renderer. به همین دلیل، hostNodeExecutable باید به یک زماناجرای واقعی Node اشاره کند، نه process.execPath متعلق به Electron.
پیکربندی نامعتبر را بر اساس کد خروج مدیریت کنید
راهاندازی Gateway برای خطاهای راهاندازی از نوع پیکربندی، از جمله پیکربندی نامعتبر، از کد خروج 78 (EX_CONFIG) استفاده میکند. بهجای استخراج متن قابلخواندن stderr، بر اساس کد خروج شاخهبندی کنید:
- فرمان
openclaw doctor --fix --yes --non-interactiveرا با همان محیط پیکربندی و وضعیت فرایند فرزند Gateway اجرا کنید. - پس از خروج موفقیتآمیز doctor، راهاندازی Gateway را یک بار دیگر امتحان کنید.
- اگر فرایند فرزند دوباره با
78خارج شد، حلقهٔ اصلاح را متوقف کنید و خطای پیکربندی را به کاربر نمایش دهید.
stderr را برای عیبیابی نگه دارید، اما تصمیمهای چرخهٔ عمر را بر اساس عبارتبندی آن نگیرید.
پس از راهاندازی موفق، یک ویرایش نامعتبر در پیکربندی زنده اثر تخریبی کمتری دارد. ناظر پیکربندی ثبت میکند که بارگذاری مجدد رد شده است و ارائهٔ سرویس را با آخرین پیکربندی درونحافظهای پذیرفتهشده ادامه میدهد. فایل را اصلاح کنید، سپس اجازه دهید ناظر snapshot معتبر بعدی را بپذیرد.
منتظر آمادگی پروتکل بمانید
بهجای یک زیررشتهٔ گزارش، از سیگنالهای WebSocket استفاده کنید:
- WebSocket متعلق به Gateway را باز کنید.
- منتظر رویداد
connect.challengeبمانید. این رویداد ثابت میکند که شنونده، WebSocket را پذیرفته و handshake چالش میتواند آغاز شود. - فرمان
connectرا همراه با امضای دستگاه متصل به چالش ارسال کنید. - رویداد
hello-okرا آمادگی برنامه برای RPC احرازشده در نظر بگیرید.
چالش عمداً پیش از مقداردهی اولیهٔ کامل رخ میدهد. اگر فرایندهای جانبی راهاندازی همچنان در انتظار باشند، connect یک خطای قابلتلاشمجدد UNAVAILABLE با details.reason: "startup-sidecars" و یک retryAfterMs محدود برمیگرداند و سپس با کد 1013 و دلیل gateway starting بسته میشود. از resolveGatewayStartupRetryAfterMs در @openclaw/gateway-protocol/startup-unavailable یا سیاست داخلی کلاینت مرجع استفاده کنید، سپس دوباره متصل شوید.
راهاندازی مجدد و خاموششدن را تفسیر کنید
پیش از بستهشدن منظم، Gateway یک رویداد shutdown را همراه با reason و restartExpectedMs پخش میکند. restartExpectedMs غیرتهی به این معناست که راهاندازی مجدد درونفرایندی یا تحت نظارت انتظار میرود؛ null به معنای خاموششدن نهایی است.
کد بستهشدن بعدی WebSocket برای هر دو حالت 1012 است. دلیل عادی بستهشدن کلاینت نیز در هر دو حالت service restart است، بنابراین نه کد بستهشدن و نه دلیل آن، راهاندازی مجدد را از خاموششدن متمایز نمیکند. اگر payload پیشین shutdown رسید، آن را حفظ کنید و با قصد توقف خود میزبان و وضعیت خروج فرایند فرزند ترکیب کنید. اگر اتصال بدون این رویداد قطع شد، از سیاست عادی اتصال مجدد محدود و نظارت بر فرایند فرزند استفاده کنید.
بهجای فایلهای وضعیت از RPC استفاده کنید
Gateway را تنها مالک وضعیت OpenClaw نگه دارید. عملیات رایج تعبیهسازی از قبل متدهای RPC دارند:
| وظیفه | متدهای RPC |
|---|---|
| فهرست و چرخهٔ عمر نشستها | sessions.list, sessions.patch, sessions.delete |
| نمایش رونوشت | chat.history |
| گزارشهای هزینه و میزان مصرف | usage.cost, sessions.usage |
| وضعیت اعتبارنامهٔ مدل | models.authStatus |
| پیکربندی | config.get, config.patch |
config.get پیش از بازگرداندن snapshot، مقادیر حساس و شناسههای SecretRef را حذف میکند. متدهای نوشتن نیز پیکربندی حذفشده را برمیگردانند. کلاینت باید نشانهٔ حذف را غیرشفاف در نظر بگیرد و از قرارداد مستندشدهٔ نوشتن پیکربندی استفاده کند؛ هرگز نباید انتظار داشته باشد Gateway اسرار متن ساده را بازگرداند.
برای پیادهسازی قابلیتهای برنامه، فایلها، جدولهای SQLite، فایلهای رونوشت یا دایرکتوریهای cache زیر ~/.openclaw را نخوانید یا تغییر ندهید. این چیدمانها جزئیات خصوصی پیادهسازی زماناجرا هستند و میتوانند بدون سازگاری پروتکل جابهجا یا تغییر داده شوند.
نصب کنید؛ مسطح نکنید
بستهٔ ریشهٔ openclaw هدفی برای vendor کردن بهصورت تکفایل نیست. فایلهای زماناجرای همراه در dist/extensions، self-importهای بدون مسیر مانند openclaw/plugin-sdk/* را حفظ میکنند، در حالی که بستهٔ npm عمداً درختهای node_modules مربوط به هر افزونه را حذف میکند.
OpenClaw را از طریق npm، pnpm یا یک نصب عادی دیگر بستههای Node نصب کنید تا Node بتواند exportهای بسته و درخت وابستگی ریشه را resolve کند. فایل اجرایی نصبشدهٔ openclaw را اجرا کنید. فقط dist را کپی نکنید، بسته را در یک bundle برنامه مسطح نکنید و فایلهای منتخب افزونه را vendor نکنید.
