docs(roadmap): add #466 — provider *_BASE_URL env vars can be malformed while doctor/status stay green

[Yeachan-Heo]

ROADMAP pinpoint #466 — malformed provider *_BASE_URL env vars leave doctor/status green

Dogfooded for the 2026-05-24 17:00/17:30 Clawhip nudge window; finalized for message 1508160182386167961.

The pinpoint

Provider endpoint env vars are accepted as routing/transport configuration but doctor / status do zero validation and surface zero provenance.

Tested vars:

• ANTHROPIC_BASE_URL
• OPENAI_BASE_URL
• XAI_BASE_URL
• DASHSCOPE_BASE_URL

Tested malformed/unsupported values:

• not-a-url
• ftp://example.com
• http://
• http://localhost:99999
• javascript:alert(1)
• empty string

All 24 combinations returned:

doctor_exit=0 stderr_bytes=0
has_failures false
auth ok 'supported auth env vars are configured'
config ok 'no config files present; defaults are active'
system ok 'captured local runtime metadata'

No diagnostic says the lane is configured to talk to javascript:alert(1), ftp://example.com, http://, or an invalid port.

Root cause traced

Provider metadata already knows the endpoint env var:

• providers/mod.rs has base_url_env / default_base_url.
• anthropic.rs:765-766 reads ANTHROPIC_BASE_URL directly:

pub fn read_base_url() -> String {
    std::env::var("ANTHROPIC_BASE_URL").unwrap_or_else(|_| DEFAULT_BASE_URL.to_string())
}

OpenAI-compat providers carry equivalent metadata for OPENAI_BASE_URL, XAI_BASE_URL, and DASHSCOPE_BASE_URL.

But diagnostics never validate or expose endpoint config:

• check_auth_health() only checks auth booleans.
• check_config_health() only checks config files/MCP counts.
• check_system_health() only reports local runtime metadata.
• status has no base_url_env, base_url_source, base_url_valid, host, scheme, or error field.

The runtime later uses these strings as actual URLs; preflight stays green.

Why distinct

• Agent开卷考试启动 #28/明天我将发布 孙玉祥-code助手，大家记得关注 #29 cover provider routing and auth-copy issues, not malformed base URL validation.
• 合影留念 #248 wants prompt lifecycle events to include provider/model/base-url identity after a prompt starts. This is the preflight counterpart: doctor/status should catch bad endpoints before API calls.
• 合影留念 #465 covers effective auth source when both Anthropic auth env vars are set. This covers endpoint config across all provider env vars.
• 挤一挤😆 #111 says /providers should list providers/base URLs/reachability, but that is a slash-command spec mismatch. This is about existing doctor/status green-light surfaces ignoring base URL env vars.

Why it matters

1. Startup friction: OpenRouter/Ollama/local proxy users inevitably touch OPENAI_BASE_URL; a one-character typo passes doctor and fails only during a live prompt.
2. Automation cannot preflight lanes. Green doctor with poisoned endpoint is false confidence.
3. Security posture: accepting javascript: / ftp: / empty string silently is bad. Provider clients should only ever use HTTP(S), and diagnostics should reject/warn on anything else.
4. Metadata already exists; missing layer is validation + redaction-safe surfacing.
5. Base URL is provider identity. For OpenAI-compatible providers, OPENAI_BASE_URL is the difference between OpenAI, OpenRouter, Ollama, local proxy, or malicious typo.

Required fix shape

(a) Add a provider endpoint diagnostics check to doctor: iterate provider metadata, read each *_BASE_URL env var if present, trim, parse with Url, validate scheme in {http, https}, non-empty host, valid port, no unsupported schemes.

(b) Add redaction-safe fields to status --output-format json: active provider, base_url_env, base_url_source, base_url_valid, base_url_scheme, base_url_host, and base_url_error if invalid.

(c) When selected model/provider is affected by invalid base URL, doctor should warn/fail and status.status should be degraded, not ok.

(d) Add tests for the 24-row matrix plus valid local URL (http://127.0.0.1:11434/v1) and valid HTTPS URL.

(e) Optional: /providers (when fixed from #111) should reuse the same endpoint validation.

Acceptance check

env OPENAI_API_KEY=sk-test OPENAI_BASE_URL='javascript:alert(1)' \
  claw doctor --output-format json |
  jq -e '.checks[] | select(.name=="providers" or .name=="provider_endpoints") |
    .status != "ok" and (.details[]? | test("OPENAI_BASE_URL"))'

Should pass. Currently no such check exists and doctor is green.

Coordination note

Still avoided F/CLAW_CONFIG_HOME because Jobdori publicly queued it as “next confirmed but unfiled.” This endpoint-validation surface is orthogonal and credential-free.

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