---
read_when:
    - تعبیه OpenClaw در یک برنامه دسکتاپ یا سرور
    - نظارت بر Gateway به‌عنوان یک فرایند فرزند
    - مدیریت آمادگی، راه‌اندازی مجدد، خاموش‌سازی یا پیکربندی نامعتبر Gateway بدون واکاوی لاگ‌ها
summary: Gateway متعلق به OpenClaw را به‌عنوان یک فرایند فرزند از Electron یا یک برنامه میزبان دیگر نظارت کنید
title: جاسازی OpenClaw
x-i18n:
    generated_at: "2026-07-27T14:05:57Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: ca67e03994f21446bfeca58c95c2cb624dde767b9983a89982627145f80dfb90
    source_path: gateway/embedding.md
    workflow: 16
---

یک میزبان تعبیه‌کننده باید بر فایل اجرایی نصب‌شدهٔ `openclaw` نظارت کند، از پروتکل WebSocket متعلق به Gateway به‌عنوان صفحهٔ کنترل خود استفاده کند و فرایند فرزند را یک زمان‌اجرای قابل‌جایگزینی در نظر بگیرد. این رویکرد، مالکیت فرایند، آمادگی، بازیابی پس از خرابی و ارتقاها را بدون وابستگی به چیدمان خصوصی وضعیت OpenClaw صریح نگه می‌دارد.

برای احراز هویت کلاینت و وضعیت اتصال مجدد، [ساخت یک کلاینت Gateway](https://docs.openclaw.ai/gateway/clients) را بخوانید.

## فرایند فرزند را با یک پیش‌تنظیم تعبیه‌سازی آغاز کنید

از یک نصب واقعی `node_modules` استفاده کنید و فایل اجرایی بسته را اجرا کنید. یک خط مبنای مناسب برای میزبانی که مالک کشف، راه‌اندازی مجدد و چرخهٔ عمر کانال است، چنین است:

```ts
import { spawn } from "node:child_process";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";

// یک مسیر مطلق به زمان‌اجرای واقعی 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، بر اساس کد خروج شاخه‌بندی کنید:

1. فرمان `openclaw doctor --fix --yes --non-interactive` را با همان محیط پیکربندی و وضعیت فرایند فرزند Gateway اجرا کنید.
2. پس از خروج موفقیت‌آمیز doctor، راه‌اندازی Gateway را یک بار دیگر امتحان کنید.
3. اگر فرایند فرزند دوباره با `78` خارج شد، حلقهٔ اصلاح را متوقف کنید و خطای پیکربندی را به کاربر نمایش دهید.

stderr را برای عیب‌یابی نگه دارید، اما تصمیم‌های چرخهٔ عمر را بر اساس عبارت‌بندی آن نگیرید.

پس از راه‌اندازی موفق، یک ویرایش نامعتبر در پیکربندی زنده اثر تخریبی کمتری دارد. ناظر پیکربندی ثبت می‌کند که بارگذاری مجدد رد شده است و ارائهٔ سرویس را با آخرین پیکربندی درون‌حافظه‌ای پذیرفته‌شده ادامه می‌دهد. فایل را اصلاح کنید، سپس اجازه دهید ناظر snapshot معتبر بعدی را بپذیرد.

## منتظر آمادگی پروتکل بمانید

به‌جای یک زیررشتهٔ گزارش، از سیگنال‌های WebSocket استفاده کنید:

1. WebSocket متعلق به Gateway را باز کنید.
2. منتظر رویداد `connect.challenge` بمانید. این رویداد ثابت می‌کند که شنونده، WebSocket را پذیرفته و handshake چالش می‌تواند آغاز شود.
3. فرمان `connect` را همراه با امضای دستگاه متصل به چالش ارسال کنید.
4. رویداد `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 نکنید.

## مرتبط

- [ساخت یک کلاینت Gateway](https://docs.openclaw.ai/gateway/clients)
- [پروتکل Gateway](https://docs.openclaw.ai/gateway/protocol)
- [CLI متعلق به Gateway](https://docs.openclaw.ai/cli/gateway)
- [یکپارچه‌سازی‌های Gateway برای برنامه‌های خارجی](https://docs.openclaw.ai/gateway/external-apps)