Debug

How it works

The /debug skill is a diagnostic tool for when something isn’t working. It knows NanoClaw’s architecture — the host process, the container system, the IPC layer, and the messaging channels — and walks you through identifying and fixing the issue.

When you run /debug, it asks what’s going wrong and then checks the relevant components. It reads logs, verifies environment variables, tests container connectivity, and inspects mount configurations. Instead of dumping all diagnostic information at once, it narrows down the problem step by step.

Log locations

NanoClaw writes logs to several locations depending on what’s happening:

• logs/nanoclaw.log — the main application log. This shows the polling loop, message processing, and container spawning.
• logs/nanoclaw.error.log — errors only. Check here first when something breaks.
• groups/{folder}/logs/container-*.log — output from individual container runs. Each agent session gets its own log file.
• Claude session logs inside the container at /home/node/.claude/ — these show what the agent actually did during a session.

Setting LOG_LEVEL=debug in your environment produces verbose output that includes every IPC request, mount operation, and message routing decision.

Common issues

The skill knows about the most frequent failure modes and has specific solutions for each:

“Claude Code process exited with code 1” — this usually means authentication failed. The skill checks whether your Claude API key or OAuth token is valid, whether it’s being passed into the container correctly, and whether the container has network access to reach Anthropic’s API.

Environment variables not reaching the container — containers get their environment from the host process. If you added a variable to .env but the container doesn’t see it, the skill checks the container spawning configuration and suggests the fix.

Mount issues — the agent can only access directories that are explicitly mounted into the container. If the agent can’t find a file it should have access to, the skill verifies the mount allowlist and the actual mount paths.

Permission errors — containers run as the node user, not root. If mounted files are owned by a different user and have restrictive permissions, the agent can’t read them. The skill identifies the specific file and permission mismatch.

Session not resuming — NanoClaw maintains persistent Claude sessions per group. If sessions aren’t being preserved between container runs, the mount path for /home/node/.claude/ is likely misconfigured.

MCP server failures — if a tool like Gmail or a custom MCP server isn’t available inside the container, the skill checks the MCP configuration, verifies the server is installed, and tests connectivity.

Manual testing

The skill can also help you test individual components in isolation:

• Spawn a container manually and run the agent with a test message.
• Open an interactive shell inside a container to inspect the filesystem and environment.
• Run Claude Code directly inside the container to check if authentication works.
• Test IPC communication between the host and a running container.

Tips

• Always check logs/nanoclaw.error.log first. Most issues leave a clear error message there.
• The quick diagnostic script checks 8 common failure points in one pass: service status, container runtime, authentication, registered groups, mount paths, log errors, disk space, and network connectivity.
• If you’re debugging intermittent issues, run with LOG_LEVEL=debug for a while and check the verbose logs after the next failure.
• Container logs are per-run, so they don’t grow indefinitely. But the main application log does — consider rotating it if NanoClaw has been running for a long time.