---
read_when:
    - اجرای فرایند Gateway یا اشکال‌زدایی آن
    - بررسی اعمال تک‌نمونه‌ای
summary: محافظ تک‌نمونهٔ Gateway با استفاده از اتصال شنوندهٔ WebSocket
title: قفل Gateway
x-i18n:
    generated_at: "2026-04-30T16:29:35Z"
    model: gpt-5.5
    provider: openai
    source_hash: 85a1cb55f08d47d36fde25900e4247ef01c9a6800bf017fbff44a337f299ce13
    source_path: gateway/gateway-lock.md
    workflow: 16
---

## چرا

- اطمینان حاصل کنید که روی همان میزبان، برای هر پورت پایه فقط یک نمونه Gateway اجرا می‌شود؛ Gatewayهای اضافی باید از پروفایل‌های ایزوله و پورت‌های یکتا استفاده کنند.
- پس از کرش/SIGKILL بدون باقی گذاشتن فایل‌های قفل کهنه، دوام بیاورد.
- وقتی پورت کنترل از قبل اشغال شده است، با خطایی روشن سریع شکست بخورد.

## سازوکار

- Gateway ابتدا یک فایل قفل برای هر پیکربندی را زیر دایرکتوری قفل وضعیت می‌گیرد و پورت پیکربندی‌شده را برای وجود یک شنونده فعلی بررسی می‌کند.
- اگر مالک قفل ثبت‌شده دیگر وجود نداشته باشد، پورت آزاد باشد، یا قفل کهنه باشد، راه‌اندازی قفل را بازپس می‌گیرد و ادامه می‌دهد.
- سپس Gateway شنونده HTTP/WebSocket را (پیش‌فرض `ws://127.0.0.1:18789`) با استفاده از یک شنونده TCP انحصاری متصل می‌کند.
- اگر اتصال با `EADDRINUSE` شکست بخورد، راه‌اندازی `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")` را پرتاب می‌کند.
- هنگام خاموشی، Gateway سرور HTTP/WebSocket را می‌بندد و فایل قفل را حذف می‌کند.

## سطح خطا

- اگر فرایند دیگری پورت را در اختیار داشته باشد، راه‌اندازی `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")` را پرتاب می‌کند.
- سایر شکست‌های اتصال به صورت `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")` نمایان می‌شوند.

## نکات عملیاتی

- اگر پورت توسط فرایند _دیگری_ اشغال شده باشد، خطا یکسان است؛ پورت را آزاد کنید یا با `openclaw gateway --port <port>` پورت دیگری انتخاب کنید.
- زیر یک ناظر سرویس، فرایند Gateway جدیدی که یک پاسخ‌دهنده سالم فعلی `/healthz` را می‌بیند، کنترل را در اختیار همان فرایند می‌گذارد. در systemd، راه‌انداز تکراری با کد 78 خارج می‌شود تا مقدار پیش‌فرض `RestartPreventExitStatus=78` مانع شود `Restart=always` در برخورد با قفل یا تداخل `EADDRINUSE` وارد حلقه شود. اگر فرایند موجود هرگز سالم نشود، تلاش‌های دوباره محدود می‌شوند و راه‌اندازی به‌جای حلقه بی‌پایان، با خطای قفل روشن شکست می‌خورد.
- برنامه macOS همچنان پیش از ایجاد Gateway محافظ PID سبک خودش را نگه می‌دارد؛ قفل زمان اجرا با فایل قفل به‌علاوه اتصال HTTP/WebSocket اعمال می‌شود.

## مرتبط

- [چند Gateway](/fa/gateway/multiple-gateways) — اجرای چند نمونه با پورت‌های یکتا
- [عیب‌یابی](/fa/gateway/troubleshooting) — تشخیص `EADDRINUSE` و تداخل‌های پورت