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

OpenCode는 데스크톱 및 IDE 인터페이스를 선택적으로 지원하며 터미널(TUI + CLI)에서 실행할 수 있는 오픈 소스 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 코딩 어시스턴트 빠른 시작을 참조하십시오.

동일한 “HTTP를 통한 로컬 모델” 스토리(Ollama 또는 llama.cpp, 권한, 가격 정책)를 가진 Anthropic의 터미널 중심 에이전트에 대해 보려면 Ollama, llama.cpp, 가격 정책용 Claude Code 설치 및 구성을 참조하십시오.

전제 조건

다음 사항이 필요합니다:

• 최신 터미널 에뮬레이터 (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

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

# Example:
# <prints a version number, e.g. vX.Y.Z>
# <prints help with available commands/subcommands>

제공자 연결 (두 가지 실용적인 방법)

경로 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: {
    // Model string format is provider/model (example only)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

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

// Basic health/version check
const health = await opencode.client.global.health();
console.log("Healthy:", health.data.healthy, "Version:", health.data.version);

// Create a session and prompt
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);

// Close server when done
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",

  // Choose a default model (provider/model). Keep this aligned with what `opencode models` shows.
  "model": "provider/model",

  // Optional: a cheaper “small model” for lightweight tasks (titles, etc.)
  "small_model": "provider/small-model",

  // Optional: OpenCode server defaults (used by serve/web)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

  // Optional safety: require confirmation before edits/commands
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

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

매일 사용할 명령어

opencode                       # start TUI
opencode run "..."             # non-interactive run (automation)
opencode run --file path "..." # attach files to prompt
opencode models --refresh      # refresh models list
opencode auth login            # configure provider credentials
opencode serve                 # headless HTTP server (OpenAPI)
opencode web                   # headless server + web UI
opencode session list          # list sessions
opencode stats                 # token/cost stats

암기할 만한 TUI 명령어

/connect   # connect a provider
/init      # analyze repo, generate AGENTS.md
/share     # share a session (if enabled)
/undo      # undo a change
/redo      # redo a change
/help      # help/shortcuts

기본 “리더 키” 개념 (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는 Anthropic의 제3자 Claude 구독 접근 차단 정책의 영향을 받은 최초의 도구 중 하나였습니다 — 이는 2026년 1월, 동일한 제한이 OpenClaw에 영향을 미치기 한 달 전에 이루어진 조치였습니다. OpenClaw 부상과 몰락 타임라인은 두 사건과 구독 컴퓨팅을 기반으로 구축된 에이전트 도구를 위한 더 넓은 패턴을 문서화합니다.

출처 (공식 우선)

공식:

• 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/