goose 코드 에이전트 튜토리얼: 설치, 모델 소스, API 설정 및 비용

goose는 Apache-2.0 오픈 소스 AI 코드 에이전트로, 터미널이나 데스크톱 앱에서 파일을 읽고 수정하며 명령을 실행할 수 있습니다. 시작하려면 설치하고, 모델 소스(provider)를 선택한 뒤, 작업을 맡길 세션을 열면 됩니다. goose 자체는 무료이며 비용은 연결한 모델에서 발생합니다.이 튜토리얼은 2026년 10월 1일의 공식 문서를 바탕으로 설치 방법, 세 가지 유료 경로, OpenAI 호환 엔드포인트에 연결하는 방법(가장 자주 발생하는 /v1 함정 포함), 일반적인 사용법을 설명합니다. 최신 버전은 2026년 9월 23일에 출시된 v1.52.0입니다.

먼저 이름부터 정리하겠습니다. 이 페이지에서 다루는 것은 goose-docs.ai의 코드 에이전트이며, 저장소는 aaif-goose/goose입니다. 원래 block/goose였고 2026년 4월 Linux Foundation의 Agentic AI Foundation으로 이전했습니다. 이것은 goose.ai가 아닙니다 — goose.ai는 별도의 호스팅 추론 서비스이며 가격도 관련이 없습니다. goose에는 현재 중국어 번체 인터페이스가 없으므로 아래 메뉴 이름은 영어 원문 그대로 씁니다.

설치

공식적으로 데스크톱 버전(goose Desktop)과 명령줄 버전(goose CLI)을 제공하며, 두 버전은 동일한 설정을 읽습니다.

# goose Desktop(macOS)
brew install --cask block-goose

# goose CLI（macOS / Linux / Windows 的 Git Bash）
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

# 只安裝、先不進入設定
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# 或用 Homebrew 裝 CLI
brew install block-goose-cli

Windows에서는 공식 웹사이트에서 데스크톱 버전을 다운로드할 수 있습니다. CLI는 Git Bash에서 동일한 한 줄 설치 명령을 실행하는 것을 권장합니다(PowerShell도 가능합니다). Homebrew 패키지 이름은 여전히 block-goose이며, 이름 변경이 설치 패키지에 완전히 반영되지 않은 결과일 뿐 프로젝트가 여전히 Block 소유라는 뜻은 아닙니다.

첫 실행: 모델 소스 선택

goose Desktop을 처음 열면 시작 화면이 표시되고, CLI는 자동으로 설정 모드로 들어갑니다(나중에 변경하려면 goose configure을 실행할 수 있습니다). 설치 페이지에 나오는 옵션은 세 가지입니다.

• OpenRouter Login —— OpenRouter 계정으로 로그인하여 모델을 자동으로 설정합니다.
• Tetrate Agent Router Service Login —— Tetrate로 로그인합니다. 문서에 따르면 goose를 통해 처음 자동 인증하면 $10 무료 크레딧을 받으며, 신규 사용자와 기존 사용자 모두에게 적용됩니다.
• Manual Configuration —— provider를 직접 선택하고 키를 입력합니다. Kunavo 같은 OpenAI 호환 엔드포인트에 연결하려면 이 경로를 사용하세요.

세 가지 유료 경로, 먼저 올바르게 선택하기

ACP 경로에 대한 설명은 goose의 ACP providers 문서에서 가져왔으며, 이 문서에서는 ACP의 session ID가 goose의 것과 다르고 텔레메트리 필드가 서로 맞지 않을 수 있다고도 안내합니다. 이미 구독이 있고 API 비용만 줄이고 싶은 사람은 이 경로부터 확인하세요.

OpenAI 호환 엔드포인트 연결: Host URL에 /v1을 추가하지 않기

가장 많이 막히는 부분입니다. goose는 전체 base URL을 사용하지 않고 “호스트”와 “경로”로 나눕니다. providers 문서에 따르면 OPENAI_HOST는 “사용자 지정 엔드포인트 URL(기본값 api.openai.com)”, OPENAI_BASE_PATH는 “호스트 뒤에 추가되는 요청 경로(기본값 v1/chat/completions)”이며, 프록시에 연결할 때는 OPENAI_HOST를 “경로를 제외한 프록시의 루트 주소”로 설정해야 합니다. Kunavo의 경우:

# goose Desktop → Settings → Models → Configure providers → OpenAI
API Key           sk-kn-...
Host URL          https://api.kunavo.com      ← 只寫網域，不加 /v1
Organization ID   （留空）
Project           （留空）

# 或用環境變數（CLI 也讀）
export OPENAI_API_KEY=sk-kn-...
export OPENAI_HOST=https://api.kunavo.com
# OPENAI_BASE_PATH 不要設：預設就是 v1/chat/completions

goose Desktop에서는 Settings → Models → Configure providers → OpenAI에 있으며, CLI에서는 goose configure → Configure Providers → OpenAI로 이동합니다. Organization ID와 Project는 OpenAI 자체 계정용이므로 비워 두면 됩니다. Host URL을 https://api.kunavo.com/v1로 입력하면 요청이 /v1/v1/chat/completions가 됩니다. 문서 자체도 “404는 일반적으로 OPENAI_BASE_PATH가 프록시에 맞지 않는다는 뜻”이라고 설명합니다 — 경로가 잘못된 것이지 키가 잘못된 것이 아닙니다. 반대로 401 “No api key passed in”이 표시되면 키를 읽지 못한 것입니다. 예를 들어 키를 config.yaml에 입력하면 goose가 무시합니다.

더 깔끔한 방법은 목록에 독립적인 provider로 추가하는 것입니다. goose는 custom_providers 폴더에서 JSON 정의 파일을 읽습니다. Kunavo는 실시간 가격표에서 생성한 파일을 제공하며, 도구 호출을 지원하는 모델만 포함하고 키 자체가 아니라 키 변수 이름만 기록합니다.

# macOS / Linux:goose 會讀這個資料夾裡所有 JSON
mkdir -p ~/.config/goose/custom_providers
curl -fsSL https://kunavo.com/goose/kunavo.json \
  -o ~/.config/goose/custom_providers/kunavo.json

# 檔案裡只有變數名稱，金鑰另外設定
export KUNAVO_API_KEY=sk-kn-...
goose session start --provider kunavo

Windows 폴더는 %APPDATA%\Block\goose\config\custom_providers\입니다. 파일을 넣으면 goose Desktop의 Configure providers에 Kunavo가 표시되며, 키를 환경 변수 대신 시스템 키체인에 저장할 수 있습니다. goose 소스 코드에 따르면 ID가 gpt-5 또는 gpt-6로 시작하는 모델은 /v1/responses를 사용하고, 나머지는 /v1/chat/completions를 사용합니다. Kunavo는 두 방식 모두 제공합니다. 직접 만들 수도 있습니다: Configure providers → Add Custom Provider, 유형은 OpenAI Compatible, API URL은 https://api.kunavo.com/v1로 입력합니다. 전체 영어 설정 페이지는 goose integration guide에 있습니다.

솔직히 말하면: 위 설정은 goose 문서와 소스 코드를 정리한 것이며, Kunavo는 자체 엔드포인트에서 goose를 실제로 실행해 보지 않았습니다 — 세션, 스트리밍 또는 도구 왕복을 실행한 적이 없습니다. 현재 작동하는 경로를 유지하고, 먼저 파일을 읽고 쓸 수 있는 작은 작업을 맡겨 테스트하세요.

일반적인 사용법

• 세션 열기:goose session ( -n 名稱로 이름 지정 가능), 이후 goose session --resume -n 名稱로 이어서 진행하고 goose session list로 기록을 확인합니다.
• 권한 모드 전환: 세션에서 /mode을 입력하면 auto, approve, chat, smart_approve를 선택할 수 있습니다. 매 단계마다 먼저 묻게 하려면 approve를 사용하세요.
• 모델 선택:goose configure에는 사용자 지정 모델 이름을 입력할 수 없습니다. 목록에 없는 ID는 goose Desktop에서 입력하거나 config.yaml에 GOOSE_MODEL를 설정하세요.
• 프로젝트 설명 파일: goose는 기본적으로 .goosehints과 AGENTS.md를 읽으며(CONTEXT_FILE_NAMES로 제어), 프로젝트 규칙을 이 파일에 작성하면 다른 에이전트로 바꿀 때도 가져갈 수 있습니다.
• 도구 호출을 지원하지 않는 모델은 선택하지 마세요: 문서에 따르면 그러한 모델은 “채팅 완성만 수행할 수 있으며”, 확장 기능도 꺼야 합니다.

세션 하나에 드는 대략적인 비용

다음은설명용 토큰 계산이며, 실제 작업 비용이나 청구 한도가 아닙니다. 한 에이전트 세션에서 여러 라운드에 걸쳐 총 캐시되지 않은 입력 토큰 400,000개를 보내고 출력 토큰 25,000개를 받는다고 가정합니다(에이전트는 매 라운드마다 컨텍스트를 다시 보내므로 입력이 특히 많습니다). 단가는 Kunavo 가격표의 실시간 토큰 100만 개당 가격을 사용합니다.

캐싱에 관하여: goose 문서에 따르면 Anthropic, Amazon Bedrock, Databricks, OpenRouter, LiteLLM provider를 통해 Claude를 사용할 때 Anthropic의 cache_control 마커가 자동으로 추가됩니다. 범용 OpenAI provider를 통해 사용하는 Claude는 이 목록에 포함되지 않으므로 goose가 해당 마커를 추가하지 않습니다. 따라서 위 표는 캐시 할인이 없다고 가정한 보수적인 추정입니다. Kunavo 가격표의 금액은 상한이 아니라 청구 하한입니다. 업스트림에서 비용을 보고하면 청구 금액은 “가격표 금액”과 “업스트림 비용 × 적용 마크업” 중 더 큰 금액으로 계산됩니다.

대만에서 결제하기

Kunavo는 선불 충전 방식으로 token 단위로 차감하며 월정액은 없습니다. 최소 충전 금액은 $10이고, 결제는 Stripe를 통해 진행됩니다. 대만에서는 신용카드(Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay 및 Link를 사용할 수 있으며 StreetPay와 LINE Pay는 사용 가능한 목록에 없습니다. 자세한 내용은 청구 안내를 참조하고, 준비가 되면 계정을 생성하여 키를 발급하세요. 다른 에이전트를 비교하려면 영어로 된 goose alternatives 및 goose vs Claude Code를 참조하세요.

자주 묻는 질문

2026년 10월 1일 확인: goose 설치, providers, ACP providers, CLI 명령 및 환경 변수 문서(aaif-goose/goose main 브랜치), 그리고 GitHub API의 버전 및 보관 상태. Kunavo는 자체 엔드포인트에서 goose를 실제로 실행해 보지 않았습니다. 가격은 실시간 가격표에서 가져왔으며, 모든 금액 예시는 설명용 토큰 계산입니다.