1. 왜 OpenCode에 OpenAI OAuth를 붙이는가

OpenCode에 OpenAI OAuth를 붙인다는 말은, 그냥 로그인 창 하나 더 띄운다는 뜻이 아닙니다. 초보자에게는 이 지점이 가장 헷갈립니다. OpenCode는 코딩을 도와주는 작업 공간이고, OpenAI OAuth는 ChatGPT 계정으로 신원을 확인하는 로그인 방식이며, Codex 백엔드는 실제로 코딩 요청을 처리하는 엔진입니다. 여기에 ChatGPT Plus 또는 Pro 구독은 그 엔진을 사용할 수 있는 이용권 역할을 합니다.¹²³

이 관계를 먼저 잡아두면, 나중에 플러그인을 설치하고 인증할 때도 왜 이런 설정이 필요한지 훨씬 덜 헷갈립니다. 반대로 이 그림 없이 시작하면, OpenCode가 모델인지, ChatGPT가 앱인지 API인지, OAuth가 API 키의 다른 이름인지 뒤엉키기 쉽습니다.

먼저 큰 그림부터 잡자

가장 쉬운 비유로 보면 이렇습니다.

즉, 우리가 하려는 일은 OpenCode라는 작업대 위에 OpenAI의 Codex 엔진을 연결하는 것입니다. 그런데 이 엔진은 아무나 바로 쓰게 해주지 않고, ChatGPT 로그인 기반의 인증을 요구합니다. 그래서 OAuth가 필요합니다. 그리고 OpenCode가 보내는 요청 형식과 Codex 백엔드가 기대하는 형식 사이에 차이가 있어서, 그 틈을 메우는 플러그인도 필요합니다.²³⁴

한 문장으로 정리하면 이렇습니다.

OpenCode에서 코딩 작업을 하되, 실제 두뇌는 OpenAI Codex를 쓰고, 그 접근 권한은 ChatGPT Plus/Pro 구독 계정의 OAuth 로그인으로 얻는다.

OpenCode는 모델이 아니라 무대다

초보자가 가장 많이 하는 착각은 OpenCode 자체를 AI 모델이라고 생각하는 것입니다. 하지만 OpenCode는 모델이 아닙니다. OpenCode는 여러 공급자의 모델을 연결해 쓰는 오픈소스 코딩 에이전트입니다. 공식 문서 기준으로 다양한 제공자를 지원하고, 필요한 방식으로 인증을 연결할 수 있습니다.¹⁵

쉽게 말해 OpenCode는 요리사가 아니라 주방입니다. 주방이 좋아도 불이 안 들어오면 요리가 안 되듯, OpenCode만 설치되어 있다고 해서 바로 코딩 AI가 동작하지는 않습니다. 실제로는 어떤 모델을 쓸지, 어떤 방식으로 인증할지, 그 모델과 OpenCode를 어떻게 이어 붙일지를 정해줘야 합니다.

그래서 이 책의 주제는 OpenCode 자체를 배우는 것에서 끝나지 않습니다. OpenCode에 OpenAI Codex 계열 모델을 연결해, 실제로 코드를 쓰고 읽고 수정하게 만드는 전체 경로를 익히는 것이 핵심입니다.

왜 API 키가 아니라 OAuth인가

OpenAI 쪽 Codex 사용 흐름에서는 로그인 방식이 중요합니다. OpenAI 개발자 문서에서는 Codex cloud를 사용할 때 ChatGPT로 로그인한다고 설명합니다.² 여기서 핵심은, 지금 우리가 다루는 방식이 전통적인 OpenAI Platform API 키 발급 방식과 다르다는 점입니다.

API 키 방식은 보통 platform.openai.com에서 키를 만들어 코드나 환경 변수에 넣어 씁니다. 반면 이번 책의 흐름은 ChatGPT 계정으로 브라우저 로그인해서 권한을 부여하는 OAuth 방식입니다. 이 차이를 이해해야 설치 단계에서 길을 잃지 않습니다.

이 방식이 매력적인 이유는 분명합니다.

• 이미 ChatGPT Plus 또는 Pro를 쓰고 있다면, 별도의 OpenAI Platform API 크레딧 중심 흐름이 아니라 구독 기반으로 Codex 접근을 구성할 수 있습니다.

• 플러그인이 OAuth 흐름을 바탕으로 인증을 처리하므로, 초보자도 API 키 관리보다 덜 낯설게 느낄 수 있습니다.

• OpenCode 안에서 코딩 작업을 하면서도 인증은 ChatGPT 계정 기준으로 묶을 수 있습니다.³⁴

다만 여기에는 중요한 선이 하나 있습니다. 이 플러그인 문서들은 공통적으로 개인 개발 용도를 강조합니다. 즉, 내 개인 작업이나 학습, 개인 프로젝트에는 잘 맞지만, 다중 사용자 서비스나 상업용 API 재판매 같은 용도에는 적합하지 않습니다. 그런 경우에는 OpenAI Platform API가 정석입니다.³⁴

왜 Codex 백엔드라는 말이 자꾸 나올까

초보자 입장에서는 ChatGPT를 쓰는데 왜 또 Codex라는 단어가 나오는지 의아할 수 있습니다. 여기서 Codex는 단순히 옛날 코드 모델 이름을 말하는 것이 아니라, 코딩 작업에 맞게 동작하는 OpenAI 쪽 백엔드 경로와 모델 계열을 가리키는 맥락으로 이해하면 편합니다.

플러그인 문서를 보면 OpenCode에서 올라오는 요청은 그대로 Codex 백엔드로 보내지지 않습니다. 중간에서 요청을 다듬습니다. 예를 들어 모델 이름을 정리하고, 메시지 형식을 맞추고, OpenCode가 내부적으로 쓰는 일부 항목을 제거한 뒤 Codex 백엔드가 받기 좋은 형태로 바꿉니다.⁴

왜 이렇게 복잡하냐고요? 서로 쓰는 말이 조금 다르기 때문입니다. OpenCode는 OpenCode 나름의 형식이 있고, Codex 백엔드는 Codex 백엔드 나름의 요구사항이 있습니다. 마치 한국 콘센트에 해외 전자기기를 꽂으려면 어댑터가 필요한 것과 비슷합니다. 플러그인은 바로 그 어댑터입니다.

그래서 설치 과정에서 플러그인을 넣는 행위는 단순한 부가기능 추가가 아닙니다. OpenCode와 Codex 백엔드를 실제로 대화하게 만드는 핵심 연결 작업입니다.

왜 설정 파일이 중요한가

이 책에서 설정 파일을 꽤 진지하게 다루는 이유도 여기 있습니다. 단순히 모델 이름 한 줄 적는 것으로 끝나지 않기 때문입니다.

플러그인 아키텍처 문서를 보면 ChatGPT 백엔드에서는 store: false가 사실상 전제처럼 다뤄집니다. 즉, 서버 쪽에 대화를 저장해두고 이어가는 방식이 아니라, 매 요청마다 이전 대화와 도구 실행 기록을 함께 보내는 쪽으로 맞춰야 합니다. 이때 메시지 ID를 제거하고, OpenCode 쪽의 일부 SDK 전용 항목도 걸러내야 정상 동작합니다.⁴

이 부분을 초보자 눈높이로 바꾸면 이렇습니다.

보통 사람은 대화를 이어갈 때 방금 한 말을 기억합니다. 그런데 이 경로에서는 서버가 그 기억을 오래 들고 있지 않는 쪽이 기본입니다. 그래서 클라이언트 쪽, 즉 OpenCode와 플러그인이 매번 중요한 대화 기록을 다시 챙겨 보내야 합니다. 플러그인은 여기에 더해 reasoning.encrypted_content 같은 정보를 포함해 추론 맥락도 이어가도록 설계되어 있습니다.⁴

바로 그래서 설정 파일이 중요합니다. 설정 파일은 단순 취향 설정이 아니라, 다음과 같은 것을 묶어두는 작업 지침서입니다.

• 어떤 모델군을 쓸지

• 추론 강도를 어느 정도로 둘지

• 출력 길이를 어느 정도로 둘지

• 어떤 추가 필드를 포함할지

• Codex 백엔드 요구사항에 맞게 어떤 동작 방식을 기본으로 둘지

즉, 설정 파일은 자동차의 네비게이션이 아니라 변속기와 계기판에 가깝습니다. 잘 넣으면 부드럽게 달리고, 대충 넣으면 시동은 걸려도 이상하게 덜컹거릴 수 있습니다.

플러그인 문서가 GPT-5.x 계열에서 전체 설정을 권장하는 이유도 여기에 있습니다. 그냥 최소 설정으로 얼렁뚱땅 붙이는 것보다, 검증된 전체 설정으로 시작하는 편이 훨씬 덜 흔들립니다.⁶

ChatGPT Plus/Pro 구독과 OpenCode 사용 방식의 관계

이제 가장 실용적인 질문으로 가보겠습니다.

그럼 결국 돈은 어디에서 나가고, 무엇을 쓰게 되는가?

이번 책의 흐름은 구독 기반 사용에 가깝습니다. 즉, 핵심 출발점은 ChatGPT Plus 또는 Pro 구독입니다. 플러그인 문서와 시작 가이드는 Codex 접근을 위해 활성 구독이 필요하다고 안내합니다.³⁶

이 구조를 이해하면 마음이 편해집니다.

• OpenCode는 오픈소스 작업 환경이다.

• OpenAI OAuth는 내 ChatGPT 계정 권한을 확인하는 문이다.

• ChatGPT Plus/Pro는 그 문을 통과할 수 있는 구독 상태다.

• 통과한 뒤에는 Codex 백엔드가 실제 코딩 요청을 처리한다.

즉, 우리는 OpenCode를 쓰고 있지만, 실제 계산은 OpenAI 쪽 Codex 능력으로 하고 있는 셈입니다. OpenCode는 조종석이고, Codex는 엔진이며, OAuth는 시동키입니다.

이 방식이 특히 잘 맞는 사람

이 방식은 모든 상황의 만능 답은 아니지만, 아래 같은 사람에게는 꽤 잘 맞습니다.

• 이미 ChatGPT Plus 또는 Pro를 구독 중인 개인 개발자

• 터미널 중심으로 코딩 보조를 받고 싶은 사람

• API 키 발급과 과금 관리를 최대한 단순하게 가져가고 싶은 사람

• 코드 생성, 수정, 리팩터링, 파일 작업 같은 코딩 중심 사용이 많은 사람

반대로 고객에게 서비스를 제공하는 백엔드, 팀 단위 다중 사용자 제품, 사용량을 고객별로 세밀하게 추적해야 하는 상용 서비스라면 이 흐름보다 OpenAI Platform API가 더 적합합니다. 플러그인 문서도 그 점을 분명히 선을 그어 설명합니다.³⁶

초보자 미니 실습: 앞으로 하게 될 흐름을 눈으로 먼저 익히기

아직 모든 도구가 설치되지 않았더라도 괜찮습니다. 아래 명령어는 이번 책에서 완성하게 될 흐름을 한눈에 보여주는 예시입니다.

# OpenCode가 설치되어 있는지 확인
opencode --version

# OpenCode용 Codex OAuth 플러그인 설치
npx -y opencode-openai-codex-auth@latest

# ChatGPT 계정으로 로그인
opencode auth login

# 첫 번째 간단한 실행 예시
opencode run 'write hello world to test.txt' --model=openai/gpt-5.2 --variant=medium

이 네 줄이 의미하는 바를 지금 단계에서 가볍게 읽어보면 좋습니다.

첫 줄은 작업대가 있는지 확인하는 단계입니다. 둘째 줄은 OpenCode와 Codex 백엔드를 이어줄 어댑터를 설치하는 단계입니다. 셋째 줄은 ChatGPT 계정 권한으로 문을 여는 단계입니다. 넷째 줄은 실제로 코딩 작업을 시키는 단계입니다.³⁶

여기서 특히 눈여겨볼 부분은 마지막 줄의 --model=openai/... 입니다. 초보자는 이걸 보고 종종 OpenAI API 키를 넣어야 하나 생각하는데, 이번 흐름에서는 핵심이 API 키가 아니라 OpenAI provider를 OAuth 기반으로 쓰도록 구성하는 것입니다. 즉, 이름은 openai/... 이지만 인증 방식은 우리가 익숙한 API 키 발급 흐름과 같지 않습니다.

초보자가 가장 자주 헷갈리는 포인트 네 가지

설치 전에 이것만 분명히 기억해도 절반은 성공입니다.

• OpenCode는 AI 모델이 아니라, 모델을 불러다 쓰는 코딩 에이전트 환경이다.

• ChatGPT Plus/Pro 구독은 웹 채팅 전용이 아니라, Codex OAuth 경로에서 사용 권한의 기반이 된다.

• OAuth 로그인은 API 키 입력과 다른 절차다. 브라우저에서 계정 인증을 거친다.

• 플러그인과 전체 설정은 옵션이 아니라, OpenCode 요청을 Codex 백엔드에 맞게 번역하고 안정화하는 핵심 장치다.

이 네 가지를 머릿속에 넣고 나면, 이후의 설치 화면과 인증 화면이 훨씬 덜 무섭게 느껴집니다. 괜히 복잡한 게 아니라, 각각 다 맡은 역할이 있어서 나뉘어 있는 것입니다.

정리

OpenCode에 OpenAI OAuth를 붙이는 이유는 단순합니다. 좋은 작업대인 OpenCode 위에서, ChatGPT 구독 기반의 Codex 코딩 능력을 안정적으로 쓰기 위해서입니다.

하지만 그 단순한 목표를 실제로 이루려면 관계를 정확히 알아야 합니다. OpenCode는 무대, OAuth는 로그인, Plus/Pro는 이용권, Codex 백엔드는 엔진, 플러그인은 통역사입니다. 이 구조를 이해하면 이후의 설치, 설정, 로그인, 첫 실행이 모두 하나의 흐름으로 이어집니다.

헷갈림은 대개 기능이 많아서 생기지 않습니다. 누가 무슨 역할을 하는지 모를 때 생깁니다. 지금 이 장에서 잡아야 하는 것은 바로 그 역할 분담입니다.

참고

¹OpenCode 공식 소개

²OpenAI Codex 인증 문서

³opencode-openai-codex-auth GitHub 저장소

⁴OpenCode Codex Auth Plugin 아키텍처 문서

⁵OpenCode 공급자 문서

⁶OpenCode Codex Auth Plugin 시작 가이드