Skip to content
OpenClaw Docs

Getting Started

Welcome to OpenClaw! This guide will take you from unboxing to a working AI agent in under 5 minutes.

What You Need

Section titled “What You Need”
  • An ESP-Claw compatible board (ESP32-S3 or ESP32-C3)
  • A USB-C data cable (not charge-only)
  • Chrome or Edge browser (version 89+)
  • A Wi-Fi network
  • An AI API key (Claude, OpenAI, or compatible)

Step 1: Flash Firmware

Section titled “Step 1: Flash Firmware”

The fastest way to get started is using our browser-based flasher. No toolchain installation required.

  1. Go to the Install page
  2. Select your board type
  3. Click Connect & Flash
  4. Select your USB device in the browser popup
  5. Wait for the flash to complete (~30 seconds)

Step 2: Connect to Wi-Fi

Section titled “Step 2: Connect to Wi-Fi”

After flashing, your board will create a Wi-Fi hotspot:

  1. On your phone or computer, connect to ESPClaw-XXXX
  2. A configuration page will open automatically
  3. Enter your home Wi-Fi network name and password
  4. Click Save

The captive portal should open automatically. If not, open http://192.168.4.1 in your browser.

Step 3: Set Up Communication Channel

Section titled “Step 3: Set Up Communication Channel”

Configure how you’ll talk to your AI agent:

Section titled “Telegram (Recommended)”
  1. Message @BotFather on Telegram
  2. Send /newbot and follow the instructions
  3. Copy the API token
  4. Enter it in the ESP-Claw configuration page

Discord

Section titled “Discord”
  1. Create a bot at the Discord Developer Portal
  2. Copy the bot token
  3. Enter it in the configuration page

MQTT

Section titled “MQTT”
  1. Set your MQTT broker address and credentials in the configuration page

Step 4: Talk to Your AI

Section titled “Step 4: Talk to Your AI”

Send a message to your bot — you should get a response within seconds!

Try these:

  • “Hello, what can you do?”
  • “What’s the temperature?” (if you have a sensor connected)
  • “Turn on the LED” (if you have an LED on GPIO 2)

🎉 Congratulations! Your $5 AI agent is up and running.

Understanding What Just Happened

Section titled “Understanding What Just Happened”

Let’s break down what’s running on your ESP32 right now:

  1. The firmware loaded into flash memory manages Wi-Fi, the serial console, and the communication channel (Telegram/Discord/MQTT).

  2. SOUL.md — a Markdown file stored on the device — tells the AI who it is and what it can do. The default personality is a helpful home assistant, but you can change it to anything.

  3. When you send a message, the firmware packages it with the SOUL.md context and sends it to your AI provider (Claude, OpenAI). The AI responds, potentially including tool calls (like “read the temperature sensor”). The firmware executes those tool calls and returns the results to the AI, which then generates the final response.

  4. MEMORY.md on the device stores notes the AI wants to remember across conversations. Over time, your agent learns your preferences and routines.

The entire process takes about 1-2 seconds for a simple query, or 2-4 seconds for queries that involve tool calls.

Common First Experiments

Section titled “Common First Experiments”

Once your basic setup is working, try these to explore the agent’s capabilities:

Test tool calling (requires DHT22 on GPIO 3):

  • “What’s the temperature and humidity?”
  • “Is it comfortable to sleep tonight?”
  • “Has the temperature changed since you last checked?”

Test memory (works without any sensors):

  • “Remember that I prefer the room at 23 degrees”
  • “What do you know about my preferences?”

Test multi-step reasoning:

  • “If the temperature is above 26 degrees, what should we do?” (The AI will read the sensor, then reason about the answer)

Test personality:

  • Try editing SOUL.md through the web config interface
  • Change the personality to a British butler, a pirate, or a Zen monk
  • See how the same questions get very different answers

Troubleshooting First Setup

Section titled “Troubleshooting First Setup”

Bot responds but says “I don’t have any tools”: Your SOUL.md might not list the available tools, or no peripherals are connected. The AI knows about tools from the SOUL.md descriptions — if you haven’t mentioned dht_read in SOUL.md, the AI won’t try to use it even if the sensor is connected.

Responses are very slow (5+ seconds): Check your Wi-Fi signal strength. The ESP32 should be within reasonable range of your router. Also check if your AI API provider is experiencing high latency — try a different model (Claude Haiku is the fastest).

Bot gives incorrect sensor readings: Sensors need a few seconds to stabilize after power-on. If you just plugged in a DHT22, wait 10-15 seconds before the first read. Also check wiring — the most common issue is a missing pull-up resistor on the data line.

Bot stops responding after a while: The AI API key might have run out of credit. Check your provider’s dashboard. Also check if the ESP32 has disconnected from Wi-Fi (the LED will start blinking instead of staying solid).

Next Steps

Section titled “Next Steps”

Now that your agent is running, explore these areas: