openclaw - 💡(How to fix) Fix doctor gateway-auth falsely reports file SecretRef gateway.auth.token unavailable despite resolved runtime snapshot

Summary

openclaw doctor --lint --only core/doctor/gateway-auth reports that gateway.auth.token is SecretRef-managed and unavailable, even though the same file SecretRef resolves successfully through openclaw secrets audit, the running Gateway is reachable, and openclaw status reports no secret diagnostics.

This appears to be a false positive in the core/doctor/gateway-auth check rather than an actual runtime SecretRef failure.

I found older related reports such as #50161 about doctor not using resolved snapshots for SecretRefs, but this still reproduces on OpenClaw 2026.5.27 specifically for gateway.auth.token backed by a file SecretRef.

Environment

• OpenClaw: 2026.5.27 (27ae826)
• Platform: macOS 26.4.1 arm64
• Install/runtime: local Gateway LaunchAgent
• Gateway URL: local loopback ws://127.0.0.1:18789
• Relevant config shape, with secrets redacted:

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": {
        "source": "file",
        "provider": "openclaw_file",
        "id": "/gateway/auth/token"
      }
    }
  },
  "secrets": {
    "providers": {
      "openclaw_file": {
        "source": "file",
        "path": "<state-dir>/secrets/openclaw-secrets.json",
        "mode": "json"
      }
    },
    "defaults": {
      "file": "openclaw_file"
    }
  }
}

Steps To Reproduce

1. Configure local gateway token auth with gateway.auth.token as a file SecretRef.
2. Start/restart Gateway.
3. Verify SecretRef resolution:

openclaw secrets audit --check --json

1. Verify Gateway status:

openclaw status --json

1. Run the targeted doctor check:

openclaw doctor --lint --only core/doctor/gateway-auth --json

Expected Behavior

If gateway.auth.token is SecretRef-managed and the active runtime snapshot can resolve it, the core/doctor/gateway-auth check should pass.

This matches the docs I checked locally:

• docs/reference/secretref-credential-surface.md lists gateway.auth.token as a supported SecretRef credential surface.
• docs/gateway/secrets.md says read-only command paths, including doctor/config repair flows, prefer the active snapshot and degrade only if the targeted SecretRef is still unavailable.
• docs/start/wizard.md says daemon install validates SecretRef-managed gateway.auth.token and does not persist the resolved token into supervisor metadata.

Actual Behavior

openclaw doctor --lint --only core/doctor/gateway-auth --json returns a warning:

{
  "ok": false,
  "checksRun": 1,
  "checksSkipped": 18,
  "findings": [
    {
      "checkId": "core/doctor/gateway-auth",
      "severity": "warning",
      "message": "Gateway token is managed via SecretRef and is currently unavailable.",
      "path": "gateway.auth.token",
      "fixHint": "Resolve or rotate the external secret source, then rerun doctor."
    }
  ]
}

However, the same setup has no unresolved SecretRefs according to secrets audit:

{
  "resolution": {
    "refsChecked": 4,
    "skippedExecRefs": 0,
    "resolvabilityComplete": true
  },
  "summary": {
    "plaintextCount": 1,
    "unresolvedRefCount": 0,
    "shadowedRefCount": 0,
    "legacyResidueCount": 3
  }
}

The nonzero audit status above is from unrelated findings: OAuth legacy residue plus one plaintext providers.codex.apiKey in an agent models.json. It does not report any unresolved SecretRefs.

openclaw status --json also reports the Gateway as healthy and no secret diagnostics:

{
  "gateway": {
    "reachable": true,
    "authWarning": null,
    "error": null
  },
  "secretDiagnostics": []
}

Evidence / Suspected Cause

From the bundled dist in the installed package, dist/doctor-core-checks-*.js appears to detect that gateway.auth.token is a SecretRef, then call resolveGatewayAuth(...) against the raw config:

const gatewayTokenRef = resolveSecretInputRef({
  value: ctx.cfg.gateway?.auth?.token,
  defaults: ctx.cfg.secrets?.defaults
}).ref;
const auth = resolveGatewayAuth({
  authConfig: ctx.cfg.gateway?.auth,
  tailscaleMode: ctx.cfg.gateway?.tailscale?.mode ?? "off"
});
if (!(auth.mode !== "password" && auth.mode !== "none" && auth.mode !== "trusted-proxy" && (auth.mode !== "token" || !auth.token))) return [];
if (gatewayTokenRef) return [{
  checkId: "core/doctor/gateway-auth",
  severity: "warning",
  message: "Gateway token is managed via SecretRef and is currently unavailable.",
  path: "gateway.auth.token",
  fixHint: "Resolve or rotate the external secret source, then rerun doctor."
}];

Because resolveGatewayAuth(...) is seeing the unresolved SecretRef object in the raw config instead of a materialized runtime value, auth.token is empty. The check then treats the mere presence of gatewayTokenRef as proof that the token is unavailable.

That does not match the runtime evidence from secrets audit and status, both of which show this file SecretRef is resolvable/healthy.

Impact

• openclaw doctor --lint reports a warning for a healthy gateway auth setup.
• Operators may rotate or downgrade a working SecretRef-managed gateway token unnecessarily.
• The suggested workaround would push users toward plaintext gateway.auth.token, which is less desirable than the current SecretRef setup.
• Health automation that treats doctor warnings as actionable becomes noisy.

Suggested Fix Direction

For core/doctor/gateway-auth, resolve gateway auth through the same read-only SecretRef-aware path used by status/secrets audit, or query the active runtime snapshot before deciding that a configured gateway.auth.token SecretRef is unavailable.

At minimum, the check should distinguish:

• SecretRef configured and resolved in active/runtime snapshot: pass
• SecretRef configured but command cannot verify resolution: degraded/unknown diagnostic
• SecretRef configured and confirmed unresolved: warning

What Was Tested

• Reproduced on OpenClaw 2026.5.27 (27ae826).
• openclaw secrets audit --check --json confirms unresolvedRefCount: 0 and resolvabilityComplete: true.
• openclaw status --json confirms Gateway is reachable and secretDiagnostics: [].
• openclaw doctor --lint --only core/doctor/gateway-auth --json still reports the warning above.
• I did not patch or test a source fix; this is a real behavior report from an installed OpenClaw runtime.