코덱스 시작하기

1.1챗봇이 아니라 코딩 에이전트

공식코덱스(Codex)는 코드를 읽고, 파일을 고치고, 명령을 실행하고, 결과를 확인하는 일을 스스로 도는 코딩 에이전트입니다. 공식 문서는 코덱스 CLI를 "코드를 살펴보고, 변경하고, 명령을 실행하고, 반복 작업을 자동화하는" 도구로 소개합니다. codex/cli

대화창에 붙여 넣을 코드를 받아 오는 것과 이 방식은 결과물이 다릅니다. 답을 받아 사람이 옮겨 적는 대신, 작업 디렉터리 안에서 변경이 일어나고 사용자는 그 변경을 검토합니다. 그래서 처음 배울 것도 프롬프트 기교가 아니라 무엇을 맡기고 어디서 멈춰 세울지입니다.

1.2코덱스와 ChatGPT의 관계

공식코덱스 문서는 ChatGPT 문서와 한 세트로 learn.chatgpt.com/docs에 있습니다. 데스크톱 앱에서는 ChatGPT 드롭다운에서 Codex를 골라 코덱스 채팅을 시작하고, 같은 앱 안에서 Chat과 Work라는 다른 갈래도 씁니다. quickstart environments/modes

공식세 갈래의 쓰임은 이렇게 갈립니다. Chat은 질문과 탐색, Work는 문서·발표자료·스프레드시트 같은 산출물, Codex는 코드베이스 맥락과 개발 도구가 필요한 소프트웨어 작업입니다. docs use-chatgpt get-started-with-work features

1.3잘하는 일과 못하는 일

공식공식 베스트 프랙티스는 코덱스를 "일회성 비서보다는 시간을 들여 설정하고 개선하는 팀원"으로 다루라고 명시합니다. 프롬프트가 완벽하지 않아도 쓸 만한 결과가 나오지만, 큰 저장소나 위험이 큰 작업일수록 맥락을 제대로 주는 것이 결과의 신뢰도를 결정합니다. best-practices

공식공식 문서는 처음 쓰는 사람이 저지르는 실수 목록도 함께 제시합니다. 그중 첫날부터 피할 수 있는 것 셋은 이렇습니다. 워크플로를 이해하기 전에 컴퓨터 전체 권한을 주는 것, 여러 작업을 워크트리 없이 같은 파일 위에서 동시에 돌리는 것, 프로젝트 전체를 채팅 하나에 몰아넣는 것. best-practices

1.4용어 최소 세트

공식공식 용어집은 표면별로 100개가 넘는 항목을 담고 있습니다. 첫날 필요한 것은 다섯 개입니다. glossary

공식승인과 샌드박스는 서로 다른 축입니다. 공식 문서는 "누가 요청을 검토하는지를 바꾼다고 해서 샌드박스가 넓어지지는 않는다"고 못박습니다. 이 구분이 L2 맥락과 통제의 뼈대가 됩니다. permission-modes

1.5성숙도 라벨 읽는 법

공식일부 기능은 성숙도 라벨을 달고 출시됩니다. 문서에서 이 라벨을 보면 그 기능에 얼마나 기대를 걸어도 되는지가 정해집니다. feature-maturity

2.18개 표면 지도

공식코덱스는 한 엔진을 여러 입구에서 씁니다. 입구가 달라도 AGENTS.md, config.toml, 스킬, 플러그인, MCP, 승인 정책은 공유됩니다. 공식 문서는 "CLI, IDE 확장, ChatGPT 데스크톱 앱이 모두 같은 설정 계층을 쓴다"고 명시합니다. best-practices

각 표면의 근거 문서는 순서대로 codex/cli codex/ide app cloud remote third-party/github third-party/slack third-party/linear 입니다.

2.2처음이면 무엇으로

공식공식 퀵스타트는 갈림길을 이렇게 안내합니다. 터미널이나 코드 에디터에서 코덱스를 쓰고 싶은 개발자는 코덱스 CLI 또는 IDE 확장으로, 프로젝트와 로컬 파일과 긴 작업을 다루려는 사람은 데스크톱 앱으로 갑니다. quickstart

관행실제 선택은 이미 어디서 일하고 있는가로 갈리는 편이 실패가 적습니다. 하루 대부분을 터미널에서 보낸다면 CLI, 에디터에서 보낸다면 IDE 확장, 여러 저장소를 오가며 병렬로 굴린다면 데스크톱 앱입니다. 셋은 배타적이지 않고 설정을 공유하므로, 하나로 시작한 뒤 나중에 늘려도 다시 배울 것이 거의 없습니다.

2.3요금제와 기능 가용성

공식코덱스는 ChatGPT Free·Go·Plus·Pro·Business·Edu·Enterprise 플랜에 포함됩니다. 별도 구독이 아니라 기존 플랜의 사용량을 씁니다. pricing

공식플랜과 인증 방식에 따라 쓸 수 있는 것이 갈립니다. 첫날 알아야 할 갈림은 셋입니다. pricing auth

공식API 키로 로그인하면 과금도 달라집니다. ChatGPT 플랜 크레딧이 아니라 OpenAI 플랫폼 계정의 표준 API 요금이 청구됩니다. auth

표면별 가용성 전체 대조표는 색인 편 부록 C에 있습니다.

2.4모델 고르기 첫 판단

공식2026년 8월 기준 권장 모델은 GPT-5.6 계열 셋입니다. Sol은 복잡하고 열린 작업, Terra는 일상 작업의 기본값, Luna는 명확하고 반복적인 작업입니다. 무엇을 고를지 모르겠으면 Sol로 시작하라고 문서가 명시합니다. models

공식추론 강도는 결과에 필요한 최소값을 쓰는 것이 원칙입니다. CLI에서는 Low·Medium·High·Extra High로, 데스크톱 앱과 IDE 확장에서는 Light가 CLI의 Low에 해당합니다. models

CLI에서 모델을 지정하며 시작

# 대화형 세션 안에서는 /model 로 바꿉니다
codex --model gpt-5.6

# 비대화 실행에도 같은 옵션이 붙습니다
codex exec -m gpt-5.6 "Review the current changes"

모델 선택과 속도의 교환은 L1 11장에서 다시 다룹니다. 지금은 기본값으로 두고 넘어가도 됩니다.

3.1CLI 설치 4경로

공식코덱스 CLI 설치 방법은 네 가지이고, 갱신 명령이 설치 명령과 같은 경우가 많습니다. codex/cli

macOS · Linux 설치 스크립트 (설치와 갱신이 같은 명령)

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows PowerShell 설치 스크립트 (설치와 갱신이 같은 명령)

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

npm

npm install -g @openai/codex

Homebrew

# 설치
brew install --cask codex

# 갱신
brew upgrade --cask codex

관행맥에서 이미 Homebrew로 다른 개발 도구를 관리하고 있다면 Homebrew 경로가 갱신 추적에 유리합니다. 그렇지 않다면 설치 스크립트 한 줄이 가장 짧습니다. npm 경로는 Node 버전 관리자를 여러 개 쓰는 환경에서 전역 설치 위치가 흔들릴 수 있어, 그 환경에서는 앞의 두 경로를 권합니다.

3.2IDE 확장 설치

공식VS Code와 호환 에디터는 코덱스 확장을 설치하고, Xcode와 JetBrains 계열은 각자의 통합을 씁니다. codex/ide

공식IDE 확장의 값은 이미 열려 있는 맥락을 그대로 쓰는 데 있습니다. 열린 파일, 선택한 코드, 최근 채팅을 컴포저에서 바로 참조하므로 문제를 다시 설명하는 시간이 줄어듭니다. codex/ide

3.3데스크톱 앱 설치

공식ChatGPT 데스크톱 앱은 Windows와 macOS용으로 제공됩니다. 설치하고 로그인한 뒤, 채팅을 시작하거나 프로젝트를 만들거나 폴더를 엽니다. 코덱스는 ChatGPT 드롭다운에서 Codex를 선택해 시작합니다. app quickstart

공식윈도우에서는 명령줄 설치도 됩니다. windows/windows-app

Windows PowerShell

winget install --id 9PLM9XGG6VKS -s msstore

공식데스크톱 앱에서 코덱스 채팅을 시작할 때는 어디서 돌릴지를 함께 고릅니다. 로컬·워크트리·클라우드 셋이고, 앞의 둘은 사용자 컴퓨터에서 돕니다. 이 선택이 L4 오케스트레이션의 주축입니다. environments/modes

3.4윈도우 사용자의 갈림길

공식데스크톱 앱은 기본적으로 윈도우 네이티브 에이전트를 씁니다. 즉 명령을 PowerShell에서 실행하고, 네이티브 윈도우 샌드박스가 걸립니다. 에이전트 자체를 WSL2에서 돌리려면 설정에서 바꾸고 앱을 재시작해야 하며, 재시작 전에는 변경이 적용되지 않습니다. windows/windows-app

공식통합 터미널은 에이전트와 별개로 고릅니다. 에이전트는 WSL에 두고 터미널은 PowerShell을 쓰는 조합도 됩니다. 터미널 선택지는 PowerShell·명령 프롬프트·Git Bash·WSL이고, 바꾼 값은 새 터미널 세션부터 적용됩니다. windows/windows-app

공식윈도우에서 코덱스가 제 성능을 내려면 개발 도구 몇 개가 먼저 깔려 있어야 합니다. Git은 앱의 리뷰 패널을 움직이고, GitHub CLI는 GitHub 기능을 켭니다. windows/windows-app

Windows PowerShell

winget install --id Git.Git
winget install --id OpenJS.NodeJS.LTS
winget install --id Python.Python.3.14
winget install --id GitHub.cli

# GitHub CLI 설치 후 인증까지 해야 앱의 GitHub 기능이 켜집니다
gh auth login

3.5인증 경로

공식로그인 방법은 둘입니다. 구독을 쓰는 ChatGPT 로그인과 사용량 과금을 쓰는 API 키 로그인. 데스크톱 앱·CLI·IDE 확장은 둘 다 지원하고, 클라우드는 ChatGPT 로그인만 됩니다. auth

CLI 로그인과 상태 확인

# 브라우저 흐름으로 ChatGPT 로그인
codex login

# API 키는 표준 입력으로 넘깁니다(명령줄 인자로 노출하지 않습니다)
printenv OPENAI_API_KEY | codex login --with-api-key

# 현재 인증 방식 확인 / 자격증명 지우기
codex login status
codex logout

공식로그인 방식은 편의 문제가 아니라 어떤 관리 통제와 데이터 정책이 적용되는지를 결정합니다. ChatGPT 로그인이면 ChatGPT 워크스페이스 권한과 역할 기반 접근 제어, 엔터프라이즈 보존·거주 설정을 따르고, API 키면 API 조직의 보존·공유 설정을 따릅니다. auth

공식자격증명은 ~/.codex/auth.json 평문 파일이나 OS 자격증명 저장소에 캐시됩니다. CLI와 IDE 확장은 같은 캐시를 공유하므로 한쪽에서 로그아웃하면 다른 쪽도 다시 로그인해야 합니다. 저장 위치는 설정으로 고를 수 있습니다. auth

config.toml

# file | keyring | auto
cli_auth_credentials_store = "keyring"

공식브라우저를 열 수 없는 원격·헤드리스 환경에서는 기기 코드 인증(베타)이 권장 경로입니다. 대화형 로그인 화면에서 Sign in with Device Code를 고르거나 codex login --device-auth를 직접 실행합니다. 먼저 ChatGPT 보안 설정(개인) 또는 워크스페이스 권한(관리자)에서 기기 코드 로그인을 켜 두어야 합니다. auth

공식기기 코드가 안 되는 환경의 대안은 둘입니다. 브라우저가 되는 기기에서 로그인한 뒤 auth.json을 복사하거나, SSH 포트 포워딩으로 콜백(localhost:1455)을 넘기는 방법입니다. auth

SSH 포트 포워딩으로 브라우저 로그인 흐름 쓰기

ssh -L 1455:localhost:1455 user@remote
# 이 SSH 세션 안에서 codex login 을 실행하고, 출력된 주소를 로컬 브라우저에서 엽니다

3.6다른 에이전트에서 이관

공식코덱스 CLI와 데스크톱 앱은 Claude Code에서 설정과 최근 작업을 가져올 수 있습니다. 가져오기는 기존 설정을 바꾸거나 지우지 않습니다. import

CLI에서

# 로컬 CLI 세션 안에서 실행합니다
/import

공식CLI 가져오기는 최근 30일 채팅을 최대 50개까지 가져옵니다. 작업이 도는 중이거나 원격 세션이거나 로컬 앱 서버 데몬에 연결된 상태에서는 /import를 쓸 수 없습니다. import

공식가져온 뒤 그대로 믿지 말고 먼저 볼 것이 있습니다. 스킬과 에이전트의 도구 제한·권한, 커스텀 인증이나 헤더를 쓰는 MCP 서버 설정, 동작이 달라질 수 있는 훅, 인자나 셸 치환에 의존하던 프롬프트 템플릿입니다. import

3.7설치가 막힐 때

증상별 대응 전체는 색인 편 부록 D와 공식 트러블슈팅 문서에 있습니다. reference/troubleshooting

4.1첫 프롬프트에서 승인까지

공식프로젝트 디렉터리를 열고 codex를 실행합니다. 처음 실행하면 로그인 방법을 고르는 화면이 먼저 나옵니다. 그다음 하고 싶은 것을 설명합니다. 공식 문서가 제시하는 첫 지시는 이렇습니다. codex/cli

터미널

cd your-project
codex

첫 프롬프트

Tell me about this project

관행첫 지시를 "무언가를 고쳐라"로 시작하지 않는 편이 좋습니다. 코덱스가 저장소를 어떻게 읽는지, 어떤 파일을 먼저 여는지, 어디서 승인을 묻는지를 먼저 보고 나면 두 번째 지시의 범위를 훨씬 정확하게 잡을 수 있습니다.

공식실제 작업 지시에는 네 가지를 담는 것이 좋은 기본값입니다. 목표(무엇을 바꾸려는가), 맥락(어떤 파일·문서·에러가 관련되는가), 제약(어떤 규약을 따라야 하는가), 완료 조건(무엇이 참이면 끝인가). best-practices

4.2승인 화면 읽는 법

공식승인 모드는 코덱스가 스스로 할 수 있는 것과 검토가 필요한 것의 경계를 정합니다. 대부분의 작업은 Ask for approval(승인 요청)로 시작하라고 공식 문서가 권합니다. 현재 작업 공간 안에서는 일하고, 그 경계를 넘으려 할 때 멈춥니다. permission-modes

공식여기서 두 축이 함께 움직인다는 것을 알아 두면 나중에 헷갈리지 않습니다. 샌드박스가 닿을 수 있는 파일과 네트워크를 정하고, 승인이 언제 멈춰 물을지를 정합니다. 검토 주체를 바꾸는 것(예: Approve for me)은 샌드박스를 넓히지 않습니다. 같은 경계를 유지한 채 경계를 넘는 요청을 자동 검토로 보낼 뿐입니다. permission-modes

공식승인 모드를 여는 곳은 표면마다 다릅니다. 데스크톱 앱과 IDE 확장은 컴포저 아래의 권한 컨트롤, CLI는 /permissions입니다. permission-modes

공식데스크톱 앱을 처음 쓰면 Ask for approval만 켜져 있습니다. Approve for me(설정에서는 Auto-review)나 Full access를 메뉴에 추가하려면 Settings > General의 Permissions에서 켜야 합니다. 켜는 것은 메뉴에 나타나게 할 뿐이고, 모드를 선택하거나 진행 중인 채팅을 바꾸지는 않습니다. permission-modes

4.3첫날 안전장치

공식공식 문서가 CLI와 IDE 확장 양쪽의 시작 절차에서 같은 문장을 반복합니다. 작업 전후로 git 체크포인트를 만들어 되돌릴 수 있게 하라는 것입니다. codex/cli codex/ide

작업 전

# 지금 상태가 깨끗한지 먼저 봅니다
git status

# 커밋되지 않은 것이 있으면 여기서 한 번 묶어 둡니다
git add -A && git commit -m "checkpoint: before codex"

관행이 한 줄이 첫 주의 사고를 대부분 막습니다. 승인 화면을 읽는 눈이 아직 없는 동안에는 "잘못되면 되돌린다"가 유일하게 확실한 안전장치이기 때문입니다. 코덱스가 만든 변경만 골라 되돌리려 할 때도 직전 커밋이 있으면 git diff 한 번으로 범위가 보입니다.

4.4첫 커밋

공식변경을 받았으면 그대로 커밋하지 말고 먼저 봅니다. 코덱스에는 전용 리뷰 경로가 있어서, 커밋하지 않은 변경이나 특정 커밋, 베이스 브랜치와의 차이를 대상으로 리뷰를 돌릴 수 있습니다. 리뷰는 작업 트리를 고치지 않고 우선순위가 매겨진 지적만 냅니다. code-review

CLI 세션 안에서

/review

공식공식 베스트 프랙티스는 여기서 한 걸음 더 나가라고 합니다. 변경을 요청하는 데서 멈추지 말고, 테스트를 만들게 하고, 관련 검사를 돌리게 하고, 결과를 확인하게 한 뒤 사람이 받아들이라는 것입니다. 그러려면 무엇이 "잘된 상태"인지를 프롬프트나 AGENTS.md가 알려 줘야 합니다. best-practices

4.5알림과 음성

공식작업이 길어지면 화면을 지키고 있을 이유가 없습니다. 데스크톱 앱은 설정에서 턴 완료 알림을 끄기 / 배경일 때만 / 항상 중에 고르게 하고, 권한 요청과 질문 알림은 별도 스위치로 켭니다. 운영체제가 알림 권한을 따로 물을 수 있습니다. notifications

공식사이드바의 벨(Activity 뷰)에서 읽지 않음·실행 중·응답 대기 채팅을 모아 볼 수 있습니다. 단축키는 macOS에서 Cmd+Option+U, 윈도우에서 Ctrl+Alt+U입니다. notifications

공식CLI의 알림은 설정 파일 쪽에 있습니다. 상세는 L2 16장에서 다룹니다. notifications

공식입력이 길어질 때는 음성을 쓸 수 있습니다. 공식 베스트 프랙티스도 맥락을 더 빨리 주는 방법으로 데스크톱 앱의 받아쓰기를 제안합니다. features/voice best-practices

4.6이미지로 맥락 주기

공식에러 스크린샷, 아키텍처 다이어그램, 디자인 시안을 프롬프트에 붙일 수 있습니다. CLI에서는 첫 프롬프트와 함께 codex --image로 넘기거나, 대화형 컴포저에 이미지를 붙여 넣습니다. codex/cli image-inputs

관행가장 값이 큰 쓰임은 말로 옮기기 번거로운 상태를 그대로 넘기는 것입니다. 스택 트레이스가 여러 창에 걸쳐 있을 때, 렌더링이 깨진 화면을 설명해야 할 때, 시안과 구현의 차이를 지적해야 할 때. 이런 상황에서는 문장을 다듬는 것보다 캡처 한 장이 정확합니다.