Summary

On macOS, openclaw gateway install can exit with Gateway service already loaded even when the currently loaded LaunchAgent still embeds a stale OPENCLAW_GATEWAY_TOKEN.

That leaves the machine stuck in a token_mismatch / unauthorized loop after a config token rotation or post-update auth change until the operator manually runs:

openclaw gateway install --force

This is a product bug in the non---force install path, not just an ops mistake.

Concrete incident

Observed on 2026.4.21 after an upgrade on macOS LaunchAgent install.

What happened:

1. Upgrade rotated the effective gateway auth token in ~/.openclaw/openclaw.json
2. The existing LaunchAgent plist still had stale embedded gateway auth state
3. A normal openclaw gateway install / updater flow saw the service was already loaded and returned early
4. The plist was never refreshed
5. Gateway itself was healthy, but app connections were rejected with reason=token_mismatch / unauthorized on every connect attempt

Recovery that worked:

openclaw gateway install --force

That regenerated the LaunchAgent plist from current config, restarted the gateway, and immediately restored authenticated RPC traffic.

Why this is the real bug

The service installer already has logic to auto-refresh a loaded service for certain drift states (for example the NODE_EXTRA_CA_CERTS refresh path).

But it does not auto-refresh when the currently loaded service definition still embeds OPENCLAW_GATEWAY_TOKEN.

In dist/install-*.js the non---force path effectively does:

• if service is loaded
• and the special TLS refresh case does not apply
• return already-installed

So any repair/update automation that calls plain openclaw gateway install silently no-ops in exactly the state where the service definition most needs to be refreshed.

Expected behavior

If the currently loaded service definition still embeds OPENCLAW_GATEWAY_TOKEN, openclaw gateway install should auto-refresh the install instead of returning already-installed.

At minimum it should emit a warning like:

Gateway service still embeds OPENCLAW_GATEWAY_TOKEN; refreshing the install.

or, if auto-refresh is not desired:

Gateway service is loaded but embeds stale gateway auth. Re-run with: openclaw gateway install --force

But the current silent early return is the dangerous behavior.

Actual behavior

openclaw gateway install returns success with:

Gateway service already loaded.
Reinstall with: openclaw gateway install --force

while the loaded LaunchAgent still contains stale embedded auth and the app is failing every connection attempt with token mismatch / unauthorized.

Repro sketch

1. Install gateway as LaunchAgent on macOS
2. Ensure the service definition embeds OPENCLAW_GATEWAY_TOKEN
3. Change or rotate the effective gateway token in config / migration / update flow
4. Keep the LaunchAgent loaded
5. Run:

openclaw gateway install

1. Observe that it exits early as already-installed
2. Observe that the plist/service definition was not refreshed
3. App/device connections fail with token mismatch until:

openclaw gateway install --force

Suggested fix

In the non---force install path, add an auto-refresh reason alongside the existing TLS CA refresh logic.

Pseudo-shape:

const currentCommand = await service.readCommand(env)
if (readEmbeddedGatewayToken(currentCommand)) {
  return "Gateway service still embeds OPENCLAW_GATEWAY_TOKEN; refreshing the install."
}

Then continue through the normal reinstall path instead of returning already-installed.

Related issues

• #62140
• #53742
• #54521
• #29373

This issue is narrower / more actionable than the broader token-drift family: the specific failure is that the installer’s loaded-service fast path skips a clearly stale service definition.