4. opencode-openai-codex-auth 플러그인 설치 실습

이제 진짜로 플러그인을 붙여 볼 차례입니다. 그런데 이번 장의 핵심은 단순히 명령어 한 줄을 복붙하는 데 있지 않습니다. 원클릭 설치가 편할수록, 무엇이 바뀌는지 더 잘 알아야 안전합니다. 설치 스크립트가 설정 파일을 어디에 쓰는지, 백업은 어떻게 남기는지, 왜 캐시를 비우는지 이해하고 나면 나중에 문제를 만나도 훨씬 덜 당황합니다.

이번 장에서는 최신 OpenCode와 레거시 OpenCode를 나눠서 설치하고, 설치 후에 실제로 어떤 파일과 캐시가 바뀌는지 눈으로 확인해 보겠습니다. 다음 장에서 설정 파일 내용을 깊게 다룰 예정이므로, 여기서는 설치 흐름과 변경 지점 파악에 집중하겠습니다.

이 플러그인은 정확히 무엇을 붙여 주나

opencode-openai-codex-auth는 OpenCode가 ChatGPT Plus 또는 Pro 구독의 OAuth 인증을 이용해 Codex 계열 모델에 접근할 수 있도록 연결해 주는 플러그인입니다. 공식 안내에서도 이 플러그인은 개인 개발용을 전제로 하며, 상업 서비스나 다중 사용자 서비스, API 재판매 용도로 쓰는 것은 대상이 아니라고 분명히 밝히고 있습니다.¹²

쉽게 말하면 이런 구조입니다.

OpenCode가 앞에서 일하고, 이 플러그인이 중간에서 요청을 다듬고, 뒤쪽에서는 ChatGPT OAuth 기반 Codex 백엔드와 통신합니다.² 그래서 겉보기에는 "OpenCode에서 OpenAI 모델을 쓰는 것"처럼 보여도, 실제로는 플러그인이 통역사 역할을 하고 있는 셈입니다.

먼저 갈림길부터: 최신 버전인가, 레거시 버전인가

설치 명령은 비슷하지만, OpenCode 버전에 따라 써야 하는 트랙이 다릅니다. 공식 문서는 OpenCode v1.0.210+를 현대식(Modern), v1.0.209 이하를 레거시(Legacy)로 구분합니다.²³

최신 OpenCode라면 기본 설치 명령을 쓰면 됩니다.

npx -y opencode-openai-codex-auth@latest

레거시 OpenCode라면 --legacy 플래그를 붙입니다.

npx -y opencode-openai-codex-auth@latest --legacy

헷갈리면 먼저 버전부터 확인해 주세요.

opencode --version

아주 단순하게 기억하면 됩니다.

여기서 말하는 variant는 최신 OpenCode가 모델과 세부 변형을 조금 더 깔끔하게 다루는 방식이라고 생각하면 됩니다. 너무 어렵게 볼 필요는 없습니다. 최신이면 기본 설치, 오래된 버전이면 --legacy만 먼저 기억해도 충분합니다.²

설치 전에 다시 점검할 것

이번 플러그인은 아무 데서나 마법처럼 튀어나오지 않습니다. 최소한 아래 조건은 갖춰져 있어야 합니다.¹

• OpenCode가 이미 설치되어 있을 것

• ChatGPT Plus 또는 Pro 구독이 있을 것

• Node.js 20 이상이 준비되어 있을 것

그리고 하나 더 있습니다. 이 플러그인은 OpenCode가 npm 패키지 플러그인을 자동으로 설치하는 구조를 활용합니다. 즉, 보통 여러분이 프로젝트 폴더 안에서 npm install opencode-openai-codex-auth를 직접 할 필요는 없습니다. OpenCode는 설정 파일의 plugin 항목을 읽고, 필요한 npm 플러그인을 시작 시 자동으로 설치하고 캐시에 보관합니다.⁴

이 부분을 이해하면 "어? 내가 프로젝트에 설치한 기억이 없는데 왜 플러그인이 동작하지?" 같은 의문이 풀립니다. 플러그인은 프로젝트의 node_modules가 아니라 OpenCode 쪽 캐시와 설정 흐름을 타고 들어옵니다.

실습 1: 최신 OpenCode에 플러그인 설치하기

먼저 최신 OpenCode 기준으로 진행해 보겠습니다. 터미널에서 아래 명령을 실행합니다.

npx -y opencode-openai-codex-auth@latest

이 명령은 설치이면서 동시에 업데이트 명령이기도 합니다. 이미 설치한 적이 있어도 같은 명령을 다시 실행하면 최신 상태로 갱신하는 흐름입니다.¹²

실행이 끝났다고 해서 바로 눈에 보이는 변화가 많은 것은 아닙니다. 그래서 초보자는 여기서 자주 속습니다. "분명 설치했는데 뭐가 달라졌지?"라는 느낌이 들기 쉽거든요. 하지만 실제로는 뒤에서 몇 가지 중요한 작업이 진행됩니다.

설치 스크립트는 뒤에서 무엇을 할까

공식 안내와 설치 설명을 종합하면, 설치 스크립트는 대략 다음 순서로 동작합니다.¹⁵

1. OpenCode 전역 설정 파일 위치를 찾습니다.

2. 기존 설정 파일을 백업합니다.

3. 현재 OpenCode 버전에 맞는 공식 구성 파일을 반영합니다.

4. OpenCode 플러그인 캐시를 정리해 최신 플러그인이 다시 설치되도록 합니다.

조금 더 사람 말로 풀어 보겠습니다.

설정 파일 위치 찾기

설치기는 보통 전역 설정 파일인 ~/.config/opencode/opencode.jsonc를 우선 사용하고, 상황에 따라 .json으로 폴백합니다.¹ 즉, 여러분이 프로젝트마다 따로 설치하는 것이 아니라 사용자 전역 설정을 먼저 손본다고 생각하면 됩니다.

기존 설정 백업

설치기는 기존 설정을 그냥 덮어쓰지 않고 백업을 남깁니다. 설치 설명에는 타임스탬프가 붙은 백업 파일 예시도 소개되어 있습니다.⁵ 이게 왜 중요하냐면, 뭔가 마음에 들지 않을 때 되돌아갈 발판이 생기기 때문입니다. 설치 스크립트가 무작정 밀어붙이는 스타일이 아니라, 최소한의 안전벨트는 채워 주는 셈입니다.

버전에 맞는 설정 반영

최신 버전에는 modern 설정, 오래된 버전에는 legacy 설정을 넣습니다.²⁵ 이때 중요한 점이 하나 있습니다. GPT-5.x 계열은 최소 설정만 넣는 방식이 공식적으로 지원되지 않습니다. 문서에서는 full configuration만 지원하며, 너무 짧은 최소 설정은 예측 불가능하게 실패할 수 있다고 강조합니다.¹³

즉, "간단해 보여서 몇 줄만 남기자"는 유혹은 잠깐 참는 편이 좋습니다. 다음 장에서 보겠지만, 이 플러그인은 모델 메타데이터와 옵션을 꽤 꼼꼼하게 요구합니다.

캐시 정리

OpenCode는 npm 플러그인을 캐시에 보관해 두었다가 재사용합니다.⁴ 그래서 캐시가 꼬이면 예전 플러그인이 계속 남아 있을 수 있습니다. 설치 스크립트가 캐시를 정리하는 이유는 아주 단순합니다. "이번에는 진짜 최신 플러그인으로 다시 받아라"라고 OpenCode에 말해 주는 것입니다.¹⁵

OpenCode 공식 문서도 문제 해결 단계에서 ~/.cache/opencode 아래 캐시를 지워 재설치를 유도하는 방식을 안내합니다.⁶ 즉, 설치 스크립트의 캐시 정리는 괜한 소동이 아니라, 실제로 자주 쓰는 안정화 방법입니다.

실습 2: 설치 후 무엇이 바뀌었는지 확인하기

이제 설치가 끝났다면, 정말로 파일이 바뀌었는지 확인해 보겠습니다. 이번 실습은 "설치 성공"보다 더 중요합니다. 어떤 파일이 생성되고 어떤 파일이 백업되었는지 보는 습관이 생기면, 앞으로 플러그인 설치가 훨씬 덜 무섭습니다.

아래 스크립트를 inspect-codex-auth-install.mjs라는 이름으로 저장하세요.

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

const home = os.homedir();
const configDir = path.join(home, ".config", "opencode");
const configCandidates = [
  path.join(configDir, "opencode.jsonc"),
  path.join(configDir, "opencode.json"),
];
const cacheDir = path.join(home, ".cache", "opencode");

const configPath = configCandidates.find((file) => fs.existsSync(file));
const backups = fs.existsSync(configDir)
  ? fs.readdirSync(configDir).filter((name) => name.includes("backup"))
  : [];

console.log("[1] 설정 디렉터리:", configDir);
console.log("[2] 사용 중인 설정 파일:", configPath ?? "없음");
console.log("[3] 백업 파일 수:", backups.length);

if (backups.length > 0) {
  console.log("[4] 백업 파일 목록:");
  for (const file of backups) {
    console.log("   -", file);
  }
}

if (configPath) {
  const content = fs.readFileSync(configPath, "utf-8");
  console.log(
    "[5] 플러그인 등록 여부:",
    content.includes("opencode-openai-codex-auth") ? "예" : "아니오"
  );
  console.log(
    "[6] openai provider 섹션 존재 여부:",
    content.includes('"openai"') ? "예" : "아니오"
  );
}

console.log(
  "[7] OpenCode 캐시 디렉터리 존재 여부:",
  fs.existsSync(cacheDir) ? "예" : "아니오"
);

실행합니다.

node inspect-codex-auth-install.mjs

정상이라면 다음과 비슷한 감각의 결과가 나옵니다.

• 설정 파일이 opencode.jsonc 또는 opencode.json로 잡힌다.

• 백업 파일이 하나 이상 보인다.

• 설정 안에 opencode-openai-codex-auth 문자열이 들어 있다.

• OpenCode 캐시 디렉터리가 존재한다.

이 실습이 좋은 이유는 간단합니다. "설치가 됐다더라"가 아니라, 설치 결과를 내 눈으로 검증하게 해 주기 때문입니다.

실습 3: 최신과 레거시 설치 결과를 구분해서 이해하기

이번에는 두 설치 방식의 차이를 머릿속에 정리해 보겠습니다. 실제 차이는 설정 구조와 모델 호출 방식에 있습니다.²

최신 OpenCode에서는 보통 이런 식으로 모델과 variant를 나눠 씁니다.

opencode run "write hello world to test.txt" --model=openai/gpt-5.2 --variant=medium

레거시 OpenCode에서는 variant가 모델 이름 안으로 들어갑니다.

opencode run "write hello world to test.txt" --model=openai/gpt-5.2-medium

아직 이 장에서는 로그인 전일 수 있으니, 위 명령을 바로 성공 테스트로 쓰기보다는 "모델 이름 체계가 이렇게 다르구나" 정도로 받아들이면 됩니다. 실제 첫 실행 성공은 뒤 챕터에서 인증까지 마친 뒤 해보겠습니다.

레거시 OpenCode에 설치할 때는 이렇게 한다

오래된 OpenCode를 쓰고 있다면 설치는 아래처럼 합니다.

npx -y opencode-openai-codex-auth@latest --legacy

이 명령 역시 설치기이자 업데이트 명령입니다.²³ 설치 원리는 최신 버전과 거의 같지만, 반영되는 설정이 레거시용이라는 점이 다릅니다. 즉, 설치기는 "그냥 플러그인 하나 더하기"가 아니라 내 OpenCode 세대에 맞는 설정 묶음을 넣는 작업까지 같이 수행합니다.⁵

초보자 입장에서는 이 차이를 너무 복잡하게 외울 필요는 없습니다. 다만 아래 한 줄은 꼭 기억해 주세요.

최신 OpenCode 설정을 레거시에 억지로 쓰면, 모델 이름이나 variant 체계가 어긋나서 나중에 이상한 오류처럼 보일 수 있습니다.

설치 뒤에 꼭 확인할 두 가지

설치가 끝났다면 적어도 두 가지는 확인해 두는 편이 좋습니다.

첫째, 설정 파일 안에 플러그인 이름이 들어갔는지 봅니다. 둘째, OpenCode를 다시 실행했을 때 플러그인 캐시가 새로 정리되며 필요한 패키지를 다시 받을 준비가 되어 있는지 확인합니다.⁴⁶

조금 더 가볍게 점검하고 싶다면 아래 명령도 도움이 됩니다.

opencode models

이 명령은 현재 구성된 provider에서 사용할 수 있는 모델 목록을 보여주는 OpenCode 기본 명령입니다.⁷ 인증 전이라도 설정이 잘 들어갔다면, 이후 모델 선택 흐름을 점검하는 데 도움이 됩니다.

"원클릭 설치"를 안전하게 다루는 습관

초보자일수록 원클릭 설치를 좋아합니다. 아주 좋은 습관입니다. 다만 여기에 한 가지만 더 붙이면 더 안전해집니다.

설치 명령을 실행하기 전과 후에 아래 세 가지만 확인해 보세요.

• 어떤 설정 파일이 바뀌는가

• 백업 파일이 남았는가

• 캐시가 새로고침될 조건이 갖춰졌는가

이 세 가지를 확인하는 사람은 나중에 문제가 생겨도 훨씬 침착합니다. 왜냐하면 "도대체 어디가 바뀌었지?"에서 시작하지 않아도 되기 때문입니다. 이미 바뀐 지점을 알고 있으니까요.

문제가 생기면 어떻게 되돌릴까

설치기가 백업을 남기는 이유는 바로 이 순간을 위해서입니다.⁵ 설치 후 OpenCode가 이상하게 동작하거나, 설정을 다시 정리하고 싶다면 먼저 백업 파일이 있는지 확인하세요. 그리고 필요하면 백업 내용을 현재 설정 파일로 되돌린 뒤, OpenCode 캐시를 정리하고 다시 시작하는 흐름으로 접근하면 됩니다.⁶

즉, 복구의 기본 순서는 보통 이렇습니다.

1. 백업 파일 확인

2. 현재 설정과 비교

3. 필요 시 백업으로 원복

4. 캐시 재정리 후 OpenCode 재실행

이 흐름만 익혀도 플러그인 설치는 훨씬 덜 위협적입니다. 컴퓨터는 생각보다 정직해서, 바꾼 파일과 캐시만 알면 상당수 문제를 추적할 수 있습니다.

이번 장에서 꼭 기억할 것

이번 장의 핵심은 설치 명령 그 자체보다, 설치 스크립트의 행동을 이해하는 것입니다.

최신 OpenCode는 기본 설치 명령을, 레거시 OpenCode는 --legacy를 사용합니다.²³ 설치 스크립트는 전역 설정 파일을 찾고, 기존 파일을 백업하고, 버전에 맞는 공식 전체 구성을 반영하고, 플러그인 캐시를 비워 새 버전이 다시 설치되게 합니다.¹⁵ 그리고 OpenCode는 원래 npm 플러그인을 자동 설치하고 캐시해 두는 구조이므로, 이 캐시 정리는 매우 현실적인 안전장치입니다.⁴⁶

이제 플러그인은 들어왔습니다. 다음 장에서는 "그래서 설정 파일 안에 정확히 무엇을 넣어야 하는가"를 본격적으로 다루겠습니다. 거기서 modern과 legacy의 full config를 제대로 읽는 법까지 깔끔하게 정리해 보겠습니다.

참고

¹Getting Started  OpenCode Codex Auth Plugin

²GitHub - numman-ali/opencode-openai-codex-auth

³opencode-openai-codex-auth/docs/getting-started.md at main

⁴플러그인  OpenCode

⁵Getting Started  numman-ali/opencode-openai-codex-auth  DeepWiki

⁶문제 해결  OpenCode

⁷CLI  OpenCode