2026 년 Codex 마스터하기 (빌더를 위한 코스)

저는 12개월 동안 Claude Code를 사용했습니다. 그런 다음 30일 동안 Codex로 전환했습니다.

그 결과 발견한 것들

2026년 Codex의 실제 정체

대부분의 사람들은 여전히 Codex를 더 똑똑한 자동완성 기능이라고 생각합니다. 하지만 그렇지 않습니다.

Codex는 완전한 에이전트형 소프트웨어 개발 플랫폼입니다. 코드베이스를 읽고, 코드를 작성 및 테스트하며, 풀 리퀘스트를 리뷰하고, Mac 데스크톱을 제어하며, 웹을 탐색하고, 이미지를 생성하며, 반복 작업을 예약하고, 세션 간 사용자 환경설정을 기억합니다.
이에 필요한 사고의 전환은 상당합니다. 여러분은 코드를 작성하는 사람에서 멈추지 않고, 잠들지 않는 주니어 엔지니어 팀이 작성한 코드를 리뷰하는 사람이 됩니다.

대부분의 개발자는 Codex를 설치하고, 2주 동안 한 줄 프롬프트를 보내고, 평범한 결과를 얻은 후 포기합니다. AGENTS.md를 설정하지 않습니다.

Skill을 작성하지 않습니다. 서브 에이전트를 사용하지 않습니다. 표면의 5%만 사용하고 그 5%로 도구를 평가합니다.

이 코스에서는 나머지 95%를 다룹니다.

다섯 가지 표면(Surfaces)

무엇이든 설치하기 전에 Codex가 어디에 존재하는지 이해하세요. 선택한 표면에 따라 작업을 얼마나 밀접하게 따라갈지, 코드가 어디서 실행될지가 결정됩니다.

CLI는 스크립팅된 워크플로우, 단일 태스크 작업, 헤드리스 자동화에 사용됩니다. 푸시하지 않는 한 코드가 머신을 떠나지 않습니다. 오픈 소스, Rust로 구축, macOS, Windows, Linux에서 실행됩니다.

IDE 확장 프로그램은 정확한 파일 컨텍스트로 대화형 편집을 위한 것입니다. VS Code, Cursor, Windsurf 또는 JetBrains에 설치됩니다. 별도의 로그인 없이 CLI 인증을 사용합니다.

데스크톱 앱은 멀티 스레드 워크플로우, 인앱 브라우저, Computer Use, Goal 모드, Appshot, Automations의 본거지입니다. 2026년 2월 macOS에, 2026년 3월 4일 Windows에 출시되었습니다.

Cloud는 비동기 백그라운드 작업, 병렬 PR, 사용자가 잠든 사이에 작업을 처리합니다. 작업은 GitHub 리포지토리가 미리 로드된 샌드박스 컨테이너에서 실행됩니다. 로컬 머신을 차단하지 않습니다.

인앱 브라우저와 Computer Use는 UI 검증, 프론트엔드 반복 작업, 엔드투엔드 테스트를 위한 것입니다. Codex가 로컬 개발 서버를 열고, 상호 작용하고, 결과를 스크린샷으로 캡처하고, 코드 변경이 올바른 시각적 출력을 생성했는지 확인합니다.

실제 워크플로우는 여러 표면을 사용합니다:

CLI - 스크립팅된 작업용
IDE - 대화형 기능 작업용
Cloud - 지켜볼 필요 없는 병렬 작업용
App - Goal 중심의 장기 실행 작업용

표면을 선택할 때 주요 고려 사항은 에이전트의 작업을 얼마나 밀접하게 따라갈지입니다. 변경 사항이 만들어지는 즉시 모니터링하려면 CLI나 IDE가 작업을 머신에서 눈앞에 유지합니다. 더 긴 세션을 위임하고 마지막에 검토하려면 Cloud가 올바른 선택입니다.

멘탈 모델: 자동완성이 아닌 에이전트

표면이 명확해졌으니, 다음 전환은 작업 단위를 이해하는 것입니다.

작업 단위는 턴(turn)이 아닌 태스크(task)입니다. 출력물은 채팅 응답이 아닌 PR입니다.

"X를 하는 함수를 작성해"보다는 "Y 기능을 구현해, 여기 제약 조건이 있고, 완료되면 테스트를 실행해"라고 생각하세요.

모든 Codex 태스크는 동일한 내부 루프를 따릅니다. Codex가 태스크와 컨텍스트를 읽고, 내부 계획을 수립하고, 단계별로 실행하며, 자신의 작업을 확인합니다.

Codex를 코딩 어시스턴트로 생각하지 마세요. 아침에 브리핑하고 오후에 리뷰하는 주니어 엔지니어 팀으로 생각하기 시작하세요.

실제 사례: WorkOS의 개발자들은 이제 아침 커피를 마시기 전에 4~5개의 Codex 태스크를 큐에 넣습니다. 다시 앉았을 때쯤이면 2~3개의 완료된 PR이 리뷰를 기다리고 있으며, 이전에 하루의 30~40%를 소모했던 유지보수 작업을 처리하고 있습니다.

2026년 5월 기준 현재 모델:

GPT-5.5 (기본값) — 대부분의 작업 처리, 이전과 동일한 지연 시간이지만 동일한 작업에 훨씬 적은 토큰 사용
GPT-5.3-Codex — 긴 자율 실행, 대규모 리팩토링, 병렬 클라우드 팬아웃에 특화됨; 이전 Codex 전문 모델보다 25% 빠름
GPT-5.5 Pro — 가장 높은 추론 능력; Pro, Business, Enterprise 요금제 전용
Codex Mini — ChatGPT Free에서 영구 무료; 학습용으로 적합

Codex는 기본적으로 GPT-5.5로 두세요. Codex가 오랫동안 자율적으로 실행되는 큰 에이전트 작업에는 GPT-5.3-Codex로 전환하세요.

시작하기: 첫 번째 실제 세션

작동하는 Codex 세션을 위한 가장 빠른 경로는 다섯 단계를 따릅니다. Fizzbuzz 튜토리얼은 잊어버리세요. 실제 코드베이스에서 시작하세요.

1단계: CLI를 설치합니다.

2단계: 실제 프로젝트를 엽니다.

이미 잘 알고 있는 위험이 낮은 리포지토리로 이동하세요. 이것이 중요합니다.

Codex는 출력을 인식하고 실수를 잡을 수 있을 때 더 잘 수행합니다. 익숙하지 않은 코드베이스에서 첫 세션을 진행하면 예측할 수 없는 결과가 발생합니다.

메시지가 표시되면 ChatGPT 계정으로 로그인하세요. 브라우저가 자동으로 열립니다. 계속을 클릭하고 터미널로 돌아갑니다.

3단계: 다른 작업을 하기 전에 /init을 실행합니다.

대부분의 튜토리얼이 건너뛰는 단일 명령어입니다. Codex가 디렉토리와 Git 기록을 스캔하고, 언어, 프레임워크, 빌드 명령어, 테스트 명령어를 식별하고, 찾은 내용으로 채워진 AGENTS.md 파일을 생성합니다.

생성된 파일을 검토하고, 잘못된 부분을 조정한 후 커밋하세요. 이 프로젝트의 모든 향후 Codex 세션에서 자동으로 읽힙니다.

4단계: Codex에 오리엔테이션 태스크를 제공합니다.

무언가를 변경하라고 하기 전에 코드베이스를 설명하도록 요청하세요. 이렇게 하면 로드된 컨텍스트에 대한 확신이 생깁니다:

출력을 읽으세요. 실제 코드베이스를 정확하게 설명한다면 필요한 컨텍스트를 가지고 있는 것입니다. 모호하거나 틀리다면 AGENTS.md에 더 많은 세부 정보가 필요합니다.

5단계: 하나의 작은 실제 태스크를 제공합니다. 구체적이고 범위가 정해진 것을 선택하세요.

이것이 올바른 Codex 프롬프트의 형태입니다: 특정 파일 컨텍스트, 예상 결과, 제약 조건, 정의된 검증 단계. 반환된 diff를 검토하세요. 이제 Codex를 제대로 사용하고 있는 것입니다.

6단계: 데스크톱 앱을 설치합니다. OpenAI 웹사이트에서 다운로드하세요. 동일한 ChatGPT 계정으로 로그인하세요.

7단계: IDE 확장 프로그램을 설치합니다. 에디터의 확장 프로그램 패널에서 "OpenAI Codex"를 검색하세요. CLI 인증을 자동으로 읽습니다.

8단계: GitHub에 연결합니다. Codex 앱 내 설정으로 이동하여 GitHub 계정을 연결하세요. 클라우드 태스크를 사용하기 전에 최소한 하나의 리포지토리를 연결하세요.

파일 위치:

~/.codex/config.toml : 주요 설정: 승인 모드, 샌드박스 모드, MCP 서버, 모델 기본값
~/.codex/AGENTS.md : 개인 AGENTS.md, 모든 프로젝트에 적용
<project>/AGENTS.md : 프로젝트 수준 지침
<project>/.agents/skills/ : 프로젝트 수준 스킬
<project>/.codex/config.toml : 프로젝트 범위 설정 (신뢰할 수 있는 프로젝트만)

AGENTS.md: 리포지토리에서 가장 중요한 파일

이제 작동하는 세션이 있으니, 다음 단계는 모든 향후 세션이 동일한 품질로 시작되도록 하는 것입니다. 이것이 AGENTS.md가 하는 일입니다.

AGENTS.md는 평범한 Codex 출력과 일관된 고품질 출력을 구분하는 단일 파일입니다.
리포지토리 루트에 있는 일반 Markdown 파일입니다. 프로젝트에서 Codex 세션이 시작될 때마다 에이전트가 다른 작업을 하기 전에 자동으로 읽습니다.
오픈 표준입니다. Codex, Cursor, Gemini CLI, Windsurf, GitHub Copilot 모두 읽습니다. 한 번 작성하면 툴체인의 모든 에이전트가 동일한 진실 공급원을 읽습니다.

해석 순서: Codex가 ~/.codex/AGENTS.md (홈 레벨, 모든 프로젝트)와 <project>/AGENTS.md (프로젝트 레벨)를 읽습니다. AGENTS.override.md 파일이 각 레벨에서 우선순위를 가집니다. 결합 제한은 32KiB입니다.

포함할 내용:

스택, 프레임워크, 언어 버전, 패키지 매니저
정확한 빌드, 테스트, 개발 명령어; 복사하여 붙여넣을 수 있어야 함, "평소 테스트 실행"이 아님
파일 구조 규칙 및 네이밍 규칙
스타일 및 패턴 규칙
금지 구역: 건드리지 말아야 할 것
출시 요구 사항: CI, PR 규칙, 배포 메커니즘

포함하지 말아야 할 내용:

비밀 또는 자격 증명 (파일은 버전 관리에 있음)
모호한 지침 ("깨끗한 코드 작성"은 에이전트에게 의미 없음)
README를 중복하는 문서화

500단어 미만으로 유지하세요. 부풀리면 모델의 작업 기억 공간에서 유용한 컨텍스트가 밀려납니다.

작동 템플릿:

Codex가 읽고 있는지 확인: 현재 로드된 지침을 요약하도록 프롬프트
대규모 모노리포지토리의 경우 서브디렉토리 내에 추가 AGENTS.md 파일 배치
packages/api/AGENTS.md 파일은 해당 패키지 내 태스크에 대해 루트 레벨 파일보다 우선함
codex trust .를 실행하여 프로젝트 레벨 .codex/config.toml을 활성화. 이는 악성 복제 리포지토리가 사용자 모르게 Codex를 구성하는 것을 방지

CLI 심층 분석

AGENTS.md가 설정되었으면, 다음으로 마스터해야 할 것은 CLI 자체입니다. 대부분의 사용자는 codex만 입력하고 진정으로 강력한 명령어를 놓칩니다.

실제 일상 사용의 95%를 커버하는 네 가지 명령어가 있습니다.

codex는 탐색, 반복, 코드베이스와의 주고받기 대화를 위한 대화형 모드를 엽니다.

codex exec "<task>"는 Codex를 비대화형으로 실행합니다. stdout으로 스트리밍하고 완료되면 종료됩니다. 이것은 스크립팅 가능한 모든 것을 위한 강력한 도구입니다:

exec를 git 훅, CI 파이프라인, cron 작업에 연결하세요. 자동화된 모든 것을 위한 빌딩 블록입니다.

codex resume --last는 정확히 중단한 지점부터 다시 시작합니다. 모든 세션이 저장됩니다:

codex cloud는 비동기 클라우드 태스크를 관리합니다. 아래 Cloud 섹션에서 다룹니다.

유용한 플래그:

--json : 다른 도구로 파이프하기 위한 JSONL 이벤트 스트림
--model <name> : GPT-5.5 또는 GPT-5.3-Codex 선택
--reasoning <level> : low, medium, high
--search : 태스크 중 웹 검색 허용
-C <dir> : 다른 작업 디렉토리에서 실행
--sandbox <mode> : 이 세션의 샌드박스 모드 재정의
--approval <policy> : 이 세션의 승인 정책 재정의

샌드박스 및 승인

CLI는 강력함을 제공합니다. 샌드박스는 Codex가 허락 없이 행사할 수 있는 권한의 정도를 제어합니다. 이를 올바르게 설정하면 위험을 만들지 않고 워크플로우를 빠르게 유지할 수 있습니다.

샌드박스는 Codex가 할 수 있는 것과 없는 것을 제어하는 경계입니다. 올바르게 설정하면 놀라움을 방지할 수 있습니다.

세 가지 샌드박스 모드:

workspace-write (기본값) : 작업 공간 내 읽기 및 쓰기, 일상적인 명령어, 허용되지 않는 한 네트워크 없음. 거의 항상 사용.
read-only : 읽기 전용, 쓰기 없음, 셸 없음. 코드 리뷰 및 탐색에 사용.
danger-full-access : 제한 없음. 거의 사용하지 않음. 테스트되고 검증된 자동화를 위해 예약.

두 가지 승인 정책:

untrusted — 신뢰되지 않은 모든 명령어 전에 물어봄. 배우거나 익숙하지 않은 프로젝트에서 사용.
on-request (기본값) — 일상적인 샌드박스 명령어는 자동 승인, 샌드박스 경계를 위반하는 것 전에 물어봄.

auto_review는 AGENTS.md를 기반으로 자동 승인 또는 거절하는 리뷰어 서브 에이전트입니다.

구성에서 approvals_reviewer = "auto_review"로 활성화합니다. 모든 단계를 지켜보고 싶지 않은 긴 비동기 태스크 및 Goal 모드에 잘 작동합니다.

계속해서 승인을 요청하는 명령어를 추가하세요. 파괴적인 명령어는 절대 추가하지 마세요.

효과적인 Codex 프롬프팅

샌드박스가 구성되고 세션이 실행 중입니다. 다음 레버는 프롬프트 품질로, 다른 어떤 변수보다 출력에 더 큰 영향을 미칩니다.

Codex 출력 품질에 대한 가장 큰 단일 레버는 프롬프트 구조입니다. 모호한 프롬프트는 모호한 코드를 생성합니다.

프레임워크: 알려주기(Tell), 보여주기(Show), 설명하기(Describe), 상기시키기(Remind).

방법이 아닌 원하는 결과를 알려주세요
예시 입력과 예상 출력을 보여주세요
사용할 API, 라이브러리, 패턴을 설명하세요
AGENTS.md의 규칙을 상기시키세요

매번 네 가지 모두 필요하지는 않습니다. 작은 버그 수정은 Tell과 Remind만 필요할 수 있습니다. 새로운 기능은 보통 네 가지 모두를 원합니다.

단일 변경 규칙: Codex는 한 번에 하나의 작업에서 다섯 개보다 훨씬 더 잘 수행합니다. "인증 버그 수정, 테스트 추가, 사용자 리포지토리 리팩토링, README 업데이트"는 동전 던기기와 같습니다. 동일한 작업을 네 개의 프롬프트로 나누면 안정적입니다.
중요하지 않은 작업에는 먼저 계획을 강제하세요: "먼저 계획을 수립하고, 내가 승인할 때까지 코드를 작성하지 마세요." 계획을 30초 검토하는 것은 잘못된 구현을 30분 디버깅하는 것보다 낫습니다.
실패 동작을 명시적으로 지정하세요. 스스로 판단하게 두면 Codex는 어떤 수단을 써서든 테스트를 통과시키려 할 것입니다:

컨텍스트를 명시적으로 제한하세요. 읽을 특정 파일을 지정하세요. "다른 것은 읽거나 수정하지 마세요. 다른 곳에서 정보가 필요하면 저에게 물어보세요."

추론 노력 수준:

Low : 사소한 편집, 포맷팅, 간단한 리팩토링
Medium (기본값) : 대부분의 기능 작업 및 버그 수정
High : 아키텍처 결정, 어려운 디버깅, 대규모 다중 파일 리팩토링

Goal 모드

단일 태스크 프롬프팅이 자연스러워지면, 다음 단계는 Codex에 며칠짜리 목표를 주고 스스로 작업을 시퀀싱하도록 하는 것입니다.

Goal 모드는 태스크별로 브리핑하기에는 너무 크지만 단일 목표에 대해 일관성 있는 작업을 위한 것입니다. 2026년 5월에 안정화되었습니다.

실행 중인 Goal을 다음 명령어로 관리하세요:

codex goal status : 활성 Goal 및 진행 상황 확인
codex goal logs <id> : Codex가 지금까지 수행한 작업 검사
codex goal pause <id> : 실행을 중단하고 입력 대기
codex goal resume <id> : 중단된 지점에서 계속
codex goal cancel <id> : 중단하고 Goal 폐기

범위가 정해진 Goal로 시작하세요. Codex가 목표를 어떻게 해석하는지 신뢰할 때까지 "최대 5개 PR"로 제한하세요. 잘못된 작업을 자신있게 수행하는 통제 불능의 Goal이 최악의 결과입니다.

항상 다음과 같이 제한하세요: 최대 PR 수, PR당 최대 코드 줄 수, PR 간 CI 게이트, 명확한 중지 조건. AGENTS.md에 포함되지 않은 아키텍처 결정에는 일시 중지. 호환성을 깨는 API 변경에는 일시 중지.

스킬: 재사용 가능한 워크플로우

Goal 모드는 큰 작업을 처리합니다. 스킬은 모든 프로젝트에서 나타나는 반복적인 마이크로 워크플로우를 처리합니다. 세션 전반에 걸쳐 동일한 지침을 반복하고 있다면, 그것이 스킬을 작성할 신호입니다.

스킬은 디렉토리로 패키징된 재사용 가능한 워크플로우입니다: SKILL.md 파일의 지침과 선택적 리소스 및 스크립트로 구성됩니다.

Codex는 이름과 설명으로 스킬을 발견합니다. 태스크가 스킬을 트리거할 때만 전체 지침을 로드합니다. 스킬이 트리거될 때까지 컨텍스트 비용 없이 50개의 스킬을 가질 수 있습니다.

스킬 위치:

개인 : $HOME/.agents/skills/ : 프로젝트 간, 리포지토리에 관계없이 작업 방식을 반영
팀 : 리포지토리 내 .agents/skills/ : 프로젝트별, 버전 관리, 협업자와 공유

SKILL.md 형식:

모든 파워 유저가 먼저 작성해야 할 세 가지 스킬:

open-pr은 표준 PR 워크플로우입니다: 브랜치 확인, 푸시, 구조화된 본문으로 PR 생성, 레이블 적용, 리뷰 요청. 일상 작업에서 가장 많이 사용되는 스킬.
new-feature는 PRD와 AGENTS.md를 읽고, 재사용할 기존 컴포넌트를 식별하고, 계획을 출력하고, 승인을 기다리고, 구현하고, 테스트한 후 open-pr 스킬을 통해 PR을 엽니다. PRD에 모호한 내용이 있으면 코드를 생성하기 전에 질문합니다.
investigate는 수정 없이 진단하는 스킬입니다. 재현을 확인하고, 관련 코드 경로를 읽고, 가설을 세우고 ("Y가 발생하는 이유는 X 때문이라고 생각합니다"), 가설과 검증 계획을 Markdown으로 출력합니다. 수정을 구현하지 않습니다. 출력은 이해이지 코드가 아닙니다.

investigate 스킬이 중요한 이유는 Codex가 가능할 때마다 근본 원인 분석을 건너뛰기 때문입니다. 바로 수정으로 직행하며, 그 수정은 종종 틀립니다. investigate-first를 강제하는 것이 디버깅 출력 품질에 대한 가장 큰 개선입니다.

스킬이 로드되었는지 확인: 사용 가능한 스킬 나열

서브 에이전트 및 병렬 처리

스킬은 반복 가능한 워크플로우를 처리합니다. 서브 에이전트는 병렬 워크플로우를 처리합니다. 이 구분이 중요한 이유는 잘못된 병렬 처리는 해결하는 문제보다 더 많은 문제를 만들기 때문입니다.

서브 에이전트는 별도의 격리된 에이전트 인스턴스입니다. 자체 컨텍스트에서 실행되고, 요약을 반환하며, 컨텍스트는 폐기됩니다. 이는 메인 에이전트의 컨텍스트에서 실행되는 스킬과 다릅니다.

서브 에이전트가 적합한 세 가지 패턴:

탐색 : 서브 에이전트를 생성하여 30개 파일을 읽고 요약; 읽기는 사용자의 컨텍스트가 아닌 에이전트의 컨텍스트에서 발생
병렬 구현 : 각각 자체 컨텍스트와 계획을 가진 5개의 독립적인 기능을 5개의 동시 서브 에이전트로 처리
검증 : 새로운 리뷰어 서브 에이전트는 방금 코드를 작성했다는 편향이 없음

사용자 정의 서브 에이전트는 .codex/agents/<name>.md에 정의됩니다:

서브 에이전트 어드레싱은 2026년 3월에 출시되었습니다. @<닉네임>으로 실행 중인 서브 에이전트와 대화하세요.
여러 개가 병렬로 실행 중일 때 다른 에이전트를 방해하지 않고 하나를 리디렉션하려는 경우 유용합니다.
팬아웃 패턴: 독립적인 태스크에서 N개의 서브 에이전트를 병렬로 생성하고 결과를 수집합니다.
가장 느린 태스크가 걸리는 시간 내에 5개의 태스크가 완료됩니다. 경험상 태스크가 메인 컨텍스트에서 30초 미만이면 거기서 수행하세요.

데스크톱 앱: 모든 것을 위한 Codex

서브 에이전트와 스킬은 CLI, IDE 확장 프로그램, 데스크톱 앱에서 동일하게 잘 실행됩니다. 하지만 데스크톱 앱에는 CLI에 해당 기능이 없는 기능들이 있습니다.

2026년 4월 16일 "Codex for (almost) everything" 업데이트는 데스크톱 앱을 코딩 도구에서 완전한 개발자 워크스테이션으로 변환했습니다.

Computer Use

Codex가 Mac을 작동합니다: 클릭, 타이핑, 스크롤, 앱 열기, 메뉴 탐색, 커서 포커스를 빼앗지 않고 함께 실행.

킬러 사용 사례는 동작 검증입니다. 단위 테스트는 통과하지만 UI가 여전히 깨져 있습니다.
Computer Use는 Codex가 개발 서버를 열고, 관련 흐름을 클릭하고, 결과를 스크린샷으로 캡처하도록 하여 이 격차를 해소합니다.
활성화하려면 Codex 설정, Computer Use, 설치로 이동하세요. macOS에서 메시지가 표시되면 화면 기록 및 손쉬운 사용 권한을 부여하세요. 모든 프롬프트에서 호출:

잠금 상태 Computer Use를 사용하면 화면이 잠긴 후에도 Codex가 데스크톱 앱을 계속 작동할 수 있습니다. 설정의 Computer Use에서 활성화하세요. 잠자기 전에 태스크를 시작하고, 머신을 잠그고, 아침에 결과를 검토하세요.

Appshot

Command-Command를 누르면 최전면 macOS 창이 직접 Codex 스레드로 들어갑니다.

Codex가 스크린샷, 보이는 텍스트, 접근성 텍스트를 캡처합니다. 종종 화면 밖으로 스크롤된 콘텐츠도 포함됩니다.

Appshot 없음: 오류 확인, Codex로 전환, 질문 입력, 스크린샷 찍기, 드래그 앤 드롭, 추가 컨텍스트 입력. 30초의 마찰.
Appshot 사용: 오류 확인, Command-Command 누르기, 질문하기. 5초.

지난 60초 이내에 Codex 스레드와 상호 작용했다면 Appshot은 해당 대화로 들어갑니다.

그렇지 않으면 새 스레드를 엽니다. 세션의 여러 Appshot은 하나의 스레드로 누적됩니다. 화면 기록 및 손쉬운 사용 권한 필요.

인앱 브라우저

인앱 브라우저는 페이지 미리보기가 아닌 네이티브 에이전트 브라우저입니다. 로컬 개발 서버를 열고, 클릭하고, 양식을 채우고, DOM 상태를 검사하고, 스크린샷을 캡처하고, 방금 작성한 패치가 시각적 버그를 수정했는지 확인합니다.

그 안에서 로컬 개발 서버를 연 다음, 렌더링된 요소에 직접 자연어 코멘트를 추가하세요.
요소에 "이 버튼을 20픽셀 더 크게 만들어"라고 작성하면 Codex가 코드베이스에서 변경을 실행하고 페이지를 다시 로드합니다.
인앱 브라우저는 창 관리 오버헤드 없이 직접 DOM 액세스를 제공하며 실제 브라우저와 샌드박스 처리됩니다.

Memory

Memory를 사용하면 Codex가 세션 간에 컨텍스트를 유지할 수 있습니다.

각 세션이 종료된 후 Codex는 상호 작용을 요약하고 ~/.codex/memories/에 기록합니다.
다음 세션에서 프롬프트를 로드하기 전에 해당 파일을 읽습니다.
Codex가 선호하는 커밋 메시지 형식, 테스팅 프레임워크, 아키텍처 패턴, 지난번에 저지른 실수를 학습합니다. 사용자가 해당 컨텍스트를 반복할 필요 없이.
설정에서 활성화하거나 config.toml의 [features] 아래에 memories = true를 추가하세요.

90개 이상의 플러그인 생태계

플러그인은 스킬, MCP, 통합의 큐레이션된 번들입니다. codex plugins install <name>으로 설치하세요.

주요 플러그인 카테고리:

프로젝트 관리 : Linear, JIRA, GitHub
CI/CD : CircleCI, Vercel, GitHub Actions
데이터베이스 : Neon, Postgres, PlanetScale
코드 품질 : Sentry, CodeRabbit
생산성 : Notion, Remotion

매일 사용하는 도구에 대해서만 설치하세요. 가능한 경우 프로젝트별로 범위를 지정하세요. 분기별로 감사하세요. 모든 플러그인은 사용 여부와 관계없이 컨텍스트 토큰을 소모합니다.

Codex Cloud: 규모에 맞는 비동기 작업

데스크톱 앱은 로컬 및 대화형 작업을 지원합니다. Cloud는 단일 대화형 세션에 비해 너무 크거나, 다른 곳에 집중하는 동안 여러 태스크를 병렬로 실행하려는 경우 사용하는 기능입니다.

Codex Cloud는 Codex를 빠른 코딩 어시스턴트에서 수평적으로 확장되는 주니어 엔지니어링 팀으로 변화시키는 기능입니다.

태스크를 제출하면 Codex가 리포지토리가 미리 로드된 샌드박스를 생성하고, 작업하고, 테스트를 실행하고, PR을 엽니다. 로컬 머신을 차단하지 않습니다.

단일 태스크 제출:

병렬 태스크; 핵심 패턴:

20분 후, 4개의 PR이 열립니다. 리뷰, 분류, 병합.

CSV 팬아웃을 사용하면 태스크 파일을 제출하고 Codex가 진행 상황 추적과 함께 병렬 클라우드 에이전트로 팬아웃합니다:

codex cloud는 활성 및 완료된 태스크를 탐색합니다. codex cloud apply <task-id>는 병합 전에 변경 사항을 로컬로 가져옵니다.

GitHub 통합

클라우드 태스크는 PR로 리포지토리에 도착합니다. GitHub 통합은 해당 PR이 어떻게 리뷰되는지, 그리고 Codex가 기존 CI/CD 파이프라인에 어떻게 통합되는지를 결정합니다.

Codex와 GitHub는 리포지토리 환경, 풀 리퀘스트 리뷰, CI/CD를 위한 codex-action의 세 가지 수준에서 통합됩니다.

리포지토리 환경이 기초입니다. Codex 설정에서 GitHub 리포지토리를 연결하면 클라우드 태스크가 리포지토리를 복제하고, 샌드박스 컨테이너에서 태스크를 실행하며, 결과를 브랜치나 PR로 푸시합니다. 모든 클라우드 태스크에 대해 AGENTS.md가 자동으로 읽힙니다.

풀 리퀘스트 리뷰는 두 가지 방식으로 작동합니다:

PR 코멘트에서 @codex review를 언급하세요. Codex가 수신 확인으로 눈 이모지로 반응한 후, AGENTS.md에 대해 확인된 심각한 문제에 초점을 맞춘 구조화된 리뷰를 게시합니다.
자동 리뷰를 켜면 수동 트리거 없이 모든 새 PR에 Codex가 게시합니다.

Codex가 리뷰를 게시한 후, PR 코멘트 스레드에서 직접 플래그가 지정된 문제를 수정하도록 요청하세요. 동일한 브랜치에 수정 사항을 커밋하고 PR을 업데이트합니다.

codex-action은 공식 GitHub Action으로, 푸시, 일정, 이슈 생성, PR 열기 등 모든 트리거에서 CI/CD 파이프라인 내에서 Codex CLI를 실행합니다. 인간이 없는 완전 자동화 파이프라인에 Codex를 통합하는 권장 방법입니다.

Automations: 무인 작업

GitHub 통합은 인간이 PR을 열 때 발생하는 작업을 처리합니다. Automations는 인간이 전혀 관여할 필요가 없을 때 발생하는 작업을 처리합니다.

Automations는 전용 작업 트리에서 실행되는 예약된 Codex 태스크입니다. Automations 패널에서 설정: 이름, 프로젝트, 프롬프트, 일정, 실행 환경.

스레드 재사용은 2026년 4월에 출시되었습니다. Automations는 실행 간에 스레드를 재사용하여 컨텍스트를 축적하고 시간이 지남에 따라 더 똑똑해질 수 있습니다.

모든 프로젝트가 가져야 할 세 가지 스타터 자동화:

주간 종속성 검토 (월요일 오전 6시): pnpm outdated 및 pnpm audit 실행. 중요, 주요, 부수적 발견 사항 보고. 안전한 부수적 및 패치 업그레이드는 자동 PR. 중요 또는 주요 업데이트는 건드리지 않음; 인간의 결정 필요.
일일 Sentry 트라이지 (평일 오전 8시): 지문별로 그룹화된 지난 24시간의 오류 가져오기. 3회 이상 발생한 각 그룹에 대해 파일과 라인 식별, 관련 코드 읽기, 근본 원인 식별. 트라이지 보고서 게시. 진단 전용, 수정 없음.
주간 스테일 PR 정리 (금요일 오후 5시): 7일 이상 된 열린 PR 나열. 각각에 대해 사용자를 기다리는 중인지, 리뷰를 기다리는 중인지, 스테일 상태인지 판단하고 알림 코멘트 게시. 아무 것도 닫거나 병합하지 마세요.

출력물이 더 이상 읽히지 않는 자동화는 중단하세요. 좋은 자동화는 어차피 반드시 수행해야 할 반복 작업을 절약하고, 단일 스캔 가능한 출력을 생성하며, 무인 상태에서 파괴적인 조치를 취하지 않습니다.

MCP 통합

Automations는 리포지토리에 있는 것과 함께 작동합니다. MCP 서버는 Codex를 리포지토리 외부의 모든 것과 함께 작동하도록 확장합니다.

MCP(Model Context Protocol)는 플러그인 뒤에 있는 오픈 스펙입니다. 플러그인이 존재하면 사용하세요. 내부 도구에 대한 사용자 정의 통합에는 원시 MCP를 사용하세요.

STDIO : Codex가 로컬 프로세스를 생성하고 stdin/stdout을 통해 통신합니다. 단독 사용의 95%를 커버합니다.
Streamable HTTP : Codex가 네트워크 엔드포인트에 연결합니다. 호스팅된 팀 MCP에 사용됩니다.

원시 MCP 서버 추가:

또는 ~/.codex/config.toml에 직접:

도구별 승인 구성: 읽기 작업은 자동 승인, 쓰기 작업은 승인 요청. MCP 서버를 추가할 때마다 Codex 의 컨텍스트에 도구 정의가 추가되어 토큰을 소모하고 집중도를 분산시킵니다. 실제로 사용하는 것만 활성화하세요.

Docker MCP Toolkit 을 사용하면 단 한 개의 명령어로 Codex 를 220 개 이상의 사전 구축된 서버에 연결할 수 있습니다:
``
docker mcp-client configure codex
``

모바일 앱

MCP 서버는 Codex 가 도달할 수 있는 범위를 확장합니다. 모바일 앱은 Codex 에 도달할 수 있는 사용자의 범위를 확장합니다.

2026년 5월 14일, Codex 가 iOS 및 Android 용 ChatGPT 모바일 앱에 출시되었습니다.

모바일 Codex 는 원격 제어 및 모니터링 인터페이스이며, 코드 편집기가 아닙니다. 일반적인 사용 사례는 책상에서 떨어져 있을 때 장시간 실행되는 클라우드 작업이나 Goal 모드 실행 상태를 휴대폰으로 확인하는 것입니다.

휴대폰에서 다음 작업을 수행할 수 있습니다:

노트북, 데브박스 또는 연결된 원격 환경에서 실행되는 라이브 실행 모니터링
스레드 탐색 및 병렬 작업 간 전환
브랜치에 병합되기 전에 diff 검토
Codex 가 하드웨어에서 실행하려는 명령 승인 또는 거부
더 강력한 모델이 필요할 경우 작업 중 모델 교체
새 프롬프트 또는 GitHub 이슈에서 직접 새 작업 시작
Codex 가 생성한 Pull Request 에 댓글 달기

설정하려면 ChatGPT 를 2026년 5월 13일 릴리스 이상으로 업데이트하고, 동일한 데스크톱 계정으로 로그인한 후, 설정 > Codex > 환경에서 최소 하나의 클라우드 환경을 구성하세요. 모바일은 기존의 모든 스레드와 연결된 호스트를 자동으로 상속받습니다.

이를 통해 가능해지는 실용적인 워크플로우: 아침에 집을 나서기 전에 Goal 모드 실행을 시작하고, 출근길에 진행 상황을 확인하며, 휴대폰으로 일시 중지된 결정을 승인하고, 사무실에 도착했을 때 이미 처음 두 개의 PR 이 열려 있는 상태를 만날 수 있습니다.

Chrome 확장 프로그램

모바일 앱은 사용자의 도달 범위를 확장합니다. Chrome 확장 프로그램은 Codex 의 도달 범위를 사용자가 이미 로그인한 모든 웹사이트로 확장합니다.

즉, 인증된 서비스(LinkedIn, Salesforce, Gmail, Workday 및 로그인이 필요한 모든 내부 도구)에 접근할 수 있습니다.
설치 방법: Codex 데스크톱 앱 내 플러그인으로 이동하여 Chrome 플러그인을 추가하고 안내 설정을 따르세요.
확장 프로그램은 활성화되면 Connected 상태를 표시합니다. Codex 스레드에서 호출하세요.

Codex는 여러 Chrome 탭을 별도의 스레드에서 서브 에이전트를 통해 제어할 수 있으며, 각 탭은 격리됩니다.

헤드리스 브라우저 자동화에 비해 큰 장점: Chrome 확장 프로그램은 웹 개발자 도구에 접근할 수 있습니다. Codex 는 DOM 을 검사하고, 콘솔 오류를 읽으며, 라이브 브라우저 세션에서 런타임 문제를 진단할 수 있습니다. macOS와 Windows 모두에서 작동합니다.

Codex SDK

Chrome 확장 프로그램은 브라우저 자동화를 처리합니다. SDK 는 프로그래매틱 자동화, 즉 Codex 를 자체 애플리케이션 및 파이프라인 내에서 인프라로 임베딩하는 것을 처리합니다.

Codex SDK는 개발자가 자체 애플리케이션과 CI 파이프라인에서 Codex 를 프로그래매틱하게 제어할 수 있도록 해줍니다.

JavaScript SDK 설치:

text

1npm install codex-sdk

기본 사용법:

text

1import Codex from 'codex-sdk';
2
3const codex = new Codex();
4const thread = await codex.createThread();
5const response = await codex.run(thread.id, "Hello, Codex!");

동일한 스레드에서 run() 을 다시 호출하면 대화를 이어갈 수 있습니다. 저장된 스레드는 codex.resumeThread(threadId) 로 재개하세요.
Python SDK는 from codex_app_server import Codex 를 사용합니다. 시작할 때 모델 이름을 전달하세요: thread = codex.thread_start(model="gpt-5.5").
SDK는 현재 실험 단계이며 로컬 Codex CLI 설치가 필요합니다.
로컬 앱 서버와 JSON-RPC 를 통해 통신하며, 데스크톱 앱에서 상호작용하는 동일한 에이전트를 제어합니다.

검증: Codex 출력을 실제로 신뢰하는 방법

위의 모든 인터페이스는 출력을 생성합니다. 검증은 해당 출력 중 얼마나 많이 실제로 배포할 수 있는지를 결정합니다.

생성은 해결되었습니다. 검증이 병목입니다.

5개의 병렬 클라우드 PR은 버그를 배포할 5번의 기회입니다. 검증 레이어 없이는 PR을 읽을 수 있는 속도에 의해 처리량이 제한됩니다.

핵심 문제는 아첨(sycophancy)입니다. 코드를 작성한 모델은 자신이 옳다고 생각하는 편향이 있습니다. 자신의 작업을 검토하도록 요청하면 대부분의 경우 긍정적인 답변을 받게 됩니다.

두 가지 구조적 해결책:

auto_review (Codex 내부): Codex 의 내장 리뷰어 서브 에이전트입니다. 새로운 컨텍스트로, 이전 출력에 대한 투자가 없으며 실제 문제를 지적할 가능성이 훨씬 높습니다.
교차 제공자 검증 (최고 표준): Codex 가 작성하고 Claude Code 가 리뷰합니다. 교차 제공자 검증은 특정 모델 제품군에 특화된 사각지대를 잡아냅니다. 이는 프로덕션 코드를 위한 최소 실행 가능한 검증 습관입니다.

컴퓨터 사용(Computer Use)을 통한 행동 검증은 "테스트 통과"와 "실제로 작동하는 것" 사이의 간극을 메웁니다. Codex 가 개발 서버를 열고, 관련 플로우를 클릭하며, 결과를 스크린샷으로 찍고, 이를 PRD와 비교하도록 하세요.

모든 PR에서의 최소 실행 가능한 습관: 직접 diff 를 열기 전에 다른 모델로 자동 리뷰를 실행하세요. 먼저 리뷰 요약을 읽으세요. 리뷰가 깨끗할 때만 diff 를 열고, 그런 다음 정확성이 아닌 취향을 위해 읽으세요. UI 변경의 경우 스크린샷을 확인하세요.

레시피: 검증된 패턴

검증 습관이 갖춰진 상태에서, 개발자들이 Codex 를 통해 가장 자주 실행하는 작업에 대한 엔드투엔드 템플릿입니다.

기능 구현: new-feature Skill을 사용하세요. PRD 와 AGENTS.md 를 읽으세요. 먼저 계획을 세우고 승인을 기다리세요. 해피 패스와 하나의 오류 케이스에 대한 테스트를 작성하세요. 모호한 점이 있다면 코드를 생성하기 전에 질문하세요.
버그 수정: 먼저 investigate Skill을 사용하세요. 진단만 수행하세요. 재현 단계, 근본 원인 가설 및 검증 계획을 출력하세요. 확인되기 전까지는 수정하지 마세요.
리팩토링: grep 으로 모든 위치를 나열하세요. 마이그레이션 계획을 출력하세요. 승인을 기다리세요. 모든 기존 테스트가 수정 없이 통과해야 합니다. 테스트를 업데이트해야 한다면 테스트가 잘못된 것입니다. 중단하고 보고하세요. 하나의 PR로 처리하세요.
서드파티 통합: /lib/integrations/[name].ts 에 래핑하세요. .env.example 에 환경 변수를 추가하세요. 이 PR에는 UI가 없습니다. 외부 서비스에 대한 수동 테스트를 위해 초안으로 열어두세요.
테스트 백필: 해피, 엣지, 오류 케이스를 다루는 테스트 계획을 출력하세요. 승인을 기다리세요. 모든 테스트가 기존 프로덕션 코드에 대해 통과해야 합니다. 프로덕션 코드를 수정하지 마세요.
의존성 업그레이드: 버전 간 릴리스 노트를 읽으세요. 변경 사항 목록을 작성하세요. 승인을 기다리세요. 코드 변경 사항을 업데이트하고 적용하세요. 테스트가 깨끗해질 때까지 실행하세요.
Goal 모드 이니셔티브: 최대 PR 수, PR당 최대 코드 라인 수, PR 간 CI 게이트, 명확한 중지 조건으로 범위를 제한하세요. AGENTS.md 에 없는 아키텍처 결정에 대해 일시 중지하세요. 모든 주요 API 변경에 대해 일시 중지하세요.

일반적인 실수

위 패턴은 일반적인 성공 사례를 다룹니다. 아래 섹션은 일반적인 실패 사례, 즉 대부분의 Codex 경험을 설명하는 10가지 실수를 다룹니다.

모호한 작업. 구체적인 결과물, 파일 및 제약 조건을 명시하세요. 구체적으로 지정할 수 없다면 작업이 브리핑할 준비가 되지 않은 것입니다.
AGENTS.md 없음. 하나를 작성하세요. 엉성하더라도 없는 것보다 낫습니다.
계획 건너뛰기. 중요하지 않은 모든 작업에 대해 "먼저 계획을 수립하세요."
멀티태스크 프롬프트. 프롬프트당 하나의 작업. 병렬 작업에는 서브 에이전트나 클라우드 작업을 사용하세요.
위험-완전-접근 권한으로 시작하기. 테스트된 자동화를 제외한 모든 것에 대해 workspace-write 및 on-request 가 올바른 기본값입니다.
너무 많은 MCP 및 플러그인. 목록을 간결하게 유지하세요. 실제로 사용하지 않는 것은 비활성화하세요.
자체 리뷰. auto_review 또는 완전히 다른 도구를 사용하세요. 코드를 작성한 모델은 해당 코드에 편향되어 있습니다.
컴파일 성공을 정확성으로 신뢰하기. 행동 검증을 포함하세요. UI 변경에는 Computer Use를 사용하세요.
과도한 병렬화. 독립적인 작업만 병렬화하세요. 공유 파일은 직렬화되어야 합니다.
무제한 Goal. 최대 PR 수, 최대 코드 라인 수, 최대 시간, 명확한 중지 조건. Goal 모드는 주니어 엔지니어에게 부여하는 통제 범위와 함께 사용할 때 가장 유용합니다.

빠른 참고 치트 시트

CLI 명령어:

codex run - 새 작업 실행
codex resume - 기존 작업 재개
codex list - 모든 작업 나열
codex log - 작업 로그 보기
codex stop - 실행 중인 작업 중지
codex status - Codex 데몬 상태 확인
codex config - 설정 파일 편집
codex plugin add - 플러그인 추가
codex skill add - Skill 추가
codex mcp list - 연결된 MCP 서버 나열

주요 파일 위치:

전역 설정: ~/.codex/config.toml
전역 AGENTS.md: ~/.codex/AGENTS.md
프로젝트 AGENTS.md: <repo-root>/AGENTS.md
재정의 파일: AGENTS.override.md
메모리: ~/.codex/memories/
Skill (개인): $HOME/.agents/skills/
Skill (팀): 저장소 내 .agents/skills/
서브 에이전트: .codex/agents/<name>.md

4단계 프롬프트 구조:

Tell (알려주기): 방법이 아닌 결과
Show (보여주기): 예시 입력 및 예상 출력
Describe (설명하기): 사용할 API, 라이브러리 및 패턴
Remind (상기시키기): AGENTS.md 의 규칙

결론

12개월 동안 Claude를 사용한 후, 전환점은 단순히 나쁜 하루가 아니었습니다. 레이트 리미트, 워크플로우 마찰, 그리고 계속해서 방해가 되는 데스크톱 앱 경험의 누적이었습니다.

바로 그 불만이 Codex 로의 전환을 추진했습니다.

지난 90일 동안 OpenAI 생태계에 깊이 빠져들면서 한 가지가 분명해졌습니다: Codex 는 진지한 개발자 워크플로우를 위한 작업 환경으로서 더 완벽하게 느껴집니다.
에이전트 모델은 더 강력하고, 주변 인터페이스는 더 광범위하며, AGENTS.md, Skills, Cloud 및 검증 루프가 갖춰지면 시스템을 더 쉽게 신뢰할 수 있습니다.
그렇다고 Claude Code 에 가치가 없다는 의미는 아닙니다. 절충안이 더 이상 의미가 없어졌다는 뜻입니다.

Claude Code 가 여전히 워크플로우에 적합하다면 계속 사용하세요. 하지만 레이트 리미트, 취약한 세션, 그리고 프로세스와 싸우는 듯한 도구에 지쳤다면, Codex 는 이제 진지한 전환을 정당화할 만큼 충분히 좋습니다.

이 글은 그 전환을 더 쉽게 만들기 위해 작성되었습니다.

이 글이 도움이 되었기를 바라며, 멋진 것을 만들어 보세요 ❤️

면책 조항

이 글은 작성자가 자신의 노트, 연구 및 개인 경험을 바탕으로 작성되었으며, AI 모델(Sonnet 4.6)에 의해 편집되었습니다.

썸네일 이미지는 Pinterest 에서 가져와 AI를 사용하여 수정했습니다.