{"id":44058744,"url":"https://github.com/microclaw/microclaw","last_synced_at":"2026-04-01T16:38:11.553Z","repository":{"id":337002401,"uuid":"1152019564","full_name":"microclaw/microclaw","owner":"microclaw","description":"An agentic AI assistant that lives in your Telegram/Discord chats, inspired by nanoclaw and incorporating some of its design ideas. ","archived":false,"fork":false,"pushed_at":"2026-02-13T07:49:07.000Z","size":5129,"stargazers_count":100,"open_issues_count":1,"forks_count":21,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-13T12:18:26.259Z","etag":null,"topics":["bot","nanoclaw","openclaw","rust"],"latest_commit_sha":null,"homepage":"https://microclaw.ai","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microclaw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-07T08:28:51.000Z","updated_at":"2026-02-13T12:15:16.000Z","dependencies_parsed_at":"2026-02-12T05:08:10.504Z","dependency_job_id":null,"html_url":"https://github.com/microclaw/microclaw","commit_stats":null,"previous_names":["microclaw/microclaw"],"tags_count":50,"template":false,"template_full_name":null,"purl":"pkg:github/microclaw/microclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microclaw%2Fmicroclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microclaw%2Fmicroclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microclaw%2Fmicroclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microclaw%2Fmicroclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microclaw","download_url":"https://codeload.github.com/microclaw/microclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microclaw%2Fmicroclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29438976,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T05:24:35.651Z","status":"ssl_error","status_checked_at":"2026-02-14T05:24:34.830Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","nanoclaw","openclaw","rust"],"created_at":"2026-02-08T01:05:33.152Z","updated_at":"2026-04-01T16:38:11.546Z","avatar_url":"https://github.com/microclaw.png","language":"Rust","funding_links":[],"categories":["Main Projects","Lightweight Alternatives \u0026 Forks","By Category","Alternative Architekturen","OpenClaw Rewrites \u0026 Alternatives"],"sub_categories":["Rust Native"],"readme":"# MicroClaw\n\u003cimg src=\"icon.png\" alt=\"MicroClaw logo\" width=\"56\" align=\"right\" /\u003e\n\n[English](README.md) | [中文](README_CN.md)\n\n[![Website](https://img.shields.io/badge/Website-microclaw.ai-blue)](https://microclaw.ai)\n[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/pvmezwkAk5)\n[![Reddit](https://img.shields.io/badge/Reddit-r%2Fmicroclaw-FF4500?logo=reddit\u0026logoColor=white)](https://www.reddit.com/r/microclaw/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/headline.png\" alt=\"MicroClaw headline logo\" width=\"92%\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eOne agent runtime for Telegram, Discord, Slack, Feishu, IRC, Web, and more.\u003c/strong\u003e\u003cbr /\u003e\n  Multi-step tool use, persistent memory, scheduled tasks, skills, MCP, and a local web control plane.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e |\n  \u003ca href=\"#install\"\u003eInstall\u003c/a\u003e |\n  \u003ca href=\"#why-microclaw\"\u003eWhy MicroClaw\u003c/a\u003e |\n  \u003ca href=\"#how-it-works\"\u003eArchitecture\u003c/a\u003e |\n  \u003ca href=\"#documentation\"\u003eDocs\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eQuick Routes:\u003c/strong\u003e\n  \u003ca href=\"docs/generated/tools.md\"\u003eTools\u003c/a\u003e ·\n  \u003ca href=\"docs/generated/config-defaults.md\"\u003eConfig Defaults\u003c/a\u003e ·\n  \u003ca href=\"docs/generated/provider-matrix.md\"\u003eProvider Matrix\u003c/a\u003e ·\n  \u003ca href=\"docs/operations/runbook.md\"\u003eRunbook\u003c/a\u003e ·\n  \u003ca href=\"docs/operations/http-hook-trigger.md\"\u003eWeb Hooks\u003c/a\u003e ·\n  \u003ca href=\"docs/clawhub/overview.md\"\u003eClawHub\u003c/a\u003e\n\u003c/p\u003e\n\nMicroClaw is an agent runtime for chat surfaces. It gives you one channel-agnostic agent loop, one provider-agnostic LLM layer, and one persistent runtime that can move across Telegram, Discord, Slack, Feishu/Lark, IRC, Web, and additional adapters over time.\n\nIt works with Anthropic and OpenAI-compatible providers, supports multi-step tool execution, keeps session state across turns, stores durable memory, runs scheduled tasks, and can expose the same runtime through both chat channels and a local web UI.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/screenshot1.png\" width=\"45%\" /\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"screenshots/screenshot2.png\" width=\"45%\" /\u003e\n\u003c/p\u003e\n\n## Why MicroClaw\n\n- **One runtime, many channels**: keep the same agent loop, tools, memory, and policies across chat platforms.\n- **Built for agentic execution**: tool calls, tool-result reflection, sub-agents, planning, and mid-run updates are first-class.\n- **Persistent by default**: sessions resume, memory survives restarts, and scheduled tasks keep running in the background.\n- **Provider-agnostic**: use Anthropic or OpenAI-compatible APIs without rewriting the runtime.\n- **Extensible where it matters**: add skills, MCP servers, plugins, hooks, and new channel adapters without replacing the core.\n\n## Quick Start\n\nInstall:\n\n```sh\ncurl -fsSL https://microclaw.ai/install.sh | bash\n```\n\nRun diagnostics:\n\n```sh\nmicroclaw doctor\n```\n\nCreate config with the interactive wizard:\n\n```sh\nmicroclaw setup\n```\n\nStart the runtime:\n\n```sh\nmicroclaw start\n```\n\nDefault local web UI:\n\n```text\nhttp://127.0.0.1:10961\n```\n\nIf you want a source build instead, jump to [Install](#install). If you want operational details, start with [Setup](#setup) and [Documentation](#documentation).\n\n## Install\n\n### One-line installer (recommended)\n\n```sh\ncurl -fsSL https://microclaw.ai/install.sh | bash\n```\n\n### Windows PowerShell installer\n\n```powershell\niwr https://microclaw.ai/install.ps1 -UseBasicParsing | iex\n```\n\nThis installer only does one thing:\n- Download and install the matching prebuilt binary from the latest GitHub release\n- It does not fallback to Homebrew/Cargo inside `install.sh` (use separate methods below)\n\nUpgrade in place later:\n\n```sh\nmicroclaw upgrade\n```\n\n### Preflight diagnostics\n\nRun cross-platform diagnostics before first start (or when troubleshooting):\n\n```sh\nmicroclaw doctor\n```\n\nMachine-readable output for support tickets:\n\n```sh\nmicroclaw doctor --json\n```\n\nChecks include PATH, shell runtime, `agent-browser`, PowerShell policy (Windows), and MCP command dependencies from `\u003cdata_dir\u003e/mcp.json` plus `\u003cdata_dir\u003e/mcp.d/*.json`.\n\nSandbox-only diagnostics:\n\n```sh\nmicroclaw doctor sandbox\n```\n\n### Uninstall (script)\n\nmacOS/Linux:\n\n```sh\ncurl -fsSL https://microclaw.ai/uninstall.sh | bash\n```\n\nWindows PowerShell:\n\n```powershell\niwr https://microclaw.ai/uninstall.ps1 -UseBasicParsing | iex\n```\n\n### Homebrew (macOS)\n\n```sh\nbrew tap microclaw/tap\nbrew install microclaw\n```\n\n### Docker image\n\nRelease tags publish an official container image to:\n\n- `ghcr.io/microclaw/microclaw:latest`\n- `ghcr.io/microclaw/microclaw:\u003cversion\u003e`\n- `docker.io/microclaw/microclaw:latest` when Docker Hub publishing credentials are configured for the repository\n\nFor first-time pulls from GHCR, you may need:\n\n```sh\ndocker login ghcr.io\n```\n\nUse your GitHub username and a Personal Access Token with `read:packages`.\n\nQuickest way to try the image:\n\n```sh\ndocker pull ghcr.io/microclaw/microclaw:latest\ndocker run --rm -it \\\n  -p 127.0.0.1:10961:10961 \\\n  ghcr.io/microclaw/microclaw:latest\n```\n\nRecommended for real use: keep config and runtime data on the host:\n\n```sh\nmkdir -p data tmp\nchmod a+r microclaw.config.yaml\nchmod -R a+rwX data tmp\n\ndocker run --rm -it \\\n  -p 127.0.0.1:10961:10961 \\\n  -v \"$(pwd)/microclaw.config.yaml:/app/microclaw.config.yaml:ro\" \\\n  -v \"$(pwd)/data:/home/microclaw/.microclaw\" \\\n  -v \"$(pwd)/tmp:/app/tmp\" \\\n  ghcr.io/microclaw/microclaw:latest\n```\n\nWhy mount them:\n\n- `microclaw.config.yaml`: keep configuration outside the container\n- `data/`: persist sessions, memory, skills, database, and runtime state\n- `tmp/`: provide a writable temp directory for container-side work\n\nThe image entrypoint is `microclaw`, so you can override the command directly:\n\n```sh\ndocker run --rm ghcr.io/microclaw/microclaw:latest doctor\ndocker run --rm ghcr.io/microclaw/microclaw:latest version\n```\n\nIf startup fails with `Permission denied (os error 13)`, re-check the `chmod` commands above and verify the mounted paths exist.\n\n### From source\n\n```sh\ngit clone https://github.com/microclaw/microclaw.git\ncd microclaw\ncargo build --release\ncp target/release/microclaw /usr/local/bin/\n```\n\nOptional semantic-memory build (sqlite-vec disabled by default):\n\n```sh\ncargo build --release --features sqlite-vec\n```\n\nFirst-time sqlite-vec quickstart (3 commands):\n\n```sh\ncargo run --features sqlite-vec -- setup\ncargo run --features sqlite-vec -- start\nsqlite3 \u003cdata_dir\u003e/runtime/microclaw.db \"SELECT id, chat_id, chat_channel, external_chat_id, category, embedding_model FROM memories ORDER BY id DESC LIMIT 20;\"\n```\n\nIn `setup`, set:\n- `embedding_provider` = `openai` or `ollama`\n- provider credentials/base URL/model as needed\n\n## How it works\n\nEvery message goes through a shared **agent loop**:\n\n1. Load file memory, structured memory, skills, and resumable session state\n2. Call the configured model with tool schemas and runtime context\n3. Execute tool calls, append results, and continue the loop until completion\n4. Persist the updated session, memory signals, and observability data\n\nThis keeps behavior consistent across channels and lets one runtime power interactive chat, scheduled work, web-triggered automation, and sub-agent execution.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/readme/microclaw-architecture.svg\" alt=\"MicroClaw architecture overview\" width=\"96%\" /\u003e\n\u003c/p\u003e\n\n## Blog post\n\nFor a deeper dive into the architecture and design decisions, read: **[Building MicroClaw: An Agentic AI Assistant in Rust That Lives in Your Chats](https://microclaw.ai/blog/building-microclaw)**\n\n## Features\n\n- **Agentic tool use** -- bash commands, file read/write/edit, glob search, regex grep, persistent memory\n- **Session resume** -- full conversation state (including tool interactions) persisted between messages; the agent keeps tool-call state across invocations\n- **Context compaction** -- when sessions grow too large, older messages are automatically summarized to stay within context limits\n- **Sub-agent** -- delegate self-contained sub-tasks to a parallel agent with restricted tools\n- **Agent skills** -- extensible skill system ([Anthropic Skills](https://github.com/anthropics/skills) compatible); skills are auto-discovered from `\u003cdata_dir\u003e/skills/` and activated on demand\n- **Plan \u0026 execute** -- todo list tools for breaking down complex tasks, tracking progress step by step\n- **Platform-extensible architecture** -- shared agent loop + tool system + storage, with platform adapters for channel-specific ingress/egress\n- **Web search** -- search the web via DuckDuckGo and fetch/parse web pages\n- **Scheduled tasks** -- cron-based recurring tasks and one-time scheduled tasks, managed through natural language\n- **Mid-conversation messaging** -- the agent can send intermediate messages before its final response\n- **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)\n- **Continuous typing indicator** -- typing indicator stays active for the full duration of processing\n- **Persistent memory** -- AGENTS.md files at global, bot/account, and per-chat scopes, loaded into every request\n- **Message splitting** -- long responses are automatically split at newline boundaries to fit channel limits (Telegram 4096 / Discord 2000 / Slack 4000 / Feishu 4000 / IRC ~380)\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `bash` | Execute shell commands with configurable timeout |\n| `read_file` | Read files with line numbers, optional offset/limit |\n| `write_file` | Create or overwrite files (auto-creates directories) |\n| `edit_file` | Find-and-replace editing with uniqueness validation |\n| `glob` | Find files by pattern (`**/*.rs`, `src/**/*.ts`) |\n| `grep` | Regex search across file contents |\n| `read_memory` | Read persistent AGENTS.md memory (`global`, `bot`, or `chat`) |\n| `write_memory` | Write persistent AGENTS.md memory |\n| `web_search` | Search the web via DuckDuckGo (returns titles, URLs, snippets) |\n| `web_fetch` | Fetch a URL and return plain text (HTML stripped, max 20KB) |\n| `send_message` | Send mid-conversation messages; supports attachments for Telegram/Discord/Slack/Weixin via `attachment_path` + optional `caption` |\n| `schedule_task` | Schedule a recurring (cron) or one-time task |\n| `list_scheduled_tasks` | List all active/paused tasks for a chat |\n| `pause_scheduled_task` | Pause a scheduled task |\n| `resume_scheduled_task` | Resume a paused task |\n| `cancel_scheduled_task` | Cancel a task permanently |\n| `get_task_history` | View execution history for a scheduled task |\n| `export_chat` | Export chat history to markdown |\n| `sessions_spawn` | Spawn an asynchronous sub-agent run and return immediately |\n| `subagents_list` | List sub-agent runs for the current chat |\n| `subagents_info` | Inspect one sub-agent run in detail |\n| `subagents_kill` | Cancel one run or all active runs in the current chat |\n| `subagents_focus` | Focus the chat on a specific sub-agent run |\n| `subagents_unfocus` | Clear focused sub-agent binding |\n| `subagents_focused` | Show current focused sub-agent run |\n| `subagents_send` | Send follow-up work to the focused sub-agent run |\n| `subagents_log` | Read timeline events for one sub-agent run |\n| `subagents_retry_announces` | Retry pending completion announcements for control chats |\n| `activate_skill` | Activate an agent skill to load specialized instructions |\n| `sync_skills` | Sync a skill from external registry (e.g. vercel-labs/skills) and normalize local frontmatter |\n| `todo_read` | Read the current task/plan list for a chat |\n| `todo_write` | Create or update the task/plan list for a chat |\n\nGenerated reference (source-of-truth, anti-drift):\n- `docs/generated/tools.md`\n- `docs/generated/config-defaults.md`\n- `docs/generated/provider-matrix.md`\n\nRegenerate with:\n```sh\nnode scripts/generate_docs_artifacts.mjs\n```\n\n## Memory\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/readme/memory-architecture.svg\" alt=\"MicroClaw memory architecture diagram\" width=\"92%\" /\u003e\n\u003c/p\u003e\n\nMicroClaw maintains persistent memory via `AGENTS.md` files:\n\n```\n\u003cdata_dir\u003e/runtime/groups/\n    AGENTS.md                 # Global memory (shared across all chats)\n    {channel}/\n        AGENTS.md             # Bot/account memory for this channel\n        {chat_id}/\n            AGENTS.md         # Per-chat memory (namespaced by channel)\n```\n\nMemory 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.\n\nMicroClaw also keeps structured memory rows in SQLite (`memories` table):\n- `write_memory` persists to file memory and structured memory\n- Background reflector extracts durable facts incrementally and deduplicates\n- Explicit \"remember ...\" commands use a deterministic fast path (direct structured-memory upsert)\n- Low-quality/noisy memories are filtered by quality gates before insertion\n- Memory lifecycle is managed with confidence + soft-archive fields (instead of hard delete)\n\nOptional memory MCP backend:\n- If MCP config includes a server exposing both `memory_query` and `memory_upsert`, structured-memory operations prefer that MCP server.\n- If MCP is not configured, unavailable, or returns invalid payloads, MicroClaw automatically falls back to built-in SQLite memory behavior.\n- Fallback is per operation. External-provider failures are classified as `timeout`, `transport`, `invalid_payload`, or `unsupported_operation` in health/self-check output.\n- Startup runs a lightweight probe against the external provider. If it fails, foreground memory operations can still continue through SQLite fallback.\n- This mode favors availability over strict cross-store consistency: SQLite fallback writes are not automatically backfilled into the external provider after recovery, and reflector background writes pause while the external provider is unhealthy to limit divergence.\n\nWhen 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.\n\n`/usage` now includes a **Memory Observability** section (and Web UI panel) showing:\n- memory pool health (active/archived/low-confidence)\n- reflector throughput (insert/update/skip in 24h)\n- injection coverage (selected vs candidate memories in 24h)\n\n### Chat Identity Mapping\n\nMicroClaw now stores a channel-scoped identity for chats:\n\n- `internal chat_id`: SQLite primary key used by sessions/messages/tasks\n- `channel + external_chat_id`: source chat identity from Telegram/Discord/Slack/Feishu/Weixin/IRC/Web\n\nThis avoids collisions when different channels can have the same numeric id. Legacy rows are migrated automatically on startup.\n\nUseful SQL for debugging:\n\n```sql\nSELECT chat_id, channel, external_chat_id, chat_type, chat_title\nFROM chats\nORDER BY last_message_time DESC\nLIMIT 50;\n\nSELECT id, chat_id, chat_channel, external_chat_id, category, content, embedding_model\nFROM memories\nORDER BY id DESC\nLIMIT 50;\n```\n\n## Skills\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/readme/skills-lifecycle.svg\" alt=\"MicroClaw skill lifecycle diagram\" width=\"92%\" /\u003e\n\u003c/p\u003e\n\nMicroClaw supports the [Anthropic Agent Skills](https://github.com/anthropics/skills) standard. Skills are modular packages that give the bot specialized capabilities for specific tasks.\n\n```\n\u003cdata_dir\u003e/skills/\n    pdf/\n        SKILL.md              # Required: name, description + instructions\n    docx/\n        SKILL.md\n```\n\n**How it works:**\n1. Skill metadata (name + description) is always included in the system prompt (~100 tokens per skill)\n2. When the model determines a skill is relevant, it calls `activate_skill` to load the full instructions\n3. The model follows the skill instructions to complete the task\n\n**Built-in skills:** pdf, docx, xlsx, pptx, skill-creator, apple-notes, apple-reminders, apple-calendar, weather, find-skills\n\n**New macOS skills (examples):**\n- `apple-notes` -- manage Apple Notes via `memo`\n- `apple-reminders` -- manage Apple Reminders via `remindctl`\n- `apple-calendar` -- query/create Calendar events via `icalBuddy` + `osascript`\n- `weather` -- quick weather lookup via `wttr.in`\n\n**Adding a skill:** Create a subdirectory under `\u003cdata_dir\u003e/skills/` with a `SKILL.md` file containing YAML frontmatter and markdown instructions.\n\nSupported frontmatter fields:\n- `name`, `description`\n- `platforms` (optional): e.g. `[darwin, linux, windows]`\n- `deps` (optional): required commands in `PATH`\n- `compatibility.os` / `compatibility.deps` (also supported)\n\nUnavailable skills are filtered automatically by platform/dependencies, so unsupported skills do not appear in `/skills`.\n\n## Plugins\n\nMicroClaw supports manifest-based plugins for:\n\n- Slash commands (for example `/uptime`, `/announce hello`)\n- Dynamic tools exposed to the agent loop\n- Per-turn context providers (prompt/document injections)\n\nDefault plugins directory:\n\n- `\u003cdata_dir\u003e/plugins`\n\nOptional override:\n\n```yaml\nplugins:\n  enabled: true\n  dir: \"./microclaw.data/plugins\"\n```\n\nPlugin admin commands (control chats):\n\n- `/plugins list`\n- `/plugins validate`\n- `/plugins reload`\n\nSee full manifest schema and examples: `docs/plugins/overview.md`.\n\n**Commands:**\n- `/stop` -- abort the current active run in this chat (keeps history/session data)\n- `/clear` -- clear current chat context (session + chat history), keep scheduled tasks\n- `/reset` -- clear current chat context (session + chat history) and scheduled task state\n- `/reset memory` -- clear current chat memory (chat AGENTS.md + structured memories), keep conversation and tasks\n- `/skills` -- list all available skills\n- `/reload-skills` -- reload skills from disk\n- `/archive` -- archive current in-memory session as markdown\n- `/usage` -- show token usage summary (current chat + global totals)\n- `/status` -- show provider/model plus current chat session/task status\n- `/providers` -- list configured provider profiles and show the active one\n- `/provider` -- show current provider/model (`/provider \u003cprofile\u003e` switches the current channel to that profile and persists it to config; `/provider reset` clears it)\n- `/models` -- list configured models for the active provider (`/models api` fetches the live provider model list when supported)\n- `/model` -- show current provider/model (`/model \u003cname\u003e` switches the current channel model override and persists it to config; `/model reset` clears it)\n\nCommand handling rules:\n- Any input starting with `/` is treated as a command.\n- Inputs with leading mentions before slash are also treated as commands (for example `@bot /status`, `\u003c@U123\u003e /status`).\n- Slash commands do **not** enter agent conversation history/session context.\n- Unknown slash commands return `Unknown command.`.\n- Use `/stop` to interrupt an in-flight run, `/clear` to wipe chat context only, and `/reset` to wipe chat context plus scheduled task state.\n\n## MCP\n\nMicroClaw supports MCP servers configured in `\u003cdata_dir\u003e/mcp.json` and optional fragments in `\u003cdata_dir\u003e/mcp.d/*.json` with protocol negotiation and configurable transport.\n\n- Default protocol version: `2025-11-05` (overridable globally or per server)\n- Supported transports: `stdio`, `streamable_http`\n\nRecommended production start (minimal local MCP only):\n\n```sh\ncp mcp.minimal.example.json \u003cdata_dir\u003e/mcp.json\n```\n\nFull example (includes optional remote streamable HTTP server):\n\n```sh\ncp mcp.example.json \u003cdata_dir\u003e/mcp.json\n```\n\nFor sidecar-style integrations (for example a separate HAPI bridge process), prefer a dedicated fragment:\n\n```sh\nmkdir -p \u003cdata_dir\u003e/mcp.d\ncp mcp.hapi-bridge.example.json \u003cdata_dir\u003e/mcp.d/hapi-bridge.json\n```\n\nDetailed ops guide: `docs/operations/hapi-bridge.md`.\n\nWeixin native guide:\n`docs/operations/weixin.md`.\n\nExample:\n\n```json\n{\n  \"defaultProtocolVersion\": \"2025-11-05\",\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"transport\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \".\"]\n    },\n    \"remote\": {\n      \"transport\": \"streamable_http\",\n      \"endpoint\": \"http://127.0.0.1:8080/mcp\"\n    }\n  }\n}\n```\n\n### Browser Automation with Playwright MCP\n\nTo give your agent access to a real browser with your existing logins (cookies, sessions), use the [Playwright MCP](https://github.com/microsoft/playwright-mcp) server in **extension mode**:\n\n1. Install the **Playwright MCP Bridge** extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/playwright-mcp-bridge)\n2. Click the extension icon and copy the `PLAYWRIGHT_MCP_EXTENSION_TOKEN`\n3. Add to your `mcp.json` (or `\u003cdata_dir\u003e/mcp.d/playwright.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"transport\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp@latest\", \"--extension\"],\n      \"env\": {\n        \"PLAYWRIGHT_MCP_EXTENSION_TOKEN\": \"\u003cyour-token-here\u003e\"\n      }\n    }\n  }\n}\n```\n\nThis 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.\n\n\u003e **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.\n\nMigration evaluation to official Rust SDK is tracked in `docs/mcp-sdk-evaluation.md`.\n\nValidation:\n\n```sh\nRUST_LOG=info cargo run -- start\n```\n\nLook for log lines like `MCP server '...' connected (...)`.\n\n### macOS Desktop Automation with Peekaboo MCP\n\n[Peekaboo](https://github.com/steipete/Peekaboo) is a macOS desktop automation MCP server. MicroClaw can use it directly via `stdio` transport (no runtime code changes needed).\n\n```sh\nmkdir -p \u003cdata_dir\u003e/mcp.d\ncp mcp.peekaboo.example.json \u003cdata_dir\u003e/mcp.d/peekaboo.json\n```\n\n`mcp.peekaboo.example.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"peekaboo\": {\n      \"transport\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"peekaboo-mcp@latest\"]\n    }\n  }\n}\n```\n\n### Windows Desktop Automation Options\n\nMicroClaw can also consume Windows desktop automation MCP servers via `stdio`.\n\n```sh\nmkdir -p \u003cdata_dir\u003e/mcp.d\ncp mcp.windows.desktop.example.json \u003cdata_dir\u003e/mcp.d/windows-desktop.json\n```\n\n`mcp.windows.desktop.example.json` includes:\n- `pywinauto` (native Windows desktop UI automation, stdio MCP)\n- optional `playwright` MCP for browser automation on Windows\n\nNote: 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.\n\n## Plan \u0026 Execute\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/readme/plan-execute.svg\" alt=\"MicroClaw plan and execute diagram\" width=\"92%\" /\u003e\n\u003c/p\u003e\n\nFor complex, multi-step tasks, the bot can create a plan and track progress:\n\n```\nYou: Set up a new Rust project with CI, tests, and documentation\nBot: [creates a todo plan, then executes each step, updating progress]\n\n1. [x] Create project structure\n2. [x] Add CI configuration\n3. [~] Write unit tests\n4. [ ] Add documentation\n```\n\nTodo lists are stored at `\u003cdata_dir\u003e/runtime/groups/{chat_id}/TODO.json` and persist across sessions.\n\n## Scheduling\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/readme/task-scheduler.svg\" alt=\"MicroClaw scheduling flow diagram\" width=\"92%\" /\u003e\n\u003c/p\u003e\n\nThe bot supports scheduled tasks via natural language:\n\n- **Recurring:** \"Remind me to check the logs every 30 minutes\" -- creates a cron task\n- **One-time:** \"Remind me at 5pm to call Alice\" -- creates a one-shot task\n\nUnder 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.\n\nManage tasks with natural language:\n```\n\"List my scheduled tasks\"\n\"Pause task #3\"\n\"Resume task #3\"\n\"Cancel task #3\"\n```\n\n## Local Web UI (cross-channel history)\n\nWhen `web_enabled: true`, MicroClaw serves a local Web UI (default `http://127.0.0.1:10961`).\n\n- Session list includes chats from all channels stored in SQLite (`telegram`, `discord`, `slack`, `feishu`, `irc`, `web`)\n- You can review and manage history (refresh / clear context / delete)\n- Non-web channels are read-only in Web UI by default (send from source channel)\n- If there are no sessions yet, Web UI auto-generates a new key like `session-YYYYMMDDHHmmss`\n- The first message in that session automatically persists it in SQLite\n- 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)\n- Password reset helpers:\n  - `microclaw web` (show usage)\n  - `microclaw web password \u003cvalue\u003e`\n  - `microclaw web password-generate`\n  - `microclaw web password-clear`\n\n### HTTP Request Trigger (headless automation)\n\nFor external automation (webhooks, CI, scripts), use the Web API with an API key that has\n`operator.write` scope.\n\nDetailed guide: [`docs/operations/http-hook-trigger.md`](docs/operations/http-hook-trigger.md)\n\nEndpoints:\n- `POST /api/send` (canonical)\n- `POST /api/chat` (alias for chatbot-style clients)\n- `POST /api/send_stream` (async run + SSE replay)\n- `POST /api/chat_stream` (alias for chatbot-style clients)\n- `GET /` accepts WebSocket upgrade for the OpenClaw Mission Control-compatible bridge\n- `POST /hooks/agent` and `POST /api/hooks/agent` (OpenClaw-style webhook payload compatibility)\n- `POST /hooks/wake` and `POST /api/hooks/wake` (system-event wake trigger: `now` or `next-heartbeat`)\n\nHook auth + policy (`channels.web`):\n```yaml\nchannels:\n  web:\n    hooks_token: \"replace-with-secret\"\n    hooks_default_session_key: \"hook:ingress\"\n    hooks_allow_request_session_key: false\n    hooks_allowed_session_key_prefixes: [\"hook:\"]\n```\n\nNotes:\n- `/hooks/*` requires hook token (`Authorization: Bearer \u003ctoken\u003e` or `x-openclaw-token`).\n- `sessionKey` in request body is rejected by default unless `hooks_allow_request_session_key: true`.\n- If you enable request `sessionKey`, use prefix allowlist to avoid arbitrary session routing.\n\nRequest body:\n```json\n{\n  \"session_key\": \"ops-bot\",\n  \"sender_name\": \"automation\",\n  \"message\": \"Check error budget and summarize incidents in the last hour.\"\n}\n```\n\nSynchronous response (`/api/send` or `/api/chat`):\n```json\n{\n  \"ok\": true,\n  \"session_key\": \"ops-bot\",\n  \"chat_id\": 123,\n  \"response\": \"...\"\n}\n```\n\nAsync streaming response (`/api/send_stream` or `/api/chat_stream`):\n```json\n{\n  \"ok\": true,\n  \"run_id\": \"6f4c2b1d-...\",\n  \"session_key\": \"ops-bot\",\n  \"chat_id\": 123\n}\n```\n\nConsume SSE events:\n```sh\ncurl -N \"http://127.0.0.1:10961/api/stream?run_id=\u003cRUN_ID\u003e\" \\\n  -H \"Authorization: Bearer $MICROCLAW_API_KEY\"\n```\n\nMission Control / OpenClaw-style WebSocket bridge:\n\n1. Connect to `ws://127.0.0.1:10961/`\n2. Wait for `connect.challenge`\n3. Send a `connect` frame with your operator API key in `params.auth.token`\n4. Use bridge methods such as `chat.send`, `sessions.send`, `sessions.kill`, `sessions.spawn`, and `sessions.set*`\n5. Consume live `chat` events (`delta` / `final` / `error`)\n\nCurrent bridge methods:\n\n- `health`\n- `status`\n- `chat.send`\n- `chat.history`\n- `sessions.delete`\n- `sessions.send`\n- `sessions.kill`\n- `sessions.spawn`\n- `sessions.setThinking`\n- `sessions.setVerbose`\n- `sessions.setReasoning`\n- `sessions.setLabel`\n- `sessions.list`\n- `agents.list`\n- `models.list`\n- `config.get`\n- `node.list`\n\nExample connect frame:\n\n```json\n{\n  \"type\": \"req\",\n  \"id\": \"connect-1\",\n  \"method\": \"connect\",\n  \"params\": {\n    \"minProtocol\": 3,\n    \"maxProtocol\": 3,\n    \"auth\": { \"token\": \"mc_...\" }\n  }\n}\n```\n\nExample chat send frame:\n\n```json\n{\n  \"type\": \"req\",\n  \"id\": \"send-1\",\n  \"method\": \"chat.send\",\n  \"params\": {\n    \"sessionKey\": \"ops-bot\",\n    \"message\": \"Summarize the current repo\",\n    \"idempotencyKey\": \"idem-1\"\n  }\n}\n```\n\nExample session spawn frame:\n\n```json\n{\n  \"type\": \"req\",\n  \"id\": \"spawn-1\",\n  \"method\": \"sessions.spawn\",\n  \"params\": {\n    \"task\": \"Summarize the current repo\",\n    \"label\": \"Ops\"\n  }\n}\n```\n\nExample session label update:\n\n```json\n{\n  \"type\": \"req\",\n  \"id\": \"label-1\",\n  \"method\": \"sessions.setLabel\",\n  \"params\": {\n    \"sessionKey\": \"ops-bot\",\n    \"label\": \"Ops\"\n  }\n}\n```\n\nBehavior notes:\n\n- The bridge is mounted at `GET /` for WebSocket upgrades, not `/ws`.\n- `sessions.send` returns a `runId` immediately and then emits `chat` events, including a terminal `final` state for normal messages.\n- `sessions.spawn` can create a new async session and persist an initial label.\n- `sessions.set*` updates only the provided field and preserves previously stored session settings.\n- `sessions.send` control payloads are acknowledged, but not yet enforced as runtime controls.\n\nLocal gateway smoke tests:\n\n```sh\nMICROCLAW_GATEWAY_TOKEN=mc_... microclaw gateway call health\nMICROCLAW_GATEWAY_TOKEN=mc_... microclaw gateway call status\nMICROCLAW_GATEWAY_TOKEN=mc_... microclaw gateway call sessions.setLabel \\\n  --params '{\"sessionKey\":\"ops-bot\",\"label\":\"Ops\"}'\nMICROCLAW_GATEWAY_TOKEN=mc_... microclaw gateway call sessions.send \\\n  --params '{\"sessionKey\":\"ops-bot\",\"message\":\"status summary\"}'\n```\n\n`microclaw gateway call` resolves connection settings from:\n\n- `MICROCLAW_GATEWAY_URL`, `OPENCLAW_GATEWAY_URL`, `GATEWAY_URL`\n- `MICROCLAW_GATEWAY_HOST`, `OPENCLAW_GATEWAY_HOST`, `GATEWAY_HOST`\n- `MICROCLAW_GATEWAY_PORT`, `OPENCLAW_GATEWAY_PORT`, `GATEWAY_PORT`\n- `MICROCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_TOKEN`, `GATEWAY_TOKEN`, `MICROCLAW_API_KEY`\n\nExample:\n```sh\ncurl -sS http://127.0.0.1:10961/api/chat \\\n  -H \"Authorization: Bearer $MICROCLAW_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"session_key\":\"ops-bot\",\"sender_name\":\"automation\",\"message\":\"status summary\"}'\n```\n\nOpenClaw-compatible webhook shape:\n```sh\ncurl -sS http://127.0.0.1:10961/hooks/agent \\\n  -H \"Authorization: Bearer $MICROCLAW_HOOKS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\":\"Summarize inbox\",\"name\":\"Email\",\"sessionKey\":\"hook:email:msg-123\"}'\n```\n\nWake example:\n```sh\ncurl -sS http://127.0.0.1:10961/hooks/wake \\\n  -H \"Authorization: Bearer $MICROCLAW_HOOKS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\":\"New email received\",\"mode\":\"now\"}'\n```\n\n## Release\n\nPublish both installer mode (GitHub Release asset used by `install.sh`) and Homebrew mode with one command:\n\n```sh\n./deploy.sh\n```\n\nNixpkgs upstream/update playbook:\n- `docs/releases/nixpkgs-upstream-guide.md`\n\n## Setup\n\n\u003e **New:** MicroClaw now includes an interactive setup wizard (`microclaw setup`) and will auto-launch it on first `start` when required config is missing.\n\n### 1. Create channel bot credentials\n\nEnable at least one channel, or use Web UI (enabled by default).\n\nTelegram (optional):\n1. Open Telegram and search for [@BotFather](https://t.me/BotFather)\n2. Send `/newbot`\n3. Enter a display name for your bot (e.g. `My MicroClaw`)\n4. Enter a username (must end in `bot`, e.g. `my_microclaw_bot`)\n5. BotFather will reply with a token like `123456789:ABCdefGHIjklMNOpqrsTUVwxyz` -- save this as `telegram_bot_token` (legacy single-account) or `channels.telegram.accounts.\u003cid\u003e.bot_token` (recommended multi-account)\n\nRecommended BotFather settings (optional but useful):\n- `/setdescription` -- set a short description shown in the bot's profile\n- `/setcommands` -- register commands so users see them in the menu:\n  ```\n  reset - Clear current session\n  status - Show runtime/session status\n  model - Show current provider/model\n  skills - List available agent skills\n  usage - Show usage summary\n  ```\n- `/setprivacy` -- set to `Disable` if you want the bot to see all group messages (not just @mentions)\n\nDiscord (optional):\n1. Open the [Discord Developer Portal](https://discord.com/developers/applications)\n2. Create an application and add a bot\n3. Copy the bot token and save it as `discord_bot_token`\n4. Invite the bot to your server with `Send Messages`, `Read Message History`, and mention permissions\n5. Optional: set `discord_allowed_channels` to restrict where the bot can reply\n\nSlack (optional, Socket Mode):\n1. Create an app at [api.slack.com/apps](https://api.slack.com/apps)\n2. Enable Socket Mode and get an `app_token` (starts with `xapp-`)\n3. Add `bot_token` scope and install to workspace to get `bot_token` (starts with `xoxb-`)\n4. Subscribe to `message` and `app_mention` events\n5. Configure under `channels.slack` in config\n\nFeishu/Lark (optional):\n1. Create an app at the [Feishu Open Platform](https://open.feishu.cn/app) (or [Lark Developer](https://open.larksuite.com/app) for international)\n2. Get `app_id` and `app_secret` from app credentials\n3. Enable `im:message` and `im:message.receive_v1` event subscription\n4. Choose connection mode: WebSocket (default, no public URL needed) or Webhook\n5. Configure under `channels.feishu` in config; set `domain: \"lark\"` for international\n\nIRC (optional):\n1. Prepare an IRC server endpoint, port, and bot nick\n2. Configure under `channels.irc` in config (`server`, `nick`, `channels` are required)\n3. Optional: enable TLS with `tls: \"true\"` and set `tls_server_name` if needed\n4. Optional: set `mention_required: \"false\"` if you want replies in channels without mention\n\n### 2. Get an LLM API key\n\nChoose a provider and create an API key:\n- Anthropic: [console.anthropic.com](https://console.anthropic.com/)\n- OpenAI: [platform.openai.com](https://platform.openai.com/)\n- Or any OpenAI-compatible provider (OpenRouter, DeepSeek, etc.)\n- For `openai-codex`, you can use OAuth (`codex login`) or an API key (for OpenAI-compatible proxy endpoints).\n\n### 3. Configure (recommended: interactive Q\u0026A)\n\n```sh\nmicroclaw setup\n```\n\n\u003c!-- Setup wizard screenshot placeholder --\u003e\n\u003c!-- Replace with real screenshot later --\u003e\n![Setup Wizard (placeholder)](screenshots/setup-wizard.png)\n\nThe `config` flow provides:\n- Question-by-question prompts with defaults (`Enter` to confirm quickly)\n- Provider selection + model selection (numbered choices with custom override)\n- Better Ollama UX: local model auto-detection + sensible local defaults\n- Channel credentials are written in multi-account form by default (`channels.\u003cchannel\u003e.default_account` + `channels.\u003cchannel\u003e.accounts.main`)\n- Per-bot `soul_path` picker for Telegram/dynamic channels (auto-discovers `souls/*.md`, also supports manual filename/path input)\n- Safe `microclaw.config.yaml` save with automatic backup in `microclaw.config.backups/` (keeps latest 50)\n- Auto-created directories for `data_dir` and `working_dir`\n\nIf you prefer the full-screen TUI, you can still run:\n\n```sh\nmicroclaw setup\n```\n\nProvider presets available in the wizard:\n- `openai`\n- `openai-codex` (ChatGPT/Codex subscription OAuth; run `codex login`)\n- `openrouter`\n- `anthropic`\n- `ollama`\n- `google`\n- `alibaba`\n- `deepseek`\n- `moonshot`\n- `mistral`\n- `azure`\n- `bedrock`\n- `zhipu`\n- `minimax`\n- `cohere`\n- `tencent`\n- `xai`\n- `huggingface`\n- `together`\n- `custom` (manual provider/model/base URL)\n\nFor 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.\n\nFor `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`.\n\nYou can still configure manually with `microclaw.config.yaml`:\n\n```\ntelegram_bot_token: \"123456:ABC-DEF1234...\"\nbot_username: \"my_bot\"\n# recommended Telegram multi-account mode (multi-token, multi-bot):\n# channels:\n#   telegram:\n#     default_account: \"main\"\n#     # optional: route group topics as separate chats via \"\u003cchat_id\u003e:\u003cthread_id\u003e\"\n#     # topic_routing:\n#     #   enabled: true\n#     # optional: only allow these Telegram user IDs in private chats (DM)\n#     # allowed_user_ids: [123456789]\n#     accounts:\n#       main:\n#         bot_token: \"123456:ABC-DEF1234...\"\n#         bot_username: \"my_bot\"\n#         # optional per-account topic routing override (fallback to channel-level)\n#         # topic_routing:\n#         #   enabled: false\n#         # optional per-account DM allowlist (overrides channel-level list)\n#         # allowed_user_ids: [123456789]\n#       support:\n#         bot_token: \"987654:XYZ-DEF9999...\"\n#         bot_username: \"support_bot\"\n# recommended Discord multi-account mode:\n# channels:\n#   discord:\n#     default_account: \"main\"\n#     accounts:\n#       main:\n#         bot_token: \"DISCORD_TOKEN_MAIN\"\n#       ops:\n#         bot_token: \"DISCORD_TOKEN_OPS\"\n#         no_mention: true\n#         allowed_channels: [123456789012345678]\n# recommended Slack multi-account mode:\n# channels:\n#   slack:\n#     default_account: \"main\"\n#     accounts:\n#       main:\n#         bot_token: \"xoxb-main...\"\n#         app_token: \"xapp-main...\"\n#       support:\n#         bot_token: \"xoxb-support...\"\n#         app_token: \"xapp-support...\"\n#         allowed_channels: [\"C123ABC456\"]\n# recommended Feishu multi-account mode:\n# channels:\n#   feishu:\n#     default_account: \"main\"\n#     accounts:\n#       main:\n#         app_id: \"cli_xxx\"\n#         app_secret: \"xxx\"\n#         topic_mode: true    # optional; only supported for domain feishu/lark\n#       intl:\n#         app_id: \"cli_yyy\"\n#         app_secret: \"yyy\"\n#         domain: \"lark\"\n#         topic_mode: true    # optional; only supported for domain feishu/lark\n# recommended IRC mode:\n# channels:\n#   irc:\n#     server: \"irc.example.com\"\n#     port: \"6697\"\n#     nick: \"microclaw\"\n#     channels: \"#general,#ops\"\n#     tls: \"true\"\n#     mention_required: \"true\"\nllm_provider: \"anthropic\"\napi_key: \"sk-ant-...\"\nmodel: \"claude-sonnet-4-20250514\"\n# optional\n# llm_base_url: \"https://...\"\ndata_dir: \"~/.microclaw\"\nworking_dir: \"~/.microclaw/working_dir\"\nworking_dir_isolation: \"chat\" # optional; defaults to \"chat\" if omitted\nsandbox:\n  mode: \"off\" # optional; default off. set \"all\" to run bash in a container sandbox\nmax_document_size_mb: 100\nmemory_token_budget: 1500\ntimezone: \"UTC\"\n# optional semantic memory runtime config (requires --features sqlite-vec build)\n# embedding_provider: \"openai\"   # openai | ollama\n# embedding_api_key: \"sk-...\"\n# embedding_base_url: \"https://api.openai.com/v1\"\n# embedding_model: \"text-embedding-3-small\"\n# embedding_dim: 1536\n```\n\n### 4. Run\n\n```sh\nmicroclaw start\n```\n\n### 5. Run as persistent gateway service (optional)\n\n```sh\nmicroclaw gateway install\nmicroclaw gateway status\nmicroclaw gateway status --json\n```\n\nManage service lifecycle:\n\n```sh\nmicroclaw gateway install --force\nmicroclaw gateway start\nmicroclaw gateway stop\nmicroclaw gateway restart\nmicroclaw gateway logs 200\nmicroclaw gateway uninstall\n```\n\nNotes:\n- macOS uses `launchd` user agents.\n- Linux uses `systemd --user`.\n- Windows uses a native Windows Service hosted directly by `microclaw.exe`. Run gateway service commands from an elevated terminal, and make sure `microclaw.config.yaml` already exists before `microclaw gateway install`.\n- Runtime logs are written to `\u003cdata_dir\u003e/runtime/logs/`.\n- macOS launchd stdout/stderr files are `microclaw-gateway.log` and `microclaw-gateway.error.log`.\n- Logs older than 30 days are deleted automatically.\n\n### 6. Run as an ACP stdio server (optional)\n\nMicroClaw can also expose an Agent Client Protocol server over stdio:\n\n```sh\nmicroclaw acp\n```\n\nUse this mode when another local tool wants to talk to MicroClaw as a sessioned chat runtime over stdio instead of through Telegram, Discord, or the Web UI.\n\n## Configuration\n\nAll configuration is via `microclaw.config.yaml`:\n\n| Key | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `telegram_bot_token` | No* | -- | Telegram bot token from BotFather (legacy single-account mode) |\n| `channels.telegram.default_account` | No | unset | Default Telegram account ID in multi-account mode |\n| `channels.telegram.accounts.\u003cid\u003e.bot_token` | No* | unset | Telegram bot token for a specific account (recommended multi-account mode) |\n| `channels.telegram.accounts.\u003cid\u003e.bot_username` | No | unset | Telegram username for a specific account (without `@`) |\n| `channels.telegram.provider_preset` | No | unset | Optional Telegram channel-level provider profile override |\n| `channels.telegram.accounts.\u003cid\u003e.provider_preset` | No | unset | Optional per-bot provider profile override for that Telegram account |\n| `channels.telegram.accounts.\u003cid\u003e.soul_path` | No | unset | Optional per-bot SOUL file path for this Telegram account |\n| `channels.telegram.topic_routing.enabled` | No | `false` | If true, Telegram topics are routed as separate chats using `external_chat_id=\u003cchat_id\u003e:\u003cthread_id\u003e` |\n| `channels.telegram.accounts.\u003cid\u003e.topic_routing.enabled` | No | inherit channel-level | Optional per-account override for Telegram topic routing |\n| `channels.telegram.allowed_user_ids` | No | `[]` | Optional Telegram private chat sender allowlist at channel scope |\n| `channels.telegram.accounts.\u003cid\u003e.allowed_groups` | No | `[]` | Optional Telegram group allowlist scoped to one account |\n| `channels.telegram.accounts.\u003cid\u003e.allowed_user_ids` | No | `[]` | Optional Telegram private chat sender allowlist scoped to one account (merged with channel scope) |\n| `discord_bot_token` | No* | -- | Discord bot token from Discord Developer Portal |\n| `channels.discord.default_account` | No | unset | Default Discord account ID in multi-account mode |\n| `channels.discord.accounts.\u003cid\u003e.bot_token` | No* | unset | Discord bot token for a specific account |\n| `channels.discord.accounts.\u003cid\u003e.allowed_channels` | No | `[]` | Optional Discord channel allowlist scoped to one account |\n| `channels.discord.accounts.\u003cid\u003e.no_mention` | No | `false` | If true, that Discord account responds in guild channels without @mention |\n| `channels.discord.provider_preset` | No | unset | Optional Discord channel-level provider profile override |\n| `channels.discord.accounts.\u003cid\u003e.provider_preset` | No | unset | Optional per-bot provider profile override for that Discord account |\n| `channels.discord.accounts.\u003cid\u003e.soul_path` | No | unset | Optional per-bot SOUL file path for this Discord account |\n| `allow_group_slash_without_mention` | No | `false` | If true, allow slash commands in group/server/channel chats without @mention |\n| `discord_allowed_channels` | No | `[]` | Discord channel ID allowlist; empty means no channel restriction |\n| `api_key` | Yes* | -- | LLM API key (`ollama` can leave this empty; `openai-codex` supports OAuth or `api_key`) |\n| `bot_username` | No | -- | Telegram bot username (without @; needed for Telegram group mentions) |\n| `llm_provider` | No | `anthropic` | Global main LLM provider profile. Built-ins include `anthropic`, `openai`, `google`, `aliyun-bailian`, `nvidia`, `openrouter`, `ollama`, and `custom` |\n| `model` | No | provider-specific | Model name |\n| `provider_presets.\u003cid\u003e` | No | `{}` | Optional reusable provider profiles for channel/bot overrides. Each profile can define provider, api key, base URL, user-agent, `default_model`, and show-thinking |\n| `model_prices` | No | `[]` | Optional per-model pricing table (USD per 1M tokens) used by `/usage` cost estimates |\n| `llm_base_url` | No | provider preset default | Custom provider base URL |\n| `openai_compat_body_overrides` | No | `{}` | Global request-body overrides for OpenAI-compatible providers (`openai`, `openrouter`, `deepseek`, `ollama`, etc.) |\n| `openai_compat_body_overrides_by_provider` | No | `{}` | Provider-specific OpenAI-compatible request-body overrides (keyed by provider name, case-insensitive) |\n| `openai_compat_body_overrides_by_model` | No | `{}` | Model-specific OpenAI-compatible request-body overrides (keyed by exact model name) |\n| `data_dir` | No | `~/.microclaw` | Data root (`runtime` data in `data_dir/runtime`, skills in `data_dir/skills`) |\n| `working_dir` | No | `~/.microclaw/working_dir` | Default working directory for tool operations; relative paths in `bash/read_file/write_file/edit_file/glob/grep` resolve from here |\n| `working_dir_isolation` | No | `chat` | Working directory isolation mode for `bash/read_file/write_file/edit_file/glob/grep`: `shared` uses `working_dir/shared`, `chat` isolates each chat under `working_dir/chat/\u003cchannel\u003e/\u003cchat_id\u003e` |\n| `high_risk_tool_user_confirmation_required` | No | `true` | Require explicit user confirmation before high-risk tool execution (for example `bash`) |\n| `sandbox.mode` | No | `off` | Container sandbox mode for bash tool execution: `off` runs on host; `all` routes bash commands into docker containers |\n| `sandbox.security_profile` | No | `hardened` | Sandbox privilege profile: `hardened` (`--cap-drop ALL --security-opt no-new-privileges`), `standard` (Docker default caps), `privileged` (`--privileged`) |\n| `sandbox.cap_add` | No | `[]` | Optional extra Linux capabilities to add (`--cap-add`); applies to `hardened` and `standard` profiles |\n| `sandbox.mount_allowlist_path` | No | unset | Optional external mount allowlist file (one allowed root path per line) |\n| `max_tokens` | No | `8192` | Max tokens per model response |\n| `max_tool_iterations` | No | `100` | Max tool-use loop iterations per message |\n| `max_document_size_mb` | No | `100` | Maximum allowed size for inbound Telegram documents; larger files are rejected with a hint message |\n| `memory_token_budget` | No | `1500` | Estimated token budget for injecting structured memories into prompt context |\n| `subagents.max_concurrent` | No | `4` | Maximum number of active sub-agent runs across the runtime |\n| `subagents.max_active_per_chat` | No | `5` | Maximum number of active sub-agent runs allowed per chat |\n| `subagents.run_timeout_secs` | No | `900` | Timeout for a single sub-agent run |\n| `subagents.max_spawn_depth` | No | `1` | Maximum recursive sub-agent depth |\n| `subagents.max_children_per_run` | No | `5` | Maximum number of child runs created from one parent run |\n| `subagents.max_tokens_per_run` | No | `400000` | Per-run token budget ceiling used by `sessions_spawn` and `subagents_orchestrate` |\n| `subagents.orchestrate_max_workers` | No | `5` | Worker cap for `subagents_orchestrate` fan-out |\n| `subagents.announce_to_chat` | No | `true` | Post sub-agent completion notices back into the parent chat |\n| `subagents.thread_bound_routing_enabled` | No | `true` | Route thread replies to the currently focused sub-agent when supported by the channel |\n| `max_history_messages` | No | `50` | Number of recent messages sent as context |\n| `control_chat_ids` | No | `[]` | Chat IDs that can perform cross-chat actions (send_message/schedule/export/memory global/todo) |\n| `max_session_messages` | No | `40` | Message count threshold that triggers context compaction |\n| `compact_keep_recent` | No | `20` | Number of recent messages to keep verbatim during compaction |\n| `embedding_provider` | No | unset | Runtime embedding provider (`openai` or `ollama`) for semantic memory retrieval; requires `--features sqlite-vec` build |\n| `embedding_api_key` | No | unset | API key for embedding provider (optional for `ollama`) |\n| `embedding_base_url` | No | provider default | Optional base URL override for embedding provider |\n| `embedding_model` | No | provider default | Embedding model ID |\n| `embedding_dim` | No | provider default | Embedding vector dimension for sqlite-vec index initialization |\n| `channels.slack.default_account` | No | unset | Default Slack account ID in multi-account mode |\n| `channels.slack.accounts.\u003cid\u003e.bot_token` | No* | unset | Slack bot token for a specific account |\n| `channels.slack.accounts.\u003cid\u003e.app_token` | No* | unset | Slack app token (Socket Mode) for a specific account |\n| `channels.slack.accounts.\u003cid\u003e.allowed_channels` | No | `[]` | Optional Slack channel allowlist scoped to one account |\n| `channels.slack.accounts.\u003cid\u003e.model` | No | unset | Optional per-bot model override for that Slack account |\n| `channels.slack.accounts.\u003cid\u003e.soul_path` | No | unset | Optional per-bot SOUL file path for this Slack account |\n| `channels.feishu.default_account` | No | unset | Default Feishu/Lark account ID in multi-account mode |\n| `channels.feishu.accounts.\u003cid\u003e.app_id` | No* | unset | Feishu/Lark app ID for a specific account |\n| `channels.feishu.accounts.\u003cid\u003e.app_secret` | No* | unset | Feishu/Lark app secret for a specific account |\n| `channels.feishu.accounts.\u003cid\u003e.domain` | No | `feishu` | Feishu domain for that account (`feishu`, `lark`, or custom URL) |\n| `channels.feishu.accounts.\u003cid\u003e.allowed_chats` | No | `[]` | Optional Feishu chat allowlist scoped to one account |\n| `channels.feishu.accounts.\u003cid\u003e.model` | No | unset | Optional per-bot model override for that Feishu/Lark account |\n| `channels.feishu.accounts.\u003cid\u003e.soul_path` | No | unset | Optional per-bot SOUL file path for this Feishu/Lark account |\n| `channels.feishu.accounts.\u003cid\u003e.topic_mode` | No | `false` | Optional per-bot threaded reply mode; only supported when account domain is `feishu` or `lark` |\n| `channels.\u003cname\u003e.soul_path` | No | unset | Optional channel-level SOUL file path fallback (used when account-level `soul_path` is not set) |\n| `soul_path` | No | unset | Global SOUL file path fallback (used when channel/account `soul_path` is not set) |\n| `channels.irc.server` | No* | unset | IRC server host/IP |\n| `channels.irc.port` | No | `\"6667\"` | IRC server port |\n| `channels.irc.nick` | No* | unset | IRC bot nick |\n| `channels.irc.username` | No | unset | IRC username (defaults to nick) |\n| `channels.irc.real_name` | No | `\"MicroClaw\"` | IRC real name (sent in USER command) |\n| `channels.irc.channels` | No* | unset | Comma-separated channel list (for example `#general,#ops`) |\n| `channels.irc.password` | No | unset | Optional IRC server password |\n| `channels.irc.model` | No | unset | Optional model override for IRC bot |\n| `channels.irc.mention_required` | No | `\"true\"` | In channel chats, require mention before replying |\n| `channels.irc.tls` | No | `\"false\"` | Enable IRC TLS connection |\n| `channels.irc.tls_server_name` | No | unset | Optional TLS SNI/server name override |\n| `channels.irc.tls_danger_accept_invalid_certs` | No | `\"false\"` | Accept invalid TLS certs (testing only) |\n\nPath compatibility policy:\n- If `data_dir` / `skills_dir` / `working_dir` are already configured, MicroClaw keeps using those configured paths.\n- If these fields are not configured, defaults are `data_dir=~/.microclaw`, `skills_dir=\u003cdata_dir\u003e/skills`, `working_dir=~/.microclaw/working_dir`.\n\n`*` At least one channel configuration must be enabled; `web_enabled` is on by default.\n\n### OpenAI-compatible body overrides\n\nThese fields let you pass custom JSON parameters to OpenAI-compatible `/chat/completions` or `/responses` requests without adding provider-specific code.\n\nMerge order (later wins):\n1. `openai_compat_body_overrides` (global)\n2. `openai_compat_body_overrides_by_provider[llm_provider]`\n3. `openai_compat_body_overrides_by_model[model]`\n\n`null` unsets a key:\n\n```yaml\nllm_provider: \"deepseek\"\nmodel: \"deepseek-chat\"\n\nopenai_compat_body_overrides:\n  temperature: 0.2\n\nopenai_compat_body_overrides_by_provider:\n  deepseek:\n    top_p: null\n    reasoning_effort: \"high\"\n\nopenai_compat_body_overrides_by_model:\n  deepseek-chat:\n    temperature: 0.0\n```\n\nNotes:\n- `provider` keys are normalized to lowercase (`OPENAI` and `openai` are equivalent).\n- `model` keys are exact-match after trimming.\n- Runtime-controlled fields like stream mode and tool payload may still be set by MicroClaw for the active request path.\n\n## Docker Sandbox\n\nUse this when you want `bash` tool calls to run in Docker containers instead of the host.\n\nQuick config:\n\n```sh\nmicroclaw setup --enable-sandbox\nmicroclaw doctor sandbox\n```\n\nOr configure manually:\n\n```yaml\nsandbox:\n  mode: \"all\"\n  backend: \"auto\"\n  security_profile: \"hardened\" # optional; hardened|standard|privileged, default hardened\n  # optional capability overrides (applies to hardened/standard)\n  # cap_add: [\"SETUID\", \"SETGID\", \"CHOWN\"]\n  image: \"ubuntu:25.10\"\n  container_prefix: \"microclaw-sandbox\"\n  no_network: true\n  require_runtime: true\n  # optional external allowlist file\n  # mount_allowlist_path: \"~/.microclaw/sandbox-mount-allowlist.txt\"\n```\n\nHow to test:\n\n```sh\ndocker info\ndocker run --rm ubuntu:25.10 echo ok\nmicroclaw start\n```\n\nThen ask the agent to run:\n- `cat /etc/os-release`\n- `pwd`\n\nNotes:\n- `sandbox.mode: \"off\"` (default) means `bash` runs on host.\n- Recommended production posture: `sandbox.mode=all`, `require_runtime=true`, `security_profile=hardened`, and keep high-risk confirmation enabled.\n- `sandbox.security_profile` defaults to `hardened` (same behavior as old hardcoded settings):\n  - `hardened`: `--cap-drop ALL --security-opt no-new-privileges`\n  - `standard`: Docker default capabilities (useful for `apt/chown/su` in sandbox)\n  - `privileged`: full container privilege (`--privileged`), debugging only\n- `sandbox.cap_add` appends `--cap-add` entries for `hardened` and `standard`.\n- If `mode: \"all\"` and Docker is unavailable:\n  - `require_runtime: false` -\u003e fallback to host with warning.\n  - `require_runtime: true` -\u003e command fails fast.\n- Optional hardening:\n  - `~/.microclaw/sandbox-mount-allowlist.txt` for sandbox mount roots.\n  - `~/.microclaw/sandbox-path-allowlist.txt` for file tool path roots.\n\nWorking directory guidance:\n- `bash` runs inside the current chat working directory under its `tmp/` subdirectory.\n- Prefer relative paths or paths under the current chat working directory instead of absolute `/tmp/...`.\n- If a command fails with `command not found`, install the dependency on the host or use a sandbox image that includes it.\n\n### Supported `llm_provider` values\n\n`openai`, `openai-codex`, `openrouter`, `anthropic`, `ollama`, `google`, `alibaba`, `aliyun-bailian`, `nvidia`, `deepseek`, `moonshot`, `mistral`, `azure`, `bedrock`, `zhipu`, `minimax`, `cohere`, `tencent`, `xai`, `huggingface`, `together`, `custom`.\n\n## Platform behavior\n\n- Telegram private chats: respond to every message.\n- 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.\n- Discord DMs: respond to every message.\n- Discord server channels: respond on @mention; optionally constrained by `discord_allowed_channels`.\n- Slack DMs: respond to every message.\n- Slack channels: respond on @mention; optionally constrained by `allowed_channels`.\n- Feishu/Lark DMs (p2p): respond to every message.\n- Feishu/Lark groups: respond on @mention; optionally constrained by `allowed_chats`.\n- 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.\n- IRC private messages: respond to every message.\n- IRC channels: by default respond on mention; configurable via `channels.irc.mention_required`.\n- Group/server/channel slash commands are mention-gated by default; set `allow_group_slash_without_mention: true` to restore permissive behavior.\n\n**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.\n\n## Multi-chat permission model\n\nTool calls are authorized against the current chat:\n\n- Non-control chats can only operate on their own `chat_id`\n- Control chats (`control_chat_ids`) can operate across chats\n- `write_memory` with `scope: \"global\"` is restricted to control chats\n\nAffected tools include `send_message`, scheduling tools, `export_chat`, `todo_*`, and chat-scoped memory operations.\n\n## Usage examples\n\n**Web search:**\n```\nYou: Search the web for the latest Rust release notes\nBot: [searches DuckDuckGo, returns top results with links]\n```\n\n**Web fetch:**\n```\nYou: Fetch https://example.com and summarize it\nBot: [fetches page, strips HTML, summarizes content]\n```\n\n**Scheduling:**\n```\nYou: Every morning at 9am, check the weather in Tokyo and send me a summary\nBot: Task #1 scheduled. Next run: 2025-06-15T09:00:00+00:00\n\n[Next morning at 9am, bot automatically sends weather summary]\n```\n\n**Mid-conversation messaging:**\n```\nYou: Analyze all log files in /var/log and give me a security report\nBot: [sends \"Scanning log files...\" as progress update]\nBot: [sends \"Found 3 suspicious entries, analyzing...\" as progress update]\nBot: [sends final security report]\n```\n\n**Coding help:**\n```\nYou: Find all TODO comments in this project and fix them\nBot: [greps for TODOs, reads files, edits them, reports what was done]\n```\n\n**Memory:**\n```\nYou: Remember that the production database is on port 5433\nBot: Saved to chat memory.\n\n[Three days later]\nYou: What port is the prod database on?\nBot: Port 5433.\n```\n\n## Architecture\n\n```\ncrates/\n    microclaw-core/      # Shared error/types/text modules\n    microclaw-storage/   # SQLite DB + memory domain + usage reporting\n    microclaw-tools/     # Tool runtime primitives + sandbox + helper engines\n    microclaw-channels/  # Channel abstractions and routing boundary\n    microclaw-app/       # App-level support modules (logging, builtin skills, transcribe)\n\nsrc/\n    main.rs              # CLI entry point\n    runtime.rs           # Runtime bootstrap + adapter startup\n    agent_engine.rs      # Channel-agnostic agent loop\n    llm.rs               # Provider abstraction (Anthropic/OpenAI-compatible/Codex)\n    channels/*.rs        # Concrete channel adapters (Telegram/Discord/Slack/Feishu/IRC)\n    tools/*.rs           # Built-in tool implementations + registry assembly\n    scheduler.rs         # Background scheduler and reflector loop\n    web.rs               # Web API + stream endpoints\n```\n\nKey design decisions:\n- **Session resume** persists full message history (including tool blocks) in SQLite; context compaction summarizes old messages to stay within limits\n- **Provider abstraction** with native Anthropic + OpenAI-compatible endpoints\n- **SQLite with WAL mode** for concurrent read/write from async context\n- **Exponential backoff** on 429 rate limits (3 retries)\n- **Message splitting** for long channel responses\n- **`Arc\u003cDatabase\u003e`** shared across tools and scheduler for thread-safe DB access\n- **Continuous typing indicator** via a spawned task that sends typing action every 4 seconds\n\n## Adding a New Platform Adapter\n\nMicroClaw's core loop is channel-agnostic. A new platform integration should mainly be an adapter layer:\n\n1. Implement inbound mapping from platform events into canonical chat inputs (`chat_id`, sender, chat type, content blocks).\n2. Reuse the shared `process_with_agent` flow instead of creating a platform-specific agent loop.\n3. Implement outbound delivery for text and attachment responses (including platform-specific length limits).\n4. Define mention/reply trigger rules for group/server contexts.\n5. Preserve session key stability so resume/compaction/memory continue to work across restarts.\n6. Apply existing authorization and safety boundaries (`control_chat_ids`, tool constraints, path guard).\n7. Add adapter-specific integration tests under `TEST.md` patterns (DM/private, group/server mention, `/reset`, limits, failures).\n\n## Observability (Langfuse)\n\nMicroClaw supports OpenTelemetry (OTLP)-based observability and provides first-class integration with [Langfuse](https://langfuse.com/). You can trace complete agent runs (`agent_run`), inspect `llm_generation` and `tool_execution` spans, and monitor token usage.\n\n### 5-minute quick start (first-time users)\n\n1. **Deploy Langfuse**\n   - **Cloud**: use `https://cloud.langfuse.com`\n   - **Self-hosted**: follow the official Langfuse self-hosting guide and make sure the UI is reachable (for example `http://127.0.0.1:3000`)\n2. **Create a Langfuse project** and copy:\n   - `langfuse_public_key` (`pk-lf-...`)\n   - `langfuse_secret_key` (`sk-lf-...`)\n3. **Configure MicroClaw** in `microclaw.config.yaml`\n4. **Restart MicroClaw**\n5. **Send one test message** in Web/Telegram/Discord and open Langfuse Traces\n\n### Recommended config\n\n```yaml\nobservability:\n  service_name: \"microclaw-agent\"\n  otlp_tracing_enabled: true\n  langfuse_host: \"https://cloud.langfuse.com\" # or \"http://127.0.0.1:3000\" for self-hosted\n  langfuse_public_key: \"pk-lf-...\"\n  langfuse_secret_key: \"sk-lf-...\"\n  otlp_tracing_max_queue_size: 8192\n  otlp_tracing_max_export_batch_size: 512\n  otlp_tracing_scheduled_delay_ms: 5000\n```\n\n### Verify it is working\n\n- Start MicroClaw with debug logs:\n\n```sh\nRUST_LOG=info,microclaw_observability=debug,opentelemetry_sdk=info microclaw start\n```\n\n- Look for:\n  - `otlp trace exporter initialized`\n  - `trace span submitted to otel sdk`\n- In Langfuse, verify:\n  - Trace name: `agent_run`\n  - Child spans: `llm_generation`, `tool_execution`\n  - Token usage fields are non-zero after real model output\n\n### Common pitfalls (read this before troubleshooting)\n\n- **Wrong `langfuse_host` value**\n  - Use only host root like `http://127.0.0.1:3000`\n  - Do not use UI path like `/project/\u003cid\u003e/traces`\n  - Do not append `/api/public/otel/v1/traces`\n- **Proxy intercepts local Langfuse traffic**\n  - If logs show proxy intercepting local URL, set:\n\n```sh\nexport NO_PROXY=127.0.0.1,localhost,\u003cyour-langfuse-host\u003e\nexport no_proxy=127.0.0.1,localhost,\u003cyour-langfuse-host\u003e\n```\n\n- **Docker networking confusion**\n  - If MicroClaw runs in container, `127.0.0.1` points to that container, not your host\n  - Use a container-reachable hostname (for example `http://langfuse-web:3000`)\n- **No traces after config change**\n  - Restart MicroClaw after editing config\n  - Send a fresh test request\n- **Too noisy OpenTelemetry timer debug logs**\n  - Raise SDK log level: `opentelemetry_sdk=info`\n- **Usage fields look incorrect in older runs**\n  - Old traces are not backfilled; validate with new runs after upgrade\n\n## Documentation\n\n| File | Description |\n|------|-------------|\n| [README.md](README.md) | This file -- overview, setup, usage |\n| [DEVELOP.md](DEVELOP.md) | Developer guide -- architecture, adding tools, debugging |\n| [TEST.md](TEST.md) | Manual testing guide for all features |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution workflow and required local checks |\n| [SECURITY.md](SECURITY.md) | Vulnerability reporting and supported version policy |\n| [SUPPORT.md](SUPPORT.md) | Operator support and compatibility expectations |\n| [CHANGELOG.md](CHANGELOG.md) | Release-oriented change log |\n| [docs/operations/acp-stdio.md](docs/operations/acp-stdio.md) | ACP stdio mode overview and verification steps |\n| [docs/operations/http-hook-trigger.md](docs/operations/http-hook-trigger.md) | Webhook and async streaming trigger behavior |\n| [docs/releases/release-policy.md](docs/releases/release-policy.md) | Release targets, gates, and rollback standard |\n| [CLAUDE.md](CLAUDE.md) | Project context for AI coding assistants |\n| [AGENTS.md](AGENTS.md) | Agent-friendly project reference |\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=microclaw/microclaw\u0026type=Date)](https://star-history.com/#microclaw/microclaw\u0026Date)\n\n## Contributors\n\nThanks to everyone who has contributed to this project.\n\n[![Contributors](https://contrib.rocks/image?repo=microclaw/microclaw)](https://github.com/microclaw/microclaw/graphs/contributors)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicroclaw%2Fmicroclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicroclaw%2Fmicroclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicroclaw%2Fmicroclaw/lists"}