Codex 사용법: CLI, IDE 확장, Codex Cloud, 데스크톱 앱 완전 입문 가이드

Codex를 처음 쓸 때는 전체 프로젝트 리팩터링부터 맡기지 않는 편이 좋습니다. 먼저 저장소를 열고, 약 20분 안에 검증할 수 있는 작은 작업 하나를 주세요.

진입점 선택 개요

OpenAI Codex는 하나의 터미널 명령이나 하나의 에디터 플러그인이 아닙니다. 여러 진입점에서 사용할 수 있는 coding agent입니다. 공식 문서에서는 CLI, IDE extension, Codex app, Codex web/cloud라는 이름을 보게 됩니다. 이들은 같은 기반 능력과 인증 모델을 공유하지만, 어울리는 작업이 다릅니다.

네 가지 진입점 비교

진입점	정의	적합한 작업	대표 사용자	주요 제약
CLI	로컬 터미널에서 실행되는 coding agent	기존 로컬 저장소, 작은 변경, 명령줄 workflow	터미널을 자주 쓰는 사용자, CI 사용자	로컬 Git 저장소가 필요하고 파일 변경이 로컬에 보입니다
IDE Extension	에디터 sidebar 안의 Codex 협업	현재 에디터 작업, open files 또는 selected code 기반의 짧은 context	VS Code, Cursor, Windsurf, JetBrains 사용자	에디터 환경에 의존하며 복잡한 작업은 Cloud에 위임할 수 있습니다
Codex App	데스크톱 command center	여러 thread, worktree, automation, Git 관리	여러 작업을 병렬로 처리하는 로컬 사용자	macOS와 Windows를 지원하며 Linux는 공식 페이지에서 확인해야 합니다
Codex Cloud/Web	GitHub에 연결되는 cloud agent	원격 저장소, PR, 비동기 작업, 컴퓨터를 떠난 뒤의 실행	팀 사용자와 원격 저장소 workflow	Enterprise workspace는 admin setup이 필요할 수 있습니다

인증 방식과 기능 차이

Codex는 두 가지 인증 경로를 지원하지만, 사용할 수 있는 기능 범위가 다릅니다.

인증 방식	사용할 수 있는 진입점	Cloud 기능 가용성	적합한 상황
ChatGPT account (Plus/Pro/Business/Edu/Enterprise)	모든 진입점(CLI/IDE/App/Cloud)	GitHub code review, Slack 등 cloud-based features 포함	개인 구독자와 팀
API key	CLI, SDK, IDE Extension	GitHub code review, Slack 등 cloud-based features 미포함	CI, automation, API 과금 기반 workflow

가격, 사용량 한도, 정확한 기능 접근은 공식 pricing 페이지와 본인 계정 dashboard에서 확인해야 합니다. API key로 로그인했을 때 Cloud 기능이 보이지 않는다면, 이는 설정이 깨진 것이 아니라 surface 차이입니다.

CLI 진입점

CLI는 로컬 터미널에서 실행되는 coding agent입니다. 선택한 디렉터리의 코드를 읽고, 파일을 수정하고, 명령을 실행하고, 결과를 확인할 수 있으므로 이미 로컬 저장소가 있을 때 잘 맞습니다.

CLI 정의와 사용 사례

CLI의 핵심 역할은 로컬 저장소 안에서 작업하는 것입니다. 코드를 읽고, 파일을 수정하고, 테스트와 lint를 실행하고, 오류를 확인하고, diff를 만듭니다. 파일을 에디터에서 열어 둘 필요는 없습니다. 터미널에서 작업을 설명하면 됩니다.

CLI가 잘 맞는 경우:

• 이미 로컬 Git 저장소가 있습니다.
• 작업이 여러 파일을 건드리거나 명령줄 검증이 필요합니다.
• 파일 변경을 로컬에서 바로 보고 git diff와 commit으로 확인하고 싶습니다.
• CI 또는 script 기반 automation을 사용합니다.

CLI가 덜 맞는 경우:

• 아직 로컬 저장소가 없어 먼저 clone해야 합니다.
• 현재 열려 있는 파일 하나만 수정하고 싶습니다. 이 경우 IDE extension이 더 부드럽습니다.
• 원격 PR workflow가 필요합니다. 이 경우 Cloud가 더 잘 맞습니다.

CLI 설치와 로그인

설치와 로그인 방법은 시간이 지나며 바뀔 수 있으므로, 아래는 큰 흐름으로 보고 정확한 명령은 공식 CLI 페이지를 확인하세요.

1. 공식 CLI 페이지에서 설치 방식을 고릅니다. 현재 공식 페이지는 standalone installer를 제공합니다. 일부 오래된 글은 npm 설치를 말할 수 있지만, 현재 공식 페이지를 우선해야 합니다.
2. 처음 실행합니다. 설치 후 codex를 실행하면 로그인 흐름으로 안내합니다.
3. 로그인 방식을 고릅니다. ChatGPT account 또는 API key를 사용할 수 있습니다. ChatGPT account는 모든 surface를 포함하고, API key는 CLI, SDK, IDE extension 사용에 한정되며 Cloud 기능은 포함하지 않습니다.

CLI는 macOS, Windows, Linux를 지원합니다. Windows에서는 공식 CLI 페이지의 현재 안내에 따라 PowerShell native sandbox 또는 WSL2를 사용합니다.

자주 쓰는 CLI 명령

CLI에는 interactive 모드와 non-interactive 모드가 있습니다. 초보자가 먼저 알아두면 좋은 명령 또는 명령 그룹은 아래 여섯 가지입니다. 이름은 바뀔 수 있으므로 정확한 syntax가 필요할 때는 CLI reference를 확인하세요.

명령	용도	예시
codex	터미널에서 대화식으로 작업하는 interactive 모드	codex
codex exec	CI 또는 script에 적합한 non-interactive 모드	codex exec "fix the CI failure"
codex login	로그인 또는 계정 전환	codex login
codex update	CLI 업데이트	codex update
codex doctor	환경 설정과 흔한 문제 점검	codex doctor
자주 쓰는 flags	권한, 모델, sandbox, approval 동작 조정	--sandbox read-only, --model, --ask-for-approval

CLI reference에는 codex apply, codex cloud, codex app 같은 더 많은 명령과 flags가 있습니다. 일부 명령은 성숙도가 다를 수 있습니다. 초보 단계에서는 interactive 모드부터 익히고, automation이 필요할 때 codex exec로 넘어가면 됩니다.

첫 CLI 작업

첫 작업의 원칙은 단순합니다. 기존 저장소를 선택하고, 약 20분 안에 검증할 수 있는 작업을 Codex에 줍니다.

OpenAI best practices는 좋은 prompt에 네 부분을 포함하라고 권장합니다.

Prompt 요소	의미	예시
Goal	원하는 결과	”README의 오래된 설치 명령을 고쳐줘”
Context	관련 배경	”이 프로젝트는 Node.js 프로젝트이고 README에는 npm install이 적혀 있지만 실제로는 yarn을 씁니다.”
Constraints	변경 경계	”README만 수정하고 다른 파일은 바꾸지 마세요. 수정 후 node README-example.js를 실행해 명령이 동작하는지 확인하세요.”
Done when	검증 조건	”README 명령이 업데이트되고 node README-example.js가 예상 출력을 내면 완료입니다.”

좋은 첫 작업:

• 오래된 README 명령이나 링크 고치기
• 빠진 테스트를 추가하거나 실패하는 테스트 고치기
• 명확한 오류 메시지가 있는 작은 bug 수정하기
• TODO 주석 정리하기
• 한 모듈에 간단한 type annotation 추가하기

피해야 할 첫 작업:

• secret이나 운영 데이터를 건드리는 작업
• 큰 refactor 또는 완전한 새 기능
• “성능 최적화”처럼 명확한 acceptance condition이 없는 작업

CLI 검토 체크리스트

CLI가 끝나면 아래 순서로 결과를 확인합니다.

1. diff 읽기: 터미널에서 git diff를 실행하고 변경이 요청과 맞는지 확인합니다. 마지막 “done” 메시지만 믿지 않습니다.
2. 테스트 실행: 프로젝트에 테스트가 있다면 npm test 또는 해당 명령을 실행합니다.
3. lint 또는 typecheck 실행: 해당 check가 있다면 새 오류가 생기지 않았는지 확인합니다.
4. 명령 출력 확인: 작업에 특정 명령 실행이 포함되었다면 출력이 예상과 맞는지 확인합니다.
5. 첫 작업에서 secret 멀리 두기: 민감한 설정을 건드리는 작업이라면 agent가 수정하기 전에 정말 필요한 변경인지 사람이 먼저 확인합니다.

검사가 통과한 뒤에 commit 또는 push합니다. 변경이 잘못되었다면 Git으로 되돌리고 prompt를 더 좁혀 다시 시도합니다.

IDE Extension 진입점

IDE extension은 Codex가 에디터 sidebar에서 함께 작업하게 해 줍니다. 이미 에디터에서 개발 중일 때 잘 맞습니다. 장점은 context가 짧고 선명하다는 점입니다. open files, selected code, 명시적인 @file reference를 사용하므로 터미널 prompt에서 전체 프로젝트를 설명할 필요가 줄어듭니다.

IDE 정의와 사용 사례

IDE extension은 에디터를 대체하지 않습니다. Codex를 coding agent로 에디터 workflow 안에 넣는 방식입니다. context는 열려 있는 파일, 선택한 snippet, 또는 @file로 명시한 파일에서 오므로 로컬 수정에 더 정확할 수 있습니다.

IDE extension이 잘 맞는 경우:

• VS Code, Cursor, Windsurf, JetBrains에서 작업 중입니다.
• 현재 파일 또는 관련 파일 몇 개에 대한 작업입니다.
• 변경을 에디터에서 바로 보고 싶습니다.
• 특정 파일을 context로 명시해야 합니다.

IDE extension이 덜 맞는 경우:

• 에디터 환경을 쓰지 않습니다. 이 경우 CLI가 더 단순합니다.
• 오래 걸리는 background 실행이 필요합니다. 이 경우 Cloud에 넘길 수 있습니다.
• 많은 파일이나 복잡한 명령 흐름을 다룹니다. CLI 또는 Cloud가 더 나을 수 있습니다.

지원 IDE

IDE extension은 아래 에디터를 지원합니다. 현재 지원 여부는 공식 IDE 페이지를 확인하세요.

에디터	설명
VS Code	공식 지원
Cursor	VS Code fork이며 VS Code extension과 호환됩니다
Windsurf	VS Code fork이며 VS Code extension과 호환됩니다
JetBrains	Rider, IntelliJ, PyCharm, WebStorm 등 관련 IDE를 지원하며 공식 availability를 확인해야 합니다

Cursor 또는 Windsurf에서 작업한다면 Codex extension과 에디터 내장 AI 기능은 나란히 사용할 수 있습니다. Codex는 작업에 맞을 때 전환해 쓰는 또 하나의 coding agent입니다.

IDE 설치와 로그인

현재 설치 절차는 공식 IDE 페이지를 따르세요.

1. extension marketplace에서 설치합니다. VS Code, Cursor, Windsurf, JetBrains의 extension marketplace에서 Codex extension을 검색합니다.
2. 로그인합니다. ChatGPT account 또는 API key를 사용할 수 있습니다. ChatGPT account는 모든 surface를 포함하고, API key는 Cloud 기능을 포함하지 않습니다.

IDE context

IDE extension의 주요 가치는 에디터 context입니다.

Context 유형	의미	예시
Open files	현재 열려 있는 파일이 context로 제공됩니다	example.tsx를 열면 Codex가 바로 살펴볼 수 있습니다
Selected code	선택한 snippet이 context가 됩니다	함수를 선택하고 설명이나 refactor를 요청합니다
@file reference	파일 이름으로 다른 파일을 명시적으로 참조합니다	@example.tsx please check the component's type definitions
Reasoning effort	agent가 사용할 reasoning 양을 조정합니다	low/medium/high; 어려운 작업에는 higher effort를 씁니다

IDE extension은 Chat, Agent, Agent Full Access 모드도 지원합니다. 차이는 권한과 자동화 수준입니다. 먼저 기본 Agent 모드에서 시작하고, trade-off를 이해한 뒤 조정하세요.

IDE에서 Cloud로 위임하기

IDE extension은 작업을 Codex Cloud에 위임할 수 있습니다. 다음 상황에서 사용합니다.

• 작업이 오래 걸릴 수 있습니다.
• 원격 저장소와 관련된 작업입니다.
• 컴퓨터를 떠나 있는 동안에도 작업이 계속되어야 합니다.
• 복잡한 작업을 background에서 실행하고 나중에 결과를 보고 싶습니다.

자주 쓰는 slash commands는 아래와 같습니다. 명령 이름은 바뀔 수 있으므로 IDE features 페이지를 확인하세요.

명령	용도
/cloud	현재 작업을 Cloud에 위임
/local	작업을 로컬에서 실행
/review	base branch, uncommitted changes, commit review
/status	Cloud 작업 상태 확인

/cloud를 사용하면 IDE가 작업 상태를 보여 줍니다. Cloud 작업이 끝나면 돌아와 diff와 결과를 검토합니다.

Codex App 진입점

Codex app은 여러 thread와 Git 관리를 위한 데스크톱 command center입니다. 또 다른 채팅 창이 아닙니다. CLI와 IDE extension의 history와 설정을 이어받을 수 있어 기존 프로젝트 작업을 계속하기에 좋습니다.

App 정의와 사용 사례

App은 여러 thread, worktree, automation, Git 작업에 초점을 둡니다. 병렬 작업, diff pane, Git 통합이 하나의 로컬 workspace에 필요할 때 유용합니다.

App이 잘 맞는 경우:

• 동시에 여러 task thread가 필요합니다.
• worktree로 병렬 작업을 격리해야 합니다.
• 시각적인 diff pane과 Git 작업을 원합니다.
• integrated terminal이 있는 데스크톱 workflow를 원합니다.

App이 덜 맞는 경우:

• 현재 파일 하나만 수정하고 싶습니다. 이 경우 IDE extension이 더 부드럽습니다.
• 로컬 저장소가 없습니다. 이 경우 Cloud를 쓰거나 먼저 repo를 clone합니다.
• 빠른 작업 하나만 필요합니다. 이 경우 CLI가 더 빠릅니다.

App 플랫폼 지원

Codex app은 macOS와 Windows를 지원합니다. Linux availability는 공식 app 페이지에서 확인하세요.

App 설치와 로그인

현재 단계는 공식 app 페이지를 따르세요.

1. 다운로드하고 설치합니다. 공식 app 페이지에서 macOS 또는 Windows installer를 받습니다.
2. 로그인합니다. ChatGPT account 또는 API key를 사용할 수 있습니다. API key를 쓰면 일부 기능이 제한될 수 있으며 공식 안내를 확인해야 합니다.
3. 프로젝트를 선택합니다. 처음 실행하면 로컬 프로젝트 디렉터리를 선택하라는 안내가 나옵니다.

App thread modes

App은 Local, Worktree, Cloud 세 가지 thread mode를 제공합니다.

Thread mode	동작	적합한 작업
Local	현재 프로젝트 디렉터리에서 직접 작업합니다	작은 변경, 단일 thread 작업, 첫 메시지의 기본 선택
Worktree	thread용 격리 worktree를 만듭니다	병렬 작업, 변경 격리, 충돌 회피
Cloud	작업을 Codex Cloud에 위임합니다	원격 저장소, PR, 오래 걸리는 작업

자세한 worktree workflow는 뒤의 가이드로 미루세요. 초보자는 Local mode부터 시작하면 됩니다.

App 핵심 기능

App의 핵심 기능은 다음과 같습니다.

기능	설명
Diff pane	파일 변경을 시각적으로 확인하고 chunk를 stage 또는 revert할 수 있습니다
Git 작업	commit, push, PR 생성과 관련 Git flow를 지원합니다
Integrated terminal	macOS에서는 Cmd+J로 terminal을 열 수 있으며 현재 shortcut은 공식 페이지를 확인하세요
IDE sync	IDE extension과 app workflow가 같은 프로젝트 안에서 sync될 수 있습니다
Shared MCP settings	CLI, IDE, app이 MCP settings를 공유할 수 있습니다

App에는 in-app browser도 있지만 로그인된 browser profile이 필요한 페이지에는 쓰지 않습니다. 로그인된 페이지가 필요하면 외부 browser에서 여세요.

Codex Cloud/Web 진입점

Codex web/cloud는 GitHub account에 연결되어 Codex가 원격 저장소에서 작업하고 PR을 만들 수 있게 합니다. 팀 workflow, 원격 저장소, 컴퓨터를 떠난 뒤에도 실행해야 하는 작업에 맞습니다.

Cloud 정의와 사용 사례

Cloud는 원격 저장소, PR, 비동기 작업을 위한 진입점입니다. cloud container를 만들고, repository를 checkout하고, setup script를 실행하고, 작업을 수행한 뒤 diff와 응답을 돌려줍니다.

Cloud가 잘 맞는 경우:

• 로컬에서 수정하고 싶지 않은 원격 저장소입니다.
• Codex가 PR을 만들거나 review해야 하는 PR flow입니다.
• 컴퓨터를 떠나 있는 동안에도 작업이 계속되어야 합니다.
• review와 협업이 있는 팀 workflow입니다.

Cloud가 덜 맞는 경우:

• 작은 로컬 변경입니다. CLI 또는 IDE extension이 더 좋습니다.
• 아주 첫 작업입니다. 먼저 로컬에서 검증하는 편이 좋습니다.
• 잦은 상호작용이 필요한 작업입니다. Cloud는 비동기 workflow입니다.

Cloud에 적합한 작업

Cloud는 아래 작업에 잘 맞습니다.

작업 유형	설명
PR review	원격 저장소의 PR을 review합니다
복잡하거나 오래 걸리는 작업	시간이 더 필요한 작업을 실행합니다
병렬 작업	여러 작업을 동시에 위임합니다
원격 저장소 변경	로컬 checkout을 건드리지 않고 변경합니다

첫날부터 큰 refactor나 완전한 기능을 Cloud에 보내지 마세요. 먼저 CLI 또는 IDE를 로컬에서 써 보고 결과가 어떻게 보이는지 익힌 뒤, 적합한 작업을 Cloud로 옮기면 됩니다.

Enterprise workspace에는 admin setup이 필요할 수 있습니다. 공식 Cloud 페이지와 본인 workspace policy를 확인하세요.

Cloud flow

Cloud task는 대략 다섯 단계를 거칩니다.

1. container 생성: Cloud가 runtime environment를 만듭니다.
2. repository checkout: GitHub repository를 checkout합니다.
3. setup script 실행: 설정된 setup script가 있으면 실행합니다.
4. agent loop 실행: agent가 명령을 실행하고 결과를 확인하며 완료될 때까지 진행합니다.
5. diff와 답변 반환: 완료된 작업은 diff와 응답을 보여 줍니다.

container cache는 최대 12시간 지속될 수 있습니다. 현재 cache policy는 공식 Cloud environments 페이지를 확인하세요.

Cloud 보안 메모

Cloud에는 몇 가지 중요한 보안 경계가 있습니다.

보안 항목	의미
Secrets는 setup 중에만 사용 가능	Secrets는 setup scripts에서 사용할 수 있고 agent phase 전에 제거됩니다. agent phase가 secrets를 읽는 script에 의존하게 만들지 마세요.
agent phase는 기본적으로 internet off	agent phase에서는 기본적으로 internet access가 꺼져 있으며, limited 또는 unrestricted access를 설정할 수 있습니다. agent가 외부 서비스에 닿을 수 있다고 가정하지 마세요.
cache는 최대 12시간	container cache는 장기 저장소가 아닙니다. 상태가 계속 유지된다고 가정하지 마세요.

더 깊은 보안 설정은 permissions, sandboxes, secrets 가이드를 참고하세요.

다음 단계

첫 작업을 마친 뒤 Codex가 두 번째나 세 번째 실행에서도 같은 실수를 반복한다면 AGENTS.md 프로젝트 가이드를 작성할 때입니다. AGENTS.md는 coding agent에게 주는 프로젝트별 지침을 담아, 매번 같은 context를 반복하지 않게 해 줍니다.

추천 후속 주제:

• AGENTS.md 프로젝트 규칙: 프로젝트 지침을 남기고 반복 설명을 줄입니다.
• Worktree 격리: 여러 작업을 병렬로 실행하되 변경이 섞이지 않게 합니다.
• Cloud workflow: 원격 저장소, PR, 환경 설정.
• 권한, sandbox, secrets: 보안 경계와 설정.
• 세 도구 비교: 실제 프로젝트에서 Codex vs Claude Code vs Cursor.
• codex exec automation: CI 호출과 script 기반 automation.

관련 BetterLink 글:

• 2026 AI 코딩 도구 개요
• Claude Code CLI 생산성 가이드
• Cursor workflow 실전
• Codex gateway와 harness