책에 포함된 노트초보자를 위한 OpenCode × OpenAI OAuth 실전 가이드: 설치, 설정, 로그인, 코드 실습까지

3. OpenCode 설치와 기본 구조 익히기

2026-04-22Views 261약 10분생성형 AI 활용

3. OpenCode 설치와 기본 구조 익히기

이제 진짜로 손을 움직일 차례입니다. 앞 장에서 준비물과 제한사항을 점검했다면, 이번에는 OpenCode를 실제로 설치하고 앞으로 계속 만나게 될 기본 구조를 머릿속에 정리해 보겠습니다.

초보자 입장에서 이번 장의 핵심은 하나입니다. OpenAI OAuth 연동은 플러그인 설치만으로 끝나는 일이 아니라, OpenCode가 어디서 설정을 읽고, 어디에 인증을 저장하고, 어떤 방식으로 실행되는지 이해하는 일이라는 점입니다. 이 구조가 잡히면 뒤 장들이 훨씬 쉬워집니다. 반대로 이 구조가 흐릿하면, 설정을 고쳤는데 왜 안 바뀌는지부터 바로 헷갈리기 시작합니다.²³

OpenCode 설치와 기본 구조 익히기

OpenCode를 어떻게 이해하면 쉬울까

OpenCode는 터미널에서 쓰는 AI 코딩 에이전트입니다. 그런데 한 가지 얼굴만 있는 도구는 아닙니다. 상황에 따라 세 가지 방식으로 생각하면 이해가 쉬워집니다.¹²

opencode라고만 실행하면 열리는 대화형 화면(TUI)
opencode run "질문"처럼 한 번만 실행하는 CLI 자동화 모드
opencode serve, opencode web처럼 백엔드 서버처럼 띄우는 헤드리스 모드

쉽게 비유하면 이렇습니다. OpenCode는 한 사람인데, 필요할 때는 상담 창구처럼 대화하고, 필요할 때는 한 번에 명령만 처리하고, 필요할 때는 뒤에서 서버처럼 조용히 일합니다.

이번 책에서는 주로 첫 번째와 두 번째 얼굴, 즉 TUI와 CLI를 가장 많이 쓰게 됩니다.

OpenCode 설치하기

설치 방법은 여러 가지가 있지만, 초보자라면 한 번에 하나만 선택하는 편이 좋습니다. 설치 방식을 두세 개 섞어 두면 나중에 어떤 바이너리가 실행되는지 헷갈릴 수 있기 때문입니다.¹

가장 많이 쓰는 설치 예시는 아래와 같습니다.

Linux, macOS, WSL에서 빠르게 설치

curl -fsSL https://opencode.ai/install | bash

npm으로 전역 설치

npm install -g opencode-ai

Homebrew 사용

brew install anomalyco/tap/opencode

Windows 예시

choco install opencode

또는

scoop install opencode

설치가 끝났다면 바로 확인해 봅니다.

opencode --version
opencode --help

버전 번호가 보이고 도움말이 나오면 첫 관문은 통과입니다.¹²

첫 실행: TUI와 CLI의 차이부터 익히기

OpenCode는 인수 없이 실행하면 기본적으로 TUI를 시작합니다.²

opencode

이 명령은 터미널 안에 대화형 인터페이스를 띄웁니다. 여기서는 채팅하듯 질문할 수 있고, 나중에는 모델 선택, 세션 전환, 파일 작업도 이어서 하게 됩니다.⁶

반면 아래 명령은 TUI를 열지 않고 한 번만 실행하고 끝납니다.²

opencode run "Say hello in Korean"

둘의 차이를 아주 단순하게 정리하면 이렇습니다.

opencode는 앉아서 대화하는 모드
opencode run은 한 줄 지시를 던지고 결과를 받는 모드

초보자는 보통 TUI부터 익히는 편이 좋습니다. 화면에서 흐름이 보여서 덜 무섭기 때문입니다. 하지만 반복 작업이나 자동화는 결국 opencode run이 훨씬 편합니다. 그래서 두 방식을 초반부터 같이 알아두는 것이 좋습니다.

초보자 실습 1: 설치가 정말 잘 되었는지 코드로 확인하기

단순히 --version만 보는 대신, 아주 작은 Node.js 스크립트로 OpenCode 실행 여부를 확인해 보겠습니다. 나중에 다른 도구 설치를 확인할 때도 같은 패턴을 그대로 응용할 수 있습니다.

프로젝트 폴더에서 check-opencode.mjs 파일을 만들고 아래 내용을 넣어 주세요.

import { execSync } from "node:child_process";

function run(command) {
  try {
    return execSync(command, { encoding: "utf-8" }).trim();
  } catch (error) {
    return `실패: ${error.message.split("n")[0]}`;
  }
}

console.log("OpenCode 버전:", run("opencode --version"));
console.log("도움말 첫 줄:", run("opencode --help").split("n")[0]);

실행합니다.

node check-opencode.mjs

정상이라면 OpenCode 버전과 도움말 일부가 출력됩니다. 만약 실패가 나온다면, 설치 자체가 안 된 경우도 있지만 PATH에 명령어 위치가 안 잡힌 경우일 수도 있습니다. 지금 단계에서는 "설치와 실행 가능 상태는 미묘하게 다를 수 있다"는 감각만 잡으면 충분합니다.

프로젝트 안에서 OpenCode를 실행해야 하는 이유

OpenCode는 현재 디렉터리에서 설정 파일을 찾고, 없으면 가장 가까운 Git 디렉터리까지 상위로 탐색합니다.³ 이 말은 곧, 어디에서 OpenCode를 실행하느냐가 꽤 중요하다는 뜻입니다.

예를 들어 어떤 프로젝트 루트에서 opencode를 실행하면, OpenCode는 그 프로젝트용 설정과 파일 구조를 기준으로 동작합니다. 반대로 아무 관계없는 홈 디렉터리에서 실행하면 "지금 어떤 프로젝트를 기준으로 일해야 하지?" 하는 상태가 되기 쉽습니다.

그래서 초반에는 아래처럼 실습 전용 폴더를 하나 만들어 두는 것이 좋습니다.

mkdir opencode-lab
cd opencode-lab
opencode

프로젝트를 처음 제대로 여는 흐름에서는 TUI 안에서 /init을 실행해 프로젝트를 분석하고 AGENTS.md를 생성하는 방식도 자주 씁니다.¹⁶ 이 파일은 나중에 OpenCode가 프로젝트 규칙과 맥락을 이해하는 데 도움을 줍니다. 쉽게 말해, 새로 합류한 팀원에게 "우리 프로젝트는 이런 스타일이야"라고 적어 주는 메모와 비슷합니다.

OpenCode의 파일 구조: 어디에 무엇이 있나

OpenCode를 처음 쓰면 가장 자주 하는 질문이 있습니다.

설정 파일은 어디 있지?
로그인 정보는 어디에 저장되지?
로그는 어디에 쌓이지?
플러그인은 어디에서 읽히지?

이 질문에 답할 수 있어야 다음 장부터 덜 헤맵니다.

먼저 큰 그림부터 잡아보겠습니다. OpenCode는 크게 두 종류의 파일을 다룹니다.

하나는 사람이 직접 손보는 설정 파일이고, 다른 하나는 실행하면서 쌓이는 데이터 파일입니다. 이 둘을 구분해 두면 머리가 훨씬 편해집니다.

자주 보게 될 핵심 경로

종류	대표 위치	용도
전역 설정	`~/.config/opencode/opencode.json`	사용자 전체 기본 설정
프로젝트 설정	`<프로젝트 루트>/opencode.json`	프로젝트 전용 설정
TUI 설정	`~/.config/opencode/tui.json`	TUI 화면 동작, 테마, 키 설정
전역 플러그인 폴더	`~/.config/opencode/plugins/`	로컬 플러그인 보관
프로젝트 플러그인 폴더	`<프로젝트 루트>/.opencode/plugins/`	프로젝트 전용 플러그인
인증 정보	`~/.local/share/opencode/auth.json`	provider 인증 정보 저장
로그	`~/.local/share/opencode/log/`	실행 로그 저장
세션/프로젝트 데이터	`~/.local/share/opencode/project/`	세션과 프로젝트 데이터 저장

여기서 한 가지 덧붙이면, 설정 파일은 .json이 기본 설명이지만 OpenCode는 JSONC도 지원합니다. 그래서 실제 환경에서는 opencode.jsonc를 쓰는 예제도 자주 보게 됩니다.³

설정 파일은 하나가 아니라 겹쳐서 읽힌다

초보자가 가장 자주 걸리는 함정이 바로 이것입니다. OpenCode 설정은 한 파일만 읽는 방식이 아니라, 여러 위치의 설정을 병합해서 읽습니다.³

순서를 아주 단순하게 요약하면 이렇습니다.

조직 기본값이 있다면 먼저 로드
전역 설정이 그 위를 덮음
커스텀 경로 설정이 있다면 그 위를 덮음
프로젝트의 opencode.json이 다시 덮음
.opencode 디렉터리의 agents, commands, plugins가 추가 반영
환경 변수 기반 인라인 설정이 마지막에 덮음

이 말을 초보자 눈높이로 번역하면, "내가 고친 설정이 안 먹는 것 같으면, 다른 위치에서 같은 키를 다시 덮고 있을 수 있다"는 뜻입니다.

예를 들어 전역 설정에서 기본 모델을 바꿨는데 프로젝트 안에서 또 다른 모델을 지정해 두었다면, 여러분은 전역 설정을 바꿨다고 생각하지만 실제 실행은 프로젝트 설정을 따르게 됩니다. 이런 일이 의외로 자주 생깁니다.

인증 정보는 어디에 저장될까

OpenCode에서 opencode auth login이나 TUI의 /connect 흐름으로 provider 인증을 하면, 인증 정보는 기본적으로 ~/.local/share/opencode/auth.json에 저장됩니다.²⁴

즉, 이 파일은 꽤 민감합니다. 초보자라면 이렇게 기억하면 됩니다.

opencode.json은 설정 파일
auth.json은 로그인 정보 파일

둘은 역할이 완전히 다릅니다.

OpenCode는 시작할 때 이 인증 파일을 읽고, 환경 변수나 프로젝트의 .env에 정의된 값도 함께 불러올 수 있습니다.² 그래서 어떤 날은 auth.json 없이도 동작하고, 어떤 날은 로그인한 적이 없는데도 모델이 보이는 일이 생길 수 있습니다. 그건 보통 환경 변수 쪽에 이미 인증 정보가 잡혀 있기 때문입니다.

여기서 중요한 습관이 하나 있습니다. 초보자는 auth.json을 직접 편집하려 들지 않는 편이 좋습니다. 일단은 로그인 명령으로 관리하는 쪽이 안전합니다. 손으로 만지다가 JSON이 깨지면, 원인을 찾기가 훨씬 어려워집니다.

로그와 세션 데이터는 어디에 쌓일까

문제가 생겼을 때 OpenCode는 꽤 많은 힌트를 남깁니다. 로그 파일은 ~/.local/share/opencode/log/에 저장되고, 세션과 프로젝트 데이터는 ~/.local/share/opencode/project/ 아래에 쌓입니다.⁴

즉, 나중에 "왜 인증이 꼬였지?", "왜 이전 세션이 남아 있지?", "왜 자꾸 같은 에러가 나지?" 같은 상황이 오면, 이 경로를 보면 됩니다. 초보자에게는 이것만 알아도 꽤 든든합니다. 컴퓨터가 아무 말도 안 하는 것 같아도, 사실은 다른 서랍에 메모를 남겨 두고 있기 때문입니다.

CLI에서 자주 쓰는 기본 명령어 몇 개만 먼저 익히기

지금 단계에서 모든 명령어를 외울 필요는 없습니다. 다만 아래 정도는 눈에 익혀 두면 좋습니다.²

opencode
opencode run "Explain closures in JavaScript"
opencode auth login
opencode auth ls
opencode models
opencode serve
opencode web
opencode session list

이 중에서 초반에 특히 중요한 것은 세 가지입니다.

opencode : 대화형 시작점
opencode auth login : 인증의 입구
opencode models : 지금 실제로 어떤 모델을 쓸 수 있는지 확인하는 도구

나중에 설정 파일에 모델명을 넣을 때도 provider/model 형식을 확인하는 데 이 명령이 아주 유용합니다.

플러그인은 어떻게 동작할까

이제 이번 장의 핵심으로 들어가 보겠습니다. 다음 장부터 설치할 opencode-openai-codex-auth 같은 플러그인은 대체 무엇일까요?

가장 쉽게 말하면, 플러그인은 OpenCode에 새로운 기능이나 연결 방식을 덧붙이는 확장 부품입니다.⁵ 브라우저의 확장 프로그램과 비슷하다고 생각하면 이해가 빠릅니다.

OpenCode는 플러그인을 두 방식으로 불러올 수 있습니다.³⁵

로컬 파일 기반 플러그인
npm 패키지 이름으로 불러오는 플러그인

npm 플러그인을 쓰면 OpenCode가 필요한 패키지를 설치하고 캐시합니다. 그래서 사용자는 보통 프로젝트 폴더 안에서 따로 npm install을 직접 하지 않아도 됩니다. 설정 파일에 플러그인 이름만 적어 두면, OpenCode가 뒤에서 필요한 부품을 가져오는 구조입니다.⁵

이 흐름을 아주 단순하게 그리면 이렇습니다.

OpenCode가 설정 파일을 읽습니다.
plugin 항목을 보고 어떤 플러그인이 필요한지 확인합니다.
플러그인을 로드합니다.
플러그인이 인증, 요청 변환, 추가 도구 같은 기능을 끼워 넣습니다.
그 상태로 모델 호출이 진행됩니다.

즉, 플러그인은 OpenCode 바깥에서 혼자 도는 별도 앱이 아니라, OpenCode가 모델과 대화하는 사이에 끼어드는 통역사이자 어댑터에 가깝습니다.

OpenAI OAuth 플러그인은 설정을 어떻게 받아갈까

우리가 다음 장부터 다룰 opencode-openai-codex-auth 계열 플러그인은 OpenCode의 설정 구조를 그대로 활용합니다. 핵심은 provider.openai.options와 provider.openai.models 같은 설정이 OpenCode 내부에서 병합된 뒤, 플러그인 쪽으로 전달된다는 점입니다.⁷

쉽게 풀어 쓰면 이렇습니다.

전역 설정과 프로젝트 설정이 먼저 합쳐집니다.
그 안의 OpenAI 관련 옵션이 정리됩니다.
플러그인이 그 값을 받아 실제 요청에 반영합니다.

예를 들어 나중에 넣게 될 reasoning 옵션이나 모델별 세부 설정은, 그냥 보기 좋은 장식이 아니라 플러그인이 실제 요청을 만들 때 읽어 가는 재료입니다.⁷

그래서 다음 장에서 플러그인을 설치한 뒤에도 설정이 엉뚱하면 동작이 이상해질 수 있습니다. 플러그인 문제처럼 보여도 사실은 설정 병합 순서 문제일 때가 많습니다. 이 장에서 구조를 먼저 익히는 이유가 바로 여기에 있습니다.

구조만 보는 미리보기 설정 예시

아래 예시는 아직 완성본이 아닙니다. 그냥 "플러그인이 어디에 들어가는지" 구조만 보는 용도입니다.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-openai-codex-auth"],
  "provider": {
    "openai": {
      "options": {
        // 다음 장들에서 실제 값 채움
      },
      "models": {
        // 다음 장들에서 실제 모델 정의
      }
    }
  }
}

여기서 눈여겨볼 것은 세 군데입니다.

plugin : 어떤 확장 기능을 붙일지
provider.openai.options : OpenAI 쪽 공통 옵션
provider.openai.models : 모델별 설정

이 세 칸이 나중에 실제 연동의 중심 무대가 됩니다.

초보자 실습 2: 내 컴퓨터에서 OpenCode 관련 경로 출력하기

이번에는 OpenCode 구조를 눈으로 확인하는 작은 실습을 해보겠습니다. 아래 파일을 show-opencode-paths.mjs라는 이름으로 저장하세요.

import os from "node:os";
import path from "node:path";

const home = os.homedir();

const paths = {
  globalConfig: path.join(home, ".config", "opencode", "opencode.json"),
  tuiConfig: path.join(home, ".config", "opencode", "tui.json"),
  globalPlugins: path.join(home, ".config", "opencode", "plugins"),
  dataDir: path.join(home, ".local", "share", "opencode"),
  authFile: path.join(home, ".local", "share", "opencode", "auth.json"),
  logDir: path.join(home, ".local", "share", "opencode", "log"),
};

console.log("OpenCode 관련 주요 경로");
console.table(paths);

실행합니다.

node show-opencode-paths.mjs

이 실습의 목적은 단순합니다. 나중에 책에서 ~/.config/opencode/opencode.json이라고 말하면, 여러분 머릿속에 "아, 그건 내 홈 디렉터리 아래 설정 파일이지"라는 그림이 떠오르게 만드는 것입니다. 초보자는 이 그림만 생겨도 설정 파일 편집이 훨씬 덜 무섭습니다.

지금 단계에서 꼭 기억할 것

이번 장에서 배운 내용을 짧게 정리하면 이렇습니다.

OpenCode는 TUI, CLI, 서버 모드를 가진 터미널 중심 도구입니다.¹²
opencode는 대화형, opencode run은 비대화형입니다.²
전역 설정은 보통 ~/.config/opencode/opencode.json, 인증 정보는 ~/.local/share/opencode/auth.json에 있습니다.²³
로그와 세션 데이터는 ~/.local/share/opencode/ 아래에 쌓입니다.⁴
플러그인은 설정을 읽고 OpenCode의 동작을 확장하는 부품입니다.⁵
앞으로 붙일 OpenAI OAuth 플러그인은 provider.openai 설정을 받아 실제 요청을 조정합니다.⁷

이제 바닥 공사는 끝났습니다. 아직 본격적인 OAuth 연동을 시작한 것은 아니지만, 앞으로 만지게 될 폴더 구조와 설정 흐름은 한 번 훑어본 셈입니다. 이런 준비가 되어 있으면 다음 장의 플러그인 설치 실습이 훨씬 덜 낯설게 느껴집니다.

다음 장에서는 드디어 opencode-openai-codex-auth 플러그인을 직접 설치해 보겠습니다.

참고

⁷OpenCode Codex Auth Plugin 설정 흐름 문서

책 목록

초보자를 위한 OpenCode × OpenAI OAuth 실전 가이드: 설치, 설정, 로그인, 코드 실습까지

전체 목차 보기