코덱스 CLI 로그인: 서버에서 –device-auth로 처음 연결하는 법

1. 로그인이 막히는 이유: 브라우저 콜백의 한계

노트북에서 코덱스를 처음 실행하면 codex 명령 하나로 시작됩니다. 처음 실행할 때 “Sign in with ChatGPT”를 고른 뒤 브라우저가 열리고, 로그인이 끝나면 자격 증명이 저장됩니다. 공식 Codex CLI 시작 안내

문제는 서버입니다. 일반 로그인(codex login)은 로컬에 콜백 서버를 띄우고 브라우저를 여는 방식이라, SSH로 접속한 원격 서버나 브라우저가 없는 환경에서는 어디에도 브라우저가 없어 흐름이 멈춥니다. 공식 저장소의 이슈에서도 같은 상황이 보고돼 있습니다. 공식 저장소 로그인 이슈

이 틈을 메우는 것이 디바이스 인증입니다. 명령에 --device-auth를 붙이면 터미널에 검증 링크와 일회용 코드가 출력되고, 브라우저가 있는 다른 기기(휴대폰이나 노트북)에서 링크를 열고 코드를 입력하면 서버 쪽 로그인이 완료됩니다. TV 앱에서 계정 연결할 때 쓰는 방식과 같습니다.

요금 기준을 먼저 정리하면 선택이 쉽습니다. 챗GPT 계정으로 로그인하면 내 요금제의 사용량과 청구 기준이 적용되고, Codex는 Free·Go 요금제를 포함해 전 요금제에 포함됩니다. 반면 API 키를 쓰면 표준 API 가격으로 별도 청구됩니다. 공식 인증 안내, 요금제별 Codex 안내

2. 1단계: 서버에 Codex CLI 설치하기

공식 단독 설치기는 macOS와 Linux를 지원합니다. 설치 명령은 공식 시작 안내 그대로입니다. 설치 안내

설치 후 codex --version처럼 버전이 출력되는지 확인하세요. Windows 서버를 쓴다면 공식 설치기 대상이 아니므로, 팀에서 쓰는 Linux 환경(WSL2 포함)에 설치하는 편이 일반적입니다. 이 부분은 공식 문서의 범위가 아니라 현장 관행이므로 회사 안내를 함께 확인하세요.

서버에 설치했다면 SSH로 접속한 터미널에서 바로 로그인 단계로 넘어갑니다. 로그인 전에 codex를 먼저 실행해 볼 수도 있지만, 브라우저가 없는 환경에서는 흐름이 멈추니 바로 디바이스 인증 명령을 쓰는 것이 빠릅니다.

3. 2단계: 디바이스 인증으로 코드 받기

서버 터미널에서 디바이스 인증 로그인을 시작합니다.

실행하면 터미널에 검증 링크(https://auth.openai.com/codex/device)와 일회용 코드가 출력됩니다. 공식 저장소 이슈에서도 이 명령이 장치 코드와 해당 링크를 안내함이 확인돼 있습니다. 공식 저장소 확인

1. 휴대폰이나 노트북의 브라우저에서 출력된 링크를 엽니다.
2. 이미 로그인된 챗GPT 계정으로 확인한 뒤, 터미널에 나온 일회용 코드를 입력합니다.
3. 이 로그인이 내가 시작한 것이 맞는지 확인하는 안내에 승인합니다.
4. 서버 터미널로 돌아오면 로그인 완료 메시지가 출력됩니다.

코드는 짧은 시간 안에 입력해야 합니다. 사용자들이 관찰한 바로는 약 15분 유효이며, 시간이 지나면 새 코드를 받아 다시 진행하면 됩니다. 코드 형식과 유효 시간은 공식 문서에 적힌 값이 아니라 사용자 보고 기준이므로 넉넉히 잡고 한 번에 진행하세요.

코드는 TV의 인증 코드처럼 한 번 쓰고 끝나는 값이지만, 남이 준 코드를 내 계정에 입력하는 일은 없어야 합니다. 터미널에 “방금 Codex에서 시작한 로그인이 맞는지 확인”하는 안내가 나오면, 내가 직접 실행한 것이 맞을 때만 진행하세요.

4. 3단계: 로그인 상태 확인과 끝내기

로그인 후에는 상태 확인과 종료 방법만 기억하면 됩니다.

codex login status는 어떤 계정·방식으로 로그인됐는지 보여 줍니다. 공식 저장소 이슈에서도 이 명령으로 챗GPT 인증 상태를 확인했음이 보고돼 있습니다. 상태 확인 명령 근거

로그인 정보는 서버에 저장돼 다음 실행부터 자동으로 쓰입니다. 공식 문서에 따라 챗GPT 로그인은 토큰이 만료되기 전에 자동으로 갱신되므로, 한 번 연결해 두면 보통 다시 브라우저 로그인을 요구하지 않습니다. 로그인 캐시 안내

5. 코드 입력했는데 안 될 때

가장 답답한 경우가 “코드까지 입력했는데 로그인이 조용히 안 되는” 상황입니다. 사용자 보고를 모아 본 결과, 원인은 대부분 서버가 아니라 계정 쪽 설정에 있습니다.

1. 디바이스 코드 로그인이 꺼져 있는 경우: 개인 계정의 보안 설정이나 회사 워크스페이스 관리자 설정에서 디바이스 코드 인증이 허용되지 않으면, 코드 입력까지는 진행돼도 서버에서 토큰을 받지 못합니다. 계정 설정을 확인하거나, 회사 계정이라면 관리자에게 디바이스 코드 인증 허용 여부를 확인하세요. 관리자 제어가 존재함은 공식 문서에서도 확인됩니다. 디바이스 코드 인증 제어 언급
2. 다른 계정·워크스페이스로 로그인된 경우: 코드를 입력한 브라우저가 내가 쓰려는 계정과 다른 계정으로 로그인돼 있으면 권한이 맞지 않을 수 있습니다. 브라우저의 로그인 계정을 확인하세요.
3. 코드가 만료된 경우: 시간이 지난 코드는 거절됩니다. 터미널에서 명령을 다시 실행해 새 코드를 받으세요.

디바이스 인증이 계속 막히면 우회 방법이 하나 더 있습니다. SSH 터널로 서버의 콜백 포트를 내 노트북에 연결하고 일반 로그인을 쓰는 방식입니다. 터미널을 두 개 띄워 한쪽은 터널 유지, 한쪽에서 로그인을 진행합니다. 이 방법은 사용자 커뮤니티에서 널리 쓰이는 방식으로, 공식 지원 절차는 아닙니다.

터널 방식을 쓸 때는 터미널 1을 끄면 로그인 흐름이 끊기니, 로그인이 끝날 때까지 열어 두세요. 팀 서버라면 포트 사용이 허용되는지 먼저 확인하세요.

6. 자격 증명 파일 보안과 주의점

로그인이 끝나면 서버의 ~/.codex/auth.json 같은 위치에 자격 증명이 저장됩니다. 공식 문서는 이 파일을 비밀번호처럼 취급하라고 명시합니다. Git에 커밋하거나, 티켓·채팅에 붙여 넣거나, 다른 사람과 공유하면 안 됩니다. 자격 증명 저장 안내

저장 위치는 설정으로 바꿀 수 있습니다. config.toml의 cli_auth_credentials_store 값을 file(파일 저장), keyring(macOS 키체인·Windows 자격 증명 관리자 같은 OS 저장소), auto, ephemeral(프로세스 메모리만) 중에서 고를 수 있습니다. 여러 사람이 쓰는 서버라면 OS 저장소를 쓰는 편이 안전합니다.

마지막으로 용도 정리입니다. 이 글의 로그인은 “내 챗GPT 계정으로 서버에서 코덱스를 쓰기 위한” 것입니다. 반복 자동화나 CI/CD 파이프라인에 붙일 거라면 계정 로그인 대신 API 키 방식이 공식 권장이며, 회사에서 발급한 접근 토큰이 있다면 codex login --with-access-token을 쓸 수도 있습니다. 접근 토큰 안내

확인 범위: 이 글은 2026년 9월 23일 공식 Codex 문서와 공식 저장소 이슈를 대조해 작성했습니다. 디바이스 인증의 코드 유효 시간·코드 형식·콜백 포트 번호는 공식 문서가 아니라 사용자 보고 기준이며, 실제 계정으로 로그인을 시험하지 않았습니다. 터미널 출력 예시와 흐름 설명은 독자가 직접 확인할 수 있도록 구성한 것으로, 화면이 조금 다를 수 있습니다. 서버에서 로그인 후에 할 일은 코덱스 자동화로 반복 업무 맡기기와 휴대폰으로 코덱스 작업 확인하기에서 이어서 볼 수 있습니다.

자주 묻는 질문