OWL 자동 설치¶
이 문서는 AI 도구에서 OWL을 사용하려는 사용자를 대상으로 합니다. 자동 설치 방식을 통해 OWL CLI, 인증 구성, 도구 디렉터리 동기화 및 OWL Skill 설치를 완료하는 방법을 설명합니다.
OWL Skill은 AI 도구를 위한 보조 기능으로, AI 도구가 로컬의 owl 명령을 인식하고 OWL 도구 디렉터리를 이해하며 로그, 메트릭, 이벤트, 트레이스 등 진단 기능을 더 안정적으로 호출할 수 있도록 돕습니다. 자동 설치는 OWL CLI 설치 후 OWL Skill도 함께 설치합니다.
터미널에서 수동으로 OWL CLI만 사용하려면 OWL Skill을 건너뛰어도 됩니다.
현재 환경에서 터미널 명령을 실행할 수 없거나, 외부 네트워크 또는 사내 네트워크의 OWL CLI Endpoint에 접근할 수 없거나, 오프라인 설치가 필요한 경우 수동 OWL 설치를 참조하세요.
사용 사례¶
다음 시나리오에 적합합니다.
- AI 도구가 터미널 명령을 실행할 수 있는 권한을 보유한 경우
- 현재 환경이 OWL CLI Endpoint 및 설치 리소스 주소에 접근할 수 있는 경우
- 현재 환경이 로컬 사용자 디렉터리에 OWL 구성을 쓸 수 있는 경우
- 사용자가 워크스페이스에 해당하는 OWL CLI Endpoint 및 임시 인증 코드를 제공할 수 있는 경우
다음 시나리오에는 적합하지 않습니다.
- 현재 도구가 순수 채팅 도구로, 터미널 명령을 실행할 수 없는 경우
- 현재 환경이 제한된 네트워크 또는 오프라인 환경인 경우
- 현재 환경이 AI 도구의 로컬 구성 쓰기를 허용하지 않는 경우
- 설치 과정의 각 단계 명령을 수동으로 검토한 후 실행해야 하는 경우
설치 명령어¶
다음 내용을 복사하여 AI 도구의 대화 창에서 실행하세요. 복사하기 전에 다음을 교체하세요.
<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 도구의 언어 환경에 따라 선택하세요.
매개변수 설명¶
| 매개변수 | 설명 | 입력 방법 |
|---|---|---|
OWL_REGISTRY_ENDPOINT |
Guance 중앙 OWL CLI Endpoint | 워크스페이스가 속한 사이트에 따라 해당 Endpoint 선택 |
OWL_TEMP_CODE |
단기 유효한 임시 인증 코드 | Guance 콘솔의 개인 API 키 페이지에서 생성 |
OWL_REGISTRY_ENDPOINT는 Endpoint 루트 주소만 입력하고, /api/v1 또는 다른 경로를 수동으로 추가하지 마세요.
임시 인증 코드 획득 경로:
- 콘솔 오른쪽 상단의 프로필 아바타 클릭
- "개인 API 키" 선택
- "임시 인증 코드 생성" 클릭
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 배포 | 아프리카 1존 (남아프리카) | https://za1-owl-api.guance.com |
| SaaS 배포 | 인도네시아 1존 (자카르타) | https://id1-owl-api.guance.com |
| SaaS 배포 | 중동 1존 (UAE) | https://me1-owl-api.guance.com |
| SaaS 배포 | 무료 전용 존 (베이징) | https://cn3-owl-api.guance.com |
| 프라이빗 배포판 | 프라이빗 배포판 | 실제 배포에서 제공하는 OWL CLI Endpoint 기준 |
실행 내용¶
AI 도구는 설치 설명에 따라 자동으로 다음 작업을 수행합니다.
- OWL CLI 다운로드 및 설치
- 워크스페이스에 해당하는 OWL CLI Endpoint 작성
OWL_TEMP_CODE를 사용하여 API Key 교환- 인증 정보를 로컬 OWL 구성에 기록
owl sync실행하여 도구 디렉터리 동기화- OWL Skill 설치
owl명령어 사용 가능 여부 확인
설치가 완료되면 AI 도구는 로컬 owl 명령과 OWL Skill을 결합하여 Guance의 진단 기능을 사용할 수 있습니다.
보안 설명¶
자동 설치 시 AI 도구에 API Key 평문을 제공할 필요가 없습니다. AI 도구는 OWL_TEMP_CODE를 사용하여 API Key를 교환하고 인증 정보를 로컬 OWL 구성에 기록합니다. 설치 과정에서 응답, 로그 또는 명령 출력에 API Key 평문이 표시되지 않아야 합니다.
OWL_TEMP_CODE는 단기 유효한 임시 인증 자격 증명으로, 설치 단계에서만 API Key를 교환하는 데 사용됩니다. 이 자격 증명은 직접 인터페이스를 호출할 수 없지만, 유효 기간 내에는 민감한 정보로 처리해야 합니다. 공개적으로 붙여넣거나, 장기 로그에 기록하거나, 코드 리포지토리 또는 공유 문서에 제출하지 마세요.
자동 설치 완료 후 OWL이 액세스할 수 있는 리소스와 실행할 수 있는 작업은 교환된 API Key에 의해 결정되며, Guance 워크스페이스의 권한 구성을 따릅니다.
일반적인 문제 해결¶
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 sync가 인증, 권한 또는 네트워크 오류를 반환하는 경우 다음을 확인하세요.
OWL_TEMP_CODE가 API Key로 성공적으로 교환되었는지- 현재 API Key에 도구 디렉터리 동기화에 필요한 권한이 있는지
- 현재 환경이 OWL CLI Endpoint에 접근할 수 있는지
더 많은 문제는 문제 해결을 참조하세요.