OpenCode 설치 및 사용법: 종합 가이드

약 3 분

OpenCode 설치 및 사용법: 종합 가이드

OpenCode는 인공지능의 힘을 직접 터미널에 불어넣는 오픈소스 AI 코딩 에이전트입니다. 에디터나 브라우저에 머무르는 기존 AI 코딩 도구와 달리, OpenCode는 터미널 기반 인터페이스, 데스크톱 앱, IDE 확장 기능을 제공하여 개발자의 생산성을 극대화합니다. 이 포괄적인 가이드는 OpenCode를 효과적으로 설치, 구성 및 사용하는 데 필요한 모든 정보를 안내합니다.

OpenCode란?

OpenCode는 AI 기반 코딩 도우미로서 다음을 지원합니다:

지능적인 코드 생성 및 완성을 통해 더 빠른 코딩
오류 분석과 수정 제안으로 효율적인 디버깅
자연어 질의를 통한 코드베이스 이해
자동화된 계획과 구현으로 기능 추가
AI 기반 분석과 제안으로 코드 리뷰
AI 에이전트 및 맞춤 도구를 활용한 워크플로우 자동화

Anthropic, OpenAI, Google 등 여러 LLM 공급자를 지원하여 필요에 맞는 모델을 자유롭게 선택할 수 있습니다.

시스템 요구 사항

사전 준비 사항

OpenCode 설치 전에 다음을 준비하세요:

최신 터미널 에뮬레이터 (TUI 사용 시):
- WezTerm - 크로스플랫폼
- Alacritty - 크로스플랫폼
- Ghostty - 리눅스 및 macOS
- Kitty - 리눅스 및 macOS
Node.js (npm/bun/pnpm/yarn 설치용):
- Node.js v18 이상 권장
LLM 공급자 API 키:
- Anthropic API 키 (Claude 모델용)
- OpenAI API 키 (GPT 모델용)
- 또는 기타 지원 공급자 API 키

설치 방법

방법 1: 설치 스크립트 (추천)

가장 빠른 설치 방법은 공식 설치 스크립트 사용입니다:

curl -fsSL https://opencode.ai/install | bash

macOS, Linux, Windows(Git Bash 또는 WSL 사용)에서 작동합니다.

방법 2: Node.js 패키지 매니저 사용

npm 사용:

npm install -g opencode-ai

Bun 사용:

bun install -g opencode-ai

pnpm 사용:

pnpm install -g opencode-ai

Yarn 사용:

yarn global add opencode-ai

방법 3: Homebrew 사용 (macOS 및 Linux)

brew install opencode

방법 4: Paru 사용 (Arch Linux)

paru -S opencode-bin

방법 5: 윈도우 전용 설치

Chocolatey 사용:

choco install opencode

Scoop 사용:

scoop bucket add extras
scoop install extras/opencode

Mise 사용:

mise use -g github:sst/opencode

방법 6: Docker

컨테이너 환경에서 사용:

docker run -it --rm ghcr.io/sst/opencode

방법 7: 바이너리 다운로드

GitHub Releases 페이지에서 미리 컴파일된 바이너리를 직접 다운로드할 수 있습니다.

설치 확인

설치 후 정상 작동 확인:

opencode --version

버전 번호가 출력되어야 합니다.

초기 설정

OpenCode Zen 연결 (초보자 권장)

OpenCode Zen은 OpenCode 팀에서 테스트 및 검증한 모델 모음입니다. 가장 간편한 시작 방법입니다.

OpenCode 실행:

cd /path/to/your/project
opencode

TUI에서 connect 명령 실행:

/connect

공급자 목록에서 "opencode" 선택
인증 URL 방문: opencode.ai/auth
로그인 후 결제 정보 등록 (무료 크레딧 사용 가능)
API 키 복사 후 터미널에 붙여넣기

기타 공급자 연결

다른 LLM 공급자도 연결 가능합니다:

`/connect` 명령어 사용:

/connect

원하는 공급자(Anthropic, OpenAI, Google 등) 선택 후 인증 절차 진행.

CLI 인증 사용:

opencode auth login

Models.dev에 등록된 공급자의 API 키 설정 안내를 받습니다.

설정된 공급자 리스트 표시:

opencode auth list

짧은 명령어:

opencode auth ls

공급자 로그아웃:

opencode auth logout

프로젝트 컨텍스트 설정

공급자 구성 후 프로젝트에 OpenCode 초기화:

프로젝트 디렉터리로 이동:

cd /path/to/your/project

OpenCode 실행:

opencode

init 명령 실행:

/init

프로젝트 구조 분석 후 프로젝트 루트에 AGENTS.md 파일 생성. 이 파일은 OpenCode가 코딩 패턴, 프레임워크, 아키텍처를 이해하는 데 도움을 줍니다.

팁: AGENTS.md 파일을 Git에 커밋하세요. 팀 간 일관성과 OpenCode의 프로젝트 이해도를 향상시킵니다.

터미널 사용자 인터페이스 (TUI) 사용법

OpenCode의 TUI는 터미널에서 인터랙티브한 경험을 제공합니다.

TUI 시작

간단히 실행:

opencode

옵션 플래그 사용 예:

# 지난 세션 이어서 실행
opencode --continue

# 특정 세션 이어서 실행
opencode --session <session-id>

# 프롬프트 입력과 함께 시작
opencode --prompt "이 코드베이스 설명해줘"

# 특정 모델 사용
opencode --model anthropic/claude-sonnet-4-5

# 특정 에이전트 사용
opencode --agent plan

기본 TUI 탐색

스크롤: 마우스 휠 또는 화살표 키
모드 전환: Tab 키로 Plan 모드와 Build 모드 전환
명령 실행: / 입력 후 명령 팔레트 접근
파일 검색: @ 입력 후 프로젝트 내 파일 퍼지 검색
종료: Ctrl+C 또는 /exit 입력

질문하기

코드베이스에 대해 OpenCode에 질문 가능:

How is authentication handled in @packages/functions/src/api/index.ts

@ 기호로 특정 파일 참조. OpenCode가 해당 파일을 분석하고 상세 설명 제공.

기능 추가하기

OpenCode는 두 가지 모드 워크플로우를 통해 강력한 기능 추가를 지원합니다:

1단계: Plan 모드

Tab 키로 Plan 모드로 전환
원하는 작업 설명:

사용자가 노트를 삭제할 때 데이터베이스에서 삭제된 것으로 표시하려고 합니다.
그 다음 최근 삭제된 노트 모두를 보여주는 화면을 만듭니다.
사용자는 이 화면에서 노트를 복구하거나 영구 삭제할 수 있습니다.

제안된 계획 검토
피드백과 반복:

이 새 화면의 디자인은 전에 사용한 디자인을 참고하고 싶습니다.
[이미지 #1] 이 이미지를 참고해 주세요.

팁: 터미널에 이미지를 드래그 앤 드롭 가능. OpenCode가 스캔하고 분석합니다.

2단계: Build 모드

다시 Tab 키로 Build 모드 전환
구현 승인:

좋아요! 변경 작업 해주세요.

OpenCode가 기능을 구현하며 필요한 파일 생성과 수정을 진행합니다.

직접 변경하기

간단한 변경은 계획 단계를 건너뛸 수 있습니다:

/settings 경로에 인증 기능을 추가해야 합니다.
@packages/functions/src/notes.ts 파일의 /notes 경로 인증 방식을 참고해서
@packages/functions/src/settings.ts 에 동일한 로직을 구현해 주세요.

변경 취소 및 재실행

실수했다면 취소 명령어 사용:

/undo

최근 변경사항을 되돌리고 프롬프트를 수정할 수 있습니다.

취소한 작업 다시 실행:

/redo

여러 번 /undo를 실행해 여러 변경을 연속 취소 가능.

CLI 명령어

OpenCode는 프로그래밍 및 자동화를 위한 강력한 CLI를 제공합니다.

직접 프롬프트 실행

비대화식으로 OpenCode 실행:

opencode run "Explain how closures work in JavaScript"

스크립트, 자동화 또는 TUI 실행 없이 빠른 답변에 유용.

모델 관리

모든 사용 가능한 모델 나열:

opencode models

공급자별 필터링:

opencode models anthropic

모델 캐시 갱신 (새 모델 추가 시):

opencode models --refresh

비용 포함 상세 모델 정보 보기:

opencode models --verbose

헤드리스 서버 시작

API 접근용 HTTP 서버 실행:

opencode serve

포트 지정:

opencode serve --port 3000

웹앱 통합이나 스크립트 내 빠른 응답(서버 콜드 부팅 회피)에 유용.

서버에 연결

한 터미널에서 서버 시작:

opencode serve

다른 터미널에서 연결해 빠른 실행:

opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

에이전트 관리

커스텀 에이전트 생성:

opencode agent create

커스텀 시스템 프롬프트 및 도구 설정을 안내합니다.

GitHub 통합

리포지토리 자동화를 위한 GitHub 에이전트 설치:

opencode github install

자동 코드 리뷰, 이슈 관리용 GitHub Actions 워크플로우 설정.

OpenCode 업그레이드

최신 버전으로 업그레이드:

opencode upgrade

특정 버전으로 업그레이드:

opencode upgrade v0.1.48

설치 방식 지정:

opencode upgrade --method brew

구성

OpenCode는 JSON 구성 파일을 통해 유연한 설정을 지원합니다.

구성 파일 위치

구성 파일은 병합되며(덮어쓰기 아님) 글로벌, 프로젝트별, 커스텀 구성이 동시에 가능:

글로벌 구성: ~/.config/opencode/opencode.json
- 테마, 공급자, 키바인드, 일반 설정용
프로젝트 구성: 프로젝트 루트의 opencode.json
- 프로젝트별 공급자, 에이전트, 설정용
- Git에 안전하게 커밋 가능
커스텀 구성 경로: OPENCODE_CONFIG 환경 변수로 지정 가능
커스텀 구성 디렉터리: OPENCODE_CONFIG_DIR 환경 변수로 지정 가능

기본 구성 예시

다음 형태로 구성 파일 생성:

{
  "$schema": "https://opencode.ai/config.json",
  
  // 테마 선택
  "theme": "opencode",
  
  // 기본 모델
  "model": "anthropic/claude-sonnet-4-5",
  
  // 가벼운 작업용 소형 모델
  "small_model": "anthropic/claude-haiku-4-5",
  
  // 자동 업데이트 설정
  "autoupdate": true
}

공급자 구성

API 키를 직접 구성에 입력 가능:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

환경 변수 사용 권장. {env:변수명} 형식 사용.

파일 참조 사용

민감한 데이터는 파일 참조 가능:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

커스텀 명령어

자주 하는 작업에 맞춤 명령어 정의 가능:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run full test suite with coverage report and show any failures.\nFocus on failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

TUI에서 /test 또는 /component MyComponent로 사용 가능.

커스텀 에이전트

전문화된 에이전트 생성:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

권한 설정

OpenCode가 사용자 승인 없이 수행 가능한 작업 제어:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

편집 및 bash 명령 수행 시 사용자 승인 필요.

코드 포매터 설정

코드 자동 포매팅 설정:

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": false
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

TUI 설정

터미널 인터페이스 커스터마이즈:

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

고급 기능

대화 공유

팀과 대화를 공유:

/share

공유 가능한 링크 생성 후 클립보드에 복사. 대화는 기본적으로 공유되지 않음.

공유 동작 구성:

{
  "share": "manual"  // "manual", "auto", "disabled" 중 선택
}

MCP 서버

Model Context Protocol(MCP) 서버로 OpenCode 기능 확장:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  }
}

지침 및 규칙

프로젝트 특정 지침 제공:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

OpenCode가 코딩 표준 및 컨벤션 이해에 도움.

환경 변수

OpenCode 환경 변수로 구성:

# 세션 자동 공유 활성화
export OPENCODE_AUTO_SHARE=true

# 커스텀 구성 경로
export OPENCODE_CONFIG=/path/to/config.json

# 구성 디렉터리 경로
export OPENCODE_CONFIG_DIR=/path/to/config-dir

# 자동 업데이트 비활성화
export OPENCODE_DISABLE_AUTOUPDATE=true

# 기본 플러그인 비활성화
export OPENCODE_DISABLE_DEFAULT_PLUGINS=true

# 실험적 모델 활성화
export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true

# Exa 웹 검색 활성화
export OPENCODE_ENABLE_EXA=true

실험 기능

실험 기능 활성화:

export OPENCODE_EXPERIMENTAL=true

특정 실험 기능 활성화:

# 아이콘 발견 기능 활성화
export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true

# TUI에서 선택 시 복사 비활성화
export OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT=true

# bash 명령 최대 출력 길이 설정
export OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH=10000

# bash 명령 기본 타임아웃(ms) 설정
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=30000