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

OpenCode 설치, 구성 및 사용 방법

Page content

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

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

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

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

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

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

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

opencode with self-hosted qwen3.5 27b LLM

/ai-devtools/ 클러스터를 구축 중이라면, OpenCode 는 자연스럽게 다음과 같은 하위 클러스터로 확장되므로 강력한 후보입니다:

  • CLI 심층 분석
  • 모델/공급자 동작 및 비용 (OpenCode 내 LLM 비교)
  • 설정 및 에이전트
  • 통합 (GitHub/GitLab/Copilot)
  • 치트시트
  • Oh My Opencode — OpenCode 위에 구축된 다중 에이전트 오케스트레이션 레이어

사전 요구 사항

다음 항목이 필요합니다:

  • 현대적인 터미널 에뮬레이터 (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 를 사용하여 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"

워크플로우: 코드 생성 (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 가 생성되지 않으면 재프롬프트하세요: “unified 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

예상 출력 형태:

  • “서버 실행 중…”
  • 버전 문자열이 포함된 건강 응답
  • 세션 프롬프트 응답 객체 (정확한 구조는 responseStyle 과 SDK 버전에 따라 다름)

복사 가능한 최소 OpenCode 설정

OpenCode 는 JSON 과 JSONC 설정을 지원합니다. 이는 프로젝트 로컬 설정을 위한 합리적인 시작점입니다.

리포지토리 루트에 opencode.jsonc 생성:

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

  // 기본 모델 선택 (공급자/모델). `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/ 페이지에 붙여넣을 수 있습니다.)

작업 명령어 / 단축키 참고 사항
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 "..." 반복적인 코ldb 부팅 방지 유용
기본 인증 활성화 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) 가 제어권을 가져와서 전문 에이전트에 하위 작업을 위임하고, 각 에이전트는 자신의 프롬프트에 최적화된 모델 패밀리를 병렬로 실행합니다.

세 가지 글에서 심층적으로 다룹니다:

출처 (공식 우선)

공식:

권위 있는 통합 참조:

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