<!-- source: https://deepwiki.com/qhkm/zeptoclaw/5.5-configuration-validation -->

# Configuration Validation

- src/cli/config.rs
- src/cli/mod.rs
- src/cli/onboard.rs
- src/config/validate.rs

Configuration validation ensures that ZeptoClaw's `config.json` file is well-formed, uses recognized field names, and follows security best practices. The validation system detects typos, suggests corrections using Levenshtein distance, and performs deep semantic checks on provider endpoints and custom tool definitions.

For information about configuration file structure and sections, see [Configuration File Structure](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Configuration File Structure) For secrets encryption validation, see [Secrets Management](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Secrets Management) For hot reload validation, see [Hot Reload](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Hot Reload)

## System Overview

The configuration validation system performs four main functions:

1. Schema validation : Checks that all field names in the config file are recognized src/config/validate.rs 204-222
2. Typo detection : Suggests correct field names when unknown fields are encountered using edit distance src/config/validate.rs 143-150
3. Semantic validation : Validates custom tool definitions, model-provider compatibility, and security policies src/cli/config.rs 52-72
4. Network safety validation : Checks provider endpoints for SSRF (Server-Side Request Forgery) risks src/config/validate.rs 155-179

Validation runs in two contexts:

- On-demand via CLI : The zeptoclaw config check command (implemented in cmd_config_check ) validates the config file and reports diagnostics src/cli/config.rs 19-117
- At load time : The Config::load() flow reads the file, decrypts values, and applies environment overrides before the system starts src/cli/config.rs 53

### High-Level Data Flow

The following diagram bridges the Natural Language concepts to the specific Code Entities involved in the validation process.

**Title: Configuration Validation Data Flow**

```

```

**Sources:** [src/config/validate.rs1-182](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L1-L182) [src/cli/config.rs11-117](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L11-L117) [src/cli/onboard.rs17-68](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L17-L68)

## Validation Architecture

The architecture separates raw JSON structure checking from post-parsing semantic checks.

**Title: Schema vs Semantic Validation Entities**

```

```

**Sources:** [src/config/validate.rs11-48](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L11-L48) [src/config/validate.rs143-150](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L143-L150) [src/config/validate.rs182-222](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L182-L222) [src/cli/config.rs52-80](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L52-L80)

## Known Field Registry

The validation system maintains compile-time lists of recognized configuration field names in `src/config/validate.rs`. Unknown fields trigger error diagnostics with Levenshtein-based suggestions.

### Top-Level Sections

**Sources:** [src/config/validate.rs11-82](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L11-L82)

## Levenshtein Distance Suggestions

The validation system uses edit distance to suggest corrections when unknown field names are encountered. If the Levenshtein distance between the unknown field and a known field is ≤ 3, a suggestion is appended to the error diagnostic.

- levenshtein(a, b) : Implements the standard matrix-based edit distance algorithm to calculate the number of single-character edits required to change one string into another src/config/validate.rs 118-140
- suggest_field(unknown, known) : Iterates through known fields, finds the one with the minimum distance (if ≤ 3), and returns a formatted "did you mean?" string src/config/validate.rs 143-150

**Sources:** [src/config/validate.rs118-150](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L118-L150)

## Advanced Semantic Validation

### Network Safety (SSRF Protection)

The function `validate_network_endpoint` ensures that provider endpoints do not target local/private networks unless explicitly allowed.

- Protocol Check : Only http and https schemes are permitted src/config/validate.rs 161-169
- SSRF Shield : Uses is_blocked_host (from src/tools/web ) to identify loopback or private IP ranges src/config/validate.rs 171-176
- Override : During onboarding, users can allow private endpoints via the --allow-private-endpoints flag src/cli/onboard.rs 17-18

### Model-Provider Compatibility

The validator checks if the configured `model` string is compatible with the selected `provider` logic. For example, it detects if a user is trying to use an OpenAI model ID with an Anthropic provider configuration [src/cli/config.rs61-72](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L61-L72)

### Custom Tool Validation

The `validate_custom_tools()` function performs checks on user-defined tools in the `custom_tools` section:

- Naming : Ensures tool names follow allowed patterns.
- Shadowing : Checks if a custom tool name conflicts with built-in system tools.
- Descriptions : Warns if tool descriptions are excessively long, which could negatively impact the LLM's context window src/cli/config.rs 54-58

## CLI Integration

The `zeptoclaw config check` command (located in `src/cli/config.rs`) provides the primary interface for users to validate their setup.

1. JSON Parsing : Reads the file and parses it into a serde_json::Value src/cli/config.rs 28-36
2. Raw Validation : Calls validate_config(&raw) to detect unknown fields and typos src/cli/config.rs 38
3. Typed Loading : Calls Config::load() to verify deserialization and environment overrides src/cli/config.rs 53
4. Custom Tool Check : Calls validate_custom_tools(&config) src/cli/config.rs 54
5. Provider Check : Validates API base URLs for SSRF risks via validate_provider_api_bases src/cli/config.rs 80
6. Workspace Hint : If a workspace is configured but tools.coding_tools is false, it provides a hint to enable them src/cli/config.rs 98-105
7. Exit Codes : If any DiagnosticLevel::Error is found, the CLI exits with status 1 src/cli/config.rs 112-114

**Sources:** [src/cli/config.rs11-117](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L11-L117) [src/config/validate.rs182-222](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L182-L222)
