diff --git a/docs/gateway/health.md b/docs/gateway/health.md index f0a86f70e511..c6e1247b0568 100644 --- a/docs/gateway/health.md +++ b/docs/gateway/health.md @@ -42,6 +42,21 @@ health commands above for live connectivity checks. - `channels..accounts..healthMonitor.enabled`: multi-account override that wins over the channel-level setting. - These per-channel overrides apply to the built-in channel monitors that expose them today: Discord, Google Chat, iMessage, Microsoft Teams, Signal, Slack, Telegram, and WhatsApp. +## Uptime monitoring + +External uptime monitoring services should use the dedicated `/health` endpoint, not `/v1/chat/completions`. + +- **DO use:** `GET /health` — instant response, no session created, no LLM call, returns `{"ok":true,"status":"live"}` +- **DON'T use:** `/v1/chat/completions` for health checks — each request creates a full agent session with skill snapshot, context assembly, and LLM calls + +When no `x-openclaw-session-key` header or `user` field is provided, `/v1/chat/completions` generates a new random session for each request. Monitoring services that ping every 15 minutes create ~96 sessions/day, each consuming 4–22KB. Over time this causes session store bloat and can lead to context window overflow. + +### Monitoring service setup examples + +- **BetterStack:** Set health check URL to `https://:/health` +- **UptimeRobot:** Add a new HTTP monitor with URL `https://:/health` +- **Generic:** Any HTTP GET to `/health` returns 200 with `{"ok":true}` when the gateway is healthy + ## When something fails - `logged out` or status 409–515 → relink with `openclaw channels logout` then `openclaw channels login`.