Building from Source

This guide walks you through building ESP-Claw firmware from source. While most users can use the browser-based flasher, building from source gives you full control over configuration, lets you add custom tools, and is essential for contributing to the project.

Prerequisites

Before you begin, make sure you have:

• A computer running Linux, macOS, or Windows 10/11
• At least 4GB of free disk space (ESP-IDF toolchain is large)
• Python 3.8 or later installed
• Git installed
• Basic familiarity with terminal/command line

Step 1: Install ESP-IDF

ESP-Claw is built on Espressif’s ESP-IDF framework (version 5.2 or later). The installation process differs by operating system.

Linux

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

# Clone ESP-IDF
mkdir -p ~/esp
cd ~/esp
git clone -b v5.2 --recursive https://github.com/espressif/esp-idf.git

# Install the toolchain
cd esp-idf
./install.sh esp32s3,esp32c3

# Set up environment (add to your .bashrc for persistence)
. $HOME/esp/esp-idf/export.sh

macOS

# Install prerequisites via Homebrew
brew install cmake ninja dfu-util python3

# Clone ESP-IDF
mkdir -p ~/esp
cd ~/esp
git clone -b v5.2 --recursive https://github.com/espressif/esp-idf.git

# Install the toolchain
cd esp-idf
./install.sh esp32s3,esp32c3

# Set up environment (add to your .zshrc for persistence)
. $HOME/esp/esp-idf/export.sh

Windows

Download and run the ESP-IDF Tools Installer from the Espressif website. The installer handles all dependencies automatically, including Python, Git, and the cross-compilation toolchain.

After installation, use the “ESP-IDF Command Prompt” shortcut that appears in your Start menu. This terminal has all environment variables pre-configured.

Verify your installation by running:

idf.py --version

You should see output like ESP-IDF v5.2.x.

Step 2: Clone the ESP-Claw Repository

git clone https://github.com/openclaw/espclaw.git
cd espclaw

The repository structure looks like this:

espclaw/
├── main/               # Application source code
│   ├── agent.c         # AI agent core logic
│   ├── tools/          # Built-in tool implementations
│   ├── channels/       # Communication channels (Telegram, MQTT, etc.)
│   ├── platform.h      # Hardware abstraction layer
│   └── main.c          # Entry point
├── components/          # Reusable ESP-IDF components
├── data/                # SPIFFS filesystem (SOUL.md, config)
├── CMakeLists.txt       # Build system configuration
├── sdkconfig.defaults   # Default SDK configuration
└── partitions.csv       # Flash partition table

Step 3: Configure the Build Target

Set the target chip for your board:

# For ESP32-S3 (recommended)
idf.py set-target esp32s3

# For ESP32-C3 (MimiClaw)
idf.py set-target esp32c3

# For ESP32-C6
idf.py set-target esp32c6

This configures the toolchain, linker scripts, and default settings for your specific chip.

Step 4: Configure Options (Optional)

Open the interactive configuration menu to customize build options:

idf.py menuconfig

Key configuration options under “ESP-Claw Configuration”:

Option	Default	Description
AI Provider	Claude	Which AI API to use
Max Response Tokens	1024	Maximum tokens per AI response
Wi-Fi SSID	(empty)	Pre-configure Wi-Fi credentials
Enable Bluetooth	Yes	BLE support (disable to save ~50KB RAM)
Enable OTA	Yes	Over-the-air updates
Log Level	Info	Serial output verbosity
PSRAM Speed	80MHz	PSRAM clock (S3 only)

Press S to save, Q to quit.

Step 5: Build

idf.py build

The first build takes 3-10 minutes depending on your machine. Subsequent builds are faster thanks to the build cache. A successful build ends with:

Project build complete. To flash, run:
 idf.py -p (PORT) flash

The output binary is located at build/espclaw.bin. The total firmware size is displayed — MimiClaw targets under 888KB, ESP-Claw is typically around 1.8-2MB.

Step 6: Flash to Your Board

Connect your ESP32 board via USB and flash:

idf.py -p /dev/ttyUSB0 flash monitor

Replace /dev/ttyUSB0 with your actual serial port. On macOS, it’s typically /dev/cu.usbmodem* or /dev/cu.SLAB_USBtoUART. On Windows, it’s COM3 or similar.

The monitor flag opens a serial terminal after flashing, so you can see boot messages and debug output. Press Ctrl+] to exit the monitor.

Common Build Errors

“Python requirements not satisfied”: Run pip install -r $IDF_PATH/requirements.txt to install missing Python packages.

“Toolchain not found”: Make sure you’ve sourced the ESP-IDF export script: . $HOME/esp/esp-idf/export.sh

“PSRAM not detected” (ESP32-S3): Check that your board actually has PSRAM. Some cheaper S3 boards omit it. In menuconfig, disable PSRAM under Component Config if your board doesn’t have it.

“Partition table doesn’t fit”: If you’ve added many custom tools, you may need to increase the app partition size in partitions.csv. The default layout allocates 1.5MB for the application.

Building MimiClaw (ESP32-C3 Variant)

MimiClaw has a separate build profile optimized for the C3’s limited memory:

idf.py set-target esp32c3
idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.mimiclaw" build

This enables aggressive compiler optimizations (-Os), disables PSRAM support, and reduces buffer sizes to fit within 400KB SRAM.