This guide covers all configuration options for MicroClaw, from basic setup to advanced features.
The main configuration file microclaw.config.yaml is stored at:
~/.microclaw/microclaw.config.yaml--config flag or MICROCLAW_CONFIG environment variableInteractive setup (recommended):
microclaw setup
Manual creation:
mkdir -p ~/.microclaw
nano ~/.microclaw/microclaw.config.yaml
# LLM Configuration (Required)
llm_provider: "anthropic"
api_key: "sk-ant-..."
model: "claude-sonnet-4-20250514"
# At least one channel required
channels:
telegram:
default_account: "main"
accounts:
main:
bot_token: "123456:ABC-DEF1234..."
bot_username: "my_bot"
MicroClaw supports multiple LLM providers:
# Anthropic (Native API)
llm_provider: "anthropic"
api_key: "sk-ant-..."
model: "claude-sonnet-4-20250514"
# OpenAI
llm_provider: "openai"
api_key: "sk-..."
model: "gpt-4o"
# OpenRouter
llm_provider: "openrouter"
api_key: "sk-or-..."
model: "anthropic/claude-3.5-sonnet"
# Ollama (Local)
llm_provider: "ollama"
model: "llama3.1"
# No API key required for local Ollama
# Google
llm_provider: "google"
api_key: "..."
model: "gemini-1.5-pro"
# DeepSeek
llm_provider: "deepseek"
api_key: "..."
model: "deepseek-chat"
# Custom Provider
llm_provider: "custom"
api_key: "..."
model: "custom-model"
llm_base_url: "https://api.example.com/v1"
| Provider | Models |
|---|---|
| Anthropic | claude-sonnet-4-20250514, claude-3-opus, claude-3-sonnet, claude-3-haiku |
| OpenAI | gpt-4o, gpt-4-turbo, gpt-4, gpt-3.5-turbo |
| OpenRouter | Any model available via OpenRouter |
| Ollama | Any locally available model |
| gemini-1.5-pro, gemini-1.5-flash | |
| DeepSeek | deepseek-chat, deepseek-coder |
# Token Limits
max_tokens: 8192
# Rate Limiting
max_tool_iterations: 100
# Memory Budget
memory_token_budget: 1500
# Custom Base URL (for self-hosted or proxy)
llm_base_url: "https://api.example.com/v1"
# Request Timeout (seconds)
request_timeout: 60
# Retry Configuration
max_retries: 3
retry_delay: 1.0
channels:
telegram:
default_account: "main"
accounts:
main:
bot_token: "123456:ABC-DEF1234..."
bot_username: "my_bot"
secondary:
bot_token: "789012:GHI-JKL456..."
bot_username: "my_bot_2"
Telegram Options:
channels:
telegram:
default_account: "main"
accounts:
main:
bot_token: "..."
bot_username: "..."
# Only respond to mentions in groups
mention_only: true
# Allowed chat IDs (optional)
allowed_chats:
- "-1001234567890"
- "123456789"
channels:
discord:
default_account: "main"
accounts:
main:
bot_token: "DISCORD_BOT_TOKEN"
# Required intents
message_content_intent: true
member_intent: true
channels:
slack:
default_account: "main"
accounts:
main:
bot_token: "xoxb-..."
app_token: "xapp-..."
channels:
feishu:
default_account: "main"
accounts:
main:
app_id: "cli_xxx"
app_secret: "xxx"
domain: "feishu" # or "lark" for international
channels:
irc:
server: "irc.example.com"
port: "6667"
nick: "microclaw"
channels: "#general,#ops"
tls: true
sasl_password: "..." # Optional SASL authentication
channels:
matrix:
homeserver: "https://matrix.org"
user_id: "@microclaw:matrix.org"
access_token: "..."
device_name: "MicroClaw Bot"
channels:
whatsapp:
phone_number: "+1234567890"
api_key: "..."
channels:
telegram:
default_account: "main"
accounts:
main:
bot_token: "TELEGRAM_TOKEN"
bot_username: "telegram_bot"
discord:
default_account: "main"
accounts:
main:
bot_token: "DISCORD_TOKEN"
slack:
default_account: "main"
accounts:
main:
bot_token: "xoxb-..."
app_token: "xapp-..."
# Main data directory
data_dir: "~/.microclaw"
# Working directory for file operations
working_dir: "~/.microclaw/working_dir"
# Working directory isolation mode
# "chat" - Each chat has isolated working directory
# "shared" - All chats share the same working directory
working_dir_isolation: "chat"
# Timezone for scheduled tasks
timezone: "UTC" # or "America/New_York", "Europe/London", etc.
~/.microclaw/
├── microclaw.config.yaml # Configuration file
├── mcp.json # MCP configuration
├── mcp.d/ # Additional MCP configs
├── runtime/
│ ├── microclaw.db # SQLite database
│ ├── logs/ # Runtime logs
│ └── groups/ # Memory files
│ ├── AGENTS.md # Global memory
│ └── {chat_id}/ # Per-chat memory
│ └── AGENTS.md
├── skills/ # Custom skills
└── working_dir/ # Tool working directory
# Memory token budget for context injection
memory_token_budget: 1500
# Memory extraction settings
memory:
# Enable reflector for automatic memory extraction
reflector_enabled: true
# Minimum confidence for memory injection
min_confidence: 0.7
# Soft archive threshold (days)
archive_threshold_days: 30
Requires building with --features sqlite-vec:
# Embedding configuration for semantic memory
embedding_provider: "openai"
embedding_model: "text-embedding-3-small"
embedding_api_key: "sk-..."
# Or use Ollama for local embeddings
embedding_provider: "ollama"
embedding_model: "nomic-embed-text"
sandbox:
# Sandbox mode: off | all
mode: "all"
# Backend: auto | docker
backend: "auto"
# Security profile: hardened | standard | privileged
security_profile: "hardened"
# Container image
image: "ubuntu:25.10"
# Container name prefix
container_prefix: "microclaw-sandbox"
# Disable network access in sandbox
no_network: true
# Require runtime dependencies
require_runtime: false
| Profile | Capabilities | Use Case |
|---|---|---|
hardened |
--cap-drop ALL --security-opt no-new-privileges |
Production, untrusted code |
standard |
Docker default capabilities | General use |
privileged |
--privileged |
Debugging only |
tools:
bash:
# Default timeout in seconds
timeout: 300
# Enable/disable sandbox
sandbox: true
# Allowed commands (optional whitelist)
allowed_commands:
- ls
- cat
- grep
- find
tools:
file:
# Maximum file size in MB
max_file_size_mb: 100
# Allowed directories (optional)
allowed_paths:
- "~/.microclaw/working_dir"
tools:
web:
# Web search provider
search_provider: "duckduckgo"
# Fetch timeout in seconds
fetch_timeout: 30
# User agent for web requests
user_agent: "MicroClaw/1.0"
scheduler:
# Enable/disable scheduler
enabled: true
# Timezone for cron expressions
timezone: "UTC"
# Maximum concurrent scheduled tasks
max_concurrent: 5
# Task timeout in seconds
task_timeout: 600
web:
# Enable web UI
enabled: true
# Bind address
host: "127.0.0.1"
# Port
port: 10961
# Password (set via CLI: microclaw web password <value>)
# password: "..."
# Session timeout in minutes
session_timeout: 60
logging:
# Log level: error | warn | info | debug | trace
level: "info"
# Log format: json | compact | pretty
format: "compact"
# Log file location
file: "~/.microclaw/runtime/logs/microclaw.log"
# Max log file size in MB
max_file_size_mb: 100
# Number of rotated log files to keep
retention_count: 5
MCP configuration is stored in a separate file mcp.json:
{
"defaultProtocolVersion": "2025-11-05",
"mcpServers": {
"filesystem": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
},
"playwright": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@playwright/mcp@latest", "--extension"],
"env": {
"PLAYWRIGHT_MCP_EXTENSION_TOKEN": "<token>"
}
},
"remote": {
"transport": "streamable_http",
"endpoint": "http://127.0.0.1:8080/mcp"
}
}
}
| Option | Description |
|---|---|
defaultProtocolVersion |
MCP protocol version (default: 2025-11-05) |
mcpServers |
Map of MCP server configurations |
transport |
Transport type: stdio or streamable_http |
command |
Command to run (for stdio transport) |
args |
Command arguments (for stdio transport) |
env |
Environment variables (for stdio transport) |
endpoint |
HTTP endpoint (for streamable_http transport) |
Skills are auto-discovered from <data_dir>/skills/. Built-in skills include:
pdf - PDF document processingdocx - Word document processingxlsx - Excel spreadsheet processingpptx - PowerPoint presentation processingskill-creator - Create new skillsapple-notes - Apple Notes integration (macOS)apple-reminders - Apple Reminders integration (macOS)apple-calendar - Apple Calendar integration (macOS)weather - Weather informationfind-skills - List available skillsCreate custom skills in ~/.microclaw/skills/:
# ~/.microclaw/skills/my-skill.yaml
name: my-skill
description: My custom skill
version: 1.0.0
tools:
- name: my-tool
description: My custom tool
input_schema:
type: object
properties:
param1:
type: string
handler:
type: bash
command: echo "Hello from my tool"
Control chats have elevated permissions for cross-chat operations:
# List of chat IDs with control permissions
control_chat_ids:
- "telegram:123456789"
- "discord:987654321"
Control chats can:
# MicroClaw Configuration
# ========================
# LLM Configuration
llm_provider: "anthropic"
api_key: "sk-ant-..."
model: "claude-sonnet-4-20250514"
max_tokens: 8192
max_tool_iterations: 100
# Channel Configuration
channels:
telegram:
default_account: "main"
accounts:
main:
bot_token: "123456:ABC-DEF1234..."
bot_username: "my_microclaw_bot"
mention_only: false
discord:
default_account: "main"
accounts:
main:
bot_token: "DISCORD_TOKEN"
# Data Directories
data_dir: "~/.microclaw"
working_dir: "~/.microclaw/working_dir"
working_dir_isolation: "chat"
timezone: "America/New_York"
# Memory Configuration
memory_token_budget: 1500
# Sandbox Configuration
sandbox:
mode: "all"
security_profile: "hardened"
image: "ubuntu:25.10"
no_network: true
# Web UI Configuration
web:
enabled: true
host: "127.0.0.1"
port: 10961
# Logging Configuration
logging:
level: "info"
format: "compact"
max_file_size_mb: 100
retention_count: 5
# Control Chats
control_chat_ids:
- "telegram:123456789"
# Run diagnostics
microclaw doctor
# JSON output
microclaw doctor --json
# Check specific components
microclaw doctor sandbox
# Start with verbose logging
RUST_LOG=debug microclaw start
# Check service status
microclaw gateway status
Configuration can also be set via environment variables:
| Variable | Description |
|---|---|
MICROCLAW_CONFIG |
Path to configuration file |
MICROCLAW_LLM_PROVIDER |
LLM provider |
MICROCLAW_API_KEY |
LLM API key |
MICROCLAW_MODEL |
Model name |
MICROCLAW_DATA_DIR |
Data directory |
TELEGRAM_BOT_TOKEN |
Telegram bot token |
DISCORD_BOT_TOKEN |
Discord bot token |
SLACK_BOT_TOKEN |
Slack bot token |
Any questions?
Feel free to contact us. Find all contact information on our contact page.