Moving OpenClaw from “works on my machine” to “auditable in production” usually stalls on two strings: Unauthorized and No API key for provider. They map to the Gateway session layer and the model provider credential layer—different fixes, different files. This guide gives a 2026-ready minimal triage order (gateway status → doctor → models auth), a six-step runbook, a decision matrix, and a credential isolation checklist. Before go-live, complete the CVE-2026-25253 + Node 24 production baseline article first.
Each item below mirrors a real mis-route from support queues—read before typing commands.
Treating every Unauthorized as a lost token: proxies may strip headers; CLI caches may hold an empty token; browsers may block WebCrypto off HTTPS.
Blaming Gateway for missing provider keys: usually the agent identity never received models auth, or systemd user units lack exported env vars.
Reinstalling before doctor: hides split PATH binaries and config drift—follow vendor triage first.
Copying developer keys into CI: breaks least privilege and rotation; issue per-runner identities.
Ignoring 127.0.0.1 + Tailscale combos: remote CLI paths resolve tokens and DNS differently—validate both sides.
Skipping on-disk validation: without config:validate (or equivalent), you get “command succeeded but process never read it” false negatives.
| Symptom | Layer first | First command | Next step |
|---|---|---|---|
| 401 / Unauthorized on CLI or WebSocket | Gateway session | openclaw gateway status | openclaw doctor; rotate/regenerate Gateway token if needed |
| Missing API key before model call | Provider creds | openclaw models status | openclaw models auth setup-token … with correct agent scope |
| Flaky success | Dual identity/config | which openclaw + user service env | Align PATH and systemd Environment= |
| Remote CLI only fails | Tunnel / token propagation | Re-test 127.0.0.1 locally | Check Tailscale Serve and HTTPS requirements |
“Classify first, cut second”—the same Unauthorized string needs different surgery on Gateway vs provider paths.
Freeze state: capture exact error text, time, user/agent ID—avoid changing token and provider keys simultaneously.
Gateway minimum set:openclaw gateway status → openclaw doctor; regenerate token per vendor docs if missing.
Validate on disk: permissions must match the Gateway user; restart the user service after edits.
Switch to provider track:openclaw models status, then models auth setup-token; never paste secrets into shared shell history.
Isolate credentials: per-agent/per-env key material or secret manager refs; ban world-readable dirs in prod.
Audit trail: record token/key rotation windows, blast radius, and rollback points in the change ticket.
openclaw gateway status openclaw doctor openclaw models status # openclaw models auth setup-token --provider anthropic # fill per official docs
Note: For systemd user services, inject provider env vars in the unit file—not only in an interactive shell.
Warning: Never paste full tokens/API keys into public tickets; fingerprint with first/last four chars.
Running a Gateway on a sleeping laptop invites intermittent auth failures from thermal and power policies. A dedicated, always-on macOS node fits production agent gateways better. When you need VPS-like Mac capacity with SSH maintenance and audit-friendly images, NodeMini Mac Mini cloud rental is usually the better fit, aligned with our remote-mode and Tailscale guides.
Not always—use section 2, then gateway status and doctor. More OpenClaw topics: blog OpenClaw filter.
Avoid it—split identities and rotation. Capacity planning: rental rates.
Check PATH/binary split and systemd env drift first, then rerun this runbook. Help: help center.