<!-- source: https://deepwiki.com/qhkm/zeptoclaw/5.2-environment-variable-overrides -->

# Environment Variable Overrides

- landing/zeptoclaw/docs/src/content/docs/concepts/tools.md
- landing/zeptoclaw/docs/src/content/docs/getting-started/introduction.md
- landing/zeptoclaw/docs/src/content/docs/reference/environment.md
- landing/zeptoclaw/docs/src/content/docs/reference/tools.md
- src/config/mod.rs
- src/config/types.rs

## Purpose and Scope

This document describes ZeptoClaw's environment variable override system, which allows runtime configuration of settings without modifying `config.json`. Environment variables follow a hierarchical naming convention and are applied after file-based configuration is loaded, enabling deployment-specific customization, secret injection, and containerized configuration.

For general configuration structure and validation, see [Configuration File Structure](/qhkm/zeptoclaw/5.1-configuration-file-structure). For secret encryption and master key management, see [Secrets Management](/qhkm/zeptoclaw/5.3-secrets-management).

## Override Resolution Flow

ZeptoClaw loads configuration in a multi-stage pipeline. The `Config::load()` method handles the sequence of reading from disk, decrypting sensitive fields, and then overlaying environment variables.

### Configuration Loading Pipeline

```

```

**Sources:** [src/config/mod.rs68-70](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L68-L70) [src/config/mod.rs79-96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L79-L96)

The resolution order ensures environment variables always win:

1. File load — Config::load_from_path() reads ~/.zeptoclaw/config.json src/config/mod.rs 59-61
2. Decryption — ENC[...] values are decrypted using decrypt_config_values if a master key is resolved via ZEPTOCLAW_MASTER_KEY or terminal prompt src/config/mod.rs 84-88
3. Deserialization — JSON is parsed into the Config struct defined in src/config/types.rs src/config/mod.rs 90
4. Environment overlay — apply_env_overrides() iterates through known environment patterns and mutates the struct src/config/mod.rs 96
5. Validation — The validate_provider_api_bases and general validation logic checks for invalid endpoints or structural errors src/config/mod.rs 98-122

**Sources:** [src/config/mod.rs50-131](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L50-L131) [src/config/types.rs54-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L54-L139)

## Naming Convention

Environment variables follow a strict hierarchical pattern:

```
ZEPTOCLAW_<SECTION>_<SUBSECTION>_<KEY>
```

**Mapping rules:**

- Section names match top-level Config struct fields (e.g., agents , providers , channels ) src/config/types.rs 58-139
- Subsections match nested struct fields (e.g., defaults within AgentConfig ) src/config/mod.rs 144-145
- Keys match leaf fields (e.g., model , max_tokens ) src/config/mod.rs 147-150
- Underscores separate hierarchy levels.

### Common Mapping Examples

**Sources:** [src/config/mod.rs142-179](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L142-L179) [src/config/types.rs167-177](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L167-L177) [landing/zeptoclaw/docs/src/content/docs/reference/environment.md9-10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/reference/environment.md?plain=1#L9-L10)

## Override Categories

### Agent and Loop Guard Configuration

The `AgentConfig` defaults are the most frequently overridden settings, controlling the primary LLM behavior and safety thresholds.

### Agent Settings Mapping

```

```

**Special parsing logic:**

- MESSAGE_QUEUE_MODE : Matches "collect" or "followup" strings (case-insensitive) src/config/mod.rs 180-186
- COMPACT_TOOLS : Parsed as true if the string is "true" or "1" src/config/mod.rs 187-189
- Numbers : Uses standard library parse() with error handling to prevent crashes on malformed input src/config/mod.rs 150-154

**Sources:** [src/config/mod.rs142-189](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L142-L189) [src/config/types.rs58-60](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L58-L60)

### Provider Configuration

Provider overrides allow setting API keys and endpoints dynamically. The system supports a wide range of providers via the `ProvidersConfig` struct.

**Key Variables:**

- ZEPTOCLAW_PROVIDERS_ANTHROPIC_API_KEY landing/zeptoclaw/docs/src/content/docs/reference/environment.md 15
- ZEPTOCLAW_PROVIDERS_OPENAI_API_KEY landing/zeptoclaw/docs/src/content/docs/reference/environment.md 16

**Special provider features:**

- Retry Logic : Configurable via ZEPTOCLAW_PROVIDERS_RETRY_ENABLED , MAX_RETRIES , and delay settings landing/zeptoclaw/docs/src/content/docs/reference/environment.md 38-41
- Fallback : Configurable via ZEPTOCLAW_PROVIDERS_FALLBACK_ENABLED and FALLBACK_PROVIDER landing/zeptoclaw/docs/src/content/docs/reference/environment.md 47-48

**Sources:** [src/config/types.rs63-64](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L63-L64) [landing/zeptoclaw/docs/src/content/docs/reference/environment.md11-49](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/reference/environment.md?plain=1#L11-L49)

### Channel Configuration

Credentials for Telegram, Discord, Slack, and other communication interfaces can be injected via environment variables to avoid storing tokens in plain text.

### Channel Credentials Flow

```

```

**Sources:** [src/config/types.rs61-62](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L61-L62) [landing/zeptoclaw/docs/src/content/docs/reference/environment.md18-24](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/reference/environment.md?plain=1#L18-L24)

## Type-Specific Parsing Internals

The implementation in `src/config/mod.rs` uses explicit parsing for different Rust types to ensure the `Config` struct remains type-safe.

### Boolean Values

Booleans are checked for specific truthy strings.

```

```

### Numeric Values

Numbers use the standard library `parse()` method. If parsing fails, the value is ignored, preserving the original config or default.

```

```

### String Values

Strings are assigned directly from the environment variable if present.

```

```

## Validation and Diagnostics

Because environment variables are applied after JSON deserialization, they bypass initial `serde` type checks. To ensure configuration integrity, ZeptoClaw performs post-load validation.

- Endpoint Validation : validate_provider_api_bases checks all provider URLs for correct formatting and accessibility src/config/mod.rs 98-106
- Error Handling : If a critical validation error is found (e.g., an invalid mandatory endpoint), the configuration load fails with a ZeptoError::Config src/config/mod.rs 118-122
- Sanitization : Diagnostic messages are sanitized to prevent leaking sensitive information like embedded passwords in URLs src/config/mod.rs 24-48

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

## Secret Management Integration

Environment variables play a critical role in the security of the configuration:

1. ZEPTOCLAW_MASTER_KEY : This variable is the primary method for providing the decryption key for ENC[...] values in non-interactive environments (like CI/CD or Docker) src/config/mod.rs 76-77 landing/zeptoclaw/docs/src/content/docs/reference/environment.md 97
2. Sensitive Overrides : Overriding api_key or token fields via environment variables prevents these secrets from ever being written to the config.json file on disk, which is a recommended security practice landing/zeptoclaw/docs/src/content/docs/reference/environment.md 117-120

**Sources:** [src/config/mod.rs72-88](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L72-L88) [landing/zeptoclaw/docs/src/content/docs/reference/environment.md93-120](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/reference/environment.md?plain=1#L93-L120)
