OpenCode: 설치, 모델 및 첫 실행

OpenCode는 터미널용 오픈 소스 AI 코딩 에이전트입니다. 도구 자체는 무료(MIT 라이선스)이며, Claude와 GPT부터 Ollama를 통한 로컬 모델까지 어떤 모델이든 연결할 수 있습니다. 프로젝트 저장소는 이미 GitHub에서 별 20만 개를 넘었습니다. “어떤 모델이든 쓸 수 있는 무료 Claude Code”라는 문구는 솔깃하지만, 정확히 짚고 넘어갈 필요가 있습니다. 도구는 무료이고, 사용 조건은 선택한 모델에 따라 달라집니다.

아래에는 공식 문서를 바탕으로 한 모든 내용이 담겨 있습니다. 도구가 무엇인지, macOS, Linux 또는 Windows에 설치하는 방법, 모델을 연결하는 방법, 첫 실행 때 할 일을 설명합니다. 비용에 관한 별도 섹션도 있습니다. 여기서 “무료”는 도구에만 해당하기 때문입니다. 모델은 유료이며, 이것이 가장 흔한 혼란의 원인입니다.

Ailoot를 활용하는 실용적인 정보는 문서에서 확인할 수 있습니다.

OpenCode란 무엇인가요? 쉽게 설명하면#

간단히 말해 OpenCode는 Claude Code와 같은 일을 합니다. 일반 언어로 작업을 입력하면 프로젝트에서 그 작업을 수행합니다. 두 가지 차이점이 있습니다. 코드가 완전히 공개되어 있어 읽고 검사할 수 있습니다. 그리고 도구가 특정 모델 provider 하나에 종속되지 않습니다. Anthropic과 OpenAI부터 사용자 하드웨어에서 실행되는 로컬 모델까지 75개 이상의 provider와 함께 작동합니다.

이 프로젝트는 Anomaly 팀이 개발합니다. 저장소는 2025년 4월 30일에 만들어졌으며, 2026년 10월 4일 기준 별 21만 1천 개 이상과 fork 2만 8천 개를 기록했습니다(GitHub API 요청으로 확인). 사용 언어는 TypeScript입니다. 문서가 계속 업데이트되므로 아래 안내는 최신 버전을 기준으로 합니다.

이름을 혼동하지 마세요. 현재 계열의 npm 패키지 이름은 opencode-ai, 저장소는 anomalyco/opencode, 터미널 명령은 간단히 opencode입니다. 오래된 글에는 sst/opencode라는 주소가 나올 수 있습니다. 조직 이름이 바뀌었고, 이전 링크는 이제 새 주소로 리디렉션됩니다.

2026년 10월 4일 업데이트: 팀이 도구의 다음 주요 세대인 OpenCode 2.0을 출시했습니다. 아래 설치 및 모델 연결 안내는 현재 1.x 계열을 기준으로 합니다(curl -fsSL https://opencode.ai/install | bash 명령으로 설치하며, 2026년 9월 30일 기준 현재 버전은 1.18.34입니다). 이 버전은 계속 적극적으로 지원되며 opencode.ai/docs의 공식 문서에서 설치하는 버전입니다. 두 번째 버전에서 정확히 무엇이 바뀌었고 언제 전환하면 되는지는 아래 별도 섹션에서 다룹니다.

OpenCode는 Claude Code 및 Codex와 어떻게 다른가요?#

Claude 구독이 이미 있다면 Claude Code를 주요 도구로 계속 사용하는 것이 좋습니다. 이에 대해서는 자세한 설치 안내를 참고하세요. OpenCode는 세 가지 경우에 유용합니다. ChatGPT Plus 또는 GitHub Copilot 구독으로 작업하고 싶거나, API 요금 없이 로컬 모델을 실행하고 싶거나, 여러 모델을 위한 단일 인터페이스를 원할 때입니다. Codex에 관한 리뷰 및 설치 안내도 있습니다.

아직 도구를 선택하는 중이라면 먼저 이 개요를 살펴보세요. 2026년에 사람들은 무엇으로 코딩하나요. 이미 OpenCode를 설치했고 ACP를 통해 Devin Desktop의 다른 에이전트와 연결해야 한다면 해당 설정 안내를 참고하세요.

OpenCode 2.0에서 무엇이 바뀌었나요?#

두 번째 버전은 curl -fsSL https://opencode.ai/v2/install | bash 명령으로 설치합니다. 공식 마이그레이션 안내(opencode.ai/v2/docs/migrate-v1)에 따르면 두 버전은 같은 opencode 명령을 사용하며, 이제 기본적으로 나란히 설치되지 않습니다. v2 설치 프로그램이 v1 바이너리를 대체하고, 패키지 관리자를 통해 v2를 설치하기 전에 먼저 v1을 제거하라고 문서에서 명시적으로 안내합니다. 하지만 구성은 같은 파일인 ~/.config/opencode/와 <project>/.opencode/에서 읽으므로 설정, 에이전트, MCP 서버는 다시 작성하지 않아도 이전됩니다. 세 가지는 다시 작성해야 합니다. 새 API를 사용하는 플러그인, 프로토콜이 변경된 서버 API 통합, 여러 tui.json 파일 대신 이제 하나의 공유 cli.json 파일을 사용하는 터미널 설정입니다.

v2의 가장 눈에 띄는 새 기능은 두 가지입니다. 첫째, 사용량 추적, 예산, 모든 팀원을 위한 공유 정책을 갖춘 유료 팀 서비스 Console이 도입되었습니다. 둘째, 팀이 마침내 Go 구독 가격을 발표했습니다. Go는 월 $10, 더 높은 한도를 제공하는 Go Plus는 월 $40입니다(opencode.ai/go 페이지, 2026년 10월 4일 확인). 이전 문서에는 금액 없이 “저렴한 구독”이라고만 적혀 있었습니다.

처음 사용하는 사람이고 에이전트만 설치하려면 아래 안내를 따르세요. 공식 문서 자체가 권장하는 현재 첫 번째 버전을 다룹니다. 새 플러그인 기능이나 팀 Console이 필요하면 v2를 고려하되, 기존 플러그인 일부를 새 API에 맞게 다시 작성해야 할 수 있습니다. 터미널이 필요 없는 오픈 소스 데스크톱 앱에 더 관심이 있다면, 자체 인터페이스를 갖춘 유사 에이전트인 ZCode 리뷰를 참고하세요.

설치 전에 무엇이 필요한가요?#

터미널에 대해 조금 더 설명하겠습니다. 설치가 계획대로 진행되지 않을 수 있는 유일한 부분이기 때문입니다. OpenCode는 터미널 안에 패널과 강조 표시가 있는 전체 인터페이스를 렌더링하므로 문서에서 최신 에뮬레이터를 요구합니다. 실행 후 인터페이스가 제대로 표시되지 않으면 먼저 안내된 네 가지 중 하나를 설치하세요. 모든 시스템에서 작동하는 WezTerm, Alacritty, Ghostty 또는 Kitty입니다. Windows에서는 주로 WSL을 사용하며, 아래에 별도 섹션이 있습니다.

두 번째는 모델입니다. OpenCode는 연결한 모델을 통해 작동하며, 도구 자체로는 요청을 처리하지 않습니다. 네 가지 옵션이 있습니다. 구독(ChatGPT Plus, GitHub Copilot, GitLab Duo), provider의 API 키, 팀 자체의 집계 서비스 OpenCode Zen, 또는 Ollama를 통한 로컬 모델입니다. 모델 연결 섹션에서 네 가지 옵션을 모두 다룹니다.

프로젝트 설명이 없으면 에이전트는 빌드 명령, 파일 구조, 사용 중인 규칙을 추측해야 합니다. 여기서 “환각”이 발생합니다. OpenCode는 이를 위해 AGENTS.md 파일을 사용합니다. 같은 방식이 Claude Code 및 다른 모든 에이전트에도 적용되며, 지침 파일 이름만 달라집니다.

macOS와 Linux에 OpenCode를 설치하려면 어떻게 하나요?#

권장 방법은 공식 설치 프로그램을 사용하는 것입니다.

1. 설치 프로그램 실행

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

   스크립트가 시스템을 감지하고 OpenCode를 다운로드합니다. 설치 후 명령을 찾을 수 없다면 터미널을 닫았다가 다시 여세요. 새 세션에서 경로를 인식합니다.

2. 설치가 제대로 되었는지 확인

   opencode --version
   

   명령이 버전 번호를 반환하면 설치가 성공한 것입니다. “command not found”라는 응답이 나오면 첫 단계로 돌아가세요. 새 터미널 세션을 시작하거나 PATH를 직접 수정하면 됩니다.

패키지를 직접 관리하고 싶다면 다음 옵션을 사용할 수 있습니다.

brew install anomalyco/tap/opencode

npm install -g opencode-ai

Homebrew 명령이 anomalyco/tap/으로 시작하는 이유는 문서에서 자체 tap을 권장하기 때문입니다. Homebrew 팀은 brew install opencode용 formula를 덜 자주 업데이트합니다. 같은 패키지 이름 opencode-ai는 bun, pnpm, yarn에서도 사용할 수 있습니다(bun install -g opencode-ai, yarn global add opencode-ai). Arch Linux에서는 안정 저장소에서 sudo pacman -S opencode를 사용하거나 AUR에서 최신 버전을 받으려면 paru -S opencode-bin을 사용하세요.

opencode upgrade로 OpenCode를 업데이트할 수 있습니다. 자동 업데이트가 활성화되어 있으면 실행할 때 자체적으로 업데이트도 다운로드합니다. 업데이트 후에는 익숙한 opencode --version 명령으로 버전을 확인하세요. 제거 기능도 내장되어 있습니다.

opencode uninstall

명령은 삭제할 항목을 정확히 보여주고 확인을 요청합니다. 원한다면 --keep-config와 --keep-data 플래그를 사용해 구성과 세션 데이터를 보존할 수 있습니다.

Windows에 OpenCode를 설치하려면 어떻게 하나요?#

개발자들이 직접 권장하는 첫 번째 옵션은 WSL입니다. 관리자 권한으로 실행한 PowerShell에서 명령 하나로 설치하세요.

wsl --install

재부팅한 뒤 시작 메뉴에서 Ubuntu를 열고 그 안에서 익숙한 명령을 실행합니다.

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

Windows 드라이브의 파일은 WSL에서 /mnt/를 통해 사용할 수 있습니다. C: 드라이브는 /mnt/c/, D: 드라이브는 /mnt/d/에 있습니다. 따라서 C:\Users\Name\project의 프로젝트는 다음처럼 열 수 있습니다.

cd /mnt/c/Users/Name/project
opencode

두 번째 옵션은 WSL을 건너뛰고 Windows 패키지 관리자를 사용하는 것입니다. PowerShell에서 실행합니다.

choco install opencode

scoop install opencode

세 번째 옵션은 데스크톱 앱과 웹 버전입니다. 앱은 일반 프로그램처럼 설치되고 터미널 없이 창에서 인터페이스를 표시합니다. 웹 버전은 opencode web 명령으로 시작합니다. 브라우저에서 OpenCode가 열리며, 파일 접근 문제를 피하기 위해 WSL에서 실행하라고 문서에서 권장합니다. 문서에는 덜 일반적인 옵션인 mise, Docker, GitHub 릴리스 페이지의 사전 빌드 바이너리도 나와 있습니다. Windows에서 bun을 통한 설치는 아직 진행 중이므로 bun을 주 패키지 관리자로 사용한다면 npm 옵션을 이용하세요.

OpenCode에 모델을 연결하려면 어떻게 하나요?#

OpenCode는 AI SDK와 Models.dev를 통해 75개 이상의 provider와 로컬 모델을 지원합니다. 대부분은 인터페이스 안에서 /connect 명령으로 연결합니다. 로컬 모델은 구성에서 서버 주소도 지정합니다. 결제 방법과 컴퓨터 요구 사항은 옵션마다 다릅니다.

문서는 초보자에게 OpenCode Zen으로 시작하라고 권합니다. 팀은 에이전트로서 특히 잘 작동하는 모델을 선정하고 자체 작업에서 provider와의 조합을 테스트했습니다.

연결 방법은 다음과 같습니다. /connect를 입력하고 OpenCode Zen을 선택한 다음, opencode.ai/auth에서 로그인하고 결제 정보를 추가한 뒤 키를 받아 붙여 넣습니다. 그러면 /models에 권장 모델 목록이 표시됩니다. 2026년 10월 4일 기준 목록에는 예를 들어 GPT 6.1 Sol, GPT 6 Astra, Claude Opus 5.5, Claude Sonnet 5, GLM 5.3, Kimi K2.5가 포함되어 있습니다. 문서는 목록이 완전하지 않고 새로운 모델이 매주 나오기 때문에 빠르게 오래된 정보가 된다고 솔직하게 경고합니다.

구독도 같은 /connect 명령으로 연결합니다. 목록에서 ChatGPT Plus 또는 GitHub Copilot을 선택하고 계정에 로그인하면 됩니다. 추가 설정은 필요하지 않습니다.

Anthropic을 선택하면 /connect에 두 가지 옵션이 나타납니다. API 키를 직접 입력하거나 Claude Pro/Max를 선택하고 브라우저로 인증할 수 있습니다. 하지만 Anthropic은 Claude Pro/Max 구독 사용을 위한 타사 플러그인을 금지하며, 이런 종류의 내장 플러그인은 버전 1.3.0부터 OpenCode에서 제거되었습니다. “Claude 구독으로 OpenCode 사용”에 관한 오래된 글을 보게 된다면 공식 인증이 아니라 제거된 플러그인을 말하는 것입니다. ChatGPT Plus, GitHub Copilot, GitLab Duo(실험적이라고 표시됨), Atomic Chat 구독은 추가 설정 없이 작동합니다.

OpenCode는 /connect에서 입력한 키를 ~/.local/share/opencode/auth.json 파일에 저장합니다. 매번 모델을 선택하고 싶지 않다면 프로젝트 루트의 opencode.json 구성 파일에 기본 모델을 설정하세요.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5"
}

형식은 provider/model이며, 두 식별자는 모두 /models 출력에 표시됩니다.

Ollama를 통해 로컬 모델을 연결하려면 어떻게 하나요?#

이 옵션은 API 요금이 전혀 들지 않습니다. 모델이 컴퓨터에서 실행됩니다. 무료 모델 전반을 비교해 고르고 있다면, 어떤 모델이 에이전트로 그럭저럭 잘 작동하고 어떤 모델은 겉보기만 그런지 다룬 별도 리뷰가 있습니다. OpenCode에서 사용하려면 공식 사이트에서 Ollama를 설치하고 모델을 다운로드하세요.

ollama pull qwen3-coder

문서에서 알아둘 만한 점은 Ollama가 OpenCode용으로 자동 구성될 수 있다는 것입니다. 별도의 통합 안내가 있습니다. 모든 설정을 직접 하려면 로컬 Ollama 서버 주소와 함께 provider를 opencode.json에 추가하세요.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

그러면 인터페이스의 /models 목록에 로컬 모델이 표시됩니다. 모델을 선택하고 작업을 시작하세요. 문서의 실용적인 주의 사항은 다음과 같습니다. 에이전트가 도구를 호출하지 않게 되면(파일 수정 또는 명령 실행), Ollama 설정에서 num_ctx를 늘리세요. 16k–32k 값부터 시작하면 됩니다. 로컬 모델은 특히 에이전트 작업에서 클라우드 모델보다 성능이 낮으며, 작은 컨텍스트는 이를 더 악화시킵니다. 로컬 버전이 충분하지 않다면 키를 이용해 클라우드의 Qwen을 연결할 수 있습니다. 키를 얻는 방법은 Qwen Code API 키 받기 안내에 나와 있습니다.

OpenCode와 사용 비용은 얼마나 드나요?#

여기서 비용은 모두 모델에 관한 것이며, 네 가지 시나리오가 있습니다. API 키나 Zen을 사용하면 실제 사용량에 따라 결제하며, 금액은 에이전트가 얼마나 작업하는지에 달려 있습니다. Go는 OpenCode 팀이 제공하는 오픈 모델용 구독 플랜입니다. Go는 월 $10, 더 높은 한도의 Go Plus는 월 $40입니다(opencode.ai/go 페이지에서 2026년 10월 4일 확인). 한도는 모델에 따라 다릅니다. 예를 들어 Go에서 Kimi K3는 5시간당 약 110회(월 440회), 더 가벼운 DeepSeek V4.1 Flash는 5시간당 약 26,000회 요청할 수 있습니다. 한도를 넘어 특정 모델을 이용하려면 별도 가격이 있다고 문서에 나와 있습니다(Kimi K3 월 $15, Go Plus 월 $60). 연결할 때 구독 페이지에서 모델 및 한도 전체 목록을 확인하세요. ChatGPT Plus 또는 Copilot을 사용하면 요청 비용은 이미 지불한 구독에 포함됩니다. 다만 구독마다 사용 강도에 관한 자체 한도가 있다는 점을 기억하세요. 마지막으로 Ollama를 통한 로컬 모델 요청은 무료지만, 빠르게 실행하려면 충분히 강력한 컴퓨터가 필요합니다.

첫 실행 때 무엇을 해야 하나요?#

프로젝트 폴더 안에서 처음 실행합니다.

cd path/to/project
opencode

입력 필드가 있는 인터페이스가 열립니다. 먼저 /init 명령을 사용하세요. 에이전트가 저장소의 중요한 파일을 살펴보고, 필요한 경우 몇 가지 질문을 한 다음 AGENTS.md 파일을 작성합니다. 이 파일에는 프로젝트 구조, 빌드 및 테스트 명령, 사용 중인 규칙이 설명됩니다. 문서는 이 파일을 git에 커밋하도록 권장합니다. 그러면 OpenCode가 이를 영구적인 프로젝트 지침으로 사용합니다. 역할 면에서 AGENTS.md는 OpenCode 생태계에서 CLAUDE.md와 직접 대응합니다.

둘째, Plan 모드를 사용하세요. Tab 키로 두 주요 에이전트 사이를 전환합니다. Build는 파일과 명령에 대한 전체 권한으로 작업하며, Plan은 분석과 계획을 위한 모드입니다. 기본적으로 Plan 모드에서는 파일 수정과 bash 명령을 실행할 때 승인이 필요합니다. 새 작업은 계획부터 시작하라고 문서에서 권장합니다. 에이전트가 하려는 일을 읽고 표현을 다듬은 다음에 Tab 키로 Build로 돌아가세요.

문서에는 다음과 같은 조언이 있습니다.

작업을 구체적으로 설명하고 더 많은 맥락을 제공할수록 다시 작업할 일이 줄어듭니다. @를 사용해 요청에 파일을 추가하세요. 이름을 입력하기 시작하면 인터페이스가 퍼지 검색으로 파일을 찾아줍니다. 이미지를 터미널로 직접 끌어다 놓을 수 있고, !로 시작하는 메시지는 셸 명령으로 실행되어 그 출력이 에이전트의 맥락에 추가됩니다. 작업을 잘못 입력했거나 에이전트가 엉뚱한 일을 했다면 /undo가 변경 사항을 되돌리며, 연달아 여러 번 실행할 수 있습니다. 다시 마음을 바꿨나요? /redo로 취소한 변경을 복원할 수 있습니다. /share는 팀과 대화를 공유하는 링크를 만듭니다. 이 명령을 사용하지 않으면 대화는 어디에도 게시되지 않습니다.

OpenCode로 무엇을 더 할 수 있나요?#

사용자 지정 명령. 반복되는 요청은 무엇이든 명령으로 만들 수 있습니다. .opencode/commands/에 Markdown 파일을 넣고 frontmatter에 description, agent, model을 설정한 다음 아래에 프롬프트 템플릿을 작성하세요. 그런 다음 /로 명령을 호출합니다. 게시 전 프로젝트 검사, 최근 오류 검토, 마이그레이션 생성 등 정기적으로 요청하는 작업이면 무엇이든 가능합니다.

서브에이전트. Build와 Plan 외에 세 가지가 더 있습니다. 여러 단계 작업을 위한 General(작업 목록을 제외한 모든 도구에 접근), 편집 권한 없이 코드를 빠르게 읽는 Explore, 외부 라이브러리를 조사하는 Scout입니다. 메시지에서 @로 이들을 언급해 호출하세요.

MCP 서버. opencode.json 구성의 mcp 섹션을 통해 외부 도구를 연결합니다. 로컬 및 원격 서버를 모두 지원합니다. 각 MCP 서버는 도구를 맥락에 추가하며, GitHub처럼 도구가 많은 서버는 맥락을 매우 빠르게 소모할 수 있습니다. 필요한 것만 선택적으로 연결하세요. MCP 개념에 대해 바로 쓸 수 있는 설정이 담긴 안내가 있습니다. Claude Code를 대상으로 작성되었지만 프로토콜은 공유됩니다.

웹 버전 및 서버. opencode web은 브라우저에서 인터페이스를 엽니다. 다른 컴퓨터에서 접속하려면 opencode serve --hostname 0.0.0.0 --port 4096을 사용하세요. 네트워크에 접근할 수 있는 경우 OPENCODE_SERVER_PASSWORD 변수로 반드시 비밀번호를 설정하세요. 비밀번호가 없으면 서버가 보호되지 않습니다.

설치에 문제가 생기면 어떻게 해야 하나요?#

설치 후 “opencode: command not found”가 표시됨. 터미널이 새 경로를 아직 인식하지 못합니다. 우선 터미널을 닫았다가 다시 여세요. 그래도 해결되지 않으면 설치 프로그램이 바이너리를 어디에 저장했는지 찾고 해당 폴더를 터미널의 PATH에 추가하세요.

모델이 응답하지 않거나 권한 오류를 표시함. provider가 연결되어 있는지 확인하세요. /connect를 입력해 다시 인증합니다. 키는 ~/.local/share/opencode/auth.json에 저장됩니다. 다른 컴퓨터에서 설치를 옮겼거나 폴더를 지웠다면 이 파일이 없을 수 있습니다. 문서는 ProviderInitError와 AI_APICallError 오류를 별도로 다룹니다. 첫 번째 오류라면 provider를 다시 인증하고, 두 번째라면 ~/.cache/opencode 폴더를 비운 뒤 재시작하세요.

인터페이스가 깨짐: 패널이 어지럽게 배치되거나 기호 대신 읽을 수 없는 문자가 표시됨. 먼저 터미널을 확인하세요. 권장 옵션 중 하나를 설치하고 그 터미널에서 OpenCode를 실행하세요. WezTerm은 세 운영체제에서 모두 작동합니다.

아무것도 도움이 되지 않으면 로그를 확인하세요. macOS와 Linux에서는 ~/.local/share/opencode/log/에 있고, Windows에서는 Win+R을 누르고 %USERPROFILE%\.local\share\opencode\log를 입력합니다. 최근 파일 10개가 보관됩니다. 자세한 로그는 opencode --log-level DEBUG 플래그로 활성화하세요. 이 로그를 가지고 프로젝트의 GitHub 저장소에 버그를 신고할 수 있습니다.

사람들은 OpenCode에 대해 또 무엇을 묻나요?#

Ailoot 열기.