Troubleshooting

Check the relevant layer before changing config. A package-load failure, blocked bootstrap, closed worker tab, missing model credentials, or disconnected bot can all look like a silent Clawa.

Clawa did not appear

With a global install, this is expected in an ordinary directory without .pi/claw.jsonc. Clawa stays dormant there. Use a project install or explicit -e from a clean folder to make a home.

1. Run pi -e /absolute/path/to/pi-clawa from the intended home.
2. Check that Node satisfies >=24.15.0 <27.
3. Check .pi/settings.json if plain pi fails but -e works.
4. Run pi --no-extensions -e /absolute/path/to/pi-clawa to isolate extension conflicts.
5. Inspect Pi’s startup error rather than adding another copy of the package path.

Bootstrap was blocked

Use the exact file list in First run. Reconcile those files or move to a clean home; setting bootstrapped: true only turns the blockage into a half-home.

A worker will not start

• Validate .pi/claw.jsonc: every worker needs an ID and cwd.
• Check enabled, autostart, model name, and provider auth.
• Check whether its Herdr tab or tmux window is still open. /jump can reopen a stopped session.
• Confirm the worker cwd still belongs to the session recorded in .pi/clawas/session-registry.json.
• Check the worker’s terminal location in the same session registry before touching stale runtime sockets.

Use /steer and watch the reported error. Config edits take effect when the tab next launches, not in a running session. Private messages still work while someone types directly in the tab.

After moving terminal hosts, an explicit reopen replaces a tmux location only when the old server is confirmed gone. If the old location cannot be checked, inspect it rather than deleting its registry entry and risking a duplicate session.

A task arrived but no turn started

The target tab and worker monitor show wake errors. For a missing model or authentication, repair the intended model or existing credentials in that tab, then resend the task. Clawa does not switch providers, accounts, or billing to make a task run.

If Pi has not acknowledged a wake after 15 seconds, Clawa reports that uncertainty without sending it again. Slow preparation may still finish. Inspect the target tab; if no turn is preparing and none starts, reload that tab before resending. Ask before making global Pi or account changes.

Pulses are silent

Try /pulse run owner:id first. Then check the visible definition, quiet hours, and owning session against the Pulse runtime rules. Inspect .pi/pulses.json only after those surfaces look right.

Identity feels stale after compaction

The next before_agent_start should refresh the five living files in Pi’s structured prompt after Pi or Codex continuity. Check that the files are under the resolved home, within the documented bounds, and not replaced by an outside instruction file you expected Clawa to load. Check for an opaque full-prompt override that hides home sections. Clawa preserves other extensions’ prompt ownership; use .pi/APPEND_SYSTEM.md or structured sections for compatible additions.

For structural checks:

python /absolute/path/to/pi-clawa/skills/clawa-ops/scripts/doctor.py /path/to/home

Discord is connected but does not reply

• Look in the owning home’s Pi tab for the incoming message and connection status. Another home’s tab cannot receive this bot’s messages.
• By default the bot accepts DMs, mentions, and replies to itself. Check /discord chat intake, channel policy, allowed or excluded channel IDs, and allowed users.
• Unmarked final text stays in Pi. Reply with a shown [mN] handle, or use [c] for a channel post.
• Check the bot token in this home’s .pi/clawa-discord/bot.env. A missing token leaves it off; a token already in use by another home is rejected. Do not paste the token into a bug report.
• A reload or disconnect drops pending turns and rich action tokens. Search archived messages with discord_history if you need earlier context.