Configuration

OpenCrabs uses two config files stored at ~/.opencrabs/:

Workspace Layout

~/.opencrabs/
├── config.toml          # Main configuration
├── keys.toml            # API keys (gitignored)
├── commands.toml        # Custom slash commands
├── opencrabs.db         # SQLite database
├── SOUL.md              # Agent personality
├── USER.md              # Your profile
├── MEMORY.md            # Long-term memory
├── AGENTS.md            # Agent behavior docs
├── TOOLS.md             # Tool reference
├── SECURITY.md          # Security policies
├── HEARTBEAT.md         # Periodic check tasks
├── memory/              # Daily memory notes
│   └── YYYY-MM-DD.md
├── images/              # Generated images
├── logs/                # Application logs
└── skills/              # Custom skills/plugins

Provider Configuration

See Provider Setup for detailed provider configuration.

Quick example — add Anthropic:

# config.toml
[providers.anthropic]
enabled = true
default_model = "claude-sonnet-4-20250514"

# keys.toml
[providers.anthropic]
api_key = "sk-ant-..."

Provider Priority

When multiple providers are enabled, the first one found in this order is used for new sessions:

MiniMax > OpenRouter > Anthropic > OpenAI > Gemini > Custom

Each session remembers which provider and model it was using. Switch providers per-session via /models.

Agent Behavior

[agent]
working_directory = "/path/to/default/dir"
thinking = "on"                     # "on", "off", or "budget_XXk"
approval_policy = "auto-always"     # "ask", "auto-session", "auto-always"
max_concurrent = 4                  # max parallel tool calls
context_limit = 200000              # context window cap (tokens)
max_tokens = 65536                  # max output tokens per API call
auto_update = true                  # auto-install releases on startup
silent_compaction = false           # suppress post-compaction personality narration
lazy_tools = true                   # JIT tool-schema loading (ships core + tool_search only)
redact_sensitive_data = true        # redact API keys, tokens, passwords, IPs from output
default_provider = "minimax"        # fallback provider when no provider is active (v0.3.62)
default_model = "MiniMax-M2.7"      # fallback model when no model is active (v0.3.62)

Sub-agent and RSI Overrides

Route spawned sub-agents and RSI (self-improvement) cycles to separate providers so they never compete with your main chat for quota:

[agent]
subagent_provider = "minimax"           # provider for spawned sub-agents
subagent_model = "MiniMax-M2.7"         # model for spawned sub-agents
self_improvement_provider = "minimax"   # provider for RSI self-improvement cycles
self_improvement_model = "MiniMax-M2.7" # model for RSI cycles

Channel Configuration

Telegram

[channels.telegram]
enabled = true
token = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
allowed_users = ["123456789"]       # numeric Telegram user IDs
allowed_channels = ["-100123456"]   # restrict to specific group/channel IDs (empty = all)
respond_to = "mention"              # "all", "dm_only", "mention" (default)
session_idle_hours = 24.0           # idle timeout for non-owner sessions
rich_messages = true                # native Telegram rich messages (Bot API 10.1, default since v0.3.64)
silence_group_start = true          # silently ignore /start from non-allowed users in groups
bot_owner = ["123456789"]           # owner IDs (gated commands, /cd hidden dirs, /profiles)

Discord

[channels.discord]
enabled = true
token = "your-discord-bot-token"
allowed_users = ["123456789012345678"]
allowed_channels = ["123456789012345678"]
respond_to = "mention"
session_idle_hours = 24.0

Slack

[channels.slack]
enabled = true
token = "xoxb-your-bot-token"
app_token = "xapp-your-app-token"      # Socket Mode token
allowed_users = ["U12345678"]
allowed_channels = ["C12345678"]
respond_to = "mention"
session_idle_hours = 24.0

WhatsApp

[channels.whatsapp]
enabled = true
allowed_phones = ["+15551234567"]      # E.164 format
session_idle_hours = 24.0

Trello

[channels.trello]
enabled = true
token = "your-trello-api-token"
app_token = "your-trello-api-key"
allowed_users = ["memberId1"]
board_ids = ["boardId1", "boardId2"]
poll_interval_secs = 60
session_idle_hours = 24.0

Other Channels (Preview)

Signal, Google Chat, and iMessage are available as preview placeholders:

[channels.signal]
enabled = true
allowed_phones = ["+15551234567"]

[channels.google_chat]
enabled = true
token = "your-google-chat-token"
allowed_users = ["user@example.com"]

[channels.imessage]
enabled = true
allowed_phones = ["+15551234567"]

Cron Defaults

Route cron jobs to cheaper providers so they never compete with your interactive session:

[cron]
default_provider = "minimax"
default_model = "MiniMax-M2.7"

Memory and Embeddings

[memory]
vector_enabled = true

[memory.embedding]
url = "https://api.openai.com/v1"
model = "text-embedding-3-small"
# api_key loaded from keys.toml: [providers.memory_embedding] api_key = "sk-..."
# dimensions = 1536  # auto-detected from first API response if unset

When [memory.embedding] is not set, embeddings are generated locally via the embeddinggemma-300M GGUF model (~300MB download, ~2.9GB RAM). Setting [memory.embedding] with an API endpoint eliminates the local model overhead.

Brain Files

[brain]
strip_empty_sections = true
default_cap = 500

[brain.caps]
SOUL.md = 300
AGENTS.md = 800

Browser

[browser]
cdp_endpoint = "http://localhost:9222"

To start a standalone Chromium with CDP enabled:

chromium --remote-debugging-port=9222 --headless --no-sandbox

A2A (Agent-to-Agent) Gateway

[a2a]
enabled = false
bind = "127.0.0.1"
port = 18790
allowed_origins = ["https://your-app.com"]
# api_key = "your-secret-key"  # Bearer token for incoming requests

Daemon Mode

[daemon]
health_port = 8080

OpenCrabs runs in two modes: TUI (interactive terminal UI with chat) and Daemon (headless background service for channels + cron). For any one profile, run only one at a time. The TUI always wins: opening it while a daemon runs shuts the daemon down and takes over the channels.

For full service lifecycle management (TUI vs Daemon comparison, opencrabs service install/start/stop, profile-aware services, OPENCRABS_PROFILE env var, troubleshooting), see the CLI Commands reference.

Image Generation and Vision

[image.generation]
enabled = true
model = "gemini-3.1-flash-image-preview"

[image.vision]
enabled = true
model = "gemini-3.1-flash-image-preview"
provider = "openrouter"           # bypasses enabled gate for vision-only providers (v0.3.63)

Vision analysis automatically scans all enabled providers (Google, OpenRouter, OpenAI-compatible, Anthropic) before returning an error. No configuration needed.

Voice Provider Fallback

STT and TTS providers support automatic failover via fallback_chain. When the primary returns a 5xx, fails a liveness probe (Voicebox), or is otherwise unreachable, the dispatcher walks the chain in order and tries each entry that has the credentials/config it needs.

[providers.stt]
fallback_chain = ["groq", "openai_compatible", "local"]

[providers.tts]
fallback_chain = ["openai_compatible", "openai", "local"]

Empty or omitted chain means “use the default priority order with the primary removed.”