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, OLLAMA_API_KEY.
Allows ad-hoc overrides: --port, --ssid, --backend, --model, etc.
Updates the same NVS runtime keys as provision.sh (WiFi, backend/model/API key/API URL, Telegram token/chat ID allowlist).

For ollama, set ZCLAW_API_URL (or pass --api-url) to a LAN-reachable endpoint.

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

Command	Use
`./scripts/test.sh host`	Primary 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\|relay`	Latency checks and round-trip timing.
`./scripts/web-relay.sh ...`	Phone-friendly chat UI via host relay for manual testing.
`./scripts/release-port.sh`	Clear 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 authorized chat IDs.
If Telegram keeps replaying stale messages, run ./scripts/telegram-clear-backlog.sh --show-config once.
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