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

# Configuration Basics

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

This page introduces ZeptoClaw's configuration system for new users. It covers the configuration file location, basic structure, essential settings for getting started, and validation. For detailed documentation of all configuration sections, see [Configuration File Structure](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Configuration File Structure) For advanced topics like secrets encryption and hot reload, see [Secrets Management](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Secrets Management) and [Hot Reload](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Hot Reload)

## Configuration File Location

ZeptoClaw reads its configuration from a JSON file located at:

```
~/.zeptoclaw/config.json
```

The configuration directory path is resolved by `Config::dir()`, which defaults to `~/.zeptoclaw` [src/config/mod.rs52-56](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L52-L56) If the file does not exist when you run a command, ZeptoClaw uses built-in defaults.

The configuration is loaded via `Config::load()`, which calls `Config::load_from_path(&Self::path())` [src/config/mod.rs68-70](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L68-L70) This process:

1. Reads config.json if it exists src/config/mod.rs 79-81
2. Decrypts any ENC[...] encrypted values using a master key resolved via ZEPTOCLAW_MASTER_KEY or an interactive prompt src/config/mod.rs 84-88
3. Deserializes the JSON into the Config struct src/config/mod.rs 90
4. Applies environment variable overrides via apply_env_overrides() src/config/mod.rs 96
5. Validates provider endpoints for SSRF/private network safety via validate_provider_api_bases() src/config/mod.rs 98-121

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

## Minimal Configuration Example

A minimal configuration to get started with an Anthropic provider looks like:

```

```

This configures:

- The default LLM model to use.
- The workspace directory for file operations.
- An Anthropic API key for the provider.

You can also provide the API key via environment variable `ZEPTOCLAW_PROVIDERS_ANTHROPIC_API_KEY` instead of storing it in the file (recommended for security) [src/config/mod.rs205-207](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L205-L207)

**Sources:** [src/config/types.rs54-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L54-L139) [src/config/mod.rs142-318](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L142-L318)

## Configuration Structure Overview

The configuration is organized into top-level sections, each controlling a different subsystem. The main `Config` struct is defined in `src/config/types.rs`.

### Code Entity Mapping: Config Structure

The following diagram maps the high-level configuration sections to their corresponding Rust structs and file locations.

```

```

**Configuration Section Mapping**

**Sources:** [src/config/types.rs54-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L54-L139) [src/config/types.rs146-187](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L146-L187)

## Essential Agent Settings

The `agents.defaults` section controls core behavior for agent runs. These are the most frequently adjusted settings.

### Model and Provider

The `model` field specifies which LLM to use. The default is set via environment variable `ZEPTOCLAW_AGENTS_DEFAULTS_MODEL` or falls back to a standard default like `"claude-3-5-sonnet-latest"` [src/config/mod.rs147-149](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L147-L149)

### Workspace Directory

The workspace is where file operations (read, write, edit) are performed. Tilde expansion is supported. Tools like `shell` run in this directory by default [src/config/mod.rs144-146](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L144-L146)

### Tool Execution Limits

### Loop Guard

The `loop_guard` configuration prevents runaway agent behavior by monitoring repeated patterns and tool outcomes [src/config/validate.rs72-82](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L72-L82) It can warn or block based on defined thresholds like `warn_threshold` and `block_threshold` [src/config/validate.rs74-75](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L74-L75)

**Sources:** [src/config/mod.rs142-180](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L142-L180) [src/config/validate.rs51-82](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L51-L82)

## Environment Variable Overrides

Any configuration value can be overridden using environment variables with the pattern `ZEPTOCLAW_SECTION_SUBSECTION_KEY`. This is implemented in `Config::apply_env_overrides()` [src/config/mod.rs142](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L142-L142)

**Common Override Examples:**

- ZEPTOCLAW_AGENTS_DEFAULTS_MODEL="gpt-4o" src/config/mod.rs 147
- ZEPTOCLAW_PROVIDERS_ANTHROPIC_API_KEY="..." src/config/mod.rs 205
- ZEPTOCLAW_LOGGING_LEVEL="debug" src/config/mod.rs 293

Environment variables are applied **after** loading the JSON file, ensuring they take precedence [src/config/mod.rs96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L96-L96)

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

## Configuration Validation

ZeptoClaw validates configuration when you run `zeptoclaw config check` or during normal startup.

### Validation Logic Flow

This diagram illustrates how the `validate_config` function in `src/config/validate.rs` processes the raw configuration.

```

```

### Unknown Field Detection

The validator compares JSON keys against known field sets like `KNOWN_TOP_LEVEL` [src/config/validate.rs11-48](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L11-L48) and `KNOWN_AGENTS_DEFAULTS` [src/config/validate.rs51-70](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L51-L70) When an unknown field is found, it uses a `levenshtein()` distance algorithm to suggest corrections [src/config/validate.rs118-140](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L118-L140)

### Network Endpoint Validation

The system includes `validate_network_endpoint()` to prevent SSRF by checking provider URLs against blocked hosts (like local/private IPs) unless `allow_private_endpoints` is explicitly enabled [src/config/validate.rs155-179](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L155-L179)

**Sources:** [src/config/validate.rs1-223](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L1-L223) [src/cli/config.rs11-96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L11-L96)

## Checking Your Configuration

The `zeptoclaw config check` command provides a comprehensive diagnostic report of your current configuration [src/cli/config.rs19-117](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L19-L117)

**The command performs the following:**

1. Locates the config file via Config::path() src/cli/config.rs 20
2. Validates JSON syntax src/cli/config.rs 30-36
3. Runs the diagnostic engine for unknown fields and typos via validate_config() src/cli/config.rs 38
4. Validates custom tool definitions via validate_custom_tools() src/cli/config.rs 54
5. Validates model-provider compatibility via validate_model_provider_compat() src/cli/config.rs 61
6. Performs SSRF validation on provider API bases via validate_provider_api_bases() src/cli/config.rs 80-95

If you need to start fresh, `zeptoclaw config reset` will back up your current configuration with a timestamp and restore defaults [src/cli/config.rs120-159](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L120-L159)

**Sources:** [src/cli/config.rs1-159](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L1-L159) [src/config/validate.rs182-237](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L182-L237)
