docs(roadmap): add #465 — doctor/status auth diagnostics hide effective ApiKeyAndBearer mode when both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are set

[Yeachan-Heo]

ROADMAP pinpoint #465 — auth diagnostics hide effective mixed-auth mode

Dogfooded across the 2026-05-24 15:00–16:30 Clawhip nudge window; finalized for message 1508145078760378418.

The pinpoint

When BOTH official Anthropic auth env vars are set:

• ANTHROPIC_API_KEY
• ANTHROPIC_AUTH_TOKEN

claw doctor reports only two booleans and says auth is healthy:

{
  "api_key_present": true,
  "auth_token_present": true,
  "details": ["Environment       api_key=present auth_token=present"],
  "name": "auth",
  "status": "ok",
  "summary": "supported auth env vars are configured"
}

But the runtime does not merely have two booleans. It resolves a third mode: AuthSource::ApiKeyAndBearer, which sends BOTH headers:

• x-api-key
• Authorization: Bearer

Doctor/status never expose that effective mode, never warn about both knobs being set, and never identify which wire auth behavior will happen.

Root cause traced

rust/crates/api/src/providers/anthropic.rs:656-666 returns AuthSource::ApiKeyAndBearer when both env vars are present. anthropic.rs:952-954 explicitly documents that both x-api-key and bearer headers are sent in that mode.

But check_auth_health() in main.rs:2071-2150 reimplements only weaker boolean detection:

api_key_present: bool
auth_token_present: bool
summary: "supported auth env vars are configured"

No effective_auth_source, no headers_sent, no both_anthropic_auth_env_vars_present, no warning.

Why distinct

• Agent开卷考试启动 #28 fixed single-env-var auth copy. This is the mixed-env state after Agent开卷考试启动 #28: both env vars present, runtime sends both headers, doctor is silent.
• 我喜羊羊合影留念！！！！！！ #37 removed claw login/logout and directed users to env vars. This shows the two official env vars can be set together with no health warning.
• 合影留念 #248 asks prompt lifecycle events to include auth source category during non-interactive runs. This is the local preflight counterpart: doctor/status should expose auth source before API calls.

Why it matters

1. Real users already confuse these vars (Agent开卷考试启动 #28 history). The natural next failure mode after "try both" is exactly this mixed state.
2. Sending both headers delegates precedence/conflict behavior to Anthropic's edge, while claw says only ok.
3. doctor is supposed to be preflight truth. This currently sounds healthier than a single-key setup, even though it may be conflicting/stale.
4. Automation cannot decide whether to ask the user to unset ANTHROPIC_AUTH_TOKEN, unset ANTHROPIC_API_KEY, or leave both.
5. Runtime truth already exists in resolve_startup_auth_source; diagnostics just don't reuse it.

Required fix shape

(a) Make check_auth_health() call the same auth-source resolver, or a shared redaction-safe helper, used by runtime startup.

(b) Add structured fields:

{
  "effective_auth_source": "api_key" | "bearer_token" | "api_key_and_bearer" | "none",
  "headers_sent": ["x-api-key", "authorization_bearer"],
  "both_anthropic_auth_env_vars_present": true
}

(c) When both are present, downgrade auth check from ok to at least warn unless product policy explicitly supports sending both.

(d) Mirror into status --output-format json, not only doctor.

(e) Regression coverage for four states: none, API key only, bearer only, both.

Acceptance check

env ANTHROPIC_API_KEY=sk-ant-fake ANTHROPIC_AUTH_TOKEN=oauth-fake \
  claw doctor --output-format json |
  jq -e '.checks[] | select(.name=="auth") |
    .effective_auth_source == "api_key_and_bearer" and
    (.headers_sent | index("x-api-key") and index("authorization_bearer")) and
    .status == "warn"'

Should pass.

Coordination note

Intentionally avoided F/CLAW_CONFIG_HOME because Jobdori publicly queued it as "next confirmed but unfiled." This auth-precedence surface is orthogonal.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]