chapter 9
Local Admin Console
USB-local recovery commands for when Wi-Fi is broken, the board is unprovisioned, or the LLM path is unavailable.
Why This Exists
The local admin console is the board's non-LLM control plane. It keeps zclaw operable when chat automation is the wrong tool for the job: first boot, provisioning mistakes, weak Wi-Fi, safe mode, or general field recovery.
- It runs over the USB serial console.
- It does not require a Wi-Fi connection.
- It does not require an LLM round trip.
- It stays available in safe mode and before normal network startup.
How To Use It
Connect the board over USB and open the serial console:
./scripts/monitor.sh /dev/cu.usbmodem1101Then type commands directly into the console:
/wifi status
/wifi scan
/bootcount
/gpio all
/diag all
/rebootThe serial benchmark helper also works well for scripted checks: ./scripts/benchmark.sh --mode serial --serial-port /dev/cu.usbmodem1101 --message "/wifi status".
Command Reference
| Command | Purpose | Notes |
|---|---|---|
/gpio [all|pin|pin high|pin low] | Read or drive tool-allowed GPIO pins locally. | Respects the configured GPIO safety policy. |
/diag [scope] [verbose] | Run local runtime diagnostics. | Scopes match get_diagnostics: quick, runtime, memory, rates, time, all. |
/wifi status | Show provisioned SSID, driver/link state, IP, RSSI, and last disconnect reason. | Useful before and after scans, reprovisioning, or recovery boots. |
/wifi scan | Scan visible Wi-Fi APs. | Lists RSSI, auth mode, channel, and frequency for the top visible networks. |
/bootcount | Show persisted boot-failure count and safe-mode threshold state. | Helps explain why the board entered safe mode. |
/reboot | Reboot the board immediately. | Replies once, then restarts. |
/factory-reset | Show the destructive reset warning. | Non-destructive by itself. |
/factory-reset confirm | Erase NVS and reboot. | Destructive: wipes Wi-Fi credentials, tokens, schedules, memory, and boot state. |
Availability Rules
- These commands are USB-local only.
- Telegram and web relay callers are rejected instead of falling through to the model.
/stoppauses chat intake, but it does not disable local admin commands.- Safe mode keeps this console available specifically so you can inspect and recover the device.
Safe Mode Workflow
A typical safe-mode session looks like this:
/bootcount
/wifi status
/wifi scan
/diag runtime verbose
/gpio allThis is the intended recovery path: inspect boot state, inspect Wi-Fi, inspect runtime health, and only then decide whether to reprovision, move the board, or factory-reset it.
Destructive Reset
/factory-reset confirm is intentionally explicit. It erases NVS and reboots the board.
- Wi-Fi credentials are removed.
- LLM and Telegram credentials are removed.
- Schedules and persistent memory are removed.
- Boot-loop state is cleared because the stored boot counter is erased.
Use this when the stored state itself is suspect. If you only need to restart the board, use /reboot instead.