11. 문제 해결
증상을 먼저 찾고, 확인 사항과 명령, 정상 결과 순서로 진행합니다.
-32000으로 플러그인이 기동하지 않음
증상: Failed to reconnect to plugin:ouroboros:ouroboros: -32000
버전부터 확인하세요. 이 기동 실패는 0.51.1에서 고쳐졌고, 그 릴리스 Highlights의 첫 항목입니다. 그 전에는 기존 환경이 [mcp] 프로필의 mcp==2.0.0을 가릴 수 있었습니다. 수정은 배포되는 런처가 uvx --isolated로 뜨게 하는 것입니다.
ooo update기대 결과: 0.51.1 이상이 됩니다. 이후 Claude Code를 완전히 닫았다가 다시 엽니다.
AUR 같은 제3자 패키지로 설치했다면 그쪽 버전을 먼저 확인하세요. 제3자 패키징은 여러 릴리스 뒤처져 있을 수 있습니다.
11.1 ooo 명령이 인식되지 않음
확인: ooo는 Claude Code 세션 안에서 동작합니다(Codex CLI·OpenCode도 설정을 마쳤다면 동일합니다 — 아래 확인 명령은 Claude Code plugin 경로 전용입니다). 일반 터미널에 입력하지 않았는지 확인합니다. 로그인이 안 된 경우에도 동작하지 않으므로 /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 서버 상태를 확인합니다.
MCP 서버 등록은 ooo setup이 아니라 plugin이 소유합니다. 일반 터미널에서 plugin부터 다시 설치합니다.
claude plugin install ouroboros@ouroboros --force정상 결과: plugin 재설치와 함께 MCP 서버 등록이 복구됩니다. Claude Code를 완전히 닫고 다시 연 뒤 /mcp를 다시 확인합니다.
그래도 연결되지 않으면 uvx --version으로 uv 설치를 확인합니다. plugin의 MCP 서버는 uvx로 기동하므로 uv가 없으면 등록이 있어도 연결에 실패합니다. 독립 CLI 설치라면 일반 터미널에서 ouroboros mcp doctor, 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로 제거합니다.