Once OpenClaw Gateway is stable, microservice teams still need a clear plan for API gateways, service discovery, circuit breaking, and multi-model intelligent routing. This article is for teams writing those concerns into production ADRs: seven review landmines that confuse Gateway reachability with gateway-grade governance, a responsibility matrix that separates Kong/Traefik from OpenClaw, and a six-step runbook (registration, health checks, routing templates, breaker tuning, observability, rollback). It also explains how to read this alongside the on-site modelRouting, Gateway security, and production observability posts.
OpenClaw excels at session orchestration, toolchains, and model routing policy. Microservices still need north/south identity, east/west authz, quotas, circuit breaking, canaries, and sticky assumptions. Use the checklist below before architecture sign-off so operations do not chase the wrong logs.
Equating HTTP forwarding with an API gateway: without unified auth, rate limits, WAF, audit fields, and tenant isolation you only added another hop.
Ignoring discovery churn: if Kubernetes or Consul instance churn does not refresh health state and route tables, intermittent 502s are misread as "the model is down".
Guessing breaker thresholds: mismatched error windows and minimum sample sizes either trip breakers on low traffic services or react too late during spikes.
Keeping multi-model routing only in prompts: business prompts cannot replace modelRouting and quota policy in openclaw.json; read the modelRouting article.
Stacking Kong/Traefik and Gateway into blind double routing: when both layers rewrite paths and timeouts, incidents become undebuggable.
Process-only metrics: without labels such as route_id, tenant, and model_backend, Prometheus only shows high CPU, not which route is burning quota.
Hardening only inside the Gateway mesh: networkPolicy, dmPolicy, exec approvals, and token rotation must align with the edge gateway; compare the security hardening guide.
The shared root cause is mixing reachability with governability: the first answers whether a request can enter Gateway; the second answers which route, quota, degradation path, and audit trail apply. Capture both in ADRs, then use the matrix below to pin boundaries.
If you already maintain not ready and gateway closed (1000) runbooks, treat this article as the traffic-governance volume: after startup and session issues are ruled out, return to routing, breakers, and edge collaboration.
Pair with the observability article: routing changes need canaries and rollback notes or a single evening deploy can breach SLO.
There is no silver bullet: first decide which layer owns tenant identity and which layer owns model and tool policy, then place timeouts, retries, and idempotency keys accordingly. Write three SLAs into the review: P95 latency, explainability of errors, and recovery time after a breaker opens.
| Concern | Kong / Traefik (edge) | OpenClaw Gateway (AI orchestration) |
|---|---|---|
| Auth and tenant | JWT, mTLS, OAuth2, API keys, tenant routing | Consumes upstream identity; enforces dmPolicy / session rules |
| Rate limits and quotas | Global or per-tenant QPS, burst buckets, IP reputation | Model concurrency, context budgets, tool-call quotas |
| Routing target | Service names, versions, canary weights | Model aliases, tool allowlists, session affinity hints |
| Breaker and fallback | Upstream HTTP error rates, connect timeouts | Model backend outages, tool timeouts, context overflow |
| Observability | Access logs, trace ID injection | Routing decision logs, model switch reasons, tool latency |
| Typical failures | Certificates, SNI, WAF false positives | Routing thresholds, quotas, RPC scope |
The edge API gateway sells north/south governance; OpenClaw sells the merge of session, model, and tool planes. When stacked, you must document who mutates packets first and who owns retries.
If you offload heavy toolchains to a dedicated remote Mac node, keep separate routing tables for model calls versus xcodebuild / CLI execution: the first cares about quotas and latency, the second about SSH and disk.
Use the OpenClaw category list to build shared context across install, Docker, systemd, observability, and security before stitching this architecture.
The sequence stresses registration and health first, then edge routing, then model routing templates, then breaker tuning, then telemetry and rollback. It mirrors the official "first 60 seconds" flow but closes the dual-gateway collaboration blind spot.
Assign a stable service_id per Gateway instance: register in Consul, etcd, or a Kubernetes Service with a read-only health endpoint; avoid pod-IP hardcoding.
Declare upstream pools at the edge: Kong upstreams or Traefik services pointing to N Gateway pods; enable active or passive health checks and minimum ready replicas.
Move model aliases and routing thresholds into openclaw.json: align semantics with the modelRouting article; the edge should only forward headers such as X-Route-Profile.
Use different breaker windows for tools versus model HTTP: long-tail tools and short model calls should not share one window or you will misfire.
Propagate trace IDs from the edge into Gateway logs: one user request should chain Kong to OpenClaw to the model vendor; align fields with the observability article.
Game-day "single instance down" and "model vendor outage": validate edge backoff and in-Gateway degradation; snapshot configs and image digests before changes.
{
"modelRouting": {
"default": "fast",
"profiles": {
"fast": { "maxContextTokens": 32000, "preferProviders": ["anthropic"] },
"heavy": { "maxContextTokens": 200000, "preferProviders": ["anthropic"] }
},
"rules": [
{ "when": { "header": { "name": "X-Route-Profile", "equals": "heavy" } }, "use": "heavy" }
]
},
"gateway": {
"bind": "127.0.0.1:18789",
"requestTimeoutMs": 120000
}
}
Note: if you change gateway.bind or reverse-proxy paths, re-check loopback and token combinations in the security hardening guide to avoid "edge looks healthy while inner layer rejects".
After upgrades, if some tenants drift while the edge stays green, suspect config sharding and instance caches: rerun openclaw doctor before rewriting prompts.
Pair with gateway closed (1000): close frames in logs mean session scope and tokens first, not edge timeouts.
A common incident pattern is edge stickiness fighting stateful Gateway assumptions: the load balancer treats traffic as stateless HTTP while Gateway caches session fragments locally. Start with single-instance load tests to validate routing templates, then enable multiple instances with consistent hashing.
For Kong/Traefik, verify health check intervals, whether passive breakers are too aggressive, and whether retries amplify outages; align OpenClaw tool allowlists and networkPolicy with least privilege from the security article.
Warning: do not disable breakers during peak incidents; use shadow routes and sampled traces first to see which backend is burning quota.
If Gateway runs on a VPS and tools execute on a dedicated remote Mac, review HTTP routing separately from SSH tool execution: the first impacts global latency, the second only some tools.
Tune the numbers below to your tenant scale and compliance posture.
/health, then model probe.Ephemeral laptops or hobby VPS hosts often oscillate between sleep, drifting ports, certificates, and upstream throttling. Teams that need reliable xcodebuild, CLI agents, and long-lived toolchains usually move compute to dedicated, always-on remote Mac nodes and keep OpenClaw on small Linux hosts for orchestration. Compared to piecing together unstable macOS virtualization, NodeMini Mac Mini cloud rental makes SSH endpoints, disk tiers, and node profiles repeatable so tool execution decouples from edge governance. Compare plans in the rental rates page and operational detail in the help center.
Bind this runbook to internal "routing change classes": TLS at the edge, modelRouting, and model vendor switches should not share the same approval path.
Usually Kong/Traefik terminates TLS and enforces mTLS, WAF, and tenant routing at the edge, while OpenClaw stays inside the mesh as the AI orchestration gateway. Avoid binding public listeners directly to Gateway unless zero trust is extremely mature. Network guidance lives in the help center.
Edge routing picks service instances; modelRouting picks model profiles and quotas. Decouple them with canary headers or tenant claims. See the modelRouting article and the OpenClaw category.
Either pin stickiness at the edge and externalize shared state to Redis or etcd, or declare Gateway fully stateless with sessions held client-side or downstream. Avoid half-stateful designs. Capacity planning can start from rental rates and observability.