WeClawBot

Install / Configure · Firmware Releases · Product Experience · 中文说明

WeClawBot is open firmware and an Agent bridge for small always-on ESP32-S3 screens. It supports the Waveshare ESP32-S3-RLCD-4.2 reflective LCD and the Zectrix Note 4 e-paper device. Both expose a 400 x 300 black-and-white canvas for persistent notes, photos, reminders, status cards, and Agent-generated dashboards.

The product has one user promise:

Put the useful thing on the little screen, quietly and reliably.

There are two ways to own that screen.

• WeClawBot Official: ordinary users flash the firmware, configure Wi-Fi, scan the WeChat QR code on the screen, and let the official WeClawBot Agent understand the message, render it, and push it back over MQTT/WSS.
• BYOA / Existing AI Assistant: advanced users choose 已有 AI 助手 in the configuration page. The screen shows a six-digit pairing code. OpenClaw, Antigravity, Hermes, WorkBuddy, Claude Code, and Codex have been verified to pair, organize information, and publish a usable screen. Other Agents or scripts that can install @openbrt/weclawbotctl and run commands can use the same protocol.

Users do not type gateway URLs, open firewall ports, or hand WeChat credentials to an Agent. The ESP32 owns Wi-Fi, WeChat login, local state, buttons, display refresh, and hardware limits. Agents own intent, layout, preview, file processing, model calls, and user-facing conversation.

Install And Configure

Open the public Web Serial console in desktop Chrome or Edge:

https://openbrt.github.io/weclawbot/web/

That single page contains both:

• firmware installation through ESP Web Tools;
• device configuration through the firmware WEC: serial protocol.

For a first flash, hold BOOT, plug in USB-C, wait for the serial port, then release BOOT. Normal upgrades do not erase the NVS area, so Wi-Fi, WeChat login, Agent mode, notes, and photos survive unless the user explicitly clears or erases the device.

After flashing:

1. Connect the device in the configuration panel.
2. Save Wi-Fi.
3. Choose 用微信连接 or 已有 AI 助手.
4. Save and reboot.

WeChat mode shows a QR code. BYOA mode shows a six-digit pairing code. Before takeover, the buttons cycle only between the two connection entries: Official <-> BYOA. After the selected takeover completes, the buttons cycle only among the three content categories: calendar -> message -> photo -> calendar. Right/down advances and left/up reverses; missing message or photo content is skipped. Cached content is not exposed while unclaimed. This behavior is identical on the Waveshare and Note 4 targets.

Pair Your AI Assistant

When the screen shows a six-digit BYOA code, tell your Agent:

Install the npm tool @openbrt/weclawbotctl in your current AI assistant environment, then bind my WeClawBot screen with pairing code 123456. Only install this npm tool; do not install any extra plugin.

The Agent should install the npm package, bind the screen, run an online doctor check, and use the MQTT profile stored at ~/.config/weclawbot/agent-mqtt.json.

Manual commands:

npm install -g @openbrt/weclawbotctl
weclawbotctl bind 123456 --name antigravity
weclawbotctl doctor --online

The stable BYOA commands are:

weclawbotctl thinking --id "$task_id" --ttl 45
weclawbotctl preview /path/to/screen-document.json
weclawbotctl screen /path/to/screen-document.json
weclawbotctl idle --id "$task_id"
weclawbotctl clear

screen publishes pixels, waits for firmware applied, and records a preview manifest when possible. Preview images are part of the product: they let the user and Agent tune density, typography, page splitting, and taste over time.

Reset Or Re-pair An AI Assistant

Recommended path:

1. Open Install / Configure.
2. Connect the device from desktop Chrome or Edge.
3. Make sure 屏幕接管方式 is set to 已有 AI 助手.
4. Expand 重置配置 and click 重置 AI 助手配对.
5. Confirm the prompt. The page clears the device-local BYOA credential, saves 已有 AI 助手 as the screen ownership mode, and reboots the device.
6. The screen shows a new six-digit pairing code. Ask the new Agent to run weclawbotctl bind <pairing-code>, then weclawbotctl doctor --online.

If the old Agent installation is no longer used, run this on that Agent host:

weclawbotctl unbind --yes

That only removes the local ~/.config/weclawbot/agent-mqtt.json credential on the Agent host. It does not make the screen show a new code; re-pairing starts from the device-side 重置 AI 助手配对 action.

The cloud binding is authoritative. After a new Agent pairs with the same physical screen, the previous Agent credential should be rejected by MQTT with a clear owner/revoked error; an old Agent must not keep controlling the screen just because its local profile file still exists. weclawbotctl status is local state; use weclawbotctl doctor --online to verify live ownership.

Physical fallback: holding the right button for five seconds performs full clear. It clears text, photos, WeChat login, and Agent pairing, so use it only when all local user state should be removed.

Hardware

Target	Display	Environment	Navigation
Waveshare ESP32-S3-RLCD-4.2	400 x 300 monochrome reflective LCD	onboard SHTC3 and battery status	KEY/left: previous and clear text; BOOT/right: next and full clear
Zectrix Note 4	400 x 300 monochrome e-paper, SSD2683	cloud weather, onboard battery status	up: previous and clear text; down: next/hardware power; voice: calendar and full clear

Both targets use ESP32-S3 and 16 MB flash. The visible set stays intentionally small: calendar, photo, and up to three message pages. E-paper refreshes more slowly, so Note 4 uses page-turn transitions and a longer carousel interval.

Firmware Roles

Firmware should stay boring and dependable:

• keep Wi-Fi credentials and WeChat/iLink tokens in local NVS;
• poll WeChat getupdates in official mode;
• ignore WeChat input in BYOA mode;
• connect to MQTT/WSS for official and BYOA control;
• validate activity, screen_document, and screen_clear;
• draw already-rendered pixels within the 400 x 300 hardware boundary;
• preserve local state across normal firmware upgrades.

Agents should evolve quickly:

• decide what the user meant;
• choose whether to ignore, clarify, render, or clear;
• produce readable black-and-white layouts;
• split pages when useful, but avoid unnecessary paging;
• send preview images back to the user-facing channel;
• improve from corrections and user taste without requiring firmware upgrades.

Build

Install ESP-IDF 5.4 or newer.

Development builds (use an isolated sdkconfig for each board):

./scripts/idf.sh -B build-waveshare -D SDKCONFIG="$PWD/build-waveshare/sdkconfig" -D SDKCONFIG_DEFAULTS="sdkconfig.defaults" build
./scripts/idf.sh -B build-note4 -D SDKCONFIG="$PWD/build-note4/sdkconfig" -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.zectrix.defaults" build

Public release builds:

./scripts/idf.sh -B build-waveshare -D SDKCONFIG="$PWD/build-waveshare/sdkconfig.public" -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.release.defaults" build
BUILD_DIR="$PWD/build-waveshare" OUT_DIR="$PWD/web/firmware" ./scripts/prepare_web_firmware.sh

./scripts/idf.sh -B build-note4 -D SDKCONFIG="$PWD/build-note4/sdkconfig.public" -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.zectrix.defaults;sdkconfig.release.defaults" build
BUILD_DIR="$PWD/build-note4" OUT_DIR="$PWD/web/firmware-note4" ./scripts/prepare_web_firmware.sh

Both hardware targets and both build channels render the same versioned upper-left title, for example 微笺 v0.1.93. The title is derived from WEC_FIRMWARE_VERSION; there is no separate development-build label.

Repository Map

• main/: ESP32 firmware
• web/: Web Serial installer, configuration page, firmware manifest, behavior contract
• integrations/hermes/: Hermes plugin
• runtime/: rules-first curator runtime examples
• docs/: architecture, protocols, reliability notes, privacy boundary, release boundary

The behavior contracts are web/firmware-contract.json for Waveshare and web/firmware-contract.note4.json for Note 4. Website simulation and release tooling should select the physical device profile instead of copying firmware behavior by hand.

Privacy Boundary

This public repository may contain firmware source, the installer/config page, public release artifacts, user docs, Agent plugin source, and audited behavior contracts.

It must not contain official cloud deployment code, private gateway logs, WeChat tokens, Wi-Fi passwords, model API keys, MQTT broker admin credentials, Tencent Cloud resource IDs, raw user data, or private prompts.

Before publishing, read docs/public-release-boundary.md and run docs/project-release-checklist.md.

Links

• Official website and simulator: https://weclawbot.link/
• Install/configure: https://openbrt.github.io/weclawbot/web/
• npm package: https://www.npmjs.com/package/@openbrt/weclawbotctl
• Releases: https://github.com/openbrt/weclawbot/releases

License

See LICENSE.