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 per-session SQLite queues (inbound.db/outbound.db) that are the sole IO surface between host and container, 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.
• data/v2-sessions/{group}/{session}/ — the per-session inbound.db (did the message reach the container?) and outbound.db (did the agent produce a reply?). Containers run with --rm, so there are no per-run container log files — container stderr is streamed into logs/nanoclaw.log at debug level instead.
• Per-group Claude state (settings, session history) at {group}/.claude-shared on the host, mounted to /home/node/.claude in the container.

Setting LOG_LEVEL=debug in your environment produces verbose output that includes full mount configurations, the container spawn command, and streamed container stderr.

Common issues

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

Authentication failures — secrets are injected per request by the OneCLI gateway; they’re never passed into containers as environment variables or chat context. If an API returns a 401 for a credential that’s in the vault, the skill checks the agent’s secret mode (onecli agents list, and onecli agents set-secret-mode if the secret was never assigned). If the gateway itself is unreachable, the runner refuses to spawn containers at all — the skill confirms the gateway is up at http://127.0.0.1:10254.

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 — conversation continuity lives in the container-owned session_state table in the session’s outbound.db, per session. To reset a session, remove its folder under data/v2-sessions/{group}/{session}/ and a fresh one is provisioned on the next message. The /home/node/.claude/ mount (from {group}/.claude-shared) holds per-group Claude settings and history.

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.
• Inspect the session DBs (ncl sessions list, or query inbound.db/outbound.db with scripts/q.ts) to see whether messages reached the container and whether the agent replied.

Tips

• Always check logs/nanoclaw.error.log first. Most issues leave a clear error message there.
• The quick diagnostic script checks 7 common failure points in one pass: container runtime, agent image, OneCLI gateway, central DB, mount targets, duplicate host instances, and recent errors.
• If you’re debugging intermittent issues, run with LOG_LEVEL=debug for a while and check the verbose logs after the next failure.
• Containers run with --rm, so they leave nothing behind after exit. But the main application log does grow — consider rotating it if NanoClaw has been running for a long time.