Configuration¶

# Path to agent workspaces directory
workspaces_path: agent_workspaces

# Logging configuration
logging:
  level: INFO              # DEBUG, INFO, WARNING, ERROR, CRITICAL
  directory: logs          # Directory for log files
  max_size_mb: 10          # Maximum log file size before rotation
  backup_count: 5          # Number of backup files to keep
  per_workspace: true      # Create separate log files per workspace

# Queue settings (OpenClaw-inspired)
queue:
  mode: collect          # collect, steer, followup, interrupt
  debounce_ms: 1000      # Wait before processing collected messages
  cap: 20                # Max queued messages per session
  drop_policy: summarize # old, new, summarize

# Lane concurrency limits
lanes:
  main_concurrency: 4      # Interactive message processing
  subagent_concurrency: 8  # Delegated subagent tasks
  cron_concurrency: 2      # Scheduled jobs

# Channel configurations
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users: []
    allowed_groups: []

# Agent defaults
agent:
  # Model format: provider:model_id
  model: anthropic:claude-sonnet-4-20250514
  max_turns: 50
  temperature: 0.7

# Builtin capabilities
builtins:
  allow: []
  deny: []

  brave_search:
    enabled: true
    config:
      count: 5

  whisper:
    enabled: true
    config:
      model: whisper-1

  elevenlabs:
    enabled: true
    config:
      voice_id: 21m00Tcm4TlvDq8ikWAM
      model_id: eleven_turbo_v2_5

  browser:
    enabled: true
    config:
      headless: true
      allowed_domains: []
      blocked_domains: []
      timeout_seconds: 30
      persist_cookies: false

  file_persistence:
    enabled: true
    config:
      max_file_size: 52428800  # 50 MB
      clear_data_after_save: false

  # email:
  #   enabled: true
  #   config:
  #     provider: gmail
  #     service_account_file: config/service-account.json
  #     delegated_user: agent@yourdomain.com
  #     allowed_recipients:
  #       - "*@yourdomain.com"
  #     max_recipients: 10

workspaces_path: agent_workspaces

logging:
  level: INFO              # Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
  directory: logs          # Directory for log files
  max_size_mb: 10          # Max log file size before rotation
  backup_count: 5          # Number of backup files to keep
  per_workspace: true      # Separate log file per workspace

queue:
  mode: collect          # Queue mode
  debounce_ms: 1000      # Debounce delay in milliseconds
  cap: 20                # Max messages per session
  drop_policy: summarize # Policy when cap is reached

lanes:
  main_concurrency: 4      # User messages
  subagent_concurrency: 8  # Delegated tasks
  cron_concurrency: 2      # Scheduled jobs

# Global defaults (config.yaml) — optional
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users: []
    allowed_groups: []

agent:
  model: anthropic:claude-sonnet-4-20250514
  max_turns: 50
  temperature: 0.7

builtins:
  allow: []  # Empty = allow all available
  deny:
    - group:voice  # Deny entire groups

  brave_search:
    enabled: true
    config:
      count: 5  # Number of search results

agent_workspaces/<workspace-name>/config/agent.yaml

name: Gilfoyle
description: Sarcastic systems architect
timezone: America/Denver  # IANA timezone identifier (default: UTC)

model:
  provider: anthropic
  model: claude-sonnet-4-20250514
  api_key: ${ANTHROPIC_API_KEY}
  temperature: 0.5
  max_turns: 50

channel:
  type: telegram
  token: ${TELEGRAM_BOT_TOKEN}
  allowed_users: [123456789]  # Only this user
  allowed_groups: []

queue:
  mode: steer          # Override global queue mode
  debounce_ms: 500     # Faster response

builtins:
  deny:
    - elevenlabs       # Disable TTS for this workspace

  browser:
    enabled: true
    config:
      allowed_domains:
        - "calendly.com"
        - "*.google.com"
      blocked_domains: []
      persist_cookies: true

heartbeat:
  enabled: true
  interval_minutes: 30
  active_hours: "09:00-17:00"
  suppress_ok: true
  delivery: channel
  target_channel: telegram
  target_id: 123456789

approval_gates:
  enabled: true
  timeout_seconds: 120
  default_action: deny
  tools:
    overwrite_file:
      require_approval: true
      show_args: true

status_reminder:
  enabled: true
  threshold: 5
  max_reminders: 3
  cooldown_turns: 1

name: Gilfoyle
description: Sarcastic systems architect
timezone: America/Denver  # IANA timezone identifier

model:
  provider: anthropic
  model: claude-sonnet-4-20250514
  api_key: ${ANTHROPIC_API_KEY}
  temperature: 0.5
  max_turns: 50

channel:
  type: telegram
  token: ${TELEGRAM_BOT_TOKEN}
  allowed_users: [123456789]
  allowed_groups: []

channels:
  - type: telegram
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users: [123456789]
  - type: discord
    token: ${DISCORD_BOT_TOKEN}
    allowed_users: [916552354470461470]
    mention_required: true
    triggers: ["!ask"]

channels:
  - type: discord
    token: ${DISCORD_BOT_TOKEN}
    allowed_groups: [111222333]
    mention_required: true
    context_messages: 25        # On-demand context fetch (default: 25)
    channel_log:
      enabled: false            # Disabled by default; set true to enable
      retention_days: 30        # Days before old logs are archived (default: 30)

queue:
  mode: steer
  debounce_ms: 500

heartbeat:
  enabled: true
  interval_minutes: 30           # How often to check in
  active_hours: "09:00-17:00"    # Only run during these hours (optional)
  suppress_ok: true              # Don't send message if agent responds "HEARTBEAT_OK"
  delivery: channel              # Where to deliver: channel, agent, or both
  target_channel: telegram       # Which channel to deliver to
  target_id: 123456789           # Channel-agnostic user/chat ID (preferred over chat_id)

approval_gates:
  enabled: true
  timeout_seconds: 120            # Seconds to wait for user response
  default_action: deny            # Action on timeout: "deny" or "approve"
  tools:
    overwrite_file:
      require_approval: true
      show_args: true             # Show tool arguments in approval prompt
    delete_task:
      require_approval: true

# Conversation auto-reset after inactivity (default: 180 minutes, 0 to disable)
session_ttl_minutes: 180

lifecycle:
  notify_session_ttl: true  # Notify user when session expires

status_reminder:
  enabled: true              # Default: true
  threshold: 5               # Tool-calling turns before first reminder (1-50)
  max_reminders: 3           # Max reminders per agent run (0-20)
  cooldown_turns: 1          # Min turns between consecutive reminders (0-10)

status_updates:
  enabled: true              # Default: true
  agent_start: true          # Report when agent run begins
  tool_calls_detected: true  # Report when agent decides to use tools
  tool_start: false          # Report before each tool execution
  tool_complete: false       # Report after each tool execution
  subagent_spawned: true     # Report when sub-agent is dispatched
  min_interval_seconds: 3    # Minimum seconds between auto-updates
  edit_in_place: true        # Edit single message in place (default: true)
  typing_indicator: true      # Send typing indicator while agent is processing
  reactions: true            # Add emoji reactions to the user's original message
  use_emojis: true           # Prefix status messages with relevant emojis

**enabled** — Enable automatic status updates sent to the user during agent execution. Default: `true`.

**agent_start** — Send `"Starting work..."` on the first run of a user message, and `"Continuing work..."` on subsequent runs (e.g., follow-up or self-continuation). Default: `true`. System events (cron, heartbeat, sub-agent completions) skip the agent start status to avoid mid-task confusion.

**tool_calls_detected** — Send `"Using tools: X, Y..."` when the agent decides to call tools. Default: `true`.

**tool_start** — Send `"Running tool: X..."` before each tool execution. Default: `false` (can be noisy).

**tool_complete** — Send `"Completed: X"` after each tool execution. Default: `false` (can be noisy).

**subagent_spawned** — Send `"Dispatched sub-agent: label"` when `spawn_agent` is called. Default: `true`.

**min_interval_seconds** — Minimum seconds between auto-detected status updates. Prevents spam during rapid tool-call sequences. Default: `3`.

**edit_in_place** — When `true` (default), the first status update sends a new message, and subsequent updates edit the same message in place. This prevents chat clutter. The status message is deleted after the agent run completes. When `false`, each update sends a separate message.

**typing_indicator** — When `true` (default), the framework sends a typing indicator (e.g., "typing..." on Telegram or "Agent is typing..." on Discord) while the agent is actively processing. Cleared when the agent completes or sends a real message.

**reactions** — When `true` (default), the framework adds an emoji reaction to the user's original message to indicate the agent has seen it and is working. The reaction is removed when the agent finishes. Only supported on channels that support emoji reactions (Telegram, Discord).

**use_emojis** — When `true` (default), status messages are prefixed with relevant emoji for visual clarity (e.g., `⚙️` for tool calls, `🚀` for starting work, `🤖` for sub-agent dispatch). Set to `false` for plain text status messages.

Status updates are sent directly to the user channel and do not create extra checkpoint entries or consume additional API calls. Agent-driven `report_progress` tool calls bypass all throttling.

---

### Merging Behavior

Workspace configuration deep-merges over global configuration:

- **Missing fields** inherit from global config
- **Present fields** override global values
- **Nested objects** merge recursively

**Example:**

**Global config.yaml:**
```yaml
agent:
  model: anthropic:claude-sonnet-4-20250514
  temperature: 0.7
  max_turns: 50

model:
  temperature: 0.5  # Override only temperature

model:
  provider: anthropic                   # From global (parsed from model string)
  model: claude-sonnet-4-20250514       # From global
  temperature: 0.5                      # From workspace
  max_turns: 50                         # From global

channel:
  type: telegram
  token: ${TELEGRAM_BOT_TOKEN}

model:
  provider: anthropic
  api_key: ${ANTHROPIC_API_KEY}

export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
export ANTHROPIC_API_KEY="sk-ant-..."

agent_workspaces/my-agent/config/.env

model:
  provider: anthropic
  model: claude-sonnet-4-20250514
  api_key: ${ANTHROPIC_API_KEY}
  temperature: 0.7

model:
  provider: openai
  model: gpt-4o
  api_key: ${OPENAI_API_KEY}
  temperature: 0.7

model:
  provider: bedrock_converse
  model: moonshot.kimi-k2-thinking
  region: us-east-1  # Optional, defaults to AWS_REGION env var

# Environment variables
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_REGION="us-east-1"

# Or use AWS CLI profile
aws configure

model:
  provider: openai
  model: kimi-k2.5
  api_key: ${MOONSHOT_API_KEY}
  base_url: https://api.moonshot.ai/v1
  temperature: 1.0

ValidationError: field required (type=value_error.missing)

ValidationError: value is not a valid enumeration member (type=type_error.enum)

Error: Environment variable TELEGRAM_BOT_TOKEN not set

ValidationError: Invalid IANA timezone identifier: 'America/InvalidCity'

# Development
poetry run openpaw -c config.dev.yaml -w my-agent

# Production
poetry run openpaw -c config.prod.yaml -w my-agent

# Testing
poetry run openpaw -c config.test.yaml -w my-agent

model:
  provider: anthropic
  model: claude-sonnet-4-20250514
  timeout_seconds: 120  # Override default timeout

builtins:
  allow: []  # Empty = allow all
  deny:
    - elevenlabs
    - group:system

builtins:
  allow:
    - brave_search
    - whisper
  # Everything else is denied (not in allow list)

builtins:
  allow:
    - group:voice
  deny:
    - elevenlabs  # Deny takes precedence over allow

/path/to/project/config.yaml

agent_workspaces/<workspace-name>/config/agent.yaml

agent_workspaces/<workspace-name>/config/.env

agent_workspaces/<workspace-name>/config/crons/*.yaml

agent_workspaces/<workspace-name>/data/dynamic_crons.json

agent_workspaces/<workspace-name>/data/TASKS.yaml

agent_workspaces/<workspace-name>/data/
├── conversations.db      # AsyncSqliteSaver checkpoint database
├── sessions.json         # Session/conversation thread state
├── token_usage.jsonl     # Token usage metrics (append-only)
└── subagents.yaml        # Sub-agent requests and results

cp config.example.yaml config.yaml

# Good — only overrides temperature
model:
  temperature: 0.5

# Bad — duplicates global config unnecessarily
model:
  provider: anthropic
  model: claude-sonnet-4-20250514
  api_key: ${ANTHROPIC_API_KEY}
  temperature: 0.5  # This is the only thing that changed
  max_turns: 50

# .env.example
TELEGRAM_BOT_TOKEN=
DISCORD_BOT_TOKEN=
ANTHROPIC_API_KEY=
BRAVE_API_KEY=
OPENAI_API_KEY=
ELEVENLABS_API_KEY=

poetry run openpaw -c config.yaml -w my-agent -v

# config.dev.yaml
logging:
  level: DEBUG

# config.prod.yaml
logging:
  level: INFO

# Run with -c flag
poetry run openpaw -c config.dev.yaml -w my-agent

Error: Configuration file not found: config.yaml

yaml.scanner.ScannerError: while scanning a simple key

Warning: Token contains literal '${TELEGRAM_BOT_TOKEN}'

Error: Workspace 'my-agent' not found in agent_workspaces/

Error: Invalid model provider: 'invalid-provider'

ValidationError: Invalid IANA timezone identifier: 'America/InvalidCity'