<!-- source: https://deepwiki.com/qhkm/zeptoclaw/5.1-configuration-file-structure -->

# Configuration File Structure

- landing/zeptoclaw/docs/src/content/docs/concepts/channels.md
- landing/zeptoclaw/docs/src/content/docs/guides/security.md
- landing/zeptoclaw/docs/src/content/docs/reference/configuration.md
- src/config/mod.rs
- src/config/types.rs

This page documents the complete structure of ZeptoClaw's configuration file located at `~/.zeptoclaw/config.json`. It covers all top-level configuration sections, their fields, default values, and relationships. For information about environment variable overrides, see [Environment Variable Overrides](/qhkm/zeptoclaw/5.2-environment-variable-overrides). For secrets encryption and management, see [Secrets Management](/qhkm/zeptoclaw/5.3-secrets-management).

## Configuration File Overview

ZeptoClaw uses a single JSON configuration file that controls all aspects of the system's behavior. The configuration file is located at `~/.zeptoclaw/config.json` by default and follows a hierarchical structure with dozens of top-level sections managed by the `Config` struct.

**Configuration File Path:**

- Default: ~/.zeptoclaw/config.json
- Path resolution: Config::path() in src/config/mod.rs 59-61
- Directory resolution: Config::dir() in src/config/mod.rs 52-56

**File Format:**

- JSON format with automated serialization/deserialization via serde .
- All fields are optional with sensible defaults defined in Default implementations or #[serde(default)] markers src/config/types.rs 56-57
- Supports encrypted values in ENC[...] format which are decrypted during the load process src/config/mod.rs 84-88
- Deserialized into the Config struct at src/config/types.rs 55-139

Sources: [src/config/types.rs55-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L55-L139) [src/config/mod.rs52-61](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L52-L61)

## Configuration Precedence

Configuration values are resolved in the following order (highest to lowest priority):

```

```

**Configuration Loading Process:**

The `Config::load_from_path` function [src/config/mod.rs78-125](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L78-L125) handles the transformation from raw JSON to the typed struct, including decryption and validation.

```

```

Sources: [src/config/mod.rs78-125](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L78-L125) [src/config/mod.rs142-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L142-L200)

## Top-Level Configuration Structure

The `Config` struct at [src/config/types.rs55-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L55-L139) contains the following primary sections:

Sources: [src/config/types.rs55-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L55-L139) [src/config/types.rs167-177](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L167-L177) [src/config/types.rs24-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L24-L39)

## Core Configuration Sections

### 1. agents (AgentConfig)

Controls the execution parameters for the `AgentLoop`. This includes defaults for all agents spawned by the system.

**AgentDefaults Fields:** [src/config/types.rs212-239](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L212-L239) (Internal struct of `AgentConfig`)

Sources: [src/config/types.rs212-239](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L212-L239) [src/config/mod.rs143-189](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L143-L189)

### 2. providers (ProvidersConfig)

Configures the `ProviderRegistry` and error handling decorators.

**Structure:** [src/config/types.rs554-577](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L554-L577)

- Credentials : Supports Anthropic, OpenAI, Gemini, Groq, Ollama, vLLM, OpenRouter, and Zhipu.
- Retry : RetryConfig src/config/types.rs 594-615 manages exponential backoff and max attempts.
- Fallback : FallbackConfig src/config/types.rs 619-635 enables automatic provider switching when the primary model fails.

Sources: [src/config/types.rs554-635](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L554-L635)

### 3. safety (SafetyConfig)

The safety layer protects against prompt injection and accidental data leaks.

**Structure Reference:** `crate::safety::SafetyConfig` [src/config/types.rs94](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L94-L94)

Sources: [src/config/types.rs94](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L94-L94)

### 4. runtime (RuntimeConfig)

Defines how shell tools and code execution are isolated to prevent host compromise.

**RuntimeType Enum:** [src/config/types.rs922-933](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L922-L933)

- Native : Direct host execution (low security).
- Docker : Isolation via Docker containers.
- Apple : macOS-native virtualization (macOS 15+).
- Landlock : Linux ABI isolation.

Sources: [src/config/types.rs922-933](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L922-L933) [src/config/types.rs936-966](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L936-L966)

## Configuration Validation

ZeptoClaw performs structural validation on startup to catch typos and unknown fields using a diagnostic system.

**Validation Flow:**
The `validate_config` function [src/config/validate.rs149-216](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L149-L216) iterates through the raw JSON and compares keys against `KNOWN_TOP_LEVEL` [src/config/validate.rs7-44](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L7-L44)

**Levenshtein Suggestions:**
If an unknown field is found, the system uses `levenshtein()` [src/config/validate.rs114-136](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L114-L136) to suggest the closest valid field name via `suggest_field()` [src/config/validate.rs139-146](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L139-L146)

```

```

Sources: [src/config/validate.rs114-216](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L114-L216) [src/config/validate.rs7-44](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L7-L44)

## Implementation: Code Entity Mapping

The following diagram bridges the configuration data to the internal Rust entities that consume them.

```

```

Sources: [src/config/types.rs55-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L55-L139) [src/config/mod.rs22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L22-L22) [src/config/types.rs26-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L26-L39)
