When CARAPACE misbehaves.

Same Wi-Fi (LAN)

• Phone and machine must be on the same network — this pairing does not work from elsewhere by design.
• The machine's address may have changed (routers reassign them). Re-run the installer line on the machine; it re-detects and re-verifies, then re-prints the QR.

Tailscale

• On the machine: tailscale status must show it logged in and connected.
• On the iPhone: open the Tailscale app and confirm the connection toggle is ON, and that both devices are on the same Tailscale account (work vs personal accounts is the classic miss).

Public HTTPS (VPS)

• From any browser, anywhere: https://<your-host>/<runtime-path>/health should answer {"ok":true...}. Paths: /carapace-claude, /carapace-codex, /carapace-hermes-api, /carapace (OpenClaw).
• If it doesn't answer, on the machine check the front and the gateway: systemctl status caddy and the service section below.
• Cloud providers sometimes ship an edge firewall: ports 80 and 443 must be open in the provider's panel. The gateways themselves stay on 127.0.0.1 — never open their ports.

Need the QR again, or it "does nothing" when scanned.

Fix: on the machine run ~/.carapace/bin/carapace-pair. One code carries every runtime installed on that machine. It re-verifies the gateway answers on the exact URL the code encodes before it renders — if it refuses, its message names the cause (service down, front unmounted, stale URL). A QR it prints is a QR that works.

OpenClaw pairs with its own code: its token lives inside OpenClaw's config, so re-run the pairing step of its setup document.

The QR leaked (screenshot, stream, wrong chat).

Fix: ~/.carapace/bin/carapace-pair <runtime> --rotate --restart — the old key dies instantly, every phone must rescan. The QR is a key, not a picture: anyone who scans it controls that gateway.

"No gateway saved" after deleting / reinstalling the app.

Fix: re-pair with the QR or Enter Manually. The gateway list lives per-install on the phone; deleting the app clears it. Purchases survive — restore from Settings → Plan. Pairing machines is free and unlimited, on every tier.

Did it survive the reboot? (It should.)

The installer makes every gateway reboot-proof and logout-proof. Check it, per runtime:

• Linux: systemctl --user status carapace-claude-gateway (or -codex- / -hermes-; OpenClaw runs carapace-status-server + its own openclaw-gateway). Restart with systemctl --user restart <unit>.
• Mac: launchd label com.carapace.<runtime>-gateway — reload with launchctl kickstart -k gui/$(id -u)/com.carapace.<runtime>-gateway.
• The gateway's own words: tail -40 ~/.carapace/<runtime>-gateway/gw.log
• If a service is gone entirely, re-run the installer line — it rebuilds only what's missing.

Mac went to sleep.

Fix: a sleeping Mac answers nothing. System Settings → Battery/Energy → prevent sleep when plugged in (or run it on a machine that stays awake). The service resumes by itself on wake.

Pearl is grey and won't turn on.

Fix: iOS Settings → Carapace → Microphone → ON. Camera too if you want vision.

Output still says "CarPlay" after leaving the car.

Fix: stale route-name display — update the app; or tap the AirPlay icon next to the output name and pick iPhone.

What happens to my music? (By design:)

• While a reply is spoken: your music ducks under the voice and comes back up by itself.
• While it's listening to you: the microphone needs an exclusive session, so music pauses — and resumes on its own the moment listening ends. If it ever doesn't come back, update the app; this went through a lot of hardening.

Voice agent never responds after I speak.

• Tap the pearl once to read the pill: red = reachability (top of this page), orange = runtime/provider (sign-in section), grey = not paired.
• Speak more than one syllable — the tap needs ~400ms of audio to trigger.

Camera is black, or preview but no answer.

Fix: iOS Settings → Carapace → Camera → ON. Vision rides your runtime's own model — if chat works, vision works; if chat errors, fix sign-in first.