콘텐츠로 이동

OWL 수동 설치


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

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

현재 사용 중인 AI 도구가 터미널 명령 실행을 지원하고 OWL CLI, 인증 설정, 도구 카탈로그 동기화 및 OWL Skill 설치를 자동으로 완료하려면 자동 설치를 사용합니다.

설치 전 준비

설치 전에 다음 정보를 준비합니다.

구성 항목 설명
OWL_INSTALL_BASE_URL OWL 설치 스크립트와 설치 패키지의 다운로드 주소
OWL_REGISTRY_ENDPOINT 워크스페이스가 속한 사이트에 대응하는 OWL CLI Endpoint
OWL_TEMP_CODE Studio 일회용 임시 인증 코드로, 설치 스크립트와 owl login --dpop에서 사용합니다
OWL_TOKEN API Key 모드와 호환되며, 설치 프로그램에 명시적으로 제공할 때 이 Key를 사용합니다
OWL_API_KEY API Key 모드의 CLI 환경 변수로, 동시에 설정하면 OWL_TOKEN보다 우선합니다

OWL_REGISTRY_ENDPOINT에는 반드시 워크스페이스가 속한 사이트에 대응하는 Guance 센터 OWL CLI Endpoint를 입력해야 하며, /api/v1을 직접 이어 붙이지 마세요.

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

권한 요구 사항

  • 현재 워크스페이스에 액세스할 수 있어야 합니다
  • OWL CLI Endpoint에 액세스할 수 있어야 합니다
  • 도구 카탈로그 동기화에 필요한 기본 액세스 권한을 보유해야 합니다
  • 대상 사이트가 DPoP를 지원하는지, 현재 계정에 대상 워크스페이스와 도구에 대한 권한이 있는지 확인해야 합니다

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를 기준으로 합니다

지원 플랫폼

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

운영 체제 지원 아키텍처
Windows amd64
Linux amd64, arm64
macOS amd64, arm64

설치 패키지 파일 이름은 owl-cli-* 형식을 사용하며, 설치 후 명령은 모두 owl로 통일됩니다.

온라인 설치

Linux / macOS

OWL_INSTALL_BASE_URL="https://static.guance.com/owl" \
OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com" \
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"
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

설치가 완료되면 owl login --dpop을 실행하고 Studio 임시 인증 코드를 입력합니다. 설치 프로그램을 시작할 때 OWL_TEMP_CODE를 통해 로그인을 완료할 수도 있습니다. API Key 모드가 필요한 경우 OWL_TOKEN, --token 또는 -Token을 명시적으로 제공하세요. 다른 계정을 추가하려면 Profile을 사용하세요.

지정 버전 설치

특정 버전을 설치하려면 설치 명령에 버전 번호를 지정할 수 있습니다.

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
  • 현재 시스템에 대응하는 설치 패키지

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

운영 체제 지원 아키텍처 파일 이름
Windows amd64 owl-cli-windows-amd64-<version>.zip
Linux amd64 owl-cli-linux-amd64-<version>.tar.gz
Linux arm64 owl-cli-linux-arm64-<version>.tar.gz
macOS amd64 owl-cli-darwin-amd64-<version>.tar.gz
macOS arm64 owl-cli-darwin-arm64-<version>.tar.gz

Linux / macOS

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

Windows

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

오프라인 설치는 본机 파일만 설치합니다. 사이트의 HTTPS Endpoint에 액세스할 수 있게 되면 owl login --dpop을 실행하여 로그인을 완료하세요.

설치 후 기본 디렉터리

실행 파일

운영 체제 기본 경로
Windows %LOCALAPPDATA%\Programs\owl\owl.exe
Linux / macOS $HOME/.local/bin/owl에 우선 설치하며, 쓰기가 불가능한 경우 /usr/local/bin/owl로 대체합니다

설정 디렉터리

운영 체제 기본 경로
Windows %USERPROFILE%\.owl
Linux / macOS $HOME/.owl

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

설정 디렉터리는 초기화 후 다음 내용을 포함합니다.

경로 설명
config.yaml 클라이언트 설정 파일
cache/ 동기화된 분류 및 도구 캐시
data/ 데이터형 도구 결과 파일
logs/ 로그 디렉터리

설치 완료 후 확인

설치가 완료되면 터미널을 다시 열고 다음 명령을 실행합니다.

owl --help
owl config show

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

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

owl sync

owl sync가 성공하면 도구 카탈로그를 가져온 것입니다. owl config show로 로그인 상태를 확인한 뒤, 현재 계정에 권한이 있는 읽기 전용 도구를 하나 호출하여 액세스가 가능한지 확인하세요.

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

업그레이드

업데이트 채널이 설정된 경우 다음 명령으로 업그레이드합니다.

owl update

owl update는 본机의 update.base_url에 지정된 채널을 사용합니다. 일반 버전은 업그레이드만 가능하며 다운그레이드는 지원하지 않고, 동일 버전은 바이너리를 유지합니다. 채널 설치 스크립트가 업데이트된 후에는 기존 testing-<SHA> 빌드도 해당 채널의 정식 버전으로 마이그레이션할 수 있으며, 기존 설정을 유지하고 다운로드 패키지의 SHA256을 검증합니다. 마이그레이션 전에 정식 버전에 필요한 테스트 기능이 포함되어 있는지 확인하세요.

다시 설치하려면 온라인 설치 명령을 실행하면 되며, 특정 버전을 설치하려면 지정 버전 설치를 참고하세요.

v1.4.0으로 업그레이드한 후 owl sync를 실행하여 도구 카탈로그를 전체 새로 고침하세요. owl.member.list는 owl.workspace.member.list로 마이그레이션되었으며, 이전 이름은 호출 별칭으로 유지됩니다. 자세한 내용은 공간 간 조회 및 멤버 도구 마이그레이션을 참고하세요.

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

  • 현재 터미널이 대상 워크스페이스에 대응하는 OWL_REGISTRY_ENDPOINT를 사용하고 있는지
  • owl config show에 DPoP: configured가 표시되는지, API Key로 설치한 경우 사용한 Key가 유효한지
  • 본机 스크립트 또는 자동화 작업이 이전 버전의 동작에 의존하고 있는지

제거

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, Claude Code, Cursor, Trae, GitHub Copilot(VS Code) 및 Windsurf 등 터미널 실행 기능을 갖춘 Agent는 모두 동일한 설치 절차를 사용할 수 있습니다. CLI는 Agent가 실제로 명령을 실행하는 환경에 설치해야 합니다.

현재 Agent 대화에서 다음 프롬프트를 보내면 해당 Agent가配套 Skill을 설치하도록 할 수 있습니다.

帮我安装这个 skill:https://github.com/GuanceCloud/ai-skills/tree/main/owl-diagnostics

설치가 완료되면 현재 Agent의 안내에 따라 Skill을 로드하고, 필요한 경우 세션을 새로 고치거나 새로 생성한 뒤 최초 호출 검증을 완료하세요. 자동 설치를 통해配套 Skill 설치를 이미 완료한 사용자는 이 섹션의 단계를 반복할 필요가 없습니다.

터미널에서 owl을 찾을 수 없다는 메시지가 표시되면 다음과 같이 처리하세요.

  • Windows: 현재 PowerShell을 닫고 다시 연 뒤 실행하세요.
  • Linux / macOS: 현재 터미널 창을 닫고 다시 연 뒤 실행하세요.

문서 평가

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