mirror of
https://github.com/openclaw/openclaw.git
synced 2026-04-07 07:11:06 +00:00
637f15375b
- cli-backends.md: remove duplicate modelAliases key - discovery.md: add missing transport=gateway and displayName TXT keys - authentication.md: retitle to "Authentication (Model Providers)", add disambiguation Note pointing to gateway connection auth docs - health.md: expand frontmatter scope, add --probe flag and response shape docs - gateway-lock.md: remove stale hardcoded date, add Related section - troubleshooting.md: fix wrong auth cross-link (model auth -> gateway config) - logging.md: add Related section linking to gateway logging internals
38 lines
1.8 KiB
Markdown
38 lines
1.8 KiB
Markdown
---
|
|
summary: "Gateway singleton guard using the WebSocket listener bind"
|
|
read_when:
|
|
- Running or debugging the gateway process
|
|
- Investigating single-instance enforcement
|
|
title: "Gateway Lock"
|
|
---
|
|
|
|
# Gateway lock
|
|
|
|
## Why
|
|
|
|
- Ensure only one gateway instance runs per base port on the same host; additional gateways must use isolated profiles and unique ports.
|
|
- Survive crashes/SIGKILL without leaving stale lock files.
|
|
- Fail fast with a clear error when the control port is already occupied.
|
|
|
|
## Mechanism
|
|
|
|
- The gateway binds the WebSocket listener (default `ws://127.0.0.1:18789`) immediately on startup using an exclusive TCP listener.
|
|
- If the bind fails with `EADDRINUSE`, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
|
|
- The OS releases the listener automatically on any process exit, including crashes and SIGKILL—no separate lock file or cleanup step is needed.
|
|
- On shutdown the gateway closes the WebSocket server and underlying HTTP server to free the port promptly.
|
|
|
|
## Error surface
|
|
|
|
- If another process holds the port, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
|
|
- Other bind failures surface as `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
|
|
|
|
## Operational notes
|
|
|
|
- If the port is occupied by _another_ process, the error is the same; free the port or choose another with `openclaw gateway --port <port>`.
|
|
- The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the WebSocket bind.
|
|
|
|
## Related
|
|
|
|
- [Multiple Gateways](/gateway/multiple-gateways) — running multiple instances with unique ports
|
|
- [Troubleshooting](/gateway/troubleshooting) — diagnosing `EADDRINUSE` and port conflicts
|