feat(gateway): add HTTP health check endpoints and Cloudflare Tunnel docs

Add unauthenticated /healthz and /health endpoints for load balancer probes.
Returns {"status":"ok"} with HTTP 200 when the gateway is running.

Also adds documentation for:
- Cloudflare Tunnel as an alternative to Tailscale for secure gateway exposure
- Health check endpoint usage for K8s, AWS ALB, and Cloudflare monitoring

Closes #1971

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
GlucksbergandClaude Opus 4.5 committed 2026-01-30 14:48:50 +00:00
1 parent e38ae0eda5
commit b3533ac0be
3 files changed
+88 -1

No files matched your search

+55 -1
View File
@@ -446,7 +446,61 @@ Avoid:
- Exposing relay/control ports over LAN or public Internet.
- Tailscale Funnel for browser control endpoints (public exposure).
### 0.7) Secrets on disk (what’s sensitive)
### 0.6.2) Cloudflare Tunnel (alternative to Tailscale)
[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) provides another way to expose your Gateway securely without opening firewall ports. The tunnel runs a local daemon (`cloudflared`) that connects outbound to Cloudflare's edge, then routes traffic to your local Gateway.
**Quick tunnel (ephemeral, for testing):**
```bash
# Install cloudflared (https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)
brew install cloudflared # macOS
# or: sudo apt install cloudflared # Debian/Ubuntu
# Start a quick tunnel (generates a random *.trycloudflare.com URL)
cloudflared tunnel --url http://127.0.0.1:18789
```
**Persistent tunnel (recommended for production):**
1. Authenticate: `cloudflared tunnel login`
2. Create tunnel: `cloudflared tunnel create clawdbot-gateway`
3. Configure `~/.cloudflared/config.yml`:
```yaml
tunnel: <tunnel-id>
credentials-file: /path/to/credentials.json
ingress:
- hostname: gateway.yourdomain.com
service: http://127.0.0.1:18789
- service: http_status:404
```
4. Route DNS: `cloudflared tunnel route dns clawdbot-gateway gateway.yourdomain.com`
5. Run: `cloudflared tunnel run clawdbot-gateway`
**Security notes:**
- Always set `gateway.auth.mode: "token"` when exposing via Cloudflare Tunnel.
- Use Cloudflare Access policies for additional authentication (SSO, email verification).
- The Gateway binds to loopback; only `cloudflared` can reach it.
- Monitor tunnel metrics in the Cloudflare dashboard.
### 0.6.3) Health check endpoint
The Gateway exposes unauthenticated health check endpoints for load balancer probes:
- `GET /healthz` - Returns `{"status":"ok"}` with HTTP 200 when the Gateway is running.
- `GET /health` - Alias for `/healthz`.
These endpoints:
- Do **not** require authentication (safe for external probes).
- Do **not** expose any sensitive information.
- Return `Cache-Control: no-cache, no-store` to prevent caching.
Use these for Kubernetes liveness/readiness probes, AWS ALB health checks, or Cloudflare origin health monitoring.
### 0.7) Secrets on disk (what's sensitive)
Assume anything under `~/.openclaw/` (or `$OPENCLAW_STATE_DIR/`) may contain secrets or private data: