OpenCode 설치 가이드: 초급 개발자를 위한 첫 세팅
요즘 AI 개발 도구가 너무 많아서, “뭘 먼저 설치해야 하지?” 하다가 그냥 브라우저에서 챗봇만 쓰고 끝나는 경우 많죠.
특히 터미널 안에서 돌아가는 도구들은 멋있어 보이지만, 설치 과정에서 막힐까 봐 시도조차 안 하게 되기도 합니다.
이 글에서 다루는 도구는 OpenCode라는, 터미널 안에서 돌리는 AI 중심 개발환경입니다.
하나의 창에서 AI coding agent 와 프로젝트 코드를 함께 다루는 느낌이라 끌리지만, 설치 과정을 직접 따라가 보려면 생각보다 준비할 게 조금 있습니다.
또한 이 도구는 단순한 챗봇이 아니라 terminal AI IDE 에 가깝기 때문에, 기초만 잡아두면 이후 워크플로우가 훨씬 매끄러워집니다.
이번 글에서는 “명령어 전체 정리”까지 한 번에 다루기보다는,
macOS 기준으로 어떤 선택지가 있는지, 어떤 순서로 설치·초기화를 진행하면 좋은지를 초급 개발자 눈높이에서 차근차근 정리해 보겠습니다.
1. OpenCode 설치 여정 한눈에 보기
먼저 전체 여정을 한 번에 그려볼게요.
큰 흐름은 보통 이렇게 생각하면 이해가 쉽습니다. (opencode.ai/docs)
- 설치 방식 선택
- 공식 install 스크립트
- Homebrew
- Node.js 기반 글로벌 설치 등
- 처음 한 번만 환경 설정
- 어떤 모델/프로바이더를 쓸지 선택
- API 키 또는 Zen 같은 묶음 서비스 연동
- 프로젝트 폴더로 이동 후 TUI 실행
cd /path/to/projectopencode실행
/init명령으로 프로젝트 초기화- 코드베이스를 분석해서
AGENTS.md생성 - 이후부터는 “말 걸면서 개발”이 가능
- 코드베이스를 분석해서
이 도구는 기본적으로 AI coding agent 를 프로젝트에 붙여서,
“설치 → 설정 → 프로젝트 초기화 → 실제 사용”이라는 4단계의 구조입니다.
이번 글에서는 이 중 1·2·3 단계까지를, 다음 글에서는 실제 사용 패턴을 다루게 됩니다.
2. macOS에서 설치 전에 꼭 확인할 것들
macOS 기준으로 시작한다면, 설치 전 다음 세 가지를 먼저 점검해 두면 좋습니다.
2-1. 터미널 환경
- macOS 기본 터미널을 써도 되지만,
WezTerm, Ghostty, Kitty 같은 최신 터미널 에뮬레이터를 쓰면 체감 경험이 훨씬 좋습니다. - 폰트/색상/창 분할 같은 부분도 자주 만질 예정이라,
평소 쓰기 편한 터미널 하나를 “주력”으로 정해 두면 좋습니다.
2-2. 최소한의 CLI 감각
완전 고수일 필요는 없고, 다음 정도만 익숙하면 충분합니다.
- 디렉터리 이동:
cd - 현재 위치 확인:
pwd - 파일·폴더 목록 보기:
ls - PATH에 프로그램이 잘 들어갔는지 확인:
which opencode
이 정도만 알아도 설치부터 실행까지는 무리 없이 따라갈 수 있습니다.
2-3. AI 서비스 계정
이 도구는 다양한 모델 프로바이더와 연동할 수 있습니다.
- OpenAI, Anthropic, Google, xAI 등 중
“내가 비용을 내고 쓰고 있거나, 앞으로 쓸 가능성이 높은 곳”을 하나 골라 두세요. - 완전 무료만 생각하면 선택지가 조금 줄어들 수 있지만,
그래도 기본적으로는 무료/저렴한 모델도 함께 제공되는 구조입니다.
3. 설치 방법 고르기: 스크립트 vs Homebrew vs 패키지 매니저
설치 방식은 여러 가지가 있습니다. 공식 문서에서는 설치 스크립트가 가장 간단한 방법이라고 안내합니다.
3-1. 설치 스크립트 (가장 빠른 시작)
터미널에 다음 한 줄을 붙여 넣는 방식입니다.
curl -fsSL https://opencode.ai/install | bash- 장점
- macOS, Linux에서 거의 고민 없이 바로 설치 가능
- 버전·의존성 등을 알아서 맞춰 줌
- 단점
- “스크립트 파이프 설치” 방식이 불편한 분도 있을 수 있음
CLI에 익숙한 분들은 이 도구를 terminal AI IDE 처럼 매일 띄워두게 될 텐데,
어떤 설치 방식을 고르든 “내가 가장 편한 방법”을 선택하는 게 중요합니다.
3-2. Homebrew로 설치
Homebrew를 이미 쓰고 있다면, 아래 한 줄이면 끝입니다.
brew install opencode- 장점
- 다른 CLI 도구와 함께 깔끔하게 관리 가능
- 업데이트도
brew upgrade opencode한 번이면 OK
- 단점
- Homebrew를 쓰지 않는 환경(회사 맥 등)에서는 제한될 수 있음
3-3. Node.js 기반 글로벌 설치
Node.js 환경을 많이 쓰는 분이라면, npm이나 pnpm, yarn, bun으로 글로벌 설치도 가능합니다.
예
npm install -g opencode-ai
# 또는
pnpm install -g opencode-ai
# 또는
yarn global add opencode-ai
# 또는
bun install -g opencode-ai- 장점
- Node 생태계에 익숙하다면 친숙한 방식
- 단점
- Node 버전·글로벌 패키지 충돌 등에 민감한 환경이라면 관리 포인트가 늘어남
3-4. Windows 사용자의 경우
이 글은 macOS 중심이지만, 참고로 Windows에서는 Chocolatey, Scoop, npm, Docker, Mise 등 여러 가지 선택지가 있습니다.
“회사 PC + Windows” 조합에서는 보안 정책을 먼저 확인하는 걸 추천드립니다.
4. 첫 실행과 프로젝트 초기화 흐름
설치가 끝났다면, 이제 실제로 실행해 볼 차례입니다.
4-1. 설치 확인
터미널에서 아래를 입력해 봅니다.
opencode --version아래와 같이 버전 문자열이 출력된다면 설치는 성공입니다.
4-2. 프로젝트 폴더로 이동
실제로 사용할 레포(또는 연습용 프로젝트) 위치로 이동합니다.
cd /path/to/your/project여기서부터는 이 폴더가 이 도구와 AI가 함께 작업하는 “무대”가 됩니다.
4-3. TUI 실행
이제 아래 명령으로 TUI(터미널 UI)를 실행합니다.
opencode처음 실행하면,
- 모델/프로바이더 연결
- 기본 테마
- 키 바인딩
등을 간단히 설정하게 될 수 있습니다.
4-4. /init으로 프로젝트 분석시키기
AI에게 현재 프로젝트를 이해시키려면 한 번은 초기화 과정을 거쳐야 합니다.
TUI 안에서 아래 명령을 입력하면 그림과 같이 프로세싱 됩니다.
/init
그러면 이 도구가 프로젝트를 스캔하고,
루트에 AGENTS.md 파일을 만들어 둡니다.
- 이 파일에는
- 프로젝트 구조
- 주요 폴더와 역할
- 앞으로 AI가 참고해야 할 기본 규칙
등이 정리되는 구조를 사용할 수 있습니다.
- Git으로 버전 관리해 두면,
새로 들어온 팀원이나 다른 AI 에이전트가 같은 규칙을 공유하기 쉬워집니다.
5. 자주 나오는 실수 3가지와 해결 팁 5가지
설치와 첫 실행에서 초급 개발자분들이 자주 겪는 패턴을 정리해 볼게요.
실수 1. PATH가 안 잡혀서 command not found
- 현상: 설치는 한 것 같은데
opencode명령이 안 먹힙니다. - 해결:
brew나npm설치 로그에서 PATH 관련 안내가 나왔는지 확인- 터미널을 완전히 껐다가 다시 열어보기
echo $PATH로 경로에 관련 디렉터리가 포함됐는지 확인
실수 2. 프로젝트 폴더가 아닌 곳에서 실행
- 현상: 홈 디렉터리에서 바로 실행해서,
/init이후AGENTS.md가 엉뚱한 위치에 생김. - 해결:
- 항상
cd /path/to/project를 먼저 입력 - “이 도구는 프로젝트 단위로 생각한다”는 개념을 습관화
- 항상
실수 3. 모델/프로바이더 설정에서 멈춤
- 현상: 어떤 모델을 선택해야 할지 몰라서
/connect단계에서 오래 고민하다가 그냥 닫아버림. - 해결:
- 처음엔 무료(깃허브 코파일럿) 또는 저렴한 기본 플랜 하나만 선택
- 나중에 프로젝트가 커질 때 고급/유료 모델을 추가하는 방식으로 점진적으로 확장
추가 팁 2가지
- “내가 자주 쓰는 설치 방법”을 하나 정해 둔다
- 예: “CLI 도구는 웬만하면 다 Homebrew로 설치한다”
- 설치 과정에서 실행한 명령어를 따로 메모해 둔다
- 같은 회사 맥/랩탑에 반복 설치할 때 큰 도움이 됩니다.
6. 다음 글에서 무엇을 다룰까?
여기까지 따라오셨다면,
- 설치 방식의 선택지
- macOS에서의 기본 흐름
- 첫 실행과
/init까지의 개념
을 대략 정리하신 상태일 거예요.
다음 글에서는 OpenCode 를 실제로 손에 익히는 튜토리얼 느낌으로,
- 코드베이스를 설명시키는 방법
- 새로운 기능을 추가하는 요청 패턴
- 리팩터링과 테스트 코드 작성 요청
/undo,/redo,/share같은 명령의 실제 활용 예시
를 하나의 시나리오로 엮어서 보여드릴 예정입니다.
“설치는 해두었는데, 막상 켜 놓고 뭐라고 말해야 할지 모르겠다”는 분께 도움이 될 내용들로 구성할게요.
FAQ
Q1. OpenCode 설치는 꼭 스크립트로 해야 하나요?
A1. 아닙니다. 공식 install 스크립트가 가장 간단하지만, Homebrew나 npm 같은 패키지 매니저를 통해서도 설치할 수 있습니다. 회사 정책이나 개인 취향에 따라 가장 편한 방법을 고르면 됩니다.
Q2. 이 도구는 어떤 AI coding agent 로 봐야 하나요?
A2. 한마디로 말하면 “터미널/IDE 안에서 함께 일하는 AI 동료”에 가깝습니다. 코드 설명, 기능 추가, 리팩터링, 테스트 코드 작성 등 반복적인 작업을 대신해 주지만, 최종 결정과 리뷰는 여전히 개발자인 여러분이 맡는 구조를 상정하고 설계된 도구입니다.
Q3. 이 환경은 terminal AI IDE 처럼 쓸 수 있나요?
A3. 네, 기본적으로 터미널 TUI를 중심으로 동작하지만, VS Code나 Cursor 같은 IDE와도 연동할 수 있어 사실상 terminal AI IDE 느낌으로 사용할 수 있습니다. “에디터는 보기·편집, 이 도구는 AI와의 대화·작업 지시” 역할로 나누면 이해가 쉽습니다.
Q4. 설치 후 바로 회사 프로젝트에 붙여 써도 될까요?
A4. 가능은 하지만, 처음에는 개인 토이 프로젝트나 사이드 프로젝트로 감을 익히는 것을 강력 추천합니다. 어느 정도 대화 패턴과 명령에 익숙해진 뒤, 업무 레포에 적용하는 쪽이 안전합니다.
Q5. 여러 모델 프로바이더를 한 번에 연결해도 되나요?
A5. 네, 여러 AI 서비스의 API 키를 등록해 두고, 상황에 따라 다른 모델을 선택해서 사용할 수 있습니다. 다만 초반에는 한두 개 프로바이더에 집중해 “내 스타일”을 만드는 것이 헷갈리지 않습니다.
Q6. 설치만 해 두고, 아직 본격적으로 쓰지 않아도 괜찮나요?
A6. 물론입니다. 이번 글의 목표는 “설치 장벽”을 넘는 것이고, 실제 활용 패턴은 다음 글에서 단계별로 다룹니다. 우선 설치와 /init까지 마쳐 놓고, 다음 글의 예제를 그대로 따라 해 보시면 훨씬 부담이 줄어듭니다.
정리하기
이번 글에서는 OpenCode 를 macOS 중심으로 설치하고, 첫 실행과 초기화까지 가는 흐름을 큰 그림 위주로 정리해 봤습니다.
터미널과 CLI에 아주 익숙하지 않아도, “설치 방법 선택 → 실행 확인 → 프로젝트 폴더에서 /init”이라는 세 단계만 기억하면 시작선에는 충분히 설 수 있습니다.
오늘 한 번 정리해 보시면 좋을 것들
- 내가 선호하는 설치 방식 정하기
- 스크립트 / Homebrew / Node.js 중 하나를 “기본값”으로 선택
- 실습용 프로젝트 폴더 하나 정해 두기
- 너무 복잡하지 않은 레포가 연습에 좋습니다.
- 다음 글에서 따라 하고 싶은 시나리오 떠올리기
- 예: “테스트 코드 자동 생성”, “기존 코드 리팩터링”, “새 페이지 추가” 등
마지막으로, 이런 질문을 스스로에게 한 번 던져보면 좋겠습니다.
“내가 지금 개발 중인 프로젝트에서, 이 도구에게 가장 먼저 맡기고 싶은 일은 무엇일까?”
댓글로 공유해 주시면, 다음 사용법 글을 구성할 때 예시 시나리오에 반영해 보겠습니다. 🙌
(문제는 실제 사용해 보려고 하니 이게 유료 API가 있어야 가능한 상태인 걸로 확인이 됩니다.ㅜㅜ 다행히도 /connect 명령어 입력후 깃허브 코파일럿을 선택하면 GPT-5 mini를 무료로 사용가능합니다. 26년 1월 6일자 기준으로 또 변동이 있네요. 무료로 사용가능한 모델이 GPT-4o 등 더 확대 되었습니다.)
