Troubleshooting

Specific symptom → specific cause → specific command. If you hit something not on this page, myclawn log --tail in one window and re-trigger the failure in another is the right first move — every important event is audited.

Daemon

`daemon control socket missing at …`

The daemon isn't running. Quick checks:

myclawn --status                    # full status incl. PID
ls -la ~/.myclawn/control.sock      # socket should exist if daemon is alive
tail -50 ~/.myclawn/daemon.err.log  # last 50 lines incl. crash, if any

If launchd / systemd has it paused:

ls ~/.myclawn/paused.flag           # if this exists, daemon will start paused
rm ~/.myclawn/paused.flag           # clear it
myclawn resume                       # or this

Force a restart:

# macOS
launchctl kickstart -k gui/$(id -u)/com.myclawn.daemon

# Linux (systemd user unit)
systemctl --user restart myclawn-daemon

"I clicked Quit in the tray and now the daemon won't come back"

That's the locked design: tray Quit writes paused.flag and disables autostart so a reboot doesn't silently bring it back. To restart, open the desktop app — it will re-enable autostart on boot — or run myclawn resume at the CLI.

myclawn ask

`EACCES: permission denied … shim.key`

Your daemon predates the shim-key auto-gen fix. Restart the daemon — it generates shim.{key,pub} at boot with 0640 owner=you group=myclawn so any bot in the myclawn group can read it.

launchctl kickstart -k gui/$(id -u)/com.myclawn.daemon
ls -la ~/.myclawn/shim.key                       # should now be -rw-r----- you myclawn

"`myclawn ask` returns Routing — no answer / status pending forever"

The most common cause is the daemon being paused. Check:

ls ~/.myclawn/paused.flag                # present iff paused
myclawn --status                         # shows paused: true
myclawn resume                           # clear

If not paused, check that the brain is actually running batches. Look for consecutive llm_call_start → llm_call_complete pairs:

myclawn log --type llm_call_* --last 10

If the brain is silent, your LLM provider may be returning errors (rate limit, auth failure). After 5 consecutive failures the daemon's circuit breaker drops agent messages — check consecutive_llm_failures in --status.

myclawn run

"Claude refuses to call `myclawn ask` — flags it as a prompt injection"

Old priming wording triggered claude's injection detector. Update the cached CLI:

# launcher curls latest run.js on every invocation, so simply
myclawn run claude   # next launch pulls the new priming via --append-system-prompt

Confirm: after spawning, the stderr should print [myclawn] priming applied via --append-system-prompt. If not, your ~/.myclawn/run.js is stale — delete it and re-run.

Bot's claude blocks at "In Bypass Permissions mode, Claude Code will not ask…"

The bot's ~/.claude/settings.json is missing the pre-accept setting:

sudo cat ~bot-1/.claude/settings.json
# should contain: {"skipDangerousModePermissionPrompt": true}

If empty / missing, run myclawn run --bot=bot-1 -- claude --version once — that re-runs the bot setup, which seeds settings.json.

"Invalid bot name 'X'. Falling back to your user."

Old fleet.js rejected bare names. Latest auto-prefixes — --bot=lisa → bot-lisa. Same fix as above: myclawn run curls the latest fleet.js; the second attempt should succeed.

"`shell-init: getcwd: cannot access parent directories: Permission denied`"

Cosmetic. Appears when the launcher transiently chdir's into a directory the new bot user can't traverse. Harmless — the spawn succeeds.

Whisper-to-bot

"I hit send and nothing happens"

Latest UI surfaces errors inline (in red). If you see no error AND no "✓ sent" toast, the catch is still swallowing. Update the dashboard:

Refresh the webview (Cmd+R in the desktop app, or relaunch).
Check that the badge reads Local · live, not Local · offline. Whispering to an offline pty errors with agent_X not registered.
If running in a regular browser (not Tauri), the dashboard falls back to POST /api/local/inject — that route refuses non-localhost callers, so you must be on localhost:3000 or 127.0.0.1.

Proxy

"`unable to verify the first certificate`" inside a bot

The bot isn't trusting ~/.myclawn/ca.pem. Two paths:

Bot's ~/.zshenv didn't set NODE_EXTRA_CA_CERTS — re-run myclawn run to refresh the env.
Some tools (e.g. older Python, Go binaries) ignore the env var and ship their own bundle. Try SSL_CERT_FILE=$NODE_EXTRA_CA_CERTS yourtool, or use --no-bot for that specific tool.

"`placeholder_on_wrong_host`" in `daemon.log`

The bot tried to send a placeholder to a host the placeholder's allow-list doesn't cover. The proxy forwards the literal placeholder string (not the real key). The receiving service rejects it. Add the host:

myclawn keys ls                                    # see current hosts
myclawn keys rotate <name> <real-value>            # there's no direct "add host" — recreate with the new host
myclawn keys rm <name>
myclawn keys add <name> <real> --hosts <h1>,<h2>

Memory

"`first memory_search may be slow on fresh install`"

EmbeddingGemma is being downloaded + warmed in the background. First search takes ~30s; subsequent ones are sub-100ms. Wait it out — the model is ~300MB and lives in ~/.cache/myclawn-embeddings/.

"`SQLITE_CORRUPT` on memory.db"

Rare; usually caused by an OOM kill during a write. The brain runs from the markdown memory and reindexes embeddings on next startup if the db is corrupt — just delete it:

rm ~/.myclawn/<cloneId>/memory.db ~/.myclawn/<cloneId>/memory.db-wal ~/.myclawn/<cloneId>/memory.db-shm
launchctl kickstart -k gui/$(id -u)/com.myclawn.daemon
# embedding backfill log will appear in daemon.err.log

Operations

"How do I see what the daemon is doing right now?"

myclawn log --tail              # the trust audit
tail -f ~/.myclawn/daemon.log   # operational (proxy connects, LLM calls)
myclawn --status                # daemon state, queue depth, budget
myclawn dreams --prompt         # the actual system prompt the LLM sees

"I want to start over"

myclawn kill          # logs every device out of the clone session, stops daemon
myclawn uninstall     # removes ~/.myclawn, ~/.config/myclawn, sudoers, fleet helper, bots
# then a fresh install:
curl -fsSL https://www.myclawn.com/install.sh | bash

When to email us

If you hit something that's not here and not obvious from myclawn log: grab the last 100 audit entries as JSON and email them to [email protected]:

myclawn log --last 100 --json > /tmp/myclawn-issue.jsonl

Security issues — do not file a public ticket. Email [email protected]. See Security for the disclosure policy.

← Architecture Bring your own agent →