문제 해결¶

이 문서는 OWL CLI 및 OWL MCP Server의 일반적인 연동 문제를 해결하기 위한 가이드입니다.

CLI: owl을 찾을 수 없음¶

현상:

command not found: owl

처리 방법:

• Windows: 현재 PowerShell을 닫고 다시 열어서 실행
• Linux / macOS: 현재 터미널 창을 닫고 다시 열어서 실행
• 실행 파일이 기본 설치 디렉터리에 존재하는지 확인

기본 실행 파일 경로:

• Windows: %LOCALAPPDATA%\Programs\owl\owl.exe
• Linux / macOS: $HOME/.local/bin/owl, 쓰기 불가능한 경우 /usr/local/bin/owl로 대체

자동 설치: AI 도구에서 명령어를 실행할 수 없음¶

원인: 현재 AI 도구에 터미널 명령어 실행 권한이 없거나, 현재 환경에서 로컬 구성을 쓸 수 없음.

처리 방법:

• 터미널 명령어 실행을 지원하는 AI 도구로 변경
• 또는 수동 설치로 전환

자동 설치: 임시 인증 키가 유효하지 않음, 만료됨 또는 권한 없음¶

원인: OWL_TEMP_CODE가 만료되었거나, 이미 사용되었거나, 복사 오류가 발생했거나, 현재 계정에 인증 코드 생성 권한이 없음.

처리 방법:

• Guance 콘솔에서 임시 인증 키를 다시 생성
• 자동 설치의 설치 명령어를 다시 실행
• 이미 사용된 OWL_TEMP_CODE는 재사용하지 않음

자동 설치: Endpoint 불일치¶

원인: OWL_REGISTRY_ENDPOINT가 워크스페이스가 위치한 사이트와 일치하지 않거나, /api/v1이 잘못 추가됨.

처리 방법:

• 워크스페이스가 위치한 노드에 따라 OWL CLI Endpoint 재선택
• OWL_REGISTRY_ENDPOINT는 Endpoint 기본 주소만 입력
• 프라이빗 배포 환경의 경우 실제 배포에서 제공된 OWL CLI Endpoint를 사용

CLI: 인증 실패 또는 Endpoint에 접근할 수 없음¶

다음 항목을 확인:

• OWL_REGISTRY_ENDPOINT가 현재 사이트의 OWL CLI Endpoint인지 확인
• Endpoint에 /api/v1이 잘못 추가되었는지 확인
• 액세스 토큰이 유효한지 확인. OWL_API_KEY와 OWL_TOKEN 모두 액세스 토큰으로 사용 가능하며, 둘 다 설정된 경우 OWL_API_KEY가 우선 적용됨
• API Key에 해당 Open API 권한이 있는지 확인
• 현재 터미널에서 OWL CLI Endpoint에 접근 가능한지 확인

CLI: tool not found 오류¶

원인: 로컬 캐시에 해당 도구가 없거나 도구 이름을 잘못 입력함.

처리 방법:

owl sync
owl list

도구 이름을 확인한 후 다시 실행.

CLI: category not found 오류¶

원인: 카테고리 이름이 존재하지 않거나 아직 동기화되지 않음.

처리 방법:

owl sync
owl category list

CLI: missing required parameter 오류¶

원인: 필수 매개변수가 누락됨.

처리 방법:

owl show <도구명>

도구 정의에 따라 필수 매개변수를 모두 채운 후 다시 실행.

CLI: unknown parameter 오류¶

원인: 매개변수명이 도구 정의와 일치하지 않음.

처리 방법:

owl show <도구명>

매개변수명을 확인한 후 다시 실행.

CLI: owl validate가 검증 실패 반환¶

owl validate는 사전 검증만 수행하며 대상 도구를 호출하지 않습니다. JSON 결과의 request_executed는 항상 false여야 합니다.

검증 실패 결과와 검증 명령어 자체 실패를 구분하세요:

• JSON에 valid: false가 포함된 경우 도구를 실행하지 마십시오. issues의 kind와 code에 따라 매개변수를 수정하세요.
• 명령어가 0이 아닌 상태 코드로 종료되거나 검증 JSON 결과를 출력하지 않은 경우, 검증이 완료되지 않은 것입니다. 도구를 실행하지 마십시오. 동기화, 인증, 네트워크 또는 Registry 가용성을 확인한 후 검증을 다시 수행하세요.

valid: false 결과의 경우, issues의 kind와 code에 따라 처리하세요:

• tool / tool_not_found: 먼저 owl sync를 실행한 후, 도구 이름이 owl list 출력과 완전히 일치하는지 확인하세요.
• parameter / invalid_arguments: 문제 목록에 따라 누락된 매개변수, 잘못된 유형 또는 알 수 없는 매개변수를 한 번에 수정하세요.
• dql_syntax / dql.parseError: owl.data.query의 query_text를 수정하세요.
• generated_dql / dql.builderError: simple query의 select_clause, where_clause 또는 group_by_clause를 수정하고, 동일한 매개변수로 재시도하지 마세요.

validate 명령어가 없다는 메시지가 표시되면 1.2.0 이상 버전으로 업그레이드하세요. simple query DQL 생성 사전 검증은 1.2.1 이상 버전이 필요합니다.

CLI: 결과가 비어 있거나 예상과 다름¶

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

1. owl show <도구명>을 사용하여 매개변수 정의 확인
2. owl list -c <카테고리 ID>를 사용하여 올바른 도구를 실행했는지 확인
3. owl sync로 로컬 캐시 새로고침
4. 쿼리 시간 범위가 올바른지 확인. 시간 매개변수는 13자리 밀리초 타임스탬프여야 함
5. API Key에 해당 리소스의 Open API 권한이 있는지 확인

MCP: 클라이언트 연결 실패¶

다음 항목을 확인:

• MCP 유형이 streamableHttp로 구성되었는지 확인
• URL이 현재 사이트의 OWL MCP Endpoint인지 확인
• URL이 /mcp로 끝나는지 확인
• 요청 헤더에 Authorization: Bearer <API Key>가 포함되어 있는지 확인
• 클라이언트가 위치한 네트워크에서 OWL MCP Endpoint에 접근 가능한지 확인

MCP: 인증 실패¶

다음 항목을 확인:

• API Key가 올바르게 복사되었는지 확인
• Authorization Header 형식이 올바른지 확인
• API Key가 비활성화, 삭제 또는 교체되었는지 확인
• API Key가 속한 워크스페이스가 현재 접근하려는 워크스페이스인지 확인

요청 헤더 형식:

Authorization: Bearer <API Key>

참고: /mcp 엔드포인트는 이벤트 스트림을 설정하기 전에 먼저 인증을 수행합니다. 자격 증명이 없거나 유효하지 않은 경우, text/event-stream 이벤트 스트림을 열지 않고 HTTP 401 Unauthorized(및 WWW-Authenticate: Bearer realm="mcp" 응답 헤더 포함)를 직접 반환합니다. 따라서 클라이언트가 "연결되었지만 이벤트 스트림이 비어 있음"을 보고하는 경우, 실제로 401을 수신했는지 먼저 확인해야 합니다. 이는 일반적으로 빈 스트림이 아닌 인증 문제이므로, 401 및 WWW-Authenticate 헤더를 기반으로 자격 증명을 수정한 후 재시도하세요.

MCP: 도구 목록이 비어 있음¶

가능한 원인:

• MCP 클라이언트가 서비스에 성공적으로 연결되지 않음
• API Key가 유효하지 않거나 권한이 부족함
• 클라이언트가 MCP 도구 목록을 새로고침하지 않음
• Endpoint 선택 오류

처리 방법:

1. 클라이언트에서 MCP 연결을 다시 테스트
2. Endpoint가 워크스페이스 사이트와 일치하는지 확인
3. Authorization Header가 올바른지 확인
4. MCP 클라이언트를 다시 로드하거나 재시작

MCP: 도구 호출 시 권한 오류 반환¶

원인: API Key에 해당 Open API 권한이 없음.

처리 방법:

• API Key 권한 범위 확인
• 읽기 전용 시나리오에 해당하는 쿼리 권한 부여
• 쓰기 시나리오에 해당하는 쓰기 권한 부여
• Agent에 과도하게 넓은 API Key 권한을 직접 부여하지 않는 것을 권장

MCP: 도구 호출 시 빈 결과 반환¶

다음 순서대로 확인:

1. 쿼리 시간 범위가 올바른지 확인
2. 선택한 데이터 도메인, source, field, index가 존재하는지 확인
3. owl.metric.list, owl.log_index.list와 같은 탐색 도구를 먼저 호출해야 하는지 확인
4. API Key에 해당 데이터 범위의 읽기 권한이 있는지 확인
5. 현재 워크스페이스에 실제로 해당 데이터가 존재하는지 확인

MCP: 쓰기 작업이 차단되거나 적용되지 않음¶

가능한 원인:

• API Key에 쓰기 권한이 없음
• 클라이언트에 수동 확인이 설정되었지만 확인되지 않음
• 매개변수 구조가 도구 요구 사항과 일치하지 않음
• 워크스페이스 측에 승인 또는 감사 제한이 있음

처리 방법:

1. 도구 매개변수 확인
2. API Key 권한 확인
3. 클라이언트가 수동 확인을 기다리고 있는지 확인
4. 워크스페이스 측 승인, 감사 또는 권한 구성 확인