2. 시작 전 준비물과 제한사항 점검
2. 시작 전 준비물과 제한사항 점검
왜 이 장을 먼저 읽어야 할까
OpenCode에 OpenAI OAuth를 붙이는 과정은 생각보다 짧지만, 막히는 지점은 늘 비슷합니다. 설치 명령어가 틀려서가 아니라, 버전이 안 맞거나, 구독 조건을 놓쳤거나, 운영체제 차이를 가볍게 봤거나, 이 방식의 사용 범위를 오해해서 멈추는 경우가 많습니다.
쉽게 말해 이 장은 출발 전에 가방을 여는 시간입니다. 노트북은 챙겼는지, 충전기는 있는지, 신분증은 들고 왔는지 확인하는 것과 비슷합니다. 이 확인을 10분만 해두면, 뒤에서 한 시간 덜 헤맬 가능성이 아주 높아집니다.
이번 장에서 먼저 점검할 것은 다음 다섯 가지입니다.
OpenCode를 실행할 수 있는 환경이 있는가
Node.js가 20 이상인가
ChatGPT Plus 또는 Pro 구독이 활성 상태인가
내가 쓰는 운영체제에서 터미널과 브라우저 흐름이 자연스럽게 이어지는가
이 방식이 어디까지 허용되는지, 어디부터는 쓰면 안 되는지 이해했는가
이번 실습에 필요한 준비물
이번 책의 흐름은 단순합니다. OpenCode + 플러그인 + ChatGPT Plus/Pro OAuth 조합을 만드는 것입니다. 이 조합을 안정적으로 쓰려면 최소한 다음 조건은 갖춰져 있어야 합니다.1
OpenCode
Node.js 20+
활성화된 ChatGPT Plus 또는 Pro 구독
로그인 가능한 브라우저
일반적인 파일 읽기·쓰기 권한이 있는 로컬 개발 환경
여기서 초보자가 가장 많이 헷갈리는 부분은 Node.js입니다. OpenCode 자체는 설치 방법에 따라 Node 없이도 들어갈 수 있지만, 이 책에서 다루는 플러그인 설치 흐름은 npx를 사용하므로 Node.js 20 이상으로 맞춰 두는 것이 가장 안전합니다.1 괜히 18 버전으로 시작했다가 "왜 나만 안 되지?" 모드에 들어갈 필요가 없습니다.
또 하나 알아둘 점이 있습니다. 앞으로 우리가 다룰 설정 파일은 보통 전역 설정인 ~/.config/opencode/opencode.json 또는 opencode.jsonc 쪽에 놓이게 됩니다. 프로젝트 루트의 opencode.json은 이 전역 설정을 덮어쓰는 방식으로 함께 동작합니다.2 즉, 나중에 설정이 꼬였을 때는 "프로젝트 설정이 전역 설정 위에 올라탔나?"를 먼저 의심하면 됩니다.
인증 정보가 저장되는 위치도 감을 잡아두면 좋습니다. OpenCode에서 공급자 인증 정보를 추가하면 일반적으로 ~/.local/share/opencode/auth.json에 저장됩니다.3 이 말은 곧, 공용 PC나 남과 함께 쓰는 계정으로 로그인하면 곤란할 수 있다는 뜻이기도 합니다.
운영체제별로 무엇을 준비해야 할까
운영체제는 단순한 취향 문제가 아닙니다. 같은 명령어를 입력해도 경로 표기, 셸 동작, 브라우저 콜백 방식이 조금씩 달라집니다. OpenCode는 macOS, Linux, Windows에서 모두 설치할 수 있지만, 실제 체감은 조금 다릅니다.4
macOS와 Linux
macOS와 Linux는 이 책의 예제를 따라가기 가장 편한 편입니다. ~/.config/... 같은 홈 디렉터리 경로 표현이 자연스럽고, bash나 zsh 계열 셸 예제도 거의 그대로 동작합니다. 브라우저가 자동으로 열리고 인증이 이어지는 흐름도 대체로 매끄럽습니다.
이 환경에서는 보통 다음 두 가지만 미리 보면 충분합니다.
터미널에서
node,npm,npx명령이 바로 인식되는가홈 디렉터리 아래 설정 파일을 만들 권한이 있는가
Windows
Windows도 충분히 가능합니다. 공식 문서 기준으로는 Chocolatey, Scoop, npm 같은 경로로 OpenCode를 설치할 수 있습니다.4 다만 초보자 입장에서는 경로 표기와 따옴표 처리에서 자주 실수합니다. 예를 들어 책에서 ~/.config/opencode/...라고 썼다면, PowerShell에서는 보통 $HOME.configopencode...처럼 이해하면 됩니다.
Windows에서 특히 기억할 점은 두 가지입니다. 첫째, 명령어는 같아 보여도 경로 구분자와 셸 문법이 다를 수 있다는 점입니다. 둘째, 브라우저 인증이 운영체제와 터미널 환경 사이에서 매끄럽게 돌아와야 한다는 점입니다.
SSH, 원격 환경, WSL 같은 우회 환경
노트북에서 직접 작업하는 게 아니라 SSH로 접속한 서버, 원격 개발 환경, 또는 WSL 안에서 작업하는 경우에는 브라우저 인증 콜백이 한 번에 돌아오지 않을 수 있습니다. 이런 상황을 대비해 플러그인은 브라우저 콜백이 실패할 때 전체 리디렉션 URL을 직접 붙여 넣는 방식도 안내합니다.5
이 말은 어렵게 들릴 수 있지만, 뜻은 간단합니다. 브라우저가 자동으로 "터미널아, 로그인 끝났어"라고 말을 못 걸면, 사용자가 그 메시지를 손으로 전달해 주는 방식이 있다는 뜻입니다. 원격 환경을 쓰는 사람이라면 이 사실만 미리 알아도 마음이 한결 편해집니다.
가장 중요한 제한사항: 이 방식은 어디까지 허용될까
이 장에서 가장 중요하게 기억해야 할 문장은 이것입니다.
이 플러그인 조합은 개인 개발용입니다.
문서에서도 분명히 밝히고 있듯이, 이 방식은 자신의 ChatGPT Plus/Pro 구독을 이용해 개인 코딩 작업을 돕는 용도로 설계되어 있습니다. 따라서 상업 서비스, API 재판매, 여러 사용자가 함께 붙는 서비스, 약관을 어기는 사용, 운영 환경의 백엔드 서비스 용도로 생각하면 안 됩니다. 그런 경우에는 OpenAI Platform API를 직접 사용하는 쪽이 맞습니다.1
이 부분은 초보자에게 특히 중요합니다. 처음 보면 "오, API 키 없이도 되네?" 하고 반가울 수 있습니다. 하지만 반갑다고 해서 아무 데나 붙이면 안 됩니다. 개인 노트북에서 내 코드 작업을 돕는 것과, 팀 서비스에 연결해 여러 사람이 쓰게 만드는 것은 전혀 다른 이야기입니다.
정리하면, 다음과 같은 사용은 피하는 것이 안전합니다.
팀 공용 서버에 붙여서 여러 명이 함께 쓰는 경우
고객 요청을 처리하는 실제 서비스 백엔드에 넣는 경우
내부 프록시처럼 열어 두고 조직 전체가 공유하는 경우
API 비용 대체재처럼 생각하고 운영 시스템에 넣는 경우
이 조합은 "내가 내 개발 환경에서 쓰는 도구"라고 이해하면 가장 정확합니다. 딱 그 선을 지키면 훨씬 덜 헷갈립니다.
Plus나 Pro라고 해서 무한 사용은 아니다
여기서 한 가지 더 짚고 넘어가겠습니다. ChatGPT Plus/Pro 구독이 있다고 해서 무한정 쓸 수 있다는 뜻은 아닙니다. OpenAI 도움말 기준으로 Codex 사용 한도는 사용 중인 플랜, 작업의 크기와 복잡도, 그리고 작업이 어디에서 실행되는지에 따라 달라질 수 있습니다.6
즉, 아주 큰 코드베이스를 계속 분석시키거나, 긴 세션을 반복하거나, 무거운 작업을 몰아서 수행하면 제한에 걸릴 수 있습니다. 마치 헬스장 회원권을 끊었다고 해서 러닝머신을 하루 19시간 독점할 수 없는 것과 비슷합니다.
초보자라면 이렇게 이해하면 충분합니다.
짧은 실습과 개인 개발에는 잘 맞는다
무거운 작업을 연속으로 많이 돌리면 한도를 만날 수 있다
"서비스 운영용 호출량"을 기대하면 안 된다
초보자용 사전 점검 실습
이제 말로만 확인하지 말고, 손으로 한 번 체크해 보겠습니다. 아직 OpenCode 설치 전이라면 일부 명령은 실패할 수 있습니다. 괜찮습니다. 지금의 목적은 내 환경 상태를 눈으로 확인하는 것입니다.
실습 1: 버전 확인하기
터미널에서 아래 명령을 실행해 보세요.
opencode --version
node -v
npm -v
npx -v여기서 해석은 간단합니다.
opencode --version이 실패하면 OpenCode는 아직 설치되지 않은 상태입니다. 그건 다음 장에서 해결하면 됩니다. 반면 node -v가 v20.x.x 이상이 아니라면, 다음 장으로 바로 넘어가지 말고 먼저 Node를 올리는 편이 좋습니다.
실습 2: Node.js 20+ 조건 자동 점검 스크립트 만들기
아래 파일을 check-env.mjs라는 이름으로 저장해 보세요.
import os from "node:os";
import fs from "node:fs";
const major = Number(process.versions.node.split(".")[0]);
const report = {
node: process.version,
platform: process.platform,
arch: process.arch,
homeDirectory: os.homedir(),
node20OrHigher: major >= 20,
};
fs.writeFileSync("env-report.json", JSON.stringify(report, null, 2));
console.log("환경 리포트를 생성했습니다: env-report.json");
console.log(report);
if (!report.node20OrHigher) {
console.log("❌ Node.js 20 이상이 필요합니다.");
} else {
console.log("✅ Node.js 버전 조건을 통과했습니다.");
}이제 실행합니다.
node check-env.mjs정상이라면 현재 운영체제, 아키텍처, 홈 디렉터리, Node 버전이 출력되고, 같은 폴더에 env-report.json 파일도 생깁니다. 아주 작은 실습이지만 의미가 있습니다. 이후 OpenCode가 어떤 홈 디렉터리를 기준으로 설정 파일을 읽을지 감을 잡는 데 도움이 되기 때문입니다.
실습 3: 작업용 폴더 만들어 보기
이제 실습용 폴더를 하나 준비해 둡니다.
mkdir opencode-openai-oauth-lab
cd opencode-openai-oauth-lab앞으로 책의 예제를 따라갈 때, 이렇게 비어 있는 실습 폴더 하나가 있으면 마음이 편합니다. 이미 진행 중인 회사 프로젝트에서 바로 실험하다가 설정 파일과 인증 흐름이 섞이면, 초보자는 문제를 추적하기가 훨씬 어려워집니다.
지금 단계에서 자주 걸리는 문제들
설치를 시작하기도 전에 막히는 원인은 대체로 몇 가지로 압축됩니다.
Node 버전이 낮다.
node -v가 20 미만이면 가장 먼저 해결해야 합니다.구독이 없다. ChatGPT Free 상태에서는 이 흐름이 이어지지 않습니다.1
사용 범위를 오해했다. 개인 개발용 흐름을 팀 서비스용처럼 생각하면 방향이 틀어집니다.1
운영체제 차이를 무시했다. 특히 Windows에서는 경로와 셸 문법을 한 번 더 확인하는 습관이 필요합니다.4
원격 환경인데 브라우저 인증을 로컬처럼 기대했다. SSH, WSL, 원격 세션에서는 수동 URL 붙여 넣기 가능성을 염두에 두면 훨씬 덜 당황합니다.5
여기서 중요한 건 "완벽한 환경"을 만드는 게 아닙니다. 문제가 생겼을 때 어디를 먼저 봐야 하는지 아는 것입니다. 그 감만 있어도 설치 과정이 훨씬 부드러워집니다.
이 장에서 기억할 한 줄 요약
OpenCode와 OpenAI OAuth 연동은 설치 명령어보다 사전 점검이 더 중요합니다. Node.js 20+, ChatGPT Plus/Pro, 운영체제별 경로 감각, 그리고 개인 개발용이라는 사용 범위를 먼저 이해하면, 뒤의 실습은 훨씬 덜 삐걱거립니다.
다음 장에서는 이제 본격적으로 OpenCode를 설치하고, 앞으로 만지게 될 기본 구조를 차근차근 익혀보겠습니다.
참고
1OpenCode Codex Auth Plugin 시작하기
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.