Summary

Warn users when a stale OPENCLAW_GATEWAY_TOKEN in ~/.openclaw/.env overrides gateway.auth.token in local gateway mode.

Problem to solve

After updating OpenClaw, my local gateway entered a confusing split-brain auth state.

I had gateway.auth.token configured in ~/.openclaw/openclaw.json, but ~/.openclaw/.env also contained OPENCLAW_GATEWAY_TOKEN. I did not manually set this env token; it appears to have been created or left by OpenClaw setup/update/install flow.

Because OPENCLAW_GATEWAY_TOKEN takes precedence over gateway.auth.token, some local auth/probe paths used the stale env token while others used the config token.

This caused confusing symptoms:

• gateway token mismatch
• health/Dashboard/CLI auth disagreement
• gateway status sometimes showed reachable/admin-capable
• openclaw health failed with token mismatch or timeout
• Dashboard connected but messages were stuck/spinning
• Discord/WhatsApp behavior was inconsistent until the stale env token was removed

Current behavior is insufficient because the gateway can look partially healthy while different local clients disagree on auth. The stale ~/.openclaw/.env token was not obvious until manually checking env precedence.

Proposed solution

Add a diagnostic guardrail in doctor/status that detects this condition:

• gateway.mode is local
• gateway.auth.token is configured in ~/.openclaw/openclaw.json
• ~/.openclaw/.env contains a non-empty OPENCLAW_GATEWAY_TOKEN

When detected, warn that env credentials override config and may be stale.

The warning should:

• not print the token or any secret
• mention the source path ~/.openclaw/.env
• explain that OPENCLAW_GATEWAY_TOKEN overrides gateway.auth.token
• suggest removing or syncing OPENCLAW_GATEWAY_TOKEN
• suggest restarting the gateway afterward

Ideally surface this in:

• openclaw doctor
• openclaw status / status --all
• openclaw gateway status --deep
• gateway install/update flows when auth token rotation or service reinstall happens

Alternatives considered

Manually checking ~/.openclaw/.env works, but users are unlikely to know that this file can override openclaw.json.

Automatically deleting the env token may be too aggressive because some users may intentionally use env-based auth.

A warning is safer: it preserves existing behavior, does not expose secrets, and points users to the exact source of the mismatch.

Impact

Affected users/systems/channels:
Local OpenClaw users running the gateway in local mode with token auth, especially after update/install/onboarding flows that rotate or recreate gateway.auth.token.

Severity:
High when it occurs, because it can block Dashboard, health checks, CLI probes, and channels while still making the gateway look partially healthy.

Frequency:
Intermittent / post-update edge case, but very hard to diagnose when it happens.

Consequence:
Users can spend a long time debugging token mismatch, health timeouts, Dashboard hangs, and inconsistent Discord/WhatsApp behavior. The fix is simple once found, but the current diagnostics do not clearly point to stale ~/.openclaw/.env credentials.

Evidence/examples

Observed on:

• OpenClaw 2026.4.26 (be8c246)
• macOS 15.2 x64
• Node 24.15.0
• local loopback gateway on 127.0.0.1:18789

Relevant findings:

• ~/.openclaw/openclaw.json had gateway.auth.token configured
• ~/.openclaw/.env contained OPENCLAW_GATEWAY_TOKEN
• removing OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD / OPENCLAW_GATEWAY_URL from ~/.openclaw/.env and restarting the gateway fixed the auth mismatch

Symptoms before removing the stale env token:

• gateway token mismatch
• openclaw health failed with token mismatch or timeout
• gateway status sometimes showed reachable/admin-capable
• Dashboard connected but agent messages were stuck/spinning
• Discord/WhatsApp behavior was inconsistent

No secrets should be printed in diagnostics; just showing that OPENCLAW_GATEWAY_TOKEN is set in ~/.openclaw/.env would have been enough.

Additional information

This was debugged with help from the OpenClaw Discord with Krill.

Suggested acceptance criteria:

• Detect local gateway mode + configured gateway.auth.token + non-empty OPENCLAW_GATEWAY_TOKEN in ~/.openclaw/.env
• Do not print either secret
• Warn that env credentials override config and may be stale
• Suggest removing/syncing OPENCLAW_GATEWAY_TOKEN in ~/.openclaw/.env
• Suggest restarting the gateway
• Surface the warning in doctor, status, and ideally install/update flows