Gateway lock

기준일: 2026-07-26
공식 기준: Gateway lock

Gateway lock 문서는 OpenClaw 공식 문서(gateway/gateway-lock)를 한국어로 정리한 가이드입니다. Gateway singleton guard: file lock plus WebSocket/HTTP bind 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Gateway singleton guard: file lock plus WebSocket/HTTP bind

한국어 가이드 범위: gateway/gateway-lock 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Why
Three layers
State and config locks
Socket bind
Operational notes
관련 문서

상세 내용

Why

주요 항목:

Only one gateway process should own a state directory; run additional gateways with isolated profiles, state directories, configs, and ports.
Survive crashes/SIGKILL without leaving stale lock files behind.
Fail fast with a clear error when another gateway already owns the port.

Three layers

Startup enforces ownership in three steps, in order:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

State and config locks

주요 항목:

Lock liveness comes from the recorded PID, platform process start identity when available, and Gateway process identity. A verified owner remains authoritative during startup before its port begins listening.
A dedicated SQLite coordinator serializes metadata inspection, stale-owner reclamation, and lock replacement. Its exclusive transaction is released automatically if the owning process crashes.
If a lock file is missing or the recorded owner process is gone, startup reclaims the lock and continues.
If either lock is actively held, startup retries for up to 5 seconds (default) before giving up:

GatewayLockError("gateway already running (pid <pid>); lock timeout after <ms>ms")

Socket bind

On shutdown, the gateway closes the HTTP/WebSocket server and removes its state and config lock files.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

On EADDRINUSE, startup retries the bind for up to 20 attempts at 500ms intervals (roughly 10 seconds total) to ride out a TIME_WAIT window after a recently exited process.
If the port is still in use after retries:
Other bind failures:

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>: <cause>")

Operational notes

주요 항목:

If the port is occupied by a different, non-gateway process, the error is the same; free the port or choose another with openclaw gateway --port <port>.
OPENCLAW_ALLOW_MULTI_GATEWAY=1 permits multiple config/runtime instances, not shared mutable state. Each instance still needs a unique OPENCLAW_STATE_DIR.
Under a service supervisor, a new gateway process that hits either error above first probes /healthz on the existing process. If that process is healthy, the new process leaves it in control instead of failing. On systemd, it exits with code 78; the unit's RestartPreventExitStatus=78 stops Restart=always from looping on a lock or EADDRINUSE conflict. If the existing process never becomes healthy, the health-probe retry is time-bounded and startup then fails with the lock error above instead of looping forever.
The macOS app keeps its own lightweight PID guard before spawning the gateway; the file lock and socket bind above are the actual runtime enforcement.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/gateway-lock
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

GatewayLockError("gateway already running (pid <pid>); lock timeout after <ms>ms")

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>: <cause>")

Gateway lock

기준일: 2026-07-26
공식 기준: Gateway lock

핵심 요약

Gateway singleton guard: file lock plus WebSocket/HTTP bind

한국어 가이드 범위: gateway/gateway-lock 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Why
Three layers
State and config locks
Socket bind
Operational notes
관련 문서

상세 내용

Why

주요 항목:

Only one gateway process should own a state directory; run additional gateways with isolated profiles, state directories, configs, and ports.
Survive crashes/SIGKILL without leaving stale lock files behind.
Fail fast with a clear error when another gateway already owns the port.

Three layers

Startup enforces ownership in three steps, in order:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

State and config locks

주요 항목:

Lock liveness comes from the recorded PID, platform process start identity when available, and Gateway process identity. A verified owner remains authoritative during startup before its port begins listening.
A dedicated SQLite coordinator serializes metadata inspection, stale-owner reclamation, and lock replacement. Its exclusive transaction is released automatically if the owning process crashes.
If a lock file is missing or the recorded owner process is gone, startup reclaims the lock and continues.
If either lock is actively held, startup retries for up to 5 seconds (default) before giving up:

GatewayLockError("gateway already running (pid <pid>); lock timeout after <ms>ms")

Socket bind

On shutdown, the gateway closes the HTTP/WebSocket server and removes its state and config lock files.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

On EADDRINUSE, startup retries the bind for up to 20 attempts at 500ms intervals (roughly 10 seconds total) to ride out a TIME_WAIT window after a recently exited process.
If the port is still in use after retries:
Other bind failures:

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>: <cause>")

Operational notes

주요 항목:

If the port is occupied by a different, non-gateway process, the error is the same; free the port or choose another with openclaw gateway --port <port>.
OPENCLAW_ALLOW_MULTI_GATEWAY=1 permits multiple config/runtime instances, not shared mutable state. Each instance still needs a unique OPENCLAW_STATE_DIR.
Under a service supervisor, a new gateway process that hits either error above first probes /healthz on the existing process. If that process is healthy, the new process leaves it in control instead of failing. On systemd, it exits with code 78; the unit's RestartPreventExitStatus=78 stops Restart=always from looping on a lock or EADDRINUSE conflict. If the existing process never becomes healthy, the health-probe retry is time-bounded and startup then fails with the lock error above instead of looping forever.
The macOS app keeps its own lightweight PID guard before spawning the gateway; the file lock and socket bind above are the actual runtime enforcement.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/gateway-lock
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

GatewayLockError("gateway already running (pid <pid>); lock timeout after <ms>ms")

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>: <cause>")

Gateway lock

핵심 요약

문서 구성

상세 내용

Why

Three layers

State and config locks

Socket bind

Operational notes

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Gateway lock

핵심 요약

문서 구성

상세 내용

Why

Three layers

State and config locks

Socket bind

Operational notes

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드