openclaw - 💡(How to fix) Fix agents.create triggers gateway restart, breaking in-flight calls (~1.5–2s port unavailability) [1 comments, 2 participants]

Summary

When a backend client calls agents.create over WebSocket, the gateway writes the new agent's auth token to <state>/devices/paired.json. The config-watcher detects this change and concludes a gateway restart is needed; SIGUSR1 fires immediately, the gateway shuts down cleanly, then re-binds — closing port 18789 for ~1.5–2 seconds.

Any in-flight HTTP or WS calls during that window fail with Connection closed (WS — pending requests rejected when the socket closes) or ECONNREFUSED (HTTP — port not listening). The client can't tell the gateway did this to itself, so the failures look like a genuine outage.

Repro

1. Backend with operator scopes connects via WS.
2. Backend issues agents.create for a new agent, immediately followed by agents.files.set for several workspace files (e.g. SOUL.md, IDENTITY.md, USER.md, MEMORY.md) and a POST /v1/chat/completions.
3. The follow-up calls fail.

Gateway log timeline

18:15:11.366  Config overwrite: paired.json (sha256 → new)
18:15:12.224  [ws] ⇄ res ✓ agents.create 4758ms
18:15:12.230  [reload] config change detected; evaluating reload
              (gateway.auth.token, gateway.tailscale, agents.list, meta.lastTouchedAt)
18:15:12.237  [reload] config change requires gateway restart
              (gateway.auth.token, gateway.tailscale)
18:15:12.241  [gateway] signal SIGUSR1 received
18:15:12.666  [shutdown] completed cleanly in 371ms
              ⏤ port 18789 closed ⏤
18:15:14.231  [gateway] starting HTTP server...
18:15:15.281  [gateway] ready

~1.6 s of port closure on a routine "add a token" operation.

Why this is a bug

• agents.create is on the hot path for any multi-tenant deployment (one gateway hosting many users' agents). Every new user / re-provision pays the restart tax.
• Token addition is logically additive; the running process should be able to absorb it without restarting.
• gateway.tailscale showing in the reload diff is suspicious — adding an agent token shouldn't dirty Tailscale config.

Proposed fixes (any of)

1. Don't restart on agent-token additions. A new entry in paired.json[].tokens.operator shouldn't require a re-bind. The runtime can re-read the trusted-token table on the next handshake.
2. Drain in-flight calls before closing the port. Keep the listener up until pending requests drain (or a short timeout), then re-bind.
3. Atomic restart — bring the new instance up on a different ephemeral port, hand off via SO_REUSEPORT or socket-passing, then close the old listener. No window of zero-listeners.

(1) is the cleanest. (2) is the smallest change that fixes user-visible impact.

Workaround

Clients can wrap WS/HTTP calls in retry-with-backoff to mask the window, but that's a per-client fix and adds latency to every legitimate failure too. Fixing it at the gateway is the right place.

Environment

• OpenClaw image built from main (commit 47009dd7)
• Container running on GCE Container-Optimized OS
• Gateway started with agents.defaults.skipBootstrap: true, pre-shared device pairing