Getting Started

Use this guide to connect an ESP32 board from this repository to an existing OpenClaw gateway.

What You Need

OpenClaw installed and openclaw available on PATH
An OpenClaw gateway the board can reach
ESP-IDF 5.x
An ESP32 board with Wi-Fi
A serial connection or board-specific flashing path, depending on the example

Commands below assume the default OpenClaw install. If you use a named profile, add --profile <profile> to the openclaw commands.

Choose An Example

ESP32 Wi-Fi Node Example: Generic ESP32 node with Wi-Fi, GPIO, and ADC commands.
ESP-BOX-3 Display Example: ESP-BOX-3 node with Wi-Fi and display commands for the built-in screen.

Prepare The Gateway

If the board will connect over Wi-Fi to a gateway running on another machine, set gateway.bind to lan first. The default loopback bind is only reachable from the gateway host itself.

Before pairing a board, set gateway.nodes.allowCommands for the example you are using. Each example README lists the commands to allow.

openclaw config set gateway.bind lan
openclaw config set gateway.nodes.allowCommands '<json-array-from-example>' --strict-json
openclaw gateway restart
openclaw gateway status --probe --json

If the gateway stays on loopback, the board cannot reach it over Wi-Fi. If the gateway does not allow the example's commands, the node can connect and still show commands: [].

Build And Flash

Use the commands from the example README for the board you are using. The general flow is:

. ~/esp-idf/export.sh
cd /path/to/example
idf.py set-target <target>
idf.py build
idf.py -p <serial-port> flash monitor

Pair The Board With The Gateway

Use a setup code for the first connection, or one of the other explicit auth commands described below.

Generate one on the gateway host:

openclaw qr \
  --url ws://<gateway-host-ip>:<gateway-port> \
  --setup-code-only

The command prints a single setup code:

<setup-code>

Sample setup code:

eyJ1cmwiOiJ3czovLzE5Mi4xNjguMS4xMDoxODc4OSIsImJvb3RzdHJhcFRva2VuIjoib2NfYm9vdHN0cmFwX2V4YW1wbGVfdG9rZW4ifQ

If the installed gateway already resolves the correct LAN URL, you can omit --url.

After flashing, open the serial console for the board and use the REPL:

openclaw> status
openclaw> wifi set <ssid> <passphrase>
openclaw> gateway setup-code <setup-code>
openclaw> status

Each example README calls out the console path for that board and the commands it exposes after pairing.

Use wifi set <ssid> for an open network, or wifi set <ssid> <passphrase> for a secured network.
The setup code contains a short-lived bootstrapToken, not the gateway's shared token. gateway setup-code <setup-code> requests one explicit connect
attempt.
If Wi-Fi is still coming up, the REPL waits for the board to obtain an
IP before it submits that attempt.
After a successful hello-ok, the node stores the issued { gateway_uri, device_token } reconnect session and uses it on later gateway connect attempts.

Other first-connect options from the REPL are:

gateway token <ws://host:port> <token>
gateway password <ws://host:port> <password>
gateway no-auth <ws://host:port>

gateway connect is only for reconnecting with a saved session that already exists on the board.

Check The Node From The Gateway

openclaw nodes status --json
openclaw nodes invoke --node <node-id> --command device.info --json

Then run one of the commands from the README for the board you are using.

If pairing did not complete as expected, use Troubleshooting.

3.8 KiB Raw Blame History