mirror of
https://github.com/openclaw/openclaw.git
synced 2026-04-04 13:51:30 +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
1.8 KiB
1.8 KiB
summary, read_when, title
| summary | read_when | title | ||
|---|---|---|---|---|
| Gateway singleton guard using the WebSocket listener bind |
|
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 throwsGatewayLockError("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 — running multiple instances with unique ports
- Troubleshooting — diagnosing
EADDRINUSEand port conflicts