11. 문제 해결
증상을 먼저 찾고, 확인 사항과 명령, 정상 결과 순서로 진행합니다.
11.1 ooo 명령이 인식되지 않음
확인: ooo는 Claude Code 세션 안에서만 동작합니다. 일반 터미널에 입력하지 않았는지 확인합니다. 로그인이 안 된 경우에도 동작하지 않으므로 /login을 먼저 마칩니다.
일반 터미널에서 plugin 상태를 확인합니다.
claude plugin list정상 결과: ouroboros@ouroboros가 enabled로 표시됩니다. 없거나 disabled면 아래 명령으로 다시 설치합니다.
claude plugin install ouroboros@ouroboros --force정상 결과: 설치 완료 후 Claude Code 세션을 다시 열면 ooo help가 동작합니다.
11.2 Interview는 되는데 run·status가 실패함
확인: plugin은 로드됐지만 Core의 MCP 서버가 연결되지 않은 상태일 수 있습니다. Claude Code에서 /mcp로 ouroboros 서버 상태를 확인합니다.
Claude Code 대화창에서 순서대로 실행합니다.
ooo setup
ooo update정상 결과: MCP 서버가 다시 등록됩니다. 등록 후 Claude Code를 완전히 닫고 다시 엽니다. 독립 CLI 설치라면 일반 터미널에서 ouroboros mcp info와 ouroboros status health로 상태를 확인합니다.
11.3 실행이 멈춘 것 같음
확인: 실행은 배경에서 오래 걸릴 수 있습니다. 먼저 상태를 조회합니다.
ooo status <session_id>정상 결과: 현재 단계가 표시됩니다. 진행이 없다고 판단되면 ooo cancel로 취소한 뒤 다시 실행합니다.
11.4 중단된 auto 재개
확인: ooo auto가 게이트나 오류로 멈추면 출력에 auto_session_id와 재개 명령이 남습니다.
ooo auto --resume <auto_session_id>정상 결과: 같은 자동 세션이 이어집니다. ID를 잃었다면 11.5의 세션 복구로 먼저 찾습니다.
11.5 닫힌 창의 세션 복구
확인: 실행 이벤트는 EventStore에 남아 있으므로 창이 닫혀도 세션을 찾을 수 있습니다.
ooo resume-session정상 결과: 진행 중이거나 일시정지된 세션 목록이 표시됩니다. 표시된 세션을 선택해 재개합니다.
11.6 같은 실패가 반복됨
확인: 반복 실행에서 같은 구조와 같은 실패가 이어지면, 반복을 늘리는 대신 접근을 바꿉니다.
ooo unstuck정상 결과: 현재 문제에 대해 다른 해결 접근이 제안됩니다. 어떤 접근을 쓸지는 사람이 선택합니다.
11.7 제거
일반 터미널에서 삭제 범위를 먼저 확인합니다.
ouroboros uninstall --dry-run정상 결과: 제거될 항목 목록이 표시됩니다. 실제 제거는 ouroboros uninstall로 실행하며, 데이터를 남기려면 --keep-data를 붙입니다. Claude Code plugin은 별도로 claude plugin uninstall ouroboros로 제거합니다.