OpenCode 설치와 사용: CLI/TUI, 로그인 또는 API 키, 첫 저장소 작업
OpenCode CLI/TUI를 설치하고 키를 연결한 다음, 실제 저장소에서 첫 작업을 끝낸다.
필요한 것은 저장소를 읽고 파일을 고치는 오픈소스 터미널 에이전트다. 다른 브라우저 채팅은 필요 없다.
이 글은 OpenCode 설치와 사용을 공식 절차로 따라간다. CLI/TUI를 설치하고 /connect 또는 opencode auth login으로 로그인하거나 API 키를 붙인 뒤, 실제 저장소에서 첫 작업을 끝낸다. 근거는 opencode.ai/docs의 Intro, Providers, CLI.
누구에게 맞나
OpenCode는 오픈소스 터미널 에이전트다. 인자 없는 opencode는 TUI, CLI도 있다. 데스크톱과 IDE는 문서에 있고 이 글은 터미널만. 첫 실행은 최신 터미널 에뮬레이터와 동작하는 모델 키 하나.
실제 저장소에서 시작
실제로 유지하는 프로젝트로 cd. 세 요점 또는 추가할 테스트 하나. 저장소 전체 재작성은 맡기지 않는다.
키는 인증 파일에
공식 저장 위치는 ~/.local/share/opencode/auth.json. TUI는 /connect, CLI는 opencode auth login. 채팅에 붙이지 않는다.
큰 편집 전에 초기화
/init은 프로젝트를 분석하고 AGENTS.md를 쓴다. 공식은 커밋을 권한다. 작은 변경은 Build. 큰 기능은 먼저 Tab으로 Plan.
설치, 인증, 첫 작업
-
1
CLI를 설치하고 TUI 열기
macOS/Linux/WSL에서
curl -fsSL https://opencode.ai/install | bash,npm install -g opencode-ai, 또는brew install anomalyco/tap/opencode(문서는 anomalyco tap을 더 최신으로 권함). Windows 네이티브는 Chocolatey, Scoop, npm. 전체 호환은 WSL. 확인은opencode --version, 실행은opencode. -
2
로그인 또는 API 키 추가
TUI에서
/connect. 초보자는 OpenCode Zen을 골라 opencode.ai/auth에서 로그인, 결제를 넣고 키를 붙인다. OpenAI, Anthropic 등 다른 제공자도 된다. CLI는opencode auth login. 확인은opencode auth list. 환경 변수나 프로젝트.env도 된다. -
3
저장소에서 첫 작업
프로젝트로
cd한 뒤opencode,/init으로AGENTS.md. 첫 질문 예: “구조를 세 줄로 설명하고 추가할 작은 테스트를 하나”. 작은 편집은 한 줄 주석, 동작은 같게. diff를 읽는다./undo가능. 스크립트는opencode run.
curl -fsSL https://opencode.ai/install | bash
# or: npm install -g opencode-ai
# or: brew install anomalyco/tap/opencode
opencode --version
# Auth (pick one):
# In the TUI: /connect → provider or OpenCode Zen → paste API key
# CLI: opencode auth login
# Check: opencode auth list
# Keys live in ~/.local/share/opencode/auth.json (do not commit)
cd /path/to/your/repo
opencode
# In the TUI: /init → writes AGENTS.md (ok to commit)
# First task: Explain the repo layout in three bullets and name one small test I can add
# Small edit: Add a one-line comment to the main entry file; do not change behavior
# Undo: /undo
# Non-interactive alternative:
# opencode run "Explain README.md in three bullets and suggest one small test"
첫 실행에서 자주 막히는 점
| 방법 | 청구 | 더 맞는 용도 |
|---|---|---|
| 설치 스크립트 / npm / brew | 도구는 오픈소스 | 로컬 첫 CLI 설치 |
| Zen 또는 제공자 API 키 | Zen 청구 또는 각사 Platform | 클라우드 읽기와 편집 |
| 환경 변수 / 프로젝트 .env | 같은 제공자 청구 | CI 또는 auth.json을 피할 때 |
- TUI가 깨지거나 단축키가 죽음
- 문서는 WezTerm, Alacritty, Ghostty, Kitty 같은 최신 에뮬레이터를 요구한다. 기본 터미널 렌더가 나쁘면 먼저 바꾼다.
- auth.json은 비밀번호 수첩
- 기본 경로는
~/.local/share/opencode/auth.json. 공개 저장소에 복사하지 말 것. 키가 Git에 들어갔다면 콘솔에서 교체. - Windows가 불완전함
- 공식은 전체 호환에 WSL. Chocolatey / Scoop / npm은 네이티브 바이너리. Windows 절을 따른다.
공식 알림: API는 공급자 또는 Zen 요금. 싼 모델로 /init과 /undo를 익힌 뒤, 실제로 결제할 모델로 바꾼다.
변경을 사람과 볼 때
한 장이 부족한 경우가 많다. tidemeet에서 짧은 공간을 열거나 공간 만들기. 공유 화이트보드. 다른 입문은 Aider와 Codex CLI.
질문
OpenCode Zen을 꼭 써야 하나?
아니다. Zen은 초보자를 위한 정리 목록. /connect로 다른 제공자, 또는 opencode auth login. Providers 페이지를 따른다.
AGENTS.md를 커밋해야 하나?
공식은 그렇다고 한다. 구조와 습관을 남긴다. 키는 이 파일에 쓰지 않는다.
처음부터 Plan 모드를 써야 하나?
작은 변경은 Build. 큰 기능은 Tab으로 Plan(파일을 쓰지 않음), 합의 후 Build로 돌아온다.
임시 회의 도구와 무슨 관계인가?
제품 연동은 없다. diff만 짧게 이야기하면 임시 회의 도구 비교를 본다.