How to Configure and Troubleshoot NanoClaw

If you're running NanoClaw on a Self-Managed VPS or Virtual Dedicated Server (VDS), you've got an AI agent that lives on your own server and takes instructions over chat — WhatsApp, Telegram, Discord, Slack, whatever you've wired up. One small host process watches for incoming messages, and every time the agent actually needs to do something, it spins up a fresh Docker container to run Claude Code in.

This guide assumes NanoClaw is already installed and running. If you still need to install it, follow whichever path applies to you and come back here afterward:

One thing worth carrying over from either install: whether you're on one-click or manual determines how you get into the right shell for the commands below — one-click needs machinectl shell nanoclaw@ first, manual just needs you in the project directory. Everything else in this guide is identical either way.

1. Quick Reference: Operational Task Matrix

NanoClaw uses pnpm, not npm, and its background service is a per-user systemd unit named with a version and a per-checkout slug, e.g. nanoclaw-v2-a1b2c3d4. You don't need to remember the exact slug — every command below works with the glob 'nanoclaw-v2-*' instead.

Operation	Execution Command	Where to Run It	Best For
Open a Claude Code Session	`claude`	One-click: inside `machinectl shell nanoclaw@` Manual: inside the project directory	Running setup/debug/channel skills (`/setup`, `/debug`, `/add-telegram`, etc.)
Check Agent Containers	`docker ps`	Either — Docker is shared across users on the host	Seeing which agent sessions are currently executing
Service Status	`systemctl --user status 'nanoclaw-v2-*' --no-pager -l`	Same shell that owns the install (nanoclaw user, or your own)	Checking process health and auto-restart status
Live Logs (service lifecycle)	`journalctl --user -u 'nanoclaw-v2-*' -f`	Same shell that owns the install	Watching for the service starting, stopping, or crash-restarting
Live Logs (application detail)	`tail -f logs/nanoclaw.log`	Project directory	Watching inbound messages and container spawns in real time
Restart the Service	`systemctl --user restart 'nanoclaw-v2-*'`	Same shell that owns the install	Recovering from a stuck or unresponsive agent
Re-run Setup	`cd ~/nanoclaw && bash nanoclaw.sh`	Same shell that owns the install	Fixing a broken config, e.g. "FATAL: No channels connected"
Edit an Agent's Standing Instructions	`nano groups/<folder>/CLAUDE.local.md`	Project directory	Updating rules, persona, and constraints for one agent group

If you're not sure which install you have: check whether /home/nanoclaw/nanoclaw exists and whether a nanoclaw system user is present (id nanoclaw). If so, you're on a one-click install and you need machinectl shell nanoclaw@ before anything else. If there's no such user, you're on a manual install — just work from wherever you cloned the repo.

2. Connecting and Managing Messaging Channels

The setup wizard already offers to connect one channel during first-time setup. Adding more later — on either install — goes through Claude Code skills, not a config file:

claude

Then, inside the session, run the skill for whatever platform you want to add:

Telegram: /add-telegram — links via a one-time code sent to your bot in Telegram.
Discord: /add-discord — links via a code sent to your bot in Discord.
WhatsApp: /add-whatsapp — drops a QR code right in your terminal; scan it with WhatsApp's linked devices feature.
Slack: /add-slack — needs a public webhook URL, since Slack pushes events in rather than NanoClaw polling for them.
Signal, iMessage, Microsoft Teams, and others: each has its own /add-* skill; a few (iMessage, Teams) need extra setup the skill will walk you through.

You can run several channels at once, and decide per channel whether it shares an agent group with everything else or gets its own dedicated one.

3. Advanced Customization and System Automation

Once the basics are running, here's how to shape how the agent behaves, control what it can touch on disk, and get it doing things on a schedule.

Customizing Agent Instructions and Memory

Every agent group gets its own folder under groups/. On a live install, the file that actually holds a group's standing rules is CLAUDE.local.md:

nano groups/main/CLAUDE.local.md

# Standing instructions for this agent group - Provide concise, actionable bullet points. - Always ask for confirmation before running destructive or system-changing commands. - Format all technical output in standard syntax blocks.

Don't confuse this with CLAUDE.md. The shared, framework-level CLAUDE.md gets rebuilt from the base config plus whatever skills are enabled — edits there get overwritten. CLAUDE.local.md, confirmed on a live install, is the per-group file NanoClaw leaves alone, and it's the one to edit for a group's standing instructions. (Some NanoClaw documentation also references a separate long-term memory/ folder per group — we didn't see one on a freshly created group during testing, so treat that as unconfirmed until it's checked on your own install.)

Directory Permissions and Security Considerations

Agent containers only see what NanoClaw explicitly lets them — there's no manual docker run -v flag to write:

Mount allowlist: ~/.config/nanoclaw/mount-allowlist.json decides which host directories any agent group is even allowed to mount. It lives outside the project folder so it never ends up mounted into a container itself.
Per-group overrides: groups/<folder>/container.json sets container options — mounts, provider, resource limits — for just that one group.
Sender allowlist (optional): ~/.config/nanoclaw/sender-allowlist.json, if you want to restrict who on a given channel can trigger the agent.

Security note for manual installs: if setup is run as root instead of a regular user, NanoClaw quietly switches to a system-level systemd unit instead of a user one — drop --user from every command in this guide if that's the case. One-click installs don't hit this, since setup always runs as the dedicated nanoclaw user.

Scheduling Recurring Tasks

The easiest way to schedule something is to just ask the agent — "every day at 8 AM, audit disk usage and send me a summary" — since scheduling is built in and doesn't need cron.

If you need this triggered from outside chat (e.g. from cron or another script), there currently isn't a supported ncl command for it — checking pnpm ncl help against a live install shows the sessions resource only supports list and get. Sessions are created automatically by the router when a message arrives; nothing in the CLI manufactures one on demand. Ask the agent to handle the scheduling itself instead — that's the supported path.

4. System Maintenance and Troubleshooting

Try the built-in debug skill before digging through logs by hand — it's usually faster:

claude

Then run /debug inside the session. It knows where the logs live, how the session database is laid out, and what the common failure patterns look like.

Monitoring Logs Manually

journalctl --user -u 'nanoclaw-v2-*' -f

Confirmed on a live install: this shows systemd-level lifecycle events only — the service starting, stopping, or restarting. It won't show inbound messages, container spawns, or anything else the application itself logs. For that — plus resolved mount configuration and streamed container stderr if you set LOG_LEVEL=debug in .env — go straight to the log files instead:

tail -f logs/nanoclaw.log tail -n 50 logs/nanoclaw.error.log

Agent containers run with --rm, so once one exits, these logs are the only place its output still exists.

Recovering from a Stuck Session

Agent containers don't stick around — each one spins up for a single message and gets torn down the moment that turn finishes, so there's rarely a long-lived container to restart. If something looks stuck, restart the host service instead, since that's what owns the whole container lifecycle:

systemctl --user restart 'nanoclaw-v2-*'

Example Output:

[systemd] nanoclaw-v2-a1b2c3d4.service restarted successfully.

And if you just want to confirm nothing got left running:

docker ps -a --filter "name=nanoclaw"

Service Crash-Looping Right After Install

If the service shows active running in systemctl --user status but chat commands fail with daemon not reachable, check logs/nanoclaw.error.log for this:

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

This happens when setup added your user to the docker group but that change hasn't taken effect in your current shell yet — common on a manual install if you ran the whole setup wizard in one sitting. Confirm it's the cause:

groups docker info

If your user shows up in docker per groups but docker info still returns a permission error, refresh the group membership without a full logout:

newgrp docker docker info

Once docker info returns real output, restart the service:

systemctl --user restart 'nanoclaw-v2-*' ls -la data/cli.sock

A socket file appearing at that path confirms the daemon started cleanly this time.

Updating NanoClaw

Easiest path — let the built-in skill handle it:

claude

/update-nanoclaw

Or manually, from the project directory:

git pull pnpm install pnpm run build systemctl --user restart 'nanoclaw-v2-*'

Example Output:

Updating c3f1a2b..f8e9d0c Fast-forward src/index.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) Done in 2.1s [systemd] nanoclaw-v2-a1b2c3d4.service restarted successfully.

Agent state — memory, sessions, group registrations — sits in a persistent SQLite database under data/, so updates don't touch it. Groups and conversation history come through untouched, on either install type.

Summary

This guide covers the full lifecycle of running NanoClaw AI agents on a Self-Managed VPS or Virtual Dedicated Server (VDS). You'll learn how to manage agent operations with systemd and Docker, connect popular chat and messaging channels, customize agent memory and permissions, automate regular tasks, monitor logs, troubleshoot issues, and safely update the NanoClaw software. Whether you've used the one-click or manual install path, this reference ensures secure, reliable agent automation so you can focus on scaling your workflows with AI.

Did you find this article helpful?