Unified LLM key
Wire up DEFENSECLAW_LLM_KEY — the single environment variable that powers the LLM judge, the MCP / skill / plugin scanners, and any custom LLM call DefenseClaw makes through Bifrost.
DefenseClaw sends every LLM call through one of two layers: the in-process Bifrost SDK (the gateway and the judge) or LiteLLM (the scanner SDKs). Both derive the provider key from DEFENSECLAW_LLM_KEY and the model prefix. For the short path, see Set up an LLM key.
One key, DEFENSECLAW_LLM_KEY, powers the LLM judge and the skill, MCP and plugin scanners. The optional decision model has its own setting and token, DEFENSECLAW_DECISION_MODEL_KEY. Set it once. Override it per component only if you need separate billing or rate limits (LLM providers).
The happy path
Before you start
- An API key for a provider such as Anthropic or OpenAI. For Bedrock, Vertex AI or Azure OpenAI, see the table at the end.
Steps
-
Pick the provider and model. This writes the top-level
llm:block that the judge and scanners inherit.defenseclaw setup llm --provider anthropic --model claude-sonnet-4-5 --api-key-env DEFENSECLAW_LLM_KEYOK Saved to /home/alice/.defenseclaw/config.yaml llm.provider: anthropic llm.model: claude-sonnet-4-5 llm.api_key_env: DEFENSECLAW_LLM_KEY = (not set) Config updated. The running gateway applies it without a restart. -
Store the key. The prompt is hidden and the value goes to
~/.defenseclaw/.env(%USERPROFILE%\.defenseclaw\.envon Windows), readable only by you.defenseclaw keys set DEFENSECLAW_LLM_KEYOK Saved DEFENSECLAW_LLM_KEY to /home/alice/.defenseclaw/.env (value hidden) The running gateway keeps the DEFENSECLAW_LLM_KEY it loaded at start; apply the change with: defenseclaw-gateway restartIn scripts, read the value from standard input so it stays out of
psand shell history:printf '%s\n' "$LLM_KEY" | defenseclaw keys set DEFENSECLAW_LLM_KEY --value-stdin$env:LLM_KEY | defenseclaw keys set DEFENSECLAW_LLM_KEY --value-stdin -
Restart the gateway so it loads the key.
defenseclaw-gateway restart -
Turn on the judge. In action mode, the wizard offers the LLM you configured instead of asking again.
defenseclaw setup guardrail --non-interactive --connector claudecode --mode action \ --detection-strategy regex_judge \ --judge-model anthropic/claude-sonnet-4-5 \ --judge-api-key-env DEFENSECLAW_LLM_KEYguardrail.judge.enabled: true guardrail.judge.llm.model: anthropic/claude-sonnet-4-5 judge credentials: DEFENSECLAW_LLM_KEY guardrail.judge.hook_connectors: all
Check it worked
defenseclaw keys check 1/1 required credentials set.
OK all required credentials presentkeys check exits 0 when every required key is set, so you can use it as a CI gate. defenseclaw keys list shows each key, whether the current config needs it, and where it was found (env, dotenv or unset). defenseclaw setup llm --show prints the resolved settings with the key masked to its last four characters. Add --ping to setup llm to send a one-token test call.
Watch the flow
Other providers
| Provider | Extra settings | Details |
|---|---|---|
| AWS Bedrock | Region and auth mode (api_key, iam_credentials, profile, instance_role) | Bedrock |
| Google Vertex AI | Project, region, auth mode | Vertex AI |
| Azure OpenAI | Endpoint, API version, deployment aliases | Azure OpenAI |
| Ollama, vLLM, LM Studio | A base_url; no key | Provider catalog |
DefenseClaw reads keys from the process environment first, then ~/.defenseclaw/.env. It does not use the OS keychain or an external secret manager.
The keys subcommands
Prop
Type
Resolution order (what keys list actually reads)
The CLI resolves credential values from the most specific source down:
| Priority | Source | macOS/Linux example | Windows PowerShell example |
|---|---|---|---|
| 1 | Process environment | export DEFENSECLAW_LLM_KEY='sk-…' | $env:DEFENSECLAW_LLM_KEY = 'sk-…' |
| 2 | User dotenv | ~/.defenseclaw/.env | %USERPROFILE%\.defenseclaw\.env |
| 3 | Unset | Required keys are marked missing; optional keys are tolerated. | Same behavior. |
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.
No operating-system keychain or external secret manager
DefenseClaw does not read or write macOS Keychain, Windows Credential
Manager, 1Password, Vault, AWS Secrets Manager, or another external secret
store. The user dotenv file is the only on-disk credential store. To source a
secret elsewhere, inject it into the process environment with export on
macOS/Linux or $env:NAME = ... in PowerShell.
Per-component overrides
A component can use its own env var. Everything else falls through to DEFENSECLAW_LLM_KEY.
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_KEYThen store those custom env names the same way as 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 ✓ setkeys 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 and scripts)
printf '%s\n' "$LLM_KEY" | defenseclaw keys set DEFENSECLAW_LLM_KEY --value-stdin
defenseclaw keys check$env:LLM_KEY | defenseclaw keys set DEFENSECLAW_LLM_KEY --value-stdin
defenseclaw keys check--value-stdin reads the value from the first line of standard input without
echoing it, so it stays out of the process list and your shell history.
--value "$LLM_KEY" also works, but other local users can see command-line
values in ps. 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
printf '%s\n' "${!ENV}" | defenseclaw keys set "$ENV" --value-stdin # bash indirection
done
defenseclaw keys check$names = 'DEFENSECLAW_LLM_KEY', 'CISCO_AI_DEFENSE_API_KEY', 'SPLUNK_ACCESS_TOKEN'
foreach ($name in $names) {
(Get-Item "Env:$name").Value | defenseclaw keys set $name --value-stdin
}
defenseclaw keys checkProvider 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. Every component starts from the unified top-level llm: block that defenseclaw setup llm writes; a component-level block overrides only the fields it sets:
| Component | Layer | Model setting (falls back to llm.model) |
|---|---|---|
| Unified default | (inherited by all) | llm.provider and llm.model, written by defenseclaw setup llm |
| Gateway upstream LLM (proxy connectors) | Bifrost (Go SDK) | guardrail.llm.model prefix (openai/, anthropic/, bedrock/, vertex/, azure/, ollama/, …) |
| LLM judge | Bifrost | guardrail.judge.llm.model prefix |
| Skill scanner second opinion | LiteLLM (Python SDK) | scanners.skill_scanner.llm.model prefix |
| MCP scanner introspection | LiteLLM | scanners.mcp_scanner.llm.model prefix |
The scanners run on the LiteLLM 1.103 release line that DefenseClaw bundles.
Local providers (ollama/, vllm/, lm_studio/) need no key: keys list never marks DEFENSECLAW_LLM_KEY REQUIRED for them and keys check passes without it. While the guardrail is on, the DEFENSECLAW_LLM_KEY row still reads OPTIONAL (it shows the setting exists, nothing needs it); with the guardrail off it reads NOT_USED. A local judge's JUDGE_API_KEY row reads NOT_USED.
Bifrost provider catalog
The Go gateway reaches every provider through Bifrost. The names below are the supported provider values (the source of truth is mapProviderKey in internal/gateway/provider_bifrost.go).
| Provider | Provider name | Notes |
|---|---|---|
| OpenAI | openai | Default for gpt-*, o1-*, o3-*, o4-* |
| Anthropic | anthropic | Default for claude-* |
| Google Gemini | gemini (also gemini-openai) | Default for gemini-* |
| AWS Bedrock | bedrock or amazon-bedrock | Resolves region/profile from env |
| Azure OpenAI | azure | Needs deployment name + endpoint |
| OpenRouter | openrouter | Multi-provider passthrough |
| Groq | groq | Lower-latency open models |
| Mistral | mistral | Mistral Cloud |
| Ollama | ollama | Local model server (no key needed) |
| Vertex AI | vertex_ai (also vertex, vertexai) | Google Vertex |
| Cohere | cohere | Cohere Cloud |
| Perplexity | perplexity | Perplexity API |
| Cerebras | cerebras | Cerebras Cloud |
| Fireworks | fireworks (also fireworks_ai, fireworksai) | Fireworks AI |
| xAI | xai | Grok models |
| HuggingFace | huggingface | HF Inference Endpoints |
| Replicate | replicate | Replicate hosted models |
| vLLM | vllm | Self-hosted vLLM (no key needed) |
| DeepSeek, Together AI, LM Studio | deepseek, together_ai (also togetherai, together), lm_studio (also lmstudio) | Reached through their own base_url with Bifrost's OpenAI-compatible adapter |
You pick a model, not a Bifrost key: gpt-4o-mini resolves to openai, a claude-* model to anthropic, and the unified key goes to whichever provider the model resolves to.
What consumes the key
LLM judge
The gateway's optional second-opinion model. Reads guardrail.judge.llm and falls back to DEFENSECLAW_LLM_KEY.
Skill Scanner
The skill scanner's LLM judge inherits the top-level llm: block (judge_source: inherit), so the unified key reaches it with no scanner-specific variable. Works with any LiteLLM-supported provider, including a local vLLM server.
MCP Scanner
The MCP scanner's LLM analyzer inherits the same llm: block (judge_source: inherit).
Set up the guardrail (judge)
defenseclaw setup guardrail --judge-model writes the judge config that consumes the key when enabled.
What gets stored where
| Where | What | Notes |
|---|---|---|
User-home .defenseclaw/.env | Canonical credential store | Atomic tmp+rename writes. POSIX uses 0o600; Windows uses an owner-private DACL. No comments or metadata. |
User-home .defenseclaw/audit.db | Action log entry per keys set | audit export shows it as action=config.change.applied with actor=cli:<your user name>; its structured fields hold defenseclaw.admin.operation=config-update, defenseclaw.admin.target_ref=config:dotenv:<ENV> and before/after states that carry only env and had_value. The value is never logged. |
User-home .defenseclaw/config.yaml | The *_env references only | The actual secret never enters config.yaml. |
| Process environment | Highest-priority lookup | export on macOS/Linux or $env:NAME = ... in PowerShell wins over the dotenv copy. Useful for one-shot debugging. |
Hook-based vs proxy-based connectors
How an agent connector intercepts model traffic determines what the unified key actually pays for:
| Connector class | Examples | What the LLM does |
|---|---|---|
| Hook-based | Codex, Claude Code, Hermes, Cursor, Devin, Copilot CLI, Antigravity, OpenCode, Amp, Kiro | The agent talks to its own LLM directly. DefenseClaw runs as a judge only: it inspects prompts/responses and emits verdicts. The unified key is only needed when guardrail.judge.enabled: true. |
| Proxy-based | OpenClaw, ZeptoClaw | Outbound LLM traffic is routed through the gateway proxy. The gateway uses the unified key for both the upstream LLM (the agent's model) and the optional judge. |
The wizard records the intent on guardrail.llm_role:
judge_only— set automatically for hook-based connectors. Only the judge consumes the key.judge_and_agent— set automatically for proxy-based connectors. The same key powers the agent's upstream LLM and the judge.
Set the role explicitly when scripting:
This OpenClaw proxy example is for macOS/Linux. Native Windows is hook-only and rejects OpenClaw setup.
defenseclaw setup guardrail \
--connector openclaw \
--llm-role judge_and_agent \
--judge-model anthropic/claude-sonnet-4-5 \
--non-interactiveCustom providers for internal or self-hosted endpoints
Internal LLM gateways (a corporate vLLM cluster, an isolated Bedrock
mirror, a lab vending machine) plug in as llm_providers.custom
entries in config.yaml (see the
configuration reference).
Each entry exposes its own base_url, env keys, allowed request types,
and per-instance TLS posture.
Manage the entries with defenseclaw setup provider add, list, show and
remove. add and remove write llm_providers in config.yaml through the
config writer; list and show print the registry the running gateway reports
and fall back, with a label, to the file on disk when the gateway is
unreachable. A file marked _derived_from is derived from
llm_providers on config writes and is not read back as input: do not edit
it. If that derived file drifts, defenseclaw doctor fails the
Custom-provider overlay row and defenseclaw doctor --fix rewrites it.
During the v9 migration, DefenseClaw imports an ordinary hand-written
custom-providers.json from 0.8.x into llm_providers, then retires the old
overlay. If any provider uses request_overrides, which llm_providers
cannot represent, migration reports it and leaves the legacy file as a
live input. The gateway continues to merge that overlay with
llm_providers after config changes. defenseclaw setup provider add and
remove copy its providers into llm_providers (without the overrides) and
leave the file in place. Preserve and review the file until those request
overrides are no longer needed; changing llm_providers alone does not remove
them. See v9 migration.
defenseclaw setup provider add \
--name acme-internal-bedrock \
--base-provider-type bedrock \
--base-url https://llm.internal:8443 \
--domain llm.internal \
--env-key ACME_BEDROCK_KEY \
--allowed-request chat \
--allowed-request embedding \
--available-model us.anthropic.claude-sonnet-4-6 \
--request-path-override chat=/openai/v1/chat/completions \
--ca-cert-file /etc/ssl/acme-root.pemWhat a custom provider does depends on the connector
A custom provider resolves the same globally, but a binding enforced on the agent versus judge/aux only depends entirely on the connector class:
| Connector class | A bound custom provider… |
|---|---|
| Proxy (OpenClaw, ZeptoClaw) | Is enforced. The agent's model traffic routes through DefenseClaw, so the custom provider can serve the agent's upstream model, the judge, or both. |
| Hook (Hermes, Cursor, Codex, OpenCode, Amp, Claude Code, Devin, Copilot, Antigravity, Kiro) | Configures DefenseClaw's judge/aux model only. The agent talks to its own model directly — those calls are never routed through or inspected by DefenseClaw, so a custom provider cannot change the agent's model. |
Hook connectors: a custom provider is judge-only
This is the easiest thing to get wrong: attaching a custom provider while
guarding a hook connector does not make the agent run on your private
model. It only changes the model DefenseClaw uses to judge. The CLI states
this for you — setup llm prints an "Enforced" vs "Judge/aux only" note when
you bind an instance, and setup provider list prints the same legend for the
active connector. Programmatically, GET /v1/connectors reports
llm_traffic_mode ("proxy" | "hooks-only") per connector.
Set --domain when you set --base-url
The gateway resolves an inbound request to a custom-provider entry by
matching the request URL's host against each entry's domains list. If
you set --base-url but never declare a --domain covering the same
host, defenseclaw doctor emits a base_url host … not covered by domains warning and the gateway falls back to default TLS / routing
because it cannot match the inbound URL to the entry. Always pass
--domain <host> alongside --base-url <scheme>://<host>:<port> (or
add the host to the entry's domains in llm_providers.custom).
Then bind a resolved role to the instance:
defenseclaw setup llm \
--provider custom \
--instance-name acme-internal-bedrock \
--model us.anthropic.claude-sonnet-4-6 \
--api-key-env ACME_BEDROCK_KEY \
--non-interactiveA later setup llm --provider with another provider (for example
anthropic or bedrock) and no --instance-name drops the instance
binding, so the role stops using the custom instance. The setup wizard does the same when you pick a catalog provider, setup guardrail --judge-provider <other> without --judge-instance-name drops the judge's instance, and a role that names its own provider with no instance does not inherit the top-level instance.
provider: custom is not a provider family. With a bound instance, the gateway, the judge and the scanners use the instance's provider family and its regional sub-block, so a keyless Bedrock instance runs the skill scanner's LLM analyzer. llm.bedrock.inference_profile applies to the scanners' model as well, so a model that is callable only through a profile, such as Claude Haiku 4.5, works from the scanners.
The judge can point at a different instance than the top-level LLM without copy-pasting:
defenseclaw setup guardrail \
--judge-instance-name acme-judge-cluster \
--judge-provider anthropic \
--judge-model claude-sonnet-4-5 \
--non-interactivedefenseclaw doctor validates that every instance_name in your
config resolves to an llm_providers.custom entry, warns when an entry
sets both a CA file and insecure_skip_verify, and warns when an entry's
base_url host is not covered by its domains list (which would
otherwise silently bypass the entry at request time).
Bedrock, Vertex AI, Azure on a custom instance
A custom instance can carry the full regional posture (region, auth
mode, deployment aliases) so a single setup llm --instance-name X
call is all that's needed downstream. Same flags as the role-level
regional flags below — they attach to the llm_providers.custom entry instead.
defenseclaw setup provider add \
--name acme-bedrock-prod \
--base-provider-type bedrock \
--domain bedrock-runtime.us-east-2.amazonaws.com \
--bedrock-region us-east-2 \
--bedrock-auth-mode iam_credentials \
--bedrock-access-key-env ACME_AWS_AKID \
--bedrock-secret-key-env ACME_AWS_SECRET \
--bedrock-inference-profile us. \
--bedrock-deployment fast=anthropic.claude-3-haiku-20240307-v1:0 \
--bedrock-deployment heavy=anthropic.claude-3-opus-20240229-v1:0
defenseclaw setup llm \
--provider custom \
--instance-name acme-bedrock-prod \
--model heavy \
--non-interactiveWhen the upstream is the public AWS Bedrock service (rather than an
internal proxy in front of it), the --domain value should be the
regional Bedrock runtime host — that's the URL the agent's outbound
calls actually carry. Internal Bedrock mirrors should use the mirror's
host plus --base-url.
The same shape works for Vertex AI (--vertex-project-id,
--vertex-region, --vertex-auth-mode,
--vertex-service-account-json-env) and Azure OpenAI
(--azure-endpoint, --azure-api-version, --azure-auth-mode,
--azure-deployment-alias model=deployment).
Role wins, the provider entry fills blanks
When the resolved role and its llm_providers.custom entry both
declare a sub-block, the role's fields win and the entry only supplies
values the role omitted. The example below pins region on the role but
inherits auth mode and the deployment alias table from the entry:
# ~/.defenseclaw/config.yaml
llm:
provider: custom
instance_name: acme-bedrock-prod
bedrock:
region: us-west-2 # overrides the entry's us-east-2
llm_providers:
custom:
- name: acme-bedrock-prod
base_provider_type: bedrock
bedrock:
region: us-east-2 # shadowed by the role above
auth_mode: iam_credentials # inherited
access_key_env: ACME_AWS_AKID # inherited
secret_key_env: ACME_AWS_SECRET # inherited
deployment_aliases: # inherited
fast: anthropic.claude-3-haiku-20240307-v1:0
heavy: anthropic.claude-3-opus-20240229-v1:0Effective dispatch posture: region us-west-2, IAM-credentials auth
from ACME_AWS_*, alias table from the entry. defenseclaw doctor
flags entry fields that the role silently shadows so the dead config
can be pruned.
Regional providers (Bedrock, Vertex AI, Azure OpenAI)
Regional providers require more than a single API key: a region (or project), an auth mode, and sometimes a deployment alias. The CLI ships dedicated flags so non-interactive installs can configure them without hand-editing YAML.
AWS Bedrock
defenseclaw setup llm \
--provider bedrock \
--model us.anthropic.claude-sonnet-4-6 \
--bedrock-region us-east-1 \
--bedrock-auth-mode iam_credentials \
--bedrock-access-key-env AWS_ACCESS_KEY_ID \
--bedrock-secret-key-env AWS_SECRET_ACCESS_KEY \
--bedrock-session-token-env AWS_SESSION_TOKEN \
--bedrock-inference-profile us. \
--non-interactiveWhen you write a Bedrock model into a config file yourself (llm.model, guardrail.judge.llm.model or a scanner's llm.model), the bedrock/ prefix is optional: bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0 and us.anthropic.claude-haiku-4-5-20251001-v1:0 both use Bedrock. In 1.0.5 an id without the prefix made the administrator's scan skill report Authentication failed and scan mcp report an analyzer DNS error.
Auth modes:
| Mode | What's required |
|---|---|
api_key (default) | AWS_BEARER_TOKEN_BEDROCK or DEFENSECLAW_LLM_KEY |
iam_credentials | --bedrock-access-key-env, --bedrock-secret-key-env, optional --bedrock-session-token-env |
profile | --bedrock-profile-name (matching ~/.aws/credentials) |
instance_role | nothing — EC2 / EKS pod identity supplies short-lived creds |
Only api_key needs DEFENSECLAW_LLM_KEY. With the other three modes setup llm shows the key as (not needed: bedrock auth_mode=...) and defenseclaw doctor skips its LLM API key row; LLM reachable still checks that the AWS credentials work.
Google Vertex AI
defenseclaw setup llm \
--provider vertex_ai \
--model claude-sonnet-4-5@vertex \
--vertex-project-id acme-prod-vertex \
--vertex-region us-central1 \
--vertex-auth-mode service_account \
--vertex-service-account-json-env GOOGLE_APPLICATION_CREDENTIALS \
--non-interactiveAzure OpenAI
defenseclaw setup llm \
--provider azure \
--model gpt-4o \
--azure-endpoint https://my-resource.openai.azure.com \
--azure-api-version 2024-10-21 \
--azure-auth-mode api_key \
--azure-deployment-alias gpt-4o=gpt4o-prod \
--azure-deployment-alias gpt-4o-mini=gpt4o-mini-prod \
--api-key-env AZURE_OPENAI_API_KEY \
--non-interactivedefenseclaw doctor calls
_check_regional_provider_config
which fails fast when a regional sub-block is missing a required
field, and runs
_check_llm_reachable
to send a one-shot max_tokens=1 ping through the resolved route.
Reachability ping
Pair any setup llm invocation with --ping to issue an immediate
llm.ping after save. It returns (ok, message) and never raises,
so the wizard stays usable when the network is flaky:
defenseclaw setup llm \
--provider anthropic \
--model claude-sonnet-4-5 \
--api-key-env DEFENSECLAW_LLM_KEY \
--non-interactive --ping ✓ llm ping: ok (anthropic/claude-sonnet-4-5)Undo
Remove the line from ~/.defenseclaw/.env and turn the judge off with:
defenseclaw setup guardrail --non-interactive --detection-strategy regex_onlyguardrail status then shows regex_only under Scan and off under Judge for each connector; the mode, fail mode and rule pack stay as they were. Without --non-interactive the command starts the full setup wizard and its judge question still defaults to yes.
Reference
cli/defenseclaw/commands/cmd_keys.py: thekeyssubcommands.cli/defenseclaw/credentials.py: the credential registry and resolve and classify functions.internal/configs/embed.go: theProviderschema behindllm_providers.custom.- Keys and credentials: the full credential table.
- Route models
- Tune the LLM judge
Semantic model routing
Run vLLM Semantic Router as a managed Docker sidecar and route supported proxy traffic between OpenAI-compatible model backends.
Decision model
An optional fast model for tool calls. It runs in front of the LLM judge, or on its own for the connectors you list. Off by default. The skill scanner records its score as advisory only.