AI Skill MartBrowse skillsPromptsProgramsLearnWhat is a Skill?
 
← Back to list

NanoClaw Container Debugging

A step-by-step playbook for tracing NanoClaw agent container failures through host logs, the two session DBs, mounts, and heartbeats.

Dev & CodingAdvanced★ 30,471⑂ 12,865AI score 8/10Last updated: Aug 9, 2026

What it does

Given NanoClaw's host–container architecture (all message flow passes through inbound.db and outbound.db), this skill tells Claude exactly where to look when something breaks.

  • A log-location table: logs/nanoclaw.error.log, logs/nanoclaw.log, per-step setup logs
  • How to enable LOG_LEVEL=debug to stream container stderr into the host log
  • Ready-made queries against messages_in, messages_out, and processing_ack via the in-tree scripts/q.ts wrapper
  • Four documented failure modes: duplicate service instances silently swallowing messages, containers exiting immediately / 401 auth, mount misconfiguration, stale .heartbeat sessions
  • ncl commands to restart groups, rebuild the image, and reset a session
  • A 7-check quick diagnostic shell script

Who it's for

  • Operators self-hosting NanoClaw whose Telegram/Signal bot stopped replying
  • Contributors trying to understand the containerized agent runtime
  • Users comfortable with Docker, SQLite, and systemd/launchd

Examples

  1. "The bot went quiet" → spot No adapter for channel type in the error log → ps aux reveals two instances → stop and disable the stale service.
  2. "The agent returns 401" → verify the OneCLI gateway on 127.0.0.1:10254, then onecli agents set-secret-mode --mode all.
  3. "Session stuck in processing" → stat the .heartbeat mtime to confirm the container died mid-run, then ncl groups restart --id <group-id>.

· · · Install guide · · ·

Try it now, no install

Paste this into Claude to use the skill without installing anything.

Read the instructions in this file and follow them to help me:
https://raw.githubusercontent.com/nanocoai/nanoclaw/HEAD/.claude/skills/debug/SKILL.md

What I want: (describe your task here)

If Claude can't open the link, open it yourself and paste the contents instead.

↓ If it works for you, download the ZIP below and install it. Then it runs on its own — no pasting each time.

Install in the Claude app (no terminal)
  1. Download the ZIP with the button below.
  2. In Claude, open Settings → Capabilities and turn on 'Code execution and file creation'. (one time)
  3. Go to Customize → Skills → + → 'Upload a skill' and upload the ZIP.
↓ Download ZIP
Install in Claude Code

Let Claude do it — paste this into Claude Code

Install the skill I found on AI Skill Mart.
Copy the .claude/skills/debug folder from the GitHub repo nanocoai/nanoclaw into my ~/.claude/skills/debug/.
When it's done, tell me in one line what this skill can do.

Install with a command instead

git clone https://github.com/nanocoai/nanoclaw.git && mkdir -p ~/.claude/skills/debug && cp -r nanoclaw/.claude/skills/debug/* ~/.claude/skills/debug/

⚠ This is a third-party skill. Check the source repository before installing.

  1. Open a terminal and clone the repo: git clone https://github.com/nanocoai/nanoclaw.git
  2. Create the skill directory: mkdir -p ~/.claude/skills/debug
  3. Copy the skill in: cp -r nanoclaw/.claude/skills/debug/* ~/.claude/skills/debug/
  4. The intended use is inside the NanoClaw project itself — if you already run NanoClaw, just start Claude Code from the repo root and the skill loads automatically.
  5. Restart Claude Code and test with a prompt like "the agent container isn't responding" to confirm it triggers.
  6. Prerequisites: a running Docker (or compatible) runtime, pnpm installed, and the ncl / onecli CLIs available — most commands assume the NanoClaw file layout.
View source on GitHub ↗License: MIT