OpenCode: 오픈소스 AI 코딩 에이전트

AI 코딩 도구가 개발자의 일상에 깊숙이 자리 잡은 지금, 많은 분들이 Claude Code, GitHub Copilot, Cursor 같은 도구들을 사용하고 계실 겁니다. 그런데 이런 도구들은 대부분 유료이고 소스 코드도 공개되어 있지 않죠.

그래서 오늘은 코드가 투명하게 공개되어 있고 다양한 모델 제공자를 지원하는 오픈소스 AI 코딩 에이전트, OpenCode를 소개해 드리겠습니다.

OpenCode란?

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

OpenCode의 핵심 특징을 살펴볼까요?

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

CLI 설치

OpenCode를 설치하는 방법은 여러 가지가 있습니다. 가장 간단한 방법은 설치 스크립트를 사용하는 것입니다.

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

npm을 선호하신다면 아래 명령어를 사용하세요.

npm install -g opencode-ai

macOS나 Linux에서는 Homebrew로도 설치할 수 있습니다.

brew install opencode

Windows 사용자라면 Chocolatey나 Scoop을 활용할 수 있습니다.

# Chocolatey
choco install opencode

# Scoop
scoop bucket add extras
scoop install extras/opencode

LLM 제공자 선택

설치가 완료되면 LLM 제공자를 설정해야 합니다. OpenCode를 처음 사용하신다면 OpenCode Zen을 추천드립니다. OpenCode 팀이 코딩 에이전트에 최적화된 모델들을 직접 테스트하고 벤치마킹해서 제공하는 유료 서비스입니다. OpenCode는 75개 이상의 LLM 제공자를 지원하는데, 모델마다 코딩 성능이 천차만별이거든요. Zen을 사용하면 어떤 모델이 좋은지 고민할 필요 없이, 여러 LLM 제공자의 API 키를 각각 발급받을 필요 없이 Zen 하나로 바로 시작할 수 있습니다.

터미널에서 opencode를 실행한 후 /connect 명령어를 입력하면 제공자 선택 화면이 나타납니다.

/connect

Popular 섹션에서 다음과 같은 제공자를 선택할 수 있습니다:

• OpenCode Zen (Recommended): OpenCode 팀이 추천하는 큐레이션 모델
• Anthropic: Claude Max 구독 또는 API 키 사용
• GitHub Copilot: 기존 Copilot 구독 활용
• OpenAI: GPT 모델 사용
• Google: Gemini 모델 사용
• OpenRouter: 다양한 모델을 하나의 API로

Zen을 선택하면 웹 브라우저에서 로그인하고 API 키를 발급받을 수 있습니다. 이미 Claude Max나 다른 AI 서비스를 구독하고 계신다면, 해당 제공자를 선택해서 기존 구독을 활용할 수도 있습니다.

프로젝트 초기화

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

cd /path/to/your/project
opencode

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

/init

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

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

기본 사용법

OpenCode의 기본적인 사용법을 알아봅시다.

프롬프트를 작성할 때 @ 키를 누르면 파일 이름 일부만 입력해도 프로젝트 내 파일을 찾을 수 있습니다. 이렇게 찾은 파일을 프롬프트에 포함시키면 OpenCode가 해당 파일의 내용을 참고해서 답변해줍니다.

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

OpenCode에는 Plan 모드와 Build 모드가 있는데요, Tab 키로 두 모드를 전환할 수 있습니다. Plan 모드에서는 변경사항을 직접 적용하지 않고 구현 계획만 제안하고, Build 모드에서는 실제로 코드를 수정합니다. 복잡한 기능을 추가할 때는 먼저 Plan 모드에서 계획을 검토한 후 Build 모드로 전환해서 구현하는 것을 권장합니다.

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

/undo

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

유용한 기능

OpenCode에는 생산성을 높여주는 다양한 기능들이 있습니다.

!로 시작하면 쉘 명령어를 바로 실행할 수 있습니다. 명령어의 출력 결과가 대화에 추가되기 때문에, LLM이 이를 참고해서 답변할 수 있습니다.

!ls -la

/models 명령어로 사용 가능한 모델 목록을 확인하고 전환할 수 있습니다. 작업 특성에 따라 더 빠른 모델이나 더 똑똑한 모델을 선택할 수 있죠.

/models

/sessions 명령어로 이전 세션 목록을 확인하고 이어서 작업할 수 있습니다. 어제 진행하던 작업을 오늘 다시 시작하고 싶을 때 유용합니다.

/sessions

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

/compact

/export 명령어는 현재 대화를 마크다운 파일로 내보내줍니다. 나중에 참고하거나 문서화할 때 유용합니다.

권한 설정

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

{
  "$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: 실행 금지

"ask"로 설정된 작업을 LLM이 시도하면 “Accept”, “Accept Always”, “Deny” 세 가지 옵션이 표시됩니다. “Accept Always”를 선택하면 현재 세션 동안 같은 종류의 명령어가 자동으로 허용됩니다.

전역 설정은 ~/.config/opencode/config.json 또는 ~/.config/opencode/config.jsonc에 저장할 수 있습니다.

세션 공유

OpenCode의 강력한 기능 중 하나는 대화 내용을 공유할 수 있다는 점입니다.

/share

이 명령어를 실행하면 현재 대화의 공유 링크가 클립보드에 복사됩니다. 팀원에게 문제 상황을 설명하거나, 버그를 디버깅할 때 유용하게 활용할 수 있습니다.

예시 대화 보기를 통해 실제 공유된 세션이 어떻게 보이는지 확인해보세요.

사용자화

OpenCode는 다양한 커스터마이징 옵션을 제공합니다.

• 테마 설정: 원하는 색상 테마를 선택할 수 있습니다
• 키바인드 변경: 자주 사용하는 단축키를 커스텀할 수 있습니다
• 코드 포매터 설정: Prettier, ESLint 등과 연동할 수 있습니다
• 커스텀 명령어: 자주 사용하는 작업을 명령어로 만들 수 있습니다

자세한 설정 방법은 공식 문서를 참고하세요.

마치며

OpenCode는 무료로 사용할 수 있는 강력한 오픈소스 AI 코딩 에이전트입니다. 오픈소스이기 때문에 데이터가 어떻게 처리되는지 직접 코드로 확인할 수 있어서, 개인정보 보호에 민감한 환경에서도 안심하고 사용할 수 있습니다.

Claude Code나 Cursor 같은 상용 도구를 사용하기 부담스러우셨다면, OpenCode를 한번 시도해보시는 것은 어떨까요? 오픈소스이기 때문에 원하는 대로 커스터마이징하거나 기여할 수도 있습니다.

더 자세한 정보는 아래 링크에서 확인하실 수 있습니다.

• OpenCode 공식 사이트
• GitHub 저장소
• 공식 문서
• OpenCode Zen