문제 해결

무언가 작동하지 않을 때 가장 빠른 진단은 언제나:

/prism:status

이 명령은 API 키 접두사, Prism이 설정된 스코프, 실제 적용 중인 엔드포인트, OTEL 변수가 올바른지를 출력합니다. 대부분의 문제가 여기서 드러납니다.

더 깊이 살펴보려면 디버그 로그를 tail 하세요. 이 로그는 항상 기록됩니다:

tail -f "${CLAUDE_PLUGIN_DATA:-$HOME/.prism/logs}/debug.log"

디버그 출력을 터미널(stderr)로도 함께 보려면 ~/.prism/config.json에 "debug": true를 넣으세요. 켜져 있는지와 정확한 기록 파일은 /prism:doctor가 알려 줍니다.

`/prism:help`이 “unknown command”를 반환합니다

플러그인이 로드되지 않은 것입니다.

설치 여부를 확인하세요: /plugin → Installed에서 prism@optra-prism을 찾으세요.
Claude Code를 재시작하세요.

그래도 없으면 재설치하세요:

/plugin marketplace add grumatic/optra-prism-plugin
/plugin install prism

그리고 재시작하세요.

또한 Node.js 18 이상이 PATH에 있는지 확인하세요. 훅 스크립트에는 네이티브 fetch가 필요합니다.

”No API key configured” 또는 “Invalid API key format”

session-start 훅은 유효한 prism_* 키를 찾을 수 없을 때 이 중 하나를 출력합니다.

/prism:setup prism_YOUR_KEY를 실행하세요.
/prism:status로 확인하세요. prism_abc12… 접두사가 표시되어야 합니다.
대시보드 헤더의 Connect 패널을 열어, 거기 표시된 /prism:setup 명령(키가 이미 들어 있습니다)을 그대로 다시 실행해 키가 유효한지 확인하세요.

대시보드에 텔레메트리가 없습니다

다음 목록을 순서대로 확인하세요:

/prism:status를 실행하세요. Scope: none이 표시되면 OTEL env 변수가 아직 설치되지 않은 것입니다. /prism:setup prism_YOUR_KEY를 다시 실행하고 Claude Code를 재시작하세요.
셋업 후 Claude Code를 재시작했나요? OTEL env 변수는 프로세스 시작 시 읽히므로, 이미 실행 중이던 세션은 이를 반영하지 못합니다.
/prism:status에서 엔드포인트 경고를 확인하세요. ingest URL이 잘못되어 보이면 키로 /prism:setup을 다시 실행하고 세션을 재시작하세요. 주소와 키가 함께 재설정됩니다.
몇 분 기다리세요. 턴이 끝나고 대시보드에 표시되기까지 짧은 지연이 있습니다.
네트워크 연결 확인. 셸에서: curl -sSI https://ingest.optra-prism.com/health. 실패한다면 사용 중인 네트워크가 Prism으로 나가는 트래픽을 막고 있는 것입니다.

`/prism:status`가 “Scope: both”를 보고합니다

OTEL 변수가 ~/.claude/settings.json과 .claude/settings.local.json 둘 다에 존재합니다. 이들은 조용히 병합되지만, 두 스코프가 경쟁한다는 뜻이며 Claude Code를 어디서 여느냐에 따라 하나만 이깁니다.

/prism:setup을 다시 실행하세요. 이 명령은 스코프 하나를 고르도록 안내하고 다른 하나를 제거합니다.

경고: “OTEL vars found in `.claude/settings.json` (shared)”

플러그인은 공유되고 커밋되는 .claude/settings.json에 OTEL 변수를 결코 기록하지 않습니다. OTLP 헤더가 prism_* 키를 담고 있기 때문입니다. /prism:status가 이 경고를 띄우면, 변수가 수동으로(아마 다른 설정 파일에서 복사되어) 거기에 들어갔고 git에 커밋되었을 수 있다는 뜻입니다.

프로젝트의 공유 .claude/settings.json에서 OTEL_* 항목을 제거하세요.
파일이 커밋되었다면 prism_* 키가 유출된 것으로 보고, 대시보드의 지원 창구로 문의해 키를 교체한 뒤 새 키로 /prism:setup을 다시 실행하세요.
/prism:setup을 다시 실행해 올바른 스코프(user 또는 project)에 변수를 재설치하세요.

전체 규칙은 설치 스코프를 참고하세요.

실시간 요약이 나타나지 않습니다

실시간 요약은 기본값이 꺼짐입니다. 켜려면:

/prism:config set show_realtime_summary true

켰는데도 안 나오면 디버그 로그를 확인하세요. 디버그 로깅 활성화 여부와 기록 파일은 /prism:doctor가 알려 줍니다.

전부 초기화

다른 방법이 모두 실패하면 깨끗하게 초기화하세요:

/prism:uninstall을 실행합니다. 무엇을 지울지 먼저 보여 준 뒤, 지금 제거하는 스코프에서 Prism이 소유한 것만 제거합니다.
재설치: /plugin install prism@optra-prism
/prism:setup prism_YOUR_KEY 실행
Claude Code를 재시작하세요.