# Environment Variables That Override VulnClaw Config File Settings

> Discover VulnClaw environment variables that override config settings. Learn how VULNCLAW_ and specific API keys like FOFA_KEY control your configurations efficiently.

- Repository: [Unclecheng/VulnClaw](https://github.com/Unclecheng-li/VulnClaw)
- Tags: reference
- Published: 2026-06-30

---

**Environment variables prefixed with `VULNCLAW_` override any setting defined in the VulnClaw [`config.yaml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/config.yaml) file, with reconnaissance API keys also accepting short-form names like `FOFA_KEY` or `HUNTER_KEY`.**

VulnClaw uses a hierarchical configuration system defined in the `Unclecheng-li/VulnClaw` repository that loads settings from built-in defaults, a user-provided YAML file, and environment variables. According to [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py), environment variables represent the highest-priority layer and can dynamically override any configuration field without modifying disk files.

## How VulnClaw Configuration Loading Works

The configuration loader implements a three-step merge process in the `load_config` function within [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py):

1. **Built-in defaults** establish base values for all settings.
2. **User-provided [`config.yaml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/config.yaml)** overlays user preferences if the file exists.
3. **Environment variables** apply the final override via the private helper `_overlay_env` starting at line 78.

This design ensures that any variable prefixed with `VULNCLAW_` takes precedence over both defaults and YAML configuration values.

## LLM Configuration Environment Variables

The following variables control Large Language Model connectivity and parameters, mapping directly to fields in the `LLMConfig` model:

- `VULNCLAW_LLM_API_KEY` – Overrides `config.llm.api_key`
- `VULNCLAW_LLM_BASE_URL` – Overrides `config.llm.base_url`
- `VULNCLAW_LLM_MODEL` – Overrides `config.llm.model`
- `VULNCLAW_LLM_PROVIDER` – Overrides `config.llm.provider`
- `VULNCLAW_LLM_MAX_TOKENS` – Overrides `config.llm.max_tokens`
- `VULNCLAW_LLM_MAX_CONTEXT_TOKENS` – Overrides `config.llm.max_context_tokens`
- `VULNCLAW_LLM_TEMPERATURE` – Overrides `config.llm.temperature`
- `VULNCLAW_LLM_AUTH_MODE` – Overrides `config.llm.auth_mode`
- `VULNCLAW_LLM_CHATGPT_AUTO_PROXY` – Overrides `config.llm.chatgpt_auto_proxy`

## Session Behavior Environment Variables

Session management settings can be overridden using these environment variables, which target fields in `SessionConfig`:

- `VULNCLAW_SESSION_OUTPUT_DIR` – Overrides `config.session.output_dir`
- `VULNCLAW_SESSION_AUTO_SAVE` – Overrides `config.session.auto_save`
- `VULNCLAW_SESSION_REPORT_FORMAT` – Overrides `config.session.report_format`
- `VULNCLAW_SESSION_MAX_ROUNDS` – Overrides `config.session.max_rounds`
- `VULNCLAW_SESSION_SHOW_THINKING` – Overrides `config.session.show_thinking`
- `VULNCLAW_SESSION_STALE_ROUNDS_THRESHOLD` – Overrides `config.session.stale_rounds_threshold`
- `VULNCLAW_SESSION_REASONING_STATE_ENABLED` – Overrides `config.session.reasoning_state_enabled`
- `VULNCLAW_SESSION_REFLEXION_ENABLED` – Overrides `config.session.reflexion_enabled`
- `VULNCLAW_SESSION_REFLEXION_MAX_SAME_VULN_FAILS` – Overrides `config.session.reflexion_max_same_vuln_fails`
- `VULNCLAW_SESSION_REFLEXION_MAX_TOTAL_NO_PROGRESS` – Overrides `config.session.reflexion_max_total_no_progress`
- `VULNCLAW_SESSION_ESCALATION_MAX_LEVEL` – Overrides `config.session.escalation_max_level`
- `VULNCLAW_SESSION_PLUGIN_RUNTIME_ENABLED` – Overrides `config.session.plugin_runtime_enabled`
- `VULNCLAW_SESSION_PLUGIN_DEFAULT_TIMEOUT` – Overrides `config.session.plugin_default_timeout`
- `VULNCLAW_SESSION_PLUGIN_MAX_REQUESTS_PER_TARGET` – Overrides `config.session.plugin_max_requests_per_target`
- `VULNCLAW_SESSION_EVIDENCE_MIN_REPORT_LEVEL` – Overrides `config.session.evidence_min_report_level`

## Safety and Execution Controls

Security-related execution settings can be modified via:

- `VULNCLAW_SAFETY_PYTHON_EXECUTE_ENABLED` – Overrides `config.safety.enable_python_execute`
- `VULNCLAW_SAFETY_PYTHON_EXECUTE_RESTRICTED` – Overrides `config.safety.python_execute_restricted`
- `VULNCLAW_SAFETY_PYTHON_EXECUTE_MODE` – Overrides `config.safety.python_execute_mode`
- `VULNCLAW_SAFETY_PYTHON_EXECUTE_MAX_LINES` – Overrides `config.safety.python_execute_max_lines`
- `VULNCLAW_SAFETY_PYTHON_EXECUTE_SHOW_WARNING` – Overrides `config.safety.python_execute_show_warning`
- `VULNCLAW_SAFETY_PYTHON_EXECUTE_MAX_OUTPUT_CHARS` – Overrides `config.safety.python_execute_max_output_chars`
- `VULNCLAW_SAFETY_PYTHON_EXECUTE_AUDIT_ENABLED` – Overrides `config.safety.python_execute_audit_enabled`

## Reconnaissance API Keys

VulnClaw accepts external reconnaissance service credentials in two formats. The short-form names are recognized for backward compatibility, while the `VULNCLAW_` prefixed versions follow the standard naming convention:

- **FOFA**: `FOFA_EMAIL` or `VULNCLAW_RECON_FOFA_EMAIL`; `FOFA_KEY` or `VULNCLAW_RECON_FOFA_KEY`
- **Hunter**: `HUNTER_KEY` or `VULNCLAW_RECON_HUNTER_KEY`
- **Quake**: `QUAKE_KEY` or `VULNCLAW_RECON_QUAKE_KEY`
- **ZoomEye**: `ZOOMEYE_KEY` or `VULNCLAW_RECON_ZOOMEYE_KEY`
- **Shodan**: `SHODAN_KEY` or `VULNCLAW_RECON_SHODAN_KEY`
- **ZeroZone**: `ZEROZONE_KEY` or `VULNCLAW_RECON_ZEROZONE_KEY`

## Practical Usage Examples

To override the LLM model and API key without editing [`config.yaml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/config.yaml):

```bash
export VULNCLAW_LLM_PROVIDER=openai
export VULNCLAW_LLM_API_KEY=sk-REDACTED
export VULNCLAW_LLM_MODEL=gpt-4o-mini
vulnclaw run

```

To change session behavior for temporary execution:

```bash
export VULNCLAW_SESSION_MAX_ROUNDS=5
export VULNCLAW_SESSION_SHOW_THINKING=true
export VULNCLAW_SESSION_OUTPUT_DIR=$HOME/.vulnclaw/custom_sessions
vulnclaw start

```

To disable Python execution safety guards:

```bash
export VULNCLAW_SAFETY_PYTHON_EXECUTE_ENABLED=false
vulnclaw run --plugin my_custom_plugin.py

```

To use FOFA reconnaissance with the short-form variable:

```bash
export FOFA_KEY=abcd1234efgh5678
vulnclaw recon fofa --query 'app="Apache"'

```

## Summary

- VulnClaw applies a three-layer configuration system where **environment variables** take precedence over both built-in defaults and [`config.yaml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/config.yaml) values.
- The `_overlay_env` function in [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py) processes all variables beginning with the **`VULNCLAW_`** prefix.
- **LLM**, **Session**, **Safety**, and **Recon** sections each expose specific environment variables that map directly to Pydantic model fields.
- Reconnaissance API keys support dual naming conventions, accepting both `VULNCLAW_RECON_*` prefixed variables and legacy short-form names like `FOFA_KEY`.
- No file modification is required to override configuration—simply export the appropriate variables before invoking the CLI.

## Frequently Asked Questions

### What prefix must environment variables use to override VulnClaw settings?

All environment variables must begin with **`VULNCLAW_`** to be recognized by the configuration loader in [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py). The exception is reconnaissance API keys, which also accept short-form names like `FOFA_KEY` or `SHODAN_KEY` for backward compatibility.

### Do environment variables override the config.yaml file completely?

Yes. According to the implementation in the `_overlay_env` function, environment variables represent the highest-priority layer. If a `VULNCLAW_*` variable is set, it will overwrite the corresponding value from [`config.yaml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/config.yaml) regardless of the YAML content.

### Can I disable Python code execution using environment variables?

Yes. Set `VULNCLAW_SAFETY_PYTHON_EXECUTE_ENABLED=false` to disable the Python execution feature, or use `VULNCLAW_SAFETY_PYTHON_EXECUTE_MODE=restricted` to enforce restricted execution mode without modifying the configuration file.

### Where is the environment variable mapping logic implemented?

The mapping logic is implemented in the private helper function **`_overlay_env`** starting at line 78 of [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py). This function reads the OS environment and applies matching variables to the `VulnClawConfig` Pydantic model defined in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py).