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

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

버전 참고 사항: OpenCode는 빠르게 출시됩니다. 여기서 제공되는 “latest” 명령어는 안정적이지만, 출력 및 기본값은 변경될 수 있습니다—항상 공식 CLI 문서와 변경 기록(아래에 링크됨)을 참조하세요.

이 기사는 AI Developer Tools: The Complete Guide to AI-Powered Development의 일부입니다.

OpenCode는 무엇인가 (그리고 어디에 맞는가)

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

• opencode를 실행할 때 터미널 UI를 시작
• opencode run을 통해 비상호작용적인 “한 번 실행” 프롬프트를 실행 (스크립트/자동화)
• opencode serve를 통해 헤드리스 HTTP 서버를 노출 (또는 opencode web을 통해 웹 UI 제공)
• 공식 JS/TS SDK @opencode-ai/sdk를 통해 프로그래밍적으로 제어

만약 /ai-devtools/ 클러스터를 구축하고 있다면, OpenCode는 자연스럽게 확장되는 서브클러스터 후보로, 다음과 같은 영역으로 확장될 수 있습니다:

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

사전 조건

원활한 사용을 위해 다음이 필요합니다:

• 현대적인 터미널 에뮬레이터 (TUI 경험에 중요).
• 적어도 하나의 모델/프로바이더에 대한 액세스 (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 파일에서 키를 로드할 수 있습니다.

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

리포지토리에서:

cd /path/to/your/repo
opencode

그런 다음 초기화:

/init

이렇게 하면 프로젝트를 분석하고 프로젝트 루트에 AGENTS.md 파일을 생성합니다. 이 파일을 커밋하는 것이 일반적으로 좋습니다. 이는 OpenCode (및 팀원)이 일관된 프로젝트 컨텍스트를 공유하도록 도와줍니다.

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

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

opencode run "JavaScript에서 클로저가 어떻게 작동하는지 설명해줘"

워크플로우: 코드 생성 (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: {
    // 모델 문자열 형식은 제공자/모델 (예시만)
    // 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 quickstart demo" } });

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

  // 기본 모델 선택 (공급자/모델). 이는 `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)를 사용합니다. 많은 단축키는 “리더 + 키”입니다.

FAQ (스키마 준비)

OpenCode란 무엇인가요?

OpenCode는 터미널(TUI + CLI)에서 작동하는 오픈소스 AI 코딩 에이전트이며, 추가로 데스크톱/IDE 표면을 제공합니다.

OpenCode는 무료인가요?

도구는 오픈소스입니다. 사용 비용은 연결한 모델/프로바이더에 따라 달라집니다. 일부 프로바이더는 구독 기반 인증 또는 무료 계층을 제공할 수 있습니다.

TUI 없이 OpenCode를 실행할 수 있나요?

opencode run "..."을 사용하여 비상호작용 모드로 실행할 수 있습니다 (스크립트/자동화에 유용).

OpenCode는 프로바이더 자격 증명을 어디에 저장하나요?

opencode auth login은 자격 증명을 ~/.local/share/opencode/auth.json에 저장합니다.

OpenCode에는 API/SDK가 있나요?

네. OpenCode는 헤드리스 HTTP 서버 (opencode serve)를 실행할 수 있으며, /doc에 OpenAPI 스펙을 제공하고 공식 JS/TS SDK: @opencode-ai/sdk를 제공합니다.

OpenCode와 GitHub Copilot을 함께 사용할 수 있나요?

GitHub은 Copilot이 OpenCode와 공식 통합을 통해 인증을 지원한다고 발표했습니다. 구체적인 가용성은 Copilot 계획과 현재 프로바이더 인증 흐름에 따라 달라집니다.

한 페이지에 인쇄 가능한 OpenCode 빠른 참조 표

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

참고 자료 (공식 자료 우선)

공식:

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