---
read_when:
    - Запуск або налагодження процесу Gateway
    - Дослідження забезпечення одноекземплярного режиму
summary: Захист singleton для Gateway за допомогою прив’язки слухача WebSocket
title: Блокування Gateway
x-i18n:
    generated_at: "2026-04-30T15:34:57Z"
    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 і надалі підтримує власний легкий PID-захист перед запуском Gateway; блокування під час виконання забезпечується файлом блокування разом із прив’язуванням HTTP/WebSocket.

## Пов’язане

- [Кілька Gateway](/uk/gateway/multiple-gateways) — запуск кількох екземплярів з унікальними портами
- [Усунення несправностей](/uk/gateway/troubleshooting) — діагностика `EADDRINUSE` і конфліктів портів