Quickstart

Get MicroClaw running in a few minutes.

1. Prerequisites

• Rust 1.70+ (2021 edition)
• at least one channel entry point:
  • Telegram bot token (legacy single-account) or Telegram channels.telegram.accounts (recommended multi-account), or
  • Discord bot token (legacy) or Discord channels.discord.accounts, or
  • Slack app token + bot token (legacy Socket Mode) or Slack channels.slack.accounts, or
  • Feishu/Lark app credentials (legacy) or Feishu channels.feishu.accounts, or
  • IRC server + nick + channel list, or
  • local Web UI mode (web_enabled: true)
• LLM API key (Anthropic/OpenAI/OpenRouter/DeepSeek/etc.)
  • openai-codex supports OAuth (codex login) or api_key (for OpenAI-compatible proxy endpoints)

2. Install

One-line installer (recommended)

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

This installer only installs prebuilt GitHub release binaries.

Homebrew (macOS)

brew tap microclaw/tap
brew install microclaw

From source

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

3. Configure (recommended)

Use the interactive setup wizard:

microclaw setup

It validates required fields, tests chat/LLM connectivity, and writes microclaw.config.yaml with backup in microclaw.config.backups/ (latest 50 kept). By default, channel credentials are written in multi-account shape (channels.<channel>.default_account + channels.<channel>.accounts.main). For multi-bot operations, setup and Web Settings both support editing full channels.<channel>.accounts JSON. Per-bot soul_path can be configured in both setup and Web Settings by selecting a file from discovered souls/*.md or entering a custom filename/path. It also includes provider/model list pickers (Enter open list, ↑/↓ move, Enter confirm, Esc close).

Built-in provider presets:

• openai, openai-codex, 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 config flow attempts to detect local models. For openai-codex, you can run codex login first (OAuth from ~/.codex/auth.json or $CODEX_HOME/auth.json), or use api_key with an OpenAI-compatible proxy endpoint.

These are also the valid values for llm_provider in microclaw.config.yaml.

Manual microclaw.config.yaml configuration is also supported:

llm_provider: "anthropic"
api_key: "sk-ant-..."
model: "claude-sonnet-4-5-20250929"
data_dir: "~/.microclaw"
working_dir: "~/.microclaw/working_dir"
working_dir_isolation: "chat" # optional; defaults to "chat"
max_document_size_mb: 100

# Pick one or more channels:
telegram_bot_token: "123456:ABC-DEF1234..."
bot_username: "my_bot"
# Recommended Telegram multi-account mode:
# channels:
#   telegram:
#     default_account: "main"
#     accounts:
#       main:
#         bot_token: "123456:ABC-DEF1234..."
#         bot_username: "my_bot"
#       support:
#         bot_token: "987654:XYZ-DEF9999..."
#         bot_username: "support_bot"
# Telegram group chat note for multi-bot:
#   In BotFather for each bot, enable Allow Groups and disable Group Privacy.
# Recommended Discord/Slack/Feishu multi-account mode:
# channels:
#   discord:
#     accounts:
#       main: { bot_token: "DISCORD_TOKEN_MAIN" }
#   slack:
#     accounts:
#       main: { bot_token: "xoxb-main...", app_token: "xapp-main..." }
#   feishu:
#     accounts:
#       main: { app_id: "cli_xxx", app_secret: "xxx", topic_mode: true } # topic_mode only for feishu/lark domains
# Optional channel overrides:
# channels:
#   telegram:
#     bot_username: "my_bot"
# discord_bot_token: "..."
# channels:
#   irc:
#     server: "irc.example.com"
#     nick: "microclaw"
#     channels: "#general"
web_enabled: true

Optional: run bash tool in Docker sandbox

Default behavior is host execution (sandbox.mode: "off").
To enable sandbox quickly:

microclaw setup --enable-sandbox
microclaw doctor sandbox

Or set it manually to route bash tool calls into Docker containers:

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

Quick verification:

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

Optional hardening:

• ~/.microclaw/sandbox-mount-allowlist.txt: sandbox mount allowlist.
• ~/.microclaw/sandbox-path-allowlist.txt: file tool path allowlist.
• sandbox.security_profile: "hardened" is the default restrictive mode; use "standard" if sandboxed commands need default Docker capabilities.

Then start MicroClaw and ask it to run:

• cat /etc/os-release
• pwd

4. Preflight diagnostics (recommended)

microclaw doctor

Sandbox-only diagnostics:

microclaw doctor sandbox

For support tickets, attach JSON output:

microclaw doctor --json

Text output includes clear status markers:

[✅ PASS] ...
[⚠️ WARN] ...
[❌ FAIL] ...

5. Run

microclaw start

That is it. On first launch, if required config is missing, start will auto-open the config flow. After setup, the runtime initializes SQLite, starts scheduler, and boots configured adapters (Telegram/Discord/Slack/Feishu/IRC/Web).

If web_enabled: true (default), local Web UI is available at:

http://127.0.0.1:10961

6. Optional: run as persistent gateway service

microclaw gateway install
microclaw gateway install --force
microclaw gateway status
microclaw gateway status --json --deep

Lifecycle commands:

microclaw gateway start
microclaw gateway stop
microclaw gateway restart
microclaw gateway logs 200
microclaw gateway uninstall

Next

• Read Configuration to see all config keys
• Explore Tools to understand what the agent can do
• Review Usage Examples for common workflows