OpenCode 빠른 시작: 터미널 AI 코딩 에이전트 설치, 설정 및 사용

OpenCode 설치, 설정 및 사용법

Page content

OpenCode는 터미널(TUI + CLI)에서 실행할 수 있는 오픈소스 AI 코딩 에이전트로, 데스크톱 및 IDE 환경도 선택적으로 지원합니다. 이 글은 OpenCode 퀵스타트: 설치, 검증, 모델/프로바이더 연결, 실제 워크플로우(CLI + API) 실행에 대한 안내입니다.

버전 참고: OpenCode는 빠르게 배포됩니다. 여기 소개된 “최신” 명령어는 안정적이지만, 출력과 기본값은 변경될 수 있습니다—항상 공식 CLI 문서와 변경 로그(아래 링크 참조)를 교차 확인하시기 바랍니다.

이 글은 AI 개발 도구: AI 기반 개발 완전 가이드의 일부입니다. 자가 호스팅 어시스턴트인 Nous Hermes를 유지 관리하고 있다면, Hermes Agent CLI 치트시트에서 이 OpenCode 퀵스타트와 함께 hermes 명령어 세트를 확인할 수 있습니다.

OpenCode란 (그리고 어디에 적합한가)

OpenCode는 터미널 우선, 에이전틱 코딩을 위해 설계되었으며, 프로바이더/모델에 유연하게 대응합니다. 실무적으로는 다음과 같은 기능을 수행하는 워크플로우 레이어입니다:

  • opencode 실행 시 터미널 UI 시작
  • opencode run을 통해 비대화형 “원샷” 프롬프트 실행 (스크립트/자동화)
  • opencode serve을 통해 헤드리스 HTTP 서버 노출 (그리고 opencode web을 통한 웹 UI)
  • 공식 JS/TS SDK @opencode-ai/sdk를 통해 프로그래매틱 제어 가능

샌드박스 환경에서 다단계 계획을 실행할 수 있는 또 다른 오픈소스 에이전틱 어시스턴트와 비교하고 싶다면, OpenHands 코딩 어시스턴트 퀵스타트를 참조하세요.

동일한 “HTTP를 통한 로컬 모델” 시나리오(Ollama 또는 llama.cpp, 권한, 가격)를 가진 Anthropic의 터미널 우선 에이전트에 대해선 Ollama, llama.cpp, 가격 설정을 위한 Claude Code 설치 및 구성을 확인하세요.

같은 터미널 에이전트 아이디어에 대한 의도적으로 최소한의 접근 방식 — 기본 도구 4개, 내장 샌드박스 없음, 나머지는 확장 기능으로 — 에 대해선 Pi 코딩 에이전트 리뷰를 참조하세요.

opencode with self-hosted qwen3.5 27b LLM

사전 요구 사항

다음과 같은 것이 필요합니다:

  • 최신 터미널 에뮬레이터 (TUI 경험에 중요합니다).
  • 최소 한 개의 모델/프로바이더에 대한 접근 권한 (프로바이더에 따라 API 키 또는 구독 인증). Ollama이나 llama.cpp와 같은 로컬 옵션은 호환되는 서버를 로컬에서 실행할 때 API 키 없이 작동합니다.

OpenCode 설치 (복사-붙여넣기)

공식 설치 스크립트 (Linux/macOS/WSL):

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

패키지 매니저 옵션 (공식 예시):

# Node.js 전역 설치
npm install -g opencode-ai

# Homebrew (대부분의 최신 릴리스에 대해 OpenCode가 권장)
brew install anomalyco/tap/opencode

# Arch Linux (안정판)
sudo pacman -S opencode

# Arch Linux (AUR에서 최신)
paru -S opencode-bin

Windows 참고사항 (공식 가이드는 최고의 호환성을 위해 WSL을 일반적으로 권장합니다). 대안으로 Scoop/Chocolatey 또는 npm이 있습니다.

# chocolatey (Windows)
choco install opencode

# scoop (Windows)
scoop install opencode

Docker (빠른 시도에 유용):

docker run -it --rm ghcr.io/anomalyco/opencode

설치 확인

opencode --version
opencode --help

예상 출력 형식 (버전에 따라 다름):

# 예시:
# <버전 번호 출력, 예: vX.Y.Z>
# <사용 가능한 명령어/하위 명령어와 함께 도움말 출력>

프로바이더 연결 (두 가지 실무적 경로)

경로 A: TUI /connect (대화형)

OpenCode 시작:

opencode

그런 다음 실행:

/connect

UI 단계를 따라 프로바이더를 선택하고 인증을 수행합니다 (일부 플로우에서는 브라우저/기기 로그인이 열립니다).

경로 B: CLI opencode auth login (프로바이더 키)

OpenCode는 다음을 통해 프로바이더를 구성할 수 있습니다:

opencode auth login

참고사항:

  • 자격 증명은 ~/.local/share/opencode/auth.json에 저장됩니다.
  • OpenCode는 환경 변수나 프로젝트의 .env 파일에서 키를 로드할 수도 있습니다.

로컬 LLM 호스팅 (Ollama, llama.cpp)

OpenCode는 OpenAI 호환 API와 함께 작동합니다. 로컬 개발을 위해 많은 사용자가 Ollama를 실행하고 OpenCode를 해당 서버로 설정합니다. 최근 저는 대신 llama.cpp로 OpenCode를 구성하고 실행하는 데 매우 좋은 경험을 했습니다—llama-server는 OpenAI 호환 엔드포인트를 노출하므로, 동일한 워크플로우로 GGUF 모델을 사용할 수 있습니다. 메모리와 런타임에 대한 세밀한 제어나 Python이 없는 더 가벼운 스택을 선호한다면 (참고: ollama은 Go로 구현됨), llama.cpp을 시도해 볼 가치가 있습니다. 오프로드된 레이어 구성, GGUF 형식 모델의 사용 편의성, 그리고 Qwen3.5와 같은 신모델에 대한 훨씬 더 우수하고 빠른 구현 호환성을 정말로 즐겼습니다. OpenCode 내에서 실제로 코딩 작업 및 구조화된 출력 정확도 측면에서 잘 수행되는 모델이 궁금하다면, OpenCode를 위한 제 손으로 직접 해본 LLM 비교를 확인하세요.

프로젝트를 올바르게 시작하기 (권장된 첫 실행)

저장소에서:

cd /path/to/your/repo
opencode

그런 다음 초기화:

/init

이것은 프로젝트를 분석하고 프로젝트 루트에 AGENTS.md 파일을 생성합니다. OpenCode(및 팀원)가 일관된 프로젝트 컨텍스트를 공유하도록 이 파일을 커밋하는 것이 일반적으로 가치가 있습니다.

핵심 CLI 워크플로우 (복사-붙여넣기 예시)

OpenCode는 비대화형 실행을 지원합니다:

opencode run "Explain how closures work in JavaScript"

명령줄 워크플로우 패턴 — git 출력 파이프, Makefile 및 CI 타깃, 무인 실행을 위한 권한 정책 — 과 예상되는 실패 모드에 대해선 OpenCode CLI 실무 가이드를 참조하세요. 이 가이드는 이 퀵스타트를 반복하지 않고 그 위에 기반을 둡니다.

워크플로우: 코드 생성 (CLI)

목표: 최소한의 컨텍스트로 작고 테스트 가능한 함수 생성.

opencode run "Write a Go function ParsePort(envVar string, defaultPort int) (int, error). It should read the env var, parse an int, validate 1-65535, and return defaultPort if empty. Include 3 table-driven tests."

예상 출력:

  • 설명과 코드 블록 (함수 + 테스트). 정확한 코드는 모델/프로바이더와 프롬프트에 따라 달라집니다.

워크플로우: 파일 안전하게 리팩토링 (CLI + Plan 에이전트)

목표: 더 제한적인 plan 에이전트가 신뢰할 수 있도록 실행되기 전에 확인.

opencode run --agent plan --file ./src/auth.ts \
  "Refactor this file to reduce complexity. Output a short plan only. Do not run commands."

예상 출력: 계획 섹션만 있고, 파일 편집 없음, 명령어 실행 없음.

워크플로우: 저장소 질문 (CLI)

목표: explore 에이전트가 구현 세부 사항을 찾을 수 있는지 확인.

opencode run --agent explore \
  "Where is authentication validated for API requests in this repository?"

예상 출력: 파일 경로와 흐름 설명의 짧은 지도.

이 둘 모두 단일 샷 스모크 테스트입니다. 동일한 작업의 제약된, 프로덕션 버전 — 명시적인 리스크/엣지 케이스 출력, 통합 디프 패치, 권한 인식 탐색 프롬프트, 그리고 모델이 따르지 않을 때 취해야 할 조치 — 에 대해선 OpenCode CLI 실무 가이드의 “최고의 OpenCode CLI 사용 사례” 섹션을 참조하세요.

워크플로우: 영속적 서버로 반복 CLI 실행 속도 향상

스크립팅하거나 여러 opencode run 호출을 실행하는 경우, 헤드리스 서버를 한 번 시작할 수 있습니다:

터미널 1:

opencode serve --port 4096 --hostname 127.0.0.1

터미널 2:

opencode run --attach http://localhost:4096 "Summarize the repo structure and main entrypoints."
opencode run --attach http://localhost:4096 "Now propose 3 high-impact refactors and why."

예상 출력:

  • opencode run과 동일하지만, 일반적으로 반복적인 시작 오버헤드가 적습니다.

프로그래매틱 사용 (공식 JS/TS SDK)

OpenCode는 HTTP 서버(OpenAPI)를 노출하고 타입 안전 JS/TS 클라이언트를 제공합니다.

설치:

npm install @opencode-ai/sdk

예시: 서버 + 클라이언트 시작 후 프롬프트

scripts/opencode-sdk-demo.mjs 생성:

import { createOpencode } from "@opencode-ai/sdk";

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    // 모델 문자열 형식은 provider/model (예시만)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`Server running at: ${opencode.server.url}`);

// 기본 상태/버전 확인
const health = await opencode.client.global.health();
console.log("Healthy:", health.data.healthy, "Version:", health.data.version);

// 세션 생성 및 프롬프트
const session = await opencode.client.session.create({ body: { title: "SDK quickstart demo" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Generate a small README section describing this repo." }],
  },
});

console.log(result.data);

// 완료 시 서버 닫기
opencode.server.close();

실행:

node scripts/opencode-sdk-demo.mjs

예상 출력 형식:

  • “Server running at …”
  • 버전 문자열을 포함한 상태 응답
  • 세션 프롬프트 응답 객체 (정확한 구조는 responseStyle과 SDK 버전에 따라 다름)

복사할 수 있는 최소 OpenCode 설정

OpenCode는 JSON 및 JSONC 설정을 지원합니다. 이것은 프로젝트 로컬 설정에 대해 합리적인 시작점입니다.

저장소 루트에 opencode.jsonc 생성:

{
  "$schema": "https://opencode.ai/config.json",

  // 기본 모델 선택 (provider/model). `opencode models`가 표시하는 것과 일치하도록 유지하세요.
  "model": "provider/model",

  // 선택 사항: 가벼운 작업(제목 등)을 위한 더 저렴한 "작은 모델"
  "small_model": "provider/small-model",

  // 선택 사항: OpenCode 서버 기본값 (serve/web에서 사용)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

  // 선택 사항 안전장치: 편집/명령어 전에 확인 요청
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

무인 opencode run 작업을 대상으로 한 더 완전한 권한 정책에 대해선 OpenCode CLI 실무 가이드를 참조하세요.

짧은 치트시트 (빠른 참조)

매일 사용할 명령어

opencode                       # TUI 시작
opencode run "..."             # 비대화형 실행 (자동화)
opencode run --file path "..." # 프롬프트에 파일 첨부
opencode models --refresh      # 모델 목록 새로고침
opencode auth login            # 프로바이더 자격 증명 구성
opencode serve                 # 헤드리스 HTTP 서버 (OpenAPI)
opencode web                   # 헤드리스 서버 + 웹 UI
opencode session list          # 세션 목록
opencode stats                 # 토큰/비용 통계

암기할 가치가 있는 TUI 명령어

/connect   # 프로바이더 연결
/init      # 저장소 분석, AGENTS.md 생성
/share     # 세션 공유 (활성화된 경우)
/undo      # 변경 사항 되돌리기
/redo      # 변경 사항 다시 실행
/help      # 도움말/단축키

기본 “리더 키” 개념 (TUI)

OpenCode는 터미널 충돌을 피하기 위해 구성 가능한 “리더” 키(일반적으로 ctrl+x)를 사용합니다. 많은 단축키는 “Leader + key"입니다.

1페이지 인쇄용 OpenCode 치트시트 테이블

이 버전은 의도적으로 밀도 높고 “인쇄 친화적"입니다. (나중에 전용 /ai-devtools/opencode/cheatsheet/ 페이지에 붙여넣을 수 있습니다.)

작업 명령어 / 단축키 참고
TUI 시작 opencode 기본 동작은 터미널 UI 시작
원샷 프롬프트 실행 opencode run "..." 스크립팅/자동화를 위한 비대화형 모드
프롬프트에 파일 첨부 opencode run --file path/to/file "..." 여러 파일을 위해 여러 --file 플래그 사용
실행에 사용할 모델 선택 opencode run --model provider/model "..." 모델 문자열은 provider/model
에이전트 선택 opencode run --agent plan "..." Plan은 더 안전한 “변경 없음” 작업(권한 제한)을 위해 설계됨
모델 목록 opencode models [provider] 캐시된 목록 업데이트를 위해 --refresh 사용
프로바이더 자격 증명 구성 opencode auth login 자격 증명을 ~/.local/share/opencode/auth.json에 저장
인증된 프로바이더 목록 opencode auth list / opencode auth ls OpenCode가 보는 것을 확인
헤드리스 서버 시작 opencode serve --port 4096 --hostname 127.0.0.1 OpenAPI 스펙은 http://host:port/doc에 위치
서버에 실행 첨부 opencode run --attach http://localhost:4096 "..." 반복적인 콜드 부트 회피에 도움
기본 인증 활성화 OPENCODE_SERVER_PASSWORD=... opencode serve 사용자 이름은 오버라이드되지 않는 한 opencode가 기본값
웹 UI 모드 opencode web 서버 시작 + 브라우저 열기
세션 내보내기 opencode export [sessionID] 아카이빙 또는 컨텍스트 공유에 유용
세션 가져오기 opencode import session.json 공유 URL에서 가져오기 가능
전역 CLI 플래그 보기 opencode --help / opencode --version 디버깅을 위해 --print-logs + --log-level
TUI 리더 키 개념 기본 리더 키는 보통 ctrl+x tui.json에서 사용자 정의 가능

Oh My Opencode — 멀티 에이전트 오케스트레이션으로 OpenCode를 더 깊이 활용

OpenCode가 실행되면, 자연스러운 다음 단계는 Oh My Opencode입니다 — OpenCode를 멀티 에이전트 하네스로 감싸는 커뮤니티 플러그인입니다. 핵심 아이디어: 세션에서 ultrawork(또는 ulw)를 입력하면 오케스트레이터(Sisyphus)가 인수를 받아, 각자의 프롬프트가 조정된 모델 패밀리에서 병렬로 실행되는 전문가 에이전트들에게 하위 작업을 위임합니다.

세 가지 글이 이를 심층적으로 다룹니다:

OpenCode는 Anthropic의 서드파티 Claude 구독 접근 차단 정책으로 영향을 받은 최초의 도구 중 하나였습니다 — 2026년 1월, 같은 제한이 OpenClaw에 영향을 미치기 한 달 전에 이루어진 조치입니다. OpenClaw의 상승과 붕괴 타임라인은 구독 컴퓨팅을 기반으로 구축된 에이전트 도구에 대해 두 사건과 그들이 대표하는 더 넓은 패턴을 문서화합니다.

출처 (공식 우선)

공식:

권위 있는 통합 참조:

신뢰할 수 있는 비교/튜토리얼:

구독하기

시스템, 인프라, AI 엔지니어링에 관한 새 글을 받아보세요.