터미널 속 AI 코딩 에이전트,
가장 쉽게. Terminal AI coding agents,
made easy.

01 · 소개Intro

OpenCode 가 뭔가요?What is OpenCode?

OpenCode는 터미널 안에서 동작하는 오픈소스 AI 코딩 에이전트예요. “이 기능 추가해줘”처럼 말하면 코드베이스를 읽고 직접 파일을 고쳐줍니다. 특정 회사 모델에 묶이지 않아 무료·로컬·유료 모델을 자유롭게 바꿔 쓰는 게 매력이에요. OpenCode is an open-source AI coding agent that runs in your terminal. Tell it “add this feature” and it reads your codebase and edits files for you. It isn't tied to one vendor, so you can freely swap between free, local, and paid models.

02 · 설치Install

설치하기Install

운영체제에 맞는 방법 하나만 고르세요. 윈도우는 Scoop 또는 npm을 추천해요.Pick one method for your OS. On Windows, Scoop or npm is easiest.

# Scoop 으로 설치 (권장)# Install via Scoop (recommended)
scoop install opencode

# 또는 Chocolatey 로# or Chocolatey
choco install opencode

# 또는 Node.js(npm)가 있다면# or, if you have Node.js (npm)
npm install -g opencode-ai

# 공식 설치 스크립트 (가장 쉬움)# Official installer (easiest)
curl -fsSL https://opencode.ai/install | bash

# 또는 Homebrew# or Homebrew
brew install anomalyco/tap/opencode

# 또는 npm# or npm
npm install -g opencode-ai

설치 확인 & 업데이트Verify & update

# 버전이 출력되면 성공!# If a version prints, you're set!
opencode --version

# 나중에 업데이트# update later
opencode upgrade

· 안드로이드 (Termux)Android (Termux)

안드로이드 기기에서 설치 (Termux)Install on Android (Termux)

안드로이드 기기에서도 쓸 수 있어요. 다만 그냥은 안 됩니다. OpenCode 실행 파일이 Termux 환경에 안 맞거든요. 그래서 proot-distro로 기기 안에 진짜 리눅스(우분투)를 깔고 그 안에서 설치합니다. 루팅은 필요 없어요. It works on Android devices — but not out of the box. OpenCode's binary doesn't match the Termux environment. So we use proot-distro to install a real Linux (Ubuntu) on the device and install there. No root needed.

1. 1

   Termux 준비Prep Termux

   Termux는 F-Droid나 GitHub 버전을 설치하세요(플레이스토어 버전은 오래됨). 그다음 갱신:Install Termux from F-Droid or GitHub (the Play Store build is outdated). Then update:

   복사Copy복사됨!Copied!

   pkg update && pkg upgrade -y

2. 2

   proot-distro 설치Install proot-distro

   기기 안에 리눅스 배포판을 설치·실행하게 해주는 도구예요.The tool that installs and runs a Linux distro on the device.

   복사Copy복사됨!Copied!

   pkg install proot-distro -y

3. 3

   우분투 설치 & 로그인Install & enter Ubuntu

   우분투(약 200MB)를 받아 설치하고 그 안으로 들어갑니다.Download Ubuntu (~200MB), install it, and log in.

   복사Copy복사됨!Copied!

   # 우분투 설치 (처음 한 번만)# install Ubuntu (once)
   proot-distro install ubuntu
   
   # 우분투 안으로 로그인# log into Ubuntu
   proot-distro login ubuntu

   로그인하면 프롬프트가 바뀌어요. 여기서부터는 우분투 안에서 입력합니다.The prompt changes after login — from here you type inside Ubuntu.

4. 4

   Node.js 설치Install Node.js

   OpenCode는 npm으로 설치하니 Node.js가 필요해요. 우분투 안에서 LTS를 깝니다.OpenCode installs via npm, so you need Node.js. Install the LTS inside Ubuntu.

   복사Copy복사됨!Copied!

   # 기본 도구# basics
   apt update && apt upgrade -y
   apt install -y curl git
   
   # Node.js LTS 설치# install Node.js LTS
   curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
   apt install -y nodejs

5. 5

   OpenCode 설치 & 실행Install & run OpenCode

   이제 평소처럼 설치·실행하면 끝! 이후는 03 · 첫 실행부터 그대로.Now install and run as usual! From here, follow 03 · First run.

   복사Copy복사됨!Copied!

   npm install -g opencode-ai
   opencode

03 · 첫 실행First run

첫 실행 & 로그인First run & login

설치가 끝났으면 작업할 폴더로 가서 opencode 만 입력하면 됩니다.Once installed, go to your project folder and just type opencode.

1. 1

   프로젝트 폴더에서 실행Run inside your project

   코드가 있는 폴더 안에서 실행해야 코드를 읽을 수 있어요.Run it inside the folder with your code so it can read the codebase.

   복사Copy복사됨!Copied!

   cd my-project
   opencode

2. 2

   제공사 연결 — /connectConnect a provider — /connect

   화면 안에서 /connect 를 입력하면 목록이 떠요. 처음이라면 OpenCode Zen의 무료 모델로 시작하길 추천(04장).Type /connect to see providers. New here? Start with OpenCode Zen free models (ch. 04).

   복사Copy복사됨!Copied!

   /connect

   터미널에서 바로 로그인하려면 opencode auth login 도 같은 역할.opencode auth login does the same from the shell.

3. 3

   프로젝트 분석 — /initAnalyze the project — /init

   /init 는 프로젝트를 훑어 AGENTS.md(에이전트용 메모)를 만들어요. 깃에 커밋해두면 다음에도 똑똑하게 일합니다./init scans the project and writes AGENTS.md (a memo for the agent). Commit it so future runs stay smart.

   복사Copy복사됨!Copied!

   /init

4. 4

   이제 그냥 말 걸기Now just talk to it

   원하는 걸 자연어로 입력! @ 로 특정 파일을 콕 집어 참조시킬 수 있어요.Type what you want in plain language. Use @ to point at a specific file.

   복사Copy복사됨!Copied!

   @src/app.js 에 다크 모드 토글 버튼을 추가해줘Add a dark-mode toggle button to @src/app.js

04 · 무료 모델Free models

무료로 모델 쓰기Use models for free

OpenCode 자체는 공짜예요. 비용은 “어떤 모델을 쓰느냐”에서 갈립니다. 무료로 시작하는 길은 크게 세 가지.OpenCode itself is free. Cost depends on which model you use. There are three ways to start free.

// 무료 모델을 기본값으로// set a free model as default
{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/<free-model>"
}

# OpenRouter 로그인# log into OpenRouter
opencode auth login

# 연결된 모델 보기# list connected models
opencode models openrouter

// 로컬 Ollama 연결// connect local Ollama
{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "qwen2.5-coder": { "name": "Qwen2.5 Coder" } }
    }
  }
}

모델 갈아끼우기Switching models

05 · 명령어Commands

명령어 & 단축키Commands & keys

터미널 명령어, 화면 안 슬래시 명령어, 키보드 단축키 세 종류로 조작해요.Three control surfaces: shell commands, in-app slash commands, and keyboard shortcuts.

① 터미널 명령어Shell commands

② 슬래시 명령어Slash commands 화면 안에서 /type / in-app

③ 키보드 단축키Keyboard shortcuts

기본 리더 키는 Ctrl+X. “리더 누른 뒤 → 단축키” (예: 새 세션 = Ctrl+X → N).The leader key is Ctrl+X. Press leader, then the key (e.g. new session = Ctrl+X → N).

06 · 에이전트Agents

에이전트 활용: Build & PlanAgents: Build & Plan

성격이 다른 두 기본 에이전트가 있어요. Tab 하나로 전환.Two built-in agents with different personalities. Switch with one Tab.

서브에이전트 — @ 로 부르기Subagents — call with @

나만의 에이전트 만들기Make your own agent

# 대화형으로 생성# create interactively
opencode agent create

# ~/.config/opencode/agents/reviewer.md
---
description: 보안·유지보수 관점 코드 리뷰review code for security & maintainability
mode: subagent
permission:
  edit: deny
  bash: deny
---
당신은 코드 리뷰어입니다. 보안과 가독성에 집중하세요.You are a code reviewer. Focus on security and readability.

07 · 꿀팁Tips

실전 꿀팁Pro tips

· CLI 비교Compare

주요 AI 코딩 CLI — 가격 & 모델Major AI coding CLIs — price & models

OpenCode 말고도 터미널 AI 코딩 CLI가 더 있어요. 모델·가격이 다르니 상황에 맞게 고르세요. (모델은 큰 ‘계열’만 적었어요.)Beyond OpenCode there are more terminal AI coding CLIs. Models and pricing differ — pick what fits. (Models shown as broad families only.)

12 · FAQ

자주 묻는 질문FAQ