Goose 완전 가이드 — 오픈소스 CLI 에이전트, Claude Code 대안

Claude Code는 Anthropic에 묶여 있고, 코드 외 작업은 약합니다. Goose는 Block(Square)이 만들고 리눅스 재단에 기증한 오픈소스 에이전트입니다. Claude, GPT, Gemini, Ollama 다 붙고, 코딩 외 자동화까지 됩니다.

[핵심 요약]
→ Goose: Block(Square)이 만든 오픈소스 범용 AI 에이전트
→ 현재: Linux Foundation AAIF로 이전 (2025년 12월)
→ 형태: 데스크탑 앱 + CLI + API — 3가지 접근 방식
→ 특징: Rust로 작성 → 빠름, macOS/Linux/Windows 전부 지원
→ 모델: 15개+ 프로바이더 지원 (Claude, GPT, Gemini, Ollama, Bedrock...)
→ ACP: 기존 Claude Code, Codex, Gemini CLI 구독 그대로 재사용 가능
→ MCP: 70개+ 익스텐션 연결 (GitHub, DB, 브라우저, Google Drive...)
→ 라이선스: Apache 2.0 — 완전 무료, 상업 이용 가능

---

Claude Code vs Goose — 언제 뭘 쓰나

Claude Code:
→ Anthropic 모델 전용 (사실상)
→ 코딩 태스크 특화, 최고 수준 코드 품질
→ 유료 ($20~$200/월)
→ 터미널 기반

Goose:
→ 어떤 모델이든 붙음 (Claude 포함)
→ 코딩 + 리서치 + 자동화 + 데이터 분석 범용
→ 완전 무료 (API 비용만)
→ 데스크탑 앱 + CLI + API
→ MCP로 외부 도구 연결 쉬움
→ 로컬 모델 (Ollama)로 완전 오프라인 가능
→ 기업 환경에서 커스텀 배포 가능

같이 쓰는 패턴:
→ 코드 품질 중요 → Claude Code
→ 외부 도구 연결 + 자동화 → Goose
→ 로컬/프라이빗 코드베이스 → Goose + Ollama

---

실전 1 — 설치 및 초기 설정

# ── macOS ─────────────────────────────────────────
# 방법 1: 공식 설치 스크립트
curl -fsSL https://github.com/aaif-goose/goose/releases/latest/download/install.sh | bash

# 방법 2: Homebrew
brew install goose-cli

# ── Linux ─────────────────────────────────────────
curl -fsSL https://github.com/aaif-goose/goose/releases/latest/download/install.sh | bash

# ── Windows ───────────────────────────────────────
# 데스크탑 앱 다운로드: https://github.com/aaif-goose/goose/releases
# 또는 WSL에서 Linux 설치

# 버전 확인
goose --version  # goose 1.33.x

프로바이더 설정

# 대화형 설정 마법사
goose configure

# 메뉴에서 선택:
# 1. Anthropic (Claude)
# 2. OpenAI (GPT)
# 3. Google (Gemini) — 무료 티어 존재
# 4. Ollama — 로컬 모델
# 5. ACP — 기존 Claude Code 구독 재사용
# ...

~/.config/goose/profiles.yaml 직접 편집:

# profiles.yaml — 여러 프로파일 설정

profiles:
  # 기본 프로파일 — Claude
  default:
    provider: anthropic
    model: claude-sonnet-4-5
    api_key: ${ANTHROPIC_API_KEY}

  # 무료 프로파일 — Gemini Free Tier
  free:
    provider: google
    model: gemini-2.5-flash
    api_key: ${GOOGLE_API_KEY}

  # 완전 로컬 — Ollama
  local:
    provider: ollama
    model: qwen3-coder:7b
    host: http://localhost:11434

  # 비용 최적화 — 태스크별 라우팅
  optimized:
    routing:
      code_generation:
        provider: anthropic
        model: claude-sonnet-4-5
      simple_tasks:
        provider: ollama
        model: qwen3-coder:7b
      code_review:
        provider: openai
        model: gpt-4o-mini

---

실전 2 — CLI 기본 사용법

# ── 대화형 모드 ───────────────────────────────────
goose session

# 특정 프로파일로
goose session --profile free

# ── 단일 명령 실행 ────────────────────────────────
goose run "현재 디렉토리의 Python 파일에서 미사용 import 전부 제거해줘"

# ── 레시피(자동화 워크플로우) 실행 ───────────────
goose run --recipe deploy.yaml

# ── 파일 컨텍스트 포함 ────────────────────────────
goose run "이 코드 리뷰해줘" --context ./src/main.py

# ── 특정 디렉토리에서 실행 ────────────────────────
goose run "테스트 커버리지 분석하고 누락된 테스트 작성해줘" \
  --workdir /path/to/project

Goose가 실제로 하는 것들

# 예시 1: 프로젝트 전체 리팩토링
goose run "
모든 Python 파일에서 에러 핸들링 리팩토링:
- 커스텀 예외 클래스로 표준화
- 적절한 로깅 추가
- API 호출에 retry 로직 추가
- 새 예외 케이스 테스트 업데이트
"

# Goose가 실제로:
# → 파일 구조 스캔
# → 기존 예외 패턴 분석
# → 커스텀 예외 클래스 생성
# → 각 파일 수정
# → 테스트 업데이트
# → 변경사항 요약 리포트

# 예시 2: API 문서 자동 생성
goose run "
프로젝트 API 라우트 분석해서:
1. OpenAPI 3.0 스펙 파일 생성
2. Markdown 사용 문서 생성
3. Postman 컬렉션 생성
"

# 예시 3: 데이터 분석 파이프라인
goose run "
sales_data.csv 분석해서:
- 월별 매출 트렌드 계산
- 이상치 탐지
- 시각화 차트 생성 (matplotlib)
- 인사이트 리포트 작성
"

---

실전 3 — MCP 확장 연결

Goose의 진짜 강점은 MCP로 외부 도구를 연결하는 것입니다.

# ~/.config/goose/config.yaml — MCP 서버 설정

mcp_servers:
  # GitHub 연동
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}

  # PostgreSQL 연동
  - name: postgres
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      DATABASE_URL: postgresql://localhost:5432/mydb

  # 파일시스템 접근
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"]

  # 브라우저 자동화
  - name: browser
    command: npx
    args: ["-y", "@modelcontextprotocol/server-puppeteer"]

  # Slack 연동
  - name: slack
    command: npx
    args: ["-y", "@modelcontextprotocol/server-slack"]
    env:
      SLACK_BOT_TOKEN: ${SLACK_BOT_TOKEN}

MCP 연결 후 가능한 워크플로우:

# GitHub 이슈 → 코드 수정 → PR 자동화
goose run "
GitHub에서 라벨이 'bug'인 열린 이슈 목록 가져와서,
각 이슈를 분석하고 수정 가능한 것들 코드 수정 후
PR 생성해줘
"

# DB 스키마 분석 + 문서화
goose run "
PostgreSQL 데이터베이스 스키마 분석해서
ER 다이어그램용 Mermaid 코드 생성하고
각 테이블 용도 설명한 문서 작성해줘
"

# 슬랙 + GitHub 통합 자동화
goose run "
오늘 머지된 PR 목록 가져와서
변경사항 요약하고
#dev-updates 슬랙 채널에 알림 보내줘
"

---

실전 4 — Recipe(레시피)로 워크플로우 자동화

반복 작업은 YAML 레시피로 저장해서 재사용합니다.

# recipes/code-review.yaml
name: 코드 리뷰 자동화
description: PR 변경사항 리뷰 및 피드백 생성

version: "1.0"
provider: anthropic
model: claude-sonnet-4-5

steps:
  - name: PR 정보 수집
    prompt: |
      GitHub MCP를 사용해서 최근 열린 PR 목록 가져와줘.
      각 PR의 변경 파일 수, 라인 수, 설명 포함해서.

  - name: 코드 품질 분석
    prompt: |
      각 PR의 변경사항 분석해서:
      - 버그 가능성
      - 보안 취약점
      - 성능 문제
      - 코드 스타일 위반
      체크해줘

  - name: 리뷰 코멘트 작성
    prompt: |
      분석 결과를 바탕으로 각 PR에 리뷰 코멘트 달아줘.
      심각한 이슈는 'REQUEST_CHANGES', 제안사항은 'COMMENT'로.

  - name: 요약 리포트
    prompt: |
      전체 리뷰 결과 요약해서 Slack #code-review 채널에 올려줘.

# recipes/deploy-check.yaml
name: 배포 전 체크리스트
description: 배포 전 자동 검증

steps:
  - name: 테스트 실행
    shell: npm test -- --coverage

  - name: 빌드 검증
    shell: npm run build

  - name: 보안 스캔
    prompt: |
      프로젝트 의존성에서 알려진 취약점 확인하고
      심각도 HIGH 이상 이슈 있으면 배포 중단해줘

  - name: 환경변수 검증
    prompt: |
      .env.example과 실제 환경변수 비교해서
      누락된 변수 있으면 알려줘

# 레시피 실행
goose run --recipe recipes/code-review.yaml
goose run --recipe recipes/deploy-check.yaml

# 레시피 목록
goose recipe list

# 커뮤니티 레시피 검색
goose recipe search "ci-cd"

[레시피 활용 패턴]
→ 매일 아침 이슈 트리아지 자동화
→ PR 머지 전 자동 리뷰
→ 주간 기술 부채 리포트
→ 배포 전 자동 검증
→ 팀 전체 공유 레시피로 워크플로우 표준화

---

실전 5 — 기업용 커스텀 배포

팀 전체에 Goose를 배포할 때 커스텀 배포 설정을 씁니다.

# custom-distro.yaml — 팀용 Goose 배포 설정

name: "MyCompany Goose"
version: "1.0.0"

# 허용된 프로바이더만
allowed_providers:
  - anthropic
  - ollama  # 로컬 모델

# 회사 MCP 서버 자동 연결
mcp_servers:
  - name: internal-jira
    url: https://mcp.company.internal/jira
  - name: internal-confluence
    url: https://mcp.company.internal/confluence

# 보안 정책
security:
  # 허용된 명령어만
  allowed_commands:
    - git
    - npm
    - pip
    - python
    - docker
  # 접근 금지 디렉토리
  blocked_paths:
    - ~/.ssh
    - /etc
    - /var
  # 위험 작업은 확인 필요
  require_confirmation:
    - "rm -rf"
    - "DROP TABLE"
    - "DELETE FROM"

# 로깅
logging:
  enabled: true
  destination: https://logs.company.internal/goose
  include_prompts: false  # 프라이버시

# 브랜딩
branding:
  name: "MyCompany AI Agent"
  welcome_message: "안녕하세요! 회사 AI 에이전트입니다."

---

마무리

✅ Goose가 빛나는 경우
→ Claude Code 말고 다른 모델도 쓰고 싶을 때
→ 코딩 외 자동화 (리서치, 데이터 분석, 문서화) 필요할 때
→ 로컬 실행으로 코드 프라이버시 지켜야 할 때
→ MCP로 여러 외부 도구 연결하는 복합 워크플로우
→ 팀 전체에 표준화된 에이전트 배포하고 싶을 때
→ 무료로 시작하고 싶을 때 (Gemini 무료 티어 연결)

❌ Goose가 안 맞는 경우
→ 순수 코딩 품질만 최우선 (Claude Code가 우세)
→ IDE 깊은 통합이 필요한 경우 (Cursor가 더 적합)
→ 설정 없이 바로 쓰고 싶을 때 (초기 설정 존재)

---

관련 글

• Claude Code 한도 자꾸 걸리는 이유와 요금제 선택 가이드
• OpenCode 완전 가이드 — 자체 API 키로 Claude Code 대신 쓰는 오픈소스 터미널 에이전트
• AI 에이전트 옵저버빌리티 완전 가이드 — 에이전트가 뭘 하는지 추적하는 법