클로드스킬마트스킬 둘러보기스킬이 뭐예요?
 
← 목록으로

NanoClaw 컨테이너 디버그

NanoClaw 에이전트 컨테이너의 로그, 세션 DB, 마운트, 인증 문제를 단계적으로 진단하는 디버깅 가이드 스킬입니다.

개발·코딩고급★ 30,471⑂ 12,865AI 점수 7/10마지막 업데이트: 2026. 8. 9.

무엇을 해주나

NanoClaw의 컨테이너 기반 에이전트 실행 시스템이 오작동할 때 원인을 찾아내는 전용 디버깅 안내서입니다. 호스트(Node)와 컨테이너(Bun) 사이의 유일한 통신 경로인 두 개의 세션 DB(inbound.db, outbound.db) 구조를 설명하고, 메시지가 어느 단계에서 끊겼는지 SQL 한 줄로 확인하는 방법을 제시합니다.

  • 아키텍처 다이어그램과 마운트 경로(/workspace, /home/node/.claude, /app/src) 정리
  • 호스트 에러 로그·앱 로그·셋업 로그 위치표와 LOG_LEVEL=debug 활성화 방법
  • 자주 발생하는 4가지 문제(중복 서비스 인스턴스로 인한 메시지 유실, 컨테이너 즉시 종료, 마운트 오류, 하트비트 기반 stale 세션) 진단·복구 절차
  • 컨테이너 재시작, 이미지 재빌드, 세션 초기화, 그리고 한 번에 돌리는 진단 스크립트

이런 분께 추천

  • NanoClaw를 직접 운영하거나 포크해서 개발 중인 사람
  • 컨테이너로 에이전트를 격리 실행하는 아키텍처의 장애 대응 패턴을 참고하고 싶은 개발자
  • Docker/systemd/SQLite 로그 추적에 익숙한 중·상급 운영자

활용 예시

  1. "봇이 답을 안 해요" → 스킬이 messages_in과 messages_out을 순서대로 조회해 메시지가 컨테이너에 도달했는지, 응답이 생성됐는지, 전달 단계에서 유실됐는지 구분해 줍니다.
  2. "API에서 401이 떨어져요" → OneCLI 게이트웨이의 secretMode가 selective인지 확인하고 onecli agents set-secret-mode 로 해결하도록 안내합니다.
  3. "세션이 계속 processing 상태예요" → .heartbeat 파일의 mtime을 확인해 컨테이너가 실행 도중 죽었는지 판별하고 ncl groups restart 로 복구합니다.

· · · 설치 가이드 · · ·

Claude 앱에 설치 (터미널 필요 없음)
  1. 아래 버튼으로 ZIP 파일을 받으세요.
  2. Claude 설정 → Capabilities에서 '코드 실행 및 파일 생성'을 켭니다. (한 번만)
  3. Claude에서 Customize → Skills → + → '스킬 업로드'를 누르고 받은 ZIP을 올립니다.
↓ ZIP 내려받기
Claude Code에 설치

Claude에게 맡기기 — 아래 문장을 Claude Code에 붙여넣으세요

클로드스킬마트에서 찾은 스킬을 설치해줘.
GitHub 저장소 nanocoai/nanoclaw 의 .claude/skills/debug 폴더를 내 ~/.claude/skills/debug/ 에 그대로 복사해줘.
설치가 끝나면 이 스킬로 무엇을 할 수 있는지 한 줄로 알려줘.

직접 명령으로 설치하기

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

⚠ 제3자가 만든 스킬입니다. 설치 전 원본 저장소를 한 번 확인하세요.

  1. 터미널을 열고 작업용 폴더로 이동합니다.
  2. 저장소를 내려받습니다: git clone https://github.com/nanocoai/nanoclaw
  3. 스킬 폴더를 만듭니다: mkdir -p ~/.claude/skills/debug
  4. 파일을 복사합니다: cp -r nanoclaw/.claude/skills/debug/* ~/.claude/skills/debug/
  5. Claude Code를 다시 실행한 뒤 "컨테이너가 응답하지 않아, 디버그해줘" 같이 말하면 스킬이 호출됩니다.
  6. 이 스킬은 NanoClaw 저장소 안에서 실행할 때 가장 잘 작동합니다. Docker와 pnpm, ncl CLI가 준비돼 있는지 먼저 확인하세요.
  7. 문서에 나오는 rm -rf data/v2-sessions/... 나 systemctl --user stop 명령은 되돌릴 수 없으니 실행 전 대상 경로와 서비스 이름을 꼭 확인하세요.
GitHub에서 원본 보기 ↗라이선스: MIT