포스트

OpenCode - AI 기반 코딩 어시스턴트

게시 업데이트
By Juho
14 분읽는 시간

목차

  1. OpenCode란?
  2. 핵심 특징
  3. 설치 방법
  4. 기본 사용법
  5. 주요 명령어
  6. 고급 기능
  7. CLI 명령어
  8. 설정 파일
  9. 권한 설정
  10. 개발 워크플로우
  11. 참고 자료

OpenCode란?

OpenCode는 완전히 무료이고 소스 코드가 공개된 오픈소스 AI 코딩 에이전트다.

개발자가 자연어로 작업을 설명하면 AI가 코드를 생성하고 수정해주는 CLI 기반 도구로, GitHub Copilot이나 Cursor, Claude Code와 같은 AI 코딩 도구의 오픈소스 대안이다.

터미널, IDE, 데스크톱 앱에서 모두 사용할 수 있으며, 다양한 LLM 공급자를 연결하여 사용할 수 있다는 것이 가장 큰 장점이다.

핵심 특징

OpenCode가 제공하는 주요 특징은 다음과 같다:

  • 완전 오픈소스: 소스 코드가 공개되어 있고 무료로 사용 가능
  • LSP 지원: Language Server Protocol을 자동으로 로딩하여 코드 이해도 향상
  • 멀티 세션: 하나의 프로젝트에서 여러 에이전트를 병렬로 실행 가능
  • 세션 공유: 대화 내용을 링크로 공유하여 팀 협업 가능
  • 75+ LLM 제공자: Claude, GPT, Gemini 및 로컬 모델까지 다양한 LLM 지원
  • Claude Pro/Max 연동: Anthropic 계정으로 로그인하여 기존 구독 활용 가능
  • 지능적인 코드 생성: AI 기반 코드 생성, 오류 분석, 자동화된 계획과 구현

설치 방법

OpenCode는 다양한 방법으로 설치할 수 있다.

공식 설치 스크립트 (권장)

1
2
3
4
5

# Linux 및 macOS
curl -fsSL https://opencode.ai/install | bash

# 설치 후 정상 작동 확인
opencode --version

npm

1

npm install -g opencode-ai

Homebrew (macOS/Linux)

1

brew install opencode

Windows

Chocolatey

1

choco install opencode

Scoop

1
2

scoop bucket add extras
scoop install extras/opencode

Arch Linux

1

paru -S opencode-bin

Docker

1

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

바이너리 다운로드

GitHub Releases에서 직접 바이너리를 다운로드할 수 있다.

기본 사용법

초기 설정

1
2
3
4
5
6
7
8

# LLM 공급자 연결
/connect

# 또는 CLI 명령어로
opencode auth login

# 설정된 LLM 공급자 리스트 표시
opencode auth list

OpenCode는 Anthropic(Claude), OpenAI(GPT), Google(Gemini) 등 75개 이상의 LLM 공급자를 지원한다. 자신의 환경에 맞는 API 키를 설정하여 사용할 수 있다.

프로젝트 시작

1
2
3
4
5

# 프로젝트 디렉토리로 이동
cd /path/to/your/project

# OpenCode 실행
opencode

프로젝트 초기화

1
2

# init 명령어 실행
/init

/init 명령어를 실행하면 루트 디렉토리에 AGENTS.md 파일이 생성된다. 이 파일은 OpenCode가 프로젝트의 코딩 패턴, 프레임워크, 아키텍처를 이해하는 데 도움을 주는 중요한 문서이다.

주요 명령어

OpenCode TUI(터미널 사용자 인터페이스)에서 사용할 수 있는 주요 명령어는 다음과 같다.

명령어기능
/connectLLM 제공자 선택 및 연결
/init프로젝트 초기화 및 AGENTS.md 생성
/undo변경사항 되돌리기
/redo변경사항 다시 적용
/models사용 가능한 모델 확인 및 전환
/sessions이전 세션 목록 확인
/compact세션 요약
/export대화를 마크다운으로 내보내기
/share대화 내용 공유 링크 생성

Plan 모드와 Build 모드

Tab 키를 눌러 Plan 모드와 Build 모드를 전환할 수 있다.

Plan 모드: 작업을 계획하고 검토하는 단계

  1. 원하는 작업을 자연어로 설명
  2. AI가 제안한 계획을 검토
  3. 필요시 피드백을 주고 계획을 반복적으로 개선
  4. 코드를 직접 수정하지 않고 설계에 집중

Build 모드: 실제로 코드를 구현하는 단계

  1. Plan 모드에서 검토한 계획을 승인
  2. AI가 자동으로 코드를 생성하거나 수정
  3. 실제 파일이 생성되고 수정됨

Build 모드에서는 AI가 실제로 파일을 생성하고 수정하므로, Plan 모드에서 충분히 검토한 후 진행하는 것이 좋다.

고급 기능

파일 참조

@ 키를 사용하여 프로젝트 내 특정 파일을 참조할 수 있다.

1

@packages/functions/src/api/index.ts 에서 인증이 어떻게 처리되는지 설명해줘

이를 통해 AI가 특정 파일의 컨텍스트를 이해하고 더 정확한 답변을 제공할 수 있다.

쉘 명령어 실행

!로 시작하는 명령어는 터미널에서 직접 실행된다.

1
2
3

!ls -la
!git status
!npm test

세션 공유

/share 명령어를 사용하여 대화 내용을 팀원과 공유할 수 있다. 생성된 링크를 통해 다른 사람이 대화 내용을 확인할 수 있다.

MCP 서버 지원

Model Context Protocol을 통해 기능을 확장할 수 있다. 커스텀 도구나 데이터 소스를 MCP 서버로 연결하여 OpenCode의 기능을 확장할 수 있다.

커스텀 명령어

자주 사용하는 작업을 단축 명령어로 정의하여 생산성을 높일 수 있다.

CLI 명령어

TUI 외에도 OpenCode는 다양한 CLI 명령어를 제공한다.

비대화식 실행

1

opencode run "프롬프트"

대화식 인터페이스 없이 일회성 작업을 실행할 수 있다.

모델 관리

1
2
3
4
5

# 사용 가능한 모델 조회
opencode models

# 모델 목록 갱신
opencode models --refresh

HTTP 서버 시작

1

opencode serve

HTTP 서버를 시작하여 콜드 부팅을 회피하고 성능을 개선할 수 있다.

커스텀 에이전트 생성

1

opencode agent create

특정 작업에 최적화된 커스텀 에이전트를 생성할 수 있다.

업그레이드

1

opencode upgrade

최신 버전으로 업그레이드한다.

인증 관리

1
2
3
4
5

# 인증 확인
opencode auth list

# LLM 공급자 로그인
opencode auth login

설정 파일

OpenCode는 opencode.json 파일을 통해 설정을 관리한다.

설정 파일 위치

  • 글로벌 설정: ~/.config/opencode/opencode.json
  • 프로젝트별 설정: 프로젝트 루트의 opencode.json

프로젝트별 설정이 글로벌 설정보다 우선순위가 높다.

주요 설정 옵션

1
2
3
4
5
6

{
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": true
}
  • theme: 테마 설정
  • model: 기본 LLM 모델
  • small_model: 작은 작업에 사용할 경량 모델
  • autoupdate: 자동 업데이트 여부

권한 설정

opencode.json 파일에서 파일 수정 및 명령어 실행 권한을 설정할 수 있다.

1
2
3
4
5
6

{
  "permissions": {
    "file_edit": "ask",
    "command_execution": "ask"
  }
}

권한 옵션:

  • allow: 자동 실행 (승인 없이 바로 실행)
  • ask: 매번 승인 요청 (권장)
  • deny: 실행 금지

민감한 작업의 경우 ask로 설정하여 사용자가 직접 승인하도록 하는 것이 안전하다.

개발 워크플로우

OpenCode를 활용한 효율적인 개발 워크플로우는 다음과 같다:

1. 프로젝트 초기화

1
2

opencode
/init
  • AGENTS.md 파일 작성하여 프로젝트 컨텍스트 제공
  • 코딩 패턴, 사용 기술, 아키텍처 등을 명시

2. 작업 계획 (Plan 모드)

  • Tab 키로 Plan 모드 전환
  • 구현하고자 하는 기능을 구체적으로 설명
  • AI가 제안한 계획을 검토하고 피드백
  • 복잡한 작업은 단계별로 나누어 계획

3. 코드 구현 (Build 모드)

  • Tab 키로 Build 모드 전환
  • 계획을 승인하여 실제 구현 시작
  • AI가 자동으로 코드 생성 및 수정
  • 파일 참조(@파일명)를 활용하여 문맥 제공

4. 반복 및 개선

  • 생성된 코드를 검토하고 필요시 추가 지시
  • /undo, /redo를 활용하여 작업 관리
  • 잘못된 부분은 구체적으로 수정 요청

모범 사례

  1. 구체적이고 단계별 프롬프트 작성
    • 모호한 요청보다는 구체적인 단계별 지시가 효과적
    • “로그인 기능 추가” 보다는 “JWT 기반 로그인 API 엔드포인트 생성, 토큰 검증 미들웨어 추가” 처럼 구체적으로 요청
  2. @ 기호로 파일 참조해 문맥 제한
    • 특정 파일의 컨텍스트를 제공하여 더 정확한 결과 도출
    • 불필요한 파일 수정을 방지
  3. 복잡한 작업은 Plan 모드에서 설계 후 Build 모드로 구현
    • 한 번에 너무 많은 작업을 요청하지 않기
    • Plan 모드에서 충분히 검토 후 Build 모드로 전환
  4. API 키는 환경 변수로 관리하여 보안 확보
    • API 키를 코드에 하드코딩하지 않기
    • 환경 변수나 시크릿 관리 도구 활용

이러한 워크플로우를 통해 개발자는 구현의 세부사항보다는 기능의 목적과 설계에 더 집중할 수 있다.

참고 자료

OpenCode에 대한 더 자세한 정보는 아래 링크에서 확인할 수 있다:

OpenCode는 AI 기반 코딩의 접근성을 높여주는 강력한 도구다.

완전 오픈소스이면서 75개 이상의 LLM 공급자를 지원하고, LSP, 멀티 세션, 세션 공유 등 다양한 기능을 제공한다. 특히 Plan 모드와 Build 모드를 분리하여 신중한 계획 수립이 가능하다는 점이 인상적이다.

Claude Pro/Max 구독이 있다면 Anthropic 계정으로 로그인하여 바로 사용할 수 있으며, 무료 오픈소스 LLM을 로컬에서 실행하여 비용 없이 사용하는 것도 가능하다.

AI 코딩 도구를 찾고 있다면, 오픈소스이면서 다양한 옵션을 제공하는 OpenCode를 시도해볼 만하다.

OpenCode
AI Coding CLI LLM