English | 中文

Note: This project is under active development. Features may change, and contributions are welcome!

An agentic AI assistant for chat surfaces, inspired by nanoclaw and incorporating some of its design ideas. MicroClaw uses a channel-agnostic core with platform adapters: it currently supports Telegram, Discord, Slack, Feishu/Lark, Matrix, WhatsApp, iMessage, Email, Nostr, Signal, DingTalk, QQ, IRC, and Web, and is designed to add more platforms over time. It works with multiple LLM providers (Anthropic + OpenAI-compatible APIs) and supports full tool execution: run shell commands, read/write/edit files, search codebases, browse the web, schedule tasks, and maintain persistent memory across conversations.

• How it works
• Install
• Features
• Tools
• Memory
• Skills
• Plugins
• MCP
• Plan & Execute
• Scheduling
• Local Web UI (cross-channel history)
• Release
• Setup
• Configuration
• Docker Sandbox
• Platform behavior
• Multi-chat permission model
• Usage examples
• Architecture
• Adding a New Platform Adapter
• Documentation

curl -fsSL https://microclaw.ai/install.sh | bash

iwr https://microclaw.ai/install.ps1 -UseBasicParsing | iex

This installer only does one thing:

• Download and install the matching prebuilt binary from the latest GitHub release
• It does not fallback to Homebrew/Cargo inside install.sh (use separate methods below)

Upgrade in place later:

microclaw upgrade

Run cross-platform diagnostics before first start (or when troubleshooting):

microclaw doctor

Machine-readable output for support tickets:

microclaw doctor --json

Checks include PATH, shell runtime, agent-browser, PowerShell policy (Windows), and MCP command dependencies from <data_dir>/mcp.json plus <data_dir>/mcp.d/*.json.

Sandbox-only diagnostics:

microclaw doctor sandbox

macOS/Linux:

curl -fsSL https://microclaw.ai/uninstall.sh | bash

Windows PowerShell:

iwr https://microclaw.ai/uninstall.ps1 -UseBasicParsing | iex

brew tap microclaw/tap
brew install microclaw

git clone https://github.com/microclaw/microclaw.git
cd microclaw
cargo build --release
cp target/release/microclaw /usr/local/bin/

Optional semantic-memory build (sqlite-vec disabled by default):

cargo build --release --features sqlite-vec

First-time sqlite-vec quickstart (3 commands):

cargo run --features sqlite-vec -- setup
cargo run --features sqlite-vec -- start
sqlite3 <data_dir>/runtime/microclaw.db "SELECT id, chat_id, chat_channel, external_chat_id, category, embedding_model FROM memories ORDER BY id DESC LIMIT 20;"

In setup, set:

• embedding_provider = openai or ollama
• provider credentials/base URL/model as needed

Every message triggers an agentic loop: the model can call tools, inspect the results, call more tools, and reason through multi-step tasks before responding. Up to 100 iterations per request by default.

For a deeper dive into the architecture and design decisions, read: Building MicroClaw: An Agentic AI Assistant in Rust That Lives in Your Chats

• Agentic tool use -- bash commands, file read/write/edit, glob search, regex grep, persistent memory
• Session resume -- full conversation state (including tool interactions) persisted between messages; the agent keeps tool-call state across invocations
• Context compaction -- when sessions grow too large, older messages are automatically summarized to stay within context limits
• Sub-agent -- delegate self-contained sub-tasks to a parallel agent with restricted tools
• Agent skills -- extensible skill system (Anthropic Skills compatible); skills are auto-discovered from <data_dir>/skills/ and activated on demand
• Plan & execute -- todo list tools for breaking down complex tasks, tracking progress step by step
• Platform-extensible architecture -- shared agent loop + tool system + storage, with platform adapters for channel-specific ingress/egress
• Web search -- search the web via DuckDuckGo and fetch/parse web pages
• Scheduled tasks -- cron-based recurring tasks and one-time scheduled tasks, managed through natural language
• Mid-conversation messaging -- the agent can send intermediate messages before its final response
• Mention catch-up (Telegram groups) -- when mentioned in a Telegram group, the bot reads all messages since its last reply (not just the last N)
• Continuous typing indicator -- typing indicator stays active for the full duration of processing
• Persistent memory -- AGENTS.md files at global, bot/account, and per-chat scopes, loaded into every request
• Message splitting -- long responses are automatically split at newline boundaries to fit channel limits (Telegram 4096 / Discord 2000 / Slack 4000 / Feishu 4000 / IRC ~380)

Generated reference (source-of-truth, anti-drift):

• docs/generated/tools.md
• docs/generated/config-defaults.md
• docs/generated/provider-matrix.md

Regenerate with:

node scripts/generate_docs_artifacts.mjs

MicroClaw maintains persistent memory via AGENTS.md files:

<data_dir>/runtime/groups/
    AGENTS.md                 # Global memory (shared across all chats)
    {channel}/
        AGENTS.md             # Bot/account memory for this channel
        {chat_id}/
            AGENTS.md         # Per-chat memory (namespaced by channel)

Memory is loaded into the system prompt on every request. The model can read and update memory through tools -- tell it to "remember that I prefer Python" and it will persist across sessions.

MicroClaw also keeps structured memory rows in SQLite (memories table):

• write_memory persists to file memory and structured memory
• Background reflector extracts durable facts incrementally and deduplicates
• Explicit "remember ..." commands use a deterministic fast path (direct structured-memory upsert)
• Low-quality/noisy memories are filtered by quality gates before insertion
• Memory lifecycle is managed with confidence + soft-archive fields (instead of hard delete)

Optional memory MCP backend:

• If MCP config includes a server exposing both memory_query and memory_upsert, structured-memory operations prefer that MCP server.
• If MCP is not configured, unavailable, or returns invalid payloads, MicroClaw automatically falls back to built-in SQLite memory behavior.

When built with --features sqlite-vec and embedding config is set, structured-memory retrieval and dedup use semantic KNN. Otherwise, it falls back to keyword relevance + Jaccard dedup.

/usage now includes a Memory Observability section (and Web UI panel) showing:

• memory pool health (active/archived/low-confidence)
• reflector throughput (insert/update/skip in 24h)
• injection coverage (selected vs candidate memories in 24h)

MicroClaw now stores a channel-scoped identity for chats:

• internal chat_id: SQLite primary key used by sessions/messages/tasks
• channel + external_chat_id: source chat identity from Telegram/Discord/Slack/Feishu/IRC/Web

This avoids collisions when different channels can have the same numeric id. Legacy rows are migrated automatically on startup.

Useful SQL for debugging:

SELECT chat_id, channel, external_chat_id, chat_type, chat_title
FROM chats
ORDER BY last_message_time DESC
LIMIT 50;

SELECT id, chat_id, chat_channel, external_chat_id, category, content, embedding_model
FROM memories
ORDER BY id DESC
LIMIT 50;

MicroClaw supports the Anthropic Agent Skills standard. Skills are modular packages that give the bot specialized capabilities for specific tasks.

<data_dir>/skills/
    pdf/
        SKILL.md              # Required: name, description + instructions
    docx/
        SKILL.md

How it works:

1. Skill metadata (name + description) is always included in the system prompt (~100 tokens per skill)
2. When the model determines a skill is relevant, it calls activate_skill to load the full instructions
3. The model follows the skill instructions to complete the task

Built-in skills: pdf, docx, xlsx, pptx, skill-creator, apple-notes, apple-reminders, apple-calendar, weather, find-skills

New macOS skills (examples):

• apple-notes -- manage Apple Notes via memo
• apple-reminders -- manage Apple Reminders via remindctl
• apple-calendar -- query/create Calendar events via icalBuddy + osascript
• weather -- quick weather lookup via wttr.in

Adding a skill: Create a subdirectory under <data_dir>/skills/ with a SKILL.md file containing YAML frontmatter and markdown instructions.

Supported frontmatter fields:

• name, description
• platforms (optional): e.g. [darwin, linux, windows]
• deps (optional): required commands in PATH
• compatibility.os / compatibility.deps (also supported)

Unavailable skills are filtered automatically by platform/dependencies, so unsupported skills do not appear in /skills.

MicroClaw supports manifest-based plugins for:

• Slash commands (for example /uptime, /announce hello)
• Dynamic tools exposed to the agent loop
• Per-turn context providers (prompt/document injections)

Default plugins directory:

• <data_dir>/plugins

Optional override:

plugins:
  enabled: true
  dir: "./microclaw.data/plugins"

Plugin admin commands (control chats):

• /plugins list
• /plugins validate
• /plugins reload

See full manifest schema and examples: docs/plugins/overview.md.

Commands:

• /stop -- abort the current active run in this chat (keeps history/session data)
• /clear -- clear current chat context (session + chat history), keep scheduled tasks
• /reset -- clear current chat context (session + chat history) and scheduled task state
• /skills -- list all available skills
• /reload-skills -- reload skills from disk
• /archive -- archive current in-memory session as markdown
• /usage -- show token usage summary (current chat + global totals)
• /status -- show provider/model plus current chat session/task status
• /model -- show current provider/model (/model <name> currently reports switch is not supported yet)

Command handling rules:

• Any input starting with / is treated as a command.
• Inputs with leading mentions before slash are also treated as commands (for example @bot /status, <@U123> /status).
• Slash commands do not enter agent conversation history/session context.
• Unknown slash commands return Unknown command..
• Use /stop to interrupt an in-flight run, /clear to wipe chat context only, and /reset to wipe chat context plus scheduled task state.

MicroClaw supports MCP servers configured in <data_dir>/mcp.json and optional fragments in <data_dir>/mcp.d/*.json with protocol negotiation and configurable transport.

• Default protocol version: 2025-11-05 (overridable globally or per server)
• Supported transports: stdio, streamable_http

Recommended production start (minimal local MCP only):

cp mcp.minimal.example.json <data_dir>/mcp.json

Full example (includes optional remote streamable HTTP server):

cp mcp.example.json <data_dir>/mcp.json

For sidecar-style integrations (for example a separate HAPI bridge process), prefer a dedicated fragment:

mkdir -p <data_dir>/mcp.d
cp mcp.hapi-bridge.example.json <data_dir>/mcp.d/hapi-bridge.json

Detailed ops guide: docs/operations/hapi-bridge.md.

Example:

{
  "defaultProtocolVersion": "2025-11-05",
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "remote": {
      "transport": "streamable_http",
      "endpoint": "http://127.0.0.1:8080/mcp"
    }
  }
}

To give your agent access to a real browser with your existing logins (cookies, sessions), use the Playwright MCP server in extension mode:

1. Install the Playwright MCP Bridge extension from the Chrome Web Store
2. Click the extension icon and copy the PLAYWRIGHT_MCP_EXTENSION_TOKEN
3. Add to your mcp.json (or <data_dir>/mcp.d/playwright.json):

{
  "mcpServers": {
    "playwright": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--extension"],
      "env": {
        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "<your-token-here>"
      }
    }
  }
}

This connects directly to your running Chrome via the extension's chrome.debugger API — no --remote-debugging-port flag needed. Your agent gets full access to your logged-in sessions (X, Google, GitHub, etc.) without any CDP setup.

Note: Chrome 136+ blocks --remote-debugging-port on the default user data directory and DPAPI cookie encryption is path-bound on Windows, so CDP-based approaches (--cdp-endpoint) will not preserve logins. Extension mode is the recommended solution.

Migration evaluation to official Rust SDK is tracked in docs/mcp-sdk-evaluation.md.

Validation:

RUST_LOG=info cargo run -- start

Look for log lines like MCP server '...' connected (...).

Peekaboo is a macOS desktop automation MCP server. MicroClaw can use it directly via stdio transport (no runtime code changes needed).

mkdir -p <data_dir>/mcp.d
cp mcp.peekaboo.example.json <data_dir>/mcp.d/peekaboo.json

mcp.peekaboo.example.json:

{
  "mcpServers": {
    "peekaboo": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "peekaboo-mcp@latest"]
    }
  }
}

MicroClaw can also consume Windows desktop automation MCP servers via stdio.

mkdir -p <data_dir>/mcp.d
cp mcp.windows.desktop.example.json <data_dir>/mcp.d/windows-desktop.json

mcp.windows.desktop.example.json includes:

• pywinauto (native Windows desktop UI automation, stdio MCP)
• optional playwright MCP for browser automation on Windows

Note: some Windows MCP projects expose only sse transport. MicroClaw runtime currently supports stdio and streamable_http transports only, so SSE-only servers need a protocol bridge before use.

For complex, multi-step tasks, the bot can create a plan and track progress:

You: Set up a new Rust project with CI, tests, and documentation
Bot: [creates a todo plan, then executes each step, updating progress]

1. [x] Create project structure
2. [x] Add CI configuration
3. [~] Write unit tests
4. [ ] Add documentation

Todo lists are stored at <data_dir>/runtime/groups/{chat_id}/TODO.json and persist across sessions.

The bot supports scheduled tasks via natural language:

• Recurring: "Remind me to check the logs every 30 minutes" -- creates a cron task
• One-time: "Remind me at 5pm to call Alice" -- creates a one-shot task

Under the hood, recurring tasks use 6-field cron expressions (sec min hour dom month dow). The scheduler polls every 60 seconds for due tasks, runs the agent loop with the task prompt, and sends results to the originating chat.

Manage tasks with natural language:

"List my scheduled tasks"
"Pause task #3"
"Resume task #3"
"Cancel task #3"

When web_enabled: true, MicroClaw serves a local Web UI (default http://127.0.0.1:10961).

• Session list includes chats from all channels stored in SQLite (telegram, discord, slack, feishu, irc, web)
• You can review and manage history (refresh / clear context / delete)
• Non-web channels are read-only in Web UI by default (send from source channel)
• If there are no sessions yet, Web UI auto-generates a new key like session-YYYYMMDDHHmmss
• The first message in that session automatically persists it in SQLite
• If no Web operator password exists, MicroClaw initializes a temporary default password helloworld and prompts you to change it after sign-in (you can skip temporarily)
• Password reset helpers:
  • microclaw web (show usage)
  • microclaw web password <value>
  • microclaw web password-generate
  • microclaw web password-clear

For external automation (webhooks, CI, scripts), use the Web API with an API key that has operator.write scope.

Detailed guide: docs/operations/http-hook-trigger.md

Endpoints:

• POST /api/send (canonical)
• POST /api/chat (alias for chatbot-style clients)
• POST /api/send_stream (async run + SSE replay)
• POST /api/chat_stream (alias for chatbot-style clients)
• POST /hooks/agent and POST /api/hooks/agent (OpenClaw-style webhook payload compatibility)
• POST /hooks/wake and POST /api/hooks/wake (system-event wake trigger: now or next-heartbeat)

Hook auth + policy (channels.web):

channels:
  web:
    hooks_token: "replace-with-secret"
    hooks_default_session_key: "hook:ingress"
    hooks_allow_request_session_key: false
    hooks_allowed_session_key_prefixes: ["hook:"]

Notes:

• /hooks/* requires hook token (Authorization: Bearer <token> or x-openclaw-token).
• sessionKey in request body is rejected by default unless hooks_allow_request_session_key: true.
• If you enable request sessionKey, use prefix allowlist to avoid arbitrary session routing.

Request body:

{
  "session_key": "ops-bot",
  "sender_name": "automation",
  "message": "Check error budget and summarize incidents in the last hour."
}

Synchronous response (/api/send or /api/chat):

{
  "ok": true,
  "session_key": "ops-bot",
  "chat_id": 123,
  "response": "..."
}

Example:

curl -sS http://127.0.0.1:10961/api/chat \
  -H "Authorization: Bearer $MICROCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_key":"ops-bot","sender_name":"automation","message":"status summary"}'

OpenClaw-compatible webhook shape:

curl -sS http://127.0.0.1:10961/hooks/agent \
  -H "Authorization: Bearer $MICROCLAW_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Summarize inbox","name":"Email","sessionKey":"hook:email:msg-123"}'

Wake example:

curl -sS http://127.0.0.1:10961/hooks/wake \
  -H "Authorization: Bearer $MICROCLAW_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"New email received","mode":"now"}'

Publish both installer mode (GitHub Release asset used by install.sh) and Homebrew mode with one command:

./deploy.sh

Nixpkgs upstream/update playbook:

• docs/releases/nixpkgs-upstream-guide.md

New: MicroClaw now includes an interactive setup wizard (microclaw setup) and will auto-launch it on first start when required config is missing.

Enable at least one channel, or use Web UI (enabled by default).

Telegram (optional):

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Enter a display name for your bot (e.g. My MicroClaw)
4. Enter a username (must end in bot, e.g. my_microclaw_bot)
5. BotFather will reply with a token like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz -- save this as telegram_bot_token (legacy single-account) or channels.telegram.accounts.<id>.bot_token (recommended multi-account)

Recommended BotFather settings (optional but useful):

• /setdescription -- set a short description shown in the bot's profile
• /setcommands -- register commands so users see them in the menu:

  reset - Clear current session
  status - Show runtime/session status
  model - Show current provider/model
  skills - List available agent skills
  usage - Show usage summary
  

• /setprivacy -- set to Disable if you want the bot to see all group messages (not just @mentions)

Discord (optional):

1. Open the Discord Developer Portal
2. Create an application and add a bot
3. Copy the bot token and save it as discord_bot_token
4. Invite the bot to your server with Send Messages, Read Message History, and mention permissions
5. Optional: set discord_allowed_channels to restrict where the bot can reply

Slack (optional, Socket Mode):

1. Create an app at api.slack.com/apps
2. Enable Socket Mode and get an app_token (starts with xapp-)
3. Add bot_token scope and install to workspace to get bot_token (starts with xoxb-)
4. Subscribe to message and app_mention events
5. Configure under channels.slack in config

Feishu/Lark (optional):

1. Create an app at the Feishu Open Platform (or Lark Developer for international)
2. Get app_id and app_secret from app credentials
3. Enable im:message and im:message.receive_v1 event subscription
4. Choose connection mode: WebSocket (default, no public URL needed) or Webhook
5. Configure under channels.feishu in config; set domain: "lark" for international

IRC (optional):

1. Prepare an IRC server endpoint, port, and bot nick
2. Configure under channels.irc in config (server, nick, channels are required)
3. Optional: enable TLS with tls: "true" and set tls_server_name if needed
4. Optional: set mention_required: "false" if you want replies in channels without mention

Choose a provider and create an API key:

• Anthropic: console.anthropic.com
• OpenAI: platform.openai.com
• Or any OpenAI-compatible provider (OpenRouter, DeepSeek, etc.)
• For openai-codex, you can use OAuth (codex login) or an API key (for OpenAI-compatible proxy endpoints).

microclaw setup

The config flow provides:

• Question-by-question prompts with defaults (Enter to confirm quickly)
• Provider selection + model selection (numbered choices with custom override)
• Better Ollama UX: local model auto-detection + sensible local defaults
• Channel credentials are written in multi-account form by default (channels.<channel>.default_account + channels.<channel>.accounts.main)
• Per-bot soul_path picker for Telegram/dynamic channels (auto-discovers souls/*.md, also supports manual filename/path input)
• Safe microclaw.config.yaml save with automatic backup in microclaw.config.backups/ (keeps latest 50)
• Auto-created directories for data_dir and working_dir

If you prefer the full-screen TUI, you can still run:

microclaw setup

Provider presets available in the wizard:

• openai
• openai-codex (ChatGPT/Codex subscription OAuth; run codex login)
• openrouter
• anthropic
• ollama
• google
• alibaba
• deepseek
• moonshot
• mistral
• azure
• bedrock
• zhipu
• minimax
• cohere
• tencent
• xai
• huggingface
• together
• custom (manual provider/model/base URL)

For Ollama, llm_base_url defaults to http://127.0.0.1:11434/v1, api_key is optional, and the interactive setup wizard can auto-detect locally installed models.

For openai-codex, you can run codex login first and MicroClaw will read OAuth from ~/.codex/auth.json (or $CODEX_HOME/auth.json). You can also provide api_key when using an OpenAI-compatible proxy endpoint. The default base URL is https://chatgpt.com/backend-api.

You can still configure manually with microclaw.config.yaml:

telegram_bot_token: "123456:ABC-DEF1234..."
bot_username: "my_bot"
# recommended Telegram multi-account mode (multi-token, multi-bot):
# channels:
#   telegram:
#     default_account: "main"
#     # optional: route group topics as separate chats via "<chat_id>:<thread_id>"
#     # topic_routing:
#     #   enabled: true
#     # optional: only allow these Telegram user IDs in private chats (DM)
#     # allowed_user_ids: [123456789]
#     accounts:
#       main:
#         bot_token: "123456:ABC-DEF1234..."
#         bot_username: "my_bot"
#         # optional per-account topic routing override (fallback to channel-level)
#         # topic_routing:
#         #   enabled: false
#         # optional per-account DM allowlist (overrides channel-level list)
#         # allowed_user_ids: [123456789]
#       support:
#         bot_token: "987654:XYZ-DEF9999..."
#         bot_username: "support_bot"
# recommended Discord multi-account mode:
# channels:
#   discord:
#     default_account: "main"
#     accounts:
#       main:
#         bot_token: "DISCORD_TOKEN_MAIN"
#       ops:
#         bot_token: "DISCORD_TOKEN_OPS"
#         no_mention: true
#         allowed_channels: [123456789012345678]
# recommended Slack multi-account mode:
# channels:
#   slack:
#     default_account: "main"
#     accounts:
#       main:
#         bot_token: "xoxb-main..."
#         app_token: "xapp-main..."
#       support:
#         bot_token: "xoxb-support..."
#         app_token: "xapp-support..."
#         allowed_channels: ["C123ABC456"]
# recommended Feishu multi-account mode:
# channels:
#   feishu:
#     default_account: "main"
#     accounts:
#       main:
#         app_id: "cli_xxx"
#         app_secret: "xxx"
#         topic_mode: true    # optional; only supported for domain feishu/lark
#       intl:
#         app_id: "cli_yyy"
#         app_secret: "yyy"
#         domain: "lark"
#         topic_mode: true    # optional; only supported for domain feishu/lark
# recommended IRC mode:
# channels:
#   irc:
#     server: "irc.example.com"
#     port: "6697"
#     nick: "microclaw"
#     channels: "#general,#ops"
#     tls: "true"
#     mention_required: "true"
llm_provider: "anthropic"
api_key: "sk-ant-..."
model: "claude-sonnet-4-20250514"
# optional
# llm_base_url: "https://..."
data_dir: "~/.microclaw"
working_dir: "~/.microclaw/working_dir"
working_dir_isolation: "chat" # optional; defaults to "chat" if omitted
sandbox:
  mode: "off" # optional; default off. set "all" to run bash in docker sandbox
max_document_size_mb: 100
memory_token_budget: 1500
timezone: "UTC"
# optional semantic memory runtime config (requires --features sqlite-vec build)
# embedding_provider: "openai"   # openai | ollama
# embedding_api_key: "sk-..."
# embedding_base_url: "https://api.openai.com/v1"
# embedding_model: "text-embedding-3-small"
# embedding_dim: 1536

microclaw start

microclaw gateway install
microclaw gateway status
microclaw gateway status --json

Manage service lifecycle:

microclaw gateway install --force
microclaw gateway start
microclaw gateway stop
microclaw gateway restart
microclaw gateway logs 200
microclaw gateway uninstall

Notes:

• macOS uses launchd user agents.
• Linux uses systemd --user.
• Runtime logs are written to <data_dir>/runtime/logs/.
• Gateway service stdout/stderr files are microclaw-gateway.log and microclaw-gateway.error.log.
• Logs older than 30 days are deleted automatically.

All configuration is via microclaw.config.yaml:

Path compatibility policy:

• If data_dir / skills_dir / working_dir are already configured, MicroClaw keeps using those configured paths.
• If these fields are not configured, defaults are data_dir=~/.microclaw, skills_dir=<data_dir>/skills, working_dir=~/.microclaw/working_dir.

* At least one channel configuration must be enabled; web_enabled is on by default.

These fields let you pass custom JSON parameters to OpenAI-compatible /chat/completions or /responses requests without adding provider-specific code.

Merge order (later wins):

1. openai_compat_body_overrides (global)
2. openai_compat_body_overrides_by_provider[llm_provider]
3. openai_compat_body_overrides_by_model[model]

null unsets a key:

llm_provider: "deepseek"
model: "deepseek-chat"

openai_compat_body_overrides:
  temperature: 0.2

openai_compat_body_overrides_by_provider:
  deepseek:
    top_p: null
    reasoning_effort: "high"

openai_compat_body_overrides_by_model:
  deepseek-chat:
    temperature: 0.0

Notes:

• provider keys are normalized to lowercase (OPENAI and openai are equivalent).
• model keys are exact-match after trimming.
• Runtime-controlled fields like stream mode and tool payload may still be set by MicroClaw for the active request path.

Use this when you want bash tool calls to run in Docker containers instead of the host.

Quick config:

microclaw setup --enable-sandbox
microclaw doctor sandbox

Or configure manually:

sandbox:
  mode: "all"
  backend: "auto"
  security_profile: "hardened" # optional; hardened|standard|privileged, default hardened
  # optional capability overrides (applies to hardened/standard)
  # cap_add: ["SETUID", "SETGID", "CHOWN"]
  image: "ubuntu:25.10"
  container_prefix: "microclaw-sandbox"
  no_network: true
  require_runtime: false
  # optional external allowlist file
  # mount_allowlist_path: "~/.microclaw/sandbox-mount-allowlist.txt"

How to test:

docker info
docker run --rm ubuntu:25.10 echo ok
microclaw start

Then ask the agent to run:

• cat /etc/os-release
• pwd

Notes:

• sandbox.mode: "off" (default) means bash runs on host.
• sandbox.security_profile defaults to hardened (same behavior as old hardcoded settings):
  • hardened: --cap-drop ALL --security-opt no-new-privileges
  • standard: Docker default capabilities (useful for apt/chown/su in sandbox)
  • privileged: full container privilege (--privileged), debugging only
• sandbox.cap_add appends --cap-add entries for hardened and standard.
• If mode: "all" and Docker is unavailable:
  • require_runtime: false -> fallback to host with warning.
  • require_runtime: true -> command fails fast.
• Optional hardening:
  • ~/.microclaw/sandbox-mount-allowlist.txt for sandbox mount roots.
  • ~/.microclaw/sandbox-path-allowlist.txt for file tool path roots.

openai, openai-codex, openrouter, anthropic, ollama, google, alibaba, deepseek, moonshot, mistral, azure, bedrock, zhipu, minimax, cohere, tencent, xai, huggingface, together, custom.

• Telegram private chats: respond to every message.
• Telegram groups: respond only when mentioned with the active account username (for example @my_bot or @support_bot in multi-account mode); all group messages are still stored for context.
• Discord DMs: respond to every message.
• Discord server channels: respond on @mention; optionally constrained by discord_allowed_channels.
• Slack DMs: respond to every message.
• Slack channels: respond on @mention; optionally constrained by allowed_channels.
• Feishu/Lark DMs (p2p): respond to every message.
• Feishu/Lark groups: respond on @mention; optionally constrained by allowed_chats.
• Feishu/Lark emoji reactions: model can choose reaction-only (reaction-only: 👍), reaction+reply (reaction: 👍 then text), or plain text; single-token reactions auto-fallback to text if reaction API fails.
• IRC private messages: respond to every message.
• IRC channels: by default respond on mention; configurable via channels.irc.mention_required.
• Group/server/channel slash commands are mention-gated by default; set allow_group_slash_without_mention: true to restore permissive behavior.

Catch-up behavior (Telegram groups): When mentioned in a group, the bot loads all messages since its last reply in that group (instead of just the last N messages). This means it catches up on everything it missed, making group interactions much more contextual.

Tool calls are authorized against the current chat:

• Non-control chats can only operate on their own chat_id
• Control chats (control_chat_ids) can operate across chats
• write_memory with scope: "global" is restricted to control chats

Affected tools include send_message, scheduling tools, export_chat, todo_*, and chat-scoped memory operations.

Web search:

You: Search the web for the latest Rust release notes
Bot: [searches DuckDuckGo, returns top results with links]

Web fetch:

You: Fetch https://example.com and summarize it
Bot: [fetches page, strips HTML, summarizes content]

Scheduling:

You: Every morning at 9am, check the weather in Tokyo and send me a summary
Bot: Task #1 scheduled. Next run: 2025-06-15T09:00:00+00:00

[Next morning at 9am, bot automatically sends weather summary]

Mid-conversation messaging:

You: Analyze all log files in /var/log and give me a security report
Bot: [sends "Scanning log files..." as progress update]
Bot: [sends "Found 3 suspicious entries, analyzing..." as progress update]
Bot: [sends final security report]

Coding help:

You: Find all TODO comments in this project and fix them
Bot: [greps for TODOs, reads files, edits them, reports what was done]

Memory:

You: Remember that the production database is on port 5433
Bot: Saved to chat memory.

[Three days later]
You: What port is the prod database on?
Bot: Port 5433.

crates/
    microclaw-core/      # Shared error/types/text modules
    microclaw-storage/   # SQLite DB + memory domain + usage reporting
    microclaw-tools/     # Tool runtime primitives + sandbox + helper engines
    microclaw-channels/  # Channel abstractions and routing boundary
    microclaw-app/       # App-level support modules (logging, builtin skills, transcribe)

src/
    main.rs              # CLI entry point
    runtime.rs           # Runtime bootstrap + adapter startup
    agent_engine.rs      # Channel-agnostic agent loop
    llm.rs               # Provider abstraction (Anthropic/OpenAI-compatible/Codex)
    channels/*.rs        # Concrete channel adapters (Telegram/Discord/Slack/Feishu/IRC)
    tools/*.rs           # Built-in tool implementations + registry assembly
    scheduler.rs         # Background scheduler and reflector loop
    web.rs               # Web API + stream endpoints

Key design decisions:

• Session resume persists full message history (including tool blocks) in SQLite; context compaction summarizes old messages to stay within limits
• Provider abstraction with native Anthropic + OpenAI-compatible endpoints
• SQLite with WAL mode for concurrent read/write from async context
• Exponential backoff on 429 rate limits (3 retries)
• Message splitting for long channel responses
• Arc<Database> shared across tools and scheduler for thread-safe DB access
• Continuous typing indicator via a spawned task that sends typing action every 4 seconds

MicroClaw's core loop is channel-agnostic. A new platform integration should mainly be an adapter layer:

1. Implement inbound mapping from platform events into canonical chat inputs (chat_id, sender, chat type, content blocks).
2. Reuse the shared process_with_agent flow instead of creating a platform-specific agent loop.
3. Implement outbound delivery for text and attachment responses (including platform-specific length limits).
4. Define mention/reply trigger rules for group/server contexts.
5. Preserve session key stability so resume/compaction/memory continue to work across restarts.
6. Apply existing authorization and safety boundaries (control_chat_ids, tool constraints, path guard).
7. Add adapter-specific integration tests under TEST.md patterns (DM/private, group/server mention, /reset, limits, failures).

Thanks to everyone who has contributed to this project.

MIT