진단은 세 단 사다리입니다. geode doctor가 환경을 점검하고, geode about이 실효 상태를 보여주고, geode config explain이 설정이 어느 레이어에서 가려졌는지 밝힙니다. 대부분의 문제는 이 사다리를 위에서 아래로 내려가면 잡힙니다.
진단 사다리
1. geode doctor # Python, PATH, 자격, 데몬 상태 2. geode about # EFFECTIVE 모델, 경로, 소켓, 마스킹 경고 3. geode config explain model # 레이어별 후보와 WINNER 4. pkill -f "geode serve" # 오래된 데몬 정리 후 재진입 5. geode setup -r # 그래도 안 되면 설정을 처음부터
geode config explain은 한 설정 키에 대해 os.environ, 프로젝트 .env, 전역 .env, 프로젝트 config.toml, 전역 config.toml, 코드 기본값 순서로 후보를 표로 보여주고 어느 레이어가 이기는지 표시합니다 (core/config/explain.py). 검증은 항상 실효값 기준입니다. config.toml의 내용이 아니라 geode about이 답입니다.
증상, 원인, 해법
| 증상 | 원인 | 해법 |
|---|---|---|
| 모델을 바꿨는데 그대로 | 상위 레이어(.env 잔존 줄, 셸 export)가 toml을 가림 | geode config explain model로 WINNER 레이어를 찾아 그 줄을 지웁니다. |
| 배너 모델과 응답 모델이 다름 | 데몬이 둘 이상 떠서 소켓 경합 | pkill -f "geode serve" 후 pgrep -f "geode serve"로 비었는지 확인하고 재진입합니다. ps aux | grep은 긴 경로가 잘려 빈 결과를 줍니다. |
| 응답이 비거나 인증 오류 | 자격 만료 또는 무효 | geode doctor가 키와 OAuth 유효성을 점검합니다. /login으로 갱신합니다. |
응답이 비고 종료 이유가 model_refusal | 모델 안전 분류기가 거절 (HTTP 200, stop_reason: refusal) | 요청을 바꿔 다시 묻거나 /model로 다른 모델을 씁니다. 카테고리가 메시지에 표시됩니다. |
context_exhausted로 종료 | prune 후에도 컨텍스트 critical | /compact 또는 /clear 후 작업을 쪼갭니다. 장기 실행 안전 참고. |
| MCP 도구가 안 보임 | MCP 서버 연결 실패 | /mcp로 서버 상태와 도구 목록을 확인합니다. /status에도 MCP 블록이 있습니다. |
MCP_SERVER_FAILED 로그가 반복됨 | serve 프로세스에서 MCP 명령(npx, codex, uvx)이나 필수 env를 못 찾음 | ~/.geode/logs/serve.log에서 실패 서버 이름을 보고 PATH와 .env를 맞춥니다. 실패한 서버는 짧게 캐시되므로 수정 뒤에는 serve를 재시작합니다. |
| 읽기 도구가 너무 자주 호출됨 | read_document, grep_files는 항상 로드되는 핵심 도구. tool cap에 숨은 것이 아님 | dialogue transcript의 tool call을 보고 질문에 파일 범위, 제외 경로, 원하는 깊이를 명시합니다. |
| 메신저 무반응 | 게이트웨이 또는 binding 문제 | geode doctor slack과 메신저 연동의 실패 표를 따릅니다. |
로그 위치
| 무엇 | 어디 |
|---|---|
| serve 데몬 로그 (10MB × 5 로테이션) | ~/.geode/logs/serve.log |
| geode-mcp, 워커, 캠페인 로그 | ~/.geode/logs/ |
| 세션별 lifecycle event | sessions.db:hook_events |
| 세션 transcript (턴 단위 대화) | ~/.geode/transcripts/<project-slug>/ |
| 비용 ledger | ~/.geode/usage/YYYY-MM.jsonl |
로그 채널 구성은 core/observability/logging_config.py의 configure_logging(mode)가 SoT입니다.