콘텐츠로 이동

OWL 자동 설치


이 문서는 AI 도구에서 OWL을 사용해야 하는 사용자를 대상으로, 자동 설치 방식을 통해 OWL CLI, 인증 구성, 도구 카탈로그 동기화 및 OWL Skill 설치를 완료하는 방법을 설명합니다.

OWL Skill은 AI 도구를 위한 지원 기능으로, AI 도구가 로컬 owl 명령을 인식하고 OWL 도구 카탈로그를 이해하며 로그, 메트릭, 이벤트, 트레이스 등 진단 기능을 보다 안정적으로 사용하도록 지원합니다. 자동 설치 절차는 OWL CLI 설치 후 현재 Agent의 메커니즘에 따라 OWL Skill을 설치합니다.

터미널에서 OWL CLI만 수동으로 사용하려면 OWL Skill을 건너뛸 수 있습니다.

설치 명령을 단계별로 검토해야 하거나 오프라인 설치가 필요한 경우 OWL 수동 설치를 사용하세요. 현재 환경에서 OWL CLI Endpoint에 액세스할 수 없다면 먼저 네트워크 액세스 문제를 해결해야 하며, 설치 방식은 호출 시의 네트워크 요구 사항을 변경하지 않습니다.

지원되는 Agent

Codex, Claude Code, Cursor, Trae, GitHub Copilot(VS Code), Windsurf는 모두 이 페이지의 통합 절차를 사용할 수 있습니다. 터미널 실행 권한이 있는 Agent 모드에서 작업하세요. 터미널 명령을 실행할 수 있는 다른 Agent도 동일한 절차로 사용할 수 있으며, 특정 제품으로 변경할 필요가 없습니다.

OWL CLI는 Agent가 실제로 명령을 실행하는 환경에 설치해야 합니다. 로컬 Agent는 로컬에 설치하고, 원격 개발, 컨테이너 또는 클라우드 Agent는 해당 환경에 설치해야 하며 해당 환경에서 OWL CLI Endpoint에 액세스할 수 있어야 합니다. 로컬 설치에 성공했다고 해서 원격 환경에서도 owl을 찾을 수 있는 것은 아닙니다.

설치 전에 연결 방식 설명을 참고하여 선택을 확인할 수 있습니다. 현재 도구가 터미널 명령을 실행할 수 없지만 원격 MCP를 지원하는 경우 MCP 연결을 대신 사용할 수 있습니다.

사용 사례

다음 사용 사례에 적합합니다:

  • AI 도구에 터미널 명령 실행 권한이 있음
  • 현재 환경에서 OWL CLI Endpoint 및 설치 리소스 주소에 액세스할 수 있음
  • 현재 환경에서 로컬 사용자 디렉터리의 OWL 구성에 쓸 수 있음
  • 사용자가 워크스페이스에 해당하는 OWL CLI Endpoint와 임시 인증 코드를 제공할 수 있음

다음 사용 사례에는 적합하지 않습니다:

  • 현재 도구가 순수 채팅 도구로 터미널 명령을 실행할 수 없음
  • 현재 환경이 제한된 네트워크 또는 오프라인 환경임
  • 현재 환경에서 AI 도구가 로컬 구성에 쓰는 것을 허용하지 않음
  • 설치 과정의 각 명령을 사람이 검토한 후에만 실행해야 함

1단계: CLI 및 함께 제공되는 Skill 설치

다음 절차는 위의 모든 Agent에 적용됩니다. 설치 지시문을 현재 Agent의 대화 창에 보내고, 안내에 따라 필요한 명령 실행 권한을 확인하세요. 자동 설치에는 함께 제공되는 Skill의 설치 단계가 포함되므로, 설치 성공을 확인한 후 별도로 다시 설치할 필요가 없습니다. 복사하기 전에 다음 치환을 완료하세요:

  • <OWL_REGISTRY_ENDPOINT>를 워크스페이스가 속한 사이트에 해당하는 OWL CLI Endpoint로 바꿉니다
  • <YOUR_TEMP_CODE>를 Guance 콘솔에서 생성한 임시 인증 코드로 바꿉니다
https://static.guance.com/owl/skill.md 를 읽고, 문서에 따라 현재 환경에 OWL CLI와 OWL Skill을 설치 및 구성하세요.

설치 파라미터는 다음과 같습니다:
OWL_REGISTRY_ENDPOINT="<OWL_REGISTRY_ENDPOINT>"
OWL_TEMP_CODE="<YOUR_TEMP_CODE>"

공식 Skill 문서는 중국어와 영어 두 버전을 제공합니다: skill.md(중국어) 및 skill.en.md(영어). AI 도구의 언어 환경에 따라 선택할 수 있습니다.

2단계: 설치 확인 및 최초 호출 완료

설치가 완료되면 동일한 Agent 대화에서 다음을 전송하세요:

owl 명령과 owl-diagnostics Skill을 사용할 수 있는지 확인하고, 먼저 owl.metric.list의 도구 설명을 확인한 다음 OWL CLI를 통해 현재 워크스페이스에서 사용 가능한 메트릭 source를 나열하세요. 결과 파일이 반환되면 파일을 읽고 비즈니스 결과를 확인하세요. 읽기 작업만 수행하고 구성이나 리소스는 수정하지 마세요.

다음 결과를 확인하세요:

  • Agent가 owl --help를 실행할 수 있음; 함께 제공되는 Skill이 설치되었으며 Agent가 해당 작업 설명을 읽을 수 있음; 새로 고침 또는 새 세션이 필요하다는 안내가 표시되면 현재 Agent의 요구 사항에 따라 작업합니다
  • owl sync가 성공적으로 완료됨; 동기화된 도구 카탈로그를 확인할 수 있음
  • Agent가 실제로 OWL CLI 도구 호출을 실행함; 결과 파일이 반환된 경우 해당 내용을 읽고 비즈니스 오류가 없는지 확인했으며 반환 데이터를 기반으로 응답함

명령 종료 코드가 0이라는 것만으로 조회 성공을 판단할 수 없으며, 반환 내용의 비즈니스 상태와 오류 정보(예: success, error)도 확인해야 합니다. 성공적으로 빈 목록이 반환된 경우 현재 워크스페이스의 데이터와 권한을 다시 확인하세요. 장애 처리 방법은 Agent의 CLI 및 Skill 문제를 참고하세요.

Skill 설치에 실패했거나 현재 Agent에 기본 Skill 메커니즘이 없는 경우에도 CLI는 독립적으로 사용할 수 있습니다. 설치 안내에 따라 현재 Agent의 Skill 또는 사용자 지정 지시문 진입점을 통해 함께 제공되는 안내를 가져온 후 읽을 수 있는지 별도로 확인하세요.

CLI를 수동으로 설치한 사용자는 함께 제공되는 Skill 설치에 따라 후속 단계를 바로 완료할 수 있으며, CLI를 다시 설치할 필요가 없습니다.

파라미터 설명

파라미터 설명 입력 방법
OWL_REGISTRY_ENDPOINT Guance 센터 OWL CLI Endpoint 워크스페이스가 위치한 사이트에 따라 해당 Endpoint를 선택합니다
OWL_TEMP_CODE Studio 일회용 임시 인증 코드로, 설치 스크립트와 owl login --dpop에서 사용 Guance 콘솔의 개인 API 키 페이지에서 생성합니다

OWL_REGISTRY_ENDPOINT에는 Endpoint 루트 주소만 입력하고, /api/v1 또는 기타 경로를 직접 이어 붙이지 마세요.

임시 인증 코드 발급 경로:

  1. 콘솔 오른쪽 상단의 개인 프로필 아이콘을 클릭합니다
  2. “개인 API 키”를 선택합니다
  3. “임시 인증 코드 생성”을 클릭합니다

Endpoint 목록

OWL CLI 서비스는 사이트별로 독립적인 Endpoint를 제공합니다. 워크스페이스가 위치한 노드에 따라 해당 서비스 주소를 선택하세요.

배포 유형 노드 이름 Endpoint
SaaS 배포 중국 리전 1(항저우) https://owl-api.guance.com
SaaS 배포 중국 리전 2(닝샤) https://aws-owl-api.guance.com
SaaS 배포 중국 리전 4(광저우) https://cn4-owl-api.guance.com
SaaS 배포 중국 리전 6(홍콩) https://cn6-owl-api.guance.one
SaaS 배포 글로벌 리전 1(오리건) https://us1-owl-api.guance.com
SaaS 배포 유럽 리전 1(프랑크푸르트) https://eu1-owl-api.guance.one
SaaS 배포 아시아 태평양 리전 1(싱가포르) https://ap1-owl-api.guance.one
SaaS 배포 아시아 태평양 리전 2(싱가포르) https://ap2-owl-api.guance.com
SaaS 배포 아프리카 리전 1(남아프리카) https://za1-owl-api.guance.com
SaaS 배포 인도네시아 리전 1(자카르타) https://id1-owl-api.guance.com
SaaS 배포 무료 존(베이징) https://cn3-owl-api.guance.com
프라이빗 배포 플랜 프라이빗 배포 플랜 실제 배포에서 제공하는 OWL CLI Endpoint를 기준으로 합니다

실행 내용

AI 도구는 설치 안내에 따라 다음 작업을 자동으로 수행합니다:

  1. OWL CLI 다운로드 및 설치
  2. 워크스페이스에 해당하는 OWL CLI Endpoint 기록
  3. 설치 프로그램이 owl login --dpop을 호출하여 OWL_TEMP_CODE에서 임시 코드를 읽고 로컬 자격 증명 저장
  4. 인증 정보를 로컬 OWL 구성에 기록
  5. owl sync를 실행하여 도구 카탈로그 동기화
  6. OWL Skill 설치
  7. owl 명령 사용 가능 여부 확인

CLI와 Skill이 모두 성공적으로 설치되면 AI 도구는 실행 환경의 owl 명령과 OWL Skill을 함께 사용하여 Guance의 진단 기능을 사용할 수 있습니다.

보안 설명

새 버전 OWL은 임시 인증 코드를 사용하여 DPoP 액세스 토큰을 획득하고, 로컬에서 개인 키를 생성하며, 비즈니스 요청에 서명합니다. 설치 및 로그인 시에는 상태만 표시하며, 응답, 로그 또는 명령 출력에 임시 코드, 토큰 또는 개인 키를 표시하지 않습니다.

OWL_TEMP_CODE는 단기간 유효하며, 성공적으로 교환된 후에는 만료됩니다. 가능한 한 빨리 사용하고, 공개적으로 붙여넣거나 장기 로그, 코드 저장소 또는 공유 문서에 저장하지 마세요. 구버전 CLI 설치를 지정하는 경우 설치 프로그램은 여전히 기존 인터페이스를 통해 임시 코드로 API 키를 교환합니다.

DPoP 로그인은 선택한 계정 및 워크스페이스의 권한에 따라 리소스에 액세스합니다. API 키를 사용하는 경우 액세스 범위는 해당 키에 따라 달라집니다. 두 방식 모두 대상 도구에 대한 읽기 또는 쓰기 권한이 필요합니다.

일반적인 문제 처리

AI 도구가 명령을 실행할 수 없음

AI 도구에서 터미널 명령을 실행할 수 없다고 표시되면 터미널 실행 권한이 있는 AI 도구에서 설치 지시문을 다시 실행하거나 OWL 수동 설치를 대신 사용하세요.

임시 인증 코드가 유효하지 않거나 만료되었거나 권한이 없음

인증 코드가 유효하지 않거나 만료되었거나 권한이 없다는 메시지가 표시되면 Guance 콘솔에서 OWL_TEMP_CODE를 다시 생성한 후 설치 지시문을 다시 실행하세요.

Endpoint에 액세스할 수 없음

Endpoint에 액세스할 수 없다는 메시지가 표시되면 다음을 확인하세요:

  • 현재 환경에서 외부 네트워크 또는 기업 네트워크의 OWL CLI Endpoint에 액세스할 수 있음
  • 워크스페이스가 속한 노드와 OWL_REGISTRY_ENDPOINT가 일치함
  • OWL_REGISTRY_ENDPOINT에 /api/v1 또는 기타 경로가 이어 붙지 않았음

설치 완료 후 owl 명령을 인식할 수 없음

설치 완료 후 owl 명령을 인식할 수 없는 경우 터미널을 다시 열거나 AI 도구에서 현재 터미널 환경 변수를 새로 고친 후 다시 확인하세요.

다음 명령을 실행하여 확인할 수 있습니다:

owl --help
owl config show

도구 카탈로그 동기화 실패

owl sync가 인증, 권한 또는 네트워크 오류를 반환하는 경우 다음을 확인하세요:

  • owl config show에 DPoP: configured가 표시되는지 확인하고, API 키로 설치한 경우 사용한 키가 유효한지 확인합니다
  • 대상 사이트가 DPoP를 지원하는지, 현재 계정에 대상 워크스페이스 및 도구에 대한 권한이 있는지 확인합니다
  • 현재 환경에서 OWL CLI Endpoint에 액세스할 수 있는지 확인합니다

추가 문제는 문제 해결을 참고하세요.

문서 평가

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