OWL 수동 설치¶

이 문서는 OWL 사용자를 대상으로 OWL CLI 설치 전 준비 사항, 온라인 설치, 특정 버전 설치, 오프라인 설치 및 설치 완료 후 확인 방법을 설명합니다.

owl은 OWL CLI의 명령어 이름입니다. 설치가 완료되면 사용자는 로컬에서 owl을 사용하여 도구 디렉터리를 동기화하고, 도구 설명을 확인하며, 플랫폼 기능을 실행할 수 있습니다.

현재 사용 중인 AI 도구가 터미널 명령어 실행을 지원하고, OWL CLI, 인증 구성, 도구 디렉터리 동기화 및 OWL Skill 설치를 자동으로 완료하려면 자동 설치를 참조하세요.

설치 전 준비¶

설치 전에 다음 정보를 준비하세요.

OWL_REGISTRY_ENDPOINT는 워크스페이스가 속한 사이트에 해당하는 Guance 중앙 OWL CLI Endpoint를 입력해야 하며, 수동으로 /api/v1을 추가하지 마세요.

• OWL_INSTALL_BASE_URL: 설치 스크립트 및 설치 패키지 다운로드에 사용됩니다.
• OWL_REGISTRY_ENDPOINT: CLI가 Guance 중앙의 OWL 서비스에 액세스하는 데 사용됩니다.
• OWL_TOKEN: 서비스 액세스 토큰으로, 호출자 ID를 식별하며 DF-API-KEY에 해당합니다.
• OWL_API_KEY: OWL_TOKEN의 별칭 환경 변수입니다. 두 개가 동시에 설정된 경우 OWL_API_KEY가 우선 적용됩니다.

권한 요구 사항¶

OWL_TOKEN은 Guance API Key를 사용합니다. OWL CLI가 액세스할 수 있는 리소스와 실행할 수 있는 작업은 해당 API Key의 Open API 권한에 따라 결정됩니다.

설치 및 최초 검증을 위해서는 최소한 다음 조건을 충족해야 합니다.

• 현재 워크스페이스에 액세스할 수 있어야 합니다.
• OWL CLI Endpoint에 액세스할 수 있어야 합니다.
• 도구 디렉터리 동기화에 필요한 기본 액세스 권한이 있어야 합니다.
• 특정 도구를 실행하려면 API Key에 해당 Open API의 읽기 또는 쓰기 권한이 있어야 합니다.

Endpoint 목록¶

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

지원 플랫폼¶

현재 설치 패키지는 다음 플랫폼을 지원합니다.

설치 패키지 파일명은 owl-cli-*를 사용하며, 설치 후 명령어는 owl로 통일됩니다.

온라인 설치¶

Linux / macOS¶

OWL_INSTALL_BASE_URL="https://static.guance.com/owl" \
OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com" \
OWL_TOKEN="your-token" \
bash -c "$(curl -fsSL https://static.guance.com/owl/install.sh)" -- --yes

실행 전에 시스템에 다음 명령어가 설치되어 있는지 확인하세요.

• bash
• curl
• tar

Windows¶

$env:OWL_INSTALL_BASE_URL = "https://static.guance.com/owl"
$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.guance.com"
$env:OWL_TOKEN = "your-token"
Set-ExecutionPolicy Bypass -Scope Process -Force
Import-Module BitsTransfer
Start-BitsTransfer -Source "$env:OWL_INSTALL_BASE_URL/install.ps1" -Destination .\owl-install.ps1
powershell .\owl-install.ps1 -Yes

시스템에서 BitsTransfer를 제공하지 않는 경우 다음 명령어를 사용하여 스크립트를 다운로드하세요.

Invoke-WebRequest -Uri "$env:OWL_INSTALL_BASE_URL/install.ps1" -OutFile .\owl-install.ps1

특정 버전 설치¶

특정 버전을 설치해야 하는 경우 설치 명령어에서 버전 번호를 지정할 수 있습니다.

Linux / macOS¶

OWL_INSTALL_BASE_URL="https://static.guance.com/owl" \
OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com" \
OWL_TOKEN="your-token" \
bash -c "$(curl -fsSL https://static.guance.com/owl/install.sh)" -- --version "1.3.0" --yes

Windows¶

$env:OWL_INSTALL_BASE_URL = "https://static.guance.com/owl"
$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.guance.com"
$env:OWL_TOKEN = "your-token"
Set-ExecutionPolicy Bypass -Scope Process -Force
Import-Module BitsTransfer
Start-BitsTransfer -Source "$env:OWL_INSTALL_BASE_URL/install.ps1" -Destination .\owl-install.ps1
powershell .\owl-install.ps1 -Version "1.3.0" -Yes

오프라인 설치¶

온라인 설치 주소에 액세스할 수 없는 환경에서는 오프라인 설치 방식을 사용할 수 있습니다.

오프라인 설치 디렉터리에는 다음 파일이 반드시 포함되어야 합니다.

• install.sh 또는 install.ps1
• version
• SHA256SUMS
• 현재 시스템에 해당하는 설치 패키지

오프라인 설치 패키지 파일명은 다음과 같습니다.

Linux / macOS¶

chmod +x ./install.sh
./install.sh \
  --local-package \
  --registry-endpoint "https://owl-api.guance.com" \
  --token "your-token" \
  --yes

Windows¶

powershell .\install.ps1 `
  -LocalPackage `
  -RegistryEndpoint "https://owl-api.guance.com" `
  -Token "your-token" `
  -Yes

설치 후 기본 디렉터리¶

실행 파일¶

구성 디렉터리¶

구성 디렉터리를 사용자 지정하려면 환경 변수 OWL_DIR을 설정할 수 있습니다. OWL_DIR이 비어 있지 않은 값으로 설정된 경우 OWL CLI는 해당 디렉터리를 구성 디렉터리로 사용하여 위 표의 기본 경로를 재정의합니다. 설정되지 않은 경우 위 표의 기본 경로($HOME/.owl / %USERPROFILE%\.owl)로 대체됩니다.

구성 디렉터리 초기화 후에는 다음 내용이 포함됩니다.

설치 완료 후 확인¶

설치가 완료된 후 터미널을 다시 열고 다음 명령어를 실행합니다.

owl --help
owl config show

명령어가 정상적으로 도움말 정보와 현재 구성을 출력하면 로컬 실행 파일과 구성 파일이 준비된 것입니다.

현재 터미널과 OWL CLI Endpoint 간의 연결성을 추가로 확인하려면 다음을 계속 실행합니다.

owl sync

owl sync가 정상적으로 완료되면 현재 터미널이 OWL CLI Endpoint에 액세스할 수 있고 OWL_TOKEN이 도구 디렉터리 동기화에 사용 가능함을 의미합니다.

owl sync가 인증, 권한 또는 네트워크 오류를 반환하는 경우 문제 해결을 참조하세요.

업그레이드¶

업데이트 채널이 설정되어 있으면 owl update를 실행하세요. update.base_url의 채널을 유지하며 일반 버전은 다운그레이드하지 않고 같은 버전은 기존 바이너리를 유지합니다. 채널 설치 스크립트를 업데이트하면 이전 testing-<SHA> 빌드도 설정과 SHA256 검증을 유지하면서 해당 채널의 릴리스 버전으로 이전할 수 있습니다. 필요한 테스트 기능이 릴리스에 포함되어 있는지 확인하세요.

v1.4.0으로 업그레이드한 후 owl sync로 전체 카탈로그를 동기화하세요. 멤버 도구 마이그레이션을 참조하세요. 재설치 또는 버전 지정은 특정 버전 설치를 참조하세요.

업그레이드 전에 다음 사항을 확인하는 것이 좋습니다.

• 현재 터미널이 대상 워크스페이스에 해당하는 OWL_REGISTRY_ENDPOINT를 사용하고 있는지 확인하세요.
• 현재 OWL_TOKEN이 여전히 유효한지 확인하세요.
• 로컬 스크립트 또는 자동화 작업이 이전 버전 동작에 의존하는지 확인하세요.

제거¶

OWL CLI를 제거하려면 OWL 실행 파일과 로컬 구성 디렉터리를 삭제하면 됩니다.

구성 디렉터리를 삭제하면 로컬 Token, 캐시, 데이터 파일 및 로그가 지워집니다. 삭제 전에 이러한 내용이 더 이상 필요하지 않은지 확인하세요.

Agent용 OWL Skill 설치 (선택 사항)¶

AI Agent에서 OWL을 통해 Guance 중앙의 진단 기능을 사용할 계획이라면, OWL CLI 설치를 완료하고 owl sync를 한 번 실행한 후 Agent에 owl-diagnostics skill을 설치하는 것이 좋습니다.

owl-diagnostics skill은 로컬에 설치되어 실행 가능한 owl 명령어에 의존합니다. 설치 후 Agent는 OWL이 동기화한 도구 디렉터리와 함께 로그, 메트릭, 이벤트, 트레이스 등의 진단 분석을 보다 안정적으로 수행할 수 있습니다.

해당 skill 주소:

https://github.com/GuanceCloud/ai-skills/tree/main/owl-diagnostics

현재 OWL CLI를 수동으로만 사용해야 하는 경우 이 단계를 건너뛰어도 됩니다.

Codex 예시

Codex에서 다음 프롬프트를 통해 owl-diagnostics skill을 설치할 수 있습니다.

이 skill을 설치해 주세요: https://github.com/GuanceCloud/ai-skills/tree/main/owl-diagnostics

설치가 완료되면 Codex를 다시 시작하여 새로 설치된 skill을 활성화합니다. 이후 Codex에서 Guance 진단 관련 작업을 실행할 때 Codex는 로컬 owl 명령어와 이 skill을 함께 사용할 수 있습니다.

터미널에서 owl을 찾을 수 없다는 메시지가 표시되면 다음 방법으로 처리하세요.

• Windows: 현재 PowerShell을 닫고 다시 연 후 실행합니다.
• Linux / macOS: 현재 터미널 창을 닫고 다시 연 후 실행합니다.