Codex CLI와 Codex App: 차이점과 선택 방법
워크플로, 병렬 작업, diff, 자동화, 인증 및 검증 측면에서 Codex CLI와 데스크톱 앱을 비교합니다.
작업이 이미 터미널, 원격 머신 또는 스크립트에 있다면 Codex CLI가 더 잘 맞습니다. 여러 병렬 작업, 시각적 diff 검토, 프로젝트 관리에는 데스크톱 앱이 더 적합합니다. 둘은 서로 다른 모델이 아니라 Codex의 두 인터페이스입니다. 커스텀 프로바이더를 사용하면 클라이언트에 따라 인증도 달라집니다. CLI와 Desktop App은 같은 방식을 사용하지만 VS Code 확장은 다른 방식을 사용합니다.
Codex CLI와 Codex App: 짧은 답
OpenAI는 데스크톱 앱이 CLI와 IDE 확장의 세션 기록 및 설정을 가져올 수 있다고 설명합니다. 따라서 두 인터페이스를 함께 쓰기 쉬워지지만, 같은 실행 환경이 되는 것은 아닙니다. 환경 변수, 재시작, 검증은 클라이언트마다 확인해야 합니다. subagent는 CLI와 App 모두에서 사용할 수 있습니다. App의 장점은 병렬 실행 자체가 아니라 스레드, worktree, diff를 시각적으로 관리하는 데 있습니다.
커스텀 프로바이더가 실제로 적용되는 위치
BetterToken은 OpenAI 호환 도구를 위한 API 액세스를 제공합니다. Codex에서는 OpenAI 공식 클라이언트, 커스텀 프로바이더, Base URL https://www.bettertoken.ai/v1, Responses 프로토콜을 사용합니다. BetterToken은 Codex 자체, ChatGPT 로그인 또는 앱 설치를 대체하지 않습니다. 자신의 BetterToken 계정과 API Key를 사용해야 합니다.
먼저 작업이 어디에서 시작되는지 구분하세요.
- Terminal의
codex명령은 CLI입니다. - 데스크톱 애플리케이션 안의 Codex는 Desktop App입니다.
- VS Code 안의 Codex 패널은 확장 기능입니다.
세 클라이언트 모두 ~/.codex/config.toml(Windows에서는 %USERPROFILE%\.codex\config.toml)에서 설정을 읽지만 인증 방식은 다릅니다.
두 모드 모두 [model_providers.custom] 섹션을 하나만 사용합니다. 하나의 TOML 파일에 같은 이름의 섹션을 두 개 만들지 마세요. 현재 사용하는 클라이언트의 인증 방식을 선택하고 정확한 필드와 현재 Model ID는 Codex CLI/Desktop App 및 Codex VS Code Extension 가이드에서 확인하세요.
Desktop App과 IDE 확장은 shell 프로필에만 정의한 변수를 받지 못할 수 있습니다. 새 프로세스가 BETTERTOKEN_API_KEY를 보지 못하면 현재 클라이언트별 가이드를 따르고 클라이언트를 완전히 다시 시작한 뒤 새 세션을 만드세요. 키를 기사, 스크린샷, 공유 저장소에 쓰면 안 됩니다.
프로바이더가 적용되었는지 확인하는 방법
재시작 후 컨텍스트가 적은 짧은 작업을 보냅니다. CLI에서는 /status를 열어 현재 프로바이더를 확인합니다. CLI, Desktop App 또는 VS Code에서 응답을 받은 뒤 BetterToken Dashboard에서 시간과 모델이 일치하는 기록을 찾으세요. 이는 모델 요청이 BetterToken을 거쳤음을 확인합니다. 오래된 세션은 변경된 설정을 깨끗하게 검증하기에 적합하지 않습니다. 401, 403, model not found가 없다는 것은 기본 동작 확인일 뿐이며, /status 또는 Dashboard의 일치 기록 없이는 어떤 프로바이더와 Base URL이 사용되었는지 증명하지 못합니다.
워크플로의 차이
CLI: 터미널, SSH, 재현 가능한 명령
CLI는 현재 shell 프로세스 안에서 실행됩니다. 대화형 모드는 저장소 작업에, codex exec는 비대화형 작업과 스크립트에, /agent는 내장 subagent를 확인하거나 전환하는 데 적합합니다. SSH 세션, 컨테이너, CI 검사, 기존 명령 세트에 쉽게 통합할 수 있습니다. 병렬 작업은 가능하지만 디렉터리, 프로세스, 결과는 보통 직접 관리합니다. 두 작업이 같은 작업 복사본을 바꾸면 안 될 경우 별도 worktree 또는 디렉터리를 사용하고 병합 전에 diff를 검토하세요.
Desktop App: 프로젝트, 스레드, 시각적 diff
Desktop App은 여러 작업을 한 인터페이스에 모읍니다. 스레드는 컨텍스트를 분리하고, 내장 worktree는 변경을 격리하며, diff는 작업 대화 옆에서 검토할 수 있습니다. 버그 수정, 새 기능, 리뷰가 동시에 진행될 때 편리합니다. 데스크톱 앱의 제공 여부, 이름, 인터페이스 위치는 업데이트에 따라 바뀔 수 있으므로 설치나 업데이트 전 공식 다운로드 페이지를 확인하세요.
구체적인 워크플로에서 무엇을 선택할까
다음이라면 CLI를 선택하세요
- 주 인터페이스가 Terminal, SSH 또는 컨테이너이다.
codex exec, shell 스크립트, 외부 스케줄링이 필요하다.- 재현 가능한 명령 순서가 중요하다.
- 병렬 작업 디렉터리를 직접 관리할 수 있다.
다음이라면 Desktop App을 선택하세요
- 여러 작업 또는 프로젝트가 동시에 실행된다.
- 그래픽 인터페이스에서 diff와 댓글을 검토하는 편이 쉽다.
- worktree와 결과 큐를 한 곳에서 보고 싶다.
- 작업이 터미널 명령이 아니라 문서, 리서치, 운영 프로세스에서 시작된다.
두 인터페이스를 함께 쓰는 경우
원격 머신과 자동화에는 CLI를, 관리와 리뷰에는 Desktop App을 사용하세요. 공유 기록과 설정은 전환을 쉽게 하지만, 실행 전마다 작업 디렉터리, 권한, 활성 프로바이더, 인증 방식을 확인해야 합니다.
자주 발생하는 프로바이더 문제
CLI에서는 되지만 VS Code에서는 안 됨
CLI/Desktop App과 확장은 서로 다른 인증 필드를 사용합니다. env_key 방식을 완전한 해결책으로 확장에 복사하지 말고 공식 auth.json을 BetterToken API Key로 덮어쓰지 마세요. 확장 전용 가이드를 열고 Reload Window를 실행하세요.
Codex가 다시 공식 로그인을 요구함
CLI/Desktop App에서 커스텀 프로바이더를 사용할 때 새 Codex 프로세스가 BETTERTOKEN_API_KEY에 접근할 수 있는지 확인하세요. 확장에서는 공식 로그인을 유지하고 모델 요청 키는 별도 필드로 전달합니다.
프로바이더를 찾을 수 없음
model_provider = "custom" 값은 [model_providers.custom] 섹션 이름과 일치해야 합니다. 중복 섹션을 제거하고 wire_api = "responses"를 확인하세요.
설정은 저장되었지만 아무것도 바뀌지 않음
기존 프로세스를 종료하고 새 터미널을 열거나 Reload Window를 실행한 다음 새 세션을 만드세요. App이 shell의 키를 보지 못하면 현재 클라이언트별 가이드를 따르고 완전히 다시 시작합니다. 오류가 계속되면 Model ID, API Key, Base URL, 인증 모드를 하나씩 확인하고 여러 매개변수를 동시에 바꾸지 마세요.
최종 선택
터미널, SSH, 스크립트, 직접적인 프로세스 관리에는 Codex CLI를 선택하세요. 병렬 작업, worktree, 시각적 리뷰에는 Desktop App을 선택하세요. 커스텀 프로바이더를 쓸 때는 먼저 클라이언트를 고르고 그 인증 방식을 적용한 뒤 짧은 새 세션에서 결과를 확인합니다.
현재 BetterToken 매개변수는 Codex 가이드에서, VS Code는 확장 기능 별도 가이드에서 확인하세요.