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: 서비스 액세스 토큰, 호출자 식별에 사용되며 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.0.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.0.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_REGISTRY_ENDPOINT를 사용하고 있는지 확인합니다.
• 현재 OWL_TOKEN이 여전히 유효한지 확인합니다.
• 로컬 스크립트 또는 자동화 작업이 이전 버전의 동작에 의존하는지 확인합니다.

제거¶

OWL CLI를 제거해야 하는 경우 OWL 실행 파일과 로컬 설정 디렉터리를 삭제하면 됩니다.

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

Agent용 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: 현재 터미널 창을 닫고 다시 연 후 실행하세요.