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

# Configuration

- src/config/mod.rs
- src/config/types.rs

ZeptoClaw's configuration system provides a flexible, layered approach to managing agent behavior, channel connections, LLM providers, security policies, and runtime settings. Configuration is primarily stored in `~/.zeptoclaw/config.json` with support for environment variable overrides and transparent secret encryption.

This parent page covers the overall configuration architecture, loading mechanisms, and global access patterns. For detailed information about specific aspects:

- Configuration File Structure — Detailed breakdown of config.json sections: agents, providers, channels, tools, memory, safety, runtime, etc.
- Environment Variable Overrides — ZEPTOCLAW_* environment variable naming conventions and overlay mechanism.
- Secrets Management — ENC[...] encryption, master key derivation, rotate command, and TokenStore for OAuth.
- Agent Templates — Built-in and user-defined templates, system prompts, tool restrictions, and model overrides.
- Configuration Validation — Schema validation, diagnostics system, Levenshtein suggestions, and custom tool validation.
- Hot Reload — ConfigWatcher polling, diff detection, transactional reload with rollback.

## Configuration Loading and Precedence

ZeptoClaw uses a four-layer loading system where each layer can override values from previous layers. The loading logic is encapsulated in `Config::load_from_path` [src/config/mod.rs78-125](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L78-L125)

**Diagram: Configuration Loading Pipeline**

```

```

Sources: [src/config/mod.rs50-125](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L50-L125) [src/config/types.rs54-58](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L54-L58)

## Configuration Directory Structure

The configuration directory is located at `~/.zeptoclaw/` (resolved via `Config::dir()` [src/config/mod.rs52-56](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L52-L56)).

**Directory Layout**

If `config.json` does not exist when `Config::load()` is called, the system returns `Config::default()` with built-in defaults, allowing zero-configuration startup [src/config/mod.rs91-93](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L91-L93)

Sources: [src/config/mod.rs51-61](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L51-L61) [src/config/types.rs54-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L54-L139)

## Configuration Section Categories

The `Config` struct in [src/config/types.rs58-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L58-L139) aggregates over 30 configuration sections organized into functional categories.

**Diagram: Configuration Struct to Code Entity Mapping**

```

```

Key sections include:

Sources: [src/config/types.rs58-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L58-L139)

## Global Configuration Singleton

ZeptoClaw maintains a global configuration instance using `OnceCell` and `RwLock` to ensure thread-safe access across the asynchronous runtime [src/config/mod.rs22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L22-L22)

```

```

Components typically access the configuration via the `CONFIG` singleton or by having the `Config` struct passed during initialization of major services like the `AgentLoop`.

Sources: [src/config/mod.rs21-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L21-L22)

## Configuration Validation

To prevent runtime failures due to malformed JSON or typos, ZeptoClaw includes a diagnostic system. It performs:

- Endpoint Validation : Checks provider API bases for valid URLs src/config/mod.rs 98-122
- Diagnostic Logging : Warnings and errors are emitted if endpoints are malformed, with sensitive information redacted src/config/mod.rs 24-48

For details on schema-level validation and Levenshtein suggestions, see **Configuration Validation**.

Sources: [src/config/mod.rs24-48](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L24-L48) [src/config/mod.rs98-122](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L98-L122)

## Environment Variable Overrides

Environment variables follow the pattern `ZEPTOCLAW_SECTION_SUBSECTION_KEY` [src/config/mod.rs66-67](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L66-L67) These are applied after the JSON file is loaded, allowing for dynamic overrides in containerized or CI environments.

Example overrides in `apply_env_overrides` [src/config/mod.rs142-190](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L142-L190):

- ZEPTOCLAW_AGENTS_DEFAULTS_MODEL src/config/mod.rs 147
- ZEPTOCLAW_AGENTS_DEFAULTS_MAX_TOKENS src/config/mod.rs 150
- ZEPTOCLAW_AGENTS_DEFAULTS_TOKEN_BUDGET src/config/mod.rs 175

For the full mapping of variables, see **Environment Variable Overrides**.

Sources: [src/config/mod.rs142-190](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L142-L190)
