zclaw docs

chapter 6

Local Dev & Hacking

Fast iteration flow for firmware, provisioning, and debugging without re-entering credentials every run.

Core Local Loop

# 1) Build
./scripts/build.sh

# 2) Flash (keeps NVS by default)
./scripts/flash.sh

# 3) Re-provision quickly from local profile
./scripts/provision-dev.sh

# 4) Watch logs
./scripts/monitor.sh

Normal flashing does not erase NVS, so WiFi/API/Telegram credentials stay intact unless you explicitly wipe.

Profile-Based Provisioning

# One-time template
./scripts/provision-dev.sh --write-template

# Edit ~/.config/zclaw/dev.env once, then:
./scripts/provision-dev.sh --show-config
./scripts/provision-dev.sh

provision-dev.sh wraps provision.sh --yes, reads your local profile, and redacts secrets in output.

  • Shows Telegram bot ID (safe identifier), not full token.
  • Supports backend-specific env fallback: OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY.
  • Allows ad-hoc overrides: --port, --ssid, --backend, --model, etc.

Reset Flows

# Wipe credentials/settings only (keep firmware)
./scripts/erase.sh --nvs --port /dev/cu.usbmodem1101
./scripts/provision-dev.sh --port /dev/cu.usbmodem1101

# Full factory wipe (firmware + settings)
./scripts/erase.sh --all --port /dev/cu.usbmodem1101
./scripts/flash.sh /dev/cu.usbmodem1101
./scripts/provision-dev.sh --port /dev/cu.usbmodem1101

Guardrails are intentional: full erase requires explicit confirmation or --yes in scripted/non-interactive runs.

Key Tooling

CommandUse
./scripts/test.sh hostPrimary local safety net (C host tests + Python script tests).
./scripts/check-binary-size.sh ...Enforce firmware size guard (888 KiB cap).
./scripts/benchmark.sh --mode serial|relayLatency checks and round-trip timing.
./scripts/web-relay.sh ...Phone-friendly chat UI via host relay for manual testing.
./scripts/release-port.shClear stale serial holders when monitor/relay clashes.

Debugging Tips

  • If serial operations fail with busy port, stop monitor/relay or run ./scripts/release-port.sh.
  • If Telegram behaves oddly, verify startup logs for Loaded bot ID: ... (safe identifier) and chat ID.
  • If you changed only runtime credentials, skip rebuild/flash and run ./scripts/provision-dev.sh directly.
  • Use ./scripts/provision-dev.sh --show-config --dry-run before scripted runs to inspect resolved values safely.

Typical Hacking Session

# code edit
./scripts/test.sh host
./scripts/build.sh
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101
./scripts/provision-dev.sh --port /dev/cu.usbmodem1101
./scripts/monitor.sh /dev/cu.usbmodem1101