> ## Documentation Index
> Fetch the complete documentation index at: https://klaw.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Overview

> Complete guide to configuring klaw

## Configuration Files

klaw uses TOML for configuration. Files are stored in `~/.klaw/`:

```
~/.klaw/
├── config.toml          # Main configuration
├── workspace/           # Agent context files
│   ├── SOUL.md
│   ├── AGENTS.md
│   └── TOOLS.md
├── agents/              # Agent definitions
├── skills/              # Installed skills
└── state/               # Runtime state
```

## Main Configuration

### Full Example

```toml theme={null}
# ~/.klaw/config.toml

# Default settings
[defaults]
model = "claude-sonnet-4-20250514"
agent = "default"
namespace = "default"
max_session_cost = 5.00

# Workspace directory
[workspace]
path = "~/.klaw/workspace"

# LLM Providers
[provider.anthropic]
api_key = "${ANTHROPIC_API_KEY}"
model = "claude-sonnet-4-20250514"
max_retries = 3
fallback = "openrouter"

[provider.openrouter]
api_key = "${OPENROUTER_API_KEY}"
model = "anthropic/claude-sonnet-4"
max_retries = 3

[provider.eachlabs]
api_key = "${EACHLABS_API_KEY}"
model = "anthropic/claude-sonnet-4-5"

# Slack integration
[channel.slack]
enabled = true
bot_token = "${SLACK_BOT_TOKEN}"
app_token = "${SLACK_APP_TOKEN}"

# Orchestrator settings
[orchestrator]
mode = "hybrid"
default_agent = "default"

[[orchestrator.rules]]
pattern = "(?i)(code|bug|fix)"
agent = "coder"

[[orchestrator.rules]]
pattern = "(?i)(research|search)"
agent = "researcher"

# Server settings
[server]
port = 8080
host = "127.0.0.1"

# Logging
[logging]
level = "info"
file = "~/.klaw/logs/klaw.log"

# Tools configuration
[tools]
timeout = 120000
output_limit = 30000
```

## Environment Variables

Environment variables override config file values:

```bash theme={null}
# Provider API Keys
export ANTHROPIC_API_KEY=sk-ant-...
export OPENROUTER_API_KEY=sk-or-...
export EACHLABS_API_KEY=...

# Slack
export SLACK_BOT_TOKEN=xoxb-...
export SLACK_APP_TOKEN=xapp-...

# Overrides
export KLAW_MODEL=claude-sonnet-4-20250514
export KLAW_STATE_DIR=/custom/path
```

### Variable Reference

Use `${VAR_NAME}` in config files:

```toml theme={null}
[provider.anthropic]
api_key = "${ANTHROPIC_API_KEY}"
```

## Initialization

Create default configuration:

```bash theme={null}
klaw init
```

This creates:

* `~/.klaw/config.toml` with defaults
* `~/.klaw/workspace/` with template files
* `~/.klaw/agents/` directory

## Provider Configuration

### Anthropic (Direct)

```toml theme={null}
[provider.anthropic]
api_key = "${ANTHROPIC_API_KEY}"
model = "claude-sonnet-4-20250514"
```

### OpenRouter

```toml theme={null}
[provider.openrouter]
api_key = "${OPENROUTER_API_KEY}"
model = "anthropic/claude-sonnet-4"
```

### each::labs

```toml theme={null}
[provider.eachlabs]
api_key = "${EACHLABS_API_KEY}"
model = "anthropic/claude-sonnet-4-5"
```

### Provider Priority

klaw auto-detects provider in this order:

1. OpenRouter (if `OPENROUTER_API_KEY` set)
2. each::labs (if `EACHLABS_API_KEY` set)
3. Anthropic (if `ANTHROPIC_API_KEY` set)

Override with `--provider`:

```bash theme={null}
klaw chat --provider anthropic
```

### Provider Resilience

Configure retry and fallback behavior per provider:

```toml theme={null}
[provider.anthropic]
api_key = "${ANTHROPIC_API_KEY}"
model = "claude-sonnet-4-20250514"
max_retries = 3       # Retry up to 3 times with exponential backoff
fallback = "openrouter" # Fallback provider on failure
```

| Field         | Description                                            | Default |
| ------------- | ------------------------------------------------------ | ------- |
| `max_retries` | Number of retry attempts with exponential backoff      | `3`     |
| `fallback`    | Name of fallback provider to use after retries exhaust | None    |

Retries use exponential backoff starting at 1s, capped at 30s, with 25% random jitter. Retryable errors include HTTP 429 (rate limit), 500, 502, 503, and connection errors.

### Cost Budget

Set a per-session spending limit in the `[defaults]` section:

```toml theme={null}
[defaults]
max_session_cost = 5.00  # Maximum cost in USD per session (0 = unlimited)
```

When the budget is reached, the agent stops with a `budget_exceeded` error. A warning is logged when cost reaches 80% of the budget.

## Channel Configuration

### Slack

```toml theme={null}
[channel.slack]
enabled = true
bot_token = "${SLACK_BOT_TOKEN}"
app_token = "${SLACK_APP_TOKEN}"

# Optional
allowed_channels = ["C123", "C456"]
default_agent = "assistant"
```

### API Server

```toml theme={null}
[server]
port = 8080
host = "0.0.0.0"
auth_token = "${API_TOKEN}"
```

## Orchestrator Configuration

### Disabled (Single Agent)

```toml theme={null}
[orchestrator]
mode = "disabled"
default_agent = "assistant"
```

### Rules-Based

```toml theme={null}
[orchestrator]
mode = "rules"
default_agent = "assistant"

[[orchestrator.rules]]
pattern = "(?i)(code|implement|fix)"
agent = "coder"

[[orchestrator.rules]]
pattern = "(?i)(deploy|docker)"
agent = "devops"
```

### AI-Based

```toml theme={null}
[orchestrator]
mode = "ai"
default_agent = "assistant"
model = "claude-haiku-3"  # Fast model for routing
```

### Hybrid

```toml theme={null}
[orchestrator]
mode = "hybrid"
default_agent = "assistant"
model = "claude-haiku-3"

# Rules checked first
[[orchestrator.rules]]
pattern = "(?i)deploy"
agent = "devops"

# AI handles everything else
```

## Per-Agent Configuration

Define per-agent settings under `[agent.<name>]`. Each agent can have its own tool allowlist, iteration limit, and approval requirements:

```toml theme={null}
[agent.default]
tools = ["bash", "read", "write", "edit", "glob", "grep", "web_fetch", "web_search"]
max_iterations = 50
require_approval = ["bash"]

[agent.researcher]
tools = ["read", "glob", "grep", "web_fetch", "web_search"]
max_iterations = 30

[agent.coder]
tools = ["bash", "read", "write", "edit", "glob", "grep"]
max_iterations = 100
require_approval = ["bash", "write"]
```

| Field              | Description                                        | Default   |
| ------------------ | -------------------------------------------------- | --------- |
| `tools`            | Allowlist of tool names this agent can use         | All tools |
| `max_iterations`   | Maximum agent loop iterations                      | `50`      |
| `require_approval` | Tools requiring user confirmation before execution | `[]`      |

## Tools Configuration

```toml theme={null}
[tools]
timeout = 120000          # 2 minutes default
output_limit = 30000      # Max output chars

[tools.bash]
allowed_commands = ["git", "npm", "go"]
blocked_commands = ["rm -rf /"]

[tools.web]
timeout = 30000
allowed_domains = ["*.example.com"]
```

## Logging Configuration

```toml theme={null}
[logging]
level = "info"            # debug, info, warn, error
file = "~/.klaw/logs/klaw.log"
format = "json"           # json or text
max_size = 100            # MB
max_backups = 3
```

## Managing Configuration

### View Current Config

```bash theme={null}
klaw config view
```

### Set Values

```bash theme={null}
klaw config set defaults.model claude-sonnet-4-20250514
klaw config set logging.level debug
```

### Reset to Defaults

```bash theme={null}
klaw config reset
```

## Context Management

For distributed mode, manage cluster contexts:

```bash theme={null}
# List contexts
klaw context list

# Use a context
klaw context use production/engineering

# Create context
klaw context set mycontext --cluster prod --namespace eng
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Providers" icon="plug" href="/docs/configuration/providers">
    Configure LLM providers
  </Card>

  <Card title="Channels" icon="message" href="/docs/configuration/channels">
    Set up communication channels
  </Card>
</CardGroup>