클로드스킬마트스킬 둘러보기바로 쓰는 문장영상으로 배우기터미널 사용법스킬이 뭐예요?
 
← 목록으로

NanoClaw 컨테이너 디버깅

NanoClaw의 세션 컨테이너가 응답하지 않거나 인증·마운트 문제가 생겼을 때 로그와 세션 DB를 따라가며 원인을 찾아주는 디버깅 가이드.

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

무엇을 해주나

NanoClaw의 호스트-컨테이너 구조(inbound.db / outbound.db 두 개의 세션 DB를 통한 메시지 흐름)를 전제로, 문제가 생겼을 때 어디를 봐야 하는지 순서대로 안내합니다.

  • 로그 위치 표: logs/nanoclaw.error.log, logs/nanoclaw.log, 설치 단계별 로그
  • LOG_LEVEL=debug로 컨테이너 stderr까지 스트리밍하는 방법
  • scripts/q.ts 래퍼로 messages_in / messages_out / processing_ack 조회
  • 대표 장애 4종(중복 서비스 인스턴스로 인한 메시지 유실, 컨테이너 즉시 종료·401 인증, 마운트 경로, heartbeat 기반 stale 세션)
  • ncl CLI로 세션·그룹 재시작, 이미지 재빌드, 세션 초기화
  • 마지막에 7단계 빠른 진단 셸 스크립트 제공

이런 분께 추천

  • NanoClaw를 셀프호스팅하며 텔레그램/시그널 봇이 갑자기 답을 안 할 때 원인을 찾아야 하는 운영자
  • 컨테이너 기반 에이전트 실행 구조를 이해하고 기여하려는 개발자
  • Docker + SQLite + systemd/launchd 환경에 익숙한 중급 이상 사용자

활용 예시

  1. "봇이 답을 안 해" → 에러 로그에서 No adapter for channel type 확인 → ps aux로 중복 인스턴스 발견 → 오래된 서비스 stop/disable.
  2. "에이전트가 401을 뱉는다" → OneCLI 게이트웨이 상태 확인 후 onecli agents set-secret-mode --mode all로 시크릿 주입.
  3. "세션이 계속 processing 상태" → .heartbeat mtime을 stat으로 확인해 컨테이너가 중간에 죽었는지 판별 후 ncl groups restart.

· · · 설치 가이드 · · ·

설치 없이 지금 한 번 써보기

아래를 Claude에 붙여넣으면 설치하지 않고도 이 스킬을 그대로 씁니다.

이 파일의 지시를 읽고 그대로 따라서 나를 도와줘:
https://raw.githubusercontent.com/nanocoai/nanoclaw/HEAD/.claude/skills/debug/SKILL.md

내가 원하는 것: (여기에 하고 싶은 일을 쓰세요)

Claude가 링크를 열지 못하면, 링크를 직접 열어 내용을 복사해 붙여넣으세요.

↓ 쓸 만하면 아래에서 ZIP을 받아 설치하세요. 그러면 매번 붙여넣지 않아도 알아서 작동합니다.

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.git && mkdir -p ~/.claude/skills/debug && cp -r nanoclaw/.claude/skills/debug/* ~/.claude/skills/debug/

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

  1. 터미널을 열고 NanoClaw 저장소를 클론합니다: git clone https://github.com/nanocoai/nanoclaw.git
  2. 스킬 폴더를 만듭니다: mkdir -p ~/.claude/skills/debug
  3. 스킬 파일을 복사합니다: cp -r nanoclaw/.claude/skills/debug/* ~/.claude/skills/debug/
  4. 다만 이 스킬은 NanoClaw 저장소 안에서 쓰는 것이 정석입니다. 이미 NanoClaw를 운영 중이라면 별도 복사 없이 프로젝트 루트에서 Claude Code를 실행하면 자동으로 인식됩니다.
  5. Claude Code를 재시작하고 /skills 또는 "컨테이너가 응답을 안 해" 같은 문장으로 발동을 확인합니다.
  6. 사전 준비: Docker(또는 호환 런타임) 실행 중, pnpm 설치, ncl·onecli 명령 사용 가능 상태여야 대부분의 절차가 동작합니다.
GitHub에서 원본 보기 ↗라이선스: MIT