코덱스(Codex) 사용법: 데스크톱 앱·CLI·IDE·클라우드 중 어디서 시작할까

코덱스(Codex)는 OpenAI의 코딩 에이전트로 지금은 네 곳에서 씁니다. ChatGPT 데스크톱 앱 안의 Codex, 터미널에서 쓰는 Codex CLI, VS Code 같은 코드 에디터의 IDE 확장, 그리고 OpenAI 쪽 작업 공간에서 도는 Codex Cloud입니다. 코딩이 처음이라면 ChatGPT 데스크톱 앱을 설치하고 앱 위쪽 메뉴에서 Codex를 고르는 것부터 시작하세요. ChatGPT 계정으로 로그인하면 되고 요금 문서상 Free 플랜에도 데스크톱 앱의 Codex가 들어 있습니다(모델과 공개 시점에 조건이 붙습니다).

9월 가톨릭대학교 AI 부트캠프에서도 코딩 경험이 없는 대학생 60여 명에게 데스크톱 앱 하나만 쓰게 했습니다. 학생들이 가장 많이 막힌 곳은 코딩이 아니라 설치였고 Windows PC에서 더 자주 막혔어요. 저는 평소 작업은 Claude Code로 하고 Codex CLI는 코드 리뷰와 교차 검증에 씁니다.

이 글은 네 진입점의 차이와 첫 작업 순서, 권한 모드, AGENTS.md, 모델 고르기, MCP 연결, Codex Cloud를 한 장에 모은 안내판입니다. 설치와 실습은 각 절 끝에 연결한 글에 자세히 있어요. 공식 문서는 2026년 10월 16일에 다시 읽고 대조했습니다. 요금·모델·공개 범위는 자주 바뀌니 결제 전에는 공식 페이지를 한 번 더 확인하세요.

코덱스(Codex)를 쓰는 네 곳

네 곳은 서로 다른 제품이 아니라 같은 Codex를 여는 창입니다. 데스크톱 앱, CLI, IDE 확장은 같은 설정 파일(~/.codex/config.toml)을 함께 써요. 한 곳에서 정한 기본 모델이나 붙인 MCP 서버가 다른 곳에도 그대로 보입니다. CLI에서 하던 대화는 /app 명령으로 macOS·Windows 데스크톱 앱에서 이어 갈 수도 있습니다.

요금 문서의 Free·Go 항목에는 "데스크톱 앱에서 GPT-6 Luna, 표준 속도, 순차 공개"가 적혀 있습니다. ChatGPT 요금 페이지와 모델 도움말에는 이전 세대 GPT-5.6 Terra도 데스크톱 앱에서 제한적으로 쓸 수 있다고 나와요. 웹·CLI·IDE 확장·iOS의 Codex와 클라우드 기능은 Plus(월 $20) 항목부터 나옵니다. API 키로 로그인할 수도 있지만 사용량만큼 API 요금이 따로 나가고 클라우드 기능은 빠집니다. 플랜별 가격과 한도는 코덱스 요금제 정리에 따로 모았습니다.

비개발자는 데스크톱 앱에서 시작하세요

데스크톱 앱을 권하는 건 터미널 명령을 몰라도 되기 때문입니다. 작업할 폴더를 고르는 창, 실행 전에 뜨는 승인 버튼, 바뀐 파일을 보여 주는 검토 패널이 모두 화면에 있어요. Free 플랜에서 쓸 수 있다는 점도 처음 써 보는 사람에게는 큽니다.

설치 파일은 공식 다운로드 페이지나 공식 문서 빠른 시작의 Download ChatGPT 버튼에서 받습니다. 다운로드 페이지에는 접속한 컴퓨터에 맞는 버튼이 보이고(Mac에서는 Download for macOS) 맨 아래 ChatGPT Classic은 Codex가 합쳐진 새 앱이 아니라 이전 버전 앱이에요. macOS(Apple Silicon·Intel), Windows(11 권장), Linux(미리보기)용이 있습니다. OS별 설치 파일과 요구사항, Windows에서 막혔을 때 볼 곳은 코덱스(Codex) 데스크톱 앱 설치와 사용법에 정리했습니다.

데스크톱 앱에서 첫 작업까지 다섯 단계

1. 로그인합니다. 앱을 열고 Continue to sign in을 누르면 브라우저가 열립니다. ChatGPT 계정으로 로그인하면 앱으로 돌아옵니다.
2. Codex를 고릅니다. 앱 위쪽의 선택 메뉴가 ChatGPT로 되어 있으면 Codex로 바꿉니다.
3. 폴더를 엽니다. 홈 폴더 아래에 빈 폴더를 하나 만들고 Add new project(Mac Cmd+O, Windows Ctrl+O)로 엽니다. Codex는 고른 폴더 안의 파일을 읽고 고칩니다.
4. 어디서 돌릴지 확인합니다. Work in에서 This computer를 고르면 내 컴퓨터의 그 폴더에서 바로 작업합니다. Cloud는 아래에서 설명할 클라우드 작업입니다. Git 프로젝트라면 별도의 Worktree 옵션으로 작업 사본을 만들 수도 있습니다.
5. 권한을 확인하고 보냅니다. 입력창 아래 권한 메뉴가 Ask for approval인지 보고 첫 요청을 보냅니다.

첫 요청은 결과를 바로 눈으로 확인할 수 있는 크기로 잡는 게 좋습니다. 아래는 예시입니다.

이 폴더에 자기소개 웹페이지 한 장을 만들어 줘.
index.html 파일 하나에 CSS까지 넣고, 외부 라이브러리나 설치는 쓰지 마.
다 만들면 어떤 파일을 만들었는지, 내 컴퓨터에서 어떻게 여는지 알려 줘.

파일 하나와 설치 금지를 적어 두면 중간에 패키지를 받으려다 인터넷 접속 승인에서 멈추는 일이 줄어요. 이 요청으로 페이지를 만들고 고치는 과정은 데스크톱 앱 글에 이어서 정리했습니다.

권한(승인) 모드: 어디까지 혼자 하게 할까

Codex가 파일을 고치고 명령을 실행할 때 어디까지 묻지 않고 진행할지는 권한 모드로 정합니다. 권한 문서의 예시 화면에 나오는 선택지는 네 가지입니다.

문서는 대부분의 작업을 Ask for approval로 시작하라고 권합니다. 이 모드에서 Codex는 연 폴더 안에서는 알아서 고치고 실행하다가 그 경계를 넘을 때 멈춰서 묻습니다. Approve for me도 경계는 같습니다. 경계를 넘는 요청을 사람 대신 별도의 검토 에이전트가 판단하게 바꿀 뿐이에요. 메뉴에 어떤 모드가 보이는지는 앱 버전, 실행 환경, 설정, 조직 정책에 따라 다릅니다.

승인 창이 떴을 때 무엇을 보고 승인할지, Windows에서 샌드박스 보호를 받는 조건은 데스크톱 앱 글에 적었습니다. CLI에서는 /permissions를 입력해 Auto, Read Only 같은 미리 정해 둔 조합을 고릅니다.

AGENTS.md: 매번 하는 말을 파일 하나로

"한국어로 답해 줘", "이 폴더는 건드리지 마"를 대화마다 반복하고 있다면 AGENTS.md에 적어 둘 때입니다. AGENTS.md 문서에 따르면 Codex는 작업을 시작하기 전에 이 파일을 읽습니다. Claude Code의 CLAUDE.md와 같은 역할을 하는 에이전트 메모리 파일이에요.

• 모든 프로젝트에 적용: Codex 홈 폴더의 ~/.codex/AGENTS.md. 데스크톱 앱에서는 Settings의 Personalization에서 이 개인 지침을 고칠 수 있습니다.
• 이 프로젝트에만 적용: 프로젝트 맨 위 폴더의 AGENTS.md. 하위 폴더에 따로 두면 그 폴더에서 작업할 때 뒤에 붙어 앞의 지침보다 우선합니다.
• 처음 만들기: CLI에서 /init을 입력하면 현재 폴더에 AGENTS.md 초안을 만들어 줍니다. 초안은 읽어 보고 내 프로젝트에 맞게 고칩니다.
• 길이 한도: 합친 지침이 기본 32KiB를 넘으면 그 뒤 파일은 읽지 않습니다.

처음에는 세 줄이면 충분합니다. 아래는 예시입니다.

# AGENTS.md
- 설명과 답변은 한국어로 써 줘.
- 이 폴더의 index.html 하나로 작업하고 외부 라이브러리는 쓰지 마.
- 파일을 지우거나 이름을 바꾸기 전에는 먼저 물어봐.

무엇을 넣고 뺄지는 CLAUDE.md 작성법의 기준이 AGENTS.md에도 그대로 통합니다.

모델 고르기: 모델 메뉴와 /model

모델은 진입점마다 바꾸는 곳이 다릅니다. 모델 문서 기준입니다.

• 데스크톱 앱: 입력창 아래의 모델·추론 조절 메뉴에서 고릅니다. 기본 설정에서 Smarter 쪽으로 옮기면 더 깊게 생각하고 Faster 쪽으로 옮기면 빠르고 한도를 덜 씁니다. Advanced를 열면 모델과 추론 강도를 직접 고를 수 있어요.
• CLI: 대화 중에 /model을 입력해 바꾸고 /status로 확인합니다. 시작할 때 codex --model gpt-6.1-sol처럼 정할 수도 있습니다.
• IDE 확장: 입력창 아래의 모델 선택 메뉴를 씁니다.
• 기본값 고정: config.toml에 model = "gpt-6.1-sol"처럼 적으면 앱·CLI·IDE 확장이 같이 따릅니다.

문서의 권장은 복잡한 코딩과 여러 단계짜리 작업에는 GPT-6.1 Sol, 기준이 분명한 반복 작업에는 GPT-6 Luna입니다. GPT-6 Astra는 가장 강한 모델이고 같은 한도를 더 빨리 씁니다. Plus에서는 Astra 사용량이 제한적이에요. Free·Go는 데스크톱 앱에서 GPT-6 Luna와 이전 세대 GPT-5.6 Terra(제한적)를 쓰는 구성입니다. GPT-6.1 Sol은 Plus·Pro·Business·Enterprise·Edu에 순차 공개 중이고 Enterprise·Edu는 관리자가 켜야 씁니다. Free·Go는 출시 대상이 아닙니다. 메뉴에 없는 모델은 아직 내 계정에 열리지 않은 것이니 보이는 모델로 진행하면 됩니다.

GPT-5.5는 2026년 10월 14일(태평양 시간 정오)부터 ChatGPT 계정으로 로그인한 Codex에서 빠졌습니다. ChatGPT 계정으로 쓰는 설정이나 스크립트에 gpt-5.5가 남아 있다면 바꿔 주세요. API 키로 로그인한 Codex는 영향이 없습니다.

저는 Codex CLI 리뷰의 기본 모델을 9월 30일부터 GPT-6.1 Sol로 두고 중요한 리뷰만 GPT-6 Astra를 지정해서 돌립니다. 구독 한도 안에서 쓰므로 모델을 바꿔도 따로 결제하지는 않아요. 다만 요금 문서에 따르면 모델과 작업 크기에 따라 사용 한도가 줄어드는 속도가 다릅니다. 두 모델을 언제 나눠 쓰는지는 GPT-6.1 Sol과 Astra 비교에 정리했습니다.

MCP 연결: 노션·GitHub 붙이기

Codex가 노션 문서를 읽거나 GitHub 이슈를 보게 하려면 MCP(AI 에이전트에 외부 도구를 연결하는 표준 방식) 서버를 붙입니다. MCP 문서에 따르면 길은 세 가지입니다.

• 데스크톱 앱: Settings에서 MCP servers를 열고 Add server를 누릅니다. 이름과 방식(STDIO 또는 Streamable HTTP), 실행 명령이나 주소를 넣고 저장한 뒤 Restart를 누릅니다.
• CLI: codex mcp add <이름> --url <주소>처럼 명령으로 추가합니다.
• 설정 파일: ~/.codex/config.toml에 직접 적습니다.

어느 길로 추가해도 같은 설정 파일에 들어가서 앱과 CLI가 함께 씁니다. 연결됐는지는 입력창에 /mcp를 쳐서 확인해요. 노션·GitHub 공식 서버를 붙이는 순서와 토큰 보관법, 401 인증 오류가 났을 때 볼 곳은 Codex MCP 연결 방법에 있습니다.

Codex Cloud: 내 컴퓨터가 잠들어도 이어지는 작업

Codex Cloud는 코딩 작업을 OpenAI 쪽 작업 공간에서 돌리는 방식입니다. 작업마다 따로 작업 공간이 생기고 내 컴퓨터가 잠들어 있어도 작업이 계속됩니다. 웹, 휴대폰, 데스크톱 앱 어디서든 결과를 보고 이어서 시킬 수 있어요.

시작하는 순서는 이렇습니다.

1. 웹이나 데스크톱 앱에서 새 작업을 열고 Work in > Cloud를 고른 뒤 Select environment를 엽니다.
2. Create environment를 눌러 작업할 GitHub 저장소를 고릅니다. GitHub 연결을 요청하면 연결합니다.
3. Get started를 누르면 Codex가 저장소를 살펴보고 필요한 도구를 설치하고 실행해 봅니다. 빠진 접근 권한이나 정보는 물어봅니다.
4. 준비 결과를 확인하고 Publish를 누릅니다. 이렇게 발행한 환경(environment)은 다음 작업에서도 다시 씁니다.
5. Start a new task로 할 일을 보냅니다. 결과와 테스트를 본 뒤 커밋하거나 풀 리퀘스트를 엽니다.

클라우드 환경 문서 기준으로 Plus 작업 공간은 기본 2 vCPU(가상 CPU 2개)·메모리 8GiB입니다. 새로 만드는 클라우드 환경에서는 브라우저·컴퓨터 사용, GitLab, 자체 운영 GitHub Enterprise Server가 아직 지원 목록에 없어요. GitLab은 머지 리퀘스트 리뷰 같은 연동이 별도 베타로 나와 있습니다.

내 컴퓨터의 파일, 실행 중인 프로그램, 브라우저 로그인은 클라우드로 자동으로 넘어가지 않아요. 요금 문서는 클라우드 작업이 로컬 메시지보다 한도를 더 쓸 수 있다고 적어 두었습니다.

그래서 GitHub를 아직 쓰지 않는 단계라면 클라우드는 나중으로 미뤄도 됩니다. 터미널에서는 codex cloud로 클라우드 작업을 보내고 목록을 확인할 수 있습니다.

'항상 켜진 에이전트'는 Codex가 아니라 ChatGPT Dots입니다

코덱스의 '항상 켜진 모드'를 찾고 있다면 공식 DevDay 2026 정리(9월 29일)에서 그 설명이 붙은 것은 Codex가 아니라 ChatGPT Dots(닷)입니다. 공식 설명은 "계속 맡은 일을 하는 항상 켜진 에이전트(always-on agents)"입니다. 자기 클라우드 컴퓨터에서 연결된 앱을 쓰며 대화 사이에도 일을 진행하고 필요하면 일을 ChatGPT Work나 Codex에 넘기기도 해요. Codex의 모드가 아니라 ChatGPT의 별도 기능입니다.

2026년 10월 16일 dots 도움말 기준으로 Pro 100·200·500은 유럽 경제 지역(EEA)·스위스·영국 밖에 있는 18세 이상 사용자가 대상입니다. Business Premium은 ChatGPT 지원 지역 전체에 순차 공개 중이고 Enterprise(Edu·Healthcare 포함)는 관리자가 켜야 쓰는 베타입니다. dots 문서에 따르면 dot과의 대화는 ChatGPT 사용 한도에 들어가지 않지만 dot이 Work나 Codex에 맡긴 작업은 그쪽 한도를 씁니다. 자세한 내용은 ChatGPT Dots 사용법과 항상 켜진 AI 에이전트 비교에 있습니다.

무엇으로 시작할까: 상황별 정리

마지막 줄은 Codex가 아니지만 같은 앱 안에 있어서 함께 적었습니다. 사용 안내는 문서·발표 자료·스프레드시트·Sites 같은 결과물은 ChatGPT Work, 코드와 개발 도구가 필요한 일은 Codex로 나눕니다. 두 기능은 겹치는 부분이 있어서 Codex로 문서 작업을 이어 해도 됩니다.

Claude Code를 이미 쓰고 있다면 둘 중 무엇을 주 도구로 할지가 다음 질문일 텐데요. 그 비교는 클로드 코드 vs 코덱스에 따로 썼습니다.

자주 묻는 질문

코덱스는 무료로 쓸 수 있나요?

요금 문서상 Free 플랜에도 데스크톱 앱의 Codex가 들어 있습니다. 다만 데스크톱 앱에서 GPT-6 Luna와 이전 세대 GPT-5.6 Terra(제한적)를 쓰는 구성이고 GPT-6 Luna는 모든 계정에 한 번에 열리지는 않습니다. 요금 문서에서 CLI·IDE 확장·클라우드는 Plus 항목부터 나와요. 남은 한도는 사용량 대시보드에서 봅니다.

한국에서도 쓸 수 있나요?

공식 What's new의 7월 9일 공지는 Codex가 합쳐진 macOS·Windows용 새 데스크톱 앱을 Free를 포함한 모든 ChatGPT 플랜에서 전 세계에 제공한다고 적었습니다. Linux 앱은 8월부터 미리보기로 나왔습니다. 결제 통화와 부가세는 결제 화면에서 확인하세요.

앱과 CLI를 둘 다 쓰면 설정을 두 번 해야 하나요?

아닙니다. 데스크톱 앱, CLI, IDE 확장은 같은 config.toml과 AGENTS.md를 읽습니다. Windows는 %USERPROFILE%\.codex를 씁니다. WSL 안에서 CLI를 따로 돌리면 리눅스 쪽 홈 폴더를 써서 설정이 자동으로 공유되지 않는다는 점만 예외입니다.

Codex CLI는 어떻게 설치하나요?

Codex CLI 문서의 설치 명령은 다음과 같습니다. 설치 뒤 프로젝트 폴더에서 codex를 실행하고 Sign in with ChatGPT를 고릅니다.

# macOS·Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex

Windows는 새 PowerShell 창에서 실행합니다.

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

IDE 확장은 어디서 받나요?

VS Code·Cursor·Windsurf는 Codex 확장을 설치하고 사이드바의 Codex 아이콘을 누릅니다. 아이콘이 안 보이면 명령 팔레트에서 Codex: Open Codex Sidebar를 실행합니다. JetBrains IDE는 AI Chat을 열어 Codex를 고릅니다. Xcode는 코딩 어시스턴트에서 새 대화를 열어 Codex를 에이전트로 고릅니다(IDE 확장 문서).

다음 단계

• 데스크톱 앱 설치부터 첫 페이지까지: 코덱스(Codex) 데스크톱 앱 설치와 사용법
• 노션·GitHub 연결: Codex MCP 연결 방법
• 플랜과 한도: 코덱스 요금제 정리
• 모델 나눠 쓰기: GPT-6.1 Sol과 Astra 비교
• Claude Code와 비교: 클로드 코드 vs 코덱스
• 만든 페이지를 공개하는 순서: 첫 홈페이지 만들기: Next.js 생성부터 Vercel 배포까지

출처와 확인 (2026-10-16)

• Quickstart (데스크톱 앱 설치·로그인·Codex 선택, 다운로드 버튼의 macOS Apple silicon·Intel, Windows, Linux 항목, CLI·IDE·클라우드 안내)
• ChatGPT desktop app (다운로드 위치, 시작 순서)
• Download ChatGPT (OS에 맞춘 다운로드 버튼, 하단 ChatGPT Classic 링크. Mac 브라우저로 확인)
• ChatGPT desktop app for Windows (Codex 홈 폴더, WSL)
• Windows sandbox (Windows 11 권장)
• ChatGPT desktop app for Linux (미리보기)
• Pricing (플랜별 진입점, API 키 조건, 사용 한도와 클라우드 작업)
• ChatGPT Plans and Pricing · OpenAI Help: GPT-6 and other models in ChatGPT (Free·Go의 GPT-5.6 Terra 제한적 제공)
• OpenAI Help: ChatGPT Work and Codex (Plus의 Astra 사용량 제한)
• Codex CLI (설치 명령, 로그인)
• Command line options (/model, /permissions, /init, /status, /app, codex cloud)
• Codex IDE extension (지원 에디터, 확장 설치)
• Permissions (권한 모드 네 가지와 설명)
• Auto-review (Approve for me 동작, 데스크톱 앱 /model)
• Custom instructions with AGENTS.md (읽는 순서, 32KiB 한도)
• Settings (Personalization의 AGENTS.md)
• Models (모델 선택 위치, 권장 모델, GPT-6.1 Sol 공개 범위, GPT-5.5 종료, config.toml 공유)
• Model Context Protocol (앱·CLI·설정 파일 경로, /mcp)
• Codex Cloud, Cloud environments, Codex environments (시작 순서, 작업 공간 사양, 지원하지 않는 기능, Work in·Worktree)
• Review GitLab merge requests with Codex (GitLab 베타 연동)
• Use ChatGPT (ChatGPT Work와 Codex 구분)
• What's new (7월 9일 데스크톱 앱 통합과 전 세계 제공), DevDay 2026 (9월 29일 dots 발표)
• Meet dots (dots 설명, 한도)
• OpenAI Help: Getting started with your dot (Pro·Business Premium·Enterprise 제공 지역과 조건)