Skip to main content

​
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:
  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: 
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
FieldDescriptionDefault
max_retriesNumber of retry attempts with exponential backoff3
fallbackName of fallback provider to use after retries exhaustNone
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"]
FieldDescriptionDefault
toolsAllowlist of tool names this agent can useAll tools
max_iterationsMaximum agent loop iterations50
require_approvalTools 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

​
Next Steps

Providers

Configure LLM providers

Channels

Set up communication channels