How to use the NanoClaw Container Debugging agent skill (debug)

What the debug skill makes the agent do

An agent skill is a folder containing a SKILL.md file with instructions that an agent loads when a request matches the skill's description. The debug skill's description covers cases where things aren't working, a container fails, authentication problems occur, or someone wants to understand how the container system works.

Once loaded, the agent works from the guide's architecture overview and log tables. It knows that the host is a single Node process that starts one container per session, and that the two session databases, inbound.db and outbound.db, are the only input and output channel between host and container. It can therefore check whether a message reached the container, whether a reply was produced, and whether the reply was delivered.

• Locates host errors, the host app log, setup logs and per-session database files
• Runs read-only database queries through the in-tree query wrapper
• Explains how to turn on verbose debug logging
• Walks through a repair step for the credential gateway, and a fix for duplicate service instances

Install the debug skill

Download the ZIP from this page and unzip it. The skill folder contains SKILL.md. Put the folder in one of two places: ~/.claude/skills/ to make it available to you across projects, or a project's .claude/skills/ folder to make it available only to that project.

Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/debug/
• Project: .claude/skills/debug/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you start

The guide assumes you have a NanoClaw checkout and can run commands in it. The skill's commands use pnpm and tsx, and the query wrapper depends on the better-sqlite3 package, which NanoClaw setup installs. The host runs as a Node.js process, and the per-session agent containers need Docker or a compatible container runtime.

You also need access to NanoClaw's logs and data directories, because the agent reads files such as logs/nanoclaw.error.log and data/v2-sessions/. Without those, the skill has nothing to inspect.

• NanoClaw checkout with pnpm and tsx available
• Node.js host process
• better-sqlite3 dependency (installed by NanoClaw setup)
• Access to NanoClaw logs and data directories
• Docker or a compatible container runtime

Trigger the skill with natural requests

You do not need to name the skill. Describe the symptom in plain language, and mention NanoClaw so the agent works in the right checkout. The description is matched against requests about broken behaviour, container failures, authentication problems and questions about how containers work.

Useful requests name the symptom and the channel or group involved, so the agent knows which session folder to check.

• "NanoClaw isn't replying to my Telegram messages. Help me find out why."
• "My NanoClaw container keeps failing to start. Check the logs."
• "Explain how NanoClaw passes messages between the host and the container."
• "Authentication is failing in a NanoClaw agent container. What should I check?"

Turn on debug logging for deeper detail

The guide tells the agent to set LOG_LEVEL=debug when more detail is needed. At debug level the log shows full mount configurations, the container spawn command and streamed container stderr lines. The source gives separate examples for a development run and for the macOS launchd service or the Linux systemd service.

Examples of diagnosis the skill supports

For a message that never got a reply, the guide describes a reading order. If messages_in has the message but messages_out has no matching reply, the container never produced one, so the agent checks processing_ack and the host log for spawn and exit lines. If messages_out has a reply but the user never got it, the agent looks at delivery. If messages_in is empty, routing never reached the session, and the agent checks the router log lines and the central wiring.

For the common issue where replies stop and the log shows 'No adapter for channel type' warnings, the guide explains the likely cause: a second NanoClaw service instance running a stale binary, whose delivery poll marks messages delivered without sending them. The agent is directed to check for duplicate processes and active services, then to stop and disable the stale one.

• Reply missing: compare inbound.db and outbound.db rows
• Reply produced but not received: investigate delivery
• No inbound rows: check routing and wiring
• Silent loss with 'No adapter for channel type': look for duplicate service instances

Safety notes: scripts and the credential gateway

The skill runs scripts, including scripts/q.ts through pnpm exec tsx, and reads and changes files in your NanoClaw checkout and data directories. It does not use the network. Review what the agent runs before approving commands, and prefer read-only SELECT queries when you are only investigating.

The gateway section is the riskiest part. It re-runs a setup step against the credential gateway. The guide itself tells the agent not to recreate gateway containers by hand with docker run or docker rm, and never to generate replacement keys for an existing database. Keep the gateway's database volumes and keys intact, and do not let an agent repair live credential services unless you are prepared to supervise it.

• Scripts run: yes, through pnpm and tsx
• Network use: none stated
• Gateway repair step touches database volumes and keys; supervise it closely

Tips for getting useful results

Give the agent the symptom, the channel, and the group or session if you know it. Ask it to check the host error log first, since the guide names that file as the place to start. If the agent cannot find a container's output after it exits, that is expected: containers run with --rm, so the guide directs it to reconstruct the story from the session databases and the host log.

• Start with logs/nanoclaw.error.log
• Ask for the reading order of inbound.db and outbound.db
• Enable LOG_LEVEL=debug before reproducing the problem
• Remember that container filesystems are removed when containers exit