Skip to main content

Z-Claw AI Assistant

Z-Claw is the smallest AI personal assistant you can build. It runs on the GLYPH-C3 board and lets you talk to an AI to control your home, set reminders, and more.

How it Works? (The Simple Version)​

Even though it's tiny, your GLYPH-C3 board is doing some smart work:

  1. Connection: It connects to your WiFi and listens for your messages (via Telegram or a Serial monitor).
  2. The Brain: It sends your question to an AI Brain (either running on your computer with Ollama or in the cloud).
  3. Actions: The AI doesn't just talk—it understands "tools." For example, if you say "Turn on the light," the AI tells the board to flick a switch (GPIO pin).
  4. No Lag: Because the code is written in C, it's extremely fast and uses very little power.

🧩 What You Need​

Before starting, make sure you have your hardware and software environment ready.

Hardware Required​

  • GLYPH-C3 board (The main AI device).
  • LED (For testing).
  • 220 ohm resistor (For testing).
  • Breadboard (For testing).
  • Jumper wires (For testing).

Circuit diagram​

Circuit Diagram

Software​

  • ESP-IDF v5.x: The core development tools from Espressif.
  • Git: Required to download the project files.
  • Python: Required for the build system and provisioning scripts.

Software Setup​

You have two ways to give your assistant a "brain":

  1. Ollama (Local): No cost, runs on your own computer (Recommended).
  2. API Key (Cloud): Uses a paid service like OpenRouter.

Step 1: Get the Code​

First, we need to download the Z-Claw project files from GitHub to your computer. Go to the Z-Claw GitHub Repository and copy the clone URL.

GitHub Repo

Open your terminal and run:

git clone --recursive https://github.com/zclaw-org/zclaw.git %userprofile%\ZClaw

Git Clone

Step 2: Setup YOUR ESP-IDF Environment​

To compile and upload the code, you need the ESP-IDF tools. You have two ways to do this:

Option A: ESP-IDF Terminal​

If you installed the standalone ESP-IDF 5.x tools, open the ESP-IDF 5.x PowerShell (or CMD) from your Windows Start Menu.

Once open, navigate to your project folder:

cd %userprofile%\ZClaw

Option B: VS Code Extension​

You can also use the official ESP-IDF extension for VS Code. This makes it easier to build and flash using the VS Code interface.

note

For a full guide on setting up the extension, see our ESP-IDF Setup Guide.

Step 3: Set the Target Board​

Every ESP32 chip is slightly different. We need to tell the project that we are using the esp32c3 chip (the one inside your GLYPH-C3).

Set Target

cd ZClaw
idf.py set-target esp32c3

Step 4: Configure Your AI Brain​

Before connecting your board, you need to decide which AI "Brain" to use. You will need these details for both the configuration menu below and the provisioning script in Step 7.

Prepare Your AI Details​

  • Option A: Ollama (Local AI): Install Ollama on your computer. Make sure it's running and keep your computer's IP address ready (e.g., http://192.168.1.50:11434).
  • Local Device URL: After getting the IP address, you should also have a local device URL ready that you will need to enter in the terminal manually.
  • Option B: OpenRouter (Cloud AI)/OpenAI and keep it ready.
tip

Need an API Key? Get one from OpenRouter or OpenAI by creating a new key named "zclaw".

OpenRouter Key

note

Gathering these details now will make the next steps much smoother! You'll need them again in Step 7.

Run the Configuration Menu​

Now, open the "Settings" menu to tell your board which AI to talk to:

idf.py menuconfig

Select zclaw Configuration --->.

:::

Step 5: Add Telegram Bot​

This allows you to message your assistant from your phone using the Telegram app.

note

Save your Bot Token and Chat ID; you'll need them for the provisioning script in Step 7.

1. Message @BotFather and use /newbot to get a Token.​

2. Message @userinfobot to get your Chat ID.​

Step 6: Build and Flash the Firmware​

This command compiles your C code and "burns" the logic onto the ESP32. Run this in your ESP-IDF terminal:

idf.py build flash
note

Wait for the process to hit 100% and show "Done."

Build Project

Step 7: Provision Your Credentials​

Now, save your WiFi, Telegram, and LLM details into the board's memory. Run this command in the same terminal:

"C:\Program Files\Git\bin\bash.exe" scripts/provision.sh --port YOUR_PORT_HERE

(Replace YOUR_PORT_HERE with your actual port number, e.g., COM145).

Follow the prompts to enter:

  • WiFi SSID & Password
  • LLM Provider: (e.g., openai or ollama)
  • LLM Model: (e.g., qwen2.5:0.5b)
  • Local Device URL: (e.g., http://192.168.1.50:11434)
  • Telegram Bot Token & Chat ID

Step 8: Start the Assistant (Monitor)​

Finally, run this to start the assistant and see the output in real-time:

idf.py -p YOUR_PORT_HERE monitor

Flash Board

What can I say?​

Try talking to your assistant:

  • "Remind me to water the plants at 8am daily."
  • "What is the temperature?"
  • "Turn off the lights (GPIO 2)."

Have fun with your mini AI Assistant!