Setup unified LLM key

DefenseClaw routes every LLM call through one of two layers: the in-process Bifrost SDK (used by the gateway and judge) or LiteLLM (used by the scanner SDKs). Both layers derive the provider-specific key (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) from a single canonical knob — DEFENSECLAW_LLM_KEY — plus the model prefix you pass on the model field.

Set it once. Verify it with defenseclaw keys check. Override per-component only when you need a separate billing or rate-limit posture for the judge or a specific scanner.

The three-step happy path

defenseclaw keys set DEFENSECLAW_LLM_KEY

defenseclaw keys check

defenseclaw setup guardrail

Watch the flow

All four keys subcommands

Resolution order (what keys list actually reads)

The CLI resolves credential values from the most specific source down:

1. process environment    (export DEFENSECLAW_LLM_KEY=sk-…)
2. ~/.defenseclaw/.env    (written by `defenseclaw keys set`)
3. unset                  (REQUIRED → marked MISSING; OPTIONAL → tolerated)

This order is implemented by cli/defenseclaw/credentials.py::resolve and is the same code path that defenseclaw quickstart and defenseclaw doctor use, so what you see in keys list is exactly what the running gateway and scanners see.

Per-component overrides

For most installs, DEFENSECLAW_LLM_KEY is the only knob you ever set. When you want a different key for a specific feature — say, a higher rate-limit account for the judge, or a separate billing line for the skill-scanner LLM second opinion — you point that one component at its own env var:

guardrail:
  judge:
    enabled: true
    llm:
      provider: anthropic
      model: claude-sonnet-4-5
      api_key_env: JUDGE_ANTHROPIC_KEY     # override; falls through to DEFENSECLAW_LLM_KEY otherwise

scanners:
  skill_scanner:
    use_llm: true
    llm:
      api_key_env: SKILL_SCANNER_OPENAI_KEY

Then store those custom env names just like the canonical key:

defenseclaw keys set JUDGE_ANTHROPIC_KEY
defenseclaw keys set SKILL_SCANNER_OPENAI_KEY
defenseclaw keys check    # both REQUIRED entries should now be ✓ set

keys list automatically resolves the env name from cfg.resolve_llm(), so the table you see is always the env vars you actually configured — not the canonical defaults.

Non-interactive (CI / scripts)

defenseclaw keys set DEFENSECLAW_LLM_KEY --value "$LLM_KEY"
defenseclaw keys check

--value skips the hidden prompt entirely; keys check returns a non-zero exit code that fails the build cleanly.

For multi-key bootstraps in CI (rare; usually a single key is enough):

for ENV in DEFENSECLAW_LLM_KEY CISCO_AI_DEFENSE_API_KEY SPLUNK_ACCESS_TOKEN; do
  defenseclaw keys set "$ENV" --value "${!ENV}"   # bash indirection
done
defenseclaw keys check

Provider routing — Bifrost vs LiteLLM

Both routing layers consume DEFENSECLAW_LLM_KEY plus the model prefix on the configured model name. You do not need to set provider-specific env vars:

Local providers (ollama/, vllm/, lm_studio/) need no key — keys list correctly classifies them as NOT_USED even when the feature is on.

Bifrost provider catalog

Inside the Go gateway, every provider call goes through the embedded Bifrost SDK — DefenseClaw never speaks directly to a provider. Bifrost handles auth, retries, streaming, and routing, and gives DefenseClaw one consistent shape for tool calls, completions, and embeddings.

mapProviderKey is the source of truth for what's wired today:

You don't pick the Bifrost key directly. You pick a model — the gateway maps gpt-4o-mini → openai, claude-3-5-sonnet-20241022 → anthropic, and so on. The unified key is then handed to whichever provider the model resolves to.

What consumes the key

What gets stored where

Reference

• cli/defenseclaw/commands/cmd_keys.py — the four subcommands.
• cli/defenseclaw/credentials.py — the CREDENTIALS registry and the resolve / classify functions.
• Reference → Keys — the full credential table with feature gating and override paths.
• Setup → Skill scanner and MCP scanner — the two scanners that consume the unified key via inject_llm_env.