sbusso/claudeclaw/debug

Name: debug
Author: sbusso

Claude Code and agent skill by sbusso/claudeclaw

Trust tier 3

community
ext:[{"type":"config","description":"Configuration overrides"}]

By sbusso
Coding
sbusso/claudeclaw
skills/debug/SKILL.md
Updated 21 Sep 2026
Version 1.0.01 version recorded

Source check pending

Checking that the SKILL.md file is still in the repository.

Debug container agent issues. Use when things aren't working, container fails, authentication problems, or to understand how the container system works. Covers logs, environment variables, mounts, and common issues.

Install

npx vskill@latest install sbusso/claudeclaw/debug

Semi-extensibleMentions customization, but needs skill-specific knowledge. Read the extensible skills standard

SKILL.md

ClaudeClaw Container & Sandbox Debugging

This guide covers debugging the agent execution system (container and sandbox runtimes).

Architecture Overview

Host (macOS)                          Container (Linux VM)
─────────────────────────────────────────────────────────────
src/orchestrator/container-runner.ts               agent/runner/
    │                                      │
    │ spawns container                      │ runs Claude Agent SDK
    │ with volume mounts                   │ with MCP servers
    │                                      │
    ├── data/env/env ──────────────> /workspace/env-dir/env
    ├── groups/{folder} ───────────> /workspace/group
    ├── data/ipc/{folder} ────────> /workspace/ipc
    ├── data/sessions/{folder}/.claude/ ──> /home/node/.claude/ (isolated per-group)
    └── (main only) project root ──> /workspace/project

Important: The container runs as user node with HOME=/home/node. Session files must be mounted to /home/node/.claude/ (not /root/.claude/) for session resumption to work.

Log Locations

Log	Location	Content
Main app logs	`logs/claudeclaw.log`	Host-side WhatsApp, routing, container spawning
Main app errors	`logs/claudeclaw.error.log`	Host-side errors
Container run logs	`groups/{folder}/logs/container-*.log`	Per-run: input, mounts, stderr, stdout
Claude sessions	`~/.claude/projects/`	Claude Code session history

Enabling Debug Logging

Set LOG_LEVEL=debug for verbose output:

bash

# 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

Debug level shows:

Full mount configurations
Container command arguments
Real-time container stderr

Common Issues

1. "Claude Code process exited with code 1"

Check the container log file in groups/{folder}/logs/container-*.log

Common causes:

Missing Authentication

Invalid API key · Please run /login

Fix: Ensure .env file exists with either OAuth token or API key:

bash

cat .env  # Should show one of:
# CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...  (subscription)
# ANTHROPIC_API_KEY=sk-ant-api03-...        (pay-per-use)

Root User Restriction

--dangerously-skip-permissions cannot be used with root/sudo privileges

Fix: Container must run as non-root user. Check Dockerfile has USER node.

2. Environment Variables Not Passing

Runtime note: Environment variables passed via -e may be lost when using -i (interactive/piped stdin).

Workaround: The system extracts only authentication variables (CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY) from .env and mounts them for sourcing inside the container. Other env vars are not exposed.

To verify env vars are reaching the container:

bash

echo '{}' | docker run -i \
  -v $(pwd)/data/env:/workspace/env-dir:ro \
  --entrypoint /bin/bash claudeclaw-agent:latest \
  -c 'export $(cat /workspace/env-dir/env | xargs); echo "OAuth: ${#CLAUDE_CODE_OAUTH_TOKEN} chars, API: ${#ANTHROPIC_API_KEY} chars"'

3. Mount Issues

Container mount notes:

Docker supports both -v and --mount syntax
Use :ro suffix for readonly mounts:

```bash # Readonly -v /path:/container/path:ro

# Read-write -v /path:/container/path ```

To check what's mounted inside a container:

bash

docker run --rm --entrypoint /bin/bash claudeclaw-agent:latest -c 'ls -la /workspace/'

Expected structure:

/workspace/
├── env-dir/env           # Environment file (CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY)
├── group/                # Current group folder (cwd)
├── project/              # Project root (main channel only)
├── global/               # Global CLAUDE.md (non-main only)
├── ipc/                  # Inter-process communication
│   ├── messages/         # Outgoing WhatsApp messages
│   ├── tasks/            # Scheduled task commands
│   ├── current_tasks.json    # Read-only: scheduled tasks visible to this group
│   └── available_groups.json # Read-only: WhatsApp groups for activation (main only)
└── extra/                # Additional custom mounts

4. Permission Issues

The container runs as user node (uid 1000). Check ownership:

bash

docker run --rm --entrypoint /bin/bash claudeclaw-agent:latest -c '
  whoami
  ls -la /workspace/
  ls -la /app/
'

All of /workspace/ and /app/ should be owned by node.

5. Session Not Resuming / "Claude Code process exited with code 1"

If sessions aren't being resumed (new session ID every time), or Claude Code exits with code 1 when resuming:

Root cause: The SDK looks for sessions at $HOME/.claude/projects/. Inside the container, HOME=/home/node, so it looks at /home/node/.claude/projects/.

Check the mount path:

bash

# In container-runner.ts, verify mount is to /home/node/.claude/, NOT /root/.claude/
grep -A3 "Claude sessions" src/orchestrator/container-runner.ts

Verify sessions are accessible:

bash

docker run --rm --entrypoint /bin/bash \
  -v ~/.claude:/home/node/.claude \
  claudeclaw-agent:latest -c '
echo "HOME=$HOME"
ls -la $HOME/.claude/projects/ 2>&1 | head -5
'

Fix: Ensure container-runner.ts mounts to /home/node/.claude/:

typescript

mounts.push({
  hostPath: claudeDir,
  containerPath: '/home/node/.claude',  // NOT /root/.claude
  readonly: false
});

6. MCP Server Failures

If an MCP server fails to start, the agent may exit. Check the container logs for MCP initialization errors.

Manual Container Testing

Test the full agent flow:

bash

# Set up env file
mkdir -p data/env groups/test
cp .env data/env/env
 
# Run test query
echo '{"prompt":"What is 2+2?","groupFolder":"test","chatJid":"test@g.us","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 \
  claudeclaw-agent:latest

Test Claude Code directly:

bash

docker run --rm --entrypoint /bin/bash \
  -v $(pwd)/data/env:/workspace/env-dir:ro \
  claudeclaw-agent:latest -c '
  export $(cat /workspace/env-dir/env | xargs)
  claude -p "Say hello" --dangerously-skip-permissions --allowedTools ""
'

Interactive shell in container:

bash

docker run --rm -it --entrypoint /bin/bash claudeclaw-agent:latest

SDK Options Reference

The agent-runner uses these Claude Agent SDK options:

typescript

query({
  prompt: input.prompt,
  options: {
    cwd: '/workspace/group',
    allowedTools: ['Bash', 'Read', 'Write', ...],
    permissionMode: 'bypassPermissions',
    allowDangerouslySkipPermissions: true,  // Required with bypassPermissions
    settingSources: ['project'],
    mcpServers: { ... }
  }
})

Important: allowDangerouslySkipPermissions: true is required when using permissionMode: 'bypassPermissions'. Without it, Claude Code exits with code 1.

Rebuilding After Changes

bash

# Rebuild main app
npm run build
 
# Rebuild container (use --no-cache for clean rebuild)
./src/runtimes/docker/build.sh
 
# Or force full rebuild
docker builder prune -af
./src/runtimes/docker/build.sh

Checking Container Image

bash

# List images
docker images
 
# Check what's in the image
docker run --rm --entrypoint /bin/bash claudeclaw-agent:latest -c '
  echo "=== Node version ==="
  node --version
 
  echo "=== Claude Code version ==="
  claude --version
 
  echo "=== Installed packages ==="
  ls /app/node_modules/
'

Session Persistence

Claude sessions are stored per-group in data/sessions/{group}/.claude/ for security isolation. Each group has its own session directory, preventing cross-group access to conversation history.

Critical: The mount path must match the container user's HOME directory:

Container user: node
Container HOME: /home/node
Mount target: /home/node/.claude/ (NOT /root/.claude/)

To clear sessions:

bash

# Clear all sessions for all groups
rm -rf data/sessions/
 
# Clear sessions for a specific group
rm -rf data/sessions/{groupFolder}/.claude/
 
# Also clear the session ID from ClaudeClaw's tracking (stored in SQLite)
sqlite3 store/messages.db "DELETE FROM sessions WHERE group_folder = '{groupFolder}'"

To verify session resumption is working, check the logs for the same session ID across messages:

bash

grep "Session initialized" logs/claudeclaw.log | tail -5
# Should show the SAME session ID for consecutive messages in the same group

IPC Debugging

The container communicates back to the host via files in /workspace/ipc/:

bash

# Check pending messages
ls -la data/ipc/messages/
 
# Check pending task operations
ls -la data/ipc/tasks/
 
# Read a specific IPC file
cat data/ipc/messages/*.json
 
# Check available groups (main channel only)
cat data/ipc/main/available_groups.json
 
# Check current tasks snapshot
cat data/ipc/{groupFolder}/current_tasks.json

IPC file types:

messages/*.json - Agent writes: outgoing WhatsApp messages
tasks/*.json - Agent writes: task operations (schedule, pause, resume, cancel, refresh_groups)
current_tasks.json - Host writes: read-only snapshot of scheduled tasks
available_groups.json - Host writes: read-only list of WhatsApp groups (main only)

Sandbox Runtime Debugging

If RUNTIME=sandbox is set, agents run via @anthropic-ai/sandbox-runtime instead of containers.

Sandbox Architecture

Host (macOS/Linux)
───────────────────────────────────────────
src/orchestrator/sandbox-runner.ts
    │
    │ spawns sandboxed process via srt CLI
    │ with kernel-enforced filesystem/network
    │
    ├── CLAUDECLAW_GROUP_DIR → groups/{folder}
    ├── CLAUDECLAW_IPC_DIR → data/ipc/{folder}
    ├── CLAUDECLAW_PROJECT_DIR → project root (read-only)
    ├── CLAUDECLAW_GLOBAL_DIR → groups/global (read-only)
    └── CLAUDECLAW_EXTRA_DIR → additional mounts

Sandbox-Specific Issues

EPERM on all operations: The srt settings JSON file requires ALL fields including empty arrays (allowRead: []). Omit any field and the entire settings file silently fails validation — zero error messages.

Agent runner won't start (tsx/EPERM): Sandbox blocks Unix sockets needed by tsx. Fix: pre-compile with cd agent/runner && npx tsc, run with plain node.

Agent can't find paths: Check that CLAUDECLAW_*_DIR env vars are set in sandbox-runner.ts. The agent runner falls back to /workspace/* if env vars are missing.

Stale sessions after runtime switch: Switching a group between container and sandbox leaves stale session IDs. Fix: sqlite3 store/messages.db "DELETE FROM sessions"

Network blocked: Verify allowedDomains in the generated settings file includes api.anthropic.com. Check data/sandbox-settings/ for the last generated settings file.

Credential issues: Sandbox passes real credentials via env vars (not through the credential proxy). Ensure ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN is in .env.

Quick Diagnostic Script

Run this to check common issues:

bash

echo "=== Checking ClaudeClaw Agent 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 - add CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY to .env"
 
echo -e "\n2. Env file copied for container?"
[ -f data/env/env ] && echo "OK" || echo "MISSING - will be created on first run"
 
echo -e "\n3. Container runtime running?"
docker info &>/dev/null && echo "OK" || echo "NOT RUNNING - start Docker Desktop (macOS) or sudo systemctl start docker (Linux)"

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 95 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/debug/SKILL.md

Popularity

Repository stars: 173
Repository forks: 56
7-day trend score: 26

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Extension points

configConfiguration overrides

Learn the extensible skills standard

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/sbusso/claudeclaw/debug/badge)](https://verified-skill.com/skills/sbusso/claudeclaw/debug)

Something wrong with this skill or its page? Tell us.