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

OpenCode 는 터미널 (TUI + CLI) 에서 실행할 수 있는 오픈 소스 AI 코딩 에이전트이며, 선택적으로 데스크톱 및 IDE 인터페이스를 제공합니다. 여기는 OpenCode 빠른 시작 가이드입니다: 설치, 검증, 모델/서비스 공급자 연결, 그리고 실제 워크플로우 (CLI + API) 실행 방법을 다룹니다.

버전 참고 사항: OpenCode 는 빠르게 업데이트됩니다. 여기의 “최신” 명령어는 안정적이지만, 출력과 기본값은 변경될 수 있습니다. 항상 공식 CLI 문서와 변경 로그 (아래 링크) 를 교차 확인하세요.

이 기사는 AI 개발 도구: AI 기반 개발을 위한 완전 가이드 의 일부입니다.

OpenCode 란 무엇이며 어디에 위치하는가

OpenCode 는 터미널 중심의 에이전트 코딩을 위해 설계되었으며, 동시에 서비스 공급자/모델에 유연합니다. 실제로는 다음과 같은 워크플로우 레이어입니다:

• opencode 를 실행하면 터미널 UI 를 시작합니다.
• opencode run 을 통해 비대화식 “원샷 (one-shot)“프롬프트를 실행합니다 (스크립트/자동화).
• opencode serve 를 통해 헤드리스 HTTP 서버를 노출하고 (및 opencode web 를 통해 웹 UI 제공).
• 공식 JS/TS SDK @opencode-ai/sdk 를 통해 프로그래밍 방식으로 제어할 수 있습니다.

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

Anthropic 의 터미널 중심 에이전트 (동일한 “HTTP 를 통한 로컬 모델” 스토리, Ollama 또는 llama.cpp, 권한, 가격 정책) 에 대해서는 Claude Code 설치 및 Ollama, llama.cpp 설정, 가격 정책 를 참조하세요.

사전 요구 사항

다음 요소가 필요합니다:

• 현대적인 터미널 에뮬레이터 (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 이 있습니다.

# chocoloatey (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 대신 설정하고 실행하는 데 매우 좋은 경험을 했습니다. llama-server 는 OpenAI 호환 엔드포인트를 노출하므로 동일한 워크플로우로 GGUF 모델을 사용할 수 있습니다. 메모리와 런타임에 대한 세밀한 제어를 선호하거나 (참고로 ollama 는 Go 로 구현됨), Python 이 없는 더 가벼운 스택을 원한다면 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"

워크플로우: 코드 생성 (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 에이전트)

목표: 더 제한적인 에이전트를 사용하여 우발적 편집 없이 리팩토링.

opencode run --agent plan --file ./src/auth.ts \
  "Refactor this file to reduce complexity. Output: (1) a short plan, (2) a unified diff patch, (3) risks/edge-cases to test. Do not run commands."

예상 출력:

• 계획 섹션 + diff --git ... 패치 블록 + 테스트 체크리스트.
• 내용은 다양합니다. diff 가 생성되지 않으면 재프롬프트: “유니디드 diff 만 반환” 또는 “diff --git 형식을 사용”.

워크플로우: 레포 질문하기 (CLI)

목표: 구현 세부 사항 빠르게 찾기.

opencode run --agent explore \
  "In this repository, where is authentication validated for API requests? List likely files and explain the flow. If uncertain, say what you checked."

예상 출력:

• 파일 경로 맵 + 흐름 설명.
• 출력은 레포 크기와 모델/공급자 컨텍스트 도구에 따라 다릅니다.

워크플로우: 영속 서버로 반복 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                       # 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) 를 사용합니다. 많은 바로가기가 “리더 + 키” 형태입니다.

한 페이지 인쇄용 OpenCode 치트시트 표

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

Oh My Opencode — 다중 에이전트 오케스트레이션으로 OpenCode 확장

OpenCode 가 실행되면 자연스러운 다음 단계는 Oh My Opencode 입니다. 이는 OpenCode 를 다중 에이전트 하네스에 감싸는 커뮤니티 플러그인입니다. 주요 개념: 세션에서 ultrawork (또는 ulw) 를 입력하면 오케스트레이터 (Sisyphus) 가 제어권을 잡고, 각 모델 계열에 조정된 프롬프트로 병렬로 실행하는 전문가 에이전트로 하위 작업을 위임합니다.

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

• Oh My Opencode 빠른 시작
  bunx oh-my-opencode install 로 설치, 공급자 구성, 10 분 미만의 첫 ultrawork 작업 실행.

• 전문 에이전트 심층 분석
  Sisyphus, Hephaestus, Oracle, Prometheus, Librarian 등 모든 11 개 에이전트 설명, 모델 라우팅, 폴백 체인, 자체 호스팅 모델을 위한 실용적 가이드.

• Oh My Opencode 경험: 솔직한 결과 및 청구 위험
  실제 벤치마크, $350 Gemini 무한 루프 사고, 그리고 OMO 가 오버헤드를 정당화하는 시점에 대한 명확한 결론.

출처 (공식 우선)

공식:

• OpenCode 문서 (소개, CLI, 설정, 서버, SDK): https://opencode.ai/docs/
• OpenCode 변경 로그: https://opencode.ai/changelog
• 공식 GitHub 레포: https://github.com/anomalyco/opencode
• 릴리스: https://github.com/anomalyco/opencode/releases

권위 있는 통합 참조:

• GitHub 변경 로그 (Copilot 이 OpenCode 지원): https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode/

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

• DataCamp: OpenCode vs Claude Code (2026): https://www.datacamp.com/blog/opencode-vs-claude-code
• Builder.io: OpenCode vs Claude Code (2026): https://www.builder.io/blog/opencode-vs-claude-code
• freeCodeCamp: OpenCode 를 사용하여 AI 를 터미널에 통합하기: https://www.freecodecamp.org/news/integrate-ai-into-your-terminal-using-opencode/