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

OpenCode를 설치, 구성 및 사용하는 방법

Page content

OpenCode는 터미널(TUI + CLI)에서 실행할 수 있는 오픈소스 AI 코딩 에이전트입니다. 선택적으로 데스크톱 및 IDE 표면도 제공합니다. 이는 OpenCode Quickstart입니다: 설치, 확인, 모델/프로바이더 연결, 그리고 실제 워크플로우 실행 (CLI + API).

버전 노트: OpenCode는 빠르게 출시됩니다. 여기서 나열된 “latest” 명령어는 안정적이지만, 출력 및 기본값이 변경될 수 있으므로 항상 공식 CLI 문서와 변경 기록(아래 링크 참조)을 다시 확인하세요.

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

OpenCode는 무엇이며, 어디에 맞는지

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

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

자체 호스팅된 qwen3.5 27b LLM과 함께하는 opencode

/ai-devtools/ 클러스터를 구축하는 경우, OpenCode는 서브클러스터 후보로 강력한 선택지입니다. 자연스럽게 다음과 같은 영역으로 확장됩니다:

  • CLI 심층 분석
  • 모델/프로바이더 행동 및 비용 (OpenCode 내부의 LLM 비교)
  • 구성 및 에이전트
  • 통합 (GitHub/GitLab/Copilot)
  • 빠른 참고 자료

사전 조건

필요한 사항:

  • 현대적인 터미널 에뮬레이터 (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 없이 가벼운 스택을 선호하는 경우 (BTW, ollama는 Go로 구현됨), llama.cpp을 사용해보는 것이 좋습니다. GGUF 형식의 모델 사용이 편리하고, 새 모델 (예: Qwen3.5)과의 호환성이 훨씬 잘 구현되어 있다는 점에서, 저는 실제로 이 기회를 매우 즐겼습니다.

프로젝트를 올바르게 시작하는 방법 (추천 첫 실행)

리포지토리에서:

cd /path/to/your/repo
opencode

그런 다음 초기화:

/init

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

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

OpenCode는 비상호 실행을 지원합니다:

opencode run "자바스크립트에서 클로저가 어떻게 작동하는지 설명해줘"

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

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

opencode run "Go 함수 ParsePort(envVar string, defaultPort int) (int, error)를 작성하세요. 이 함수는 환경 변수를 읽고 정수를 파싱한 후 1-65535 범위 내에서 검증하고, 빈 경우 defaultPort를 반환해야 합니다. 3개의 테이블 기반 테스트를 포함하세요."

예상 출력:

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

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

목표: 더 엄격한 에이전트를 사용하여 사고 없는 편집을 방지하여 리팩토링.

opencode run --agent plan --file ./src/auth.ts \
  "이 파일을 복잡도를 줄이기 위해 리팩토링하세요. 출력: (1) 짧은 계획, (2) 통합된 차이 패치, (3) 테스트해야 할 위험/엣지 케이스. 명령어를 실행하지 마세요."

예상 출력:

  • 계획 섹션 + diff --git ... 패치 블록 + 테스트 확인 목록.
  • 내용은 다를 수 있습니다. 차이를 생성하지 않으면 다시 프롬프트: “차이만 반환” 또는 “diff --git 형식 사용.”

워크플로우: 리포지토리 질문 (CLI)

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

opencode run --agent explore \
  "이 리포지토리에서 API 요청에 대한 인증이 어디에서 검증되는가요? 가능한 파일을 나열하고 흐름을 설명하세요. 확신하지 못하면 확인한 내용을 말하세요."

예상 출력:

  • 짧은 파일 경로 지도 + 흐름 설명.
  • 출력은 리포지토리 크기와 모델/프로바이더 컨텍스트 도구에 따라 다릅니다.

워크플로우: 반복적인 CLI 실행을 빠르게 하기 위한 지속 가능한 서버

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

터미널 1:

opencode serve --port 4096 --hostname 127.0.0.1

터미널 2:

opencode run --attach http://localhost:4096 "리포지토리 구조와 주요 진입점을 요약하세요."
opencode run --attach http://localhost:4096 "이제 3개의 고영향 리팩토링을 제안하고 그 이유를 설명하세요."

예상 출력:

  • 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(`서버가 실행 중: ${opencode.server.url}`);

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

// 세션 생성 및 프롬프트
const session = await opencode.client.session.create({ body: { title: "SDK 빠른 시작 예시" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "이 리포지토리에 대한 작은 README 섹션을 생성하세요." }],
  },
});

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",

  // 기본 모델 선택 (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 빠른 참고

매일 사용하는 명령어

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 "..." 반복적인 시작 오버헤드 방지에 유용
기본 인증 활성화 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에서 커스터마이징 가능

참고자료 (공식 우선)

공식:

권위적인 통합 참고:

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