6. OpenAI OAuth 로그인과 인증 흐름 이해하기

설정 파일까지 잘 넣었다면, 이제 드디어 문이 열리는 순간입니다. 그 문이 바로 opencode auth login입니다.

초보자에게 이 단계가 특히 헷갈리는 이유는 간단합니다. 터미널에서 명령을 쳤는데 갑자기 브라우저가 열리고, 로그인 화면이 나오고, 어떤 때는 자동으로 돌아오고, 어떤 때는 URL을 직접 붙여 넣으라고 하기 때문입니다. 처음 겪으면 "내가 뭘 잘못했나?" 싶기 쉽습니다.

하지만 구조를 알고 보면 생각보다 단순합니다. 이번 장의 핵심은 딱 이것입니다.

OpenCode는 OpenAI에 비밀번호를 직접 보내는 것이 아니라, 브라우저를 통해 OAuth 인증을 받고, 그 결과를 이후 요청에 재사용할 수 있도록 로컬 인증 저장소에 보관한다는 점입니다.¹²³

이 흐름만 머릿속에 들어오면 로컬 PC는 물론이고, SSH, WSL, 원격 서버에서도 훨씬 덜 당황하게 됩니다.

인증 흐름을 한 장면으로 먼저 보기

먼저 큰 그림부터 보겠습니다.

1. 터미널에서 opencode auth login을 실행합니다.³

2. OpenCode와 플러그인이 로그인 절차를 준비하고, 브라우저에서 열 수 있는 인증 URL을 만듭니다.²

3. 브라우저에서 ChatGPT Plus 또는 Pro 계정으로 로그인하고 권한을 승인합니다.¹²

4. 인증이 끝나면 브라우저가 로컬 콜백 주소로 돌아오거나, 원격 환경이라면 그 전체 URL을 복사해 터미널에 붙여 넣습니다.²⁴

5. OpenCode는 인증 결과를 로컬에 저장하고, 이후 실제 모델 요청 때 재사용합니다.³⁵

6. 이후 토큰이 만료되면 가능한 경우 자동 갱신을 시도합니다.⁵

쉽게 비유하면 이렇습니다. OpenCode는 열쇠를 직접 만드는 도구가 아니라 출입증을 받아 보관하는 관리자에 가깝습니다. 브라우저에서 본인 확인을 마치면, OpenCode가 그 출입 정보를 보관했다가 다음부터 꺼내 쓰는 식입니다.

실습 1: 가장 기본적인 로그인 실행

가장 먼저 해볼 일은 아주 단순합니다.

opencode auth login

그러면 보통 provider를 고르는 화면이 나오고, 여기서 OpenAI를 선택합니다.³

그다음 로그인 방식이 보이면 일반적인 로컬 환경에서는 브라우저 기반 ChatGPT Plus/Pro 로그인을 고르면 됩니다. 플러그인 문서도 설치 후 기본 흐름을 opencode auth login으로 안내하고 있고, SSH·WSL·원격 환경이라면 Manual URL Paste 방식을 고르라고 설명합니다.²⁴

정상적으로 진행되면 브라우저가 열리고 로그인 및 승인 화면이 나옵니다. 여기서 중요한 점은, 이 단계는 OpenCode 안의 작은 팝업이 아니라 브라우저에서 진행되는 공식 인증 흐름이라는 것입니다.

인증이 끝났다면 저장 여부를 이렇게 확인할 수 있습니다.

opencode auth ls

또는 긴 이름으로 써도 됩니다.

opencode auth list

이 명령은 저장된 provider 인증 정보를 확인할 때 쓰입니다.³

브라우저에서 실제로 무슨 일이 일어나는가

이 부분이 이해되면 인증이 훨씬 덜 무섭습니다.

OpenAI OAuth 로그인은 보통 다음 흐름으로 생각하면 됩니다.

먼저 OpenCode 쪽이 로그인 요청을 준비합니다. 이때 그냥 "나 로그인할래요" 하고 끝나지 않습니다. 중간에 PKCE라는 안전장치가 함께 사용됩니다. PKCE는 쉽게 말해 "중간에 누가 인증 코드를 가로채도 함부로 써먹기 어렵게 만드는 확인 장치"입니다.¹

그다음 브라우저에서 사용자가 실제 계정 로그인을 하고 권한을 승인합니다. 그러면 OpenAI는 곧바로 비밀 토큰을 브라우저에 뿌리는 대신, 짧게 쓸 수 있는 authorization code를 돌려줍니다.¹

마지막으로 OpenCode 쪽이 그 코드를 바탕으로 실제 사용에 필요한 인증 정보를 받아 저장합니다.¹⁵

정리하면 이렇습니다.

• 브라우저는 사람 확인을 맡습니다.

• OpenCode는 코드 교환과 인증 정보 보관을 맡습니다.

• 이후 플러그인은 인증 정보를 사용하고, 필요하면 갱신합니다.⁵

이렇게 역할이 나뉘기 때문에, 브라우저가 열리는 것이 이상한 현상이 아니라 오히려 정상입니다.

실습 2: 로컬 PC에서 자동 콜백으로 로그인하기

로컬 macOS, Linux, Windows처럼 OpenCode를 실행한 컴퓨터와 브라우저를 여는 컴퓨터가 같은 경우에는 자동 콜백 방식이 가장 편합니다.

일반적인 순서는 이렇습니다.

opencode auth login

이후 브라우저가 열리고 인증을 마치면, 브라우저가 로컬 콜백 주소로 돌아옵니다. 플러그인 문서에서는 이 흐름에서 localhost:1455 포트를 기준으로 설명합니다.⁴

즉, 내부적으로는 이런 느낌입니다.

터미널 → 브라우저 열기 → OpenAI 로그인 → localhost:1455로 복귀 → 인증 저장

여기서 한 가지 알아둘 점이 있습니다. 이미 다른 프로그램이 같은 포트를 쓰고 있으면 자동 콜백이 꼬일 수 있습니다. 플러그인 문서에서는 특히 공식 Codex CLI가 동시에 실행 중이면 둘 다 1455 포트를 쓰는 충돌이 생길 수 있으니 확인해 보라고 안내합니다.⁴

브라우저가 자동으로 열리지 않아도 너무 놀랄 필요는 없습니다. 인증 URL은 보통 터미널에도 표시되므로, 그 URL을 복사해서 직접 브라우저에 붙여 넣어 진행할 수 있습니다.⁴

실습 3: SSH, WSL, 원격 서버에서는 Manual URL Paste가 왜 중요한가

이 장의 진짜 핵심이 여기 있습니다.

초보자가 SSH나 WSL에서 가장 많이 헷갈리는 부분은 이겁니다.

OpenCode는 원격 환경에서 실행 중인데, 브라우저는 내 로컬 컴퓨터에서 열린다는 점입니다.

예를 들어 이런 상황을 떠올려 보세요.

• 회사 서버에 SSH로 접속해 있습니다.

• 그 서버에서 opencode auth login을 실행했습니다.

• 인증 URL은 내 노트북 브라우저에서 엽니다.

• 로그인은 잘 됐는데, 마지막 콜백은 내 노트북 주소창으로 돌아옵니다.

• 그런데 OpenCode는 서버 쪽 터미널에서 기다리고 있습니다.

이때 자동 복귀가 안 되는 것은 자연스러운 일입니다. 브라우저와 터미널이 같은 컴퓨터에 있지 않기 때문입니다.

그래서 플러그인 문서는 이런 환경에서 ChatGPT Plus/Pro (Manual URL Paste) 방식을 쓰라고 안내합니다.²⁴

절차는 다음과 같습니다.

1. 원격 터미널에서 opencode auth login 실행

2. 로그인 방식에서 Manual URL Paste 선택

3. 표시된 인증 URL을 로컬 브라우저에서 열기

4. 로그인과 권한 승인 완료

5. 브라우저 주소창에 최종적으로 나타난 전체 redirect URL을 복사

6. 그 URL 전체를 원격 터미널에 붙여 넣기²⁴

여기서 중요한 포인트는 코드 일부만 복사하지 말고 전체 URL을 붙여 넣는 것입니다.²⁴

예를 들면 이런 식입니다.

http://127.0.0.1:1455/auth/callback?code=...&state=...

실제 값은 훨씬 길겠지만, 핵심은 code만 떼어내는 게 아니라 주소창 전체 문자열을 넘기는 것입니다.

이 방식은 처음엔 조금 원시적으로 보여도 아주 강력합니다. 자동 복귀가 안 되는 환경에서도 브라우저 인증 결과를 안전하게 터미널로 전달할 수 있기 때문입니다.

저장되는 것은 비밀번호가 아니라 인증 토큰이다

로그인이 끝나면 OpenCode는 provider 인증 정보를 로컬 저장소에 보관합니다. OpenCode 공식 문서는 인증 정보가 일반적으로 ~/.local/share/opencode/auth.json에 저장된다고 설명합니다.³

여기서 초보자가 기억해야 할 핵심은 구조의 세부 필드가 아니라 무엇이 저장되느냐입니다.

• 로그인 비밀번호 자체를 저장하는 것은 아닙니다.

• 이후 요청에 쓸 인증 토큰과 관련 정보가 저장됩니다.

• 그래서 한 번 로그인에 성공하면, 매번 브라우저를 다시 열지 않아도 되는 것입니다.¹³⁵

이 파일이나 저장소는 민감합니다. API 키와 비슷한 수준의 인증 정보라고 생각하는 편이 안전합니다. Git에 커밋하거나, 메신저로 보내거나, 화면 공유 중 그대로 노출하는 일은 피하는 것이 좋습니다.

코드 실습: 저장 여부만 안전하게 확인하기

초보자에게 추천하는 확인 방식은 "토큰 값을 출력하지 않고, 저장 여부만 보는 것"입니다.

아래 코드를 check-auth-file.mjs로 저장해 보세요.

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

const home = os.homedir();
const authPath = path.join(home, ".local", "share", "opencode", "auth.json");

if (!fs.existsSync(authPath)) {
  console.log("auth.json 파일을 찾지 못했습니다.");
  process.exit(1);
}

console.log("auth.json 파일이 존재합니다.");
console.log("파일 크기:", fs.statSync(authPath).size, "bytes");
console.log("민감한 내용은 직접 출력하지 않는 편이 안전합니다.");

실행은 이렇게 합니다.

node check-auth-file.mjs

이 스크립트의 장점은 두 가지입니다. 첫째, 인증 저장소가 실제로 생겼는지 확인할 수 있습니다. 둘째, 민감한 토큰 문자열 자체는 출력하지 않아서 실수로 복사·노출할 위험을 줄일 수 있습니다.

Windows에서도 OpenCode 공식 문서는 같은 저장소가 사용자 홈 아래 .local\share\opencode 계열에 생성된다고 안내합니다.³

자동 갱신은 어떻게 동작하는가

이제 많은 사람이 좋아하는 부분입니다. 로그인을 매번 다시 하지 않아도 되는 이유 말입니다.

플러그인 문서에 따르면, 이 플러그인은 요청을 보내기 전에 현재 인증 상태를 확인하고, 필요하면 refresh 흐름으로 새 access token을 받아오는 구조를 포함합니다.⁵

즉, 내부적으로는 이런 순서입니다.

1. 모델 요청 직전 현재 access token 상태 확인

2. 아직 유효하면 그대로 사용

3. 만료됐거나 더 이상 유효하지 않으면 refresh 흐름 시도

4. 새 인증 정보 저장

5. 그다음 실제 요청 전송⁵

사용자 입장에서는 보통 아무 일도 안 일어난 것처럼 느껴집니다. 그냥 어제 로그인한 상태로 오늘도 이어서 쓰는 것처럼 보입니다. 하지만 뒤에서는 조용히 토큰 점검과 갱신이 돌아가고 있는 셈입니다.

자동 갱신이 실패하면 어떻게 해야 하나

자동 갱신은 편리하지만 만능은 아닙니다. 계정 상태가 바뀌었거나, 저장된 인증 정보가 오래됐거나, 네트워크가 꼬였거나, 토큰이 무효가 되었을 수 있습니다. 플러그인 트러블슈팅 문서도 인증 문제의 기본 처방으로 다시 opencode auth login을 실행해 재인증하라고 안내합니다.⁴⁵

아주 실용적으로 정리하면 이렇습니다.

• 평소에는 자동 갱신을 믿고 그냥 사용한다.

• 갑자기 401, 인증 실패, refresh 실패가 나오면 재로그인을 먼저 시도한다.

• 저장 상태가 의심되면 opencode auth ls로 확인한다.³

초보자 기준에서는 이 순서만 기억해도 절반은 해결됩니다. 인증 문제를 만나면 괜히 설정 파일 전체를 갈아엎기보다, 먼저 인증 상태가 살아 있는지부터 확인하는 것이 훨씬 현명합니다.

초보자가 자주 헷갈리는 세 장면

여기서 많이 틀리는 장면만 짧게 짚고 넘어가겠습니다.

첫째, 브라우저에서는 로그인 성공처럼 보이는데 터미널은 계속 기다리는 경우입니다. 이건 대개 원격 환경에서 자동 콜백을 기대했기 때문입니다. 이럴 때는 Manual URL Paste가 더 잘 맞습니다.²⁴

둘째, 브라우저가 아예 자동으로 안 열리는 경우입니다. 이것도 크게 이상한 일은 아닙니다. 터미널에 표시된 URL을 직접 브라우저에 붙여 넣어 진행하면 됩니다.⁴

셋째, 예전에는 됐는데 며칠 뒤 인증 오류가 나는 경우입니다. 보통은 토큰 갱신 문제이거나 계정 상태 변화일 수 있으니, opencode auth login으로 다시 연결해 보는 것이 가장 빠릅니다.⁴⁵

이 장면만 이해하면 원격 환경이 덜 무섭다

SSH, WSL, 원격 개발 환경에서 핵심은 "인증이 실패했다"가 아니라 "브라우저와 터미널의 위치가 다르다"는 점을 먼저 떠올리는 것입니다.

로컬 환경에서는 브라우저와 OpenCode가 같은 집에 살아서 자동으로 문 앞까지 배달이 됩니다. 반면 원격 환경에서는 브라우저는 내 노트북에 있고, OpenCode는 서버 방 안에 있습니다. 주소가 다르니 문 앞 배달이 실패하는 것입니다.

그럴 때 수동 URL 붙여 넣기는 택배기사에게 현관 비밀번호를 전화로 알려 주는 것과 비슷합니다. 번거로워 보여도 상황을 정확히 해결합니다.

이 비유 하나만 기억해도, 다음번에 WSL이나 SSH에서 인증이 막혔을 때 훨씬 차분해집니다.

이번 장에서 꼭 기억할 것

이번 장의 핵심은 세 줄로 정리할 수 있습니다.

OpenCode의 OpenAI 로그인은 opencode auth login에서 시작하며, 브라우저를 통한 OAuth 흐름으로 인증이 성립합니다.¹²³ 로컬 환경에서는 자동 콜백이 편하고, SSH·WSL·원격 환경에서는 Manual URL Paste가 특히 중요합니다.²⁴ 로그인에 성공하면 인증 정보가 로컬에 저장되고, 이후 요청에서는 자동 갱신이 돌아가므로 매번 브라우저를 다시 열 필요가 없습니다.⁵

이제 인증의 문은 열었습니다. 다음 장에서는 실제로 첫 실행을 성공시키기 위해 모델을 고르고, 기본 명령어를 넣고, "아, 진짜 된다"는 감각까지 연결해 보겠습니다.

참고

¹Authentication - Codex | OpenAI Developers

²Getting Started | OpenCode Codex Auth Plugin

³CLI | OpenCode

⁴Troubleshooting Guide | OpenCode Codex Auth Plugin

⁵Token Management & Refresh | OpenCode Codex Auth Plugin