OpenCode 사용법: 설치부터 첫 버그 수정과 비용 확인까지

잘 알고 있는 버그 하나와 이미 보유한 모델 계정으로 시작하세요. 실제 수정 사항과 비용을 검토한 뒤에 코딩 툴 구독을 하나 더 추가할 가치가 있는지 판단하면 됩니다.

AI 코딩 에이전트 OpenCode는 어떤 작업을 하나요?

OpenCode는 터미널 인터페이스에서 프로젝트를 읽고, 파일을 수정하고, 명령을 실행합니다. 터미널이 작업대라면 모델은 여기에 연결하는 엔진입니다. 엔진을 바꾸면 추론 능력과 속도, 가격이 달라집니다. 작업 대상은 계속 같은 저장소입니다. OpenCode 개요, Ollama 연동

모델 제공업체는 모델을 공급하는 서비스입니다. API 키는 프로그램이 해당 서비스를 이용하고 연결된 결제 계정으로 비용을 청구할 수 있게 하는 인증 정보입니다. 로컬 모델은 자신의 컴퓨터에 있는 추론 서버를 통해 실행합니다. 이 선택들은 어떤 에이전트 인터페이스를 쓸지와 별도로 결정해야 합니다.

제공업체와 모델의 호환성도 실제 작업으로 확인해야 합니다. 툴 호출은 파일 읽기나 명령 실행 같은 동작을 요청하는 기능입니다. OpenCode는 툴 호출과 코드 생성을 모두 잘 처리하는 모델이 비교적 적다고 설명합니다. 대규모 리팩터링을 맡기기 전에 작은 작업으로 모델을 평가하세요. 모델 선택 가이드

OpenCode 설치 후 프로젝트 실행하기

공식 문서에 따라 설치한 뒤, 작업할 저장소 안에서 실행합니다. Node.js와 npm이 설치되어 있다면 문서에 안내된 패키지 설치 명령을 사용할 수 있습니다.

npm install -g opencode-ai
cd /path/to/project
opencode

프로젝트 경로는 자신의 경로로 바꾸세요. OpenCode 문서에는 curl -fsSL https://opencode.ai/install | bash 방식도 안내되어 있으며, 권장 Homebrew 탭 명령은 brew install anomalyco/tap/opencode입니다. 설치 방식은 하나를 선택하면 됩니다. Windows에서는 Linux 툴을 실행할 수 있는 Windows 환경인 WSL을 권장하며, npm, Chocolatey, Scoop 설치 방법도 제공합니다. 공식 설치 및 첫 실행 안내

OpenCode를 실행하면 터미널 안에 텍스트 사용자 인터페이스인 TUI가 열립니다. /connect처럼 /로 시작하는 명령은 이 인터페이스 안에서 입력합니다. opencode stats처럼 opencode로 시작하는 명령은 셸에서 실행합니다.

Git 저장소를 사용하고 새 브랜치에서 시작하세요. Git이 변경 사항을 기록하므로 커밋하기 전에 추가되거나 삭제된 줄을 보여 주는 diff를 확인할 수 있습니다.

이미 결제 중인 모델 계정 연결하기

/connect를 실행해 제공업체를 선택하고 문서에 안내된 인증 절차를 완료합니다. 이어서 /models를 실행해 모델을 선택하세요. 주요 제공업체는 미리 설정되어 있지만, 사용자 지정 엔드포인트나 로컬 서버는 추가 설정이 필요할 수 있습니다. 모델 선택 방법

이 표는 OpenCode의 공개 제공업체 페이지에 설명된 연결 경로를 정리한 것입니다. 특정 유료 계정에서 어떤 기능이나 모델을 이용할 수 있는지 보장하는 내용은 아닙니다. 제공업체별 연결 안내

채팅 서비스 구독에 API 사용량이 자동으로 포함되는 것은 아닙니다. Anthropic은 Claude Pro에 Claude Console API 사용이 포함되지 않는다고 안내합니다. OpenCode의 Anthropic 항목 역시 Claude Pro/Max 인증 플러그인 사용을 경고합니다. 이 경로에서는 Anthropic API 키를 사용하거나, 구독을 활용하려면 Claude Code를 사용하세요. OpenAI도 API 토큰 요금과 구독 사용을 구분합니다. Claude Pro 결제 안내, OpenCode의 Anthropic 관련 경고, OpenAI 구독 및 API 요금

Ollama를 사용한다면 Ollama와 OpenCode를 설치한 뒤 ollama launch opencode를 실행하고 로컬 모델을 선택합니다. 세션을 열지 않고 설정만 하려면 ollama launch opencode --config를 사용할 수 있습니다. 실행 도구에는 로컬 모델과 클라우드 모델이 모두 표시되므로 의도에 맞게 선택하세요. Ollama의 OpenCode 설정 안내

로컬 연결을 수동으로 설정할 경우, OpenCode의 제공업체 예제는 @ai-sdk/openai-compatible, 로컬 주소 http://localhost:11434/v1, 그리고 서버에서 제공하는 모델과 일치하는 모델 ID를 사용합니다. LM Studio 전용 제공업체 예제도 있습니다. 목록에 없는 OpenAI 호환 서비스는 /connect → Other에서 연결하고, opencode.json에 일치하는 제공업체 ID와 주소, 모델 설정을 넣습니다. 로컬 및 사용자 지정 제공업체 설정

OpenCode 사용법: 실제 버그 하나로 시작하기

에이전트를 실행하기 전에 올바른 동작을 설명할 수 있는 버그를 선택하세요. 전체 애플리케이션을 다시 설계해 달라는 요청보다는 빈 이메일 주소를 허용하는 회원가입 폼이 첫 작업으로 적합합니다.

먼저 프로젝트를 초기화합니다. /init을 실행하세요. 이후 에이전트 세션에 적용할 지침을 담은 Markdown 파일인 AGENTS.md를 생성하거나 갱신합니다. 계속 진행하기 전에 파일을 읽고 명령과 전제를 바로잡으세요. 프로젝트 초기화

다음으로 계획을 요청합니다. Tab을 눌러 Plan을 선택하세요. @로 저장소의 실제 구현 파일과 테스트 파일을 참조합니다. 빈 이메일 버그라면 다음과 같이 요청할 수 있습니다.

이는 작업 요청의 예시이며, 테스트를 완료했다는 보고가 아닙니다. 자신의 프로젝트에 있는 실제 버그와 파일로 바꿔 사용하세요. Plan은 권한 설정으로 파일 수정과 셸 명령을 제한합니다. 격리된 실행 환경을 제공하는 것은 아닙니다. 에이전트와 Plan 동작, 파일 참조 방법

이어서 합의한 범위를 구현합니다. Tab으로 Build로 전환하고 버그를 재현하는 회귀 테스트를 추가한 뒤 최소한의 수정으로 해결하도록 요청하세요. 수정 전 동작에서는 테스트가 실패하고 수정 후에는 통과하는지 보여 달라고 한 다음, 관련된 기존 검사도 실행하게 합니다. Build는 툴이 활성화된 기본 에이전트입니다. Build 에이전트

마지막으로 결과를 직접 검토합니다. diff를 읽고, 테스트의 검증 조건이 의도한 동작과 맞는지 확인하며, 작업과 무관한 변경이 없는지 살펴보세요. 잘못된 동작을 검증하는 테스트는 통과해도 큰 의미가 없습니다. 실제로 실행한 명령과 해결하지 못한 실패를 에이전트가 보고하도록 요청하세요.

수정이 의도에서 벗어나면 /undo로 마지막 메시지와 그에 따른 변경을 되돌릴 수 있습니다. /redo는 되돌린 메시지를 복원합니다. 두 명령 모두 Git을 사용합니다. 되돌리기 및 복원

AGENTS.md와 규칙을 실무에 맞게 작성하기

유능한 개발자가 이 저장소에서 작업할 때 필요한 지침을 작성하세요. 실제로 확인할 수 있을 만큼 구체적이어야 합니다.

• 실제 설치, 빌드, 린트, 테스트 명령과, 순서가 중요할 경우 실행 순서.
• 애플리케이션 코드, 공유 패키지, 자동 생성 파일의 위치.
• 따라야 할 규칙과 그 규칙을 보여 주는 기존 모듈.
• 관련 검사와 변경된 동작의 요약을 포함한 완료 기준.

프로젝트 지침 파일을 커밋해 팀이 함께 사용하도록 합니다. 개인 규칙은 ~/.config/opencode/AGENTS.md에 둡니다. 해당 OpenCode 규칙 파일이 없으면 OpenCode는 CLAUDE.md를 대체 파일로 사용할 수 있습니다. 규칙 및 파일 위치

opencode.json은 설정 파일입니다. instructions 배열로 기존 지침을 불러올 수 있으므로 기여 가이드 내용을 AGENTS.md에 복사할 필요가 없습니다. 다음 예제는 파일 수정과 셸 명령 실행 전에 승인을 요청하도록 설정합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md"],
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

프로젝트에 실제로 존재하는 지침 파일 이름을 사용하고, 기존 설정이 있다면 여기에 병합하세요. AGENTS.md 안에 다른 파일 이름만 적는다고 그 파일의 내용이 자동으로 불러와지지는 않습니다. 해당 파일을 로드하려면 instructions를 사용합니다. 사용자 지정 지침

규칙은 원하는 동작을 설명하고, 권한은 툴의 작업을 실행할 수 있는지 제어합니다. 대부분의 권한은 처음에 allow로 설정되어 있으므로 승인 요청을 받고 싶다면 권한 설정을 의도에 맞게 선택하세요. 권한 설정

반복되는 필요가 생기면 플러그인 추가하기

플러그인은 툴 실행이나 세션 유휴 상태 전환 같은 이벤트를 통해 OpenCode를 확장하는 JavaScript 또는 TypeScript 코드입니다. 이를 이용해 로컬 완료 알림이나 저장소에 맞춘 작업 흐름을 만들 수 있습니다. 플러그인 훅과 예제

프로젝트 하나에 적용할 로컬 플러그인은 .opencode/plugins/에, 모든 프로젝트에 적용할 플러그인은 ~/.config/opencode/plugins/에 둡니다. OpenCode는 시작할 때 이 파일들을 불러옵니다. npm에 배포된 패키지는 opencode.json의 plugin 배열에 추가합니다. 문서에는 opencode-wakatime 같은 이름이 예시로 나옵니다. 패키지와 의존성은 시작 시 Bun으로 자동 설치됩니다. 개발 환경에 실행 가능한 코드를 추가하기 전에 플러그인의 소스와 유지 관리 상태를 검토하세요. 플러그인 로드 방법

기본 제공 작업 흐름부터 사용하세요. 없애고 싶은 반복 작업이 명확해졌을 때 플러그인을 추가하면 됩니다. 플러그인 수가 많아지면 이점을 얻기도 전에 설정과 디버깅 작업이 늘어날 수 있습니다.

OpenCode와 Zen 비용은 어떻게 계산하나요?

에이전트의 작업 흐름과 모델 사용료를 구분하세요. 지원되는 기존 구독을 연결하면 해당 계정의 이용 권한을 사용합니다. API 키를 사용하면 제공업체가 사용량을 기준으로 요금을 부과합니다. 로컬 추론에서는 컴퓨터의 처리 용량과 운영 비용을 고려해야 합니다. Zen은 모델 이용 권한을 구매하는 별도의 선택 사항입니다. 모델 제공업체 선택

OpenCode Zen은 사용량 기반 모델 서비스입니다. 공개 페이지에 안내된 구매 금액은 $20 잔액에 카드 처리 수수료 $1.23을 더한 $21.23이며, 모델 사용에 쓸 수 있는 잔액은 $20입니다. 요청에는 마진을 붙이지 않으며, 월간 지출 한도를 설정할 수 있고, 잔액이 $5에 도달하면 $20가 자동 충전된다고 안내합니다. 이는 잔액과 결제 조건이며 월 구독료가 아닙니다. 충전하기 전에 현재 조건을 확인하세요. Zen 공개 요금 페이지

연결하려면 /connect를 실행해 OpenCode Zen을 선택합니다. 계정과 결제 설정을 완료해 API 키를 발급받은 뒤 OpenCode에 붙여 넣고 /models를 사용하세요. 다른 제공업체로 이미 필요한 작업을 할 수 있다면 Zen을 선택할 필요는 없습니다. Zen 연결 안내

Anthropic API 요금으로 계산한 세션 비용 예시

Anthropic의 직접 API로 Claude Sonnet 4.6을 사용하는 세션 비용은 공개된 표준 요금인 입력 토큰 백만 개당 $3, 출력 토큰 백만 개당 $15로 계산할 수 있습니다. 토큰은 모델이 처리하거나 생성하는 텍스트의 작은 단위입니다. 세션 전체의 모든 요청을 합쳐 캐시되지 않은 입력 토큰 200,000개와 출력 토큰 20,000개를 사용한다고 가정하겠습니다. Anthropic 모델 및 툴 요금

이는 계산 예시입니다. OpenCode 세션을 실제로 측정한 결과도, 버그 수정 한 건의 가격을 보장하는 수치도 아닙니다. 표준 직접 API 요금을 적용하고, 캐시와 추가 서비스 수수료가 없다고 가정합니다. 지침, 반복해서 전달되는 대화 맥락, 툴 결과를 포함해 요청에 들어가는 모든 내용을 계산해야 합니다. 캐시 읽기와 쓰기에는 다른 요금이 적용되며, 서비스와 모델을 바꾸면 비용도 달라집니다. 이 예시는 Zen 요금을 계산한 것이 아닙니다.

가정한 사용량으로 스무 세션을 실행하면 총 $18, 서른 세션이면 총 $27입니다. 비교 기준으로 Claude Pro의 미국 공개 가격은 월 $20이며, 사용량 제한이 있는 Claude Code를 포함합니다. 이 계산은 사용량에 따라 달라지는 API 예산이 고정된 사용자당 요금을 넘어설 수 있는 지점을 보여 줍니다. 결과물이나 제공 사용량이 같다는 뜻은 아니며, 자신의 작업에서 어느 쪽이 더 저렴한지도 이 수치만으로 판단할 수 없습니다. Claude Pro 가격과 API 구분

셸에서 opencode stats를 실행하면 사용량과 비용 통계를 볼 수 있습니다. 최근 하루만 보려면 opencode stats --days 1을 사용합니다. 개별 세션은 opencode export로 선택해 데이터를 JSON으로 내보낼 수 있습니다. 실제로 요금을 청구하는 서비스의 내역과 사용량을 대조하세요. 토큰 기반 추정치는 구독에 포함된 작업 한 건의 가격이 아닙니다. 사용량 확인 명령

실무 효과를 기준으로 고른 여섯 가지 작업

결과가 올바른지 판단할 수 있는 반복 작업부터 시작하세요. 아래는 제안하는 작업 흐름이며, 실제로 관찰한 시간 절감 효과를 주장하는 것은 아닙니다.

제공업체와 작업 흐름을 설정하고 나면 OpenCode의 비대화형 명령 opencode run에 프롬프트를 전달해 스크립트로 작업할 수 있습니다. 작업을 확실하게 검증할 방법이 마련된 뒤 반복 자동화를 적용하세요. CLI run 명령

OpenCode, Claude Code, Pi 중 무엇을 선택하나요?

모델 선택이 작업 흐름의 핵심이고, 프로젝트 규칙과 플러그인 지원에 더해 기본 제공 Plan 및 Build 에이전트를 원한다면 OpenCode를 선택하세요. 제공업체 메뉴를 통해 여러 서비스와 로컬 환경을 공통 인터페이스로 사용할 수 있습니다. 이는 작업 흐름에 따른 추천이며, 더 좋은 코드를 생성한다는 주장은 아닙니다. OpenCode 모델, 에이전트

이미 Claude를 주로 사용하고, 문서에 안내된 터미널 또는 IDE 연동으로 Claude Pro나 Max 구독을 활용하고 싶다면 Claude Code를 선택하세요. Claude와 Claude Code는 해당 요금제의 사용량 제한을 공유합니다. 결제 방식은 2026년 Claude Code 요금 안내에서 비교할 수 있습니다. Claude 구독 연동

확장 기능, 프롬프트 템플릿, 스킬, 테마로 직접 구성할 수 있는 작은 코어를 원한다면 Pi를 선택하세요. Pi도 여러 제공업체를 지원하므로 모델 선택의 유연성만으로 OpenCode를 Pi보다 우선할 이유는 없습니다. Pi의 공개 소개에 따르면 계획 모드는 코어에 기본 탑재되는 대신 확장 기능으로 추가할 수 있습니다. 저는 기본 제공 작업 흐름을 원하는 경우 OpenCode를, 그 흐름을 더 많이 직접 설계하고 싶은 개발자에게는 Pi를 추천합니다. Pi 공개 소개

터미널 에이전트를 더 넓게 비교하려면 Gemini CLI와 Claude Code 비교를 읽어 보세요. 모델 이용 권한, 선호하는 작업 흐름, 결제 경로를 각각 구분해 비교해야 합니다.

OpenCode를 기반으로 만들 수 있는 두 가지 사업

가장 유망한 방향: 저장소에 맞춘 코드 리뷰 워크플로

소규모 개발팀은 반복해서 발생하는 실수를 점검하고 재현 가능한 근거와 함께 우려 사항을 제시하는 리뷰 워크플로에 비용을 지불할 수 있습니다. 수요 신호는 2026년 10월 4일 확인한 DataForSEO 키워드 추정치입니다. 미국에서 “ai code review”의 월간 검색량은 약 1,300회입니다. CodeRabbit의 공개 Essentials 요금은 연간 결제 시 개발자당 월 $24, 월간 결제 시 $30으로, 이 분야에 유료 시장이 있다는 구체적인 비교 기준입니다. DataForSEO 키워드 데이터, CodeRabbit 요금

판매 가능한 최소 버전은 팀의 리뷰 체크리스트와 프로젝트 지침을 불러오고, 전달받은 diff를 검토한 뒤 파일 위치, 검증 단계, 기록된 모델 사용량을 담은 짧은 보고서를 반환하는 형태입니다. 반복해서 실행할 수 있는 로컬 명령부터 만들고, 수작업을 줄이는 곳에만 플러그인 훅을 추가하세요.

관건은 경쟁과 신뢰입니다. 범용 리뷰 래퍼는 기존 툴에 비해 이점이 작습니다. 유망한 틈새시장을 찾으려면 반복적으로 적용해야 하는 도메인 규칙이 있어야 하고, 제안이 리뷰어의 수고를 줄인다는 근거가 필요합니다. 검색량은 코드 리뷰 분야에 대한 관심을 보여 줄 뿐, OpenCode 기반 제품의 수요를 입증하지는 않습니다. 여기서 이 기회가 가장 유망한 이유는 리뷰가 반복되는 작업이고, 실제 diff를 기준으로 유용성을 판단할 수 있기 때문입니다.

에이전시를 위한 검증된 OpenCode 온보딩 패키지

에이전시는 고객사 저장소마다 정상 작동하는 제공업체 연결, 정확한 AGENTS.md, 최소한의 설정, 검토를 마친 첫 작업을 제공하는 설정 서비스를 구매할 수 있습니다. 같은 DataForSEO 확인 결과, 미국에서 “open source ai coding assistant”의 월간 검색량은 약 1,600회로 이 분야에 대한 관심을 보여 줍니다. DataForSEO 키워드 데이터

MVP는 설정 체크리스트와 저장소별 설정을 묶고, 성공적으로 실행된 검증 명령과 명확한 결제 경로를 결과물로 제공하는 형태입니다. 또 하나의 범용 코딩 에이전트 인터페이스를 만들려고 하지는 마세요. 무료 문서만으로도 설치 방법을 알 수 있다는 점이 걸림돌이며, 검색 관심이 지불 의사를 입증하지도 않습니다. 에이전시가 가치를 인정하는 경우에만 고객사별 설정과 지속적으로 관리하는 인수인계 자료에 비용을 청구하세요.

여전히 사람이 판단해야 하는 부분

모델이 비즈니스 요구사항을 제대로 이해했는지는 OpenCode가 대신 판단해 주지 않습니다. 테스트, 코드 리뷰, 배포 판단은 여전히 사용자의 몫입니다. 제공업체를 바꿀 때도 결과물의 품질과 실제 비용을 다시 확인해야 합니다.

로컬 추론은 호스팅 모델 사용료 대신 하드웨어 용량과 설정 작업이 필요합니다. 로컬 에이전트 인터페이스라도 클라우드 제공업체에 연결하면 모델 요청은 해당 제공업체로 전송됩니다. 프롬프트를 입력하는 위치와 추론이 실행되는 위치는 별도로 결정하세요.

수정 방법을 이미 알고 있는 아주 작은 변경이라면 설정과 검토에 변경 자체보다 더 많은 주의와 시간이 들 수 있습니다. 요구사항이 모호한 프로젝트에서는 에이전트에게 구현을 요청하기 전에 인수 기준부터 정의하세요. 가치 있는 결과는 정확하게 수정하고 검토까지 마친 변경 사항입니다.

월요일에 바로 해 볼 일: 재현 가능한 버그 하나를 고르고, 새 브랜치를 만들고, 제공업체 하나를 연결한 뒤 읽기, 계획, 수정, 테스트, 검토의 한 주기를 끝내세요. 사용한 모델, 통과한 검사, 세션 비용이 청구된 방식을 기록합니다. 이 기록이 다음 툴 선택을 위한 근거가 됩니다.

팀의 저장소에 맞춘 코딩 또는 리뷰 워크플로를 구축하고 싶다면 AI 에이전트 개발이 다음 단계입니다.