NanoClaw

NanoClaw: Fixes

This page covers the problems NanoClaw users run into most, drawn from the official troubleshooting pages and the project's GitHub issues. Each one gives the symptom, the likely cause, and the fix, and it follows The playbook.

These checks match the docs and issues as of 14 November 2026, when the newest release was v2026.10.0. Run every command in Terminal on a Mac or in the Ubuntu window on Windows, from inside the nanoclaw folder unless it says otherwise.

The project's own first step for most problems is to open Claude Code in the nanoclaw folder and run /debug, which reads the logs for you. This guide could not confirm whether the installer puts Claude Code on your computer, so the fixes below use plain commands instead.

Setup stops or fails

Symptom. bash nanoclaw.sh stops partway with an error, or a browser sign-in never finishes.

Likely cause. A missing tool, a download that failed, or a sign-in that timed out. Every setup run writes a short log to logs/setup.log and the full output of each step under logs/setup-steps/, so the real reason is usually in there.

Fix.

  1. Read the last lines of the log:
cd ~/nanoclaw
tail -n 40 logs/setup.log
  1. Follow the recovery message setup printed. To try again, run bash nanoclaw.sh from the same nanoclaw folder, and if it asks what to do with the existing install, choose Keep it & continue setup.
  2. If Terminal says git is not found, go back to the Git check on the install page. If setup finished but Terminal cannot find pnpm, open a new Terminal or Ubuntu window and run cd ~/nanoclaw first.
  3. If setup cannot fetch the prebuilt image, run setup again and choose Build it here, which needs no account. An open GitHub issue from 12 November 2026 reports that fetching can fail after Node is upgraded, with a message saying "Couldn't fetch the sandbox image".

Do not delete an existing nanoclaw folder just to start over, because the quick start warns it may hold an agent you already set up. When you ask for help on Discord, leave out passwords, keys, and sign-in codes.

What you should see setup carries on from the step that failed and ends with You're ready!

Docker will not start

Symptom. NanoClaw stops with a box that says FATAL: Container runtime failed to start.

Likely cause. Docker is not running. NanoClaw checks for Docker each time it starts and exits if it cannot reach it.

Fix. Start Docker, check it, then restart NanoClaw:

Then run this, and check that it prints details rather than an error:

docker info

Restart NanoClaw the same way as in the egress lockdown step on the install page.

What you should see docker info prints a list of details, and NanoClaw starts without the box.

The agent never replies

Symptom. pnpm run chat prints NanoClaw daemon not reachable, or it waits and then prints timeout: no reply in 120000ms.

Likely cause. The first message means the background service is not running. The second usually means no agent is connected to the terminal chat, although the first reply after a quiet spell can also take 30 to 60 seconds while the container starts.

Fix.

  1. Start the service. On a Mac, use the launchctl kickstart line from the install page. On Windows, use systemctl --user restart <unit>, or run bash start-nanoclaw.sh if you use the start script.
  2. Send the message again and give it a full minute.
  3. If it still times out, check the list of messages NanoClaw turned away, and the reason for each:
ncl dropped-messages list
  1. If the reason says no agent is connected, the CLI channel page gives a script that connects one to the terminal chat. It is safe to run while NanoClaw is running, and you can change the two names:
pnpm exec tsx scripts/init-cli-agent.ts --display-name "Your name" --agent-name "Nano"

What you should see the agent's reply in the window.

The model gives errors

Symptom. The agent replies with a short error instead of an answer, or it stops replying after working for a while.

Likely cause. Since v2026.10.0, a failed Claude run shows Claude's own short reason in the chat for known failures, such as an invalid API key. The usual causes are these:

Fix.

  1. Read the most recent errors:
tail -n 50 logs/nanoclaw.error.log
  1. For a bad key, make a new key for one workspace in the Claude Console, then run the model step of setup again with pnpm run setup -- --step provider-auth. This guide could not confirm that this step offers the same Claude choices as the first setup, so follow what it shows. The vault also has a web dashboard, at the address saved as ONECLI_URL in .env, where you can browse saved secrets.
  2. For a spend limit, check your usage at Anthropic before you raise anything, because a sudden jump can mean a job is repeating itself.
  3. For a wrong model name, look at the agent's settings, then set a model name the docs list, such as sonnet, opus, or haiku, and restart. Put your agent's id where it says <id>:
ncl groups list
ncl groups config get --id <id>
ncl groups config update --id <id> --model sonnet
ncl groups restart --id <id>

What you should see a normal reply to your next message, and no new lines in logs/nanoclaw.error.log.

The agent loops or repeats itself

Symptom. The agent keeps doing the same thing, sends the same message again and again, or your model bill climbs while you are not using it.

Likely cause. There are three common ones. Two agents told to always reply can message each other forever, because the docs say there is no built-in limit on agent-to-agent loops. A scheduled task may run more often than you meant. A container that gets stuck is stopped and its message retried, and the troubleshooting page says that after five tries you see Message marked as failed after max retries.

Fix.

  1. Stop it first, using the next section.
  2. List and cancel scheduled tasks:
ncl tasks list
ncl tasks cancel --all
  1. Clear the conversation with pnpm run chat /clear. The providers page says /clear resets the conversation but not the workspace files or memory. The hardening page says only an owner or admin may use it, and this guide could not confirm that the terminal chat counts as one, so if the reply says "Permission denied", skip this step.
  2. Send a smaller job with one clear finished result, and when two agents are involved, give each one a stop condition such as "report back once, then wait."

What you should see ncl tasks list shows no live tasks, and the agent answers your next message once.

Stop it right now

Symptom. You want the agent to stop immediately, whatever it is doing.

Likely cause. Not a fault. Closing the terminal does not stop it, because NanoClaw runs as a background service and keeps working without the window.

Fix. Do these in order.

  1. Cancel every scheduled task with ncl tasks cancel --all.
  2. Stop the background service, putting the name you found where it says <label> or <unit>:

On a Mac, find the name with launchctl list | grep nanoclaw, then run:

launchctl unload ~/Library/LaunchAgents/<label>.plist

On Windows with systemd on, find the name with systemctl --user list-units 'nanoclaw-v2-*', then run:

systemctl --user stop <unit>

On Windows with the start script, run:

kill $(cat nanoclaw.pid)
  1. Stop any agent container that is still running. The update docs show NanoClaw stopping its containers as a separate step after it stops the service, so do the same:
docker ps --filter label=nanoclaw-install
docker ps -q --filter label=nanoclaw-install | xargs -r docker stop

The launchctl unload and kill lines come from the install page. systemctl --user stop is systemd's own standard command for the same service, and docker stop is Docker's own command for the containers that the docs' label=nanoclaw-install filter lists.

To start again later on a Mac, run launchctl load ~/Library/LaunchAgents/<label>.plist. On Windows, use systemctl --user restart <unit> or bash start-nanoclaw.sh.

What you should see running docker ps --filter label=nanoclaw-install again lists no containers, and pnpm run chat says the daemon is not reachable.

After it does something wrong, follow After it does something wrong once the agent is stopped.

It will not start after an update

Symptom. NanoClaw stops with NanoClaw stopped: update did not go through the supported path.

Likely cause. The code was updated with a plain git pull. NanoClaw records each proper update, and it refuses to start when the code does not match that record.

Fix. The docs say the only supported way to update is /update-nanoclaw, run inside Claude Code in the nanoclaw folder, and that it also repairs an install stopped this way. Do not update with git pull. If you cannot run Claude Code, this guide could not confirm a supported way to update or repair the install, so ask on the project's Discord.

What you should see after the repair, NanoClaw starts and the agent answers your next message.

Update it safely

Symptom. You want a newer NanoClaw, and you want the files in your containers' folders to stay.

Likely cause. None. This is housekeeping. Run every command in Terminal on a Mac, or in the Ubuntu window on Windows, from the nanoclaw folder. Do these three steps in order.

Fix.

  1. Copy the folders that hold settings, memory, and the workspace before you update. From ~/nanoclaw, copy .env, data, groups, and store to a folder outside the project. .env holds settings and chat-app tokens, data holds the agent database and session history, and groups holds each agent's workspace, memory, and instructions. Also copy ~/.config/nanoclaw if it is there, because the folder list lives in it. A copy can live in File History or Previous Versions on Windows, or in Time Machine on a Mac. On Windows, put that copy where those backups can see it, because these folders live inside Ubuntu.
cd ~/nanoclaw
mkdir -p "$HOME/nanoclaw-backup"
cp -a .env data groups "$HOME/nanoclaw-backup/"
cp -a store "$HOME/nanoclaw-backup/"
cp -a "$HOME/.config/nanoclaw" "$HOME/nanoclaw-backup/config-nanoclaw"

What you should see nanoclaw-backup contains .env, data, and groups, and those same folders are still inside ~/nanoclaw. If the store or config line says "No such file or directory", that item is not on this install. The three items above are still copied.

  1. Read CHANGELOG.md in the nanoclaw folder, and the release history, before you update. The supported update is the /update-nanoclaw skill inside Claude Code in the nanoclaw folder, because ncl has no update command. If Claude Code is not on your computer yet, install it first or ask on Discord before changing the checkout. Read the changed files and any breaking-change lines the updater shows, and confirm only when they look right. The updater stops this install's agent containers while leaving the OneCLI vault container untouched, copies .env, data, groups, and store into its snapshot, and switches the code. Those folders stay on disk, so do not delete them or run a Docker command that deletes volumes. Do not update with git pull, and note that this guide could not confirm whether an update ever resets egress lockdown or the folder list.

What you should see the updater asks you to confirm before it stops the service, and after it finishes your groups folder still holds the same agent files.

  1. Check the version the program file declares, then send one small test message. The updater stamps that same version into data/upgrade-state.json when the supported path finishes.
node -p "require('./package.json').version"
pnpm run chat "Reply with the single word pong. Do not change any file."

What you should see a version number such as 2026.10.0, the word pong, and your earlier files still inside groups.

Uninstall or reset it cleanly

Symptom. You want NanoClaw gone, or you want to start over from a clean install.

Likely cause. Not a fault. NanoClaw has its own uninstaller, which removes only what belongs to this copy.

Fix. To remove it, run bash nanoclaw.sh --uninstall --dry-run to see what it would remove, then run bash nanoclaw.sh --uninstall. It asks before deleting each group of files, and you delete the nanoclaw folder at the end.

The uninstaller asks about three groups separately, and the answer starts at no for each one:

  1. The app and its background service, including this copy's containers and image.
  2. App data, logs, and secrets, which erases stored conversations. Your .env is copied to .env.bak first.
  3. Your agents' memory and files in groups/, which cannot be recovered once deleted.

It leaves some things alone on purpose: the OneCLI vault and the keys saved in it, the folder ~/.config/nanoclaw/ with your folder and sender lists, and a line it added to ~/.bashrc and ~/.zshrc. Delete the key itself in the Claude Console if you no longer need it.

To start over instead, run bash nanoclaw.sh in the same folder, and when it finds the existing install, it offers Uninstall NanoClaw & exit as an alternative to upgrading. On Windows, removing Ubuntu itself is a separate step, covered in Microsoft's WSL documentation.

What you should see the dry run lists what it found, then the real run prints a final summary of what was removed and what was left alone.

Sources

Opened 14 November 2026.

NanoClaw:

Other tools:

Next

Continue to Advanced.

Checked 14 November 2026 · prices, limits, and versions change