문제 해결¶

이 문서는 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로 대체됩니다.

CLI: 이전 testing 빌드를 업그레이드할 수 없음¶

owl --version이 testing-<SHA>를 표시하면 현재 채널에 업데이트된 설치 스크립트가 있는지 확인한 후 owl update를 실행하세요. CLI를 먼저 교체하거나 채널을 변경할 필요가 없습니다.

failed to parse local owl version 또는 failed to read local owl version이 나오면 owl --version이 정상 실행되고 지원되는 릴리스 버전 또는 testing- 뒤에 7~40자리 16진수 Git SHA를 반환하는지 확인하세요. 알 수 없거나 손상되었거나 실행에 실패한 버전을 이전 버전으로 취급하여 덮어쓰지 않습니다. 원인을 확인한 뒤 수동 설치를 사용하세요.

자동 설치: AI 도구가 명령을 실행할 수 없음¶

원인: 현재 AI 도구에 터미널 명령 실행 권한이 없거나, 현재 환경에서 로컬 구성을 쓸 수 없도록 금지되어 있습니다.

처리 방법:

• 터미널 명령 실행을 지원하는 AI 도구로 변경합니다.
• 또는 수동 설치로 변경합니다.

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

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

처리 방법:

• Guance 콘솔에서 임시 인증 코드를 다시 생성합니다.
• 자동 설치의 설치 명령을 다시 실행합니다.
• 이미 사용한 OWL_TEMP_CODE는 재사용하지 마십시오.

자동 설치: 엔드포인트 불일치¶

원인: OWL_REGISTRY_ENDPOINT가 워크스페이스가 속한 사이트와 일치하지 않거나, /api/v1이 잘못 추가되었습니다.

처리 방법:

• 워크스페이스가 속한 노드에 따라 OWL CLI 엔드포인트를 다시 선택합니다.
• OWL_REGISTRY_ENDPOINT에는 엔드포인트 루트 주소만 입력합니다.
• 프라이빗 배포 환경에서는 실제 배포에서 제공하는 OWL CLI 엔드포인트를 사용하십시오.

CLI: 인증 실패 또는 엔드포인트에 접근할 수 없음¶

다음 항목을 확인하십시오:

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

CLI: HTTPS 인증서 확인 실패¶

로컬 개발 또는 프라이빗 테스트 환경에서 자체 서명된 인증서를 사용하는 경우, CLI가 x509: certificate signed by unknown authority를 반환할 수 있습니다. 신뢰할 수 있는 CA를 시스템에 설치하는 것이 우선입니다. 실제로 설치할 수 없는 경우 임시로 다음을 실행하십시오:

owl config set registry.insecure_skip_verify true

이 설정은 Registry의 신원 확인을 비활성화하므로 중간자 공격에 취약해질 수 있습니다. 통제된 개발 환경에서만 사용하고, 프로덕션 환경에서는 절대 활성화하지 마십시오. 확인을 복원하려면 owl config set registry.insecure_skip_verify false를 실행하십시오.

CLI: 장시간 쿼리 조기 시간 초과¶

데이터 쿼리가 context deadline exceeded를 반환하는 경우, 먼저 네트워크와 Registry 상태를 확인한 다음 registry.request_timeout 값을 확인하십시오. 이 값의 단위는 밀리초이며, 기본값은 150000입니다. 데이터 쿼리 도구의 서버 측 제한 시간은 130초이므로, 클라이언트 측 총 시간 초과를 더 짧게 설정하지 않는 것이 좋습니다.

owl config set registry.request_timeout 180000

클라이언트 시간 초과를 늘려도 서버 측 쿼리 제한 시간이 연장되지는 않습니다. 쿼리가 여전히 실패하면 시간 범위를 좁히거나, 반환량을 줄이거나, 쿼리 조건을 단순화하십시오.

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 엔드포인트인지 확인합니다.
• URL이 /mcp로 끝나는지 확인합니다.
• 요청 헤더에 Authorization: Bearer <API Key>가 포함되어 있는지 확인합니다.
• 클라이언트가 있는 네트워크에서 OWL MCP 엔드포인트에 접근할 수 있는지 확인합니다.

MCP: 인증 실패¶

다음 내용을 확인하십시오:

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

요청 헤더 형식:

Authorization: Bearer <API Key>

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

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

가능한 원인:

• MCP 클라이언트가 서비스에 성공적으로 연결되지 않았습니다.
• API Key가 유효하지 않거나 권한이 부족합니다.
• 클라이언트가 MCP 도구 목록을 새로 고치지 않았습니다.
• 엔드포인트 선택이 잘못되었습니다.

처리 방법:

1. 클라이언트에서 MCP 연결을 다시 테스트합니다.
2. 엔드포인트가 워크스페이스 사이트와 일치하는지 확인합니다.
3. Authorization 헤더가 올바른지 확인합니다.
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. 워크스페이스 측의 승인, 감사 또는 권한 구성을 확인합니다.