goose 설치 및 사용자 지정 Provider 구성

goose는 컴퓨터에서 실행되는 범용 AI 어시스턴트입니다. 코딩 외에도 검색, 글쓰기, 자동화, 데이터 정리를 수행할 수 있습니다. 데스크톱 버전, 터미널 또는 인터페이스를 통해 사용할 수 있으며, 데스크톱 버전과 터미널 버전은 동일한 모델 구성을 공유합니다. 반복적인 코딩 작업에 적합하며 GitHub, 데이터베이스, 파일에도 연결할 수 있습니다.

설치 전 준비

goose는 Desktop과 CLI 두 가지 설치 방식을 제공합니다. Desktop은 창이 있는 데스크톱 버전이고, CLI는 터미널에 명령을 입력해 사용하는 버전입니다. 두 버전은 Provider와 모델을 포함한 핵심 구성을 공유합니다. Provider는 “goose가 어떤 모델 서비스를 사용할지 지정하는 연결 구성”이라고 이해하면 됩니다.

창이 필요한 경우

goose Desktop

macOS에서는 zip 다운로드
또는 brew cask
Linux에서는 설치 패키지 사용

터미널만 필요한 경우

goose CLI

download_cli.sh
또는 Homebrew CLI
그다음 goose session

Windows

먼저 환경 선택

Git Bash 또는 MSYS2
PowerShell도 사용 가능
명령을 찾을 수 없으면 PATH에 추가

macOS에서는 다운로드하거나 Homebrew를 사용할 수 있습니다. Linux 데스크톱 버전은 배포판용 설치 패키지를 사용합니다. Windows에서는 먼저 안내된 터미널 환경을 확인하세요.

시작하기 전에 현재 모델 목록에 있는 모델 ID를 준비하세요. 모델 ID는 모델 서비스가 특정 모델을 식별할 때 사용하는 이름이며, 사용할 때 전체 값을 그대로 복사해야 합니다.

설치 및 최초 실행

창이 필요한 경우

macOS에는 다음 두 가지 설치 방법이 안내되어 있습니다.

설치 페이지에서 다운로드합니다. 페이지에는 macOS Silicon과 macOS Intel 버전이 있습니다. 다운로드한 zip 파일의 압축을 풀고 안에 있는 프로그램을 실행합니다.
또는 Homebrew를 사용합니다.

brew install --cask block-goose

동일한 애플리케이션을 다운로드하며 업데이트도 함께 처리할 수 있습니다.

Apple Mac M3에서 실행한 뒤 창이 나타나지 않으면 ~/.config에 읽기 및 쓰기 권한이 있는지 확인하세요. goose는 이 디렉터리에 로그를 기록합니다.

Linux 데스크톱 버전은 설치 페이지에서 다운로드합니다. DEB(Ubuntu/Debian), RPM(RHEL/Fedora), Flatpak이 제공됩니다. Debian 또는 Ubuntu에서는 DEB 파일을 다운로드하고 저장된 디렉터리로 이동한 다음 sudo dpkg -i (filename).deb을 실행하고 애플리케이션 메뉴에서 goose를 엽니다. (filename)은 실제 파일명으로 바꾸세요.

Windows 데스크톱 버전은 설치 페이지에서 다운로드하고 zip 파일의 압축을 푼 다음 안에 있는 프로그램을 실행합니다.

터미널만 필요한 경우

macOS와 Linux에서 다음을 실행합니다.

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

설치 중 대화형 구성을 진행하지 않으려면 앞에 CONFIGURE=false를 추가합니다.

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

macOS에서는 다음 명령도 사용할 수 있습니다.

brew install block-goose-cli

설치된 CLI를 업데이트하려면 다음을 사용합니다.

goose update

Windows에서는 다음 세 가지 환경 중 하나가 필요합니다. Git for Windows와 함께 제공되며 권장 항목으로 표시된 Git Bash, MSYS2 또는 Windows 10/11에 기본 포함된 PowerShell입니다. Git Bash와 MSYS2에서는 위와 동일한 download_cli.sh 명령을 사용합니다. PowerShell에서는 먼저 스크립트를 다운로드한 뒤 실행합니다.

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"
.\download_cli.ps1

goose가 PATH에 없다는 메시지가 표시되면 설치 페이지의 안내에 따라 ~/.local/bin 또는 %USERPROFILE%\.local\bin을 현재 셸 구성에 추가한 뒤 터미널을 다시 여세요. PATH는 터미널이 프로그램 위치를 검색하는 디렉터리 모음입니다. 경로가 추가되지 않으면 프로그램이 설치되어 있어도 이름만 입력해서 실행하지 못할 수 있습니다.

2026-10-09 기준 CLI 버전은 1.54.0입니다. 설치 스크립트는 기본적으로 프로그램을 ~/.local/bin에 설치합니다. 환경 변수 GOOSE_BIN_DIR로 이 디렉터리를 변경할 수 있습니다. 변경 후에는 스크립트가 셸 구성을 자동으로 수정하지 않으며, 터미널에 해당 디렉터리가 PATH에 없다는 메시지가 표시됩니다. 그 디렉터리를 PATH에 추가하거나 전체 경로로 실행하세요.

처음 사용할 때 goose가 Provider 구성을 요청합니다. 기본 제공 공급자는 건너뛰고 다음 섹션에 따라 사용자 지정 Provider를 추가할 수 있습니다. 터미널에서 작업할 디렉터리로 이동한 뒤 다음을 실행합니다.

goose session

OmniProxy에서 연결 매개변수 가져오기

자신의 OmniProxy에서 주소, 키, 모델 이름을 준비하세요. 사용자 지정 Provider 예시에서는 base_url을 /v1/chat/completions까지 입력하므로 여기서도 같은 형식을 사용합니다.

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   현재 OmniProxy 모델 목록에서 복사하고, 여러 개일 경우 영문 쉼표로 구분

모델 이름은 현재 OmniProxy 목록에서 전체 값을 복사하고 슬래시도 그대로 유지하세요. 2026-10-09 기준 공급자 문서에서 비교할 수 있는 두 ID는 Grok의 grok-4.7과 OpenAI 문서의 gpt-6-luna입니다. gpt-6-luna는 Chat Completions를 지원합니다. Chat Completions에서 함수 호출은 reasoning_effort가 none일 때만 지원됩니다. 목록에 없는 이름은 그대로 사용하지 마세요.

도구 구성 입력

사용자 지정 Provider는 OpenAI, Anthropic 또는 Ollama 호환 형식을 사용합니다. 호환 형식은 도구가 특정 범용 인터페이스에 따라 요청을 전송하는 방식이라고 이해하면 됩니다. OmniProxy에 연결할 때는 OpenAI Compatible을 선택하세요.

데스크톱 버전

왼쪽 위 버튼을 눌러 사이드바를 엽니다.
Settings를 클릭합니다.
Models를 클릭합니다.
Configure providers를 클릭합니다.
창 아래쪽의 Add Custom Provider를 클릭합니다.
Provider Type에서 OpenAI Compatible을 선택합니다. Display Name에는 OmniProxy를 입력할 수 있습니다. API URL에는 이전 섹션의 주소를 입력합니다. 키가 필요하면 API Key 요구 옵션을 선택하고 OmniProxy 키를 입력합니다. Available Models에는 모델 이름을 입력하며, 여러 개일 경우 영문 쉼표로 구분합니다.
Create Provider를 클릭합니다.

현재 데스크톱 버전에서는 이 창에서 사용자 지정 요청 헤더를 정의할 수 없습니다. 요청 헤더가 필요하면 생성 후 구성 파일을 수정하세요.

터미널

다음을 실행합니다.

goose configure

Custom Providers를 선택한 뒤 Add A Custom Provider를 선택합니다. API Type에서 OpenAI Compatible을 선택하고 안내에 따라 이름, API URL, 키 필요 여부, 모델 이름, 스트리밍 응답 지원 여부를 입력합니다.

Windows에서 수동으로 구성할 때 키링 오류가 발생하면 저장 여부를 묻는 메시지에서 keyring에 저장하지 않도록 선택하고 환경 변수를 사용하세요. 그런 다음 goose configure를 다시 실행합니다. 키링은 시스템에서 키를 저장하는 소규모 보안 저장소입니다.

구성 파일

안내된 디렉터리는 다음과 같습니다.

macOS 및 Linux: ~/.config/goose/custom_providers/
Windows: %APPDATA%\Block\goose\config\custom_providers\

파일은 제공된 예시를 참고해 작성할 수 있습니다. 이름, 주소, 모델을 자신의 값으로 바꾸고 키는 api_key_env에서 지정한 환경 변수에 넣으세요. 실제 키를 파일에 직접 기록하지 마세요.

{
  "name": "omniproxy",
  "engine": "openai",
  "display_name": "OmniProxy",
  "api_key_env": "OMNIPROXY_API_KEY",
  "base_url": "https://your-omniproxy-origin.example/v1/chat/completions",
  "models": [
    { "name": "grok-4.7", "context_limit": 128000 },
    { "name": "gpt-6-luna", "context_limit": 128000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

context_limit에는 예시와 같이 숫자를 유지하세요. 실제 컨텍스트는 모델과 OmniProxy에 따라 달라지므로 이 예시 값을 해당 모델의 공식 한도로 간주하지 마세요. 사용하기 전에 다음을 실행합니다.

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

작업 디렉터리로 이동한 뒤 다음을 실행합니다.

goose session --provider omniproxy --model grok-4.7

--model은 목록에 있는 전체 ID로 바꾸세요. goose session에는 start 하위 명령이 없습니다. --provider와 --model은 환경 변수 GOOSE_PROVIDER, GOOSE_MODEL로 지정할 수도 있습니다. 게이트웨이가 키를 검증하지 않더라도 OMNIPROXY_API_KEY에는 값이 있어야 하며, 로컬에서만 사용하는 임의의 자리표시자 문자열을 사용할 수 있습니다. 2026-10-09에는 이 방식으로 파일을 읽을 수 있었습니다.

창

Settings

사이드바의 Settings
Models 페이지
Add Custom Provider

터미널

goose configure

Custom Providers 선택
그다음 추가 선택
유형은 OpenAI Compatible 선택

파일

custom_providers

macOS와 Linux에서는 ~/.config
Windows에서는 APPDATA
base_url은 공식 예시를 따름

세 가지 방법 모두 같은 종류의 구성을 작성합니다. Provider 유형은 OpenAI Compatible을 선택하세요.

실제 작업으로 확인

일반 파일이 있는 디렉터리로 이동한 뒤 이전 섹션의 goose session을 실행합니다. 지정한 파일의 첫 번째 줄을 읽도록 요청하세요. 구성이 저장되었다는 메시지만 표시하는 것이 아니라 실제 파일 내용을 반환해야 합니다.

파일을 읽거나 명령을 실행하려면 세션에 Developer 확장이 필요합니다. Developer 확장은 goose가 로컬 파일과 명령을 처리할 수 있게 하는 도구 모듈이라고 이해하면 됩니다. 기본 구성에는 일반적으로 포함되어 있습니다. 파일 도구가 없다고 응답하면 명령에 다음을 추가하세요.

--with-builtin developer

--no-profile은 함께 추가하지 마세요. 이 매개변수는 기본 확장을 비활성화합니다.

2026-10-09에 goose 1.54.0으로 지정한 파일의 첫 번째 줄을 읽을 수 있었습니다. 첫 응답에는 약 1분이 걸릴 수 있습니다.

그런 다음 OmniProxy의 호출 기록에서 호출 출처와 모델 이름을 확인합니다.

시작

세션에 진입할 수 있음

goose session
Provider가 방금 추가한 항목임
모델 이름이 목록에 있음

작업

실제로 작업을 수행함

예: 현재 디렉터리 나열
응답 확인하기
저장 성공 여부만 확인하지 않기

기록

게이트웨이에서 확인 가능

주소는 문서 예시를 기준으로 함
키를 저장소에 기록하지 않기
모델 ID가 목록과 일치함

Provider를 저장한 뒤 실제 세션을 한 번 실행해 확인해야 합니다.

자주 발생하는 오류

goose 명령을 찾을 수 없음: 설치 페이지의 안내에 따라 설치 디렉터리를 PATH에 추가한 뒤 터미널을 다시 여세요.
M3 데스크톱 버전에서 창이 나타나지 않음: ~/.config의 읽기 및 쓰기 권한을 확인하세요.
키링 오류: keyring에 저장하지 말고 환경 변수를 사용하세요.
모델이 목록에 없음: 데스크톱 버전에서는 Use custom model을 선택해 모델 이름을 직접 입력할 수 있습니다. goose configure에서는 사용자 지정 모델 이름을 입력할 수 없습니다. 터미널에서는 데스크톱 버전을 사용하거나 구성의 GOOSE_MODEL을 직접 수정해야 합니다.
주소에 연결할 수 없음: API URL이 예시와 동일하게 /v1/chat/completions까지 입력되어 있는지, OmniProxy가 실행 중인지 확인하세요.
파일을 읽을 수 없다고 응답함: Developer 확장을 추가하고 --no-profile을 사용하지 마세요.
unsupported Responses role: system 반환: 일반적으로 주소는 올바릅니다. 모델 목록에 있는 다른 전체 ID로 변경하세요.

공식 참고 자료

설치는 Install goose를 참고하세요. 사용자 지정 Provider는 goose providers를 참고하세요. 예시에 사용된 모델 ID는 xAI 모델 페이지와 GPT-6 Luna에서 확인할 수 있습니다.

모든 플레이스홀더를 고유한 OmniProxy 구성의 값으로 바꾸세요. 실제 키를 게시하지 마세요.

저장된 결과나 HTTP 200 만으로는 전체 에이전트 호환성이 입증되지 않습니다. OmniProxy 호출 기록에서 소스와 모델을 확인하세요.

공식 소스 · goose ↗