The Debug skill helps troubleshoot NanoClaw’s containerized agent execution system. It covers logs, environment variables, mounts, and common failure scenarios.
What It Does
The Debug skill helps you:
- Understand the container architecture
- Locate and interpret log files
- Enable verbose debug logging
- Diagnose common issues
- Test container configuration manually
- Fix session resumption problems
How to Apply
Invoke the skill
Run /debug in your OpenCode or NanoClaw context.
Describe the problem
Tell the skill what’s not working:
- “Container exits with code 1”
- “Agent not responding”
- “Sessions not resuming”
- “Environment variables missing”
Follow diagnostic steps
The skill will:
- Check relevant log files
- Verify container configuration
- Test mounts and permissions
- Provide fix instructions
Log Locations
| Log Type | Location | Contents |
|---|
| Main app logs | logs/nanoclaw.log | WhatsApp, routing, container spawning |
| Main app errors | logs/nanoclaw.error.log | Host-side errors |
| Container logs | groups/{folder}/logs/container-*.log | Per-run input, mounts, stderr, stdout |
| Claude sessions | ~/.claude/projects/ | Session history |
Enabling Debug Logging
Set LOG_LEVEL=debug for verbose output:
# For development
LOG_LEVEL=debug npm run dev
# For launchd service (macOS)
# Add to plist EnvironmentVariables:
<key>LOG_LEVEL</key>
<string>debug</string>
# For systemd service (Linux)
# Add to unit [Service] section:
Environment=LOG_LEVEL=debug
- Full mount configurations
- Container command arguments
- Real-time container stderr
Common Issues
”Claude Code process exited with code 1”
Check: groups/{folder}/logs/container-*.log
Common causes:
- Missing authentication (add
CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY to .env)
- Root user restriction (container must run as
node user)
- Session resumption failure (check mount path is
/home/node/.claude/)
Environment Variables Not Passing
Environment variables must be in data/env/env (mounted to container), not just .env.
# Sync environment to container
mkdir -p data/env && cp .env data/env/env
Session Not Resuming
Root cause: Sessions must be mounted to /home/node/.claude/ (not /root/.claude/).
Fix: Verify container-runner.ts has correct mount path:
mounts.push({
hostPath: claudeDir,
containerPath: '/home/node/.claude', // Correct
readonly: false
});
Mount Issues
Expected container structure:
/workspace/
├── env-dir/env # Environment variables
├── group/ # Current group folder (cwd)
├── project/ # Project root (main channel only)
├── global/ # Global CLAUDE.md (non-main)
├── ipc/ # Inter-process communication
└── extra/ # Custom mounts
docker run --rm --entrypoint /bin/bash nanoclaw-agent:latest -c 'ls -la /workspace/'
Manual Testing
Test agent flow
mkdir -p data/env groups/test
cp .env data/env/env
echo '{"prompt":"What is 2+2?","groupFolder":"test","chatJid":"[email protected]","isMain":false}' | \
docker run -i \
-v $(pwd)/data/env:/workspace/env-dir:ro \
-v $(pwd)/groups/test:/workspace/group \
-v $(pwd)/data/ipc:/workspace/ipc \
nanoclaw-agent:latest
Test Claude Code directly
docker run --rm --entrypoint /bin/bash \
-v $(pwd)/data/env:/workspace/env-dir:ro \
nanoclaw-agent:latest -c '
export $(cat /workspace/env-dir/env | xargs)
claude -p "Say hello" --dangerously-skip-permissions --allowedTools ""
'
Interactive shell
docker run --rm -it --entrypoint /bin/bash nanoclaw-agent:latest
Quick Diagnostic Script
Run this to check common issues:
echo "=== Checking NanoClaw Container Setup ==="
echo -e "\n1. Authentication configured?"
[ -f .env ] && (grep -q "CLAUDE_CODE_OAUTH_TOKEN=sk-" .env || grep -q "ANTHROPIC_API_KEY=sk-" .env) && echo "OK" || echo "MISSING"
echo -e "\n2. Container runtime running?"
docker info &>/dev/null && echo "OK" || echo "NOT RUNNING"
echo -e "\n3. Container image exists?"
echo '{}' | docker run -i --entrypoint /bin/echo nanoclaw-agent:latest "OK" 2>/dev/null || echo "MISSING"
echo -e "\n4. Session mount path correct?"
grep -q "/home/node/.claude" src/container-runner.ts 2>/dev/null && echo "OK" || echo "WRONG"
echo -e "\n5. Recent container logs?"
ls -t groups/*/logs/container-*.log 2>/dev/null | head -3 || echo "No logs yet"
The container runs as user node (uid 1000) with HOME=/home/node. All mounts and session paths must reflect this.
