mirror of
https://github.com/instructkr/claw-code.git
synced 2026-04-09 01:24:49 +08:00
docs(providers): add honest provider/auth support matrix + improve MissingApiKey error copy
Problem:
- `rust/README.md` on `dev/rust` only shows `ANTHROPIC_API_KEY` under
Configuration and says nothing about other providers, so users
asking "does AWS Bedrock work? other API keys?" have no answer and
assume silent support.
- `ApiError::MissingApiKey` Display message says "Anthropic API" but
gives no signal to a user who exported `OPENAI_API_KEY` (or
`AWS_ACCESS_KEY_ID`) that their key is being ignored because this
branch has no code path for that provider.
- The multi-provider routing work (providers/anthropic.rs,
providers/openai_compat.rs, prefix routing for openai/, qwen/, etc.)
landed on `main` but has not yet merged into `dev/rust`, so the
support matrix actually differs between branches. Nothing in dev
docs communicates that.
Changes:
1. `rust/README.md`: new "Providers & Auth Support Matrix" section
between Configuration and Features, split into three sub-sections:
a. Supported on `dev/rust` (this branch) — just Anthropic. Explicit
call-out that OPENAI_API_KEY / XAI_API_KEY / DASHSCOPE_API_KEY
are ignored here because the `providers/` module does not exist
on this branch.
b. Additionally supported on `main` — xAI, OpenAI, DashScope, with
a note that model-name prefix routing (`openai/`, `gpt-`,
`qwen/`, `qwen-`) wins over env-var presence.
c. Not supported anywhere in this repo (yet) — AWS Bedrock, Google
Vertex AI, Azure OpenAI, Google Gemini, each with a one-line
"why it doesn't work today" pointing at the concrete code gap
(no SigV4 signer, no Google ADC path, api-version query params,
etc.) so users don't chase phantom config knobs. Proxy-based
escape hatch documented.
2. `rust/crates/api/src/error.rs`: `MissingApiKey` Display message now
keeps the grep-stable prefix ("ANTHROPIC_AUTH_TOKEN or
ANTHROPIC_API_KEY is not set") AND tells the user exactly which
other env vars are ignored on this branch plus which providers
aren't supported on any branch yet, with a pointer at the README
matrix section. Non-breaking change — the variant is still a unit
struct, no callers need to change.
3. New regression test
`missing_api_key_display_lists_supported_and_unsupported_providers_and_points_at_readme`
in `rust/crates/api/src/error.rs` asserts the grep-stable prefix is
preserved AND that OPENAI_API_KEY, XAI_API_KEY, DASHSCOPE_API_KEY,
Bedrock, Vertex, Azure, and rust/README.md all appear in the
rendered message, so future tweaks cannot silently drop the
user-facing signal without breaking CI.
Verification:
- `cargo build --release -p api` clean
- `cargo test --release -p api` 26 unit + 6 integration = 32 passing
- New regression test passes
- `cargo fmt -p api` clean
- `cargo clippy --release -p api` clean
Note: workspace-wide `cargo test` shows 11 pre-existing
`rusty-claude-cli` failures on clean `dev/rust` HEAD caused by tests
reading `~/.claude/plugins/installed/sample-hooks-bundled/` from the
host home directory instead of an isolated test fixture. These are
environment-leak test brittleness, not caused by this PR (verified by
stashing changes and re-running — failures reproduce on unmodified
HEAD). Filing as a separate ROADMAP pinpoint.
Does not close any open issue (issues are disabled on the repo);
addresses Clawhip dogfood nudge from 2026-04-08 about users asking
"other api keys? AWS Bedrock도 되냐" without a clear matrix.
Co-authored-by: gaebal-gajae <gaebal-gajae@layofflabs.com>
This commit is contained in:
@@ -52,9 +52,23 @@ impl Display for ApiError {
|
||||
fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
|
||||
match self {
|
||||
Self::MissingApiKey => {
|
||||
// Intentionally explicit about what this branch does and
|
||||
// does not support so users who exported OPENAI_API_KEY,
|
||||
// XAI_API_KEY, DASHSCOPE_API_KEY, AWS_*, or Google
|
||||
// service-account credentials get an immediate "aha"
|
||||
// instead of assuming a misconfiguration bug. See
|
||||
// rust/README.md § "Providers & Auth Support Matrix"
|
||||
// for the full matrix and the branch differences.
|
||||
write!(
|
||||
f,
|
||||
"ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY is not set; export one before calling the Anthropic API"
|
||||
"ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY is not set; export one before calling the Anthropic API. \
|
||||
On this branch (`dev/rust`) only Anthropic is wired up \
|
||||
— OPENAI_API_KEY, XAI_API_KEY, DASHSCOPE_API_KEY, and \
|
||||
AWS/Google credentials are ignored. Multi-provider \
|
||||
routing (OpenAI, xAI, DashScope) lives on `main`; AWS \
|
||||
Bedrock, Google Vertex AI, and Azure OpenAI are not \
|
||||
supported on any branch yet. See rust/README.md \
|
||||
§ 'Providers & Auth Support Matrix' for details."
|
||||
)
|
||||
}
|
||||
Self::ExpiredOAuthToken => {
|
||||
@@ -132,3 +146,46 @@ impl From<VarError> for ApiError {
|
||||
Self::InvalidApiKeyEnv(value)
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn missing_api_key_display_lists_supported_and_unsupported_providers_and_points_at_readme() {
|
||||
// given
|
||||
let error = ApiError::MissingApiKey;
|
||||
|
||||
// when
|
||||
let rendered = format!("{error}");
|
||||
|
||||
// then — the message must keep the grep-stable core so CI
|
||||
// parsers and docs that quote the exact substring continue to
|
||||
// resolve, AND it must tell the user which env vars are
|
||||
// ignored on this branch and where to find the full matrix.
|
||||
assert!(
|
||||
rendered.contains("ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY is not set"),
|
||||
"grep-stable prefix must remain intact, got: {rendered}"
|
||||
);
|
||||
assert!(
|
||||
rendered.contains("OPENAI_API_KEY"),
|
||||
"should explicitly call out that OPENAI_API_KEY is ignored on dev/rust, got: {rendered}"
|
||||
);
|
||||
assert!(
|
||||
rendered.contains("XAI_API_KEY"),
|
||||
"should explicitly call out that XAI_API_KEY is ignored on dev/rust, got: {rendered}"
|
||||
);
|
||||
assert!(
|
||||
rendered.contains("DASHSCOPE_API_KEY"),
|
||||
"should explicitly call out that DASHSCOPE_API_KEY is ignored on dev/rust, got: {rendered}"
|
||||
);
|
||||
assert!(
|
||||
rendered.contains("Bedrock") && rendered.contains("Vertex") && rendered.contains("Azure"),
|
||||
"should tell users Bedrock/Vertex/Azure are not supported on any branch, got: {rendered}"
|
||||
);
|
||||
assert!(
|
||||
rendered.contains("rust/README.md"),
|
||||
"should point users at the README matrix for the full story, got: {rendered}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user