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는 터미널 우선(AI) 에이전틱 코딩을 위해 설계되어 있으며, 동시에 프로바이더/모델 유연성을 유지합니다. 실제로, 이는 다음을 수행할 수 있는 워크플로 레이어입니다:

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

샌드박스 환경에서 다단계 계획을 실행할 수 있는 다른 오픈소스 에이전틱 어시스턴트와 비교하고 싶다면, OpenHands CLI 퀵스타트를 확인하시기 바랍니다.

동일한 “HTTP를 통한 로컬 모델” 스토리(Ollama 또는 llama.cpp, 권한, 가격)를 가진 Anthropic의 터미널 우선 에이전트에 대해선 Ollama, llama.cpp, 가격을 위한 Claude Code 설치 및 설정를 참고하시기 바랍니다.

같은 터미널 에이전트 아이디어의 고의로 최소화된 접근 방식 — 4개의 기본 도구, 내장 샌드박스 없음, 그 외 모든 것을 확장 플러그인으로 구현 — 에 대해서는 Pi Coding Agent 리뷰를 확인하십시오.

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를 해당 Ollama로 지정합니다. 저는 최근 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 잡을 위한 무단(unattended) 운영에 지향된 더 완전한 권한 정책에 대해서는 OpenCode CLI 실무 가이드를 참고하십시오.

세션 간 프로젝트 메모리는 별도의 설치입니다. OpenCode, Cursor 및 기타 코딩 에이전트를 위한 Hindsight Memory는 사용자 레벨 ~/.config/opencode/opencode.json에 플러그인을 추가하며, 위 프로젝트 opencode.jsonc와 다른 파일입니다.

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

매일 사용할 명령어

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)를 사용합니다. 많은 단축키는 “리더 + 키”입니다.

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 http://host:port/doc의 OpenAPI 스펙
서버에 실행 첨부 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의 제3자 Claude 구독 접근 차단 정책의 영향을 받은 최초의 도구 중 하나였습니다 — 2026년 1월, 동일한 제한이 OpenClaw에 도달하기 한 달 전에 이루어진 조치입니다. OpenClaw의 부상과 몰락 타임라인는 이 두 사건과 구독 컴퓨팅 위에 구축된 에이전트 도구에 대한 더 넓은 패턴을 문서화합니다.

출처 (공식 우선)

공식:

권위 있는 통합 참고 자료:

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

구독하기

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