Configuration Overview

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

# ~/.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:

# 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:

[provider.anthropic]
api_key = "${ANTHROPIC_API_KEY}"

Initialization

Create default configuration:

klaw init

This creates:

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

Provider Configuration

Anthropic (Direct)

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

OpenRouter

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

each::labs

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

Provider Priority

klaw auto-detects provider in this order:

OpenRouter (if OPENROUTER_API_KEY set)
each::labs (if EACHLABS_API_KEY set)
Anthropic (if ANTHROPIC_API_KEY set)

Override with --provider:

klaw chat --provider anthropic

Provider Resilience

Configure retry and fallback behavior per provider:

[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:

[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

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

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

API Server

[server]
port = 8080
host = "0.0.0.0"
auth_token = "${API_TOKEN}"

Orchestrator Configuration

Disabled (Single Agent)

[orchestrator]
mode = "disabled"
default_agent = "assistant"

Rules-Based

[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

[orchestrator]
mode = "ai"
default_agent = "assistant"
model = "claude-haiku-3"  # Fast model for routing

Hybrid

[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:

[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

[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

[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

klaw config view

Set Values

klaw config set defaults.model claude-sonnet-4-20250514
klaw config set logging.level debug

Reset to Defaults

klaw config reset

Context Management

For distributed mode, manage cluster contexts:

# List contexts
klaw context list

# Use a context
klaw context use production/engineering

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

Getting Started

Core Concepts

Guides

Configuration

Architecture

CLI Reference

Resources

Configuration Overview

Configuration Files

Main Configuration

Full Example

Environment Variables

Variable Reference

Initialization

Provider Configuration

Anthropic (Direct)

OpenRouter

each::labs

Provider Priority

Provider Resilience

Cost Budget

Channel Configuration

Slack

API Server

Orchestrator Configuration

Disabled (Single Agent)

Rules-Based

AI-Based

Hybrid

Per-Agent Configuration

Tools Configuration

Logging Configuration

Managing Configuration

View Current Config

Set Values

Reset to Defaults

Context Management

Next Steps

Providers

Channels

​Configuration Files

​Main Configuration

​Full Example

​Environment Variables

​Variable Reference

​Initialization

​Provider Configuration

​Anthropic (Direct)

​OpenRouter

​each::labs

​Provider Priority

​Provider Resilience

​Cost Budget

​Channel Configuration

​Slack

​API Server

​Orchestrator Configuration

​Disabled (Single Agent)

​Rules-Based

​AI-Based

​Hybrid

​Per-Agent Configuration

​Tools Configuration

​Logging Configuration

​Managing Configuration

​View Current Config

​Set Values

​Reset to Defaults

​Context Management

​Next Steps

Providers

Channels

Configuration Files

Main Configuration

Full Example

Environment Variables

Variable Reference

Initialization

Provider Configuration

Anthropic (Direct)

OpenRouter

each::labs

Provider Priority

Provider Resilience

Cost Budget

Channel Configuration

Slack

API Server

Orchestrator Configuration

Disabled (Single Agent)

Rules-Based

AI-Based

Hybrid

Per-Agent Configuration

Tools Configuration

Logging Configuration

Managing Configuration

View Current Config

Set Values

Reset to Defaults

Context Management

Next Steps