OpenCode 설치 및 사용법 완벽 가이드: 무료 오픈소스 AI 코딩 에이전트

작성일자 글쓴이

Claude Code, GitHub Copilot, Cursor… 이런 AI 코딩 도구들을 사용하고 싶지만 비용이 부담되시나요? 🤔 오늘은 완전 무료이면서 소스 코드까지 공개된 오픈소스 AI 코딩 에이전트, OpenCode를 소개해 드리겠습니다!

🚀 OpenCode란 무엇인가요?

OpenCode는 터미널, IDE, 데스크톱 앱에서 사용할 수 있는 오픈소스 AI 코딩 에이전트입니다. Claude Code와 비슷한 컨셉이지만, 완전히 무료이고 소스 코드가 GitHub에 공개되어 있다는 점이 가장 큰 차이점이에요.

65만 명 이상의 개발자가 신뢰하는 이 도구는 Claude, GPT, Gemini 등 다양한 대규모 언어 모델을 지원합니다. 오픈소스이기 때문에 데이터가 어떻게 처리되는지 직접 코드로 확인할 수 있어서, 개인정보 보호에 민감한 환경에서도 안심하고 사용할 수 있어요.

OpenCode의 핵심 특징

  • LSP 지원: LLM을 위한 Language Server를 자동으로 로딩해줍니다
  • 멀티 세션: 같은 프로젝트에서 여러 에이전트를 병렬로 실행할 수 있습니다
  • 세션 공유: 대화 내용을 링크로 공유해서 팀원과 협업하거나 디버깅할 수 있습니다
  • 75+ LLM 제공자: Claude, GPT, Gemini는 물론 로컬 모델까지 지원합니다
  • Claude Pro/Max 연동: 기존 Anthropic 구독을 활용할 수 있습니다

💻 OpenCode 설치 방법

OpenCode를 설치하는 방법은 여러 가지가 있어요. 운영체제에 맞는 방법을 선택하시면 됩니다!

방법 1: 설치 스크립트 사용 (가장 간단!)

터미널에서 아래 명령어 한 줄이면 끝입니다:

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

방법 2: npm으로 설치

Node.js를 사용하신다면 npm으로도 설치할 수 있어요:

npm install -g opencode-ai

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

brew install opencode

방법 4: Windows 사용자

Windows에서는 Chocolatey나 Scoop을 활용할 수 있습니다:

# Chocolatey
choco install opencode

# Scoop
scoop bucket add extras
scoop install extras/opencode

🔧 LLM 제공자 설정하기

설치가 완료되면 LLM 제공자를 설정해야 합니다. 터미널에서 opencode를 실행한 후 /connect 명령어를 입력하세요:

opencode
/connect

그러면 제공자 선택 화면이 나타납니다. 선택 가능한 주요 옵션들:

  • OpenCode Zen (추천): OpenCode 팀이 코딩에 최적화된 모델을 직접 테스트하고 제공하는 유료 서비스
  • Anthropic: Claude Max 구독 또는 API 키 사용
  • GitHub Copilot: 기존 Copilot 구독 활용
  • OpenAI: GPT 모델 사용
  • Google: Gemini 모델 사용 (무료 API 제공!)
  • OpenRouter: 다양한 모델을 하나의 API로

💡 무료로 시작하고 싶다면? Google Gemini API는 무료 티어를 제공하고 있어서 비용 부담 없이 시작할 수 있어요. 또는 Ollama를 사용하면 로컬에서 완전 무료로 AI 모델을 돌릴 수도 있습니다!

📁 프로젝트 초기화

이제 작업할 프로젝트 디렉토리로 이동해서 OpenCode를 시작해봅시다:

cd /path/to/your/project
opencode

프로젝트에서 처음 OpenCode를 사용한다면 /init 명령어로 초기화하는 것을 권장합니다:

/init

이 명령어를 실행하면 OpenCode가 프로젝트 구조를 분석하고 AGENTS.md 파일을 생성합니다. 이 파일은 OpenCode가 프로젝트의 구조와 코딩 패턴을 이해하는 데 도움을 줍니다. Claude Code의 CLAUDE.md와 비슷한 역할을 해요!

💡 Tip: AGENTS.md 파일은 Git에 커밋해서 팀원들과 공유하는 것이 좋습니다!

🎯 기본 사용법

파일 참조하기

프롬프트를 작성할 때 @ 키를 누르면 파일 이름 일부만 입력해도 프로젝트 내 파일을 찾을 수 있습니다:

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

Plan 모드 vs Build 모드

OpenCode에는 두 가지 모드가 있어요. Tab 키로 전환할 수 있습니다:

  • Plan 모드: 변경사항을 직접 적용하지 않고 구현 계획만 제안
  • Build 모드: 실제로 코드를 수정

복잡한 기능을 추가할 때는 먼저 Plan 모드에서 계획을 검토한 후 Build 모드로 전환해서 구현하는 것을 권장합니다!

변경 되돌리기

원하지 않는 변경이 적용되었다면 /undo 명령어로 되돌릴 수 있습니다:

/undo

여러 번 실행해서 여러 변경사항을 되돌릴 수도 있고, /redo로 다시 적용할 수도 있어요. 참고로 /undo와 /redo는 내부적으로 Git을 사용하기 때문에 프로젝트가 Git 저장소여야 합니다.

⚡ 유용한 명령어 모음

쉘 명령어 실행

!로 시작하면 쉘 명령어를 바로 실행할 수 있습니다. 출력 결과가 대화에 추가되어 LLM이 참고할 수 있어요:

!ls -la
!npm run build

모델 전환

/models 명령어로 사용 가능한 모델 목록을 확인하고 전환할 수 있습니다:

/models

세션 관리

/sessions 명령어로 이전 세션 목록을 확인하고 이어서 작업할 수 있습니다:

/sessions

대화 요약

대화가 길어지면 /compact 명령어로 세션을 요약할 수 있습니다. 컨텍스트 윈도우를 절약하면서도 중요한 맥락은 유지됩니다:

/compact

대화 내보내기

/export 명령어는 현재 대화를 마크다운 파일로 내보내줍니다:

/export

세션 공유

/share 명령어로 현재 대화의 공유 링크를 생성할 수 있습니다. 팀원에게 문제 상황을 설명하거나 디버깅할 때 유용해요:

/share

🔐 권한 설정

OpenCode가 파일을 수정하거나 명령어를 실행할 때 매번 승인을 받을지, 자동으로 실행할지 설정할 수 있습니다. 프로젝트 루트에 opencode.json 파일을 만들어서 설정하세요:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": {
      "git push": "ask",
      "git status": "allow",
      "npm run build": "allow",
      "terraform *": "deny"
    }
  }
}

권한 값은 세 가지가 있습니다:

  • allow: 승인 없이 자동 실행
  • ask: 매번 사용자에게 승인 요청
  • deny: 실행 금지

🚀 oh-my-opencode: 더 강력한 확장

OpenCode를 더욱 강력하게 만들어주는 플러그인 oh-my-opencode도 소개해 드릴게요! 12,000개 이상의 GitHub 스타를 기록한 인기 프로젝트입니다.

oh-my-opencode의 특징

  • 7개의 전문 에이전트: Sisyphus 오케스트레이터가 이끄는 전문화된 AI 팀
  • 병렬 작업: 여러 에이전트가 동시에 백그라운드에서 작업
  • 역할별 최적 모델: 각 작업에 가장 적합한 모델이 자동 선택
  • Todo Enforcer: 작업이 완료될 때까지 자동으로 지속

oh-my-opencode 설치

npm install -g oh-my-opencode

설치 후 ultrawork 키워드를 사용하면 Sisyphus 에이전트가 활성화되어 복잡한 작업을 자동으로 처리해줍니다!

📊 OpenCode vs 다른 AI 코딩 도구 비교

도구 가격 오픈소스 모델 선택 로컬 모델
OpenCode 무료 ✅ 75+ ✅
Claude Code $20~$200/월 ❌ Claude만 ❌
GitHub Copilot $10~$19/월 ❌ 제한적 ❌
Cursor $20/월 ❌ 여러 개 ❌

💡 실전 활용 팁

1. 무료로 시작하기

Ollama를 사용하면 API 키 없이 완전 무료로 시작할 수 있어요:

# Ollama 설치 후
ollama pull qwen3
# OpenCode에서 Ollama 연결

2. 컨텍스트 관리

대화가 길어지면 /compact로 요약하고, 새로운 주제는 새 세션으로 시작하세요. 토큰을 절약할 수 있습니다!

3. 팀 협업

AGENTS.md 파일을 Git에 커밋하고, /share로 세션을 공유하면 팀원들과 효과적으로 협업할 수 있어요.

4. 안전한 사용

중요한 명령어(git push, 배포 관련)는 permission을 “ask”로 설정해서 실수를 방지하세요.

🔧 문제 해결

설치가 안 될 때

Node.js 버전이 18 이상인지 확인하세요:

node --version

모델 연결이 안 될 때

API 키가 올바른지 확인하고, /connect로 다시 연결을 시도해보세요.

/undo가 작동하지 않을 때

프로젝트가 Git 저장소인지 확인하세요. git init으로 초기화가 필요할 수 있습니다.

✨ 마무리

OpenCode는 무료로 사용할 수 있는 강력한 오픈소스 AI 코딩 에이전트입니다. Claude Code나 Cursor 같은 상용 도구를 사용하기 부담스러우셨다면, OpenCode를 한번 시도해보시는 것은 어떨까요?

오픈소스이기 때문에 원하는 대로 커스터마이징하거나 직접 기여할 수도 있어요. 75개 이상의 LLM 제공자를 지원하니 원하는 모델을 자유롭게 선택할 수 있고, Ollama를 사용하면 완전 무료로 로컬에서 AI 코딩 어시스턴트를 운영할 수도 있습니다!

더 자세한 정보는 아래 링크에서 확인하세요:

궁금한 점이 있으시면 댓글로 남겨주세요! 즐거운 코딩 되세요! 🚀