# Configuration

ZeroClaw utilizes a TOML-based configuration system designed for modularity, security, and extensibility. The configuration is primarily managed through `config.toml`, which is loaded from the workspace directory or a fallback legacy location.

***

## Config Struct

The core of the configuration system is defined in `config/schema.rs` via the `Config` struct. It contains over 30 sections, each governing a specific subsystem.

### Global Settings
* `workspace_dir`: The root directory for ZeroClaw data (computed at runtime).
* `config_path`: The path to the active `config.toml`.
* `api_key`: Global API key for the default provider.
* `api_url`: Base URL override for provider APIs.
* `default_provider`: The primary provider ID (e.g., "anthropic", "ollama").
* `default_model`: The default model used for queries.
* `default_temperature`: Model temperature (0.0 to 2.0, default 0.7).

### Subsystem Sections
* `observability`: Tracing and metrics configuration.
* `autonomy`: Security policies and autonomy levels.
* `security`: Secret management and sandbox settings.
* `runtime`: Native vs Docker execution modes.
* `reliability`: Retry logic and fallback providers.
* `scheduler`: Periodic task execution settings.
* `agent`: Orchestration parameters (history size, tool iterations).
* `skills`: Skill loading and prompt injection modes.
* `model_routes`: Routing specific hints to provider/model pairs.
* `embedding_routes`: Routing for vector embedding models.
* `channels_config`: Configuration for Telegram, Discord, Slack, etc.
* `memory`: Backend settings for SQLite or vector storage.
* `storage`: Persistent file storage provider configuration.
* `secrets`: Encryption settings for credentials.
* `browser`: Browser automation and "computer-use" sidecar.
* `identity`: AIEOS or OpenClaw format identity documents.
* `cost`: Budget enforcement and price tracking.
* `hardware`: Physical world interaction (serial/probe) settings.
* `hooks`: Lifecycle and built-in hook toggles.

***

## ModelProviderConfig

ZeroClaw supports multiple provider profiles via the `model_providers` HashMap.

```rust
pub struct ModelProviderConfig {
    pub name: Option<String>,
    pub base_url: Option<String>,
    pub wire_api: Option<String>,
    pub requires_openai_auth: bool,
    pub azure_openai_resource: Option<String>,
    pub azure_openai_deployment: Option<String>,
    pub azure_openai_api_version: Option<String>,
}
```

This allows for configuring multiple instances of the same provider (e.g., local Ollama vs. remote Ollama) or complex Azure OpenAI deployments with distinct resource names and versions.

***

## DelegateAgentConfig

Sub-agents used by the `delegate` tool are configured separately to allow for specialized behavior.

```rust
pub struct DelegateAgentConfig {
    pub provider: String,
    pub model: String,
    pub system_prompt: Option<String>,
    pub api_key: Option<String>,
    pub temperature: Option<f64>,
    pub max_depth: u32,
    pub agentic: bool,
    pub allowed_tools: Vec<String>,
    pub max_iterations: usize,
}
```

Sub-agents can be limited to specific toolsets and have a `max_depth` to prevent infinite delegation loops.

***

## TOML Structure

Example `config.toml` demonstrating provider setup and security routing:

```toml
default_provider = "anthropic"
default_model = "claude-3-5-sonnet"

[model_providers.ollama_local]
name = "ollama"
base_url = "http://localhost:11434"

[[model_routes]]
hint = "fast"
provider = "ollama_local"
model = "llama3"

[security]
encrypt = true

[autonomy]
level = "high"
```

***

## Hot-Reload

ZeroClaw supports hot-reloading for specific runtime fields without requiring a full service restart.

### Supported Fields
* `api_key` / `api_url`
* `default_provider`
* `default_model`
* `default_temperature`
* `reliability` settings

### Mechanism
The system utilizes a file watcher (via `config_file_stamp`) that monitors the `config.toml` modification time. When a change is detected, the `maybe_apply_runtime_config_update` function reloads the file, decrypts any secrets using the `SecretStore`, and updates the runtime provider cache.

***

## Relevance to Luna

ZeroClaw's configuration architecture serves as the target state for [[Configuration]] in Luna. 

* **Subsystem Isolation**: Luna plans to migrate from `appsettings.json` to a per-subsystem TOML structure to improve modularity, similar to ZeroClaw's section pattern.
* **Security First**: The pattern of separating `autonomy` and `security` configs is a requirement for Luna's [[Core]].
* **Hot-Reload**: ZeroClaw's implementation of lightweight file watching for key LLM parameters is a "nice-to-have" feature Luna aims to adopt during the migration.

***

[[Configuration]] | [[Core]]