# How to Configure VulnClaw: Complete Setup Guide for the AI Security Agent

> Learn how to configure VulnClaw, the AI security agent. Master settings via config.yaml, CLI, presets, and environment variables for robust security.

- Repository: [Unclecheng/VulnClaw](https://github.com/Unclecheng-li/VulnClaw)
- Tags: how-to-guide
- Published: 2026-07-03

---

**VulnClaw stores configuration in `~/.vulnclaw/config.yaml` and supports CLI-based editing, provider presets, and environment variable overrides loaded via Pydantic models in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py).**

VulnClaw is an open-source AI-powered security testing framework that requires specific configuration before executing vulnerability scans. The repository `Unclecheng-li/VulnClaw` manages settings through a layered system combining YAML files, provider presets, and runtime environment variables. Understanding how to configure VulnClaw properly ensures secure LLM integration and proper MCP service activation.

## Where VulnClaw Stores Configuration

By default, VulnClaw creates a user-specific configuration directory at `~/.vulnclaw`. This path can be overridden by setting the `VULNCLAW_CONFIG_DIR` environment variable before running the tool.

The configuration directory contains the following structure:

- `CONFIG_FILE` (`~/.vulnclaw/config.yaml`) – The persistent YAML configuration file
- `SESSIONS_DIR` – Runtime session data storage
- `TARGETS_DIR` – Target specifications and metadata
- `KB_DIR` – Knowledge base storage
- `SKILLS_DIR` – Skill definitions and templates

The directories are created automatically when the first configuration operation runs via the `ensure_dirs()` function in [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py).

## Editing Configuration via CLI

While you can edit the YAML file manually, VulnClaw provides a safe, typed CLI interface that validates inputs against Pydantic schemas defined in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py).

Use the `vulnclaw config set` command with dot-notation to modify nested values:

```bash

# Set LLM API credentials

vulnclaw config set llm.api_key sk-xxxxxxxxxxxxxxxxxxxx

# Adjust session limits

vulnclaw config set session.max_rounds 30

# Disable Python execution for safety

vulnclaw config set safety.enable_python_execute false

```

The CLI parses the key, coerces the value to the appropriate type (int, bool, str), and persists changes through `set_config_value()` → `save_config()` in [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py).

## Configuring LLM Providers

VulnClaw ships with built-in support for 13 OpenAI-compatible providers defined in the `PROVIDER_PRESETS` constant within [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py). The `apply_provider_preset()` function in [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py) automatically configures the base URL and default model for your chosen provider.

Switch providers using the preset command:

```bash

# Auto-configure MiniMax (fills base_url and model)

vulnclaw config provider minimax

# Override with custom endpoint if needed

vulnclaw config set llm.base_url https://my-api.example.com/v1
vulnclaw config set llm.model my-custom-model

```

## Setting Up MCP (Model-Context-Protocol) Services

MCP servers extend VulnClaw's capabilities with external tools like Chrome DevTools or Burp Suite. Built-in servers are defined in `BUILTIN_MCP_SERVERS` in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py).

Enable services via the CLI:

```bash
vulnclaw config set mcp.servers.chrome-devtools.enabled true
vulnclaw config set mcp.servers.burp.enabled true

```

Each server configuration includes a `transport` field supporting three types defined in `MCPTransportConfig`: `stdio`, `sse`, or `streamable-http`. The transport specifies how VulnClaw communicates with the MCP server, including command paths, arguments, or URLs.

## Overriding Settings with Environment Variables

Any configuration field can be overridden at runtime using environment variables prefixed with `VULNCLAW_`. The `_overlay_env()` function in [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py) processes these variables after loading the YAML file, ensuring the precedence order: **environment variables > config file > built-in defaults**.

Common environment overrides:

```bash
export VULNCLAW_LLM_API_KEY=sk-xxxx
export VULNCLAW_SESSION_MAX_ROUNDS=20
export VULNCLAW_SAFETY_PYTHON_EXECUTE_ENABLED=false

```

For reconnaissance services like FOFA or Shodan, export the standard key names (`FOFA_KEY`, `SHODAN_KEY`) and the loader will map them into `config.recon` automatically.

## Configuring Safety and Sandbox Options

The `safety` section in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py) controls the `python_execute` tool used by the agent for dynamic code execution. Configure these carefully based on your risk tolerance:

- **`enable_python_execute`** – Default `true`; set to `false` to disable the tool entirely
- **`python_execute_mode`** – Default `trusted-local`; options include `safe`, `lab`, or `trusted-local`
- **`python_execute_max_lines`** – Default `50`; limits code length per execution
- **`python_execute_audit_enabled`** – Default `true`; logs all executions to `python_execute_audit.jsonl`

Modify via CLI:

```bash
vulnclaw config set safety.python_execute_mode safe
vulnclaw config set safety.python_execute_max_lines 25

```

## Loading Configuration Programmatically

Access the merged configuration in Python using the `load_config()` function from [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py):

```python
from vulnclaw.config.settings import load_config

cfg = load_config()
print("LLM provider:", cfg.llm.provider)
print("Base URL:", cfg.llm.base_url)
print("Session dir:", cfg.session.output_dir)

```

This returns the final configuration object with all defaults, file values, and environment overlays applied.

## Summary

- **Configuration location**: `~/.vulnclaw/config.yaml` (override with `VULNCLAW_CONFIG_DIR`)
- **CLI editing**: Use `vulnclaw config set <key> <value>` for type-safe updates via `set_config_value()`
- **Provider setup**: Run `vulnclaw config provider <name>` to apply presets from `PROVIDER_PRESETS`
- **MCP services**: Enable built-in servers in `BUILTIN_MCP_SERVERS` using dot-notation keys
- **Environment overrides**: Prefix any config key with `VULNCLAW_` and export; processed by `_overlay_env()`
- **Safety controls**: Adjust `python_execute` settings through the `safety` section in schema.py

## Frequently Asked Questions

### Where is the VulnClaw configuration file located?

VulnClaw stores its configuration in `~/.vulnclaw/config.yaml` by default. The directory is created automatically by `ensure_dirs()` in [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py) when you first run a configuration command. You can relocate this directory by setting the `VULNCLAW_CONFIG_DIR` environment variable before executing VulnClaw.

### How do I switch between different LLM providers?

Use the `vulnclaw config provider <name>` command to switch between the 13 built-in OpenAI-compatible providers. This invokes `apply_provider_preset()` in [`vulnclaw/config/settings.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py), which automatically populates the `base_url` and `model` fields in [`config.yaml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/config.yaml) based on the `PROVIDER_PRESETS` definition in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py).

### Can I configure VulnClaw using only environment variables without editing YAML?

Yes. Any configuration field supports environment variable overrides using the `VULNCLAW_` prefix (e.g., `VULNCLAW_LLM_API_KEY`). The `_overlay_env()` function loads these after the YAML file, ensuring environment variables take precedence. For CI/CD deployments, you can rely entirely on environment variables without creating a [`config.yaml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/config.yaml) file.

### How do I disable Python code execution for security hardening?

Set `vulnclaw config set safety.enable_python_execute false` or export `VULNCLAW_SAFETY_ENABLE_PYTHON_EXECUTE=false`. This disables the `python_execute` tool entirely. Alternatively, use `vulnclaw config set safety.python_execute_mode safe` to restrict execution to sandboxed environments, as defined in the Pydantic models in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py).