English | 中文 | 日本語

The world's first AI assistant(OpenClaw) on a $5 chip. No Linux. No Node.js. Just pure C

MimiClaw turns a tiny ESP32-S3 board into a personal AI assistant. Plug it into USB power, connect to WiFi, and talk to it through Telegram or a Feishu bot — it handles any task you throw at it and evolves over time with local memory — all on a chip the size of a thumb.

• Tiny — No Linux, no Node.js, no bloat — just pure C
• Handy — Message it from Telegram or Feishu, it handles the rest
• Loyal — Learns from memory, remembers across reboots
• Energetic — USB power, 0.5 W, runs 24/7
• Lovable — One ESP32-S3 board, $5, nothing else

You send a message on Telegram, Feishu, or a LAN WebSocket client. The ESP32-S3 picks it up over WiFi, feeds it into an agent loop — the LLM thinks, calls tools, reads memory — and sends the reply back. Supports both Anthropic (Claude) and OpenAI (GPT) as providers, switchable at runtime. Everything runs on a single $5 chip with all your data stored locally on flash.

The default quick start uses ESP32-S3-DevKitC-1 with no external peripherals attached. Plug into the correct USB port, configure WiFi/Bot/API key, flash the firmware, and verify from Telegram or Feishu.

1. Prepare an ESP32-S3-DevKitC-1 and plug into the port labeled USB (not COM).
2. Install ESP-IDF and clone this repository.
3. Copy main/mimi_secrets.h.example to main/mimi_secrets.h and fill in WiFi, bot, and API key.
4. Build and flash the firmware.
5. Open Telegram or Feishu and send /start or hello to test the full agent path.

• An ESP32-S3-DevKitC-1 (default quick-start board; use a variant with 16 MB flash and 8 MB PSRAM)
• A USB Type-C cable
• A Telegram bot token, or a Feishu self-built app with bot capability and event subscription
• An Anthropic API key — from console.anthropic.com, or an OpenAI API key — from platform.openai.com
• No microphone, speaker, or display is required for the default quick start

# You need ESP-IDF v5.5+ installed first:
# https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/

git clone https://github.com/memovai/mimiclaw.git
cd mimiclaw

idf.py set-target esp32s3

sudo apt-get update
sudo apt-get install -y git wget flex bison gperf python3 python3-pip python3-venv \
  cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

./scripts/setup_idf_ubuntu.sh
./scripts/build_ubuntu.sh

xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

./scripts/setup_idf_macos.sh
./scripts/build_macos.sh

MimiClaw uses a two-layer config system: build-time defaults in mimi_secrets.h, with runtime overrides via the serial CLI. CLI values are stored in NVS flash and take priority over build-time values.

cp main/mimi_secrets.h.example main/mimi_secrets.h

Edit main/mimi_secrets.h:

#define MIMI_SECRET_WIFI_SSID       "YourWiFiName"
#define MIMI_SECRET_WIFI_PASS       "YourWiFiPassword"
#define MIMI_SECRET_TG_TOKEN        ""              // leave empty if you only use Feishu
#define MIMI_SECRET_FEISHU_APP_ID   ""
#define MIMI_SECRET_FEISHU_APP_SECRET ""
#define MIMI_SECRET_FEISHU_VERIFY_TOKEN ""
#define MIMI_SECRET_FEISHU_ENCRYPT_KEY ""
#define MIMI_SECRET_API_KEY         "sk-ant-api03-xxxxx"
#define MIMI_SECRET_MODEL_PROVIDER  "anthropic"     // "anthropic" or "openai"
#define MIMI_SECRET_SEARCH_KEY      ""              // optional: Brave Search API key
#define MIMI_SECRET_PROXY_HOST      ""              // optional: e.g. "10.0.0.1"
#define MIMI_SECRET_PROXY_PORT      ""              // optional: e.g. "7897"

Then build and flash:

# Clean build (required after any mimi_secrets.h change)
idf.py fullclean && idf.py build

# Find your serial port
ls /dev/cu.usb*          # macOS
ls /dev/ttyACM*          # Linux

# Flash and monitor (replace PORT with your port)
# USB adapter: likely /dev/cu.usbmodem11401 (macOS) or /dev/ttyACM0 (Linux)
idf.py -p PORT flash monitor

Recommended first check:

• Telegram: send /start to confirm connectivity
• Feishu: send hello to confirm callback ingress and outbound messaging
• Send hello to test the full agent path

Important: Plug into the correct USB port! Most ESP32-S3 boards have two USB-C ports. You must use the one labeled USB (native USB Serial/JTAG), not the one labeled COM (external UART bridge). Plugging into the wrong port will cause flash/monitor failures.

Quick-start reference board: the default path in this README assumes ESP32-S3-DevKitC-1. For the first boot, keep the board in its minimum form: USB cable only, no microphone, no speaker, no display.

Show reference photo

This branch defaults to a no external voice gateway build. Text chat works without running tools/voice_gateway.py.

1. Fill these build-time secrets in main/mimi_secrets.h:

For a normal Feishu Bot setup, these are the fields that matter:

• Required: App ID
• Required: App Secret
• Recommended: Receive Mode
• Strongly recommended in webhook mode: Verify Token
• Optional in webhook mode: Encrypt Key
• Usually leave as-is: Open API Base

#define MIMI_SECRET_FEISHU_APP_ID        "cli_xxx"              // required: Feishu App ID
#define MIMI_SECRET_FEISHU_APP_SECRET    "xxx"                  // required: Feishu App Secret
#define MIMI_SECRET_FEISHU_RECEIVE_MODE  "websocket"            // recommended: board-side long connection; or use webhook
#define MIMI_SECRET_FEISHU_VERIFY_TOKEN  "mimiclaw-feishu"      // recommended in webhook mode
#define MIMI_SECRET_FEISHU_ENCRYPT_KEY   ""                     // only needed for encrypted webhook callbacks
#define MIMI_SECRET_FEISHU_OPEN_API_BASE "https://open.feishu.cn" // usually keep default; override only for local stub validation

• App ID and App Secret are mandatory for the bot to work
• MIMI_SECRET_FEISHU_RECEIVE_MODE supports websocket and webhook
• websocket is the recommended default: the board opens the long connection itself, so you do not need a public callback URL
• only webhook mode needs Verify Token, Encrypt Key, /feishu/events, and a public callback path
• Verify Token is not strictly required by Feishu, but this project strongly recommends setting it in webhook mode
• leave Encrypt Key empty until plaintext webhook callbacks are working

2. In the Feishu Open Platform:

At minimum, fill in these items:

• create a self-built app
• enable bot capability
• subscribe to event im.message.receive_v1
• if receive mode is websocket:
  • no Request URL is required
  • no public callback address is required
• if receive mode is webhook:
  • set request URL to https://<public-address>/feishu/events
  • set Verify Token to the same value as MIMI_SECRET_FEISHU_VERIFY_TOKEN
  • leave Encrypt Key empty for plaintext callbacks, or set it to match MIMI_SECRET_FEISHU_ENCRYPT_KEY
• keep MIMI_SECRET_FEISHU_OPEN_API_BASE on the official host unless you are using the local OpenAPI stub for validation

This firmware now supports encrypted Feishu event payloads:

• this applies only to webhook
• if Encrypt Key is empty, callbacks are handled as plaintext events
• if Encrypt Key is configured, the firmware validates X-Lark-Signature and decrypts the encrypt field
• keeping Verify Token enabled is still recommended for an extra source check on URL verification and normal events

Recommended minimum setup:

1. Start with App ID and App Secret

2. Set Receive Mode to websocket

3. Only switch to webhook if you explicitly need callback mode

4. Enable Encrypt Key only after webhook text ingress is stable

5. Choose the ingress mode you want:

• websocket:
  • the device opens a long connection to Feishu itself
  • no public callback is required
  • the truly required fields are just App ID and App Secret
• webhook:
  • callback path is fixed at /feishu/events
  • the shared HTTP service listens on port 18789
  • if your board is not public, add reverse proxy / port forwarding / tunnel to http://<device-lan-ip>:18789/feishu/events

4. Smoke test after flashing:

• watch serial logs
• in websocket mode, look for Feishu WebSocket long connection enabled and Feishu WS connected
• in webhook mode, look for Feishu callback registered at /feishu/events
• if Encrypt Key is enabled in webhook mode, confirm both URL verification and event delivery succeed in the Feishu console
• send hello to the bot in Feishu
• expect a text reply from MimiClaw

4.1 Local replay without the Feishu console

If you only want to validate the device-side /feishu/events path, run this from your dev machine:

./tools/run_feishu_replay.sh --scenario all --verify-token mimiclaw-feishu

Common examples:

# replay plaintext text / duplicate / image / file / audio / sticker callbacks
./tools/run_feishu_replay.sh --scenario all --verify-token mimiclaw-feishu

# replay encrypted duplicate delivery
./tools/run_feishu_replay.sh \
  --scenario duplicate \
  --verify-token mimiclaw-feishu \
  --encrypt-key your_encrypt_key \
  --encrypted

# print request and response bodies for debugging
./tools/run_feishu_replay.sh --scenario text --show-body

Notes:

• the script targets http://127.0.0.1:18789/feishu/events by default
• the duplicate scenario sends the same event_id/message_id twice to verify firmware deduplication
• under the default configuration, image/file/audio/sticker only validate the callback -> summary text -> Agent downgrade path

If you already enabled MIMI_FEISHU_GATEWAY_MEDIA_ENABLED=1, you can also exercise the real image/file download branch with a local OpenAPI stub.

1. Point the device to your dev machine from the serial CLI:

mimi> set_feishu_open_api_base http://<your-host-ip>:19091

2. Start the local Feishu OpenAPI stub:

python3 tools/feishu_openapi_stub.py --host 0.0.0.0 --port 19091

3. In another terminal, start voice_gateway.py

4. Run validation with gateway expectations:

./tools/run_feishu_validate.sh \
  --scenario image \
  --verify-token mimiclaw-feishu \
  --log-file ./logs/monitor.log \
  --expect-media-mode gateway

Notes:

• the stub includes image_key=img_replay_demo and file_key=file_replay_demo
• --expect-media-mode gateway requires gateway_parse from to appear in logs
• run mimi> clear_feishu_open_api_base to switch the device back to the official Feishu host

If you already save serial logs to a file, you can also run replay + validation together:

./tools/run_feishu_validate.sh \
  --scenario all \
  --verify-token mimiclaw-feishu \
  --log-file ./logs/monitor.log

The validator checks:

• HTTP responses for each replayed callback
• the returned challenge for url_verification
• whether duplicate produces Skip duplicate Feishu event in logs
• whether text/media scenarios produce the expected ingress log markers

If you want to run serial monitor + replay validation + log capture in one shot:

./tools/run_feishu_validate_live.sh \
  --port /dev/ttyACM0 \
  --scenario all \
  --verify-token mimiclaw-feishu

Notes:

• this script starts idf.py -p PORT monitor in the background
• monitor output is written to logs/feishu-validate-*.log
• when validation finishes, the monitor process is stopped and the log file is kept for review

Current limits:

• text messages go to the Agent as-is
• by default, image / file / audio / sticker / other non-text Feishu messages are downgraded into summary text before entering the Agent
• if you enable MIMI_FEISHU_GATEWAY_MEDIA_ENABLED=1 and run voice_gateway.py, Feishu image/file messages are downloaded and sent through real vision / doc parsing; audio/sticker/other still stay in summary mode
• outbound Feishu delivery uses chat_id
• repeated Feishu deliveries are lightly deduplicated by event_id/message_id before entering the Agent

This is an optional extension. The default no-gateway build does not depend on it.

Not required for the default quick start. If you only want to get the board online, skip this section for now.

Start the local gateway (STT + image analysis endpoint):

python3 tools/voice_gateway.py \
  --host 0.0.0.0 --port 8090 --model small --device cpu \
  --vision-enabled

• STT endpoint: http://<your-host-ip>:8091/stt_upload
• Vision endpoint: http://<your-host-ip>:8091/vision_upload
• Document endpoint: http://<your-host-ip>:8091/doc_upload
• By default, gateway tries loading API defaults from main/mimi_secrets.h; you can override via --vision-endpoint/--vision-api-key/--vision-model

To actually enable these media extensions in firmware, also set these in main/mimi_config.h and rebuild:

#define MIMI_TELEGRAM_GATEWAY_MEDIA_ENABLED 1
#define MIMI_FEISHU_GATEWAY_MEDIA_ENABLED   1

Both defaults are 0, which keeps the no-gateway text + summary behavior. After enabling them:

• Telegram regains real STT / vision / doc parsing for voice / photos / documents
• Feishu enables real download + vision / doc parsing for image/file, while other media types still fall back to summaries

After gateway is running, execute:

./tools/run_doc_regression.sh --basic
./tools/run_doc_regression.sh --office

Or run with custom arguments:

python3 tools/doc_regression.py \
  --manifest tools/doc_regression_manifest.example.json \
  --base-url http://127.0.0.1:8091

The script calls /doc_upload and validates format, extracted text length, keywords, parser prefix, and latency budget. tools/doc_regression_manifest.office.example.json includes a real xlsx sample and an optional xls case (food_legacy.xls) which is skipped when missing.

Connect via serial to configure or debug. Config commands let you change settings without recompiling — just plug in a USB cable anywhere.

Runtime config (saved to NVS, overrides build-time defaults):

mimi> wifi_set MySSID MyPassword   # change WiFi network
mimi> set_tg_token 123456:ABC...   # change Telegram bot token
mimi> set_feishu_app cli_xxx secret_xxx   # set Feishu app_id / app_secret
mimi> set_feishu_receive_mode websocket   # switch to board-side long connection
mimi> set_feishu_verify_token token_xxx   # set Feishu Verify Token
mimi> set_feishu_encrypt_key key_xxx      # set Feishu Encrypt Key
mimi> set_feishu_open_api_base http://127.0.0.1:19091  # override Feishu OpenAPI base (useful for local validation)
mimi> set_api_key sk-ant-api03-... # change API key (Anthropic or OpenAI)
mimi> set_model_provider openai    # switch provider (anthropic|openai)
mimi> set_model gpt-4o             # change LLM model
mimi> set_proxy 127.0.0.1 7897  # set HTTP proxy
mimi> clear_proxy                  # remove proxy
mimi> set_search_key BSA...        # set Brave Search API key
mimi> config_show                  # show all config (masked)
mimi> config_reset                 # clear NVS, revert to build-time defaults

Note:

• Feishu app_id/app_secret/receive_mode/verify_token/encrypt_key/open_api_base can now be updated via CLI
• NVS-stored Feishu config overrides build-time defaults

Debug & maintenance:

mimi> wifi_status              # am I connected?
mimi> memory_read              # see what the bot remembers
mimi> memory_write "content"   # write to MEMORY.md
mimi> heap_info                # how much RAM is free?
mimi> agent_stats              # agent success rate / latency / failures
mimi> heartbeat_status         # heartbeat counters / last run
mimi> heartbeat_now            # trigger heartbeat immediately
mimi> cron_status              # cron schedule + counters
mimi> cron_set 30 "task..."    # run every 30 min
mimi> cron_now                 # trigger cron immediately
mimi> cron_clear               # clear cron schedule
mimi> session_list             # list all chat sessions
mimi> session_clear 12345      # wipe a conversation
mimi> heartbeat_trigger           # manually trigger a heartbeat check
mimi> cron_start                  # start cron scheduler now
mimi> restart                     # reboot

Most ESP32-S3 dev boards expose two USB-C ports:

REPL requires the UART (COM) port. The USB (JTAG) port does not support interactive REPL input.

# Flash via USB (JTAG) port
idf.py -p /dev/cu.usbmodem11401 flash

# Open REPL via UART (COM) port
idf.py -p /dev/cu.usbserial-110 monitor
# or use any serial terminal: screen, minicom, PuTTY at 115200 baud

MimiClaw stores everything as plain text files you can read and edit:

MimiClaw supports tool calling for both Anthropic and OpenAI — the LLM can call tools during a conversation and loop until the task is done (ReAct pattern).

To enable web search, set a Brave Search API key via MIMI_SECRET_SEARCH_KEY in mimi_secrets.h.

MimiClaw has a built-in cron scheduler that lets the AI schedule its own tasks. The LLM can create recurring jobs ("every N seconds") or one-shot jobs ("at unix timestamp") via the cron_add tool. When a job fires, its message is injected into the agent loop — so the AI wakes up, processes the task, and responds.

Jobs are persisted to SPIFFS (cron.json) and survive reboots. Example use cases: daily summaries, periodic reminders, scheduled check-ins.

The heartbeat service periodically reads HEARTBEAT.md from SPIFFS and checks for actionable tasks. If uncompleted items are found (anything that isn't an empty line, a header, or a checked - [x] box), it sends a prompt to the agent loop so the AI can act on them autonomously.

This turns MimiClaw into a proactive assistant — write tasks to HEARTBEAT.md and the bot will pick them up on the next heartbeat cycle (default: every 30 minutes).

• WebSocket gateway on port 18789 — connect from your LAN with any WebSocket client
• Feishu Bot — supports both board-side WebSocket long connection and /feishu/events webhook ingress; text passthrough and summary fallback by default, with optional real gateway parsing for image/file
• OTA updates — flash new firmware over WiFi, no USB needed
• Dual-core — network I/O and AI processing run on separate CPU cores
• HTTP proxy — CONNECT tunnel support for restricted networks
• Tool use — ReAct agent loop with Anthropic tool use protocol
• Telegram media handling — in the default no-gateway mode, voice/photos/documents fall back to media summaries; if you enable MIMI_TELEGRAM_GATEWAY_MEDIA_ENABLED=1 and run voice_gateway.py, Telegram can use real STT / vision / doc parsing again
• Feishu media handling — in the default no-gateway mode, media falls back to summaries; if you enable MIMI_FEISHU_GATEWAY_MEDIA_ENABLED=1 and run voice_gateway.py, Feishu image/file can use real download + vision / doc parsing

• Inbound security: Telegram allowlist (allow_from) + WebSocket auth token
• File tool safety boundaries: write default-limited to /spiffs/memory/
• Reliability: retries/backoff for LLM and outbound delivery; drop status first, preserve final replies
• Budget guards: tool iterations, context size, tool output size, end-to-end timeout caps
• Memory governance: unify daily memory path and add dedicated memory write tools
• Observability: run_id, stage-level latency logs, agent_stats diagnostics command

Detailed tracking: docs/TODO.md.

• Multi-provider — supports both Anthropic (Claude) and OpenAI (GPT), switchable at runtime
• Cron scheduler — the AI can schedule its own recurring and one-shot tasks, persisted across reboots
• Heartbeat — periodically checks a task file and prompts the AI to act autonomously
• Tool use — ReAct agent loop with tool calling for both providers

Technical details live in the docs/ folder:

• docs/ARCHITECTURE.md — system design, module map, task layout, memory budget, protocols, flash partitions
• docs/TODO.md — feature gap tracker and roadmap

Please read CONTRIBUTING.md before opening issues or pull requests.

Thanks to everyone who has contributed to MimiClaw.

MIT

Inspired by OpenClaw and Nanobot. MimiClaw reimplements the core AI agent architecture for embedded hardware — no Linux, no server, just a $5 chip.