터미널에서 쓰는 AI 코딩 에이전트, OpenCode 설치부터 활용까지

 

터미널에서 쓰는 AI 코딩 에이전트, OpenCode 설치부터 활용까지 (한 번에 정리)

요즘 AI 코딩 도구는 대부분 에디터 확장이나 웹 기반이 많죠. 그런데 “터미널에서 바로” 코딩을 돕는 에이전트를 찾는 분들도 많습니다.
OpenCode는 그런 니즈에 맞춘 오픈소스 AI 코딩 에이전트로, 터미널(TUI/CLI) 중심 사용을 기반으로 프로젝트 이해, 코드 수정, 기능 추가, 자동화까지 연결할 수 있는 것이 특징이에요.

이번 글에서는 설치 → 인증(모델 연결) → 프로젝트 초기화 → TUI 사용법 → CLI 자동화 → 설정 파일(opencode.json) 운영까지 실무 관점으로 쭉 정리해봅니다.

---

1) OpenCode가 뭐가 좋은가?

OpenCode를 한 줄로 말하면 **“터미널에서 바로 실행되는 AI 코딩 파트너”**입니다.

제가 느낀 장점은 이런 쪽이에요.

• 코드 생성/수정 작업을 터미널 흐름 그대로 이어갈 수 있음
• 자연어로 코드베이스를 물어보고, 특정 파일을 콕 집어 분석시키는 방식이 편함
• 기능 추가를 “계획 → 구현” 흐름으로 분리해서 실수 줄이기 좋음
• OpenAI/Anthropic/Google 등 여러 공급자 모델을 골라 쓸 수 있는 구조

---

2) 시작 전 준비 체크리스트

설치 자체는 어렵지 않지만, 아래는 미리 준비해두면 시행착오가 확 줄어요.

• Node.js: 보통 18 이상 권장(패키지 매니저 설치 방식 이용 시)
• 터미널 환경: TUI를 쓸 거면 최신 터미널 앱이 유리(색상/입력/스크롤)
• 모델 API 키: OpenAI/Anthropic 등 사용할 공급자 키 준비
  • 키는 “구성 파일에 하드코딩”보다 환경변수/키 파일 참조가 안전합니다.

---

3) 설치 방법 (가장 흔한 3가지)

여기서는 많이 쓰는 방식 위주로 정리할게요. (OS별로 선택)

A. 설치 스크립트 방식(간단/빠름)

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

B. Node 패키지 매니저로 전역 설치

npm install -g opencode-ai
# 또는 pnpm / yarn / bun 등 사용 가능

C. Homebrew(macOS/Linux)

brew install opencode

설치 후에는 버전이 찍히면 성공입니다.

opencode --version

---

4) 처음 실행 & 모델(공급자) 연결하기

OpenCode는 “그냥 실행”하면 TUI로 들어갑니다.

cd /path/to/your/project
opencode

처음엔 **모델 연결(인증)**이 필요해요.
TUI 안에서 보통 “연결” 커맨드를 실행하는 흐름이 가장 편합니다.

• TUI에서 명령 입력(슬래시 명령 팔레트):
  • /connect
  • 공급자 선택(OpenAI/Anthropic 등)
  • 안내에 따라 인증/키 입력

CLI로 처리하고 싶으면 아래처럼 로그인 흐름을 타도 됩니다.

opencode auth login
opencode auth list   # 또는 opencode auth ls

---

5) 프로젝트 컨텍스트 세팅 (중요)

OpenCode를 “대화형 챗봇”이 아니라 “프로젝트 이해하는 에이전트”로 쓰려면
프로젝트 초기화가 꽤 중요합니다.

TUI에서:

• /init

이 과정을 거치면 프로젝트 루트에 AGENTS.md 같은 컨텍스트 파일이 생성될 수 있는데(프로젝트 구조/패턴/규칙 등),
팀으로 쓸 거면 Git에 함께 커밋해두는 편이 일관성이 좋아요.

---

6) TUI 기본 사용법 (터미널에서 쓰는 핵심)

TUI는 “질문”만 하는 게 아니라, 파일 탐색/계획/수정/되돌리기까지 한 흐름으로 돌아갑니다.

자주 쓰는 조작

• 스크롤: 마우스 휠 / 방향키
• 명령 팔레트: / 입력 후 커맨드
• 파일 참조: @ 입력 후 파일명 검색(퍼지 검색 느낌)
• 종료: Ctrl + C 또는 /exit

파일 지정해서 질문하기

예: 특정 파일을 콕 찍어 설명을 시킬 수 있어요.

• How is authentication handled in @packages/functions/src/api/index.ts

(이 방식이 “프로젝트 전체를 막연히 읽어라”보다 정확도가 높습니다.)

---

7) 기능 추가할 때: “Plan → Build” 흐름 추천

제가 가장 유용하다고 느낀 건, 기능 추가를 두 단계로 나누는 방식이에요.

1) Plan(계획) 모드

• 요구사항을 자연어로 상세히 말하고
• 나온 계획을 검토/수정

2) Build(구현) 모드

• 계획이 괜찮으면 구현 진행
• 파일 생성/수정이 발생하니 변경점은 꼭 리뷰

이 흐름을 쓰면 “AI가 바로 고쳐서 프로젝트 난장판 되는 상황”이 줄어듭니다.

---

8) 실수했을 때 되돌리기 (이게 은근 편함)

• 최근 변경 취소:

/undo

• 취소했던 작업 다시 실행:

/redo

변경을 여러 번 실행하는 작업에서 특히 유용합니다.

---

9) CLI 모드로 자동화하기 (스크립트/CI에 활용)

TUI 말고도, 명령 한 줄로 실행하는 방식이 있습니다.

바로 질문 실행

opencode run "Explain how closures work in JavaScript"

모델 목록/갱신

opencode models
opencode models --refresh
opencode models --verbose

서버(헤드리스)로 띄워서 빠르게 쓰기

자주 호출하는 환경이면 서버를 띄우는 방식도 가능합니다.

opencode serve
# 다른 터미널에서 attach 방식으로 run
opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

---

10) 설정 파일(opencode.json) 운영 팁

OpenCode는 설정 파일을 통해 “기본 모델, 테마, 권한, 커스텀 커맨드”까지 꽤 폭넓게 조정할 수 있습니다.

구성 파일 위치(운영 방식)

• 글로벌 설정: ~/.config/opencode/opencode.json
• 프로젝트 설정: 프로젝트 루트의 opencode.json

팀 프로젝트라면, 프로젝트 설정은 저장소에 커밋하고,
API 키 같은 민감정보는 환경변수/별도 파일로 빼는 것을 추천합니다.

API 키는 환경변수 참조 권장

(예: OPENAI/ANTHROPIC 키를 환경변수로 관리)

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

자주 쓰는 작업을 커맨드로 단축

예를 들어 테스트 실행을 커맨드로 만들어두면 편합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run full test suite and summarize failures with fixes.",
      "description": "Run tests and analyze failures",
      "agent": "build"
    }
  }
}

TUI에서 /test처럼 호출 가능.

권한(편집/명령 실행) 안전장치

AI가 임의로 파일을 바꾸거나 bash를 막 치는 걸 막고 싶으면:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

---

11) 실무에서 추천하는 사용 루틴

제가 추천하는 “덜 헤매는” 루틴은 이렇습니다.

1. 처음엔 /init으로 프로젝트 컨텍스트를 세팅
2. 질문할 땐 @파일로 범위를 좁혀 정확도 높이기
3. 기능 추가는 Plan → Build로 진행
4. 변경점은 커밋 단위를 작게(Undo/Redo 활용)
5. API 키는 커밋 금지(환경변수/키 파일 참조)

---

마무리

OpenCode는 “AI를 어디에 붙이느냐”보다, 개발 흐름 안에서 얼마나 자연스럽게 쓰느냐가 포인트라고 느꼈습니다.
터미널 기반 작업이 많은 분, 서버/WSL/리눅스 환경에서 개발하는 분, 또는 자동화(CI/스크립트)에 관심 있는 분이라면 한 번쯤 세팅해볼 만해요.

원하시면, (1) Windows(WSL) 기준 설치 가이드, (2) 한국진로적성센터 업무에 맞춘 커스텀 커맨드(opencode.json) 템플릿, (3) Terminal Bench SFT 작업용 “규칙 파일/에이전트 프롬프트” 세팅 예시까지 블로그 후속 글 형태로도 만들어드릴게요.