revka doctor, status, self-test
상태 점검, 설정 유효성 검사, 트레이스 조회, 자가 테스트 스위트.
Revka는 세 가지 서로 다른 질문에 답하는 세 가지 진단 명령을 제공합니다. **revka doctor**는 설정, 워크스페이스, 실행 중인 데몬을 검사하고, **revka status**는 에이전트 설정 상태를 한 화면에 요약하여 출력하며 Docker 헬스 프로브로도 사용할 수 있습니다. **revka self-test**는 새로 설치한 환경이 엔드 투 엔드로 정상 작동하는지 확인합니다. revka status(기본 보고서)와 revka self-test --quick은 완전히 오프라인에서 실행됩니다. revka doctor는 로컬 Kumiho CE 백엔드가 설정된 경우를 제외하면 오프라인입니다. revka self-test(--quick 없이)와 revka doctor models는 기본적으로 네트워크 점검을 수행하므로 실행 중인 게이트웨이가 필요합니다. 세 명령 모두 언제든지 안전하게 호출할 수 있습니다. 단, revka self-test는 메모리 쓰기/삭제 라운드 트립을 일시적으로 수행하고, revka doctor는 임시 워크스페이스 탐색 파일을 기록한다는 점에 유의하세요.
이 페이지는 커맨드 라인에서 Revka 인스턴스를 진단할 때 참조하는 레퍼런스입니다. 이 점검들에 데이터를 제공하는 메트릭 및 트레이싱 백엔드에 대해서는 관찰 가능성 및 트레이싱을 참고하세요.
revka doctor
섹션 제목: “revka doctor”revka doctor는 구조화된 다중 범주 진단을 실행하고, 범주별로 심각도 지표(ok, warn, error)가 표시된 사람이 읽기 쉬운 보고서를 출력합니다. 마지막에는 12 ok, 2 warnings, 0 errors와 같은 요약 줄이 표시됩니다.
revka doctor내부적으로 각 점검은 DiagResult { severity, category, message }를 생성하므로, 동일한 진단 결과가 대시보드의 doctor 페이지와 CLI 양쪽에서 모두 사용됩니다. 대시보드 화면에 대해서는 로그, 감사, doctor, 페어링 및 스킨을 참고하세요.
진단 범주
섹션 제목: “진단 범주”revka doctor는 다음 범주를 점검합니다. warn은 정보성으로 실행 실패를 유발하지 않으며, error는 배포 전에 수정해야 할 문제를 나타냅니다.
| 범주 | 점검 항목 |
|---|---|
config | 설정 파일 존재 여부, 프로바이더 유효성, API 키 존재 여부, 기본 모델 설정, 온도 범위(0.0–2.0), 게이트웨이 포트 유효성, 폴백 프로바이더 유효성, 모델 라우트 유효성, 임베딩 라우트 유효성, 채널 최소 1개 설정 여부, 위임 에이전트 프로바이더 유효성 |
workspace | 디렉터리 존재 및 쓰기 가능 여부, 디스크 공간(100 MB 미만 시 경고), SOUL.md 존재 여부(없으면 경고), AGENTS.md 존재 여부(없으면 경고) |
daemon | 상태 파일 존재 여부, 하트비트 최신성, 스케줄러 상태, 채널별 최신성 |
environment | git이 PATH에 있는지, $SHELL 설정 여부, $HOME/$USERPROFILE 설정 여부, curl이 PATH에 있는지 |
sidecars | Kumiho가 활성화된 경우 — venv Python 존재 여부, kumiho 패키지 임포트 가능 여부, kumiho_memory 패키지 임포트 가능 여부 |
kumiho | 로컬 커뮤니티 에디션의 경우 — GET /api/_live와 GET /api/_health 탐색(Neo4j, Redis 이벤트 스트림, 임베딩 준비 상태) |
cli-tools | PATH에서 설정된 CLI 도구 탐색 |
config 범주는 키 존재 여부만 확인하는 것이 아니라 실제 유효성 검사를 수행합니다. provider_validation_error는 프로바이더를 실제로 생성해 보며, 모델/임베딩 라우트와 위임 에이전트 프로바이더도 실제로 해석합니다. 이 때문에 revka doctor는 배포 전 게이트로도 유용하게 활용할 수 있습니다.
revka doctor models
섹션 제목: “revka doctor models”models 서브커맨드는 설정된 모든 프로바이더(또는 지정한 단일 프로바이더)의 라이브 모델 카탈로그를 탐색하고, 프로바이더별 상태, 모델 수, 상세 메시지를 포함한 연결 매트릭스를 출력합니다.
revka doctor models # probe all configured providersrevka doctor models --provider anthropic # probe one providerrevka doctor models --provider openrouter --use-cache| 플래그 | 의미 |
|---|---|
--provider <ID> | 지정한 프로바이더만 탐색합니다. 기본값: 알려진 모든 프로바이더. |
--use-cache | 강제 라이브 갱신을 건너뛰고 캐시된 카탈로그를 우선 사용합니다. |
프로바이더별 결과는 다음과 같이 분류되며, 오류가 아닌 결과가 항상 실패를 의미하지는 않습니다.
ok— 카탈로그 가져오기 성공, 모델 수 보고됨.skipped— 해당 프로바이더가 라이브 모델 검색을 지원하지 않음(오류가 아님).auth/access— HTTP 401/403/429,unauthorized,rate limit, 또는insufficient quota. 대개 API 키가 없거나 유효하지 않은 경우입니다.error— 기타 모든 실패(연결 오류, 잘못된 형식의 응답 등).
revka doctor traces
섹션 제목: “revka doctor traces”traces 서브커맨드는 관찰 가능성 레이어가 기록하는 런타임 트레이스 JSONL 파일을 쿼리합니다. 최신 이벤트부터 내림차순으로 나열하며(타임스탬프, id, 이벤트 타입, 성공 여부, 메시지 미리보기), UUID로 단일 이벤트를 지정하면 전체 페이로드를 조회할 수 있습니다.
revka doctor traces # 20 most recent eventsrevka doctor traces --limit 50 # show 50 eventsrevka doctor traces --event tool_call # filter by event typerevka doctor traces --contains "shell" # case-insensitive text searchrevka doctor traces --event tool_call --contains "timeout"revka doctor traces --id <trace-id> # full payload for one event| 플래그 | 의미 |
|---|---|
--limit <N> | 표시할 최대 이벤트 수. 기본값: 20. |
--event <TYPE> | 정확한 event_type으로 필터링합니다(대소문자 구분 없음). |
--contains <TEXT> | event_type, message, payload, channel, provider, model에서 부분 문자열 검색합니다. |
--id <UUID> | 단일 이벤트를 가져와 전체 페이로드를 pretty JSON으로 출력합니다. 다른 필터는 무시됩니다. |
각 RuntimeTraceEvent는 id(UUID), timestamp(RFC 3339), event_type, 선택적 필드인 channel / provider / model / turn_id / success / message, JSON payload를 포함합니다. 목록 뷰에서는 메시지 미리보기가 잘리며, --id를 사용하면 전체 페이로드를 확인할 수 있습니다.
revka status
섹션 제목: “revka status”revka status는 현재 인스턴스의 설정 상태를 한 화면에 요약하여 출력합니다. 설정과 로컬 상태만 읽으며, 사람이 읽는 출력을 위해 데몬이 필요하지 않습니다.
revka status보고서에는 다음 정보가 포함됩니다.
- 버전, 워크스페이스 경로, 설정 경로
- 프로바이더 및 모델, 설정된 관찰 가능성 백엔드 및 트레이스 저장 모드/경로
- 자율성 수준 및 런타임 종류(
native/docker) - 서비스 상태(실행 중 / 중지됨), 하트비트 인터벌, 자동 저장 상태를 포함한 유효 메모리 백엔드
- 보안 — 워크스페이스 전용 플래그, 허용된 루트, 허용된 명령, 시간당 최대 액션 수, 비용 추적(활성화된 경우 오늘/이번 달 지출 대비 한도), OTP 상태, e-stop 상태
- 채널 — 설정된 모든 채널 및 설정 완료 여부
status —format exit-code
섹션 제목: “status —format exit-code”스크립트, 모니터, Docker HEALTHCHECK에서 사용하려면 --format exit-code를 전달하세요. 사람이 읽는 보고서를 건너뛰고 설정된 게이트웨이에 경량 GET /health 요청을 수행하며, 게이트웨이가 정상이면 0, **그렇지 않으면 1**로 종료합니다.
revka status --format exit-codeDocker Compose의 컨테이너 라이브니스 점검으로 연결하려면 다음과 같이 구성하세요.
healthcheck: test: ["CMD", "revka", "status", "--format=exit-code"] interval: 60s timeout: 10s retries: 3 start_period: 10s이것이 컨테이너화된 배포의 표준 라이브니스 점검 방식입니다. 전체 컨테이너 설정은 Docker, Compose & one-click PaaS를 참고하세요.
revka self-test
섹션 제목: “revka self-test”revka self-test는 설치가 실제로 작동하는지 확인합니다. SQLite 메모리 데이터베이스를 열고, 프로바이더 및 도구 레지스트리를 로드하고, 보안 정책을 파싱하며, 전체 모드에서는 게이트웨이와 메모리 라운드 트립도 검증합니다. 점검 중 하나라도 실패하면 종료 코드 1로 종료되므로, 설치 후 또는 CI 게이트로 활용하기에 적합합니다.
revka self-test실행 중인 게이트웨이가 필요한 네트워크 점검을 포함한 모든 점검을 실행합니다.
revka self-test --quick네트워크 점검(게이트웨이 상태, 메모리 라운드 트립, WebSocket 핸드셰이크)을 건너뜁니다. 데몬이 실행 중이지 않은 오프라인 또는 CI 환경에서의 유효성 검사에 적합합니다.
| 플래그 | 의미 |
|---|---|
--quick | 모든 네트워크 점검을 건너뜁니다 — 게이트웨이 상태 점검, 메모리 라운드 트립, WebSocket 핸드셰이크 없음. |
점검 항목
섹션 제목: “점검 항목”항상 실행되는 빠른 스위트(quick suite)가 포함하는 항목:
- config — 설정 파일이 존재하고, 로드되며, 파싱됩니다.
- workspace — 워크스페이스 디렉터리가 존재하고 쓰기 가능합니다(임시 파일로 탐색).
- sqlite —
memory.db가 열리고 쿼리에 응답합니다. - providers — 프로바이더 레지스트리에 항목이 있습니다.
- tools — 핵심 도구 레지스트리에 항목이 있습니다.
- channels — 채널 설정이 로드됩니다(채널 타입과 설정된 개수를 보고).
- security — 보안 정책이 파싱됩니다(자율성 수준 보고).
- version — 버전 정합성 점검.
전체 스위트는 세 가지 네트워크 점검을 추가합니다(--quick으로 건너뜀):
- gateway — 설정된 게이트웨이에 대한
GET /health가 성공을 반환합니다. - memory — 활성 메모리 백엔드를 통한 쓰기 / 읽기 / 삭제 라운드 트립.
- websocket —
ws://<host>:<port>/ws/chat에 대한 WebSocket 핸드셰이크.
출력은 점검별 통과/실패 표시와 요약 줄(All N checks passed. 또는 N/M checks failed.)이 포함된 번호 매기기 표입니다. 비정상 종료는 최소 하나의 점검이 실패했음을 의미합니다.