콘텐츠로 이동

문제 해결


이 문서는 OWL CLI 및 OWL MCP Server의 일반적인 연동 문제를 처리하기 위한 내용을 다룹니다.

v1.9.0: DPoP 로그인 및 업그레이드

invalid_grant는 임시 코드가 유효하지 않거나, 만료되었거나, 이미 사용되었음을 의미하므로 Studio에서 새 코드를 생성하세요. invalid_token은 자격 증명이 만료되었음을 의미하므로 새 코드로 owl login --dpop을 실행하세요. invalid_dpop_proof인 경우 로컬 시계, 사이트 HTTPS 주소 및 Registry의 Ingress 구성을 확인하세요. CLI는 유효한 새 nonce challenge를 처리하므로 인증 실패로 인해 쓰기 작업을 자동으로 재전송하지 마세요.

profile add가 여전히 API Key 입력을 요청하면 먼저 CLI를 업그레이드하고, owl profile add --help를 사용하여 Studio temporary code (DPoP)가 포함되어 있는지 확인하세요. 기존 스크립트는 OWL_TEMP_CODE를 통해 임시 코드를 제공하도록 변경하세요. 계정 추가에는 네트워크 연결이 필요하며, 전환은 로컬 구성만 확인합니다.

owl sync가 성공하면 도구 카탈로그를 가져왔음을 의미합니다. owl config show로 로그인 상태를 확인한 후, 현재 계정에 권한이 있는 읽기 전용 도구를 하나 호출하여 액세스가 가능한지 확인하세요. 여러 Profile 사용.

v1.7.0: 업그레이드 및 호출 결과

  • DQL 실패 시 query_text, raw_output 및 issues[].message에서 구체적인 원인과 사용 가능한 행/열 정보를 확인하세요. time.validation_unavailable은 검증기를 사용할 수 없음을 의미하며, 쿼리 구문 오류로 간주해서는 안 됩니다. 진단 정보를 공유하기 전에 그 안의 원본 쿼리 내용을 확인하세요.
  • 문서 버전이 변경된 후에는 다시 검색하고 새 read_reference를 사용하세요. Registry 파일 시스템에 액세스하지 마세요. DQL 본문 읽기를 참고하세요.
  • 런타임 모드에서 구성 또는 Profile 작업이 거부되면 실행기가 세 가지 런타임 변수가 그룹으로 주입되었는지 확인해야 합니다. ID를 전환하여 우회하지 마세요. 런타임 Profile을 참고하세요.
  • 카탈로그 쓰기가 pending 상태이거나 감사 결과가 불확실한 경우 쓰기 결과 및 확인 절차에 따라 처리하고, 새 UUID를 생성하여 쓰기를 반복하지 마세요.

v1.6.0: 시간 검증 또는 동기화 실패

시간 오류는 issues[].code로 구분할 수 있습니다. time.unit은 타임스탬프 단위와 정수 유형을 확인하고, time.pair는 쌍을 이루는 매개변수를 보완하며, time.order는 선후 순서를 수정하고, time.span은 초과된 윈도우를 축소합니다. DQL 상대 윈도우 또는 충돌하는 윈도우는 제거하거나 외부 범위와 일치하는 절대 윈도우로 변경해야 합니다. time.validation_unavailable의 경우 Registry의 dqlcheck를 확인한 후 사전 검사를 다시 시도하세요.

owl sync는 어느 한 카테고리의 다운로드가 실패하면 실패를 반환하며, 실패한 카테고리의 기존 캐시와 로컬 버전을 유지합니다. 최초 자동 동기화 실패는 후속 실행을 차단합니다. 캐시 만료 후 자동 동기화가 실패하면 기존 동작대로 경고하고 기존 캐시를 사용합니다.

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: 기존 테스트 버전 업그레이드 실패

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가 붙은 형식인지 확인하세요. 알 수 없거나 손상되었거나 실행에 실패한 버전은 이전 버전으로 간주되어 강제로 덮어쓰이지 않습니다. 원인을 확인한 후 수동 설치를 참고하여 다시 설치할 수 있습니다.

Agent의 CLI 및 Skill 문제

증상 확인 및 처리
로컬 터미널에서 owl을 실행할 수 있지만 Agent가 명령을 찾지 못함 Agent가 실행 환경에서 owl --help를 확인하도록 합니다. 원격 개발 또는 컨테이너는 로컬과 설치를 공유하지 않으므로 실제 실행 환경에 CLI를 설치하고 해당 환경의 PATH를 새로 고쳐야 합니다
CLI는 사용 가능하지만 함께 제공되는 Skill을 인식하지 못함 Agent가 owl-diagnostics가 현재 제품에서 인식 가능한 위치에 설치되었는지 확인하도록 합니다. 제품 안내에 따라 새로 고치거나 새 세션을 생성하세요. 통합 Skill 설치 안내를 다시 전송할 수 있습니다
Agent가 명령만 제시하고 실제로 실행하지 않음 현재 터미널 실행 기능이 있는 Agent 모드를 사용 중인지, 필요한 권한이 부여되었는지 확인한 후 읽기 전용 호출을 한 번 실행하도록 명확히 요청하세요
Agent 전환 후 조회되는 워크스페이스가 올바르지 않음 새 Agent의 실행 환경에서 현재 Profile과 Endpoint를 확인하세요. 다른 터미널의 환경 변수 또는 구성이 이미 적용되었다고 가정하지 마세요

CLI 실행 가능, Skill 인식, 비즈니스 호출 성공은 서로 다른 세 가지 확인 항목입니다. 최종적으로 최초 호출 검증에 따라 실제 반환 결과를 확인하세요.

자동 설치: 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 액세스 불가

먼저 실제 적용되는 ID 및 구성 출처를 확인하세요:

owl profile current -f json
owl config show

Profile을 선택한 후( default 포함) Endpoint/Key 전체 세트는 해당 Profile에서 가져오며, OWL_REGISTRY_ENDPOINT, OWL_API_KEY 또는 OWL_TOKEN을 수정해도 이를 덮어쓰지 않습니다. 기존 구성 모드이거나 --conf를 별도로 사용하는 경우에만 이러한 환경 변수가 구성 파일을 덮어씁니다.

다음 내용을 확인하세요:

  • 현재 적용되는 Endpoint가 워크스페이스가 속한 사이트의 OWL CLI Endpoint인지
  • Endpoint에 /api/v1이 잘못 appended되지 않았는지
  • 선택한 Profile의 액세스 토큰이 유효한지, 환경 변수 덮어쓰기가 적용되는 시나리오에서 OWL_API_KEY와 OWL_TOKEN이 동시에 설정된 경우 OWL_API_KEY가 우선인지
  • API Key에 해당 Open API 권한이 있는지
  • 현재 터미널에서 OWL CLI Endpoint에 액세스할 수 있는지

CLI: 잘못된 Profile 선택

owl profile list 및 owl profile current -f json을 사용하여 로컬 별칭, 영구 저장된 기본값 및 실제 선택을 확인하세요. 선택 우선순위는 --profile > OWL_PROFILE > owl switch가 저장한 기본값입니다. Profile을 추가해도 전환되지 않으며, --profile은 이번 명령에만 영향을 줍니다.

owl --profile customer-a config show
owl --profile customer-a sync
owl --profile customer-a exec owl.data.show_dql_namespace

Profile을 선택하면 Endpoint와 자격 증명은 해당 Profile에서 가져오며, ID 환경 변수는 이를 덮어쓰지 않습니다. ID와 무관한 환경 설정은 계속 적용됩니다. OWL_PROFILE이 설정된 경우 해당 변수를 해제해야 owl switch를 실행할 수 있습니다. 요청 실패 시 다른 Profile로 자동 전환되지 않습니다. B를 추가한 후에도 기본 계정은 여전히 A입니다. --profile customer-b는 현재 명령에 대해서만 B를 선택합니다. owl switch customer-b를 실행하면 이후 명령에서 B를 사용할 수 있습니다. 계정 추가에는 임시 코드의 온라인 교환이 필요하며, 전환은 로컬 구성만 확인합니다.

CLI: profile remove --purge 정리 실패

오류에 표시된 관리 대상 디렉터리 권한을 확인하고, 권한을 수정한 후 삭제를 다시 시도하세요. 아티팩트 정리에 실패하면 구성과 자격 증명은 유지되고 별칭은 복원되며, 일부 캐시 또는 쿼리 파일은 이미 삭제되었을 수 있습니다. 아티팩트를 유지해야 하는 경우 --purge 없이 owl profile remove <alias>를 사용하세요.

CLI: HTTPS 인증서 검증 실패

로컬 개발 또는 프라이빗 테스트 환경에서 자체 서명 인증서를 사용하는 경우 CLI가 x509: certificate signed by unknown authority를 반환할 수 있습니다. 우선 시스템에 신뢰할 수 있는 CA를 설치하세요. 설치가 정말 불가능한 경우 임시로 다음을 실행할 수 있습니다:

owl config set registry.insecure_skip_verify true

이 구성은 Registry ID 검증을 비활성화하므로 중간자 공격을 받을 수 있으며, 통제된 개발 환경에서만 사용해야 하고 프로덕션 환경에서는 활성화해서는 안 됩니다. 검증을 복원하려면 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 표시

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

각 Profile의 도구 캐시는 독립적입니다. Profile, Endpoint 또는 Key를 전환한 후 동일한 Profile에서 owl sync를 실행하세요.

처리 방법:

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 엔드포인트는 이벤트 스트림을 설정하기 전에 먼저 인증을 수행합니다. 자격 증명이 누락되었거나 유효하지 않으면 HTTP 401 Unauthorized를 직접 반환하며( WWW-Authenticate: Bearer realm="mcp" 응답 헤더 포함), text/event-stream 이벤트 스트림을 열지 않습니다. 따라서 클라이언트가 "연결되었지만 이벤트 스트림이 비어 있음"을 보고하면 실제로 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. 워크스페이스 측 승인, 감사 또는 권한 구성 확인

문서 평가

이 페이지가 도움이 되었나요?