Codex 실전 가이드

OpenAI 공식 코딩 에이전트 Codex를 처음 쓰는 사람을 위한 실전 가이드 — 전 31편. 설치·인증부터 설정·모델·MCP·Skills·자동화·보안·팀 운영까지.

0. 이 가이드를 읽기 전에

01이 가이드의 목적

이 가이드는 Codex를 다음 수준까지 사용할 수 있게 만드는 것입니다.

설치한다
→ 로그인한다
→ 프로젝트에서 실행한다
→ 코드베이스를 이해시킨다
→ 안전하게 작업을 맡긴다
→ 변경사항을 검토한다
→ 테스트한다
→ 반복 작업을 자동화한다
→ 팀 단위 규칙과 보안까지 관리한다

단순 명령어 모음이 아니라, Codex를 실제 개발 워크플로에 녹여 쓰는 방법을 설명합니다.

02이 가이드가 다루는 범위

이 가이드는 Codex의 핵심 기능을 빠짐없이 다룹니다.

시작하기

설치, 인증, 첫 실행

기본 사용

CLI, slash commands, 파일 수정, diff 확인

안전장치

sandbox, approval, permission profiles

설정

config.toml, profiles, 모델 선택

프로젝트 규칙

AGENTS.md

확장 기능

MCP, Skills, Plugins, Hooks

작업 관리

Plan Mode, Goal Mode, Session Management

자동화

codex exec, GitHub Action, CI/CD

고급 활용

Cloud, Desktop App, IDE Extension, Chrome Extension

운영

성능 최적화, 디버깅, 보안, Enterprise 배포

실전 예제

Workflow Recipes, Migration Guide, 빠른 참조 카드

03이 가이드를 읽는 방법

처음부터 끝까지 읽어도 되지만, 본인의 목적에 따라 순서를 다르게 잡는 것이 좋습니다.

Codex가 처음인 사람

0장 → 1장 → 3장 → 4장 → 5장, 다음 6장, 8장, 14장

터미널에 익숙한 개발자

1장 → 2장 → 5장 → 7장, 다음 9장, 13장, 24장

실무에 바로 쓰려는 사람

5장 → 8장 → 14장 → 15장, 다음 20장, 28장, 29장

팀 리드

15장 → 28장 → 29장, 다음 14장, 30장

자동화를 원하는 사람

24장 → 29장 → 30장, 다음 13장, 28장

다른 AI 코딩 도구에서 넘어온 사람

1장 → 2장 → 29장, 다음 15장, 20장

04초보자 추천 학습 순서

초보자는 최소한 다음 순서로 읽는 것을 추천합니다.

0장: 이 가이드 읽는 법
1장: Codex 핵심 요약
2장: Codex 작동 방식 이해
3장: 설치
4장: 인증
5장: 첫 세션
8장: 자주 쓰는 slash commands
14장: Sandbox와 Approval
15장: AGENTS.md

05초보자가 반드시 알아야 할 기본 개념

Codex를 쓰다 보면 자주 등장하는 개념들이 있습니다.

CLI

터미널에서 Codex를 실행하는 방식

TUI

터미널 안에서 열리는 대화형 화면

Session

Codex와 진행 중인 하나의 작업 대화

Thread

이어서 관리되는 대화 흐름

Fork

기존 대화를 복사해 다른 방향으로 이어가기

Sandbox

Codex가 접근할 수 있는 범위를 제한하는 안전장치

Approval

Codex가 특정 작업 전에 사용자 승인을 요청하는 정책

AGENTS.md

프로젝트에서 Codex가 따라야 할 규칙 파일

config.toml

Codex 설정 파일

Profile

작업 상황별 설정 묶음

MCP

외부 서비스와 Codex를 연결하는 프로토콜

Skill

특정 작업 방식을 재사용하기 위한 지식 패키지

Hook

특정 이벤트 전후에 실행되는 자동 동작

Plugin

Codex 기능을 확장하는 패키지

Plan Mode

실행 전에 계획부터 세우는 모드

Goal Mode

지속되는 작업 목표를 관리하는 모드

codex exec

비대화형 자동화 실행 방식

이 용어들은 뒤에서 다시 자세히 설명합니다. 지금은 이런 이름들이 반복해서 나온다는 정도만 알고 넘어가면 됩니다.

06초보자가 가장 먼저 익혀야 할 5가지

Codex를 처음 쓸 때는 기능이 많아 보일 수 있습니다. 하지만 처음부터 전부 알 필요는 없습니다.

먼저 아래 5가지만 익히면 됩니다.

1프로젝트에서 Codex 실행하기

2프로젝트 구조 물어보기

3복잡한 작업은 먼저 계획시키기

4변경사항 확인하기

5안전한 기본 권한으로 사용하기

이 5가지만 익혀도 Codex를 안전하게 시작할 수 있습니다.

1. 프로젝트에서 Codex 실행하기

cd my-project
codex

2. 프로젝트 구조 물어보기

이 프로젝트의 구조와 실행 방법을 초보자도 이해할 수 있게 설명해줘.

3. 복잡한 작업은 먼저 계획시키기

/plan 로그인 기능을 리팩터링하려고 해.
관련 파일을 찾고, 위험 요소와 단계별 작업 계획을 먼저 제안해줘.

4. 변경사항 확인하기

/diff

5. 안전한 기본 권한으로 사용하기

sandbox_mode = "workspace-write"
approval_policy = "on-request"

07원칙 1. 안전한 기본값으로 시작한다

처음부터 danger-full-access같은 강한 권한을 쓰지 않습니다.

08원칙 2. 큰 작업은 바로 실행하지 않는다

큰 작업은 먼저 /plan으로 계획을 확인합니다.

/plan 결제 모듈을 리팩터링하려고 해.
현재 구조를 분석하고 단계별 변경 계획을 먼저 세워줘.

계획을 보고 나서 실행하는 것이 안전합니다.

09원칙 3. 변경사항은 반드시 검토한다

Codex가 만든 코드도 사람이 확인해야 합니다.

/diff

특히 다음 작업 후에는 반드시 확인합니다.

인증
결제
데이터베이스
권한 처리
보안 설정
CI/CD
대규모 리팩터링

10원칙 4. 테스트를 실행한다

변경 후에는 관련 테스트를 실행해야 합니다.

Codex 안에서 요청할 수 있습니다.

변경한 로그인 API와 관련된 테스트를 실행하고 결과를 요약해줘.

또는 직접 실행합니다.

npm test

11원칙 5. 반복 지시는 AGENTS.md에 적는다

매번 반복해서 말해야 하는 규칙은 AGENTS.md에 적어둡니다.

예시:

# AGENTS.md

- 모든 변경 후 관련 테스트를 실행한다.
- 기존 API 응답 형식은 유지한다.
- TypeScript strict mode 기준으로 작성한다.
- 새 기능에는 테스트를 추가한다.

12가이드에서 사용하는 예시 기준

이 가이드는 이해를 돕기 위해 다음 형태의 예시를 사용합니다.

터미널 명령:

codex
codex "프롬프트"
codex --profile fast "작업 내용"

설정 (TOML 형식):

model = "gpt-5.5"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Codex 안 명령:

/plan 이 작업의 단계별 계획을 세워줘.

13권장 기본 설정

초보자는 처음에 아래 설정을 기준으로 시작하는 것이 좋습니다.

model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

이 설정의 의미는 다음과 같습니다.

model = "gpt-5.5"

권장 기본 모델 사용

model_reasoning_effort = "medium"

속도와 정확도의 균형

sandbox_mode = "workspace-write"

작업 폴더 중심으로 읽기/쓰기 허용

approval_policy = "on-request"

위험하거나 범위를 넘는 작업은 승인 요청

처음에는 이 정도만 설정해도 충분합니다.

14실습을 위한 준비물

Codex를 실습하려면 다음이 있으면 좋습니다.

Node.js / npm

npm 설치 방식 사용 시 필요

Git

프로젝트 변경사항 확인에 필요

코드 프로젝트

아무 git repo나 가능

OpenAI / ChatGPT 계정

로그인 및 사용 권한 필요

터미널

CLI 사용 시 필요

코드 에디터

VS Code, Cursor, Windsurf 등

초보자는 테스트용 프로젝트를 하나 준비하는 것이 좋습니다. 처음부터 운영 중인 중요한 프로젝트에 바로 적용하지 않는 편이 안전합니다.

15처음 실습할 때 추천 흐름

처음에는 실제 운영 프로젝트보다 작은 예제 프로젝트에서 시작하는 것이 좋습니다.

테스트용 프로젝트 폴더로 이동
codex 실행
프로젝트 구조 설명 요청
실행 방법과 테스트 방법 요청
작은 수정 작업 요청
/diff로 변경사항 확인
테스트 실행
변경사항 되돌리기 또는 커밋

터미널에서는:

cd sample-project
codex

Codex 안에서:

이 프로젝트의 구조, 실행 방법, 테스트 방법을 초보자 기준으로 설명해줘.

16절대 처음부터 하지 말아야 할 것

초보자는 다음 행동을 피하는 것이 좋습니다.

danger-full-access로 시작

Codex가 시스템 전체에 접근할 수 있음

운영 프로젝트에서 바로 대규모 수정

변경 범위와 위험을 파악하기 어려움

/diff 없이 커밋

의도치 않은 변경을 놓칠 수 있음

테스트 없이 배포

오류를 발견하지 못할 수 있음

AGENTS.md 없이 팀 프로젝트 작업

팀 규칙을 Codex가 모를 수 있음

MCP를 한꺼번에 많이 연결

복잡도와 토큰 비용 증가

모호한 요청으로 대규모 작업 지시

결과가 기대와 다를 가능성 증가

섹션 00 · 마무리

이 단원에서 기억할 것

이 장은 Codex 본문에 들어가기 전 읽는 오리엔테이션입니다.

안전하게 시작하고, 계획을 먼저 세우고, 변경사항을 검토하고, 테스트하라.

초보자는 다음을 먼저 익히면 됩니다.

CLI 실행: cd project && codex
계획 세우기: /plan 명령
변경사항 확인: /diff 명령
안전한 기본값: workspace-write + on-request
프로젝트 규칙: AGENTS.md 작성

다음 단원

1단원. Codex 핵심 요약

1. Codex 핵심 요약

01Codex는 무엇인가?

Codex는 개발자가 터미널, 데스크톱 앱, IDE, 클라우드, 브라우저 환경에서 사용할 수 있는 통합 코딩 에이전트입니다.

Codex는 다음과 같은 일을 할 수 있습니다:

프로젝트 구조 분석
코드 설명
버그 수정
기능 추가
테스트 작성
리팩터링
코드 리뷰
문서 작성
셸 명령 실행
파일 패치 적용
외부 서비스 연동
장기 작업을 클라우드에 위임

02초보자를 위한 Codex의 정의

내 프로젝트를 이해하고, 필요한 파일을 찾아보고, 수정안을 만들고, 명령까지 실행할 수 있는 AI 개발 파트너

Codex는 단순히 코드를 알려주는 챗봇이 아닙니다. 코드베이스를 직접 읽고, 명령을 실행하고, 파일을 수정하고, 외부 도구와 연결하며, 필요하면 클라우드 작업까지 위임할 수 있습니다.

즉, "질문에 답하는 도구"가 아니라 개발 작업을 함께 수행하는 에이전트형 개발 도구로 이해하면 됩니다.

03Codex가 단순 챗봇이 아닌 이유

일반적인 AI 챗봇은 사용자가 붙여넣은 코드나 설명을 보고 답변합니다. 반면 Codex는 실제 개발 환경 안에서 동작합니다.

Codex는 다음 작업을 직접 수행할 수 있습니다:

# 프로젝트 구조 읽기
ls
# 테스트 실행
npm test
# 특정 파일 수정
apply patch
# 변경사항 확인
git diff

즉, Codex는 단순히 "이렇게 고치세요"라고 말하는 수준을 넘어서, 실제 파일을 읽고 수정하고 검증하는 흐름까지 도와줍니다.

04핵심 시스템 1: config.toml

config.toml은 Codex의 동작 방식을 정하는 설정 파일입니다.

다음과 같은 내용을 설정할 수 있습니다:

사용할 모델

어떤 AI 모델을 쓸지 정합니다

추론 강도

모델의 사고 깊이를 조절합니다

샌드박스 모드

접근 범위를 제한합니다

승인 정책

어떤 작업에 사용자 허락이 필요한지 정합니다

초보자가 기억할 기본 설정:

model = "gpt-5.5"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

05핵심 시스템 2: Sandbox / Approval

Codex는 실제 명령을 실행하고 파일을 수정할 수 있기 때문에, 안전장치가 필요합니다.

Sandbox

Codex가 기술적으로 어디까지 접근할 수 있는지 제한

Approval

Codex가 어떤 작업을 하기 전에 사용자 허락을 받아야 하는지 결정

대표적인 sandbox 모드:

read-only

읽기만 가능. 가장 안전

workspace-write

현재 작업 폴더 중심으로 읽기/쓰기 가능

danger-full-access

전체 시스템 접근 가능. 매우 주의 필수

06초보자 추천 조합

sandbox_mode = "workspace-write"
approval_policy = "on-request"

이 조합은 실무 개발에 충분히 편하면서도, 위험한 작업은 사용자의 승인을 받도록 합니다.

예를 들어 workspace-write 모드에서는 Codex가 현재 프로젝트 폴더 안에서는 파일을 수정할 수 있지만, 시스템 전체를 마음대로 건드리지는 못합니다.

07핵심 시스템 3: AGENTS.md

AGENTS.md는 프로젝트 안에서 Codex가 따라야 할 작업 규칙을 적어두는 파일입니다.

예시:

# AGENTS.md

## 개발 규칙

- TypeScript 코드는 strict mode 기준으로 작성한다.
- 변경 후 반드시 npm test를 실행한다.
- 기존 public API는 임의로 변경하지 않는다.
- 스타일 변경은 최소화한다.
- 새 기능에는 테스트를 추가한다.

쉽게 말하면 AGENTS.md는 Codex에게 주는 프로젝트 운영 매뉴얼입니다.

08좋은 AGENTS.md의 효과

좋은 AGENTS.md가 있으면 Codex는 매번 같은 실수를 반복하지 않습니다.

또한 팀의 작업 방식에 맞춰 움직이기 쉬워집니다.

Codex의 행동을 정하는 가장 효과적인 도구입니다.

09핵심 시스템 4: MCP

MCP는 Model Context Protocol의 약자입니다.

MCP를 사용하면 Codex가 외부 도구나 서비스와 연결될 수 있습니다:

GitHub
Figma
Sentry
데이터베이스
사내 API
문서 시스템
이슈 트래커

10MCP의 역할

기본 Codex가 "내 코드베이스를 읽고 수정하는 도구"라면, MCP를 붙인 Codex는 "외부 서비스까지 연결해서 작업하는 에이전트"가 됩니다.

예를 들어 Sentry MCP가 연결되어 있다면 Codex가 에러 로그를 보고 버그 원인을 찾는 식의 워크플로가 가능합니다.

11핵심 시스템 5: Skills

Skills는 Codex가 특정 작업을 더 잘 수행하도록 만드는 재사용 가능한 작업 지식입니다.

예를 들어 이런 skill을 만들 수 있습니다:

PR 리뷰 skill
테스트 작성 skill
보안 점검 skill
API 문서화 skill
마이그레이션 점검 skill
릴리즈 노트 작성 skill

12Skills의 효과

Skills는 매번 긴 프롬프트를 반복해서 쓰지 않도록 도와줍니다.

예를 들어 매번 이렇게 말하는 대신:

이 PR을 리뷰해줘. 보안 문제, 성능 문제, 테스트 누락, API 호환성 문제를 따로 나눠서 봐줘.

PR 리뷰용 skill을 만들어두면 Codex가 필요한 상황에서 해당 지침을 재사용할 수 있습니다.

13Codex의 주요 사용 화면

Codex는 하나의 방식으로만 쓰는 도구가 아닙니다. 같은 Codex 지능을 여러 화면에서 사용할 수 있습니다:

CLI

터미널 중심 개발, 빠른 수정, 자동화

Desktop App

여러 작업을 동시에 관리, 시각적 diff 검토

IDE Extension

VS Code, Cursor, Windsurf 안에서 바로 편집

Codex Cloud

오래 걸리는 작업을 클라우드에 맡기기

Chrome Extension

브라우저 기반 업무, 관리자 페이지, 대시보드 작업

14초보자 추천 시작점

초보자는 처음에 CLI 또는 IDE Extension부터 시작하는 것이 가장 쉽습니다.

터미널에 익숙하다면 CLI가 좋습니다
코드 에디터 안에서 바로 쓰고 싶다면 IDE Extension이 좋습니다

15Codex의 핵심 작업 흐름

Codex의 기본 작업 흐름은 다음과 같습니다:

프로젝트 폴더에서 Codex 실행
Codex가 코드베이스를 읽음
사용자가 작업 요청
Codex가 필요한 파일과 명령을 확인
변경안 생성
사용자가 diff 검토
승인 후 적용
테스트 실행
결과 확인

16Codex 실행 예시

터미널에서:

cd my-project
codex

Codex 안에서는 이렇게 요청할 수 있습니다:

이 프로젝트 구조를 설명해줘.

또는

로그인 API에 입력값 검증을 추가해줘.

17변경사항 확인

작업 후에는 다음 명령으로 변경사항을 확인합니다:

/diff

이것이 Codex 작업 흐름에서 가장 중요한 단계입니다.

18초보자가 반드시 기억할 명령어

처음에는 모든 명령어를 외우지 않아도 됩니다. 아래 명령어부터 익히면 충분합니다:

codex

Codex 실행

/plan

실행 전에 작업 계획 세우기

/diff

Codex가 만든 변경사항 확인

/status

현재 세션 상태 확인

19주요 명령어 (계속)

/model

모델 변경

/compact

긴 대화를 요약해 컨텍스트 확보

/resume

이전 세션 재개

/review

코드 리뷰

/permissions

권한 설정 확인 또는 변경

/quit

종료

초보자에게 가장 중요한 명령어는 /plan과 /diff입니다.

20원칙 1: 큰 작업은 계획부터

나쁜 예:

이 프로젝트 전체를 리팩터링해줘.

좋은 예:

/plan 이 프로젝트의 인증 모듈을 리팩터링하려고 해.
현재 구조를 먼저 분석하고, 위험 요소와 단계별 계획을 제안해줘.

복잡한 작업일수록 /plan을 먼저 쓰는 것이 안전합니다.

21원칙 2: 변경 후 반드시 diff 확인

Codex가 만든 변경사항은 항상 확인해야 합니다:

/diff

특히 다음 작업 후에는 diff 확인이 필수입니다:

인증 관련 코드 수정
결제 관련 코드 수정
데이터베이스 마이그레이션
대규모 리팩터링
CI/CD 설정 변경
보안 관련 수정

22원칙 3: 프로젝트 규칙은 AGENTS.md에

매번 같은 지시를 반복하지 말고 AGENTS.md에 적어두는 것이 좋습니다.

예시:

- 모든 변경 후 npm test를 실행한다.
- DB schema 변경 시 migration 파일을 함께 작성한다.
- 기존 API 응답 형식은 깨지지 않게 유지한다.
- 새로 추가한 함수에는 단위 테스트를 작성한다.

23원칙 4: 상황에 맞는 profile 사용

작업마다 필요한 속도와 안정성이 다릅니다.

예를 들어 빠른 질문에는 fast, 보안 리뷰에는 careful, CI 자동화에는 ci profile을 사용할 수 있습니다:

codex --profile fast "이 함수 설명해줘"
codex --profile careful "이 인증 로직 보안 리뷰해줘"
codex --profile ci "실패한 테스트 원인 분석해줘"

24원칙 5: 컨텍스트 관리

Codex는 긴 대화를 계속 기억하지만, 컨텍스트 창이 가득 차면 성능이 떨어질 수 있습니다.

이럴 때는 /compact를 사용합니다:

/compact

또는 필요한 파일만 명확히 지정합니다:

@src/auth/login.ts 이 파일 중심으로 입력값 검증 로직을 점검해줘.

25실수 1: 처음부터 danger-full-access 사용하기

codex --sandbox danger-full-access

이 모드는 Codex에게 매우 큰 권한을 줍니다. 초보자는 기본적으로 사용하지 않는 것이 좋습니다.

추천:

codex --sandbox workspace-write --ask-for-approval on-request

26실수 2: diff를 확인하지 않고 바로 커밋하기

Codex가 만든 코드도 사람이 검토해야 합니다.

항상 다음 순서를 지키는 것이 좋습니다:

작업 요청 → 변경 생성 → /diff 확인 → 테스트 실행 → 커밋

27실수 3: 너무 넓고 모호하게 요청하기

나쁜 예:

코드 좀 좋게 만들어줘.

좋은 예:

src/auth 폴더의 로그인 흐름을 읽고,
중복된 검증 로직을 줄이는 리팩터링 계획을 먼저 제안해줘.

28실수 4: AGENTS.md 없이 팀 프로젝트에 적용하기

팀 프로젝트에서는 작업 규칙이 중요합니다.

AGENTS.md 없이 Codex를 쓰면 팀의 스타일, 테스트 방식, 배포 규칙을 모른 채 작업할 수 있습니다.

29실수 5: MCP를 너무 많이 연결하기

MCP 서버가 많아지면 도구 정의가 늘어나고, 토큰 비용도 증가할 수 있습니다.

처음에는 꼭 필요한 MCP만 연결하는 것이 좋습니다.

30Codex 학습 로드맵

Codex를 한 문장으로 정리하면:

개발자의 로컬 프로젝트와 외부 도구를 이해하고, 안전장치 안에서 명령 실행과 파일 수정을 수행하는 멀티 표면 코딩 에이전트

초보자는 다음 순서로 익히면 됩니다:

설치 → 로그인 → CLI 실행 → 프로젝트 분석 요청
→ /plan 사용 → 코드 수정 요청 → /diff 확인
→ 테스트 실행 → AGENTS.md 작성 → profile 설정

섹션 01 · 마무리

이 장의 핵심 정리

Codex는 단순 챗봇이 아니라 코딩 에이전트다
Codex는 CLI, Desktop App, IDE Extension, Cloud, Chrome에서 사용할 수 있다
Codex를 잘 쓰려면 config.toml, Sandbox / Approval, AGENTS.md, MCP, Skills를 이해해야 한다
초보자는 workspace-write + on-request 조합으로 시작하는 것이 좋다
복잡한 작업은 /plan으로 먼저 계획하고, 변경 후에는 /diff로 반드시 확인해야 한다
프로젝트 규칙은 AGENTS.md에 적어두는 것이 좋다
긴 대화에서는 /compact로 컨텍스트를 관리한다

다음 단원

2. Codex 작동 방식 이해하기

2. Codex 작동 방식 이해하기

01Codex의 전체 구조

Codex는 크게 4개의 계층으로 이해할 수 있습니다.

Codex
├─ Surface Layer
│  ├─ CLI
│  ├─ Desktop App
│  ├─ IDE Extension
│  ├─ Cloud Tasks
│  └─ Chrome Extension
│
├─ Extension Layer
│  ├─ MCP
│  ├─ Skills
│  ├─ Apps
│  └─ Web Search
│
├─ Security Layer
│  ├─ Sandbox
│  └─ Approval Policy
│
└─ Core Layer
   ├─ GPT-5.x-Codex Intelligence
   ├─ Shell Tool
   ├─ Patch Tool
   ├─ Read Tool
   └─ Web Search Tool

Core Layer는 두뇌, Security Layer는 안전장치, Extension Layer는 확장부, Surface Layer는 사용자가 만나는 화면입니다.

02Core Layer: Codex의 두뇌

Core Layer는 Codex의 가장 안쪽에 있는 핵심 지능입니다. GPT-5.x-Codex 모델 계열을 기반으로 하며 사용자의 요청을 이해하고 실제 개발 작업을 계획합니다.

Core Layer가 담당하는 작업

코드베이스 구조 이해
파일 읽기
코드 수정 방향 판단
패치 생성
셸 명령 실행 계획
테스트 실행 결과 해석
오류 원인 분석
리팩터링 전략 수립
문서 작성
작업 요약

03Core Layer의 사고 흐름

사용자가 "로그인 API에서 이메일 형식 검증을 추가해줘"라고 요청했다고 가정해보겠습니다.

Codex의 Core Layer는 단순히 답변만 하지 않습니다. 보통 다음 흐름으로 생각합니다.

1. 로그인 API가 어디에 있는지 찾는다.
2. 관련 route, controller, service 파일을 읽는다.
3. 기존 validation 방식이 있는지 확인한다.
4. 프로젝트 스타일에 맞는 수정안을 만든다.
5. 필요한 경우 테스트 파일도 찾는다.
6. 변경 패치를 만든다.
7. 사용자가 확인할 수 있도록 diff를 보여준다.

즉, Core Layer는 추론, 판단, 코드 이해, 작업 계획의 중심입니다.

04Core Layer에서 사용하는 도구

Codex의 두뇌는 혼자서만 일하지 않습니다. 필요한 작업을 수행하기 위해 여러 도구를 사용합니다.

Read

파일 내용을 읽음

Shell

터미널 명령 실행

Patch

파일 수정 사항 적용

Web Search

필요한 경우 웹 정보 검색

MCP Tools

외부 서비스와 연결

이 구조 때문에 Codex는 단순히 설명만 하는 것이 아니라, 실제 개발 환경에서 행동하는 에이전트처럼 움직일 수 있습니다.

05Security Layer: 안전장치

Codex는 실제 명령을 실행하고 파일을 수정할 수 있기 때문에, 반드시 안전장치가 필요합니다. Security Layer는 두 부분으로 이루어집니다.

Sandbox

Codex가 접근할 수 있는 범위를 제한

Approval Policy

특정 작업 전에 사용자 허락이 필요한지 결정

06Sandbox 모드

Sandbox는 Codex가 기술적으로 어디까지 접근할 수 있는지 제한합니다.

대표적인 sandbox 모드:

read-only

파일 읽기만 가능

workspace-write

현재 작업 공간 중심으로 읽기/쓰기 가능

danger-full-access

전체 시스템 접근 가능

초보자에게 가장 적합한 기본값:

sandbox_mode = "workspace-write"

이 모드는 실제 개발 작업을 할 수 있으면서도, 시스템 전체를 무제한으로 열어주지는 않습니다.

07Approval Policy

Approval Policy는 Codex가 어떤 작업을 하기 전에 사용자에게 허락을 받아야 하는지 결정합니다.

대표적인 approval 정책:

untrusted

읽기 외 대부분 작업에 승인 요청

on-request

일반 작업은 진행, 위험하거나 범위를 넘는 작업은 승인 요청

never

승인 요청 없이 진행

초보자 추천 조합:

sandbox_mode = "workspace-write"
approval_policy = "on-request"

이 조합은 작업 효율과 안전성의 균형이 좋습니다.

08OS 수준의 샌드박스

Codex의 sandbox는 단순한 약속이 아니라, 운영체제 수준의 제한을 사용합니다.

macOS

Seatbelt

Linux

Landlock + seccomp

Windows

Restricted token 기반 sandbox

이 점이 중요한 이유는 Codex가 단순히 "하지 않겠습니다"라고 약속하는 것이 아니라, 운영체제 차원에서 접근 권한을 제한한다는 점입니다.

Sandbox는 Codex에게 씌우는 안전 울타리입니다. Codex가 실수하더라도 울타리 밖으로 나가지 못하게 막습니다.

09Extension Layer 개요

Extension Layer는 Codex가 기본 기능을 넘어 외부 도구와 연결되도록 해주는 계층입니다.

대표 구성:

MCP — GitHub, Figma, Sentry 같은 외부 서비스 연결
Skills — 특정 작업을 더 잘 수행하도록 만드는 재사용 가능한 작업 지식
Apps — ChatGPT connectors와 연결되는 영역
Web Search — 인터넷의 최신 정보를 참고할 수 있게 함

10MCP (Model Context Protocol)

MCP를 사용하면 Codex가 외부 서비스에 연결될 수 있습니다.

연결 가능한 서비스:

GitHub
Figma
Sentry
데이터베이스
사내 API
문서 시스템
이슈 트래커

예시: Sentry MCP가 연결되어 있다면, Codex가 실제 에러 로그를 확인하고 관련 코드 위치를 찾아 수정 방향을 제안할 수 있습니다.

MCP는 Codex를 단순 코드 도우미에서 외부 업무 시스템과 연결된 개발 에이전트로 확장합니다.

11Skills와 Apps

Skills는 Codex가 특정 작업을 더 잘 수행하도록 만드는 재사용 가능한 작업 지식입니다.

만들 수 있는 skill 예시:

테스트 작성 skill
PR 리뷰 skill
보안 점검 skill
API 문서화 skill
마이그레이션 점검 skill
릴리즈 노트 작성 skill

Skills는 Codex에게 특정 업무 방식을 가르쳐두는 재사용 가능한 매뉴얼입니다.

Apps는 ChatGPT connectors와 연결되며, 코드베이스 바깥의 업무 맥락을 참고할 수 있게 합니다.

12Web Search

Web Search는 Codex가 인터넷의 최신 정보를 참고할 수 있게 해줍니다.

유용한 작업:

최신 라이브러리 사용법 확인
최근 API 변경사항 확인
에러 메시지 검색
공식 문서 참고
보안 권고 확인

단, 모든 작업에 웹 검색이 필요한 것은 아닙니다. 프로젝트 내부 코드만 보면 되는 작업은 파일 읽기와 shell 실행만으로 충분한 경우가 많습니다.

13Surface Layer: Codex를 사용하는 화면

Surface Layer는 사용자가 Codex와 실제로 만나는 인터페이스입니다. Codex는 하나의 화면만 제공하지 않습니다.

여러 화면에서 사용할 수 있습니다:

CLI — 터미널에서
Desktop App — 시각적 인터페이스
IDE Extension — 에디터 안에서
Cloud Tasks — 원격 환경에서
Chrome Extension — 브라우저에서

14CLI (Command Line Interface)

CLI는 터미널에서 Codex를 사용하는 방식입니다.

기본 실행:

codex

프롬프트를 바로 전달:

codex "이 프로젝트 구조를 설명해줘"

CLI가 좋은 상황:

터미널 중심 개발
빠른 코드 분석
버그 수정
테스트 실행
git diff 확인
자동화 스크립트
CI/CD 연결

CLI는 가장 기본적이면서도 강력한 사용 방식입니다.

15Desktop App

Desktop App은 Codex를 시각적으로 사용할 수 있는 앱입니다.

CLI보다 더 편리한 기능:

여러 작업을 동시에 관리
각 작업을 별도 worktree에서 실행
변경사항을 시각적으로 검토
대화 fork
내장 terminal 사용
자동화 작업 관리
Appshots 사용
Computer Use 기능 사용

Desktop App이 좋은 상황:

여러 작업을 동시에 돌릴 때

작업별 thread 관리가 쉬움

diff를 눈으로 자세히 보고 싶을 때

시각적 리뷰가 편함

팀원이 Codex에 익숙하지 않을 때

터미널 지식이 적어도 사용 가능

장기 작업을 관리할 때

작업 흐름을 분리하기 좋음

16IDE Extension

IDE Extension은 VS Code, Cursor, Windsurf 같은 에디터 안에서 Codex를 사용하는 방식입니다.

IDE Extension이 좋은 상황:

현재 열려 있는 파일을 바로 수정하고 싶을 때
코드를 보면서 질문하고 싶을 때
inline edit이 필요할 때
컴파일 → 수정 → 테스트 흐름을 빠르게 반복할 때
에디터 중심으로 개발할 때

IDE Extension은 초보자가 가장 자연스럽게 느낄 수 있는 방식입니다. 이미 사용 중인 에디터 안에서 Codex를 부를 수 있기 때문입니다.

17Codex Cloud와 Chrome Extension

Codex Cloud는 작업을 로컬 컴퓨터가 아니라 OpenAI가 관리하는 환경에서 실행하는 방식입니다.

Cloud 작업이 좋은 상황:

오래 걸리는 리팩터링
여러 이슈 동시 처리
대규모 코드 변경
PR 생성까지 이어지는 작업
로컬 컴퓨터를 계속 켜두기 어려운 작업
독립적으로 실행해도 되는 작업

Codex for Chrome는 브라우저 기반 작업에 적합합니다. 관리자 콘솔, 내부 대시보드, CMS 콘텐츠, 티켓 시스템 등에 사용할 수 있습니다.

18표면별 사용 추천

Codex를 잘 쓰는 사람들은 하나의 화면만 고집하지 않습니다. 작업 성격에 따라 적절한 표면을 선택합니다.

빠른 질문

CLI

현재 파일 수정

IDE Extension

큰 리팩터링 계획

CLI + /plan

여러 작업 병렬 진행

Desktop App

오래 걸리는 작업

Cloud

브라우저 업무

Chrome Extension

Codex는 하나의 도구라기보다 상황별로 다른 표면을 가진 통합 개발 에이전트입니다.

19Codex의 기본 작업 흐름

Codex가 실제로 작업하는 흐름은 보통 다음과 같습니다.

사용자가 요청한다.
Codex가 현재 프로젝트와 설정을 확인한다.
AGENTS.md 같은 프로젝트 지침을 읽는다.
필요한 파일을 찾는다.
관련 코드를 읽는다.
작업 계획을 세운다.
필요한 경우 shell 명령을 실행한다.
파일 수정안을 만든다.
diff를 보여준다.
사용자가 검토한다.
테스트를 실행한다.
결과를 요약한다.

20실제 사례: 비밀번호 검증 추가

사용자가 "회원가입 API에 비밀번호 길이 검증을 추가해줘"라고 요청했다고 가정하겠습니다.

Codex는 보통 다음을 확인합니다.

회원가입 API route는 어디인가?
validation 로직은 기존에 어디에 있는가?
비밀번호 정책이 이미 정의되어 있는가?
테스트 파일은 어디에 있는가?
에러 응답 형식은 어떤 구조인가?
변경 후 어떤 테스트를 실행해야 하는가?

이런 과정을 거친 뒤 Codex는 수정안을 만듭니다.

21AGENTS.md: 프로젝트 지침 파일

Codex는 프로젝트에 AGENTS.md가 있으면 이를 중요한 지침으로 사용합니다.

예시 AGENTS.md 내용:

# AGENTS.md

- 모든 변경 후 npm test를 실행한다.
- TypeScript strict mode 기준으로 작성한다.
- 기존 API 응답 형식을 깨지 않는다.
- 새 기능에는 테스트를 추가한다.

그러면 Codex는 작업할 때 이 규칙을 참고합니다. 매번 지시문으로 반복하지 않아도 됩니다.

AGENTS.md는 Codex가 프로젝트에 맞게 행동하도록 만드는 핵심 장치입니다.

22Codex의 설정 우선순위

Codex는 여러 위치에서 설정을 읽습니다. 우선순위는 다음과 같습니다.

실행할 때 전달한 CLI 옵션
프로젝트 설정 파일
사용자 설정 파일
시스템 설정 파일
Codex 기본값

예시:

codex -m gpt-5.4 "이 코드 리뷰해줘"

이 경우 해당 세션에서는 gpt-5.4가 사용됩니다.

실행할 때 직접 지정한 옵션이 가장 강합니다.

23컨텍스트 관리

Codex는 대화 내용, 읽은 파일, 명령 결과, 프로젝트 지침 등을 컨텍스트로 사용합니다.

하지만 컨텍스트에는 한계가 있습니다. 대화가 너무 길어지거나 많은 파일을 읽으면 컨텍스트가 가득 찰 수 있습니다.

이때 사용하는 명령:

/compact

/compact는 긴 대화 내용을 요약해서 컨텍스트 공간을 확보하는 데 사용합니다.

또한 필요한 파일을 직접 지정하면 Codex가 더 효율적으로 작업할 수 있습니다.

@src/auth/login.ts 이 파일 중심으로 로그인 검증 로직을 점검해줘.

작업 범위가 작을수록 Codex가 더 정확하게 일합니다.

24초보자를 위한 추천 이해 순서

처음부터 모든 구조를 외울 필요는 없습니다. 아래 순서로 이해하면 됩니다.

CLI 또는 IDE에서 Codex를 실행한다.
Codex가 파일을 읽고 수정할 수 있다는 점을 이해한다.
sandbox와 approval이 안전장치라는 점을 이해한다.
/plan과 /diff로 안전하게 작업하는 습관을 만든다.
AGENTS.md로 프로젝트 규칙을 알려준다.
config.toml로 기본 동작을 설정한다.
필요해지면 MCP와 Skills로 확장한다.
큰 작업은 Desktop App이나 Cloud로 분리한다.

처음에는 다음 세 가지만 알아도 충분합니다.

Codex는 코드를 읽는다. Codex는 명령을 실행할 수 있다. Codex는 sandbox와 approval 안에서 안전하게 움직인다.

25초보자용 실전 시나리오

상황

처음 보는 프로젝트를 받았습니다. 무엇부터 봐야 할지 모릅니다.

Codex 실행

cd my-project
codex

첫 요청

이 프로젝트의 전체 구조를 초보자도 이해할 수 있게 설명해줘.
주요 폴더, 실행 방법, 테스트 방법, 핵심 진입점을 정리해줘.

26초보자용 시나리오 (계속)

다음 요청

/plan 이 프로젝트에서 로그인 기능이 어떻게 동작하는지 분석해줘.
관련 파일을 찾고, 데이터 흐름을 단계별로 설명하는 계획을 먼저 세워줘.

변경 요청

로그인 API에 이메일 형식 검증이 없다면 추가해줘.
기존 validation 스타일을 먼저 확인하고 같은 방식으로 적용해줘.

변경 확인

/diff

테스트 요청

관련 테스트를 실행하고 결과를 요약해줘.

이 흐름이 Codex의 가장 기본적인 사용 패턴입니다.

섹션 02 · 마무리

이 단원에서 기억할 것

Codex는 4개 계층(Core, Security, Extension, Surface)으로 이루어진 통합 개발 에이전트입니다.

Core Layer는 Codex의 두뇌로, 코드 이해와 작업 계획을 담당합니다.
Security Layer는 sandbox와 approval로 안전성을 보장합니다.
Extension Layer는 MCP, Skills, Apps, Web Search로 확장합니다.
Surface Layer는 CLI, Desktop App, IDE Extension, Cloud, Chrome 등 다양한 화면을 제공합니다.
AGENTS.md와 config.toml로 프로젝트 규칙을 정의합니다.
초보자는 CLI 또는 IDE에서 시작하는 것이 좋습니다.

다음 단원

3단원. Codex 설치하기

3. Codex 설치하기

01설치 전 확인할 것

Codex를 설치하기 전에 아래 항목을 먼저 확인합니다.

운영체제

macOS, Linux, Windows 지원

터미널

macOS Terminal, iTerm2, Linux shell, Windows PowerShell 등

Git

프로젝트 변경사항 확인에 필요

npm

npm 방식으로 설치할 경우 필요

Homebrew

macOS에서 Homebrew 방식으로 설치할 경우 필요

인증 정보

ChatGPT 계정 또는 API Key (Codex 인증에 필요)

Codex CLI는 로컬 터미널에서 실행되는 코딩 에이전트이며, 선택한 디렉터리 안에서 코드를 읽고, 수정하고, 명령을 실행할 수 있습니다.

02초보자 추천 설치 방법

초보자는 운영체제에 따라 아래 방식으로 시작하면 됩니다.

macOS

standalone installer 또는 Homebrew

Linux

standalone installer 또는 npm

Windows

PowerShell installer 또는 npm

WSL2

Linux 방식으로 설치

가장 단순한 기준:

macOS / Linux → standalone installer
Windows → PowerShell installer
Node.js 환경이 이미 있음 → npm
macOS에서 Homebrew를 자주 씀 → Homebrew

03macOS / Linux: 공식 standalone installer

macOS 또는 Linux에서는 공식 installer를 사용할 수 있습니다.

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

이 방식은 별도의 npm이나 Homebrew 없이 Codex CLI를 설치할 수 있는 방식입니다.

설치 후 터미널에서 다음 명령을 실행합니다.

codex

처음 실행하면 로그인 절차가 표시됩니다.

04Unattended install

CI, 원격 서버, 자동화 환경처럼 대화형 입력 없이 설치해야 하는 경우:

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

CODEX_NON_INTERACTIVE=1은 설치 과정에서 대화형 입력을 줄이기 위한 환경 변수입니다.

05Windows: PowerShell installer

Windows에서는 PowerShell에서 설치할 수 있습니다.

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

설치 후 PowerShell에서 다음 명령을 실행합니다.

codex

Windows에서는 native PowerShell 환경에서 Codex를 사용할 수 있고, Linux 네이티브 환경이 필요한 경우 WSL2를 사용할 수도 있습니다.

06npm으로 설치하기

Node.js와 npm이 이미 설치되어 있다면 npm으로 설치할 수 있습니다.

npm install -g @openai/codex

설치 후 실행합니다.

codex

npm 방식은 macOS, Linux, Windows 모두에서 사용할 수 있는 범용 설치 방식입니다.

업데이트할 때는 다음 명령을 사용합니다.

npm install -g @openai/codex@latest

07Homebrew로 설치하기

macOS에서 Homebrew를 사용한다면 다음 명령으로 설치할 수 있습니다.

brew install --cask codex

설치 후 실행합니다.

codex

업데이트는 보통 다음처럼 진행합니다.

brew update
brew upgrade --cask codex

08winget으로 설치하기

Windows에서 winget을 사용하는 설치 방식도 가능합니다.

winget install OpenAI.Codex

다만 최신 공식 Codex CLI quickstart에서는 Windows 설치 방식으로 PowerShell installer를 명시적으로 안내하고 있습니다. Windows 초보자는 다음 방식을 우선 추천합니다.

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

winget을 사용할 경우 설치 후 반드시 다음을 확인합니다.

codex --version

09바이너리 직접 다운로드

npm, Homebrew, installer를 사용할 수 없는 환경에서는 GitHub Releases에서 플랫폼별 바이너리를 직접 다운로드할 수 있습니다.

macOS Apple Silicon / arm64

codex-aarch64-apple-darwin.tar.gz

macOS Intel / x86_64

codex-x86_64-apple-darwin.tar.gz

Linux x86_64

codex-x86_64-unknown-linux-musl.tar.gz

Linux arm64

codex-aarch64-unknown-linux-musl.tar.gz

다운로드 후에는 압축을 풀고 실행 파일 이름을 codex로 바꾼 뒤 PATH에 넣습니다.

10바이너리 직접 다운로드 · 설치 예시

tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex-x86_64-unknown-linux-musl codex
chmod +x codex
sudo mv codex /usr/local/bin/

설치 확인:

codex --version

11설치 확인하기

설치가 끝나면 다음 명령으로 Codex가 정상 설치되었는지 확인합니다.

codex --version

정상적으로 설치되었다면 버전이 출력됩니다.

codex-cli 0.136.0

그다음 Codex를 실행합니다.

codex

처음 실행하면 로그인 화면이 나타납니다.

12Codex 업그레이드

Codex는 자주 업데이트됩니다. 새 버전에는 모델 지원, sandbox, permissions, hooks, plugins, desktop 연동, bug fix 등이 포함될 수 있으므로 주기적으로 업데이트하는 것이 좋습니다.

standalone installer 업그레이드

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

npm 업그레이드

npm install -g @openai/codex@latest

Homebrew 업그레이드

brew update
brew upgrade --cask codex

업그레이드 후 확인

codex --version

13Shell Completions 설정

Shell completions를 설정하면 터미널에서 Codex 명령어 자동완성을 사용할 수 있습니다.

bash

codex completion bash > /etc/bash_completion.d/codex

권한 문제가 있으면 sudo를 사용합니다.

codex completion bash | sudo tee /etc/bash_completion.d/codex

zsh

mkdir -p ~/.zsh/completions
codex completion zsh > ~/.zsh/completions/_codex

14Shell Completions 설정 (계속)

~/.zshrc에 completion 경로가 없다면 다음을 추가합니다.

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit
compinit

적용:

source ~/.zshrc

fish

mkdir -p ~/.config/fish/completions
codex completion fish > ~/.config/fish/completions/codex.fish

적용:

source ~/.config/fish/config.fish

15설치 후 첫 실행

설치가 끝났다면 프로젝트 폴더로 이동합니다.

cd my-project

Codex를 실행합니다.

codex

처음 실행 시 로그인 절차가 표시됩니다. 초보자에게는 ChatGPT 계정 로그인을 추천합니다. API key 방식도 가능하지만 일부 기능은 계정 로그인 방식과 차이가 있을 수 있으므로, 처음에는 ChatGPT 계정 로그인이 가장 단순합니다.

16설치 방식별 장단점

standalone installer

가장 단순, npm 불필요 | macOS/Linux 초보자에게 추천

PowerShell installer

Windows 공식 quickstart 방식 | Windows 사용자 추천

npm

OS 범용, 업데이트 쉬움 | Node.js 개발자 추천

Homebrew

macOS에서 관리 쉬움 | macOS 개발자 추천

winget

Windows 패키지 관리 | Windows 고급 사용자 추천

바이너리 직접 다운로드

패키지 매니저 불필요 | 제한된 서버/고급 사용자 추천

17PATH 문제 해결

설치 후 codex 명령이 인식되지 않는다면 대부분 PATH 문제입니다.

오류 예시:

codex: command not found

Windows PowerShell:

codex : The term 'codex' is not recognized

확인할 것:

which codex

Windows PowerShell:

where.exe codex

현재 PATH 확인:

echo $PATH

Windows PowerShell:

$env:Path

18설치 보안 주의사항

Codex는 인증 토큰과 프로젝트 코드에 접근할 수 있으므로 설치 출처가 매우 중요합니다. 반드시 다음 출처만 사용합니다.

공식 OpenAI 문서
공식 openai/codex GitHub 저장소
공식 npm 패키지 @openai/codex
공식 installer URL

최근에는 Codex 관련 개발자를 노린 악성 npm 패키지가 인증 토큰을 훔치는 사례가 보도되었습니다.

따라서 설치할 때는 이름이 비슷한 비공식 패키지를 피해야 합니다.

잘못된 예:

npm install -g codex
npm install -g codex-ui
npm install -g codexui-android

권장:

npm install -g @openai/codex

19설치 후 바로 해볼 기본 명령어

설치가 끝나면 아래 순서로 확인합니다.

codex --version

codex

프로젝트 폴더에서 실행합니다.

cd my-project
codex

또는 한 줄 명령으로 실행할 수도 있습니다.

codex "이 프로젝트가 어떤 구조인지 설명해줘"

20설치 문제 해결 ① · ②

문제 1. codex 명령을 찾을 수 없음

증상:

command not found: codex

해결:

codex --version
which codex
echo $PATH

npm 설치라면 다시 설치합니다.

npm install -g @openai/codex@latest

문제 2. npm 권한 오류

증상:

EACCES: permission denied

가장 단순한 우회는 standalone installer를 사용하는 것입니다.

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

21설치 문제 해결 ③ · ④

npm global prefix 설정

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

shell 설정 파일에 추가합니다.

export PATH="$HOME/.npm-global/bin:$PATH"

적용:

source ~/.zshrc

또는:

source ~/.bashrc

문제 3. Windows PowerShell 실행 정책 문제

현재 정책 확인:

Get-ExecutionPolicy

설치 명령은 일시적으로 ByPass를 사용합니다.

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

22설치 문제 해결 ⑤

문제 4. 설치는 됐지만 로그인 화면이 안 나옴

먼저 버전을 확인합니다.

codex --version

다시 실행합니다.

codex

그래도 문제가 있으면 기존 설정 또는 인증 파일 문제일 수 있습니다. 다음 장의 인증 파트에서 다룹니다.

문제 5. 오래된 버전이 실행됨

여러 방식으로 설치하면 PATH 앞쪽에 있는 오래된 Codex가 실행될 수 있습니다.

확인:

which codex
codex --version

Windows:

where.exe codex
codex --version

중복 설치를 정리한 뒤 다시 설치하거나 업데이트합니다.

23초보자용 설치 체크리스트

아래 항목을 모두 확인하면 설치가 끝난 것입니다.

□ 운영체제 확인

내 운영체제에 맞는 설치 방식을 선택했다

□ 공식 출처

공식 출처의 설치 명령만 사용했다

□ 버전 확인

codex --version이 정상 출력된다

□ 프로젝트 폴더

프로젝트 폴더에서 codex를 실행할 수 있다

□ 로그인 화면

첫 실행 시 로그인 화면이 표시된다

□ npm 패키지명

npm 설치 시 패키지명이 @openai/codex인지 확인했다

□ 비공식 패키지

비공식 Codex 유사 패키지를 설치하지 않았다

섹션 03 · 마무리

이 단원에서 기억할 것

Codex는 macOS, Linux, Windows에서 모두 사용할 수 있습니다. 초보자에게 추천하는 설치 방식은 운영체제에 따라 다릅니다.

macOS/Linux 초보자: standalone installer가 가장 단순
Windows 초보자: PowerShell installer 우선 추천
Node.js 개발자: npm 설치 (npm install -g @openai/codex)
macOS Homebrew 사용자: brew install --cask codex

설치 후에는 반드시 codex --version으로 확인하고, 비공식 패키지나 이름이 비슷한 패키지는 설치하지 마세요.

다음 단원

4단원. Codex 인증하기

4. Codex 인증하기

01인증 방식 한눈에 보기

Codex에서 사용할 수 있는 대표 인증 방식은 다음과 같습니다.

ChatGPT OAuth

대부분의 사용자 —

codex login

Device Auth

원격 서버, 브라우저 자동 실행이 어려운 환경 —

codex login --device-auth

API Key

API 기반 사용, 자동화, 별도 키 관리 환경 —

codex login --with-api-key

Access Token

이미 발급된 access token을 사용하는 고급 환경 —

codex login --with-access-token

초보자에게는 ChatGPT OAuth 로그인을 추천합니다.

02ChatGPT 계정으로 로그인하기

가장 기본적인 인증 방법입니다.

터미널에서 다음 명령을 실행합니다.

codex login

브라우저가 열리면 ChatGPT 계정으로 로그인합니다. 로그인 후 다시 터미널로 돌아오면 Codex를 사용할 수 있습니다.

로그인 상태 확인:

codex login status

정상적으로 로그인되어 있다면 현재 인증 모드가 출력됩니다.

03ChatGPT 로그인을 추천하는 이유

처음 사용하는 사람에게는 API Key보다 ChatGPT 계정 로그인이 더 쉽습니다.

설정이 단순함

브라우저에서 로그인하면 됨

키 복사 실수 위험이 적음

API Key를 직접 다루지 않음

계정 플랜과 연결됨

Plus, Pro, Business, Enterprise 등 계정 권한을 사용할 수 있음

Desktop App, Cloud 기능과 연결하기 쉬움

계정 기반 기능 사용에 적합

04Device Auth로 로그인하기

브라우저가 자동으로 열리지 않는 환경에서는 Device Auth를 사용할 수 있습니다.

예를 들어 다음 상황에서 유용합니다:

원격 서버
SSH 접속 환경
Headless 서버
브라우저가 없는 개발 환경
터미널만 사용할 수 있는 환경

명령어:

codex login --device-auth

이 명령을 실행하면 터미널에 인증 URL과 코드가 표시됩니다. 사용자는 다른 기기나 브라우저에서 URL을 열고 코드를 입력해 로그인합니다.

05Device Auth 흐름

Device Auth의 인증 과정은 다음과 같습니다.

1원격 서버에서 codex login --device-auth 실행

2터미널에 인증 URL과 코드 표시

3내 로컬 브라우저에서 URL 접속

4코드 입력

5ChatGPT 계정 로그인

6원격 서버의 Codex 인증 완료

06API Key로 로그인하기

API Key를 사용해 Codex를 인증할 수도 있습니다. 공식 CLI reference 기준으로 API Key는 stdin으로 전달합니다.

예시:

printenv OPENAI_API_KEY | codex login --with-api-key

또는 직접 입력할 수도 있습니다.

codex login --with-api-key

이 경우 터미널이 API Key 입력을 기다립니다.

보안상 주의: API Key를 명령어에 그대로 적는 방식은 피하는 것이 좋습니다.

07API Key 입력 방식

나쁜 예 — 명령어에 키를 노출:

codex login --with-api-key sk-...

권장 방식 — 환경 변수와 stdin 사용:

export OPENAI_API_KEY="sk-..."
printenv OPENAI_API_KEY | codex login --with-api-key

이 방식은 터미널 히스토리에 키가 남지 않아 더 안전합니다.

08API Key 방식이 적합한 경우

API Key 로그인은 다음 상황에 적합합니다.

CI/CD 자동화

브라우저 로그인 없이 인증 가능

서버 환경

계정 OAuth보다 환경 변수 관리가 쉬움

조직별 API 사용량 관리

API billing 기준으로 관리 가능

SDK / 자동화 스크립트

토큰 기반 실행 흐름에 적합

다만 초보자는 API Key를 직접 관리하다가 노출할 위험이 있으므로, 처음에는 ChatGPT OAuth 로그인을 권장합니다.

09Access Token으로 로그인하기

고급 환경에서는 access token을 stdin으로 전달할 수도 있습니다.

printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

이 방식은 일반 초보자용이라기보다, 이미 access token을 안전하게 발급·관리하는 자동화 환경에서 사용합니다.

초보자는 보통 이 방식을 사용할 필요가 없습니다.

10로그인 상태 확인하기

현재 Codex가 로그인되어 있는지 확인하려면 다음 명령을 사용합니다.

codex login status

이 명령은 현재 인증 모드를 출력하고, 자격 증명이 있으면 종료 코드 0을 반환합니다.

자동화 스크립트 예시:

if codex login status >/dev/null 2>&1; then
  echo "Codex is logged in"
else
  echo "Codex is not logged in"
fi

초보자도 문제가 생기면 가장 먼저 이 명령을 실행해보면 됩니다.

11로그아웃하기

저장된 인증 정보를 삭제하려면 다음 명령을 사용합니다.

codex logout

codex logout은 저장된 API key와 ChatGPT 인증 정보를 제거합니다.

다음 상황에서 로그아웃을 권장합니다:

공용 컴퓨터에서 사용한 경우

계정 보호

회사 장비 반납 전

인증 정보 제거

다른 계정으로 전환할 때

기존 인증 충돌 방지

API Key를 교체할 때

오래된 키 제거

12인증 정보 저장 방식 설정하기

Codex는 인증 정보를 저장해야 다음 실행 때 다시 로그인하지 않아도 됩니다. 자격 증명 저장 방식은 config.toml의 cli_auth_credentials_store로 설정할 수 있습니다.

file

파일에 자격 증명 저장

keyring

운영체제 키체인 또는 보안 저장소 사용

auto

가능하면 keyring을 사용하고, 불가능하면 file로 대체

초보자에게는 auto 설정을 추천합니다. 보안이 중요한 회사 장비에서는 keyring 사용을 검토합니다.

13로그인 방식을 강제하기

조직이나 팀 환경에서는 로그인 방식을 제한하고 싶을 수 있습니다. config.toml의 forced_login_method 설정으로 가능합니다.

ChatGPT 로그인만 사용하도록 강제:

forced_login_method = "chatgpt"

또는 API Key 방식만 쓰도록 정할 수 있습니다:

forced_login_method = "api"

이 설정은 개인 초보자보다는 팀, 회사, 엔터프라이즈 환경에서 더 중요합니다.

14MCP OAuth 인증과 Codex 로그인의 차이

Codex에는 두 종류의 인증이 등장할 수 있습니다.

Codex 로그인

Codex CLI 자체 사용 권한

MCP OAuth 로그인

특정 MCP 서버나 외부 서비스 사용 권한

Codex 자체에 로그인:

codex login

MCP 서버에 로그인:

codex mcp login <server-name>

초보자는 먼저 Codex 자체 로그인을 완료하고, MCP는 나중에 외부 서비스 연동 장에서 다루면 됩니다.

15여러 계정 사용 시 주의사항

개인 계정과 회사 계정을 모두 사용하는 경우 인증 충돌이 생길 수 있습니다.

16인증과 플랜 권한

ChatGPT 계정으로 로그인하면 계정 플랜과 조직 설정에 따라 사용할 수 있는 Codex 기능이 달라질 수 있습니다.

영향을 주는 요소:

Plus / Pro / Business / Enterprise / Edu 등 구독 플랜
조직 관리자 설정
사용 가능한 모델
Cloud 작업 가능 여부
사용량 한도
팀 보안 정책

정확한 한도와 사용 가능 기능은 계정 상태와 조직 설정에 따라 달라질 수 있으므로, 문제가 있으면 먼저 로그인 상태를 확인합니다.

17인증 정보 보안 주의사항

API Key와 access token은 비밀번호와 비슷하게 취급해야 합니다.

절대 하지 말아야 할 것:

- API Key를 GitHub에 커밋하기
- API Key를 README에 붙여넣기
- API Key를 Slack, Discord 등에 그대로 공유하기
- 터미널 히스토리에 남는 방식으로 키 입력하기
- 출처가 불분명한 Codex 유사 패키지에 로그인하기

API Key를 환경 변수로 사용할 때도 .env 파일이 git에 올라가지 않도록 .gitignore에 추가합니다:

.env
.env.local
*.key

18인증 문제 해결

문제 1. 로그인했는데 Codex가 계속 로그인하라고 함

먼저 상태를 확인합니다:

codex login status

로그인 정보가 없다고 나오면 다시 로그인합니다. 그래도 반복되면 로그아웃 후 다시 로그인합니다:

codex logout
codex login

문제 2. 브라우저가 열리지 않음

브라우저 자동 실행이 안 되는 환경에서는 Device Auth를 사용합니다:

codex login --device-auth

19인증 문제 해결 (계속)

문제 3. 원격 서버에서 로그인할 수 없음

SSH 서버나 headless 환경에서는 다음 방식을 사용합니다:

codex login --device-auth

또는 API Key 방식:

printenv OPENAI_API_KEY | codex login --with-api-key

문제 4. API Key가 작동하지 않음

확인할 항목: 환경 변수 이름이 맞는가? • 실제 값이 비어 있지 않은가? • 키 앞뒤에 공백이 없는가? • 폐기되거나 회전된 키가 아닌가? • 조직에서 API 사용이 허용되어 있는가?

echo "$OPENAI_API_KEY"

20인증 문제 해결 (추가)

문제 5. 다른 계정으로 로그인되어 있음

현재 상태를 확인합니다:

codex login status

기존 인증을 제거합니다:

codex logout

다시 로그인합니다:

codex login

문제 6. CI에서 인증 실패

CI에서는 보통 API Key를 secret으로 등록한 뒤 stdin으로 전달합니다:

printenv OPENAI_API_KEY | codex login --with-api-key

21초보자용 인증 체크리스트

Codex 설치가 완료되었다

□

codex --version이 정상 출력된다

□

codex login을 실행했다

□

브라우저에서 ChatGPT 계정 로그인을 완료했다

□

codex login status로 로그인 상태를 확인했다

□

공용 컴퓨터라면 사용 후 codex logout을 실행한다

□

API Key를 사용하는 경우 터미널이나 Git에 노출하지 않는다

□

원격 서버에서는 codex login --device-auth를 사용한다

□

22추천 인증 흐름

초보자라면 아래 순서로 진행하면 됩니다:

codex --version
codex login
codex login status
codex

원격 서버라면 다음 흐름을 사용합니다:

codex --version
codex login --device-auth
codex login status
codex

자동화 환경이라면 다음 흐름을 사용합니다:

printenv OPENAI_API_KEY | codex login --with-api-key
codex login status

섹션 04 · 마무리

이 단원에서 기억할 것

Codex를 사용하려면 설치 후 인증이 필요합니다. 초보자는 codex login으로 ChatGPT 계정 로그인을 사용하는 것이 가장 쉽습니다. 브라우저를 열 수 없는 서버 환경에서는 codex login --device-auth를 사용하고, 자동화 환경에서는 API Key를 stdin으로 전달하는 방식을 권장합니다.

로그인 상태는 codex login status로, 로그아웃은 codex logout으로 처리하고, API Key와 access token은 절대 코드 저장소나 채팅에 노출하지 말 것입니다.

다음 단원

5단원. Quick Start: 첫 세션 시작하기

5. Quick Start: 첫 세션 시작하기

01첫 세션의 목표

첫 세션에서는 아래 흐름을 익히면 충분합니다.

프로젝트 폴더로 이동한다.
Codex를 실행한다.
프로젝트 구조를 설명시킨다.
작은 작업을 요청한다.
변경사항을 확인한다.
필요하면 테스트를 실행한다.
세션을 종료한다.

처음부터 대규모 리팩터링이나 자동화를 시도하지 않아도 됩니다. 첫 세션의 목적은 Codex가 내 프로젝트에서 어떻게 작동하는지 감각을 익히는 것입니다.

02실습 전 준비

먼저 아래 항목이 준비되어 있어야 합니다.

Codex 설치

codex --version

Codex 로그인

codex login status

Git 프로젝트

.git 폴더가 있는 프로젝트

터미널

macOS Terminal, iTerm2, Linux shell, PowerShell 등

코드 에디터

VS Code, Cursor, Windsurf 등

설치와 로그인 확인:

codex --version
codex login status

정상적으로 설치와 로그인이 되어 있다면 첫 세션을 시작할 수 있습니다.

03프로젝트 폴더로 이동하기

Codex는 현재 터미널이 위치한 폴더를 기준으로 프로젝트를 이해합니다. 먼저 작업할 프로젝트 폴더로 이동합니다.

cd ~/my-project

Git 프로젝트라면 다음처럼 확인할 수 있습니다.

git status

정상적인 프로젝트라면 현재 브랜치와 변경사항 상태가 출력됩니다.

On branch main
nothing to commit, working tree clean

초보자는 첫 실습을 운영 중인 중요한 프로젝트에서 바로 하지 말고, 테스트용 프로젝트나 개인 프로젝트에서 시작하는 것이 좋습니다.

04Codex 실행하기

프로젝트 폴더에서 Codex를 실행합니다.

codex

그러면 터미널 안에 Codex 대화형 화면이 열립니다. 이 화면을 보통 TUI, 즉 Terminal UI라고 부릅니다.

Codex가 실행되면 사용자는 자연어로 작업을 요청할 수 있습니다.

이 프로젝트가 어떤 구조인지 설명해줘.

처음에는 코드 변경을 요청하기보다, 프로젝트를 읽고 설명하게 하는 것이 좋습니다.

05첫 번째 요청: 프로젝트 구조 설명시키기

첫 요청은 다음처럼 입력합니다.

이 프로젝트의 구조를 초보자도 이해할 수 있게 설명해줘.
주요 폴더, 실행 방법, 테스트 방법, 핵심 진입점을 정리해줘.

Codex는 보통 다음을 확인합니다.

package.json, pyproject.toml, Cargo.toml 같은 프로젝트 설정 파일
README
src, app, lib, test 같은 주요 폴더
실행 스크립트
테스트 스크립트
프레임워크 구조
핵심 진입점

이 단계에서는 파일을 수정하지 않고, 프로젝트를 이해하는 데 집중합니다.

06좋은 첫 질문 예시

프로젝트 이해를 위한 좋은 첫 질문 예시입니다.

기술 스택

이 프로젝트가 어떤 기술 스택으로 만들어졌는지 설명해줘.

로컬 실행

이 프로젝트를 로컬에서 실행하려면 어떤 순서로 해야 하는지 알려줘.

테스트 실행

테스트는 어떤 명령어로 실행하는지 찾아줘.

역할별 정리

핵심 폴더와 파일을 역할별로 정리해줘.

07두 번째 요청: 작은 작업 요청하기

프로젝트 구조를 이해했다면 작은 작업을 하나 요청해봅니다. 처음에는 안전한 문서 수정이나 작은 코드 개선이 좋습니다.

README에 로컬 실행 방법 섹션이 없다면 추가해줘.

또는:

로그인 API의 입력값 검증 방식이 어떻게 되어 있는지 확인하고,
수정이 필요하면 먼저 어떤 변경이 필요한지 설명해줘.

초보자에게 추천하는 첫 작업은 변경 범위가 작고 위험이 낮은 것입니다.

08추천하는 첫 작업

README 보완

위험이 낮고 diff 확인이 쉬움

테스트 명령 찾기

코드 변경 없이 프로젝트 이해 가능

특정 함수 설명

파일 읽기 중심이라 안전함

작은 validation 추가

실제 코드 수정 흐름을 익히기 좋음

주석 보완

변경 범위가 작음

처음부터 피해야 할 요청:

프로젝트 전체를 리팩터링해줘.
아키텍처를 전부 갈아엎어줘.
테스트를 전부 고치고 배포까지 해줘.

첫 세션에서는 작고 명확한 작업이 좋습니다.

09복잡한 작업은 /plan으로 먼저 시작하기

작업이 조금이라도 복잡하다면 바로 실행하지 말고 /plan을 사용합니다.

/plan 로그인 API에 입력값 검증을 추가하려고 해.
관련 파일을 찾고, 기존 validation 방식과 테스트 위치를 확인한 뒤
단계별 작업 계획을 먼저 제안해줘.

/plan은 Codex가 바로 파일을 수정하기 전에, 먼저 접근 방법을 정리하게 만드는 명령입니다.

파일 1~2개짜리 작은 작업 → 바로 요청 가능 / 파일 3개 이상 바뀔 것 같은 작업 → /plan 먼저 사용

10/plan이 유용한 상황

여러 파일이 바뀔 가능성

변경 범위를 먼저 확인해야 함

기존 구조를 잘 모름

잘못된 파일을 수정할 수 있음

인증, 결제, 권한 관련 작업

위험도가 높음

리팩터링

영향 범위를 예측해야 함

테스트 추가

기존 테스트 구조를 먼저 봐야 함

11Codex가 작업하는 동안 개입하기

Codex가 작업하는 중에도 사용자가 방향을 수정할 수 있습니다.

그 파일이 아니라 src/auth/login.ts를 중심으로 봐줘.

테스트 범위를 바꾸고 싶다면:

전체 테스트 대신 로그인 관련 테스트만 먼저 실행해줘.

작업 범위를 줄이고 싶다면:

이번에는 코드 수정하지 말고 분석만 해줘.

초보자는 Codex가 항상 완벽하게 의도를 맞힌다고 생각하지 말고, 작업 중간에 방향을 계속 조정할 수 있다고 이해하면 됩니다.

12변경사항 확인하기: /diff

Codex가 파일을 수정했다면 반드시 변경사항을 확인해야 합니다.

/diff

/diff는 현재 세션에서 Codex가 만든 변경사항을 보여줍니다. 확인할 항목:

변경 파일

의도한 파일만 바뀌었는가?

변경 범위

너무 많은 코드가 바뀌지 않았는가?

기존 동작

기존 API나 UI가 깨지지 않는가?

테스트

관련 테스트가 추가되거나 수정되었는가?

보안

민감한 정보가 노출되지 않았는가?

스타일

프로젝트 코드 스타일과 맞는가?

Codex가 수정했다면 반드시 /diff를 본다.

13/diff를 반드시 확인할 작업

특히 아래 작업 후에는 /diff를 반드시 확인합니다.

인증 로직 수정
결제 로직 수정
권한 처리 수정
데이터베이스 schema 변경
환경 변수 변경
CI/CD 설정 변경
대규모 리팩터링

초보자에게 가장 중요한 습관은 다음입니다.

Codex가 수정했다면 반드시 /diff를 본다.

14테스트 실행하기

변경사항을 확인했다면 관련 테스트를 실행합니다. Codex에게 테스트 명령을 찾아달라고 할 수 있습니다.

이 프로젝트에서 관련 테스트를 실행하는 명령어를 찾아줘.

또는 직접 요청할 수 있습니다.

방금 변경한 부분과 관련된 테스트를 실행하고 결과를 요약해줘.

예시 테스트 명령:

npm test
pytest
pnpm test
cargo test
go test ./...

테스트가 실패하면 바로 "고쳐줘"라고 하기보다, 먼저 원인을 분석하게 하는 것이 좋습니다.

15작업 결과 요약시키기

작업이 끝나면 Codex에게 요약을 요청합니다.

이번 세션에서 변경한 내용을 요약해줘.
변경 파일, 핵심 수정 내용, 실행한 테스트, 남은 TODO를 정리해줘.

좋은 요약 형식:

변경 파일:
- src/auth/login.ts
- src/auth/login.test.ts

핵심 변경:
- 이메일 형식 검증 추가
- 잘못된 이메일 입력 시 400 응답 반환
- 기존 에러 응답 형식 유지

테스트:
- npm test -- login 실행
- 모든 관련 테스트 통과

이 요약은 커밋 메시지나 PR 설명을 작성할 때도 유용합니다.

16세션 종료하기

작업이 끝났다면 Codex를 종료합니다.

/quit

또는:

/exit

터미널로 돌아온 뒤 Git 상태를 확인합니다.

git status
git diff

변경사항을 다시 확인한 뒤 필요하다면 커밋합니다.

git add .
git commit -m "Add login email validation"

초보자는 Codex가 만든 변경사항을 충분히 검토한 뒤 커밋하는 것이 좋습니다.

17첫 세션 예시 전체 흐름

아래는 첫 세션의 전체 예시입니다.

cd ~/my-project
codex

Codex 안에서 입력합니다.

이 프로젝트의 구조를 초보자도 이해할 수 있게 설명해줘.
주요 폴더, 실행 방법, 테스트 방법, 핵심 진입점을 정리해줘.

작은 작업을 요청합니다.

README에 로컬 실행 방법 섹션이 없다면 추가해줘.
기존 README 스타일에 맞춰 작성해줘.

변경사항을 확인합니다.

/diff

검증을 확인하고 요약한 뒤 종료합니다.

18한 줄 명령으로 시작하기

Codex는 대화형 TUI를 열지 않고, 시작 프롬프트를 바로 전달할 수도 있습니다.

codex "이 프로젝트 구조를 설명해줘"

또는:

codex "실패한 테스트의 원인을 분석해줘"

이 방식은 빠른 질문에 유용합니다. 다만 초보자는 처음에는 대화형 모드로 실행하는 것이 좋습니다.

codex

대화형 모드에서는 Codex가 어떤 파일을 읽고, 어떤 작업을 하려는지 따라가기 더 쉽습니다.

19첫 세션에서 써볼 만한 프롬프트 (1)

프로젝트 이해

다음 프롬프트는 첫 세션에서 바로 써볼 수 있습니다.

이 프로젝트의 전체 구조를 설명해줘.
주요 폴더와 파일이 어떤 역할을 하는지 정리해줘.

이 프로젝트를 로컬에서 실행하는 방법을 찾아서 단계별로 알려줘.

테스트 실행 방법과 주요 테스트 폴더를 알려줘.

코드 이해

로그인 기능이 어떤 파일들을 거쳐 동작하는지 추적해줘.

이 프로젝트에서 API 요청이 들어와서 응답이 나가기까지의 흐름을 설명해줘.

데이터베이스 연결 설정이 어디에 있는지 찾아줘.

20첫 세션에서 써볼 만한 프롬프트 (2)

안전한 수정

README에 설치 방법 섹션이 없다면 추가해줘.
기존 문체와 형식을 유지해줘.

/plan 회원가입 API에 입력값 검증을 추가하려고 해.
기존 validation 패턴을 먼저 찾고 작업 계획을 제안해줘.

이 함수에 대한 단위 테스트가 없다면 테스트 추가 계획을 먼저 제안해줘.

검증

방금 변경한 부분과 관련된 테스트를 실행해줘.

테스트 실패가 있다면 원인을 분석하고, 바로 수정하지 말고 수정 계획을 먼저 알려줘.

이번 변경사항이 기존 동작을 깨뜨릴 위험이 있는지 리뷰해줘.

21첫 세션에서 피해야 할 프롬프트

너무 넓거나 모호한 요청은 피하는 것이 좋습니다.

나쁜 예:

이 프로젝트 전체를 개선해줘.

코드 품질을 전부 좋게 만들어줘.

아키텍처를 알아서 최적화해줘.

전체 테스트를 고치고 배포까지 해줘.

이런 요청은 변경 범위가 지나치게 넓고, Codex가 의도와 다른 방향으로 움직일 가능성이 큽니다.

좋은 예:

/plan src/auth 폴더의 로그인 흐름을 분석하고,
중복 validation 로직을 줄이는 리팩터링 계획을 제안해줘.
아직 코드는 수정하지 마.

README의 로컬 실행 방법 섹션만 보완해줘.
기존 형식을 유지하고, 코드 변경은 하지 마.

22첫 세션에서 권장하는 안전 설정

첫 세션에서는 아래 조합을 추천합니다.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

workspace-write

현재 프로젝트 중심으로 읽기/쓰기 허용

on-request

위험하거나 범위를 넘는 작업은 사용자 승인 요청

더 조심스럽게 시작하고 싶다면 읽기 전용으로 실행할 수도 있습니다.

codex --sandbox read-only

읽기 전용 모드에서는 프로젝트 분석, 구조 설명, 코드 리뷰 같은 작업에 적합합니다. 실제 파일 수정을 하고 싶다면 workspace-write를 사용합니다.

codex --sandbox workspace-write --ask-for-approval on-request

23첫 세션 후 확인할 것

첫 세션이 끝난 뒤에는 아래를 확인합니다.

git status
git diff

확인할 내용:

의도한 파일만 수정되었는가?
불필요한 파일이 생성되지 않았는가?
lock file이 의도치 않게 바뀌지 않았는가?
테스트나 빌드 결과 파일이 커밋 대상에 들어가지 않았는가?
민감한 정보가 추가되지 않았는가?

필요 없는 변경사항은 되돌립니다.

git checkout -- path/to/file

새로 생긴 불필요한 파일은 삭제합니다.

rm path/to/file

24초보자용 첫 세션 체크리스트

프로젝트 이동

프로젝트 폴더로 이동했다.

상태 확인

git status로 현재 상태를 확인했다.

Codex 실행

codex를 실행했다.

구조 설명

프로젝트 구조 설명을 요청했다.

작은 작업

작은 작업 하나를 요청했다.

계획 먼저

복잡한 작업은 /plan으로 먼저 계획시켰다.

diff 확인

변경 후 /diff를 확인했다.

테스트/검증

관련 테스트 또는 검증 방법을 확인했다.

작업 요약

작업 요약을 요청했다.

종료

/quit 또는 /exit으로 종료했다.

최종 확인

터미널에서 git status와 git diff를 다시 확인했다.

섹션 05 · 마무리

이 단원에서 기억할 것

첫 세션의 목표는 Codex의 사용 흐름을 익히는 것입니다. 복잡한 기능을 처음부터 다 알 필요는 없습니다.

프로젝트 폴더 이동 → codex 실행 → 구조 설명 요청 → 작은 작업 요청 → /diff 확인 → 테스트 실행 → 종료

이 흐름을 반복하면서 다음을 기억하세요.

첫 작업은 코드 수정이 아니라 프로젝트 이해에 집중
복잡한 작업은 /plan으로 먼저 계획 확인
파일 수정 후에는 항상 /diff 확인
세션 종료 후에도 터미널에서 git status와 git diff 재확인

다음 단원

6단원. Codex 핵심 인터페이스

6. Codex 핵심 인터페이스

01인터페이스 한눈에 보기

Codex는 하나의 화면에서만 쓰는 도구가 아닙니다. 같은 Codex 에이전트를 CLI, Desktop App, IDE Extension, Cloud, Chrome Extension 같은 여러 인터페이스에서 사용할 수 있습니다.

CLI

터미널에서 Codex 실행

Desktop App

여러 작업을 시각적으로 관리

IDE Extension

에디터 안에서 바로 Codex 사용

Codex Cloud / Web

오래 걸리는 작업을 클라우드에 위임

Chrome Extension

로그인된 브라우저 상태가 필요한 웹 작업

02초보자를 위한 시작 가이드

초보자는 처음부터 모든 인터페이스를 사용할 필요는 없습니다. 가장 먼저 CLI 또는 IDE Extension으로 시작하고, 작업이 커지면 Desktop App이나 Cloud로 확장하면 됩니다.

처음에는 작은 작업을 안전하게 끝내는 흐름을 만드는 것이 가장 중요합니다.

03인터페이스 선택 기준

처음에는 아래 기준으로 선택하면 됩니다.

터미널에서 빠르게 작업하고 싶다
→ CLI

에디터 안에서 코드 보면서 수정하고 싶다
→ IDE Extension

여러 작업을 동시에 돌리고 diff를 시각적으로 보고 싶다
→ Desktop App

오래 걸리는 작업을 맡겨두고 싶다
→ Codex Cloud / Web

로그인된 웹사이트나 관리자 페이지에서 작업해야 한다
→ Chrome Extension

실무에서는 하나만 쓰기보다 상황에 따라 섞어 씁니다.

04실무 사용 예시

실제로는 다음처럼 사용할 수 있습니다.

1. CLI에서 코드베이스 분석
2. IDE Extension으로 현재 파일 수정
3. Desktop App에서 큰 리팩터링 병렬 진행
4. Cloud에 장기 작업 위임
5. Chrome Extension으로 로그인된 대시보드 확인

05CLI: 터미널 중심 인터페이스

CLI는 Codex의 가장 기본적인 사용 방식입니다. 프로젝트 폴더에서 다음 명령을 실행합니다.

codex

또는 시작 프롬프트를 바로 전달할 수 있습니다.

codex "이 프로젝트 구조를 설명해줘"

06CLI가 좋은 상황

CLI는 다음 상황에 좋습니다.

빠른 코드 분석

터미널에서 바로 실행 가능

작은 버그 수정

변경 범위를 빠르게 확인 가능

테스트 실행

shell 명령과 자연스럽게 연결

git diff 확인

터미널 워크플로와 잘 맞음

자동화

codex exec와 연결 가능

CI/CD

비대화형 실행에 적합

서버 환경

GUI 없이 사용 가능

07CLI 시작하는 방법

초보자는 CLI에서 다음 흐름부터 익히면 됩니다.

cd my-project
codex

Codex 안에서 입력합니다.

이 프로젝트의 구조와 실행 방법을 설명해줘.

작업이 복잡하면 먼저 계획을 세웁니다.

/plan 로그인 API에 입력값 검증을 추가하려고 해.
관련 파일을 찾고 작업 계획을 먼저 제안해줘.

변경 후에는 diff를 확인합니다.

/diff

08CLI 대화형 TUI

codex를 실행하면 터미널 안에 대화형 화면이 열립니다. 이 화면을 TUI, 즉 Terminal UI라고 부릅니다.

TUI에서는 다음 작업을 할 수 있습니다.

자연어 요청

Codex에게 작업 지시

파일 참조

@로 파일 첨부

shell 명령

!command 형태로 명령 실행

slash commands

/plan, /diff, /status 등 사용

진행 중 개입

작업 중 방향 수정

diff 확인

변경사항 검토

모델 변경

세션 중 모델 전환

09CLI TUI 예시

실제 사용 예시는 다음과 같습니다.

@src/auth/login.ts 이 파일의 로그인 흐름을 설명해줘.

!npm test

/status

10CLI에서 자주 쓰는 명령

초보자가 먼저 익힐 명령은 다음입니다.

/plan

실행 전 계획 세우기

/diff

변경사항 확인

/status

현재 세션 상태 확인

/model

모델 변경

/compact

긴 대화 요약

/review

코드 리뷰

/permissions

권한 확인 또는 조정

/resume

이전 세션 재개

/quit

종료

처음에는 아래 세 가지만 확실히 익혀도 충분합니다.

/plan
/diff
/status

11Desktop App: 작업 관리형 인터페이스

Desktop App은 Codex를 시각적으로 사용할 수 있는 앱입니다. CLI가 터미널 중심이라면, Desktop App은 여러 Codex 작업을 한곳에서 관리하는 작업 지휘실에 가깝습니다.

Desktop App의 핵심 장점:

Multi-tasking: 여러 Codex thread를 동시에 관리
Worktree isolation: 작업별로 격리된 Git worktree 사용
Inline diff review: 변경사항을 앱 안에서 검토
Integrated terminal: thread별 터미널 사용
Conversation forking: 대화를 복제해 다른 방향으로 실험
Automations: 반복 작업 자동화
Appshots: 화면 상태를 Codex에게 전달
In-app browser: 웹 앱 화면을 함께 보고 피드백
Computer Use: GUI 앱 조작이 필요한 작업 지원

12Desktop App이 좋은 상황

여러 작업을 동시에 진행

thread별로 분리 관리 가능

큰 리팩터링

작업 흐름을 시각적으로 추적 가능

diff를 편하게 보고 싶음

Git 변경사항 검토가 쉬움

Codex 작업을 병렬로 돌림

worktree isolation 활용 가능

팀원이 터미널에 익숙하지 않음

GUI 기반이라 접근성이 좋음

자동화 작업을 관리

앱 안에서 흐름 확인 가능

적합한 작업 예:

인증 모듈 리팩터링
오래된 API 마이그레이션
여러 GitHub issue 동시 처리
문서 정리와 테스트 보강을 병렬로 진행
PR 전 변경사항을 시각적으로 리뷰

13Desktop App을 CLI보다 먼저 써도 되는가?

가능합니다.

터미널이 익숙하지 않은 초보자라면 Desktop App이 더 편할 수 있습니다. 다만 개발 자동화나 CI/CD까지 생각하면 CLI도 결국 익혀두는 것이 좋습니다.

14IDE Extension: 에디터 안에서 사용하는 Codex

IDE Extension은 VS Code, Cursor, Windsurf 같은 에디터 안에서 Codex를 사용하는 방식입니다.

Codex IDE Extension은 이런 특징이 있습니다.

VS Code, Cursor, Windsurf 및 VS Code 호환 에디터에서 사용 가능
Codex CLI와 같은 에이전트 사용
같은 설정을 공유

15IDE Extension이 좋은 상황

현재 파일을 보면서 수정

에디터 문맥을 바로 활용

inline edit 필요

코드 위치 중심 작업에 적합

함수 단위 수정

작은 변경을 빠르게 반영

테스트 실패를 바로 고침

compile-test loop에 좋음

코드 리뷰 중 질문

선택한 코드 기준으로 설명 가능

초보자가 터미널보다 에디터가 편함

진입 장벽이 낮음

예시 요청:

이 함수의 예외 처리를 더 안전하게 바꿔줘.
현재 파일에서 중복된 로직을 찾아 정리해줘.
이 컴포넌트에 대한 테스트를 추가해줘.

16IDE Extension과 CLI의 차이

실행 위치

CLI

IDE Extension

실행 위치

터미널

코드 에디터

장점

빠름, 자동화에 강함

코드 보면서 작업하기 쉬움

파일 선택

@file, 검색 중심

현재 열린 파일과 선택 영역 중심

테스트 실행

shell 명령과 자연스럽게 연결

에디터 워크플로와 연결

17Codex Cloud / Codex Web: 클라우드 작업 인터페이스

Codex Cloud 또는 Codex Web은 로컬 컴퓨터가 아니라 클라우드 환경에서 Codex에게 작업을 맡기는 방식입니다.

Codex cloud의 특징:

자체 클라우드 환경에서 백그라운드 작업을 수행
병렬 작업도 가능

18Cloud가 좋은 상황

오래 걸리는 작업

로컬에서 계속 기다릴 필요가 적음

여러 이슈 처리

병렬로 맡기기 좋음

대규모 리팩터링

독립된 작업으로 분리 가능

PR 생성

작업 결과를 PR로 연결 가능

로컬 리소스 부담 줄이기

클라우드 환경에서 실행

백그라운드 작업

다른 일을 하면서 진행 가능

적합한 작업:

오래된 테스트 전체 정리
deprecated API 사용처 마이그레이션
여러 GitHub issue triage
문서 전체 업데이트
대규모 타입 오류 수정
반복적인 코드 스타일 정리

19Cloud 사용 시 주의할 점

Cloud는 강력하지만, 초보자가 처음부터 모든 작업을 Cloud에 맡길 필요는 없습니다.

Cloud에 적합한 작업은 다음 조건을 만족하는 경우입니다.

요구사항이 명확하다.
작업 범위가 독립적이다.
중간에 계속 사용자가 개입하지 않아도 된다.
결과를 diff나 PR로 검토할 수 있다.
실패해도 로컬 개발 흐름이 멈추지 않는다.

반대로 다음 작업은 처음에는 로컬 CLI나 IDE에서 하는 것이 좋습니다.

요구사항이 자주 바뀌는 작업
민감한 인증/결제 로직 수정
세밀한 UI 조정
사용자가 계속 방향을 잡아줘야 하는 작업
처음 보는 코드베이스 분석

20Chrome Extension: 브라우저 기반 인터페이스

Codex Chrome Extension은 Codex가 Chrome을 사용해 웹사이트를 읽거나 조작해야 할 때 사용하는 인터페이스입니다.

Codex Chrome Extension의 특징:

로그인된 브라우저 상태가 필요한 사이트에서 작업 가능
LinkedIn, Salesforce, Gmail, 내부 도구 같은 사이트 지원

21Chrome Extension이 좋은 상황

로그인된 사이트 확인

기존 브라우저 세션 사용

관리자 페이지 작업

웹 UI 조작 필요

SaaS 도구 확인

API가 없어도 화면 기반 작업 가능

내부 대시보드 점검

로그인 상태와 UI 맥락 필요

CMS 콘텐츠 확인

웹 페이지 기반 수정 흐름

버그 재현

실제 브라우저 화면 확인 가능

적합한 작업:

관리자 콘솔에서 설정 확인
내부 대시보드에서 오류 상태 확인
CMS 페이지에서 문구 검토
로그인된 웹 앱에서 버그 재현
Salesforce 같은 SaaS 화면에서 데이터 확인

22In-app Browser와 Chrome Extension의 차이

Codex에는 Desktop App의 in-app browser와 Chrome Extension이 모두 등장합니다.

위치

In-app Browser: Codex App 내부

Chrome Extension: 사용자의 Chrome

적합한 작업

In-app Browser: 로컬 개발 서버, 공개 페이지 preview

Chrome Extension: 로그인된 사이트, 내부 도구

로그인 상태

In-app Browser: 제한적

Chrome Extension: 사용자의 브라우저 상태 활용

초보자 기준

In-app Browser: 웹 UI 피드백용

Chrome Extension: 실제 웹 업무 자동화용

쉽게 말하면 다음과 같습니다.

내가 만든 웹 앱 화면을 Codex와 같이 보고 싶다
→ In-app Browser

로그인된 실제 사이트에서 Codex가 작업해야 한다
→ Chrome Extension

23Computer Use: GUI 작업이 필요할 때

Computer Use는 Codex가 그래픽 인터페이스를 보고 조작해야 할 때 사용하는 기능입니다.

Computer Use의 특징:

macOS 또는 Windows의 graphical user interface를 보고 조작 가능
명령줄 도구나 구조화된 통합만으로 부족한 작업에 적합

적합한 작업:

데스크톱 앱에서만 재현되는 버그 확인
브라우저 기반 수동 설정 작업
GUI 설정 변경
플러그인이나 API가 없는 데이터 소스 확인
화면을 보면서 UI 동작 점검

초보자는 Computer Use를 처음부터 사용할 필요는 없습니다. 먼저 CLI, IDE, Desktop App 사용법을 익힌 뒤, GUI 작업이 꼭 필요할 때 사용하는 것이 좋습니다.

24작업별 추천 인터페이스

프로젝트 구조 분석

CLI

현재 파일 수정

IDE Extension

작은 버그 수정

CLI 또는 IDE

큰 리팩터링

CLI /plan 또는 Desktop App

여러 작업 병렬 진행

Desktop App

장기 작업 위임

Codex Cloud

PR 생성 작업

Codex Cloud 또는 Desktop App

웹 앱 화면 리뷰

Desktop App In-app Browser

로그인된 사이트 작업

Chrome Extension

GUI 앱 조작

Computer Use

자동화 스크립트

CLI codex exec

CI/CD 연결

CLI codex exec

25초보자 추천 사용 순서

초보자는 아래 순서로 익히는 것이 좋습니다.

CLI에서 프로젝트 구조 설명시키기
CLI에서 /plan과 /diff 익히기
IDE Extension으로 현재 파일 수정해보기
Desktop App에서 변경사항 시각적으로 보기
Cloud에 작은 독립 작업 맡겨보기
필요할 때 Chrome Extension 사용하기

가장 중요한 것은 처음부터 모든 인터페이스를 쓰는 것이 아니라, 작은 작업을 안전하게 끝내는 흐름을 만드는 것입니다.

26CLI와 Desktop App 선택 기준

터미널에서 빠르게 끝낼 수 있는가?

CLI

여러 작업을 동시에 돌려야 하는가?

Desktop App

Git diff를 시각적으로 보고 싶은가?

Desktop App

자동화 스크립트로 돌릴 것인가?

CLI

CI/CD에 붙일 것인가?

CLI

팀원이 터미널에 익숙하지 않은가?

Desktop App

작업을 세밀하게 제어하고 싶은가?

CLI

정리하면 다음과 같습니다.

빠르고 직접적인 개발 작업
→ CLI

여러 작업을 관리하고 시각적으로 검토
→ Desktop App

27IDE와 CLI를 함께 쓰는 흐름

실무에서는 IDE와 CLI를 함께 쓰는 방식이 좋습니다.

흐름 예시:

CLI에서 전체 프로젝트 구조 분석
IDE에서 관련 파일 열기
IDE Extension으로 함수 단위 수정
CLI에서 테스트 실행
CLI 또는 Desktop App에서 diff 검토
Git으로 커밋

실제 명령 예시:

codex "이 프로젝트에서 로그인 기능이 어떤 파일을 거쳐 동작하는지 찾아줘"

IDE에서 관련 파일을 열고:

이 함수의 입력값 검증을 기존 스타일에 맞게 보강해줘.

다시 CLI에서:

npm test
git diff

이렇게 하면 전체 분석은 CLI, 세밀한 수정은 IDE, 검증은 다시 CLI로 나누어 처리할 수 있습니다.

28인터페이스별 안전 사용 팁

CLI

처음에는 workspace-write + on-request 조합 사용
복잡한 작업은 /plan 먼저 사용
변경 후 /diff 확인

Desktop App

thread별 작업 범위를 명확히 나누기
병렬 작업 결과를 한꺼번에 merge하지 않기
worktree별 변경사항 확인하기

IDE Extension

현재 파일만 바꾸는 작업부터 시작
선택 영역 기준 요청을 활용
변경 후 에디터 diff 확인

Codex Cloud

요구사항을 명확히 적기
독립적인 작업만 맡기기
결과 PR 또는 diff를 반드시 리뷰하기

Chrome Extension

허용할 사이트를 신중하게 선택
민감한 페이지 작업은 직접 확인
로그인된 브라우저 상태를 사용하는 점을 인지

29초보자가 피해야 할 인터페이스 사용 실수

처음부터 Cloud에 큰 작업을 맡김

결과 검토가 어려울 수 있음

CLI에서 /diff 확인 없이 커밋

의도치 않은 변경을 놓칠 수 있음

Desktop App에서 병렬 작업을 너무 많이 실행

merge 충돌과 검토 부담 증가

IDE에서 현재 파일만 보고 전체 구조를 무시

영향 범위를 놓칠 수 있음

Chrome Extension에 너무 많은 사이트 권한 부여

보안 위험 증가

Computer Use를 불필요하게 사용

GUI 조작은 예측 가능성이 낮을 수 있음

초보자는 "작게 요청하고, diff를 확인하고, 테스트한다"는 원칙을 모든 인터페이스에서 동일하게 적용하면 됩니다.

30인터페이스 선택 요약

CLI
가장 기본. 터미널에서 빠르게 분석, 수정, 테스트.

Desktop App
여러 작업 관리, worktree, 시각적 diff, 자동화.

IDE Extension
현재 파일과 선택 영역 중심의 빠른 편집.

Codex Cloud / Web
오래 걸리는 독립 작업을 백그라운드에 위임.

Chrome Extension
로그인된 웹사이트나 내부 도구에서 브라우저 작업.

Computer Use
GUI 앱을 직접 보고 조작해야 하는 작업.

섹션 06 · 마무리

이 단원에서 기억할 것

Codex는 CLI, Desktop App, IDE Extension, Cloud, Chrome Extension 등 여러 인터페이스에서 사용할 수 있다.

CLI는 가장 기본적이고 자동화에 강하다.
Desktop App은 여러 작업을 병렬로 관리하고 diff를 시각적으로 검토할 때 좋다.
IDE Extension은 에디터 안에서 현재 파일을 바로 수정할 때 좋다.
Codex Cloud는 오래 걸리는 독립 작업을 백그라운드로 맡길 때 좋다.
Chrome Extension은 로그인된 웹사이트나 내부 도구 작업에 적합하다.
In-app Browser는 웹 앱 화면 preview와 visual feedback에 좋고, 로그인 상태가 필요한 작업은 Chrome Extension이 더 적합하다.
초보자는 CLI 또는 IDE Extension으로 시작하고, 필요해지면 Desktop App과 Cloud로 확장하면 된다.

다음 단원

7단원. CLI 기본 사용법

7. CLI 기본 사용법

01CLI 기본 실행

가장 기본적인 실행 명령은 다음입니다.

codex

프로젝트 폴더에서 실행합니다.

cd ~/my-project
codex

그러면 터미널 안에 Codex 대화형 화면이 열립니다. 이 화면에서 자연어로 Codex에게 작업을 요청할 수 있습니다.

예시:

이 프로젝트 구조를 설명해줘.
로그인 기능이 어떤 파일들을 거쳐 동작하는지 분석해줘.
실패한 테스트의 원인을 찾아줘.

02한 줄 프롬프트로 실행하기

대화형 화면을 열면서 동시에 첫 요청을 전달할 수도 있습니다.

codex "이 프로젝트 구조를 설명해줘"

또는:

codex "실패한 테스트의 원인을 분석해줘"

이 방식은 빠른 질문이나 단발성 작업에 좋습니다.

codex "package.json을 읽고 이 프로젝트의 실행 명령과 테스트 명령을 알려줘"

단, 초보자는 처음에는 그냥 codex로 대화형 화면을 열고 진행하는 것을 추천합니다. 대화형 화면에서는 Codex가 어떤 작업을 하려는지 더 쉽게 따라갈 수 있습니다.

03프로젝트 폴더에서 실행해야 하는 이유

Codex는 현재 터미널 위치를 기준으로 프로젝트를 이해합니다.

좋은 예:

cd ~/projects/my-app
codex

나쁜 예:

cd ~
codex

프로젝트 밖에서 실행하면 Codex가 관련 파일을 찾기 어렵습니다. 실행 전에는 현재 위치를 확인합니다.

pwd

Git 프로젝트인지 확인합니다.

git status

초보자는 Codex 실행 전 git status를 확인하는 습관을 들이는 것이 좋습니다.

04모델 지정하기

Codex 실행 시 사용할 모델을 지정할 수 있습니다.

codex -m gpt-5.5

또는 프롬프트와 함께 지정합니다.

codex -m gpt-5.5 "이 프로젝트의 인증 구조를 분석해줘"

-m은 --model의 짧은 형태입니다.

codex --model gpt-5.5 "이 코드 리뷰해줘"

모델 선택은 작업의 난이도와 비용에 영향을 줍니다.

간단한 질문

빠른 모델

일반 코드 수정

기본 모델

복잡한 디버깅

강한 추론 모델

보안 리뷰

높은 reasoning effort

대규모 리팩터링

강한 모델 + /plan

초보자는 처음에는 기본 모델을 그대로 사용해도 됩니다.

05reasoning effort 지정하기

Codex는 모델이 얼마나 깊게 추론할지 설정할 수 있습니다.

codex -c model_reasoning_effort="medium"

복잡한 문제라면 높일 수 있습니다.

codex -c model_reasoning_effort="high" "이 race condition 원인을 찾아줘"

보안 감사나 복잡한 아키텍처 분석에는 다음처럼 사용할 수 있습니다.

codex -c model_reasoning_effort="xhigh" "이 인증 모듈의 보안 취약점을 리뷰해줘"

다만 높은 reasoning effort는 더 많은 토큰과 비용을 사용할 수 있습니다. 초보자 기본값은 다음이 적당합니다.

model_reasoning_effort = "medium"

06sandbox 모드 지정하기

Codex는 실제 파일을 읽고 수정할 수 있으므로 sandbox 설정이 중요합니다.

codex --sandbox workspace-write

읽기 전용으로 실행할 수도 있습니다.

codex --sandbox read-only

전체 접근 권한을 주는 방식도 있습니다.

codex --sandbox danger-full-access

하지만 초보자는 danger-full-access를 사용하지 않는 것이 좋습니다.

read-only

읽기만 가능 (분석, 리뷰용)

workspace-write

작업 공간 중심으로 읽기/쓰기 가능 (기본 추천)

danger-full-access

시스템 전체 접근 가능 (비추천)

07approval policy 지정하기

approval policy는 Codex가 언제 사용자 승인을 요청할지 정합니다.

codex --ask-for-approval on-request

sandbox와 함께 사용하면 다음과 같습니다.

codex --sandbox workspace-write --ask-for-approval on-request

untrusted

읽기 외 작업 대부분에 승인 요청

on-request

일반 작업은 진행, 위험한 작업은 승인 요청

never

승인 요청 없이 진행

초보자 추천 조합은 실무 작업을 할 수 있으면서도, 위험한 작업은 멈추고 사용자에게 확인을 요청합니다.

08안전하게 분석만 하고 싶을 때

처음 보는 프로젝트라면 읽기 전용으로 시작하는 것도 좋습니다.

codex --sandbox read-only

이 상태에서는 다음과 같은 작업을 요청하기 좋습니다.

이 프로젝트 구조를 설명해줘.
로그인 기능이 어떤 파일을 거쳐 동작하는지 분석해줘.
테스트 실행 방법을 찾아줘.
보안상 위험해 보이는 부분을 코드 수정 없이 리뷰해줘.

읽기 전용 모드는 Codex가 파일을 수정하지 못하므로 초보자에게 안전합니다.

09파일 첨부하기: @

TUI 안에서 @를 사용하면 파일을 찾아 Codex 대화에 첨부할 수 있습니다.

@src/auth/login.ts 이 파일의 로그인 흐름을 설명해줘.

또는:

@package.json 이 프로젝트의 scripts를 설명해줘.

파일을 명확히 지정하면 Codex가 더 정확하게 답할 수 있습니다.

좋은 예:

@src/api/users.ts 이 파일에서 입력값 검증이 부족한 부분을 찾아줘.

나쁜 예:

전체 프로젝트에서 문제 찾아줘.

작업 범위를 줄일수록 Codex의 결과가 좋아집니다.

10shell 명령 실행하기: !

TUI 안에서 !를 붙이면 shell 명령을 실행할 수 있습니다.

!npm test
!git status
!pnpm lint
!pytest

이 기능은 Codex 대화 중간에 직접 명령을 실행하고 결과를 확인할 때 유용합니다.

!git diff
!npm run test:unit

단, 명령 실행은 sandbox와 approval 설정의 영향을 받습니다. 위험한 명령은 승인 요청이 뜰 수 있습니다.

11외부 에디터 열기

TUI 안에서 긴 프롬프트를 작성해야 할 때는 외부 에디터를 열 수 있습니다. Ctrl+G는 $VISUAL 또는 $EDITOR에 설정된 외부 에디터를 여는 단축키입니다.

사용 흐름:

Codex TUI에서 Ctrl+G 입력
외부 에디터 열림
긴 지시문 작성
저장 후 닫기
Codex 입력창에 반영

긴 작업 지시를 작성할 때 유용합니다.

12이전 입력 기록 탐색

Codex TUI에서는 이전에 입력한 프롬프트를 다시 불러올 수 있습니다. 보통 화살표 키로 draft 기록을 탐색합니다.

↑ 이전 입력
↓ 다음 입력

Ctrl+R은 이전 프롬프트와 slash command 기록을 검색하는 데 사용됩니다.

Ctrl+R

이후 이전에 입력했던 /plan, /diff, 작업 요청 등을 찾아 재사용할 수 있습니다.

13실행 중 Codex에게 추가 지시하기

Codex가 작업 중일 때도 사용자가 방향을 수정할 수 있습니다. 예를 들어 Codex가 잘못된 파일을 보고 있다면:

그 파일이 아니라 src/auth/login.ts를 중심으로 봐줘.

작업 범위를 줄이고 싶다면:

이번에는 코드 수정하지 말고 분석만 해줘.

테스트 범위를 바꾸고 싶다면:

전체 테스트 대신 로그인 관련 테스트만 먼저 실행해줘.

중요한 점은 작업을 맡긴 뒤 끝까지 방치하는 것이 아니라 중간에 방향을 계속 조정할 수 있다는 것입니다.

14이전 메시지 수정하기

Esc를 두 번 누르면 이전 메시지를 편집할 수 있습니다.

사용 상황:

방금 입력한 지시가 너무 모호했을 때
파일명을 잘못 썼을 때
"수정해줘"가 아니라 "계획만 세워줘"라고 바꾸고 싶을 때
테스트 범위를 추가하고 싶을 때

예시:

처음 입력: 로그인 기능 고쳐줘.

수정 후: /plan 로그인 기능의 입력값 검증 흐름을 분석하고, 수정이 필요한 부분과 테스트 계획을 먼저 제안해줘. 아직 코드는 수정하지 마.

초보자는 모호한 요청을 했다고 느껴지면 바로 수정하는 것이 좋습니다.

15새 대화 시작하기

같은 Codex 세션 안에서 새 대화를 시작하려면 /new를 사용합니다.

/new

사용 상황:

이전 작업과 완전히 다른 작업을 시작할 때
컨텍스트가 너무 복잡해졌을 때
실험적으로 다른 방향의 요청을 해보고 싶을 때

이후 새 요청: 이 프로젝트의 배포 구조를 설명해줘.

16이전 세션 재개하기

저장된 대화를 다시 열고 싶다면 /resume을 사용합니다.

/resume

또는 CLI 실행 시 resume 관련 옵션을 사용할 수 있습니다.

유용한 상황:

어제 하던 작업을 이어서 진행
중간에 종료한 디버깅 세션 재개
이전 분석 내용을 바탕으로 후속 작업 진행

단, 오래된 세션을 이어갈 때는 현재 코드 상태가 바뀌었을 수 있으므로 먼저 확인해야 합니다.

현재 git 상태와 이전 세션 이후 변경된 파일을 확인해줘.

17대화 fork 하기

현재 대화를 다른 방향으로 이어가고 싶다면 /fork를 사용할 수 있습니다.

/fork

사용 예시:

현재 리팩터링 방향 A를 유지한 버전과, 더 보수적인 방향 B를 따로 비교하고 싶을 때

fork는 기존 대화 맥락을 복사해서 새로운 thread로 이어가는 방식입니다. 초보자는 처음부터 자주 쓸 필요는 없지만, 대안을 비교할 때 유용합니다.

18모델 변경하기: /model

세션 중간에도 모델을 바꿀 수 있습니다.

/model

사용 상황:

간단한 작업에서 빠른 모델로 변경
어려운 버그에서 강한 모델로 변경
비용을 줄이고 싶을 때
보안 리뷰처럼 깊은 추론이 필요할 때

CLI 실행 시 모델을 지정할 수도 있습니다.

codex -m gpt-5.5

세션 중에는 /model을 사용하면 됩니다.

19긴 대화 요약하기: /compact

대화가 길어지면 컨텍스트가 가득 찰 수 있습니다. 이때 /compact를 사용합니다.

/compact

/compact는 긴 대화 내용을 요약해 컨텍스트 공간을 확보하는 데 사용합니다.

사용 상황:

긴 디버깅을 오래 진행했을 때
여러 파일을 많이 읽었을 때
같은 세션에서 계속 후속 작업을 하고 싶을 때
Codex 응답이 맥락을 놓치는 것처럼 느껴질 때

초보자는 긴 작업 중간에 /compact를 사용한 뒤 지금까지의 작업 요약을 바탕으로 다음 단계만 진행해줘.라고 요청해도 좋습니다.

20변경사항 확인하기: /diff

Codex가 파일을 수정했다면 반드시 /diff로 확인합니다.

/diff

확인할 항목:

의도한 파일만 바뀌었는가?
변경 범위가 너무 넓지 않은가?
테스트가 추가되었는가?
기존 API 응답이 깨지지 않는가?
민감한 정보가 추가되지 않았는가?
불필요한 lock file 변경이 있는가?

초보자 원칙: Codex가 수정했다면 반드시 /diff를 본다.

21코드 리뷰 요청하기: /review

현재 working tree를 리뷰하고 싶다면 /review를 사용할 수 있습니다.

/review

사용 상황:

Codex가 만든 변경사항 검토
내가 직접 수정한 코드 검토
PR 올리기 전 점검
보안, 성능, 테스트 누락 확인

더 구체적인 예시:

/review 이번 변경에서 보안 문제, 테스트 누락, API 호환성 문제를 중심으로 봐줘.

22현재 상태 확인하기: /status

현재 세션 상태를 확인하려면 /status를 사용합니다.

/status

확인할 수 있는 항목은 버전과 환경에 따라 다르지만, 일반적으로 다음과 관련됩니다.

사용 중인 모델
token / context 사용량
현재 sandbox mode
approval policy
git branch
세션 설정

문제가 생기면 /status부터 확인하는 습관이 좋습니다.

23권한 확인하기: /permissions

Codex의 권한 상태를 확인하거나 조정하려면 /permissions를 사용합니다.

/permissions

사용 상황:

Codex가 파일을 수정하지 못할 때
명령 실행이 막힐 때
네트워크 접근이 필요한 작업을 할 때
sandbox / approval 상태를 확인하고 싶을 때

초보자는 권한을 무작정 높이기보다, 먼저 현재 상태를 확인해야 합니다. 위험한 권한을 요청받으면 변경 이유를 확인한 뒤 승인 여부를 결정합니다.

24앱과 MCP 확인하기

Codex에 연결된 외부 도구를 확인하려면 다음 명령을 사용할 수 있습니다.

/mcp
/apps

/mcp는 설정된 MCP tools를 확인할 때 사용합니다. /apps는 ChatGPT connectors 관련 앱을 탐색할 때 사용합니다.

초보자는 처음에는 MCP나 Apps를 몰라도 됩니다. 기본 CLI 사용에 익숙해진 뒤 외부 도구 연결이 필요할 때 배우면 됩니다.

25Skills 확인하기

사용 가능한 skills를 확인하거나 호출하려면 /skills를 사용합니다.

/skills

Skills는 반복 작업을 표준화할 때 유용합니다. 예를 들어:

PR 리뷰
테스트 작성
보안 점검
문서 작성
릴리즈 노트 작성

처음에는 직접 프롬프트로 요청하고, 반복되는 작업이 생기면 skill로 관리하는 흐름이 좋습니다.

26plugins 확인하기

설치된 plugins를 확인하거나 관리하려면 /plugins를 사용합니다.

/plugins

Plugins는 Codex 기능을 확장하는 시스템입니다. 초보자는 기본 기능을 먼저 익힌 뒤, 팀이나 프로젝트에서 필요한 plugin만 사용하는 것이 좋습니다.

27직접 shell 명령과 Codex 요청의 차이

TUI 안에서는 사용자가 직접 shell 명령을 실행할 수도 있고, Codex에게 실행을 요청할 수도 있습니다.

직접 실행:

!npm test

Codex에게 요청:

관련 테스트를 찾아 실행하고 결과를 요약해줘.

!npm test

사용자가 명령을 직접 지정

자연어 요청

Codex가 적절한 명령을 찾고 실행

초보자는 처음에는 Codex에게 명령을 찾게 하는 것이 편합니다.

28CLI 옵션과 config의 관계

Codex는 config.toml 설정을 읽지만, 실행 시 CLI 옵션으로 값을 덮어쓸 수 있습니다.

예를 들어 config에 기본 모델이 있어도:

model = "gpt-5.5"

실행 시 다른 모델을 지정하면 해당 실행에서는 CLI 옵션이 우선합니다.

codex -m gpt-5.4 "이 코드 리뷰해줘"

inline config override도 가능합니다.

codex -c model_reasoning_effort="high" "이 버그 원인을 분석해줘"

중첩 설정도 지정할 수 있습니다.

codex -c 'sandbox_workspace_write.network_access=true' "의존성을 설치해줘"

초보자는 이렇게 기억하면 됩니다: 실행할 때 직접 준 옵션이 config보다 우선한다.

29profile로 실행하기

작업 유형별 설정 묶음인 profile을 사용할 수 있습니다.

codex --profile fast "이 함수 설명해줘"
codex --profile careful "이 인증 로직 보안 리뷰해줘"
codex --profile ci "실패한 테스트 원인을 분석해줘"

Profile은 나중에 설정 장에서 자세히 다루지만, 기본 개념은 다음입니다.

fast

빠른 질문, 간단한 수정

careful

보안, 아키텍처, 복잡한 디버깅

ci

자동화, CI/CD

pair

실시간 페어링

30읽기 전용 코드 리뷰 실행 예시

처음 보는 프로젝트에서 안전하게 분석만 하고 싶다면 다음처럼 실행합니다.

codex --sandbox read-only

Codex 안에서:

이 프로젝트의 인증 흐름을 분석해줘.
코드는 수정하지 말고, 위험해 보이는 부분만 정리해줘.

또는 한 줄로:

codex --sandbox read-only "이 프로젝트의 인증 흐름을 분석하고 보안상 위험 요소를 정리해줘. 코드는 수정하지 마."

31일반 개발 작업 실행 예시

일상적인 개발 작업에는 다음 조합이 좋습니다.

codex --sandbox workspace-write --ask-for-approval on-request

Codex 안에서:

/plan 회원가입 API에 비밀번호 길이 검증을 추가하려고 해.
기존 validation 패턴과 테스트 위치를 확인하고 계획을 먼저 제안해줘.

계획 확인 후: 계획대로 진행해줘.

변경 후: /diff

테스트: 관련 테스트를 실행하고 결과를 요약해줘.

32빠른 질문 실행 예시

간단한 질문은 한 줄로 처리할 수 있습니다.

codex "package.json의 scripts를 설명해줘"
codex "이 프로젝트에서 dev server를 실행하는 명령을 찾아줘"
codex "src/auth 폴더의 역할을 요약해줘"

이 방식은 빠르지만, 긴 작업에는 대화형 TUI가 더 적합합니다.

33CLI에서 안전하게 작업하는 기본 루틴

초보자는 아래 루틴을 반복하면 됩니다.

git status 확인
codex 실행
프로젝트 또는 작업 범위 설명 요청
복잡하면 /plan 사용
변경 승인
/diff 확인
테스트 실행
작업 요약 요청
/quit
터미널에서 git status, git diff 재확인

실제 명령 흐름:

git status
codex

Codex 안에서: /plan 로그인 API에 이메일 검증을 추가하려고 해. 기존 코드 스타일과 테스트 위치를 먼저 확인해줘.

변경 후: /diff

종료 후: git status, git diff

34CLI 초보자가 자주 하는 실수

프로젝트 밖에서 codex 실행

관련 파일을 제대로 찾기 어려움

처음부터 큰 작업 요청

변경 범위가 커져 검토 어려움

/plan 없이 리팩터링 요청

잘못된 방향으로 수정될 수 있음

/diff 확인 없이 커밋

의도치 않은 변경을 놓칠 수 있음

danger-full-access 남용

시스템 전체에 위험 가능

테스트 실행 생략

변경 오류를 놓칠 수 있음

모호한 프롬프트 사용

결과가 기대와 달라질 수 있음

35좋은 CLI 프롬프트 예시 ①

프로젝트 분석

이 프로젝트의 구조를 초보자도 이해할 수 있게 설명해줘.
주요 폴더, 실행 방법, 테스트 방법, 핵심 진입점을 정리해줘.

기능 흐름 분석

로그인 요청이 들어와서 응답이 나가기까지 어떤 파일들을 거치는지 추적해줘.
코드는 수정하지 말고 설명만 해줘.

36좋은 CLI 프롬프트 예시 ②

안전한 리팩터링 계획

/plan src/auth 폴더의 중복 validation 로직을 줄이려고 해.
기존 구조, 영향 범위, 테스트 계획을 먼저 정리해줘.
아직 파일은 수정하지 마.

작은 수정

README에 로컬 실행 방법 섹션이 없다면 추가해줘.
기존 문체와 형식을 유지해줘.

테스트 실행

방금 변경한 부분과 관련된 테스트 명령을 찾아 실행하고,
실패하면 원인을 먼저 분석해줘.

37나쁜 CLI 프롬프트 예시

아래처럼 범위가 넓고 모호한 요청은 피하는 것이 좋습니다.

코드 전부 고쳐줘.
이 프로젝트를 좋게 만들어줘.
전체 리팩터링 해줘.
알아서 최적화해줘.

더 좋은 방식:

/plan src/api 폴더에서 중복된 에러 처리 로직을 줄이는 방법을 제안해줘.
영향 범위와 테스트 계획을 먼저 설명하고, 아직 코드는 수정하지 마.

38CLI 기본 명령 요약

codex

대화형 CLI 실행

codex "프롬프트"

시작 프롬프트와 함께 실행

codex -m 모델명

모델 지정

codex --sandbox read-only

읽기 전용 실행

codex --sandbox workspace-write

작업 공간 쓰기 허용

codex --ask-for-approval on-request

필요 시 승인 요청

codex --profile fast

profile 지정

codex -c key=value

config 값 일시 override

39TUI 기본 조작 요약

@

파일 검색 및 첨부

!command

shell 명령 직접 실행

Ctrl+G

외부 에디터 열기

Ctrl+R

이전 입력 검색

Esc 두 번

이전 메시지 편집

/plan

계획 모드

/diff

변경사항 확인

/status

현재 상태 확인

/quit

종료

섹션 07 · 마무리

이 단원에서 기억할 것

CLI는 Codex의 가장 기본적이고 강력한 사용 방식입니다. 프로젝트 폴더에서 codex를 실행하면 대화형 TUI가 열리고, 터미널과 프로젝트 파일을 함께 다룰 수 있습니다.

초보자가 꼭 기억해야 할 3가지:

프로젝트 폴더에서 실행 → 복잡하면 /plan으로 시작 → 수정 후 /diff로 확인

모든 고급 기능(profile, MCP, plugin)은 나중에 배워도 괜찮습니다. 먼저 기본 흐름에 익숙해지는 것이 가장 중요합니다.

다음 단원

8단원. Slash Commands 완전 정리

8. Slash Commands 완전 정리

01Slash Command란?

Slash Command는 Codex 대화형 CLI 안에서 /로 시작하는 명령어입니다.

/plan
/diff
/status

일반 프롬프트가 "Codex에게 자연어로 요청하는 방식"이라면, Slash Command는 세션 제어, 모델 변경, 권한 확인, diff 확인, 작업 계획, 리뷰, 설정 확인 같은 기능을 빠르게 실행하는 명령어입니다.

02주요 Slash Command 목록

Slash Command는 일반적으로 다음 작업에 사용합니다.

작업 계획

/plan

변경사항 확인

/diff

세션 상태 확인

/status

모델 변경

/model

대화 요약

/compact

권한 확인

/permissions

코드 리뷰

/review

세션 종료

/quit

초보자는 처음에 /plan, /diff, /status, /permissions, /quit 5개만 익혀도 충분합니다.

03Slash Command 기본 사용법

Codex TUI 안에서 /를 입력하면 사용할 수 있는 명령어 목록이 표시됩니다.

단독 실행 예시

/diff

설명 포함 실행 예시

/plan 결제 모듈의 에러 처리 구조를 개선하려고 해.
영향 범위와 단계별 계획을 먼저 제안해줘.

명령어에 따라 단독으로 실행하는 것도 있고, 뒤에 설명을 붙여 실행하는 것도 있습니다.

04Slash Command 전체 목록 (1/2)

/quit, /exit

Codex 종료 (높음)

/new

새 대화 시작 (중간)

/resume

이전 대화 재개 (중간)

/fork

현재 대화를 새 thread로 분기 (중간)

/model

모델 변경 (높음)

/compact

긴 대화 요약 (높음)

/diff

변경사항 확인 (매우 높음)

05Slash Command 전체 목록 (2/2)

/review

코드 리뷰 (높음)

/plan

실행 전 계획 수립 (매우 높음)

/goal

지속 작업 목표 관리 (중간)

/vim

Vim 편집 모드 전환 (낮음)

/hooks

hooks 탐색 및 전환 (중간)

/mention

파일 첨부 (중간)

/init

AGENTS.md scaffold 생성 (높음)

06Slash Command 전체 목록 (3/3)

/status

세션 상태 확인 (매우 높음)

/permissions

권한 확인 및 조정 (매우 높음)

/personality

응답 스타일 조정 (낮음)

/mcp

MCP tools 확인 (중간)

/apps

ChatGPT connectors 탐색 (낮음)

/ps

background terminals 확인 (중간)

/skills

skills 확인 및 호출 (중간)

07나머지 Slash Commands

/plugins

plugins 관리 (중간)

/title

terminal window title 설정 (낮음)

/config

현재 config 확인 (높음)

/statusline

TUI footer 설정 (낮음)

/feedback

로그와 피드백 전송 (낮음)

/logout

로그아웃 (중간)

08/quit 또는 /exit

Codex CLI를 종료합니다.

/quit
또는
/exit

둘 다 세션을 종료하는 명령입니다.

사용 상황

작업을 마쳤을 때
터미널로 돌아가고 싶을 때
세션을 종료하고 git 상태를 직접 확인하고 싶을 때

종료 후에는 터미널에서 변경사항을 다시 확인하는 것이 좋습니다.

git status
git diff

09/new

현재 Codex 세션 안에서 새 대화를 시작합니다.

/new

사용 상황

완전히 다른 작업을 시작할 때

이전 맥락이 방해되지 않게 함

대화가 너무 길어졌을 때

새로운 흐름으로 정리

실험적 질문을 하고 싶을 때

기존 작업 흐름과 분리

주의: /new는 Git 변경사항을 되돌리는 명령이 아닙니다. 파일 변경사항은 그대로 남아 있으므로, 필요하면 /diff나 git diff로 확인해야 합니다.

10/resume

이전에 저장된 대화를 다시 엽니다.

/resume

사용 상황

어제 하던 작업을 이어서 할 때
중간에 종료한 디버깅을 다시 열 때
이전 분석 내용을 기반으로 후속 작업을 할 때

재개 후에는 현재 코드 상태가 이전과 달라졌는지 확인하는 것이 좋습니다.

현재 git 상태를 확인하고, 이전 세션 이후 바뀐 파일이 있는지 알려줘.

11/fork

현재 대화를 새 thread로 분기합니다.

/fork

/fork는 지금까지의 대화 맥락을 유지하면서, 다른 방향의 작업 흐름을 실험하고 싶을 때 사용합니다.

사용 예시

리팩터링 방법 A와 B를 비교하고 싶을 때
현재 계획은 유지하되 다른 접근도 검토하고 싶을 때
기존 대화 흐름을 보존하면서 새로운 실험을 하고 싶을 때

초보자는 처음부터 자주 쓸 필요는 없지만, 대안을 비교할 때 유용합니다.

12/model

현재 세션에서 사용할 모델을 변경합니다.

/model

사용 상황

간단한 질문

빠른 모델로 전환

복잡한 버그 분석

강한 모델로 전환

보안 리뷰

높은 추론 모델 사용

비용 절감

저렴한 모델 사용

초보자는 처음에는 기본 모델을 그대로 사용해도 됩니다.

13/compact

긴 대화 내용을 요약해서 컨텍스트 공간을 확보합니다.

/compact

Codex는 대화 내용, 읽은 파일, 명령 출력, 작업 계획 등을 컨텍스트로 사용합니다. 대화가 길어지면 컨텍스트가 가득 차고, Codex가 이전 내용을 놓칠 수 있습니다.

사용 상황

긴 디버깅을 오래 진행했을 때
많은 파일을 읽었을 때
같은 세션에서 계속 후속 작업을 해야 할 때

14/diff

현재 세션에서 만들어진 변경사항을 확인합니다.

/diff

초보자에게 가장 중요한 명령어 중 하나입니다. Codex가 파일을 수정했다면 반드시 /diff를 실행해야 합니다.

확인할 항목

변경 파일

의도한 파일만 바뀌었는가?

변경 범위

너무 많은 코드가 바뀌지 않았는가?

로직

기존 동작을 깨지 않는가?

테스트

테스트가 추가되거나 수정되었는가?

15/diff 후속 활용

변경사항을 본 뒤 Codex에게 다시 요청할 수 있습니다.

diff를 기준으로 불필요한 변경이 있는지 리뷰해줘.
방금 변경 중 README 수정만 남기고 코드 변경은 되돌려줘.

자주 하는 후속 요청

이 변경사항을 커밋 메시지 형태로 요약해줘
이 diff 기준으로 PR 설명을 작성해줘
이 변경사항이 기존 동작을 깨뜨릴 위험이 있는지 검토해줘

16/review

현재 working tree 또는 변경사항을 리뷰합니다.

/review

사용 상황

PR 올리기 전 점검
Codex가 만든 변경사항 검토
내가 직접 수정한 코드 검토
보안 문제 확인

더 구체적으로 요청할 수도 있습니다.

/review 이번 변경사항에서 보안 문제, 테스트 누락, 기존 API 호환성 문제를 중심으로 봐줘.

17/plan

파일을 바로 수정하기 전에 작업 계획을 세웁니다.

/plan 로그인 API에 입력값 검증을 추가하려고 해.
관련 파일을 찾고, 기존 validation 방식과 테스트 위치를 확인한 뒤
단계별 작업 계획을 먼저 제안해줘.

/plan은 초보자에게 가장 중요한 명령어입니다. 복잡한 작업은 바로 실행시키지 말고 먼저 계획을 확인해야 합니다.

18/plan 사용 기준

언제 /plan을 써야 하는가?

여러 파일이 바뀔 가능성

변경 범위를 먼저 파악

처음 보는 코드베이스

구조를 먼저 이해

인증/결제/권한 관련 작업

위험도가 높음

대규모 리팩터링

영향 범위가 큼

초보자 기준

3개 이상의 파일이 바뀔 것 같으면 /plan 먼저 사용한다.

19/goal

지속되는 작업 목표를 만들거나 관리합니다.

/goal

/goal은 유지되는 작업 목표를 생성, 일시 중지, 재개, 삭제하는 데 사용됩니다.

사용 상황

긴 리팩터링을 여러 단계로 진행할 때
작업 목표를 세션 전반에 유지하고 싶을 때
여러 턴에 걸쳐 진행 상황을 추적하고 싶을 때

초보자는 처음에는 /plan을 먼저 익히고, 장기 작업이 필요할 때 /goal을 사용하면 됩니다.

20/vim, /hooks, /mention

/vim

TUI composer에서 Vim 편집 모드를 전환합니다.

/vim

Vim 키 조작에 익숙한 사용자를 위한 기능입니다.

/hooks

Codex lifecycle hooks를 탐색하거나 전환합니다. 특정 이벤트 전후에 실행되는 자동 동작을 관리합니다.

/mention

대화에 파일을 첨부합니다.

@src/auth/login.ts 이 파일의 로그인 흐름을 설명해줘.

21/init

프로젝트에 AGENTS.md scaffold를 생성합니다.

/init

AGENTS.md는 Codex가 프로젝트에서 따라야 할 규칙을 적는 파일입니다.

포함할 수 있는 내용

# AGENTS.md

## Development Rules

- Run tests after code changes.
- Keep existing public API behavior.
- Follow the existing code style.
- Add tests for new behavior.

/init은 처음 프로젝트에서 Codex를 사용할 때 매우 유용합니다.

22/status

현재 세션 상태를 확인합니다.

/status

확인할 수 있는 항목

현재 모델
reasoning effort
sandbox mode
approval policy
git branch
token/context 사용량
remote 연결 상태

문제가 생기면 가장 먼저 확인할 명령 중 하나입니다.

23/permissions

현재 권한과 approval 설정을 확인하거나 조정합니다.

/permissions

사용 상황

Codex가 파일을 수정하지 못할 때
명령 실행이 막힐 때
네트워크 접근이 필요한 작업을 할 때
위험한 작업 전에 현재 권한을 확인할 때

초보자는 Codex가 작업을 못 한다고 해서 바로 권한을 높이지 말고 먼저 /permissions로 상태를 확인해야 합니다.

danger-full-access는 초보자 기본값으로 쓰지 않는다.

24/personality, /mcp, /apps

/personality

Codex의 커뮤니케이션 스타일을 조정합니다. friendly, pragmatic, none 같은 스타일을 선택할 수 있습니다.

/mcp

설정된 MCP tools를 확인합니다. GitHub, Figma, Sentry, 데이터베이스 등 외부 도구와의 연결을 관리합니다.

/apps

ChatGPT connectors 또는 연결 가능한 apps를 탐색합니다. 외부 업무 도구 연결 상태를 확인할 수 있습니다.

25/ps, /skills, /plugins

/ps

background terminals를 표시합니다. Codex가 백그라운드에서 실행 중인 터미널 작업을 확인할 때 사용합니다.

/skills

사용 가능한 Skills를 확인하거나 호출합니다. Skills는 Codex가 특정 작업을 더 잘 수행하도록 만드는 재사용 가능한 작업 지식입니다.

/plugins

설치된 plugins를 탐색하고 관리합니다. 설치된 plugin 확인, 활성화/비활성화, marketplace plugin 탐색이 가능합니다.

26/title, /config, /statusline

/title

터미널 창 제목을 설정합니다.

/title auth-refactor

여러 Codex 세션을 동시에 열었을 때 창을 구분하는 데 유용합니다.

/config

현재 적용 중인 config 값과 source를 출력합니다. 어떤 config가 적용 중인지 확인하고, user config와 project config 충돌을 확인할 수 있습니다.

/statusline

TUI footer를 설정합니다. 모델, context, git branch 같은 정보를 보기 좋게 구성할 수 있습니다.

27/feedback, /logout

/feedback

Codex maintainers에게 로그와 피드백을 전송합니다.

/feedback

Codex 버그를 보고하거나 이상한 동작을 전달할 때 사용합니다. 전송 전에 민감한 정보가 포함되지 않았는지 확인해야 합니다.

/logout

Codex에서 로그아웃합니다.

/logout
또는 터미널에서:
codex logout

28초보자가 가장 먼저 외울 Slash Commands

처음부터 모든 명령어를 외울 필요는 없습니다. 아래 7개부터 익히면 됩니다.

/plan

복잡한 작업을 바로 실행하지 않고 계획부터 세움

/diff

Codex가 바꾼 내용을 확인

/status

현재 세션 상태 확인

/permissions

권한과 sandbox 상태 확인

/review

변경사항 리뷰

/compact

긴 대화 정리

/quit

종료

29초보자 기본 루틴

대부분의 작업은 이 루틴을 따르면 안전합니다.

1/plan 작업 계획 확인

2/diff 변경사항 확인

3/review 변경사항 검토

4/status 문제 생기면 상태 확인

5/quit 종료

30작업 유형별 Slash Command 추천

처음 보는 프로젝트 분석

/plan, /status

작은 코드 수정

/diff, /review

큰 리팩터링

/plan, /goal, /compact, /diff

보안 점검

/review, /permissions, /plan

긴 디버깅

/compact, /status, /ps

권한 문제 해결

/permissions, /config

외부 도구 확인

/mcp, /apps

31좋은 /plan 사용 예시

인증 리팩터링

/plan src/auth 폴더의 로그인 흐름을 리팩터링하려고 해.
현재 구조, 중복 로직, 위험 요소, 테스트 계획을 먼저 정리해줘.
아직 코드는 수정하지 마.

테스트 추가

/plan 회원가입 API에 대한 테스트를 추가하려고 해.
기존 테스트 구조를 먼저 확인하고,
어떤 케이스를 추가해야 하는지 계획을 세워줘.

32좋은 /review 사용 예시

일반 리뷰

/review

보안 중심 리뷰

/review 이번 변경사항에서 인증 우회, 권한 검증 누락,
민감정보 노출 가능성을 중심으로 봐줘.

테스트 중심 리뷰

/review 이번 변경에서 테스트가 부족한 부분과
edge case 누락을 중심으로 봐줘.

33좋은 /diff 후속 요청 예시

/diff를 본 뒤에는 다음처럼 추가 요청할 수 있습니다.

이 diff에서 불필요한 변경이 있는지 찾아줘.
이 변경사항을 커밋 메시지 형태로 요약해줘.
이 diff 기준으로 PR 설명을 작성해줘.
이 변경 중 테스트가 필요한 부분을 알려줘.
이 변경사항이 기존 동작을 깨뜨릴 위험이 있는지 검토해줘.

34Slash Command와 일반 프롬프트 조합하기

나쁜 예

/plan
/review

좋은 예

/plan 결제 모듈의 에러 처리 방식을 정리하려고 해.
현재 구조를 분석하고, 변경 범위와 테스트 계획을 먼저 제안해줘.

/review 이번 변경에서 보안 문제, 성능 저하,
테스트 누락을 중심으로 봐줘.

명령어만 입력해도 동작하지만, 원하는 기준을 함께 적으면 결과가 더 좋아집니다.

35Slash Command 사용 시 주의사항

1. /new는 변경사항을 되돌리지 않는다

/new는 새 대화를 시작할 뿐입니다. 파일 변경사항은 그대로 남아 있으므로, /diff나 git diff로 확인해야 합니다.

2. /compact는 만능이 아니다

/compact는 긴 대화를 요약하지만, 세부 내용 일부가 압축될 수 있습니다. 중요한 요구사항은 AGENTS.md나 별도 문서에 남기는 것이 좋습니다.

3. /permissions에서 권한을 무작정 높이지 않는다

Codex가 추가 권한을 요청하면 이유를 확인하고, 더 좁은 권한으로 해결할 수 있는지 확인합니다.

36더 많은 주의사항

4. /review가 사람 리뷰를 대체하지는 않는다

/review는 강력하지만 최종 검토는 사람이 해야 합니다. 특히 인증, 결제, 보안, 데이터베이스 변경은 직접 확인해야 합니다.

5. /goal은 장기 작업용이다

간단한 작업에는 /plan만으로 충분합니다. /goal은 여러 단계에 걸친 지속 목표가 있을 때 사용합니다.

37Slash Command 실전 루틴 - 안전한 코드 수정

기본 루틴

/plan 작업 계획 세우기
→ 계획 확인
→ 수정 진행
→ /diff
→ /review
→ 테스트 실행
→ 요약
→ /quit

구체 예시

/plan 로그인 API에 이메일 형식 검증을 추가하려고 해.
기존 validation 패턴과 테스트 구조를 먼저 확인해줘.

38Slash Command 실전 루틴 - 디버깅과 초기화

긴 디버깅 루틴

/status
→ /plan
→ 원인 후보 분석
→ 테스트 실행
→ /compact
→ 수정
→ /diff
→ /review

프로젝트 초기 세팅 루틴

/init
→ AGENTS.md 수정
→ /config
→ /permissions
→ /status

39Slash Command 빠른 참조

/quit, /exit

Codex 종료

/new, /resume, /fork

대화 관리

/model, /compact

세션 설정

/diff, /review, /plan

핵심 작업 명령

/goal, /vim, /hooks

고급 기능

/mention, /init

프로젝트 관리

/status, /permissions, /config

상태 확인

/personality, /mcp, /apps

외부 연결

/ps, /skills, /plugins

도구 관리

/title, /statusline

UI 설정

/feedback, /logout

계정 관리

섹션 08 · 마무리

이 단원에서 기억할 것

Slash Command는 Codex CLI에서 세션을 제어하고, 코드를 검토하고, 작업을 계획하는 강력한 도구입니다.

초보자에게 가장 중요한 것은 /plan → /diff → /review 루틴입니다. 이 세 가지만으로도 안전하고 효율적인 작업이 가능합니다.

다음 단원

9단원. 설정 시스템: config.toml 이해하기

9. 설정 시스템: config.toml 이해하기

01Codex 설정 우선순위

Codex는 설정값을 다음 순서로 해석합니다. 위에 있을수록 우선순위가 높습니다.

CLI flags, --config — 이번 실행에서만 적용되는 임시 설정

프로젝트 .codex/config.toml — 현재 프로젝트 또는 하위 폴더 전용 설정

--profile 프로필 파일 — 특정 작업 모드용 설정

User config — 개인 기본 설정

System config — 시스템 전체 기본 설정

Built-in defaults — Codex 내장 기본값

예를 들어 ~/.codex/config.toml에 기본 모델을 지정했더라도, 실행할 때 아래처럼 입력하면 이번 실행에서는 CLI 옵션이 이깁니다.

codex --model gpt-5.5

또는 임의 키를 직접 덮어쓸 수 있습니다.

codex --config model='"gpt-5.5"'
codex --config sandbox_workspace_write.network_access=true

--config 값은 JSON이 아니라 TOML 값으로 파싱됩니다. 문자열은 따옴표 처리에 주의해야 합니다.

02User config

User config는 개인 기본 설정입니다.

기본 위치는 다음과 같습니다.

~/.codex/config.toml

Codex CLI와 IDE 확장은 같은 설정 레이어를 공유합니다. 따라서 CLI에서 설정한 기본 모델, 승인 정책, 샌드박스 설정, MCP 서버 설정은 IDE 확장에서도 같은 기준으로 적용될 수 있습니다.

User config에는 보통 다음 값을 둡니다.

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

model

기본으로 사용할 모델

approval_policy

명령 실행 전 승인 요청 방식

sandbox_mode

파일 시스템·네트워크 접근 범위

web_search

웹 검색 사용 방식

[mcp_servers.*]

MCP 서버 연결 설정

[features]

기능 플래그 설정

approval_policy는 untrusted, on-request, never 등을 사용할 수 있고, sandbox_mode는 read-only, workspace-write, danger-full-access 값을 사용할 수 있습니다.

03Project config

Project config는 특정 저장소 또는 하위 폴더에만 적용되는 설정입니다.

위치는 다음과 같습니다.

<repo>/.codex/config.toml

Codex는 프로젝트 루트에서 현재 작업 디렉터리까지 올라오며 .codex/config.toml을 찾고, 같은 키가 여러 번 나오면 현재 작업 디렉터리에 가장 가까운 설정이 이깁니다. 단, 프로젝트가 trusted 상태일 때만 프로젝트 설정을 불러옵니다. untrusted 프로젝트에서는 프로젝트 .codex/ 레이어, 프로젝트 로컬 hooks, rules가 무시됩니다.

예시:

my-app/
  .codex/config.toml
  frontend/
    .codex/config.toml

현재 위치가 my-app/frontend라면 frontend/.codex/config.toml이 더 가까우므로 같은 키에 대해 우선 적용됩니다.

Project config에는 프로젝트 작업 방식만 넣는 것이 좋습니다.

model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

반대로 provider, auth, telemetry, notification처럼 머신 또는 개인 계정에 묶이는 설정은 프로젝트 설정에서 무시될 수 있습니다.

04System config

System config는 머신 전체에 적용되는 기본 설정입니다. Unix 기준 위치는 다음과 같습니다.

/etc/codex/config.toml

우선순위는 User config보다 낮습니다. 즉, 시스템 관리자가 기본값을 깔아두더라도 사용자가 ~/.codex/config.toml에서 같은 키를 지정하면 User config가 이깁니다.

System config는 "강제 정책"이라기보다 "공통 기본값"에 가깝습니다.

예시:

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

조직에서 반드시 막아야 하는 값이 있다면 System config보다 requirements.toml을 사용해야 합니다.

05Managed requirements.toml

requirements.toml은 일반 설정 파일이 아니라 관리자가 강제하는 제약 조건입니다. 사용자가 config.toml, profile, CLI 옵션에서 다른 값을 지정해도, requirements와 충돌하면 Codex가 호환 가능한 값으로 되돌리고 사용자에게 알립니다.

대표적으로 이런 값을 제한할 수 있습니다.

allowed_approval_policies = ["untrusted", "on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]
allowed_web_search_modes = ["disabled", "cached"]

위 예시는 다음을 막습니다.

approval_policy = "never"
sandbox_mode = "danger-full-access"
web_search = "live"

requirements 레이어의 우선순위는 다음과 같습니다.

Cloud-managed requirements

macOS MDM requirements_toml_base64

System requirements.toml

중요한 점은 requirements.toml이 값을 "설정"한다기보다 "허용 범위"를 정한다는 것입니다.

06CODEX_HOME 이해하기

CODEX_HOME은 Codex의 로컬 상태 루트 디렉터리입니다. 기본값은 다음과 같습니다.

~/.codex

이 안에는 보통 다음 파일과 디렉터리가 들어갑니다.

~/.codex/
  config.toml
  auth.json
  history.jsonl
  log/
  sessions/
  skills/

환경변수로 CODEX_HOME을 지정할 수 있지만, 지정한 디렉터리는 미리 존재해야 합니다.

mkdir -p ~/.codex-work
CODEX_HOME=~/.codex-work codex

이렇게 실행하면 Codex는 기본 ~/.codex/config.toml 대신 아래 파일을 기준으로 봅니다.

~/.codex-work/config.toml

실무에서는 계정, 조직, 실험 환경을 분리할 때 유용합니다.

07config.toml 기본 구조

TOML에서는 루트 키를 먼저 쓰고, 그다음 테이블을 쓰는 방식이 읽기 쉽습니다. 기본 구조는 다음과 같습니다.

# 1. 루트 설정
model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

# 2. sandbox 세부 설정
[sandbox_workspace_write]
network_access = false
writable_roots = []

# 3. 환경변수 전달 정책
[shell_environment_policy]
inherit = "core"
include_only = ["PATH", "HOME", "USER", "SHELL"]

# 4. 기능 플래그
[features]
hooks = true
undo = true

# 5. MCP 서버 설정 예시
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true

자주 쓰는 값은 다음과 같습니다.

approval_policy

"on-request" — 필요할 때 사용자 승인 요청

sandbox_mode

"workspace-write" — 현재 작업공간 쓰기 허용

web_search

"cached" — 캐시 기반 웹 검색

model_reasoning_effort

"medium" 또는 "high" — 추론 강도

sandbox_workspace_write.network_access

false — 샌드박스 내부 네트워크 차단

08초보자용 최소 config

처음에는 과하게 열어두지 않는 설정이 좋습니다.

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[sandbox_workspace_write]
network_access = false

이 설정의 의도는 단순합니다.

on-request

위험하거나 범위를 벗어난 작업은 물어보게 함

workspace-write

프로젝트 안에서는 작업 가능

network_access = false

임의 네트워크 접근 방지

web_search = "cached"

기본 검색은 가능하되 live fetch는 제한

초보자는 danger-full-access와 approval_policy = "never" 조합을 피하는 것이 좋습니다.

09실무자용 추천 config

실무자는 생산성과 안전성을 같이 잡는 구성이 좋습니다.

model = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
hide_agent_reasoning = true

[sandbox_workspace_write]
network_access = false
writable_roots = []

[shell_environment_policy]
inherit = "core"
include_only = [
  "PATH", "HOME", "USER", "SHELL",
  "LANG", "LC_ALL", "TERM"
]

[features]
hooks = true
undo = true
shell_snapshot = true

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true
startup_timeout_sec = 10
tool_timeout_sec = 60

실무 기준으로는 다음 원칙을 잡으면 됩니다.

기본은 workspace-write

프로젝트 작업은 가능하게 하되 시스템 전체 접근은 막음

승인은 on-request

위험 작업은 명시적으로 확인

네트워크는 기본 차단

필요한 경우 프로젝트별 또는 승인 기반으로 열기

MCP는 User config 우선

provider/auth 성격이 섞이면 project config보다 user config가 안정적

프로젝트별 차이는 .codex/config.toml

repo마다 다른 추론 강도, 샌드박스 설정만 분리

10config 충돌이 날 때: 1단계 (CLI 옵션)

설정이 예상대로 적용되지 않으면 아래 순서로 확인합니다.

1단계: 실행할 때 CLI 옵션을 줬는지 확인

CLI 옵션과 --config가 최상위 우선순위입니다.

codex --model gpt-5.5
codex --config sandbox_mode='"read-only"'

테스트할 때는 일단 옵션 없이 실행해 봅니다.

codex

11config 충돌이 날 때: 2단계 (Project config)

2단계: 현재 디렉터리의 project config 확인

현재 위치 기준으로 가까운 .codex/config.toml이 user config보다 우선합니다.

pwd
find .. -path "*/.codex/config.toml" -print

프로젝트가 untrusted 상태라면 project config는 무시될 수 있습니다. trusted 여부도 같이 확인해야 합니다.

12config 충돌이 날 때: 3단계 (프로필)

3단계: `--profile` 사용 여부 확인

프로필을 사용하면 다음 파일이 user config 위에 덮입니다.

~/.codex/<profile-name>.config.toml

예시:

codex --profile deep-review

Codex 0.134.0 이후에는 config.toml 안의 [profiles.name] 방식이 아니라 별도 profile-name.config.toml 파일을 사용하는 구조입니다.

13config 충돌이 날 때: 4단계 (CODEX_HOME)

4단계: 실제 `CODEX_HOME` 확인

CODEX_HOME을 바꿔놓으면 보고 있는 config 파일이 달라질 수 있습니다.

echo $CODEX_HOME

비어 있으면 기본값은 다음입니다.

~/.codex/config.toml

값이 있다면 다음 파일을 확인해야 합니다.

$CODEX_HOME/config.toml

14config 충돌이 날 때: 5단계 (requirements)

5단계: requirements 정책 확인

아무리 config를 바꿔도 적용되지 않는다면 관리 정책이 막고 있을 수 있습니다.

확인할 파일:

/etc/codex/requirements.toml

Windows라면:

%ProgramData%OpenAICodex
equirements.toml

특히 아래 키를 확인합니다.

allowed_approval_policies = ["on-request"]
allowed_sandbox_modes = ["workspace-write"]
allowed_web_search_modes = ["disabled", "cached"]

requirements는 사용자가 우회할 수 없는 제약 조건입니다. 충돌하면 Codex가 호환 가능한 값으로 되돌립니다.

15config 충돌이 날 때: 6단계 (Project 무시 키)

6단계: project config에서 무시되는 키를 넣었는지 확인

프로젝트 .codex/config.toml에는 일부 키를 넣어도 무시됩니다.

대표적으로 피해야 할 키:

openai_base_url = "..."
model_provider = "..."
notify = [...]
profile = "..."
[model_providers.foo]
[otel]

이런 값은 user config에 둡니다.

~/.codex/config.toml

16config 충돌이 날 때: 7단계 (TOML 문법)

7단계: TOML 문법 확인

자주 나는 실수는 다음과 같습니다.

# 잘못된 예: 문자열 따옴표 누락
model = gpt-5.5

# 올바른 예
model = "gpt-5.5"

# 잘못된 예: 테이블 아래에 루트 키를 섞어서 헷갈림
[sandbox_workspace_write]
network_access = false

model = "gpt-5.5"

가독성을 위해 루트 키를 먼저 쓰고, 그다음 [table]을 쓰는 방식으로 정리합니다.

섹션 09 · 마무리

이 단원에서 기억할 것

config.toml은 Codex의 기본 행동을 정하는 파일입니다. 가장 기본 위치는 ~/.codex/config.toml이고, 프로젝트별 차이는 <repo>/.codex/config.toml에 둡니다.

우선순위는 위에서 아래로 강합니다. CLI 옵션이 가장 강하고, project config는 user config보다 강합니다. 반대로 조직 보안 정책은 requirements.toml로 관리되며, 이 값은 일반 config로 우회할 수 없습니다.

CLI 옵션 → 프로젝트 설정 → 프로필 → User 설정 → System 설정 → 내장 기본값

다음 단원

10단원. 모델 선택 가이드

10. 모델 선택 가이드

01먼저 정정: 모델과 reasoning effort는 다르다

Codex에서 다음 두 개는 서로 다른 설정입니다.

model = "gpt-5.5"
model_reasoning_effort = "xhigh"

model은 어떤 AI 모델을 쓸지 정합니다. model_reasoning_effort는 그 모델이 얼마나 깊게 생각할지 정합니다.

따라서 "Codex 5.5 xhigh를 쓴다"는 말은 정확히는 다음 뜻입니다.

gpt-5.5 모델을 사용하면서 reasoning effort를 xhigh로 올려서 쓴다.

02현재 Codex에서 기준으로 삼아야 할 모델 목록

현재 Codex 가이드에서 중심으로 다룰 모델은 아래와 같습니다.

gpt-5.5

기본 추천 모델. 복잡한 코딩, 컴퓨터 사용, 지식 작업, 리서치

gpt-5.4

03gpt-5.5: 기본 추천 모델

gpt-5.5는 현재 Codex에서 가장 먼저 선택해야 할 기본 모델입니다. 복잡한 코딩, computer use, 지식 작업, 리서치 워크플로에 적합한 최신 frontier 모델입니다.

추천 상황:

큰 기능 구현

계획, 수정, 검증 흐름이 안정적

리팩터링

여러 파일과 의존성을 같이 봐야 함

버그 추적

원인 분석과 수정 전략이 필요

문서·스프레드시트·슬라이드 생성

Codex 안에서 지식 작업 품질이 좋음

브라우저나 앱 조작 포함 작업

computer use와 tool use에 적합

불확실한 문제 해결

고난도 reasoning이 필요

04gpt-5.4: 비용과 성능의 균형 모델

gpt-5.4는 gpt-5.5보다 한 단계 낮은 비용과 성능의 균형 모델입니다. 전문 작업용 flagship frontier 모델로, gpt-5.3-codex의 코딩 능력에 더 강한 reasoning, tool use, agentic workflow 능력을 결합했습니다.

추천 상황:

일반적인 기능 추가

gpt-5.5까지 필요 없는 경우

중간 규모 버그 수정

비용과 품질 균형

반복적인 코드 수정

충분한 품질과 더 나은 사용량 효율

테스트 보강

대량 작업에서 부담이 낮음

빠른 실험

고급 모델 소모를 아낄 수 있음

설정 예시:

model = "gpt-5.4"
model_reasoning_effort = "medium"

05gpt-5.4-mini: 빠른 루틴 작업과 subagent용 모델

gpt-5.4-mini는 가볍고 빠른 작업에 적합합니다. responsive coding tasks와 subagents에 적합한 빠르고 효율적인 mini 모델이며, routine local messages에서 더 높은 사용량 한도를 제공합니다.

추천 상황:

간단한 함수 수정

큰 reasoning이 필요 없음

타입 에러 수정

범위가 좁음

문서 문구 수정

빠르게 처리 가능

테스트 이름 변경

단순 반복 작업

subagent 병렬 탐색

비용과 속도 효율이 좋음

대량 파일의 단순 패턴 변경

고급 모델 낭비 방지

설정 예시:

model = "gpt-5.4-mini"
model_reasoning_effort = "low"

초보자는 "간단한 일은 mini, 복잡한 일은 5.5"로 외우면 됩니다.

06gpt-5.3-codex: 코드 리뷰·클라우드 작업·전문 코딩 모델

gpt-5.3-codex는 이름 그대로 Codex 특화 모델입니다. 복잡한 소프트웨어 엔지니어링을 위한 업계 선도 코딩 모델이며, 그 코딩 능력이 gpt-5.4에도 반영되었습니다. Cloud tasks와 code review는 gpt-5.3-codex에서 실행됩니다.

추천 상황:

PR 리뷰

Codex code review의 핵심 모델

Cloud task

클라우드 작업과 직접 연결

복잡한 코드베이스 분석

agentic coding에 강함

장시간 실행형 작업

코드 변경 흐름에 특화

테스트 실패 분석

코드 중심 판단에 적합

설정 예시:

model = "gpt-5.3-codex"
model_reasoning_effort = "high"

07gpt-5.3-codex-spark: Pro용 초고속 research preview 모델

gpt-5.3-codex-spark는 일반적인 "최고 품질 모델"이라기보다, 빠른 코딩 반복을 위한 특수 모델입니다. near-instant, real-time coding iteration에 최적화된 text-only research preview 모델이며 ChatGPT Pro 사용자에게 제공됩니다.

추천 상황:

실시간 코드 아이디어

응답 속도가 중요

작은 수정 반복

빠른 왕복이 중요

UI 문구·간단 코드 스케치

깊은 추론보다 속도 우선

프로토타입 탐색

즉시성이 중요

실행 예시:

codex -m gpt-5.3-codex-spark

Spark는 research preview이고 Pro 사용자 전용으로 안내되며, API에서 일반적으로 쓰는 모델이라기보다는 Codex 안에서 빠른 반복을 위해 선택하는 모델입니다.

08gpt-5.2와 legacy 모델은 언제 보이는가

gpt-5.2는 현재 Codex 모델 문서에서 alternative model로 분류됩니다. 이전 세대 general-purpose 모델로, 깊은 숙고가 필요한 어려운 디버깅이나 agentic task에 사용할 수 있는 대체 선택지입니다.

하지만 초보자 가이드의 중심 모델로 둘 필요는 없습니다.

또한 gpt-5.1-codex-mini 같은 이름은 현재 목차에 넣지 않는 편이 맞습니다. API 전체 모델 목록에서 gpt-5.1 Codex mini는 deprecated로 표시됩니다.

정리하면:

gpt-5.5

중심 모델

gpt-5.4

보조 중심 모델

gpt-5.4-mini

가벼운 작업용 중심 모델

gpt-5.3-codex

Codex 특화 중심 모델

gpt-5.3-codex-spark

Pro research preview로 별도 설명

gpt-5.2

alternative로 짧게 설명

gpt-5.1-codex-mini

legacy/deprecated로 목차에서 제거

09xhigh는 모델명이 아니라 추론 강도다

gpt-5.5와 xhigh를 함께 쓰는 조합은 실무적으로 매우 강한 조합입니다.

model = "gpt-5.5"
model_reasoning_effort = "xhigh"

이 조합은 다음 작업에 적합합니다.

대규모 리팩터링

영향 범위를 더 깊게 검토

복잡한 버그 분석

원인 후보를 더 끈질기게 좁힘

보안 리뷰

누락 가능성을 줄임

아키텍처 설계

트레이드오프 검토가 중요

마이그레이션 계획

단계와 리스크를 함께 봐야 함

장문 문서 생성

구조와 일관성 유지가 중요

반대로 아래 작업에는 xhigh가 과할 수 있습니다.

단순 문구 수정

low

간단한 타입 에러

low 또는 medium

작은 함수 추가

medium

테스트 이름 변경

low

import 정리

minimal 또는 low

10작업 유형별 모델 선택표

처음 보는 코드베이스 분석

gpt-5.5 + high

대규모 리팩터링 계획

gpt-5.5 + xhigh

복잡한 버그 수정

gpt-5.5 + high 또는 xhigh

일반 기능 추가

gpt-5.5 또는 gpt-5.4 + medium

단순 코드 수정

gpt-5.4-mini + low

테스트 추가

gpt-5.4 또는 gpt-5.4-mini + medium

PR 리뷰

gpt-5.3-codex + high

Codex Cloud task

gpt-5.3-codex + 기본값

빠른 코드 반복

gpt-5.3-codex-spark + 기본값

문서·가이드 작성

gpt-5.5 + high

보안 검토

gpt-5.5 + xhigh

subagent 병렬 탐색

gpt-5.4-mini + low 또는 medium

11초보자 추천 조합

초보자는 처음부터 모델을 많이 바꾸지 않는 편이 좋습니다. 아래 조합 하나로 시작하면 충분합니다.

model = "gpt-5.5"
model_reasoning_effort = "medium"

이 조합은 품질, 속도, 비용 균형이 가장 무난합니다.

조금 더 안전하게 쓰고 싶다면:

model = "gpt-5.5"
model_reasoning_effort = "high"

정말 중요한 작업이라면:

model = "gpt-5.5"
model_reasoning_effort = "xhigh"

초보자 기준 추천 규칙은 간단합니다.

잘 모르겠다

gpt-5.5 + medium

중요한 코드 변경

gpt-5.5 + high

실패하면 큰 작업

gpt-5.5 + xhigh

가벼운 반복 작업

gpt-5.4-mini + low

12실무자 추천 조합

실무자는 작업 성격별로 profile을 나누는 것이 좋습니다.

기본 작업용

model = "gpt-5.5"
model_reasoning_effort = "medium"

깊은 분석용

model = "gpt-5.5"
model_reasoning_effort = "xhigh"

빠른 루틴 작업용

model = "gpt-5.4-mini"
model_reasoning_effort = "low"

코드 리뷰용

model = "gpt-5.3-codex"
model_reasoning_effort = "high"

비용 절약형 일반 작업용

model = "gpt-5.4"
model_reasoning_effort = "medium"

13config.toml에 기본 모델 설정하기

기본 모델은 ~/.codex/config.toml에 지정합니다.

# ~/.codex/config.toml

model = "gpt-5.5"
model_reasoning_effort = "medium"

네 스타일처럼 강하게 쓰려면 이렇게 둡니다.

# ~/.codex/config.toml

model = "gpt-5.5"
model_reasoning_effort = "xhigh"

단, 모든 작업을 xhigh로 처리하면 응답 시간이 길어지고 사용량 소모가 커질 수 있습니다. xhigh는 가장 어려운 asynchronous agentic task나 모델 지능 한계를 테스트하는 eval에 쓰라고 설명됩니다.

실무용 profile 예시:

# ~/.codex/deep.config.toml

model = "gpt-5.5"
model_reasoning_effort = "xhigh"

실행:

codex --profile deep

14CLI와 IDE에서 모델 바꾸기

CLI에서 새 세션을 특정 모델로 시작하려면 -m 또는 --model을 씁니다.

codex -m gpt-5.5
codex -m gpt-5.4
codex -m gpt-5.4-mini
codex -m gpt-5.3-codex

CLI에서 -m 또는 --model 플래그를 사용할 수 있으며, 활성 CLI 세션 중에는 /model 명령으로 모델을 바꿀 수 있습니다. IDE extension에서는 입력창 아래 model selector를 사용합니다.

활성 세션에서:

/model

한 번만 덮어쓰기:

codex --model gpt-5.5

reasoning effort까지 일회성으로 바꾸려면:

codex -m gpt-5.5 -c model_reasoning_effort='"xhigh"'

15비용·속도·품질 기준으로 고르는 법

모델 선택은 아래 순서로 판단하면 됩니다.

1단계: 중요한 작업인가?

중요하면 gpt-5.5를 씁니다.

model = "gpt-5.5"
model_reasoning_effort = "high"

더 중요하면:

model = "gpt-5.5"
model_reasoning_effort = "xhigh"

2단계: 반복 작업인가?

반복적이고 단순하면 gpt-5.4-mini를 씁니다.

model = "gpt-5.4-mini"
model_reasoning_effort = "low"

3단계: 코드 리뷰나 Cloud 작업인가?

코드 리뷰와 Cloud task에서는 gpt-5.3-codex가 중요합니다.

4단계: 속도가 제일 중요한가?

Pro 사용자이고 near-instant coding iteration이 필요하면 gpt-5.3-codex-spark를 고려합니다. Spark는 Fast mode가 아니라 별도 모델이며, research preview로 제공됩니다.

5단계: 더 빠르게 돌리고 싶은가?

Fast mode는 별도 모델이 아니라 지원 모델을 더 빠르게 실행하는 속도 설정입니다. Fast mode는 현재 gpt-5.5와 gpt-5.4를 지원하고, 더 많은 credits를 소비합니다.

CLI에서는:

/fast on
/fast off
/fast status

config에 기본값으로 둘 수도 있습니다.

service_tier = "fast"

[features]
fast_mode = true

섹션 10 · 마무리

대부분의 Codex 작업은 gpt-5.5로 시작합니다. 가볍고 반복적인 작업은 gpt-5.4-mini를 쓰고, 코드 리뷰와 Cloud 작업은 gpt-5.3-codex가 중요합니다. xhigh는 모델명이 아니라 추론 강도입니다.

다음 단원

11단원. 추론 노력 Reasoning Effort

11. 추론 노력 Reasoning Effort

01추론 노력(Reasoning Effort)이란

Reasoning effort는 모델이 답을 내기 전에 얼마나 깊게 생각할지 정하는 설정입니다.

Codex에서 모델을 고르는 것이 "누가 일할지"를 정하는 것이라면, reasoning effort는 "얼마나 신중하게 일할지"를 정하는 것입니다.

예를 들어:

model = "gpt-5.5"
model_reasoning_effort = "xhigh"

이것은 "gpt-5.5 모델을 최고 수준 추론 강도로 사용한다"는 뜻입니다.

02Reasoning model의 작동 원리

Reasoning model은 최종 답변을 바로 쓰기 전에 내부 reasoning token을 사용해 문제를 분해하고, 여러 접근 방식을 검토하고, 도구 사용 계획을 세웁니다. 이는 복잡한 문제 해결, 코딩, 과학적 추론, 다단계 agentic workflow에 특히 적합합니다.

중요한 점은 이 reasoning token이 사용자에게 그대로 보이지 않는다는 것입니다. 하지만 API 문서 기준으로 reasoning token은 context window 공간을 차지하고, output token으로 과금됩니다.

즉 reasoning effort를 올리면 보통 다음 변화가 생깁니다.

품질

복잡한 작업에서 좋아질 수 있음

속도

더 느려질 수 있음

비용

reasoning token 때문에 늘어날 수 있음

안정성

계획, 검토, 도구 사용이 더 신중해질 수 있음

과잉추론

단순 작업에서는 오히려 불필요하게 길어질 수 있음

03Codex 설정 키: model_reasoning_effort

Codex의 기본 추론 강도는 config.toml에서 설정합니다.

model_reasoning_effort = "medium"

Codex 설정 레퍼런스 기준 model_reasoning_effort는 다음 값을 지원합니다. 단, xhigh는 모델에 따라 지원 여부가 달라집니다.

minimal
low
medium
high
xhigh

기본 예시

model = "gpt-5.5"
model_reasoning_effort = "medium"

깊은 분석용 예시

model = "gpt-5.5"
model_reasoning_effort = "xhigh"

04minimal: 거의 생각하지 않고 빠르게

minimal은 Codex config 기준에서 가장 낮은 reasoning effort입니다.

추천 상황:

단순 문구 수정

깊은 판단이 필요 없음

import 정리

규칙 기반 작업

짧은 설명 요청

빠른 응답이 중요

단순 파일 위치 찾기

reasoning보다 검색이 중요

정해진 포맷 변환

창의적 판단이 거의 없음

예시

model = "gpt-5.4-mini"
model_reasoning_effort = "minimal"

단, 코드 변경이 실제 파일 수정과 연결된다면 최소한 low 이상을 쓰는 편이 더 안전합니다.

05low: 가벼운 추론이 필요한 작업

low는 빠른 작업에 적합하지만, minimal보다는 조금 더 생각하게 하는 설정입니다.

추천 상황:

작은 함수 수정

간단한 문맥 판단 필요

타입 에러 수정

오류 원인 확인 필요

테스트 이름 변경

단순하지만 실수 방지 필요

코드 스타일 정리

규칙 적용 중심

문서 요약

깊은 분석보다는 압축이 중요

실무에서 low는 "가볍지만 실수하면 귀찮은 작업"에 좋습니다. 특히 gpt-5.4-mini + low 조합은 빠른 반복 작업이나 subagent용으로 적합합니다.

06medium: 기본 추천 균형점

medium은 대부분의 사용자에게 가장 무난한 기본값입니다.

GPT-5.5 문서는 reasoning effort 기본값이 medium이며, 품질·신뢰성·지연시간·비용의 균형점이라고 설명합니다.

추천 상황:

일반 기능 추가

적당한 계획과 구현 필요

보통 난이도 버그 수정

원인 분석 필요

테스트 작성

코드 이해와 검증 필요

문서 작성

구조화 필요

처음 쓰는 프로젝트 작업

너무 낮게 잡으면 누락 가능

초보자 기본 추천

model = "gpt-5.5"
model_reasoning_effort = "medium"

07high: 복잡한 코딩과 분석 작업

high는 복잡한 문제를 더 신중하게 풀게 하는 설정입니다.

추천 상황:

여러 파일에 걸친 기능 추가

영향 범위 검토 필요

실패한 테스트 원인 분석

원인 후보 비교 필요

리팩터링 계획

구조 판단 필요

코드 리뷰

누락과 부작용 확인 필요

API 설계

인터페이스와 확장성 판단 필요

배포 전 검토

실수 비용이 큼

예시

model = "gpt-5.5"
model_reasoning_effort = "high"

08xhigh: 최고난도 작업용 깊은 추론

xhigh는 가장 강한 추론 강도입니다.

GPT-5.5 문서는 high나 xhigh를 품질 향상이 추가 지연시간과 비용을 정당화할 때 사용하라고 설명합니다. 특히 xhigh는 가장 어려운 비동기 agentic task나 모델 지능의 한계를 테스트하는 eval에 적합합니다.

추천 상황:

대규모 리팩터링

전체 구조와 부작용 검토

보안 리뷰

누락 위험 감소

복잡한 장애 분석

여러 원인 후보 비교

아키텍처 설계

장단점과 미래 확장성 검토

마이그레이션 계획

단계별 리스크 관리

긴 문서·가이드 작성

구조 일관성 유지

중요한 자동화 설계

실패 비용이 큼

하지만 모든 작업에 xhigh가 정답은 아닙니다. GPT-5.5 문서는 higher reasoning effort가 항상 더 좋은 것은 아니며, 기준이 약하거나 도구 접근이 열려 있으면 과잉 탐색이나 품질 저하가 생길 수 있다고 설명합니다.

09none과 minimal의 차이

API 문서에서는 GPT-5.5 reasoning effort 값으로 none, low, medium, high, xhigh가 보입니다.

하지만 Codex config.toml의 model_reasoning_effort 값은 다음과 같습니다.

minimal
low
medium
high
xhigh

즉 Codex 설정 파일에서는 minimal을 사용합니다.

API의 reasoning.effort 값

none, low, medium, high, xhigh

Codex model_reasoning_effort 값

minimal, low, medium, high, xhigh

Codex 사용자라면 config.toml에서는 minimal을 기준으로 기억하면 됩니다.

10Plan Mode 전용 설정: plan_mode_reasoning_effort

Plan Mode에서는 일반 답변보다 더 깊은 추론이 필요할 때가 많습니다. 그래서 Codex에는 Plan Mode 전용 override인 plan_mode_reasoning_effort가 따로 있습니다.

예시

model = "gpt-5.5"
model_reasoning_effort = "medium"

# /plan 모드에서는 더 깊게 생각하게 함
plan_mode_reasoning_effort = "high"

이 설정은 실무에서 꽤 유용합니다. 일반 작업은 빠르게, 계획 수립은 신중하게 하는 방식입니다.

추천 조합:

일반 effort

Plan Mode effort

용도

low

medium

빠른 작업자

medium

high

일반 실무자

high

xhigh

신중한 설계·리뷰 중심

xhigh

최고 신중 모드

11reasoning_summary와의 차이

model_reasoning_summary는 model_reasoning_effort와 다릅니다.

model_reasoning_effort

모델이 얼마나 깊게 생각할지 정함

model_reasoning_summary

reasoning 관련 요약을 어느 정도 보여줄지 정함

Codex 설정 레퍼런스 기준 model_reasoning_summary 값은 다음입니다.

auto
concise
detailed
none

예시

model = "gpt-5.5"
model_reasoning_effort = "high"
model_reasoning_summary = "concise"

초보자는 보통 기본값인 auto 또는 간결한 concise가 좋습니다. reasoning summary를 자세히 보이게 한다고 해서 모델이 더 깊게 생각하는 것은 아닙니다. 깊게 생각하게 하는 설정은 model_reasoning_effort입니다.

12verbosity와의 차이

model_verbosity도 model_reasoning_effort와 다릅니다.

model_reasoning_effort

생각의 깊이

model_verbosity

최종 답변의 길이와 상세도

예를 들어 아래 설정은 "깊게 생각하지만 짧게 답하라"는 뜻입니다.

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
model_verbosity = "low"

반대로 아래 설정은 "적당히 생각하고 자세히 설명하라"는 뜻입니다.

model = "gpt-5.5"
model_reasoning_effort = "medium"
model_verbosity = "high"

실무에서 쓸 만한 조합:

깊은 판단 + 짧은 결론

xhigh + low verbosity

학습용 설명

medium/high + high verbosity

코드 리뷰

high + medium verbosity

문서 작성

high + high verbosity

13토큰 비용과 속도에 미치는 영향

Reasoning effort를 올리면 내부 reasoning token이 늘어날 수 있습니다. API 문서 기준 reasoning token은 사용자에게 보이지 않지만 context window를 차지하고 output token으로 과금됩니다.

따라서 다음 공식이 성립합니다.

높은 reasoning effort
= 더 깊은 검토 가능성
= 더 긴 대기시간 가능성
= 더 높은 토큰 사용량 가능성

하지만 GPT-5.5는 이전 모델보다 같은 reasoning effort에서도 더 적은 reasoning token으로 강한 결과를 낼 수 있도록 개선되었습니다.

실무 기준:

빨리 끝내야 함

minimal 또는 low

품질과 속도 균형

medium

중요한 코드 변경

high

실패 비용이 큼

xhigh

14작업 유형별 추천 설정

작업 유형에 따라 추천 reasoning effort가 다릅니다.

단순 질문 답변

minimal 또는 low

문구 수정

minimal

import 정리

minimal

작은 함수 수정

low

타입 에러 해결

low 또는 medium

일반 기능 추가

medium

테스트 작성

medium

처음 보는 코드베이스 분석

high

버그 원인 추적

high

여러 파일 리팩터링

high 또는 xhigh

보안 리뷰

xhigh

아키텍처 설계

xhigh

마이그레이션 계획

xhigh

Plan Mode

high 또는 xhigh

15초보자 추천 설정과 실무자 프로필

초보자 기본 설정:

model = "gpt-5.5"
model_reasoning_effort = "medium"
model_reasoning_summary = "auto"
model_verbosity = "medium"

실무자 추천 profile 구성:

기본 작업용

medium + plan_mode high

깊은 분석용

xhigh + xhigh

빠른 작업용

gpt-5.4-mini + low

코드 리뷰용

gpt-5.3-codex + high

최고 신중 모드

gpt-5.5 + xhigh

초보자가 기억해야 할 기준은 단 하나입니다.

minimal = 가장 빠름 / low = 가벼운 작업 / medium = 기본 추천 / high = 복잡한 작업 / xhigh = 실패 비용이 큰 최고난도 작업

섹션 11 · 마무리

이 단원에서 기억할 것

Reasoning effort는 모델의 "생각 깊이"를 정하는 설정입니다. Codex에서 기본 키는 model_reasoning_effort이며, 사용 가능한 값은 minimal, low, medium, high, xhigh입니다.

초보자 추천:

model = "gpt-5.5"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

기억할 원칙은 하나입니다. 작업이 단순하면 낮게, 복잡하고 실패 비용이 크면 높게 설정하면 됩니다.

다음 단원

12단원. Codex 비용 이해하기

12. Codex 비용 이해하기

01Codex 비용 구조 한 줄 요약

Codex 비용은 ChatGPT 플랜에 포함된 사용량을 먼저 쓰고, 한도를 넘으면 credits 또는 API token 과금으로 계산되는 구조다. Codex는 Free, Go, Plus, Pro, Business, Edu, Enterprise 플랜에 포함되지만, 사용량 한도와 추가 결제 방식은 플랜마다 다르다.

ChatGPT 로그인 사용 = 플랜 포함 사용량 + 필요 시 credits
API Key 사용 = OpenAI API token 과금
Business/Enterprise = seat + workspace credits + admin spend control

02ChatGPT 플랜별 Codex 포함 여부

Free

제한적 포함 (Codex credits 추가 구매 불가, Plus 업그레이드 유도)

가벼운 작업용 포함 (Codex credits 추가 구매 불가, Plus 업그레이드 유도)

Plus

포함 (한도 초과 시 credits 구매 가능), 약 30,000원/month

Pro 5x

Plus 대비 5x 사용량, 약 150,000원/month

Pro 20x

Plus 대비 20x 사용량, 약 300,000원/month

Business

standard seat 또는 Codex seat로 포함

Enterprise / Edu

계약형, flexible pricing 또는 per-seat usage limit

API Key

구독과 별도, API token 과금

03Free / Go

Free와 Go에도 Codex는 포함된다. Free는 quick coding task 탐색용, Go는 lightweight coding task용으로 설명된다.

Free

0원/month, 제한적 Codex 체험

약 12,000원/month, 가벼운 Codex 작업

중요한 제한은 Free와 Go 사용자는 Codex 한도 초과 시 credits를 추가 구매하는 방식이 아니라 Plus 업그레이드를 안내받는다는 점이다. Free와 Go 사용자는 Codex credits 추가 구매 대신 Plus 업그레이드 prompt를 받는다.

04Plus

Plus는 월 약 30,000원이며, Codex web, CLI, IDE extension, iOS, cloud-based integrations, automatic code review, Slack integration, GPT-5.5, GPT-5.4, GPT-5.3-Codex, GPT-5.4-mini를 포함한다.

가격

약 30,000원/month

로컬 Codex

가능

CLI / IDE

가능

Cloud task

가능, GPT-5.3-Codex 기준

Code review

가능, GPT-5.3-Codex 기준

추가 credits

가능

05Pro 5x / Pro 20x

Pro는 두 단계로 나뉜다.

Pro 5x

약 150,000원/month, Plus 대비 5x 사용량

Pro 20x

약 300,000원/month, Plus 대비 20x 사용량

Pro 약 150,000원이 Plus보다 5x 높은 사용량, Pro 약 300,000원이 Plus보다 20x 높은 사용량을 제공한다. 기존 약 300,000원 Pro는 유지되며, 약 150,000원 Pro는 더 낮은 가격의 Pro 선택지다.

Pro는 Plus의 모든 Codex 기능에 더해 GPT-5.3-Codex-Spark research preview 접근을 제공한다. Spark는 Pro 사용자용 빠른 day-to-day coding model로 설명된다.

06Business

Business는 두 seat 구조다.

Standard ChatGPT seat

ChatGPT + Codex 포함, 고정 월 과금, 최소 2 seats

Codex seat

Codex only, 사용량 기반 과금, 최소 없음

Standard ChatGPT seat 가격은 대부분 국가 기준 월간 약 37,500원/user/month, 연간 결제 시 약 30,000원/user/month로 설명된다. Codex seat는 Codex only이며 고정 월 비용 없이 사용량 기반이고, workspace credits가 필요하다.

Business는 pay-as-you-go이며, standard 또는 usage-based Codex seats를 배정할 수 있고, workspace credits로 사용량을 확장할 수 있다.

07Enterprise / Edu / Gov / Health

Enterprise와 Edu는 계약형이다. flexible pricing에서는 fixed rate limit이 없고 usage가 credits에 따라 확장된다. 단, flexible pricing이 없는 Enterprise/Edu는 대부분 기능에서 Plus와 같은 per-seat usage limit을 가진다.

Enterprise / Edu with flexible pricing

credits 기반 확장

Enterprise / Edu without flexible pricing

대부분 기능에서 Plus와 유사한 seat별 한도

Business / Enterprise workspace

workspace credits, admin analytics, spend controls

Business, Edu, Enterprise 플랜에서 flexible pricing을 쓰는 경우에는 추가 workspace credits를 구매해 Codex를 계속 사용할 수 있다.

08API Key 사용 시 비용 구조

API Key로 Codex를 쓰면 ChatGPT 플랜 included usage가 아니라 OpenAI Platform API 과금이 적용된다. API Key 사용 시 CLI, SDK, IDE extension에서 Codex를 쓸 수 있지만 GitHub code review, Slack 같은 cloud-based features는 제공되지 않고, token 사용량에 따라 API pricing으로 과금된다.

CLI

가능

SDK / codex exec

가능

IDE extension

가능

Codex Cloud task

불가

GitHub code review

불가

Slack integration

불가

과금

OpenAI API token 기준

09Codex 크레딧 과금 방식

2026년 4월 2일부터 Codex pricing은 message당 평균 과금이 아니라 API token usage에 맞춘 token-based credit pricing으로 변경되었다. 이 변경은 Plus, Pro, Business, 신규 Enterprise에 적용되었고, 2026년 4월 23일부터 기존 Enterprise, Edu, Health, Gov, ChatGPT for Teachers에도 적용되었다.

과금 계산 단위는 세 가지다.

Input tokens

Codex에 들어가는 프롬프트, 코드, 컨텍스트

Cached input tokens

prompt caching으로 할인 적용되는 입력 토큰

Output tokens

Codex가 생성하는 답변, 코드, reasoning output 포함

공식 rate card는 모델별로 1M input tokens, 1M cached input tokens, 1M output tokens당 credits를 표시한다. 실제 credit 사용량은 각 작업의 input / cached input / output token 비율에 따라 달라진다.

계산식:

총 credits
= input_tokens / 1,000,000 × input_rate
  + cached_input_tokens / 1,000,000 × cached_input_rate
  + output_tokens / 1,000,000 × output_rate

10모델별 Codex 크레딧 rate card

GPT-5.5

Input: 125 credits / 1M, Cached: 12.50 credits / 1M, Output: 750 credits / 1M

GPT-5.4

Input: 62.50 credits / 1M, Cached: 6.250 credits / 1M, Output: 375 credits / 1M

GPT-5.4-Mini

Input: 18.75 credits / 1M, Cached: 1.875 credits / 1M, Output: 113 credits / 1M

GPT-5.3-Codex

Input: 43.75 credits / 1M, Cached: 4.375 credits / 1M, Output: 350 credits / 1M

GPT-5.2

Input: 43.75 credits / 1M, Cached: 4.375 credits / 1M, Output: 350 credits / 1M

GPT-5.3-Codex-Spark

research preview (rate 미확정)

GPT-Image-2.0 image

Input: 200 credits / 1M, Cached: 50 credits / 1M, Output: 750 credits / 1M

GPT-Image-2.0 text

Input: 125 credits / 1M, Cached: 31.25 credits / 1M, Output: 250 credits / 1M

GPT-5.5 Codex 작업 1회가 일반적으로 약 5~45 credits를 소비할 수 있지만, 실제 사용량은 작업 크기와 token mix에 따라 달라진다.

11플랜별 5시간 사용량 한도 · Plus

공식 표의 단위는 5시간 rolling window다. local messages와 cloud tasks는 같은 5시간 window를 공유하며, 추가 weekly limits이 적용될 수 있다.

Plus:

GPT-5.5

Local Messages: 15–80, Cloud Tasks: Not available, Code Reviews: Not available

GPT-5.4

Local Messages: 20–100, Cloud Tasks: Not available, Code Reviews: Not available

GPT-5.4-mini

Local Messages: 60–350, Cloud Tasks: Not available, Code Reviews: Not available

GPT-5.3-Codex

Local Messages: 30–150, Cloud Tasks: 10–60, Code Reviews: 20–50

Plus 표의 한도는 모델, 작업 크기, 로컬/클라우드 실행 여부, 컨텍스트 크기에 따라 실제 메시지 수가 범위 안에서 달라진다.

12플랜별 5시간 사용량 한도 · Pro 5x / 20x

Pro 5x (Plus 대비 5배):

GPT-5.5

Local Messages: 80–400, Cloud Tasks: Not available, Code Reviews: Not available

GPT-5.4

Local Messages: 100–500, Cloud Tasks: Not available, Code Reviews: Not available

GPT-5.4-mini

Local Messages: 300–1750, Cloud Tasks: Not available, Code Reviews: Not available

GPT-5.3-Codex

Local Messages: 150–750, Cloud Tasks: 50–300, Code Reviews: 100–250

Pro 20x (Plus 대비 20배):

GPT-5.5

Local Messages: 300–1600, Cloud Tasks: Not available, Code Reviews: Not available

GPT-5.4

Local Messages: 400–2000, Cloud Tasks: Not available, Code Reviews: Not available

GPT-5.4-mini

Local Messages: 1200–7000, Cloud Tasks: Not available, Code Reviews: Not available

GPT-5.3-Codex

Local Messages: 600–3000, Cloud Tasks: 200–1200, Code Reviews: 400–1000

13Business 한도 · Fast mode

Business: Plus와 같은 범위를 표시한다. 다만 Business는 standard ChatGPT seats, Codex seats, workspace credits, spend controls가 결합될 수 있으므로 실제 비용 관리는 개인 Plus와 다르다.

GPT-5.5

Local Messages: 15–80

GPT-5.4

Local Messages: 20–100

GPT-5.4-mini

Local Messages: 60–350

GPT-5.3-Codex

Local Messages: 30–150, Cloud Tasks: 10–60, Code Reviews: 20–50

Fast mode는 별도 모델이 아니라 지원 모델을 더 빠르게 실행하는 속도 설정이다. 속도는 약 1.5x 증가하며, GPT-5.5는 Standard 대비 2.5x credits, GPT-5.4는 2x credits를 소비한다. API key 사용 시에는 Fast mode credits가 아니라 standard API pricing이 적용된다.

14GPT-5.3-Codex-Spark 비용

GPT-5.3-Codex-Spark는 Pro 사용자용 research preview 모델이다. Spark는 near-instant, real-time coding iteration에 최적화된 text-only research preview 모델로 설명된다.

현재 rate card에서는 Spark의 credit rate가 final이 아니며 research preview로 표시된다. Spark가 Pro 사용자 전용 research preview이고, API launch 시점에는 API에서 사용할 수 없으며, 별도 usage limit이 demand에 따라 조정될 수 있다고 설명된다.

상태

research preview

대상

ChatGPT Pro 사용자

성격

초고속 text-only coding iteration

API

launch 시점 API 미지원

credit rate

final 아님

usage limit

별도 limit, 수요에 따라 조정 가능

15이미지 생성 비용 · 작업별 비용 차이

이미지 생성: Codex 이미지 생성은 일반 Codex usage limit과 같은 general usage limit에 포함된다. 이미지 생성이 유사한 non-image turn보다 평균 3~5배 빠르게 included limits를 소모할 수 있고, 한도 초과 후에는 credits에서 차감된다. Free plan에서는 이미지 생성이 제공되지 않는다.

ChatGPT 플랜 사용

Codex general usage limit 소모

한도 초과 후

credits 차감

Free

이미지 생성 불가

API Key

API pricing 적용

평균 소모

유사 turn 대비 3~5x 빠르게 한도 소모 가능

작업별 비용 차이: 같은 "메시지 1개"라도 비용은 같지 않다. 작은 script나 routine function은 allowance의 일부만 쓸 수 있지만, 큰 codebase, long-running task, extended session처럼 많은 context를 유지해야 하는 작업은 message당 훨씬 더 많이 소모한다.

16비용을 키우는 요소

큰 repository

input context 증가

긴 대화

이전 context 유지

큰 AGENTS.md

매 turn마다 주입되는 지침 증가

많은 MCP 서버

tool definition과 context 증가

높은 reasoning effort

output/reasoning token 증가 가능

Fast mode

credit multiplier 적용

이미지 생성

일반 turn 대비 3~5x 소모 가능

Cloud task

GPT-5.3-Codex 기준 별도 limit

Code review

PR 단위 GPT-5.3-Codex 사용

17숨겨진 토큰 오버헤드

Codex 비용은 사용자가 직접 입력한 문장만으로 결정되지 않는다. 실제로는 다음 항목이 input 또는 output token에 포함될 수 있다.

system instructions

Codex 기본 지침

AGENTS.md

프로젝트 지침

file context

읽은 파일 내용

tool output

shell, test, grep, git 결과

MCP tool definitions

연결된 MCP 서버 도구 설명

reasoning tokens

모델 내부 추론 output token

diff / patch 내용

변경사항 설명과 코드

long session context

긴 세션 유지 비용

AGENTS.md 크기 줄이기, MCP 서버 수 제한, 불필요한 context 제거, 작은 모델 전환을 usage limit 절약 방법으로 제시한다.

18비용 확인 위치

Codex web / app

Codex Settings > Usage Dashboard

Codex CLI

/status

Plus / Pro credits

Codex Settings > Usage > Credits

Business workspace

Workspace settings → Billing

Business auto reload

workspace credit automatic reload

API Key

OpenAI Platform usage / billing dashboard

current limits를 Codex usage dashboard에서 확인할 수 있고, CLI session 중에는 /status로 remaining limits를 볼 수 있다. Business credit에서는 workspace billing에서 credits를 추가하고, automatic reload와 monthly recharge limit을 설정할 수 있다.

19비용 최적화 전략 · 모델·MCP·세션

1. 기본 모델을 무조건 GPT-5.5 xhigh로 고정하지 않는다

gpt-5.5 + xhigh는 중요한 설계, 보안 리뷰, 대형 리팩터링에는 맞지만 단순 반복 작업에는 과하다. GPT-5.5는 GPT-5.4-mini보다 input 기준 약 6.67배, output 기준 약 6.64배 높은 credit rate를 가진다.

아키텍처 / 보안 / 대형 리팩터링

GPT-5.5 high/xhigh

일반 기능 구현

GPT-5.5 medium 또는 GPT-5.4 medium

단순 수정

GPT-5.4-mini low

병렬 subagent

GPT-5.4-mini

GitHub PR review

GPT-5.3-Codex

2. AGENTS.md를 작게 유지한다

AGENTS.md는 매 작업 context에 반복적으로 들어갈 수 있으므로 길수록 input token이 증가한다. 큰 프로젝트에서는 repository 내부에 중첩해 필요한 context만 주입되도록 관리하는 것이 좋다.

3. MCP 서버를 필요할 때만 켠다

MCP 서버를 많이 붙이면 tool definitions와 context가 늘어나 message limit을 더 많이 소비한다. 항상 켜기: GitHub, filesystem처럼 자주 쓰는 MCP. 필요할 때만 켜기: Figma, Sentry, Jira, Linear, DB 관련 MCP.

20비용 최적화 전략 · Fast mode·파일·팀 관리

4. Fast mode를 상시 기본값으로 두지 않는다

Fast mode는 속도는 약 1.5x 빨라지지만, GPT-5.5는 2.5x credits, GPT-5.4는 2x credits를 쓴다. 실시간 페어 코딩은 켜기, 단순 문서 생성은 끄기, 마감 직전 수정은 켜기를 추천한다.

5. 긴 세션은 /compact로 압축한다

대화가 길어질수록 context 비용이 커진다. 작업 단위 분리 → 불필요 파일 context 제거 → /compact → 새 session 순서로 관리한다.

6. 파일을 한꺼번에 많이 붙이지 않는다

큰 파일 여러 개를 무조건 @file로 붙이면 input token이 크게 증가한다. 먼저 관련 파일 후보만 찾아보고, 그 다음 수정해야 할 파일 목록과 이유를 제시한 후 승인하면 그 파일들만 열어서 수정하는 방식을 따른다.

팀 비용 관리 체크리스트

Business/Enterprise에서는 seat 구분 (standard vs Codex), workspace credits 월 예산 사전 충전, auto reload 설정 (minimum/target balance), 기본 모델 정책 (GPT-5.4 기본, 중요 작업만 GPT-5.5), Fast mode 기본 off, MCP 팀 표준만 활성, AGENTS.md app별 분리, Cloud task 장기 작업만, PR review 범위 제한, analytics 정기 확인이 필요하다.

21플랜 선택 가이드

가끔 테스트

Free / Go

개인 개발자, 주 2~3회 집중 사용

Plus (약 30,000원/month)

매일 Codex로 실무 개발

Pro 5x (약 150,000원/month)

병렬 프로젝트, 장시간 agent 작업

Pro 20x (약 300,000원/month)

팀 단위 사용

Business

보안·감사·SSO·대규모 조직

Enterprise / Edu

CI/CD 자동화

API Key 또는 Enterprise access token

개인 기준으로는 Plus가 기본 시작점이고, Codex를 매일 오래 쓰면 Pro 5x, 병렬로 여러 작업을 계속 돌리면 Pro 20x가 맞다. 팀에서는 standard ChatGPT seat와 usage-based Codex seat를 분리해 설계해야 한다.

섹션 12 · 마무리

이 단원에서 기억할 것

Codex 비용은 플랜에 포함된 사용량 한도와 추가 과금 방식으로 관리된다. token-based credit pricing으로 변경되었으며, 같은 작업이라도 context 크기, 모델 선택, 세션 길이에 따라 비용이 크게 달라진다.

중요한 작업은 GPT-5.5, 일반 작업은 GPT-5.4, 단순 반복은 GPT-5.4-mini로 선택하고, AGENTS.md와 MCP를 최소화하며, Fast mode와 긴 세션을 주의깊게 관리할 때 비용을 효율적으로 쓸 수 있다.

다음 단원

13단원. Profiles로 작업 모드 나누기

13. Profiles로 작업 모드 나누기

01profile이 필요한 이유

Codex 작업은 항상 같은 성격이 아닙니다.

단순 수정

빠른 응답, 낮은 비용

중요한 리팩터링

깊은 추론, 안전한 승인

코드 리뷰

읽기 전용, 높은 분석력

CI 자동화

비대화형 실행, 승인 프롬프트 없음

페어 코딩

적당한 속도와 설명

보안 검토

보수적인 권한, 높은 추론

이걸 매번 CLI 옵션으로 길게 입력하면 비효율적입니다.

codex -m gpt-5.5 -c model_reasoning_effort='"xhigh"' -c approval_policy='"on-request"' -c sandbox_mode='"read-only"'

profile을 만들면 이렇게 줄일 수 있습니다.

codex --profile deep

02Codex profile의 정확한 의미

Codex profile은 이름이 붙은 설정 레이어입니다.

--profile profile-name을 넘기면 Codex는 먼저 기본 사용자 설정인 ~/.codex/config.toml을 읽고, 그 위에 ~/.codex/profile-name.config.toml을 덮어씁니다. profile 파일은 기본 설정 전체를 복사하는 파일이 아니라, 기본값과 다른 부분만 적는 override 파일입니다.

예시 기본 설정

# ~/.codex/config.toml

model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

예시 profile 파일

# ~/.codex/deep.config.toml

model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

실행 결과

codex --profile deep

최종 적용:

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
sandbox_mode = "read-only"

03profile 파일 위치와 이름 규칙

profile 파일은 CODEX_HOME 아래에 둡니다.

기본 CODEX_HOME:

~/.codex

profile 파일 형식:

~/.codex/.config.toml

예시:

~/.codex/fast.config.toml
~/.codex/careful.config.toml
~/.codex/deep.config.toml
~/.codex/review.config.toml
~/.codex/ci.config.toml
~/.codex/pair.config.toml

profile 이름에는 문자, 숫자, 하이픈, 언더스코어를 사용할 수 있습니다.

좋은 이름:

fast
deep-review
xhigh
ci
pair_mode

피하는 게 좋은 이름 (공백·특수문자):

deep review
review/prod
ci.prod

04profile 적용 우선순위

profile은 전체 설정 우선순위에서 중간에 있습니다.

1. CLI flags / --config overrides

가장 높음

2. Project config .codex/config.toml

3. Profile file ~/.codex/profile-name.config.toml

4. User config ~/.codex/config.toml

5. System config /etc/codex/config.toml

6. Built-in defaults

가장 낮음

예를 들어 profile에 model = "gpt-5.4-mini"가 있어도, CLI에서 직접 지정하면 CLI 값이 이깁니다.

codex --profile fast --model gpt-5.5

최종 모델은 gpt-5.5입니다.

05더 이상 쓰면 안 되는 legacy profile 방식

예전 방식처럼 ~/.codex/config.toml 안에 profile을 중첩해서 쓰면 안 됩니다.

잘못된 legacy 방식

# 더 이상 권장되지 않음

profile = "deep"

[profiles.deep]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

Codex 0.134.0 이후로는 --profile이 config.toml 안의 [profiles.profile-name]을 읽지 않습니다. profile은 별도 파일인 ~/.codex/profile-name.config.toml로 옮겨야 합니다.

올바른 방식

# ~/.codex/deep.config.toml

model = "gpt-5.5"
model_reasoning_effort = "xhigh"

codex --profile deep

06기본 User config 먼저 만들기

profile을 잘 쓰려면 먼저 기본값을 안정적으로 잡아야 합니다.

# ~/.codex/config.toml

model = "gpt-5.5"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

model_reasoning_summary = "auto"
model_verbosity = "medium"
web_search = "cached"

[features]
shell_snapshot = true

이 기본값은 "평소 작업용"입니다. profile 파일에는 여기서 달라지는 값만 넣으면 됩니다.

07`fast` profile

fast profile은 빠른 반복 작업용입니다.

모델

gpt-5.4-mini

추론

low

권한

workspace write

승인

on-request

용도

단순 수정, 문구 변경, 타입 에러, 반복 작업

# ~/.codex/fast.config.toml

model = "gpt-5.4-mini"
model_reasoning_effort = "low"
plan_mode_reasoning_effort = "medium"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

model_reasoning_summary = "none"
model_verbosity = "low"

실행

codex --profile fast
codex -p fast

08`careful` profile

careful profile은 안전한 일반 실무용입니다.

모델

gpt-5.5

추론

high

권한

workspace write

승인

on-request

용도

일반 기능 구현, 버그 수정, 테스트 작성

# ~/.codex/careful.config.toml

model = "gpt-5.5"
model_reasoning_effort = "high"
plan_mode_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

model_reasoning_summary = "auto"
model_verbosity = "medium"

실행

codex --profile careful

09`xhigh` / `deep` profile

deep profile은 최고 신중 모드입니다. Codex 5.5 xhigh 조합은 이 profile로 두면 깔끔합니다.

# ~/.codex/deep.config.toml

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

model_reasoning_summary = "concise"
model_verbosity = "medium"

실행

codex --profile deep

읽기 전용 deep profile을 따로 만들 수도 있습니다.

# ~/.codex/deep-readonly.config.toml

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex --profile deep-readonly

10`review` profile

review profile은 코드 리뷰 전용입니다.

리뷰는 보통 파일을 수정하지 않고 읽고 판단하는 작업이므로 read-only가 적합합니다.

# ~/.codex/review.config.toml

model = "gpt-5.3-codex"
model_reasoning_effort = "high"
plan_mode_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "read-only"

model_reasoning_summary = "concise"
model_verbosity = "medium"

CLI에서 바로 리뷰

codex --profile review

세션 안에서

/review

리뷰 모델을 항상 고정하고 싶다면 기본 config에 넣을 수 있습니다.

# ~/.codex/config.toml

review_model = "gpt-5.3-codex"

11`ci` profile

ci profile은 비대화형 자동화용입니다.

CI에서는 사용자가 승인 버튼을 누를 수 없기 때문에 approval_policy = "never"를 쓰는 경우가 많습니다. 다만 이 설정은 신중해야 합니다.

# ~/.codex/ci.config.toml

model = "gpt-5.4"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "medium"

approval_policy = "never"
sandbox_mode = "workspace-write"

model_reasoning_summary = "none"
model_verbosity = "low"

실행 예시

codex exec --profile ci "analyze the failing tests and propose a minimal fix"

더 보수적인 CI profile

# ~/.codex/ci-readonly.config.toml

model = "gpt-5.4"
model_reasoning_effort = "medium"

approval_policy = "never"
sandbox_mode = "read-only"

CI에서 피해야 할 조합:

approval_policy = "never"
sandbox_mode = "danger-full-access"

12`pair` profile

pair profile은 페어 코딩용입니다.

목적은 너무 느리지 않으면서, 설명과 코드 변경 품질을 모두 확보하는 것입니다.

# ~/.codex/pair.config.toml

model = "gpt-5.5"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

model_reasoning_summary = "auto"
model_verbosity = "medium"

실행

codex --profile pair

13`auto` profile

auto profile은 로컬에서 어느 정도 자율 실행을 허용하는 작업용입니다.

CI처럼 완전 비대화형은 아니지만, 매번 묻는 것을 줄이고 싶을 때 사용합니다.

# ~/.codex/auto.config.toml

model = "gpt-5.4"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

model_reasoning_summary = "auto"
model_verbosity = "medium"

위 설정은 이름은 auto지만 완전 자동은 아닙니다. 정말 프롬프트 없이 돌리는 자동화는 approval_policy = "never"를 써야 하지만, 그건 CI처럼 격리된 환경에서만 권장됩니다.

더 공격적인 auto profile

# ~/.codex/auto-never.config.toml

model = "gpt-5.4"
model_reasoning_effort = "medium"

approval_policy = "never"
sandbox_mode = "workspace-write"

model_reasoning_summary = "none"
model_verbosity = "low"

사용 전 확인

git status
codex --profile auto-never

14profile 실행 방법

기본 실행:

codex --profile fast
codex --profile careful
codex --profile deep
codex --profile review

짧은 옵션

codex -p fast
codex -p deep

비대화형 실행

codex exec --profile ci "run tests and summarize failures"

모델만 임시로 바꾸기

codex --profile careful --model gpt-5.4

임의 설정 일회성 override

codex --profile deep -c model_reasoning_effort='"high"'

15일회성 override와 profile의 차이

User config

항상 쓰는 기본값. ~/.codex/config.toml

Profile

반복되는 작업 모드. ~/.codex/deep.config.toml

CLI override

이번 한 번만 변경. -c model_reasoning_effort='"high"'

Project config

특정 repo 규칙. .codex/config.toml

예시:

codex --profile deep -c sandbox_mode='"read-only"'

이 경우 profile은 deep이지만, 이번 실행에서는 sandbox_mode만 read-only로 바뀝니다. 우선순위상 CLI override가 profile보다 강합니다.

16permission profiles와 config profiles의 차이

Codex에는 두 종류의 "profile"이라는 말이 나옵니다.

Config profile

Codex 전체 설정 레이어. codex --profile deep

Permission profile

파일시스템·네트워크 권한 정책. default_permissions = "project-edit"

이 장에서 다루는 것은 config profile입니다.

permission profile은 beta 기능이며, 로컬 명령의 파일시스템·네트워크 접근 범위를 더 세밀하게 제어하는 권한 정책입니다. permission profiles는 기존 sandbox_mode와 함께 compose되지 않습니다.

초보자는 14장 Sandbox와 Approval까지는 기존 방식인 sandbox_mode와 approval_policy 중심으로 가는 게 낫습니다.

17초보자용 profile 템플릿

초보자는 profile을 너무 많이 만들 필요 없습니다. 세 개면 충분합니다.

기본 config

# ~/.codex/config.toml

model = "gpt-5.5"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

model_reasoning_summary = "auto"
model_verbosity = "medium"

빠른 작업

# ~/.codex/fast.config.toml

model = "gpt-5.4-mini"
model_reasoning_effort = "low"
plan_mode_reasoning_effort = "medium"

model_reasoning_summary = "none"
model_verbosity = "low"

codex --profile fast

신중한 작업

# ~/.codex/careful.config.toml

model = "gpt-5.5"
model_reasoning_effort = "high"
plan_mode_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

codex --profile careful

최고 신중 작업

# ~/.codex/deep.config.toml

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"

approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_summary = "concise"

codex --profile deep

초보자 규칙

평소 작업       → 기본 config
가벼운 작업     → fast
중요한 작업     → careful
실패 비용 큰 작업 → deep

18실무자용 profile 운영 전략

실무자는 최소 다섯 개로 나누는 게 좋습니다.

fast        = 빠른 반복
careful     = 일반 실무
deep        = 최고 신중
review      = 코드 리뷰
ci          = 자동화

파일 구조

~/.codex/config.toml
~/.codex/fast.config.toml
~/.codex/careful.config.toml
~/.codex/deep.config.toml
~/.codex/review.config.toml
~/.codex/ci.config.toml

19profile 충돌 디버깅

profile이 예상대로 적용되지 않으면 아래 순서대로 확인합니다.

1단계: 파일 이름 확인

ls ~/.codex

정확한 파일명:

deep.config.toml

잘못된 파일명:

deep.toml
profile-deep.config.toml
deep.config

2단계: legacy 방식 제거

~/.codex/config.toml 안에 아래가 남아 있으면 제거합니다.

profile = "deep"

[profiles.deep]
model = "gpt-5.5"

3단계: CLI override 확인

다음처럼 실행하면 profile보다 CLI 모델이 우선합니다.

codex --profile fast --model gpt-5.5

4단계: project config 확인

현재 repo에 project config가 있는지 확인합니다.

find . -path "*/.codex/config.toml" -print

project config는 profile보다 우선합니다.

5단계: project trust 확인

project config가 적용되지 않는다면 trusted project인지 확인합니다. Codex는 보안상 untrusted project의 config와 project-local hooks를 무시합니다.

6단계: project config에 넣으면 안 되는 key 확인

project-local .codex/config.toml에는 profile, profiles, provider, notification, telemetry 관련 key 등이 무시됩니다. profile 선택은 CLI의 --profile profile-name과 ~/.codex/profile-name.config.toml으로 해야 합니다.

잘못된 project config

# /.codex/config.toml

profile = "deep"

올바른 실행

codex --profile deep

섹션 13 · 마무리

profile은 작업 모드를 저장하는 별도 파일

Codex profile은 단순한 옵션 모음이 아닙니다. 반복되는 작업 패턴마다 최적의 설정을 미리 저장해두고, 한 줄의 명령으로 불러오는 방식입니다.

평소에 쓰는 기본값은 ~/.codex/config.toml, 작업마다 달라지는 설정은 별도 profile 파일로 관리하세요.

초보자는 fast, careful, deep 세 개만으로 시작해도 충분합니다. 실무에서는 review, ci, pair를 추가해 더 섬세하게 대응할 수 있습니다.

다음 단원

14단원. Sandbox와 Approval 시스템

14. Sandbox와 Approval 시스템

01Sandbox와 Approval의 차이

Sandbox와 Approval은 서로 다른 보안 장치입니다.

Sandbox

Codex가 기술적으로 할 수 있는 범위를 제한

Approval

Codex가 그 범위를 넘으려 할 때 사용자에게 물어볼지 결정

Sandbox는 기술적 경계, Approval은 확인 절차입니다.

예시:

sandbox_mode = "workspace-write"
approval_policy = "on-request"

이 설정은 현재 workspace 안에서는 읽기, 수정, 일반 명령 실행 가능하고, workspace 밖 수정이나 네트워크 접근은 승인 요청을 의미합니다.

02Codex 보안 모델 전체 구조

Codex의 로컬 실행 보안은 크게 세 겹으로 이루어져 있습니다.

Sandbox

파일시스템, 네트워크, 명령 실행 범위 제한

Approval

경계 밖 작업을 실행하기 전 확인

Rules / Permission profiles

특정 명령·경로·네트워크를 더 세밀하게 제어

Codex CLI와 IDE extension은 OS 수준 메커니즘으로 sandbox policy를 강제합니다. 기본값은 네트워크 접근 없음, 쓰기 권한은 active workspace 안으로 제한됩니다.

03sandbox_mode 핵심 값

config.toml에서 sandbox는 sandbox_mode로 설정합니다.

sandbox_mode = "workspace-write"

지원되는 값은 세 가지입니다.

read-only

파일을 읽을 수 있지만 수정과 명령 실행은 승인 필요

workspace-write

workspace 안에서 읽기·수정·일반 명령 실행 가능

danger-full-access

sandbox 제한 제거

04read-only 모드

read-only는 가장 보수적인 모드입니다. Codex는 파일을 살펴보고 설명할 수 있지만, 파일을 수정하거나 명령을 실행하려면 approval이 필요합니다.

sandbox_mode = "read-only"
approval_policy = "on-request"

추천 상황:

처음 보는 코드베이스 분석

수정 없이 구조 파악

보안 리뷰

실수로 파일 변경 방지

PR 리뷰

읽고 판단하는 작업 중심

중요한 운영 repo 확인

변경 리스크 최소화

05read-only 모드 · 설정 예시

실행 예시:

codex --sandbox read-only --ask-for-approval on-request

Profile 예시:

# ~/.codex/review.config.toml

model = "gpt-5.5"
model_reasoning_effort = "high"

sandbox_mode = "read-only"
approval_policy = "on-request"

06workspace-write 모드

workspace-write는 로컬 개발에서 가장 많이 쓰는 기본 모드입니다. Codex는 현재 workspace 안의 파일을 읽고 수정하고, routine local command를 실행할 수 있습니다. workspace 밖 수정이나 네트워크 접근은 승인 요청 대상입니다.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

추천 상황:

일반 기능 구현

파일 수정 필요

버그 수정

테스트 실행과 수정 반복

리팩터링

여러 파일 수정 가능

문서 업데이트

workspace 안 파일 수정

07workspace-write 모드 · 설정 예시

초보자 기본 추천:

# ~/.codex/config.toml

sandbox_mode = "workspace-write"
approval_policy = "on-request"

CLI 실행:

codex --sandbox workspace-write --ask-for-approval on-request

08danger-full-access 모드

danger-full-access는 sandbox 제한을 제거합니다. filesystem과 network boundary를 제거하며, Codex에게 full access를 주고 싶을 때만 사용해야 합니다.

sandbox_mode = "danger-full-access"

가장 위험한 조합:

sandbox_mode = "danger-full-access"
approval_policy = "never"

이 조합은 샌드박스 없음, 승인 요청 없음, 전체 접근 허용을 의미합니다.

사용해도 되는 경우:

일회용 VM

VM 자체를 버릴 수 있어야 함

Docker 격리 환경

host volume과 secret이 제한되어야 함

CI 임시 runner

권한과 네트워크가 외부에서 제한되어야 함

테스트 전용 sandbox machine

민감 파일·계정·토큰이 없어야 함

일반 로컬 개발 머신에서는 기본값으로 쓰면 안 됩니다.

09approval_policy 핵심 값

Approval policy는 Codex가 언제 멈추고 사용자에게 물어볼지를 정합니다.

approval_policy = "on-request"

지원되는 값:

untrusted

trusted set 밖 명령은 승인 요청

on-request

sandbox 안에서는 진행, 경계 밖은 승인 요청

never

승인 요청 없이 주어진 sandbox 안에서만 최선 실행

granular

승인 종류별로 surface 여부를 세밀하게 제어

10untrusted 정책

untrusted는 보수적인 승인 정책입니다. Codex가 trusted set에 없는 명령을 실행하기 전에 물어봅니다. known-safe read operation만 자동 실행하고, 상태를 바꾸거나 외부 실행 경로를 유발할 수 있는 명령은 approval이 필요합니다.

sandbox_mode = "workspace-write"
approval_policy = "untrusted"

추천 상황:

낯선 repo

script가 무엇을 할지 모름

보안 민감 프로젝트

명령 실행을 보수적으로 제한

외부 기여 코드

package script 위험 가능

운영 관련 repo

실수 비용 큼

11on-request 정책

on-request는 가장 실용적인 기본값입니다. Codex가 sandbox 안에서는 기본적으로 작업하고, sandbox 밖으로 나가야 할 때 물어봅니다. Default permissions도 workspace-write + on-request + user reviewer 조합입니다.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

추천 상황:

일반 개발

편의성과 안전성 균형

기능 구현

workspace 안 파일 수정 가능

테스트 실행

일반 명령 자동 실행 가능

초보자 기본값

위험 작업은 멈추고 물어봄

12on-request 정책 · 기본 추천

기본 추천 설정:

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "user"

13never 정책

never는 approval prompt를 띄우지 않는 정책입니다. 중요한 점은 never가 sandbox를 없애는 뜻은 아니라는 것입니다. Codex는 설정된 sandbox 제약 안에서만 최선을 다합니다.

안전한 예:

sandbox_mode = "read-only"
approval_policy = "never"

의미: 읽기만 가능, 승인 요청 없음, 수정이나 경계 밖 작업은 하지 못함

CI용 예:

sandbox_mode = "workspace-write"
approval_policy = "never"

의미: workspace 안에서는 수정 가능, 승인 요청 없음, workspace 밖 작업은 실패하거나 제한됨

위험한 예:

sandbox_mode = "danger-full-access"
approval_policy = "never"

이 조합은 일반 로컬 머신에서 쓰면 안 됩니다.

14Granular approval policy

Granular approval은 approval 종류별로 prompt를 허용하거나 자동 거부하는 방식입니다.

approval_policy = { granular = {
  sandbox_approval = true,
  rules = true,
  mcp_elicitations = true,
  request_permissions = false,
  skill_approval = false
} }

제어 가능한 항목:

sandbox_approval

sandbox escalation 승인 prompt 허용

rules

rules의 prompt 결정으로 생기는 승인 허용

mcp_elicitations

MCP elicitation prompt 허용

request_permissions

request_permissions tool prompt 허용

skill_approval

skill script 승인 prompt 허용

초보자는 처음부터 granular를 쓰지 않아도 됩니다. 대부분은 approval_policy = "on-request"로 충분합니다.

15approvals_reviewer: user와 auto_review

Approval prompt를 누가 검토할지도 설정할 수 있습니다.

approvals_reviewer = "user"

지원되는 값:

user

사용자가 직접 검토

auto_review

reviewer subagent를 사용

기본값:

approval_policy = "on-request"
approvals_reviewer = "user"

auto-review 예시:

approval_policy = "on-request"
approvals_reviewer = "auto_review"
sandbox_mode = "workspace-write"

중요한 점은 auto-review는 sandbox boundary를 바꾸는 것이 아니라 approval request를 검토하는 reviewer만 바꾸는 것입니다.

16Network access 설정

workspace-write 모드에서는 기본적으로 네트워크 접근이 꺼져 있습니다. 네트워크를 허용하려면 다음 설정을 추가합니다.

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

17writable_roots로 쓰기 범위 확장하기

workspace-write는 기본적으로 현재 workspace 안에서만 쓰기를 허용합니다. 다른 디렉터리에도 쓰기가 필요하면 writable_roots를 추가합니다.

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = [
  "/Users/me/.pyenv/shims",
  "/Users/me/dev/shared-package"
]

좋은 사용 예:

monorepo 밖 shared package 수정

shared package 경로

local tool shim 필요

.pyenv/shims

generated output 저장

특정 output 폴더

나쁜 사용 예:

[sandbox_workspace_write]
writable_roots = ["/"]

이건 사실상 sandbox 의미를 크게 약화시킵니다.

18/permissions로 세션 중 권한 바꾸기

Codex CLI에서는 세션 중 /permissions로 권한 모드를 바꿀 수 있습니다.

/permissions

사용 흐름:

read-only로 코드 분석
계획 확인
/permissions로 workspace-write 전환
파일 수정
diff 확인

초보자에게 좋은 패턴:

처음 보는 repo → read-only
수정해도 되겠다고 판단 → workspace-write
매우 위험한 작업 → 계속 read-only 유지

19Rules로 특정 명령 허용·확인·차단하기

Rules는 특정 command prefix를 기준으로 허용, 확인, 차단을 정하는 기능입니다.

allow

prompt 없이 허용

prompt

실행 전 확인

forbidden

실행 차단

사용 예시:

git commit은 직접 하고 싶다 → forbidden
rm -rf는 무조건 막고 싶다 → forbidden
npm install은 매번 확인하고 싶다 → prompt

권한을 넓게 풀기보다 rules로 command prefix를 allow, prompt, forbid하는 편이 더 적합합니다.

20Permission profiles와 기존 sandbox 방식의 차이

Codex에는 beta permission profiles도 있습니다.

기존 방식:

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

permission profile 방식:

default_permissions = ":workspace"

주의: default_permissions와 sandbox_mode나 [sandbox_workspace_write]를 함께 쓰면 안 됩니다. 둘 중 하나만 사용합니다.

초보자 기준: 14장에서는 sandbox_mode + approval_policy 방식만 익히면 충분합니다. permission profiles는 고급/베타 권한 모델로 따로 다룹니다.

21자주 쓰는 안전 조합 ① · ②

1. 초보자 기본 조합

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "user"

효과: workspace 안에서는 작업 가능, workspace 밖 수정/네트워크 접근은 승인 필요

2. 읽기 전용 리뷰 조합

sandbox_mode = "read-only"
approval_policy = "on-request"

효과: 분석은 가능, 수정이나 명령 실행은 승인 필요

추천: 코드 리뷰, 보안 분석, 처음 보는 repo, 운영 코드 확인

22자주 쓰는 안전 조합 ③ · ④

3. 조용한 읽기 전용 CI

sandbox_mode = "read-only"
approval_policy = "never"

효과: 읽기만 가능, approval prompt 없음, 수정 불가

4. 자동 수정 CI

sandbox_mode = "workspace-write"
approval_policy = "never"

효과: workspace 안 수정 가능, approval prompt 없음, workspace 밖 작업 제한

추천 조건: CI runner가 격리, secret 노출 제한, 변경사항은 PR diff로 검토

23자주 쓰는 안전 조합 ⑤

5. 보수적 실무 조합

sandbox_mode = "workspace-write"
approval_policy = "untrusted"

효과: 파일 수정은 가능, untrusted command는 승인 필요

24위험한 조합

위험 1. full access + never

sandbox_mode = "danger-full-access"
approval_policy = "never"

위험: 파일시스템 제한 없음, 네트워크 제한 없음, approval 없음

위험 2. network access 상시 허용

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

위험: 외부 문서, package script, API response를 통한 prompt injection 가능성 증가

25위험한 조합 · 계속

위험 3. writable root를 너무 넓게 설정

[sandbox_workspace_write]
writable_roots = ["/"]

위험: workspace-write의 보호 의미가 거의 사라짐

대신 필요한 폴더만 좁게 추가합니다:

[sandbox_workspace_write]
writable_roots = ["/Users/me/dev/shared-package"]

위험 4. CI에서 host secret이 많은 상태로 full access

sandbox_mode = "danger-full-access"
approval_policy = "never"

위험: CI secret, deploy key, cloud token, package token 노출 가능성 증가

CI에서는 workspace-write 또는 read-only를 기본으로 두고, 네트워크와 secret 접근을 runner 레벨에서 제한해야 합니다.

26초보자 추천 설정

초보자는 아래 설정으로 시작합니다.

# ~/.codex/config.toml

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "user"

[sandbox_workspace_write]
network_access = false

설정의 의미:

workspace-write

현재 프로젝트 안 파일 수정 가능

on-request

위험하거나 경계 밖 작업은 물어봄

user

승인은 사용자가 직접 판단

network_access = false

shell command의 외부 네트워크 차단

처음 보는 repo에서는 read-only profile을 쓰습니다:

# ~/.codex/readonly.config.toml

sandbox_mode = "read-only"
approval_policy = "on-request"
approvals_reviewer = "user"

실행: codex --profile readonly

27실무자 추천 profile

기본 개발용

# ~/.codex/dev.config.toml

model = "gpt-5.5"
model_reasoning_effort = "medium"

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "user"

[sandbox_workspace_write]
network_access = false

실행: codex --profile dev

깊은 분석용

# ~/.codex/deep-readonly.config.toml

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"

sandbox_mode = "read-only"
approval_policy = "on-request"
approvals_reviewer = "user"

실행: codex --profile deep-readonly

28실무자 추천 profile · 계속

신중한 수정용

# ~/.codex/deep-edit.config.toml

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "user"

[sandbox_workspace_write]
network_access = false

실행: codex --profile deep-edit

네트워크 허용 작업용

# ~/.codex/net.config.toml

model = "gpt-5.5"
model_reasoning_effort = "high"

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "user"

[sandbox_workspace_write]
network_access = true

실행: codex --profile net

이 profile은 상시 기본값으로 두지 않습니다.

29CI/CD에서의 sandbox와 approval

CI/CD에서는 사람이 approval을 누를 수 없으므로 approval_policy = "never"를 쓰는 경우가 많습니다. 다만 sandbox는 유지해야 합니다.

읽기 전용 CI:

# ~/.codex/ci-readonly.config.toml

sandbox_mode = "read-only"
approval_policy = "never"

자동 수정 CI:

# ~/.codex/ci-edit.config.toml

sandbox_mode = "workspace-write"
approval_policy = "never"

[sandbox_workspace_write]
network_access = false

실행:

codex exec --profile ci-readonly "review this diff and report risks"
codex exec --profile ci-edit "fix lint errors only"

피해야 할 CI 설정:

sandbox_mode = "danger-full-access"
approval_policy = "never"

이 조합은 CI runner가 강하게 격리되어 있고, secret과 네트워크가 외부에서 제한되어 있을 때만 예외적으로 검토합니다.

30문제 해결 체크리스트

1. Codex가 파일을 수정하지 못한다

확인: sandbox_mode = "read-only"

해결: sandbox_mode = "workspace-write" + approval_policy = "on-request"

2. workspace 밖 파일을 수정하지 못한다

확인: sandbox_mode = "workspace-write"

해결: [sandbox_workspace_write]에 writable_roots 추가

3. npm install이나 pip install이 실패한다

확인: network_access = false

해결: network_access = true (필요할 때만 켜기)

4. approval prompt가 아예 안 뜬다

확인: approval_policy = "never"

해결: approval_policy = "on-request"

5. approval이 너무 자주 뜬다

확인: sandbox_mode = "read-only" + approval_policy = "untrusted"

해결: sandbox_mode = "workspace-write" + approval_policy = "on-request"

6. 프로젝트 설정이 적용되지 않는다

확인할 것: 프로젝트가 trusted 상태인가? .codex/config.toml이 현재 repo 안에 있는가? CLI override가 더 높은 우선순위로 덮고 있지 않은가?

7. .git이나 .codex가 수정되지 않는다

추천: git commit은 직접 실행, Codex에는 diff 생성과 테스트까지만 맡기기

섹션 14 · 마무리

14장 핵심 정리

Sandbox는 무엇을 할 수 있는지 정합니다.

sandbox_mode = "read-only"
sandbox_mode = "workspace-write"
sandbox_mode = "danger-full-access"

Approval은 언제 물어볼지 정합니다.

approval_policy = "untrusted"
approval_policy = "on-request"
approval_policy = "never"

기억할 기준:

read-only = 분석용 / workspace-write = 일반 개발용 / danger-full-access = 외부에서 격리된 환경 전용 / untrusted = 보수적 확인 / on-request = 기본 추천 / never = CI/자동화 전용

다음 단원

15단원. AGENTS.md 사용법

15. AGENTS.md 사용법

01AGENTS.md란 무엇인가

AGENTS.md는 Codex에게 프로젝트 작업 규칙을 알려주는 Markdown 파일입니다.

사람에게 README.md가 있다면, AI 코딩 에이전트에게는 AGENTS.md가 있습니다.

README.md

사람을 위한 프로젝트 설명

AGENTS.md

AI 에이전트를 위한 작업 지침

공식 Codex 문서에 따르면 AGENTS.md는 저장소와 함께 이동하는 durable project guidance이며, Codex가 작업을 시작하기 전에 적용됩니다.

02AGENTS.md가 필요한 이유

AGENTS.md는 반복해서 말해야 하는 지침을 저장합니다.

매번 이렇게 말하는 대신:

이 프로젝트는 pnpm을 써.
테스트는 pnpm test로 돌려.
API 변경하면 docs도 업데이트해.
.env 파일은 절대 읽거나 수정하지 마.
PR 전에는 lint와 typecheck를 확인해.

저장소 루트에 한 번만 남겨둘 수 있습니다. 공식 Best practices 문서는 좋은 AGENTS.md에 repo layout, 실행 방법, build/test/lint 명령, engineering convention, PR expectation, constraints, do-not rules, 검증 기준이 들어가야 한다고 설명합니다.

03Codex가 AGENTS.md를 읽는 방식

Codex는 실행 시작 시 instruction chain을 만듭니다. 발견 순서는 다음과 같습니다.

범위

읽는 파일

Global scope

${CODEX_HOME}/AGENTS.override.md 또는 ${CODEX_HOME}/AGENTS.md

Project scope

프로젝트 루트부터 현재 작업 디렉터리까지의 AGENTS.override.md, AGENTS.md, fallback 파일

Merge order

루트에서 현재 디렉터리 방향으로 합침

우선순위

현재 디렉터리에 가까운 파일이 더 나중에 들어가므로 더 강함

기본 CODEX_HOME은 ~/.codex입니다. Codex는 ~/.codex/AGENTS.md → repo/AGENTS.md → repo/apps/web/AGENTS.md 순서로 지침을 합칩니다.

04Global AGENTS.md

Global AGENTS.md는 모든 프로젝트에 적용되는 개인 기본 지침입니다.

위치: ~/.codex/AGENTS.md

예시:

# ~/.codex/AGENTS.md

## Working agreements

- 답변은 한국어로 작성한다.
- 코드 변경 전에는 간단한 계획을 먼저 제시한다.
- 중요한 파일 삭제나 대규모 리팩터링 전에는 반드시 확인을 요청한다.
- 새 production dependency를 추가하기 전에는 이유와 대안을 설명한다.

Global 파일에 넣기 좋은 것: 답변 언어, 설명 스타일, 승인 선호, 개인 습관, 선호 패키지 매니저

Global 파일에 넣지 않는 게 좋은 것: 특정 repo의 테스트 명령, 특정 팀의 코딩 컨벤션, 특정 서비스의 배포 절차

05Project AGENTS.md

Project AGENTS.md는 저장소 루트에 두는 팀 공통 지침입니다.

위치: repo-root/AGENTS.md

예시 구성:

Project overview — 프로젝트 목적과 기술 스택
Commands — 설치, 개발 서버, lint, 테스트, 빌드 명령
Repository rules — 파일 배치, API 구조, 문서 업데이트 기준
Safety — 환경 변수, API 키, 배포 명령 보호

공식 문서는 repository-level AGENTS.md가 프로젝트 규칙을 Codex에게 알려주면서 global defaults를 상속한다고 설명합니다.

06Nested AGENTS.md와 가까운 지침 우선 원칙

대형 저장소나 monorepo에서는 루트 하나로 끝내면 안 됩니다.

예시 구조:

repo/
  AGENTS.md
  apps/
    web/
      AGENTS.md
    admin/
      AGENTS.md
  services/
    payments/
      AGENTS.md

Codex가 services/payments에서 시작하면 이 순서로 지침을 읽습니다: ~/.codex/AGENTS.md → repo/AGENTS.md → repo/services/payments/AGENTS.md. 현재 디렉터리에 가까운 파일이 더 나중에 합쳐져 앞선 지침을 override합니다.

07AGENTS.override.md

AGENTS.override.md는 같은 디렉터리에 있는 일반 AGENTS.md보다 우선합니다.

같은 디렉터리에 둘 다 있으면: Codex는 AGENTS.override.md를 사용하고 AGENTS.md는 사용하지 않습니다.

상황

사용법

임시 실험

AGENTS.override.md로 실험 규칙 추가

특정 하위 프로젝트 예외

nested override 사용

개인 임시 전체 override

~/.codex/AGENTS.override.md

팀 규칙 일시 중단

override에 명시

주의: AGENTS.override.md는 강한 파일입니다. 임시로 만들었다면 작업 후 제거해야 합니다.

08fallback 파일명 설정하기

이미 팀에서 다른 지침 파일을 쓰고 있다면 Codex가 그 파일도 instruction file로 읽게 할 수 있습니다.

설정 예시:

# ~/.codex/config.toml

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

이렇게 설정하면 Codex는 각 디렉터리에서 다음 순서로 찾습니다: AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md

09project_doc_max_bytes와 지침 크기 제한

Codex는 instruction chain의 합산 크기가 project_doc_max_bytes에 도달하면 더 이상 파일을 추가하지 않습니다. 기본값은 32 KiB입니다.

설정 예시:

# ~/.codex/config.toml

project_doc_max_bytes = 65536

하지만 무조건 크게 늘리는 것이 정답은 아닙니다.

문제

설명

context 증가

매 작업마다 더 많은 지침이 들어감

비용 증가

input token 증가

충돌 증가

오래된 규칙과 새 규칙이 섞임

지침 무시 가능성

너무 길면 핵심 규칙이 묻힘

공식 Best practices 문서도 main file은 간결하게 유지하고, planning, code review, architecture 같은 task-specific markdown으로 나누라고 권장합니다.

10/init으로 초안 만들기

Codex CLI에서는 /init으로 현재 디렉터리에 시작용 AGENTS.md를 만들 수 있습니다.

/init

공식 Best practices 문서는 /init slash command가 현재 디렉터리에 starter AGENTS.md를 scaffold하는 quick-start 명령이며, 생성 결과를 팀의 실제 build, test, review, ship 방식에 맞게 편집해야 한다고 설명합니다.

추천 흐름:

repo root에서 Codex 실행
/init 실행
생성된 AGENTS.md 확인
실제 명령어와 규칙으로 수정
팀 리뷰 후 commit

11기본 템플릿

가장 무난한 기본 템플릿의 구성:

Project overview

프로젝트의 목적, 주요 기술 스택, 중요한 디렉터리

Commands

설치, 개발 서버, 테스트, lint, typecheck, 빌드

Repository layout

주요 디렉터리와 역할

Coding conventions

코드 스타일, 문서 업데이트, dependency 정책

Testing rules

테스트 추가, 범위, 최종 검증

Safety rules

환경 변수, credential, deployment 보호

PR expectations

변경 요약, 테스트 결과, 리스크 명시

12코딩 스타일 지시하기

코딩 스타일은 짧고 구체적으로 적습니다.

좋은 예:

## Coding conventions

- TypeScript에서는 any를 피하고, 필요한 경우 이유를 주석으로 남긴다.
- React component는 named export를 사용한다.
- API route handler에는 business logic을 직접 넣지 말고 src/domain으로 분리한다.
- CSS는 Tailwind utility를 우선 사용하고, 반복 패턴은 component로 추출한다.
- 기존 파일의 스타일을 우선 따른다.

나쁜 예: "좋은 코드를 작성한다", "깔끔하게 만든다", "유지보수 가능하게 한다"는 너무 추상적입니다. Codex가 실제로 판단할 수 있는 규칙으로 바꿔야 합니다.

13테스트·빌드·린트 명령 지시하기

Codex가 작업 후 검증하려면 정확한 명령어가 필요합니다.

좋은 예:

## Commands

- Install dependencies: pnpm install
- Run unit tests: pnpm test
- Run a single test file: pnpm test -- path/to/file.test.ts
- Run lint: pnpm lint
- Run type checks: pnpm typecheck
- Build production bundle: pnpm build

monorepo 예:

- Web app dev: pnpm --filter web dev
- Web app tests: pnpm --filter web test
- API tests: pnpm --filter api test
- All checks: pnpm turbo run lint test typecheck

14금지 작업 명시하기

Codex가 하면 안 되는 작업은 명시적으로 적습니다.

기본 금지 목록:

## Do not

- Do not run deployment commands.
- Do not rotate, print, or modify secrets.
- Do not edit .env* files.
- Do not rewrite migration history.
- Do not delete user data or test fixtures unless explicitly requested.
- Do not introduce new production dependencies without explaining why.
- Do not make broad formatting-only changes in unrelated files.

또는 더 강하게:

## High-risk actions

Ask for explicit confirmation before:
- Running database migrations
- Deleting files
- Changing authentication or authorization logic
- Modifying payment, billing, or money movement code
- Adding dependencies
- Changing CI/CD configuration

AGENTS.md는 행동 지침이고, 기술적으로 명령을 막는 장치는 아닙니다.

15보안·시크릿·데이터 관련 지침

보안 규칙은 반드시 구체적으로 적습니다.

예시:

## Security and secrets

- Do not read, print, copy, or modify .env, .env.*, private keys, certificates, or credential files.
- If a task requires secrets, stop and ask the user.
- Never paste tokens, API keys, cookies, or credentials into logs or responses.
- Treat production data as sensitive.
- Do not make network calls to production services unless explicitly requested.

데이터 프로젝트 예:

- Do not modify files in data/raw/.
- Write processed data to data/processed/.
- Write reports to reports/.
- Do not include personally identifiable information in generated examples.

16PR 리뷰 지침 작성하기

팀에서 Codex를 리뷰어로 쓴다면 review 기준을 따로 적습니다.

간단한 방식:

## Review expectations

When reviewing code:
- Focus on correctness, security, test coverage, and maintainability.
- Prefer actionable findings over style opinions.
- Include file paths and concrete examples.
- Mention missing tests when behavior changes.
- Do not approve changes that fail typecheck or tests.

별도 파일로 분리하는 방식: AGENTS.md에 "Follow docs/code_review.md when reviewing pull requests"라고 참조하면, Codex가 리뷰 중 해당 지침을 따를 수 있습니다.

17monorepo에서 AGENTS.md 나누기

monorepo에서는 루트 파일을 작게 유지하고, 세부 규칙은 하위 폴더에 둡니다.

권장 구조:

repo/
  AGENTS.md
  apps/
    web/
      AGENTS.md
    mobile/
      AGENTS.md
  services/
    api/
      AGENTS.md
    payments/
      AGENTS.md
  packages/
    ui/
      AGENTS.md

루트 파일은 repository-wide rules와 layout을 담고, 각 하위 폴더는 해당 모듈의 구체적 규칙을 담습니다. Codex는 가장 가까운 파일이 우선되어 subproject별 맞춤 지침을 제공할 수 있습니다.

18여러 AI 코딩 도구와 함께 쓰기

AGENTS.md는 Codex만의 폐쇄 형식이 아니라 여러 AI 코딩 도구가 함께 쓰는 open format입니다.

기존 파일이 있다면 이렇게 처리할 수 있습니다:

기존 파일

처리 방식

CLAUDE.md

핵심 규칙을 AGENTS.md로 이동

.cursorrules

프로젝트 규칙을 AGENTS.md로 통합

.github/copilot-instructions.md

공통 규칙은 AGENTS.md, GitHub 전용 규칙은 유지

CONTRIBUTING.md

사람용 지침은 유지, 에이전트 실행 규칙은 AGENTS.md

README.md

소개와 quickstart는 유지, AI 작업 규칙은 AGENTS.md

마이그레이션: 기존 파일을 AGENTS.md로 rename하고 backward compatibility를 위해 symbolic link를 만들 수 있습니다.

19AGENTS.md, config.toml, Rules, Skills의 차이

헷갈리기 쉬운 네 가지를 구분해야 합니다.

항목

역할

AGENTS.md

프로젝트 작업 지침 (테스트 명령, 코드 스타일, 금지 작업)

config.toml

Codex 실행 설정 (모델, reasoning, sandbox, approval, MCP)

Rules

명령 허용·확인·차단 (rm -rf 금지, npm install 확인)

Skills

반복 워크플로 패키지 (PR 리뷰 skill, 테스트 작성 skill)

구분 기준: 무엇을 따라야 하는가? → AGENTS.md | 어떤 모델/권한으로 실행할까? → config.toml | 어떤 명령을 막을까? → Rules | 반복 업무를 어떻게 패키징할까? → Skills

20좋은 AGENTS.md 예시

좋은 AGENTS.md의 구조:

## Project overview
TypeScript monorepo using pnpm workspaces...

## Commands
- Install: pnpm install
- Tests: pnpm test (또는 pnpm --filter web test)

## Coding conventions
- Use TypeScript strict types
- Keep business logic out of route handlers

## Safety rules
- Do not read or modify .env* files

## PR expectations
- Summarize changed files, mention tests run, list risks

이 예시가 좋은 이유: 명령이 실제 실행 가능하다 | 금지 작업이 명확하다 | 테스트 기준이 있다 | 파일 구조를 알려준다 | 추상적 표현보다 행동 규칙이 많다

21나쁜 AGENTS.md 예시

나쁜 예:

## Rules
- Be smart.
- Write clean code.
- Make it scalable.
- Use best practices.
- Always improve everything.
- Never make mistakes.

문제

설명

너무 추상적

실제 판단 기준이 없음

검증 명령 없음

Codex가 무엇을 실행해야 할지 모름

범위 제한 없음

관련 없는 리팩터링 유발 가능

금지 작업 없음

위험한 작업을 막지 못함

더 나쁜 패턴: "항상 리팩터링하라", "보이는 모든 걸 고쳐라", "필요한 모든 명령을 실행해라"처럼 무한정 권장하면 불필요한 대규모 변경과 dependency 변경을 유발합니다.

22유지보수 방법

AGENTS.md는 한 번 만들고 끝나는 파일이 아닙니다. 업데이트해야 하는 상황과 해야 할 일:

상황

해야 할 일

Codex가 같은 실수를 반복

규칙 추가

테스트 명령이 바뀜

Commands 수정

새 패키지 추가

Repository layout 수정

PR 피드백이 반복됨

Review expectations 추가

보안 사고 가능성 발견

Safety rules 강화

파일이 너무 길어짐

하위 AGENTS.md 또는 별도 문서로 분리

실무 유지보수 루틴: Codex가 같은 실수를 두 번 한다 → 원인을 짧은 규칙으로 만든다 → AGENTS.md에 추가한다 → 다음 작업에서 효과를 본다 → 너무 길어지면 하위 문서로 분리한다

23문제 해결 체크리스트

1. Codex가 AGENTS.md를 안 읽는 것 같다

codex --ask-for-approval never "Summarize the current instructions."

2. 잘못된 지침이 적용된다

확인: ~/.codex/AGENTS.override.md, repo/AGENTS.override.md, 하위 디렉터리의 override. 필요하면 rename 또는 remove.

3. 하위 폴더 지침이 적용되지 않는다

codex --cd services/payments "Show which instruction files are active."

4. fallback 파일이 무시된다

설정 확인: project_doc_fallback_filenames에 등록, 새 세션 시작.

5. 지침이 잘린다

해결: project_doc_max_bytes 늘리기 또는 루트 파일 단축, 하위 폴더별 분리.

섹션 15 · 마무리

이 단원에서 기억할 것

AGENTS.md는 Codex에게 프로젝트별 작업 규칙을 알려주는 파일입니다.

기본 위치: ~/.codex/AGENTS.md (개인) → repo/AGENTS.md (팀) → repo/subdir/AGENTS.md (하위)

기본 템플릿 핵심 섹션: Project overview, Commands, Repository layout, Coding conventions, Testing rules, Safety rules, PR expectations

짧게, 구체적으로, 실행 가능하게, 반복 실수 중심으로 관리한다.

AGENTS.md에 넣을 것: 프로젝트 구조, 실행 명령, 테스트·린트·빌드 명령, 코딩 컨벤션, 금지 작업, 보안 규칙, PR 리뷰 기준

AGENTS.md에 넣지 말 것: 너무 추상적인 말, 오래된 명령어, 모든 repo에 맞지 않는 개인 취향, 비밀값이나 credential, 기술적으로 차단해야 할 보안 정책

다음 단원

16단원. Hooks

16. Hooks

01Hooks란 무엇인가

Hooks는 Codex 실행 흐름 중 특정 시점에 사용자 스크립트를 자동으로 실행하는 확장 시스템입니다.

공식 문서는 hooks를 Codex lifecycle 안에 deterministic script를 주입하는 확장 프레임워크로 설명합니다. 예를 들어 prompt에 API key가 붙었는지 검사하거나, 대화 내용을 로깅하거나, turn 종료 시 검증 스크립트를 실행하거나, 특정 디렉터리에서 추가 context를 주입할 수 있습니다.

Codex가 무언가 하려는 순간
→ hook이 실행됨
→ 허용, 차단, 경고, 추가 context 주입 가능

AGENTS.md가 "따라야 할 지침"이라면, hooks는 "정해진 시점에 실행되는 자동 검사기"입니다.

02Hooks가 필요한 상황

Hooks는 아래 상황에 적합합니다.

위험한 명령 차단

rm -rf, git push, deploy 같은 명령을 자동 차단

secret 유출 방지

prompt나 command에 API key가 들어갔는지 검사

팀 정책 강제

특정 파일, 디렉터리, 명령어 사용 제한

자동 검증

작업 종료 시 lint/test 필요 여부를 알려줌

logging / analytics

세션 시작, prompt 제출, tool 사용 기록

directory-specific context

특정 디렉터리에서 추가 작업 규칙 주입

enterprise 정책

관리자가 공통 hook을 강제

AGENTS.md에 "하지 마라"고 적는 것은 지침이고, hook으로 차단하는 것은 실행 제어에 가깝습니다. 중요한 정책일수록 AGENTS.md만 믿지 말고 hook, sandbox, approval, rules와 함께 쓰는 편이 안전합니다.

03Hooks는 기본 활성화되어 있다

Hooks는 기본적으로 켜져 있습니다. 끄려면 config.toml에서 [features].hooks = false를 설정합니다.

다시 켜기:

[features]
hooks = true

조직 관리자는 requirements.toml에서 hooks를 강제로 끌 수도 있습니다.

[features]
hooks = false

04Hooks 파일 위치

Codex는 active config layer 옆에서 hooks를 찾습니다. 실무에서 가장 많이 쓰는 위치는 네 가지입니다.

~/.codex/hooks.json
~/.codex/config.toml
<repo>/.codex/hooks.json
<repo>/.codex/config.toml

~/.codex/hooks.json

개인 전체 hook

~/.codex/config.toml

개인 config 안 inline hook

<repo>/.codex/hooks.json

프로젝트 전용 hook

<repo>/.codex/config.toml

프로젝트 config 안 inline hook

프로젝트 로컬 hook은 프로젝트 .codex/ layer가 trusted 상태일 때만 로드됩니다.

05hooks.json 방식과 config.toml inline 방식

Hooks는 두 가지 방식으로 설정할 수 있습니다.

첫 번째: hooks.json 파일

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/pre_tool_use_policy.py",
            "timeout": 30,
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}

06config.toml inline 방식

두 번째는 config.toml 안에 inline으로 쓰는 방식입니다.

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

권장 기준:

hooks.json

hooks가 많거나 팀에서 hook만 따로 관리할 때

inline [hooks]

config와 hook 설정을 한 파일에 간단히 둘 때

07Hook 설정 구조

Hook 설정은 세 단계입니다.

Event
→ Matcher group
→ Hook handler

예시:

PreToolUse

어떤 lifecycle event에서 실행할지

matcher

어떤 tool, trigger, source에 반응할지

hooks

실제 실행할 handler 목록

type = "command"

현재 실행되는 handler 유형

command

실행할 shell command

timeout

최대 실행 시간, 초 단위

statusMessage

UI에 표시할 상태 메시지

08Matcher 패턴

matcher는 hook이 언제 실행될지 정하는 정규식 문자열입니다. "*", "", 또는 matcher 생략은 해당 event의 모든 발생에 매칭됩니다.

자주 쓰는 matcher:

Bash
^Bash$
^apply_patch$
Edit|Write
mcp__filesystem__read_file
mcp__filesystem__.*
startup|resume|clear|compact
manual|auto

Event별 matcher 대상:

PreToolUse

tool name

PermissionRequest

tool name

PostToolUse

tool name

PreCompact / PostCompact

manual 또는 auto

SessionStart

startup, resume, clear, compact

SubagentStart / SubagentStop

subagent type

09Hook trust review와 /hooks

Non-managed command hook은 실행 전에 사용자가 직접 review하고 trust해야 합니다. Codex는 hook 정의의 현재 hash를 기준으로 trust를 기록하므로, hook 내용이 바뀌면 다시 review 대상이 됩니다.

CLI에서 hook 관리:

/hooks

/hooks에서 할 수 있는 일:

hook source 확인
새 hook 또는 변경된 hook review
hook trust
개별 non-managed hook disable

Managed hook은 system, MDM, cloud, requirements.toml 같은 관리 소스에서 온 hook입니다. 이런 hook은 정책상 trusted로 표시되고, 사용자 hook browser에서 비활성화할 수 없습니다.

10Lifecycle event 전체 목록

현재 config reference가 예시로 드는 lifecycle hook event는 다음입니다.

SessionStart

세션 시작, resume, clear, compact 후

UserPromptSubmit

사용자 prompt가 모델로 보내지기 직전

PreToolUse

tool 실행 직전

PermissionRequest

Codex가 approval prompt를 띄우기 직전

PostToolUse

tool 실행 후

PreCompact

conversation compact 직전

PostCompact

conversation compact 직후

SubagentStart

subagent 시작 시

SubagentStop

subagent 종료 시

Stop

turn 종료 시

11SessionStart

SessionStart는 세션이 시작될 때 실행됩니다.

Matcher 대상:

startup
resume
clear
compact

입력에는 source가 포함됩니다. stdout에 plain text를 출력하면 추가 developer context로 들어갑니다. JSON으로 출력하면 additionalContext를 줄 수 있습니다.

사용 상황: 세션 시작 시 팀 규칙 추가 주입, 작업 디렉터리별 추가 context 제공, 최근 작업 메모 요약 삽입

12UserPromptSubmit

UserPromptSubmit은 사용자 prompt가 모델에 전달되기 직전에 실행됩니다.

입력에는 사용자가 제출한 prompt가 들어옵니다. 이 event는 현재 matcher를 사용하지 않으며, 설정된 matcher는 무시됩니다. plain text stdout은 추가 developer context로 들어가고, decision: "block"으로 prompt 자체를 차단할 수도 있습니다.

사용 상황: prompt에 API key가 붙었는지 검사, 운영 DB 삭제 요청 같은 고위험 요청 차단, prompt 내용에 따라 추가 안내 context 주입

13UserPromptSubmit 차단 예시

차단 output 예시:

{
  "decision": "block",
  "reason": "Prompt appears to contain a secret. Remove it before continuing."
}

또는 exit code 2와 stderr로 차단 사유를 전달할 수 있습니다.

14PreToolUse

PreToolUse는 Bash, apply_patch, MCP tool 같은 지원 tool이 실행되기 직전에 실행됩니다.

입력에는 tool_name, tool_use_id, tool_input이 포함됩니다. Bash와 apply_patch의 경우 tool_input.command를 사용합니다.

사용 상황: 위험한 Bash command 차단, 특정 파일 수정 차단, MCP tool 호출 제한, 명령 실행 전 추가 context 주입, 지원되는 tool input rewrite

15PreToolUse 차단 output

차단 output 예시:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook."
  }
}

지원되는 tool call은 permissionDecision: "allow"와 updatedInput으로 rewrite할 수 있습니다.

16PermissionRequest

PermissionRequest는 Codex가 사용자에게 approval을 요청하기 직전에 실행됩니다.

예를 들어 shell escalation 또는 managed-network approval이 필요할 때 실행됩니다. approval이 필요 없는 command에는 실행되지 않습니다. 이 hook은 request를 allow, deny, 또는 결정하지 않고 일반 approval flow로 넘길 수 있습니다.

승인 output:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow"
    }
  }
}

17PermissionRequest 거부 output

거부 output:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "deny",
      "message": "Blocked by repository policy."
    }
  }
}

여러 hook이 decision을 반환하면 deny가 이깁니다. deny가 없고 하나라도 allow가 있으면 approval prompt를 띄우지 않고 진행합니다.

18PostToolUse

PostToolUse는 tool 실행 후에 실행됩니다.

Bash, apply_patch, MCP tool call 이후 실행되며, Bash command가 non-zero status로 끝난 경우에도 실행됩니다. 단, 이미 실행된 tool의 side effect를 되돌릴 수는 없습니다.

사용 상황: command output 검사, 테스트 실패 결과를 model-visible feedback으로 바꾸기, 생성 파일 변경 감지, 금지 파일 변경 후 경고

중요한 제한: PostToolUse는 이미 실행된 작업을 되돌릴 수 없습니다. 차단이 목적이면 PreToolUse를 써야 합니다.

19PreCompact / PostCompact

PreCompact는 conversation compact 직전에 실행됩니다. PostCompact는 compact 직후 실행됩니다. Matcher 대상은 manual 또는 auto입니다.

사용 상황: compact 전에 중요한 TODO 저장, compact 후 요약 품질 검사, 장기 세션에서 메모 파일 업데이트

PreCompact hook이 continue: false를 반환하면 compact 전에 멈출 수 있습니다. PostCompact hook이 continue: false를 반환하면 compact 후 멈플 수 있습니다.

20SubagentStart / SubagentStop

SubagentStart는 subagent가 시작될 때 실행됩니다. SubagentStop은 subagent가 종료될 때 실행됩니다.

SubagentStart에서는 plain text stdout이 subagent용 추가 developer context로 들어갈 수 있습니다. SubagentStop은 exit 0일 때 JSON stdout을 기대하며, plain text output은 invalid합니다.

사용 상황: subagent별 추가 지침 주입, review subagent에 별도 보안 기준 제공, subagent 결과가 부족하면 한 번 더 실행 유도

21Stop

Stop은 turn이 끝날 때 실행됩니다.

Matcher는 현재 사용되지 않습니다. Exit 0에서는 JSON stdout을 기대하며 plain text output은 invalid합니다. decision: "block"은 turn을 거절하는 것이 아니라, Codex에게 계속 진행하라는 continuation prompt를 자동 생성합니다.

사용 상황: 테스트가 안 돌았으면 한 번 더 확인하게 하기, 작업 종료 전 체크리스트 강제, 마지막 assistant message 검사, 필수 보고 형식 누락 시 계속 작성하게 하기

22Stop hook 주의사항

Stop hook은 무한 continuation을 만들 수 있습니다. 반드시 stop_hook_active 같은 입력 필드를 보고 반복을 제한해야 합니다.

공식 hook input에는 stop_hook_active가 포함되어, 해당 turn이 이미 Stop hook으로 continuation되었는지 확인할 수 있습니다.

23Hook input JSON 구조

모든 command hook은 stdin으로 JSON object 하나를 받습니다. 공통 필드는 다음입니다.

session_id

현재 Codex session id

transcript_path

session transcript 경로 (string 또는 null)

cwd

세션 working directory

hook_event_name

현재 hook event 이름

model

활성 모델 slug

permission_mode

현재 permission mode

turn_id

turn-scoped hook에서 제공되는 Codex turn id

24Hook input 읽기 (Python)

Python hook에서 입력 읽기:

#!/usr/bin/env python3

import json
import sys

payload = json.load(sys.stdin)

event = payload.get("hook_event_name")
cwd = payload.get("cwd")
model = payload.get("model")

25Hook output JSON 구조

여러 event는 공통 output field를 지원합니다.

{
  "continue": true,
  "stopReason": "optional",
  "systemMessage": "optional",
  "suppressOutput": false
}

일반 성공: exit 0 + stdout 없음

차단 또는 continuation: exit 2 + stderr에 이유 출력, 또는 event-specific JSON을 stdout으로 출력

26Hook output 주의사항

Event마다 실제 지원 범위가 다릅니다.

PreToolUse

continue: false는 현재 지원되지 않음

PermissionRequest

updatedInput, updatedPermissions, interrupt는 future reserved

PostToolUse

side effect를 undo하지 못함

Stop

JSON stdout 필요, plain text invalid

SubagentStop

JSON stdout 필요, plain text invalid

27실무 예시: 위험한 Bash 명령 차단

목표: rm -rf, git push, deploy, kubectl delete, terraform apply 같은 명령을 자동 차단합니다.

.codex/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/block_dangerous_bash.py\"",
            "timeout": 10,
            "statusMessage": "Checking Bash safety policy"
          }
        ]
      }
    ]
  }
}

28실무 예시: block_dangerous_bash.py

.codex/hooks/block_dangerous_bash.py:

#!/usr/bin/env python3

import json
import re
import sys

payload = json.load(sys.stdin)
tool_input = payload.get("tool_input") or {}
command = tool_input.get("command", "")

dangerous_patterns = [
    r"\brm\s+-rf\b",
    r"\bgit\s+push\b",
    r"\bkubectl\s+delete\b",
    r"\bterraform\s+apply\b",
]

29실무 예시: prompt 내 secret 검사

.codex/hooks.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/check_prompt_secret.py\"",
            "timeout": 10,
            "statusMessage": "Checking prompt for secrets"
          }
        ]
      }
    ]
  }
}

입력에는 사용자가 제출한 prompt가 들어옵니다. UserPromptSubmit은 prompt가 모델로 보내지기 직전에 실행됩니다.

30실무 예시: 작업 종료 시 테스트 실행 유도

Stop hook은 turn 종료 시 실행됩니다. 테스트가 필요한데 언급되지 않았으면 Codex가 한 번 더 확인하게 만들 수 있습니다.

.codex/hooks.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/stop_require_tests.py\"",
            "timeout": 10,
            "statusMessage": "Checking completion criteria"
          }
        ]
      }
    ]
  }
}

31Plugin-bundled hooks

Plugin도 lifecycle hook을 포함할 수 있습니다.

기본 plugin hook 위치:

hooks/hooks.json

또는 .codex-plugin/plugin.json에서 hook path를 지정할 수 있습니다.

Plugin hook command에는 다음 환경 변수가 제공됩니다:

PLUGIN_ROOT

설치된 plugin root

PLUGIN_DATA

plugin의 writable data directory

CLAUDE_PLUGIN_ROOT

호환용 plugin root

CLAUDE_PLUGIN_DATA

호환용 plugin data

32Managed hooks와 requirements.toml

조직 관리자는 requirements.toml에서 managed hooks를 강제할 수 있습니다.

주의: Codex가 managed_dir의 script를 배포하지 않습니다. 조직의 MDM 또는 device-management 시스템이 script를 설치·업데이트해야 합니다.

Managed hooks는 system, MDM, cloud, requirements.toml 같은 source에서 오며, 관리 정책상 trusted이고 사용자 hook browser에서 비활성화할 수 없습니다.

33Hooks 보안 주의점 (1)

1. Hook은 로컬 command를 실행합니다

Hook command는 세션의 cwd에서 실행됩니다.

피해야 할 예:

{
  "type": "command",
  "command": "curl https://example.com/install.sh | sh"
}

34Hooks 보안 주의점 (2)

2. Project-local hook은 trust review 전까지 실행되지 않습니다

악성 repo가 .codex/hooks.json을 심어둘 수 있기 때문에 Codex는 non-managed hook을 바로 실행하지 않고 review/trust 절차를 요구합니다.

권장: /hooks에서 hook command 전체 확인, 절대 경로와 script 내용 확인, 의심스러운 network call 확인, trust 후 실행

35Hooks 보안 주의점 (3~4)

3. 여러 matching hook은 모두 실행됩니다

Matching hook이 여러 파일에 있으면 모두 실행됩니다. 보안 hook을 여러 개 두면 서로 순서를 보장한다고 가정하면 안 됩니다.

4. PostToolUse는 undo가 아닙니다

PostToolUse는 tool 실행 후 검사할 수 있지만, 이미 실행된 command의 side effect를 되돌리지는 못합니다. 차단이 목적이면 PreToolUse를 사용하세요.

36Hooks 보안 주의점 (5~7)

5. Transcript format에 의존하지 않습니다

Hook input의 transcript_path는 편의용입니다. Transcript format이 hooks용 stable interface가 아니며 변경될 수 있습니다.

6. Hook script에 secret을 넣지 않습니다

API_KEY를 하드코딩하지 말고 os.environ.get()으로 환경 변수에서 읽으세요.

7. Timeout을 짧게 둡니다

기본 timeout은 생략 시 600초입니다. 오래 걸리는 hook은 Codex 작업 흐름을 느리게 만듭니다. "timeout": 10 정도가 권장입니다.

37문제 해결 (1~2)

1. Hook이 실행되지 않는다

확인: config.toml에서 [features] hooks = false 여부. 또는 /hooks에서 trust가 필요한 상태인지 확인합니다.

2. Project hook이 무시된다

원인: 프로젝트가 untrusted 상태. Project-local hooks는 project .codex/ layer가 trusted일 때만 로드됩니다. /hooks에서 project trust 상태를 확인하고 다시 세션을 시작합니다.

38문제 해결 (3~5)

3. Hook이 두 번 실행되는 것 같다

원인: hooks.json과 config.toml inline hooks가 동시에 존재, user hook과 project hook이 동시에 matching, plugin hook까지 matching. 해결: 한 layer에서는 hooks.json 또는 inline [hooks] 중 하나만 사용

4. PreToolUse에서 차단했는데 다른 hook도 실행된다

정상 동작입니다. 같은 event의 여러 matching command hooks는 concurrently 시작되므로 중요한 차단 로직은 하나의 hook에 합치세요.

39문제 해결 (6~7)

5. PostToolUse로 차단했는데 command가 이미 실행됐다

정상 동작입니다. PostToolUse는 tool 실행 후 hook이므로 명령 실행 전 차단은 PreToolUse로 옮기세요.

6. Stop hook이 무한 반복된다

원인: Stop hook이 계속 decision: block을 반환함. 해결: if payload.get("stop_hook_active"): sys.exit(0)로 무한 반복을 방지하세요.

40Windows에서 command가 안 돈다

commandWindows 또는 TOML alias command_windows를 사용합니다.

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 .codex/hooks/check.py"
command_windows = 'py -3 .codex\hooks\check.py'
timeout = 10

섹션 16 · 마무리

이 단원에서 기억할 것

Hooks는 Codex lifecycle 중 특정 시점에 command script를 실행하는 시스템입니다.

주요 위치: ~/.codex/hooks.json, ~/.codex/config.toml, <repo>/.codex/hooks.json, <repo>/.codex/config.toml

가장 중요한 원칙은 차단은 PreToolUse, 사후 검사는 PostToolUse, 작업 종료 검증은 Stop입니다.

초보자는 처음에 UserPromptSubmit(prompt 검사), PreToolUse(실행 전 차단), PostToolUse(실행 후 검사) 세 개만 익히면 충분합니다.

다음 단원

17단원. MCP: Model Context Protocol

17. MCP: Model Context Protocol

01MCP란 무엇인가

MCP는 AI 애플리케이션이 외부 도구, 데이터 소스, 워크플로에 연결하기 위한 표준 프로토콜입니다.

간단히 말하면:

MCP = Codex가 외부 도구를 표준 방식으로 연결하는 통로

Codex는 MCP를 통해 다음을 할 수 있습니다.

GitHub

PR, issue, repository 정보 조회·관리

Figma

디자인 파일 읽기

Sentry

에러 로그 확인

Browser / Playwright

브라우저 제어와 검사

Docs MCP

최신 개발 문서 검색

사내 DB / API

내부 시스템 조회 또는 워크플로 실행

02Codex에서 MCP가 하는 일

Codex에서 MCP는 기본 내장 도구만으로 부족한 외부 컨텍스트와 도구를 추가하는 확장 계층입니다.

Codex 기본 능력:

파일 읽기
파일 수정
shell 명령 실행
diff 확인
테스트 실행

MCP로 확장되는 능력:

GitHub PR/issue 조작
Figma 디자인 읽기
Sentry 에러 확인
브라우저 열기와 screenshot
외부 문서 검색
사내 시스템 조회

03MCP의 기본 구조: Host, Client, Server

MCP 표준은 크게 세 요소로 구성됩니다.

Host

AI 애플리케이션. 여기서는 Codex

Client

Host 안에서 MCP 서버와 연결하는 커넥터

Server

도구와 컨텍스트를 제공하는 외부 시스템

Codex 관점에서 정리하면:

Codex = Host
Codex 내부 MCP 연결부 = Client
GitHub/Figma/Sentry/Context7 MCP = Server

04Codex가 지원하는 MCP transport

Codex가 지원하는 MCP server 형태는 크게 두 가지입니다.

STDIO

로컬 command로 MCP 서버 프로세스를 실행

Streamable HTTP

URL 주소에 있는 MCP 서버에 HTTP로 연결

구분:

STDIO MCP = 내 컴퓨터에서 서버 프로세스를 실행
Streamable HTTP = URL로 외부 또는 로컬 MCP 서버에 연결

05MCP 설정 위치

MCP 설정은 config.toml 안에 둡니다.

기본 위치:

~/.codex/config.toml

프로젝트별 위치:

/.codex/config.toml

주의: 프로젝트 .codex/config.toml의 MCP 설정은 trusted project에서만 적용됩니다.

untrusted project에서는 project-scoped .codex/ layer가 건너뛰어집니다.

06CLI로 MCP 서버 추가하기

MCP 서버는 CLI로 추가할 수 있습니다.

기본형:

codex mcp add --

환경 변수 포함:

codex mcp add --env VAR1=VALUE1 --env VAR2=VALUE2 --

예시:

codex mcp add context7 -- npx -y @upstash/context7-mcp

확인 및 도움말:

/mcp
codex mcp --help

07config.toml로 MCP 서버 설정하기

세밀한 설정은 config.toml에서 합니다.

기본 구조:

[mcp_servers.]
...

예시:

# ~/.codex/config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60

08STDIO MCP 서버 설정

STDIO 서버는 로컬 command로 실행되는 MCP 서버입니다.

기본 예시:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

STDIO에서 자주 쓰는 필드:

command

MCP 서버를 실행할 command

args

command에 넘길 인자

env

서버에 직접 전달할 환경 변수

env_vars

현재 환경에서 allow/forward할 환경 변수

cwd

서버를 시작할 working directory

startup_timeout_sec

서버 시작 timeout

tool_timeout_sec

tool 실행 timeout

enabled

서버 활성/비활성

09STDIO 환경 변수 예시

환경 변수를 설정할 때의 예시입니다.

[mcp_servers.mytool]
command = "node"
args = ["server.js"]
cwd = "/Users/me/dev/my-mcp-server"
env_vars = ["MY_LOCAL_TOKEN"]

[mcp_servers.mytool.env]
NODE_ENV = "production"

env_vars는 plain variable name 또는 { name = "...", source = "local" | "remote" } object를 받을 수 있습니다.

string entry는 기본적으로 local source를 사용하며, source = "remote"는 executor-backed remote stdio에서만 사용됩니다.

10Streamable HTTP MCP 서버 설정

Streamable HTTP 서버는 URL로 접속하는 MCP 서버입니다.

기본 예시:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

HTTP header 예시:

[mcp_servers.company_docs]
url = "https://mcp.company.internal/mcp"
bearer_token_env_var = "COMPANY_MCP_TOKEN"

[mcp_servers.company_docs.http_headers]
X-Workspace = "engineering"

[mcp_servers.company_docs.env_http_headers]
X-User-Token = "COMPANY_USER_TOKEN"

11HTTP 필드 의미

Streamable HTTP 서버의 필드들:

url

MCP 서버 URL

bearer_token_env_var

bearer token을 읽을 환경 변수 이름

http_headers

config에 직접 적는 static header

env_http_headers

환경 변수에서 값을 읽어 header로 전달

secret은 http_headers에 직접 쓰지 말고 bearer_token_env_var 또는 env_http_headers를 쓰는 편이 안전합니다.

12Bearer token과 HTTP header 설정

Bearer token 방식은 환경 변수에 token을 넣고, config에는 환경 변수 이름만 적는 방식이 좋습니다.

환경 변수 설정:

export FIGMA_OAUTH_TOKEN="..."

config 설정:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

나쁜 예 (token을 직접 쓰는 것):

[mcp_servers.figma.http_headers]
Authorization = "Bearer 실제토큰값"

이유: config.toml이 실수로 commit되어도 token 값 자체는 들어가지 않습니다.

13OAuth MCP 서버 로그인

OAuth를 지원하는 MCP 서버는 CLI로 로그인합니다.

codex mcp login

OAuth callback 설정:

mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"

설정하지 않으면 Codex는 ephemeral port를 사용합니다.

OAuth credential 저장 방식:

mcp_oauth_credentials_store = "auto"

가능한 값: auto, file, keyring

14OAuth scope 설정

OAuth scope를 지정하여 권한을 제한할 수 있습니다.

예시:

[mcp_servers.github]
url = "https://example.com/mcp"
scopes = ["repo:read", "issues:read"]

mcp_servers.<id>.scopes는 해당 MCP 서버 인증 시 요청할 OAuth scopes를 정의합니다.

필요할 때만 write scope를 추가하는 것이 안전합니다.

15MCP tool allowlist / denylist

MCP 서버가 많은 tool을 제공하면 필요한 tool만 켜는 것이 좋습니다.

허용 목록:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]

차단 목록:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot", "evaluate"]
disabled_tools = ["evaluate"]

disabled_tools는 enabled_tools 이후 적용됩니다.

16tool allowlist 필드 의미

tool 제어 필드들:

enabled_tools

이 서버에서 사용할 tool allowlist

disabled_tools

allowlist 적용 후 다시 끌 tool denylist

enabled = false

서버 설정은 남기고 비활성화

17MCP tool approval mode

MCP tool마다 승인 정책을 정할 수 있습니다.

서버 기본값:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
default_tools_approval_mode = "prompt"

특정 tool만 override:

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"

값 의미:

auto

Codex가 tool 성격과 정책에 따라 처리

prompt

tool 실행 전 사용자 확인

approve

prompt 없이 승인

18approval mode 실무 예시

읽기 전용 tool만 자동 승인하고 싶다면:

[mcp_servers.docs]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
default_tools_approval_mode = "prompt"

[mcp_servers.docs.tools.search]
approval_mode = "approve"

[mcp_servers.docs.tools.read]
approval_mode = "approve"

기본 원칙: 쓰기/삭제 위험이 있는 tool은 prompt로 유지합니다.

19read-only MCP 구성 방식

Codex MCP 설정에 모든 서버에 공통 적용되는 단일 read_only = true 같은 범용 옵션이 있는 것은 아닙니다.

read-only에 가깝게 운영하려면 다음 네 가지를 조합합니다.

OAuth scope 제한

read-only scope만 요청

enabled_tools

읽기 tool만 allowlist

disabled_tools

write/delete/update tool 차단

default_tools_approval_mode = "prompt"

위험 tool은 매번 확인

20read-only MCP 예시

GitHub read-only 설정 예시:

[mcp_servers.github]
url = "https://example-github-mcp.company/mcp"
scopes = ["repo:read", "issues:read"]
enabled_tools = ["repos/list", "pull_requests/read", "issues/read"]
disabled_tools = ["repos/delete", "pull_requests/merge", "issues/write"]
default_tools_approval_mode = "prompt"

핵심: read-only MCP는 서버 인증 권한 + tool allowlist + approval mode로 만듭니다.

21MCP 서버 instructions

MCP 서버는 initialization 중 instructions field를 반환할 수 있습니다.

Codex는 이 instructions를 서버 전체 지침으로 읽고, 해당 서버의 tool과 함께 사용합니다.

예시:

This server provides read-only access to internal API documentation.
Use search_docs before read_doc.
Do not call write or admin tools.
Rate limit: at most 5 requests per minute.

서버 instructions에 넣기 좋은 내용:

tool 사용 순서

먼저 search, 그다음 read

제한

write tool 사용 금지

rate limit

분당 요청 제한

데이터 민감도

고객 정보 출력 금지

인증 범위

read-only access

처음 512자는 Codex가 서버 사용 여부를 판단할 때 중요하므로 self-contained하게 쓰세요.

22plugin-provided MCP servers

Plugin이 MCP 서버를 포함할 수도 있습니다.

예시:

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"

구분:

일반 MCP

[mcp_servers.<id>]

plugin MCP

[plugins.<plugin>.mcp_servers.<server>]

transport 설정

사용자가 직접 설정 vs plugin manifest가 정의

사용자 관리

command/url 직접 설정 vs enabled/tool policy만

23Codex 자체를 MCP 서버로 실행하기

Codex는 다른 agent나 도구가 사용할 수 있도록 자기 자신을 MCP 서버로 실행할 수도 있습니다.

codex mcp-server

사용 상황:

다른 agent가 Codex를 tool처럼 호출
멀티에이전트 워크플로에서 Codex를 하위 실행기로 사용
CI/CD 오케스트레이터가 Codex 작업을 MCP로 호출

일반 초보자는 이 기능부터 쓸 필요는 없습니다. 보통은 "Codex에 MCP 서버를 연결하는 것"이 먼저고, "Codex 자체를 MCP 서버로 노출하는 것"은 고급 자동화 영역입니다.

24MCP가 토큰 비용에 미치는 영향

MCP 서버는 편하지만 비용과 context 사용량을 늘릴 수 있습니다.

비용을 늘리는 요소:

MCP 서버 수 증가

tool 정의와 instructions가 context에 포함

tool 수 증가

모델이 선택해야 할 tool 설명 증가

긴 server instructions

매 세션 context 증가

큰 tool output

tool 결과가 대화 context에 들어감

여러 MCP 동시 사용

context pollution 가능성 증가

25비용 최적화

비용을 줄이려면 다음과 같이 설정합니다.

불필요한 서버 비활성화:

[mcp_servers.big_server]
enabled = false

필요한 tool만 허용:

[mcp_servers.github]
enabled_tools = ["pull_requests/read", "issues/read"]
disabled_tools = ["pull_requests/merge", "issues/write"]

26초보자가 먼저 연결해볼 MCP

초보자에게 추천하는 순서:

1순위

OpenAI Docs / Context7 — 문서 검색용이라 상대적으로 안전

2순위

GitHub read-only — PR/issue 맥락 파악에 유용

3순위

Figma read-only — 프론트엔드 작업에 유용

4순위

Sentry read-only — 오류 분석에 유용

5순위

Browser / Playwright — 강력하지만 권한 관리 필요

초보자 기본 원칙:

문서 검색 MCP부터 시작
write/delete/admin tool이 있는 MCP는 나중에 연결

27GitHub MCP

GitHub MCP는 repository, PR, issue 등 GitHub API 맥락을 Codex에게 줄 때 유용합니다.

추천 용도:

PR 분석

PR 설명, comment, changed files 확인

issue triage

issue 내용 요약, label 후보 제안

release note

merged PR 기반 정리

review 보조

GitHub thread 맥락 확인

위험 요소:

PR merge

잘못 실행하면 실제 변경

issue/comment write

외부 공개 기록 생성

repo setting 변경

권한이 크면 위험

token scope 과다

불필요한 write 권한 노출

28GitHub read-only 예시

GitHub MCP를 안전하게 설정하는 예시:

[mcp_servers.github]
url = "https://example-github-mcp.company/mcp"
scopes = ["repo:read", "issues:read"]
enabled_tools = ["repos/list", "pull_requests/read", "issues/read"]
default_tools_approval_mode = "prompt"

29Figma MCP

Figma MCP는 디자인 파일을 읽고 구현에 반영할 때 유용합니다.

추천 용도:

디자인 분석

frame, component, spacing 확인

UI 구현

Figma 기준으로 React component 작성

디자인 QA

구현과 디자인 차이 확인

asset 확인

색상, typography, layout 참고

기본 예시:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

30Sentry MCP

Sentry MCP는 production error, stack trace, issue context를 Codex에게 제공할 때 유용합니다.

추천 용도:

오류 원인 분석

stack trace 기반 코드 위치 추적

regression 확인

최근 배포와 에러 증가 비교

issue 요약

Sentry issue를 개발 task로 변환

테스트 후보 도출

재발 방지 테스트 제안

주의: Sentry에는 사용자 정보, URL, request body, token 조각 등 민감 데이터가 포함될 수 있습니다.

31Sentry MCP 설정

32Browser / Playwright / Chrome DevTools MCP

Browser 계열 MCP는 웹앱을 실제 브라우저에서 열고 검사할 때 유용합니다.

추천 용도:

UI 테스트

페이지 열기, 클릭, screenshot

디버깅

console error 확인

레이아웃 확인

visual regression 탐색

E2E 보조

Playwright 흐름 점검

Chrome DevTools 예시:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"

주의: 브라우저 MCP는 로그인 세션, 쿠키, 관리자 페이지, 내부 대시보드에 접근할 수 있으므로 prompt 기본값이 안전합니다.

33OpenAI Docs / Context7 MCP

문서 검색 MCP는 초보자에게 가장 안전한 시작점입니다.

Context7 예시:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true
default_tools_approval_mode = "approve"

CLI 추가:

codex mcp add context7 -- npx -y @upstash/context7-mcp

34MCP 보안 체크리스트 ①

1. token을 config에 직접 쓰지 않는다

나쁜 예:

[mcp_servers.company.http_headers]
Authorization = "Bearer 실제토큰"

좋은 예:

[mcp_servers.company]
bearer_token_env_var = "COMPANY_MCP_TOKEN"

2. write tool은 기본 prompt로 둔다

[mcp_servers.github]
default_tools_approval_mode = "prompt"

읽기 tool만 자동 승인:

[mcp_servers.github.tools.pull_requests_read]
approval_mode = "approve"

35MCP 보안 체크리스트 ②

3. 필요 없는 tool은 꺼둔다

[mcp_servers.github]
enabled_tools = ["pull_requests/read", "issues/read"]
disabled_tools = ["pull_requests/merge", "issues/write"]

4. MCP 서버를 항상 많이 켜두지 않는다

[mcp_servers.figma]
enabled = false

5. project MCP는 trusted project에서만 신뢰한다

프로젝트 .codex/config.toml에 MCP 서버가 들어 있다면, 그 서버 command나 URL이 안전한지 먼저 확인합니다.

36MCP 보안 체크리스트 ③

6. OAuth scope를 최소화한다

[mcp_servers.github]
scopes = ["repo:read", "issues:read"]

필요할 때만 write scope를 추가합니다.

7. startup timeout과 tool timeout을 명시한다

startup_timeout_sec = 20
tool_timeout_sec = 45

기본값: startup timeout 10초, tool timeout 60초

37MCP 문제 해결 체크리스트 ①

1. /mcp에 서버가 안 보인다

확인:

/mcp

확인할 것:

config.toml 위치가 맞는가?
[mcp_servers.<id>] table 이름이 맞는가?
enabled = false가 아닌가?
프로젝트 config라면 trusted project인가?

2. STDIO 서버가 시작 실패한다

체크:

command가 PATH에 있는가?
args가 배열 형태인가?
cwd가 존재하는가?
필요한 env가 전달되는가?
startup_timeout_sec가 너무 짧지 않은가?

38MCP 문제 해결 체크리스트 ②

3. HTTP MCP 인증이 실패한다

확인:

echo $FIGMA_OAUTH_TOKEN

체크:

환경 변수 이름이 맞는가?
token이 현재 shell에 export되어 있는가?
IDE extension이 같은 환경 변수를 볼 수 있는가?
bearer_token_env_var에 token 값 자체를 넣지 않았는가?

4. OAuth callback이 실패한다

고정 port가 필요하면:

mcp_oauth_callback_port = 5555

특정 redirect URI가 필요하면:

mcp_oauth_callback_url = "https://devbox.example.internal/callback"

39MCP 문제 해결 체크리스트 ③

5. tool이 너무 많이 보여서 Codex가 헷갈린다

해결:

[mcp_servers.big_server]
enabled_tools = ["search", "read"]
disabled_tools = ["write", "delete", "admin"]

또는 서버 자체 비활성화:

[mcp_servers.big_server]
enabled = false

6. tool 실행이 자주 멈춘다

읽기 tool만 자동 승인:

[mcp_servers.docs.tools.search]
approval_mode = "approve"

[mcp_servers.docs.tools.read]
approval_mode = "approve"

위험 tool은 prompt 유지:

[mcp_servers.github.tools.merge]
approval_mode = "prompt"

40MCP 문제 해결 체크리스트 ④

7. MCP 때문에 비용이 늘었다

원인:

MCP 서버 수가 많음
tool 정의가 많음
instructions가 김
tool output이 큼

해결:

[mcp_servers.figma]
enabled = false

[mcp_servers.github]
enabled_tools = ["pull_requests/read", "issues/read"]

41초보자 기본 MCP config

가장 간단하고 안전한 설정:

# ~/.codex/config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true
default_tools_approval_mode = "approve"
startup_timeout_sec = 20
tool_timeout_sec = 60

용도:

최신 개발 문서 검색
낮은 위험
MCP 입문용

42신중한 실무 config

여러 MCP를 선택적으로 관리하는 설정:

# ~/.codex/config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true
default_tools_approval_mode = "approve"
startup_timeout_sec = 20
tool_timeout_sec = 60

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
enabled = false
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled = false
enabled_tools = ["open", "screenshot"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"

운영 방식:

문서 MCP만 상시 활성화
Figma와 Browser MCP는 필요할 때 enabled = true
브라우저 open은 승인 없이 허용
screenshot 등 나머지는 prompt

43GitHub read-only 중심 config

GitHub를 중심으로 운영할 때의 설정:

[mcp_servers.github]
url = "https://example-github-mcp.company/mcp"
bearer_token_env_var = "GITHUB_MCP_TOKEN"
scopes = ["repo:read", "issues:read"]
enabled_tools = [
  "repos/list",
  "pull_requests/read",
  "issues/read"
]
disabled_tools = [
  "pull_requests/merge",
  "issues/write",
  "repos/delete"
]
default_tools_approval_mode = "prompt"

[mcp_servers.github.tools."pull_requests/read"]
approval_mode = "approve"

[mcp_servers.github.tools."issues/read"]
approval_mode = "approve"

목표:

읽기 tool은 자동 승인
쓰기·삭제·merge tool은 차단 또는 prompt
token scope도 read 중심

섹션 17 · 마무리

MCP: Model Context Protocol 핵심 정리

MCP는 Codex를 외부 도구와 연결하는 표준 확장 시스템입니다. 기본 내장 도구만으로 부족한 GitHub, Figma, Sentry, 문서 검색 등의 외부 컨텍스트를 추가할 수 있습니다.

지원하는 transport:

STDIO: 로컬 command로 MCP 서버 프로세스를 실행
Streamable HTTP: URL로 외부 또는 로컬 MCP 서버에 연결

기본 설정 위치는 ~/.codex/config.toml (전역) 또는 <repo>/.codex/config.toml (프로젝트, trusted만)입니다.

초보자는 문서 검색 MCP(Context7)부터 시작하고, GitHub, Figma, Sentry, Browser는 read-only로 설정하여 단계적으로 추가하는 것이 안전합니다.

가장 중요한 기준:

MCP는 많이 붙일수록 강력해지지만, context 비용과 보안 위험도 같이 늘어난다. 항상 필요한 서버만 켜고, tool은 allowlist로 좁히고, write tool은 prompt로 둔다.

다음 단원

18단원. Skills 시스템

18. Skills 시스템

01Skills란 무엇인가

Skill은 Codex에게 "이런 종류의 작업은 이렇게 처리하라"고 알려주는 작업 전용 지식 패키지입니다.

반복 작업에 적합한 Skill 예시:

PR 리뷰 체크리스트
테스트 코드 작성 규칙
릴리즈 노트 작성 방식
장애 로그 분석 절차
마이그레이션 계획 수립 방식
보안 리뷰 루틴
팀의 커밋 메시지 규칙
특정 프레임워크에서 컴포넌트 생성 방식

핵심은 "지식"이 아니라 "반복 가능한 작업 흐름"입니다. 단순 설명서가 아니라 Codex가 실제 작업 중 따라야 할 절차를 담는 것이 Skill의 목적입니다.

02Skills가 필요한 이유

같은 프롬프트를 계속 복사해서 쓰고 있다면 Skill로 바꿔야 합니다.

Skills가 필요한 네 가지 이유:

작업 품질 일관성

같은 리뷰 기준, 같은 테스트 기준을 Codex가 반복해서 따름

프롬프트 단축

사용자는 "이 PR을 리뷰해줘"라고만 말해도 Codex가 관련 Skill을 선택 가능

팀 지식 공유

개인 노하우가 아니라 저장소 안의 .agents/skills에 넣으면 팀원이 같은 방식으로 사용

복잡한 절차 담기

AGENTS.md보다 복잡한 절차를 담을 수 있으며 특정 작업 수행에 최적화

03재사용 가능한 작업 지식 패키징

Skill은 다음과 같은 상황에서 특히 효과적입니다.

같은 프롬프트를 3번 이상 반복해서 쓴다
같은 종류의 작업에서 Codex가 계속 비슷한 실수를 한다
팀원이 같은 작업을 서로 다른 방식으로 처리한다
작업에 참고 문서, 예시, 체크리스트가 필요하다
작업 결과물의 형식이 항상 일정해야 한다

"테스트 작성 Skill" 예시: 테스트 프레임워크, 파일 이름 규칙, 단위/통합 테스트 구분, mock 허용 범위, 테스트 실행 명령, 실패 시 원인 확인 순서, 결과 보고 형식 등을 포함합니다.

04Skill 구조

기본 구조는 다음과 같습니다.

my-skill/
  SKILL.md
  scripts/
  references/
  assets/
  agents/
    openai.yaml

SKILL.md는 필수이며, scripts/, references/, assets/, agents/openai.yaml은 선택 항목입니다. SKILL.md에는 최소한 name과 description 메타데이터가 들어가야 합니다.

가장 단순한 Skill은 메타데이터(name, description)와 절차만으로 만들 수 있습니다.

05SKILL.md 필수 항목

description은 매우 중요합니다. Codex가 Skill을 자동으로 고를 때 이 설명을 기준으로 판단하기 때문입니다.

좋은 description 예시:

Review pull requests, diffs, branches, or code changes for correctness, security, test coverage, maintainability, and risky behavior. Use when the user asks for PR review, code review, diff review, or merge readiness.

나쁜 description 예시:

Helps with code.

나쁜 설명은 범위가 너무 넓어서 Codex가 언제 이 Skill을 써야 하는지 판단하기 어렵습니다.

06Skill 호출 방식

Codex는 Skill을 두 방식으로 사용합니다.

명시적 호출

사용자가 직접 특정 Skill을 부릅니다.

$pr-review 이 diff를 리뷰해줘.

암시적 호출

사용자가 Skill 이름을 직접 말하지 않아도 Codex가 작업 내용을 보고 적절한 Skill을 선택합니다.

이 PR에서 위험한 부분 위주로 리뷰해줘.

암시적 호출이 잘 되려면 description에 "PR", "review", "diff", "code change" 같은 트리거 단어가 필요합니다.

07Skill MCP dependency

Skill은 작업 절차를 정의하고, MCP는 외부 도구와 시스템에 연결합니다. 둘을 함께 쓰면 강력합니다.

예: "Sentry 장애 분석 Skill"은 절차를 정의하고, MCP 서버가 Sentry 데이터를 가져옵니다.

Skill의 agents/openai.yaml에 MCP 도구 의존성을 선언할 수 있습니다.

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"

외부 시스템에 접근하는 Skill은 반드시 권한, 인증, 데이터 노출 범위를 확인해야 합니다.

08실무 예시: PR 리뷰 Skill

PR 리뷰 Skill은 대부분의 팀에서 바로 효과를 볼 수 있는 대표적인 Skill입니다.

폴더 구조:

.agents/
  skills/
    pr-review/
      SKILL.md
      references/
        review-checklist.md

PR 리뷰 Skill의 검토 우선순위:

Correctness bugs
Security vulnerabilities
Data loss 또는 migration risk
Broken API contracts
Missing 또는 weak tests
Performance regressions
Maintainability problems
Style issues (이해도에만 영향 시)

09실무 예시: PR 리뷰 Skill (계속)

필수 프로세스

Inspect the diff before giving conclusions
Identify the purpose of the change
Check whether the implementation matches the stated purpose
Look for edge cases
Verify whether tests cover the changed behavior
Recommend exact fixes when possible

출력 형식

Summary, Critical findings, Major findings, Minor findings, Test gaps, Merge recommendation(Block / Approve after fixes / Approve)로 구성합니다.

사용 예시

$pr-review 현재 브랜치와 main의 diff를 기준으로 리뷰해줘.

10실무 예시: 테스트 작성 Skill

테스트 작성 Skill은 팀의 테스트 스타일을 고정하는 데 유용합니다.

테스트 작성 프로세스:

Identify the behavior being tested
Check existing test patterns before adding new tests
Prefer the repository's existing test utilities and fixtures
Add the smallest meaningful test set
Include regression tests for fixed bugs
Avoid over-mocking unless the codebase already uses that pattern
Run the relevant test command if available
Report what was tested and what remains untested

테스트 선택 규칙

Pure functions: 단위 테스트 선호 / API behavior: 기존 패턴이 있으면 통합 테스트 선호 / Bug fixes: regression 테스트 추가 / UI behavior: 기존 컴포넌트 테스트 패턴 따르기

11좋은 Skill 작성법

좋은 Skill은 길이가 긴 Skill이 아니라 작업 성공률을 높이는 Skill입니다.

좋은 Skill의 특징:

하나의 Skill은 하나의 작업만 담당
description에 사용 시점과 제외 범위가 분명
입력과 출력 형식이 명확
Codex가 따라야 할 순서가 있음
예외 상황에서의 행동 방식이 명시됨
참고 문서는 references/에 분리
스크립트는 반드시 필요한 경우에만 포함

나쁜 Skill 패턴: "개발을 잘해라"처럼 너무 넓은 범위 / 프로젝트 전체 규칙을 Skill에 포함 / AGENTS.md에 있어야 할 내용을 Skill에 포함 / 외부 도구 접근 권한이 너무 넓은 경우 / 실행 절차 없이 배경 설명만 긴 경우 / 출력 형식이 없어 결과가 매번 다른 경우

12Skill 작성 순서

Skill 작성 시 다음 순서로 접근합니다.

반복되는 작업 하나를 고른다
실제로 자주 쓰는 프롬프트를 모은다
Codex가 자주 틀리는 부분을 정리한다
작업 순서를 체크리스트로 만든다
원하는 출력 형식을 고정한다
SKILL.md로 만든다
2~3개의 실제 작업에 적용해본다
description과 절차를 다듬는다
팀에 공유할 가치가 있으면 repo skill 또는 plugin으로 만든다

13Skills 관리 전략

Skills는 많아질수록 관리가 중요해집니다. 설치된 Skill이 너무 많으면 초기 Skill 목록이 제한되므로 description은 짧고 선명해야 합니다.

Skill 위치별 용도:

$HOME/.agents/skills

개인이 모든 프로젝트에서 쓰는 Skill

.agents/skills

특정 저장소나 팀에서 공유하는 Skill

/etc/codex/skills

공용 머신, 컨테이너, 조직 단위 기본 Skill

plugin

여러 팀이나 사용자에게 배포할 재사용 패키지

14Skills 관리 전략 (계속)

관리 원칙:

개인 습관 → $HOME/.agents/skills
팀 표준 → repo의 .agents/skills
조직 표준 → /etc/codex/skills 또는 managed setup
배포 가능한 묶음 → plugin
외부 도구 연결 포함 → plugin + MCP

Skill이 많아졌을 때 정리 기준:

최근 30일 동안 사용하지 않은 Skill은 비활성화 후보로 둔다
description이 겹치는 Skill은 합치거나 이름을 분명히 나눈다
프로젝트 규칙은 AGENTS.md로 옮긴다
외부 서비스 연결이 필요한 Skill은 MCP dependency를 명시한다
팀 전체에 배포할 Skill은 plugin으로 패키징한다

특정 Skill을 비활성화하려면 ~/.codex/config.toml에서 enabled = false로 설정할 수 있습니다.

섹션 18 · 마무리

이 단원에서 기억할 것

Skills는 Codex를 "매번 새로 지시해야 하는 도구"에서 "팀의 반복 작업 방식을 기억하고 재사용하는 작업 에이전트"로 바꾸는 기능입니다.

가장 먼저 만들기 좋은 Skill은 다음 세 가지입니다:

1. PR 리뷰 Skill / 2. 테스트 작성 Skill / 3. 릴리즈 노트 작성 Skill

초보자는 처음부터 복잡한 Skill을 만들 필요가 없습니다. 먼저 자주 쓰는 프롬프트 하나를 SKILL.md로 옮기고, 실제 작업에 적용하면서 description, 절차, 출력 형식을 조금씩 다듬으면 됩니다.

다음 단원

19단원. Plugins

19. Plugins

01Plugins란 무엇인가

Codex의 Plugin은 Codex가 사용할 수 있는 기능 묶음입니다. 하나의 Plugin 안에는 다음 요소가 들어갈 수 있습니다.

- Skills
- Apps / connectors
- MCP servers
- Hooks
- Assets
- Plugin manifest

간단히 말하면 다음과 같습니다:

Skill  = 작업 방법
MCP    = 외부 도구 연결
Hook   = 특정 시점에 자동 실행되는 규칙
Plugin = Skill + MCP + Hook + 앱 연동을
         설치 가능한 패키지로 묶은 것

초보자는 Plugin을 "Codex에 추가로 설치하는 작업 팩"으로 이해하면 됩니다.

02Plugins와 Skills의 차이

Skills와 Plugins는 비슷해 보이지만 역할이 다릅니다.

구분

내용

핵심 목적

Skills: 작업 절차 정의 / Plugins: 배포와 설치

포함 내용

Skills: SKILL.md, references, scripts / Plugins: skills, apps, MCP servers, hooks, assets

사용 범위

Skills: 개인/프로젝트 단위 / Plugins: 개인, 팀, 워크스페이스, marketplace 단위

적합한 상황

Skills: 반복 프롬프트 정형화 / Plugins: 여러 사람이 설치해서 같은 기능 사용

예시

Skills: PR 리뷰 Skill / Plugins: PR 리뷰 Skill + GitHub MCP + hooks

즉, Skill은 "Codex가 어떻게 일해야 하는가"를 정의하고, Plugin은 "그 작업 방식을 다른 사람도 쉽게 설치해서 쓰게 하는 방법"입니다.

03Plugin discovery

Plugin discovery는 Codex가 설치 가능한 Plugin 목록을 찾는 과정입니다.

Codex app에서는 Plugins 화면에서 curated plugin, workspace에서 공유된 plugin, 사용자가 만든 plugin을 탐색할 수 있습니다. CLI에서는 Codex를 실행한 뒤 /plugins 명령으로 plugin browser를 열 수 있습니다.

codex
/plugins

Plugin을 찾는 기본 흐름은 다음과 같습니다.

Codex app 또는 CLI에서 Plugins 목록을 연다.
필요한 Plugin을 검색하거나 marketplace별로 탐색한다.
Plugin 상세 정보를 확인한다.
설치한다.
필요한 경우 외부 앱 인증을 완료한다.
새 thread에서 Plugin을 사용한다.

04Plugin 사용 방식

Plugin을 사용할 때는 두 가지 방식이 있습니다.

첫째, Codex에게 그냥 원하는 결과를 말합니다.

오늘 읽지 않은 Gmail 스레드를 요약해줘.

둘째, 특정 Plugin이나 bundled Skill을 명시합니다.

@Gmail 오늘 unread 메일 중 중요한 것만 요약해줘.

Codex는 사용자가 직접 Plugin을 지정하지 않아도 설치된 도구 중 적절한 것을 선택할 수 있고, 특정 Plugin이나 Skill을 쓰고 싶으면 @로 명시할 수 있습니다.

05Plugin marketplace

Plugin marketplace는 설치 가능한 Plugin 목록을 담은 JSON catalog입니다. Codex는 공식 curated marketplace뿐 아니라 repo marketplace, legacy-compatible marketplace, personal marketplace도 읽을 수 있습니다.

대표 위치는 다음과 같습니다.

공식 Plugin Directory
$REPO_ROOT/.agents/plugins/marketplace.json
$REPO_ROOT/.claude-plugin/marketplace.json
~/.agents/plugins/marketplace.json

개인 또는 팀용 marketplace 예시는 다음과 같습니다.

{
  "name": "team-codex-plugins",
  "interface": {
    "displayName": "Team Codex Plugins"
  },
  "plugins": [
    {
      "name": "team-pr-review",
      "source": {
        "source": "local",
        "path": "./plugins/team-pr-review"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

06CLI에서 marketplace 추가

CLI에서 marketplace를 직접 추가할 수도 있습니다.

codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-root

codex plugin marketplace는 add, list, remove, upgrade를 지원하며, GitHub shorthand, Git URL, SSH URL, local marketplace root를 source로 받을 수 있습니다.

07Workspace plugin sharing

Workspace plugin sharing은 만든 Plugin을 같은 ChatGPT workspace 구성원에게 공유하는 기능입니다.

공유 흐름은 다음과 같습니다.

Codex app에서 Plugins를 연다.
Created by you로 이동한다.
공유할 Plugin 상세 페이지를 연다.
Share를 선택한다.
workspace members를 추가하거나 share link를 복사한다.
접근 권한을 정해 초대한다.

공유받은 사람은 Plugin Directory의 Shared with you 영역에서 해당 Plugin을 찾을 수 있습니다.

운영 기준은 다음처럼 잡으면 좋습니다.

개인 실험용 Plugin       → 공유하지 않음
팀 내부 반복 작업 Plugin → workspace sharing
repo별 표준 Plugin       → repo marketplace
조직 전체 표준 Plugin    → managed marketplace 또는 organization policy
외부 공개 가능 Plugin    → public / curated distribution 검토

08Plugin hooks

Plugin은 hooks를 포함할 수 있습니다. Plugin root에는 hooks/ 디렉터리를 둘 수 있고, 그 안에 lifecycle hooks 설정을 담을 수 있습니다.

예상 구조는 다음과 같습니다.

my-plugin/
  .codex-plugin/
    plugin.json
  skills/
    my-skill/
      SKILL.md
  hooks/
    hooks.json
  .mcp.json
  .app.json
  assets/

Plugin hooks는 다음 상황에서 유용합니다.

작업 시작 시 팀 정책 안내
위험한 shell 명령 차단
변경 후 테스트 실행 유도
secret 포함 여부 검사
PR 리뷰 전에 diff 확인 강제
특정 MCP tool 사용 전 승인 요구

09Plugin enable / disable

Plugin은 설치와 활성화 상태가 분리됩니다.

설치된 Plugin을 완전히 제거하려면 Plugin browser에서 uninstall을 선택합니다.

설치된 Plugin을 유지하되 꺼두려면 ~/.codex/config.toml에서 다음처럼 설정할 수 있습니다.

[plugins."gmail@openai-curated"]
enabled = false

설정 후 Codex를 재시작하면 됩니다.

관리 관점에서는 다음 기준이 좋습니다.

자주 쓰는 Plugin        → enabled = true
가끔 쓰는 Plugin        → 필요할 때만 enable
보안상 민감한 Plugin    → 기본 disabled
팀 표준 Plugin          → repo 또는 workspace 기준으로 enable
실험용 Plugin           → 개인 config에서만 enable

10팀에서 Plugins를 관리하는 방법

팀 단위에서는 Plugin을 무작정 늘리면 안 됩니다. Plugin은 Skills, MCP, apps, hooks를 함께 묶을 수 있기 때문에 편리하지만, 보안과 유지보수 책임도 커집니다.

팀 운영 원칙은 다음과 같습니다.

먼저 Skill로 만든다.
반복 사용 가치가 확인되면 Plugin으로 묶는다.
외부 도구 접근이 필요한 경우 MCP 권한을 최소화한다.
hooks는 강제 정책이 필요한 경우에만 넣는다.
marketplace.json으로 설치 경로를 표준화한다.
version, author, repository, license 정보를 명확히 적는다.
팀원이 설치하기 전에 어떤 데이터에 접근하는지 문서화한다.
deprecated Plugin은 marketplace에서 제거하거나 NOT_AVAILABLE로 바꾼다.

11Plugin manifest 예시

Plugin manifest는 .codex-plugin/plugin.json에 둡니다. 이 manifest는 Plugin 식별, bundled components 연결, 설치 화면에 표시되는 metadata 제공이라는 세 가지 역할을 합니다.

{
  "name": "team-pr-review",
  "version": "0.1.0",
  "description": "Bundle team PR review skills and review automation.",
  "author": {
    "name": "Engineering Team",
    "email": "[email protected]"
  },
  "repository": "https://github.com/example/team-codex-plugins",
  "license": "MIT",
  "keywords": ["review", "quality", "pull-request"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

초보 팀은 처음부터 거창한 Plugin 체계를 만들 필요가 없습니다. 가장 좋은 순서는 다음입니다.

1단계: .agents/skills에 팀 Skill 추가
2단계: 사용률 높은 Skill만 Plugin으로 묶기
3단계: repo marketplace.json 만들기
4단계: 팀원에게 /plugins에서 설치하게 하기
5단계: 외부 도구가 필요한 Plugin에만 MCP 추가
6단계: 검증된 Plugin만 workspace sharing

12Plugin이 설치되어 있는지 확인

Plugin이 동작하지 않을 때는 체계적으로 확인합니다. 가장 먼저 확인할 것은 Plugin의 설치 상태입니다.

CLI에서는 /plugins를 열어 설치 상태를 확인합니다.

codex
/plugins

설치되어 있지 않다면 Plugin Directory나 marketplace에서 다시 설치합니다.

13Plugin이 disabled 상태인지 확인

~/.codex/config.toml에 다음처럼 되어 있으면 Plugin이 꺼진 상태입니다.

[plugins."plugin-name@marketplace-name"]
enabled = false

사용하려면 true로 바꾸거나 해당 항목을 제거한 뒤 Codex를 재시작합니다.

또한 marketplace가 제대로 인식되는지도 확인해야 합니다.

codex plugin marketplace list

Git 기반 marketplace를 쓰고 있다면 최신 상태로 갱신합니다.

codex plugin marketplace upgrade

14marketplace.json 경로와 plugin.json 확인

repo marketplace라면 위치는 보통 다음입니다.

$REPO_ROOT/.agents/plugins/marketplace.json

source.path는 marketplace root 기준 상대 경로여야 하며, 일반적으로 ./로 시작합니다.

Plugin manifest의 올바른 위치는 다음과 같습니다.

my-plugin/
  .codex-plugin/
    plugin.json

주의할 점은 .codex-plugin/ 안에는 plugin.json만 두고, skills/, hooks/, assets/, .mcp.json, .app.json은 Plugin root에 둔다는 것입니다.

15인증 문제 및 MCP 확인

Plugin이 Gmail, Slack, Google Drive 같은 외부 앱을 포함한다면 인증이 필요할 수 있습니다. 일부 Plugin은 설치 중 인증을 요구하고, 일부는 처음 사용할 때 인증을 요구합니다.

Plugin에 .mcp.json이 포함되어 있다면 MCP 서버가 정상 실행되는지도 확인해야 합니다.

점검 항목은 다음과 같습니다.

MCP 서버 명령이 존재하는가
필요한 env가 설정되어 있는가
OAuth 또는 token 인증이 끝났는가
tool allowlist / denylist가 너무 좁지 않은가
sandbox 또는 approval 설정이 MCP 실행을 막고 있지 않은가

Plugin 설치 후에는 새 thread에서 사용하는 것이 안전합니다.

섹션 19 · 마무리

이 단원에서 기억할 것

Plugins는 Codex 기능을 팀과 조직 단위로 배포하기 위한 설치 가능한 패키지입니다.

Skill로 작업 방식을 만들고, Plugin으로 설치 가능하게 묶으며, Marketplace로 배포합니다. Workspace sharing으로 팀에 공유하고, config.toml로 enable / disable을 관리합니다.

초보자에게 추천하는 첫 Plugin은 다음과 같습니다.

team-pr-review plugin
test-writer plugin
release-notes plugin
security-review plugin
docs-maintainer plugin

처음에는 Skill 하나만 담은 단순 Plugin으로 시작하고, 실제로 반복 사용되는 것이 확인되면 MCP, hooks, app integration을 추가하는 방식이 가장 안전합니다.

다음 단원

20단원. Plan Mode와 협업 방식

20. Plan Mode와 협업 방식

01Plan Mode란 무엇인가

Plan Mode는 Codex가 구현 전에 다음 작업을 먼저 하도록 만드는 모드입니다.

1. 요구사항을 이해한다.
2. 관련 파일과 구조를 살핀다.
3. 모호한 부분을 질문한다.
4. 변경 범위를 제안한다.
5. 실행 순서를 계획한다.
6. 위험 요소와 검증 방법을 정리한다.
7. 사용자가 승인하면 구현으로 넘어간다.

/plan 또는 Shift + Tab으로 Plan Mode를 켤 수 있습니다.

기본 사용법:

codex
/plan

02Plan Mode 실행 방법

단순히 /plan만 입력하거나, 처음부터 요청과 함께 줄 수 있습니다.

slash command 입력:

/plan 로그인 로직을 OAuth 기반으로 바꾸는 마이그레이션 계획을 세워줘.

/plan을 입력하고 Enter를 누르면 현재 대화가 Plan Mode로 전환되며, inline prompt도 함께 줄 수 있습니다. 단, 이미 작업이 실행 중인 동안에는 /plan을 사용할 수 없습니다.

03직접 실행과 Plan Mode의 차이

직접 실행은 바로 파일을 읽고 수정하는 방식입니다.

로그인 실패 시 에러 메시지가 안 뜨는 버그를 고쳐줘.

반면 Plan Mode는 구현보다 설계를 먼저 합니다.

/plan 로그인 실패 처리 흐름을 점검하고, 에러 메시지 표시 구조를 개선하는 계획을 세워줘.

04직접 실행 vs Plan Mode 비교

실무에서는 "작은 수정은 직접 실행, 구조 변경은 Plan Mode"로 나누면 됩니다.

목적

직접 실행: 바로 수정 | Plan Mode: 먼저 분석하고 계획

적합한 작업

직접 실행: 작고 명확한 버그 수정 | Plan Mode: 리팩터링, 마이그레이션, 설계 변경

위험도

직접 실행: 변경이 빠르지만 방향이 어긋날 수 있음 | Plan Mode: 느리지만 검토 가능

사용자 개입

직접 실행: 결과 diff 검토 중심 | Plan Mode: 계획 단계부터 개입

05언제 /plan을 써야 하는가

다음 상황에서는 바로 실행하지 말고 /plan부터 쓰는 것이 좋습니다.

변경 파일이 여러 개일 것 같다.
요구사항이 아직 모호하다.
기존 구조를 먼저 이해해야 한다.
DB migration이 포함된다.
인증, 결제, 권한, 보안 로직이 포함된다.
테스트 전략이 필요하다.
실패하면 되돌리기 어려운 작업이다.
팀원에게 변경 방향을 설명해야 한다.
PR을 여러 단계로 나눠야 한다.

06/plan이 적합한 예시

예를 들어 다음 요청들은 직접 실행보다 Plan Mode가 적합합니다.

/plan 기존 REST API를 GraphQL로 점진적으로 옮기는 계획을 세워줘.

/plan 현재 결제 플로우에서 중복 결제가 발생할 수 있는 지점을 찾고 개선 계획을 세워줘.

/plan 이 모노레포에서 공통 UI 컴포넌트 패키지를 분리하는 작업 계획을 세워줘.

반대로 범위가 작고 명확하면 바로 실행해도 됩니다.

Button 컴포넌트의 disabled 스타일이 빠져 있어. 추가해줘.

07큰 리팩터링에서 Plan Mode 사용하기

나쁜 요청: 너무 넓어서 Codex가 어떤 기준으로 구조를 바꿔야 하는지 알기 어렵습니다.

이 프로젝트 구조를 깔끔하게 리팩터링해줘.

좋은 요청: 목표와 제약을 명확히 전달합니다.

/plan src/api와 src/services의 역할이 섞여 있는 것 같아.
현재 구조를 분석하고, public API는 유지하면서 service layer를 정리하는
단계별 리팩터링 계획을 세워줘.
테스트가 깨지지 않도록 각 단계마다 검증 명령도 포함해줘.

08큰 리팩터링 계획에 포함할 항목

리팩터링에서는 "무엇을 바꿀지"만큼 "무엇을 바꾸지 않을지"가 중요합니다.

현재 구조 요약
문제점
변경하지 않을 것
변경할 것
단계별 실행 순서
각 단계의 예상 diff 범위
테스트와 검증 명령
rollback 전략
PR 분리 기준

예시 제약:

공개 API, DB schema, route path는 바꾸지 말고
내부 구조만 정리해줘.

09모호한 요구사항 정리하기

Plan Mode의 가장 큰 장점은 모호한 요구사항을 실행 가능한 작업으로 바꾸는 데 있습니다.

모호한 상태:

대시보드가 너무 느린데 개선해줘.

Plan Mode로 진단 계획을 세우기:

/plan 대시보드 성능 개선 계획을 세워줘.
먼저 병목을 추정하지 말고, 어떤 파일과 측정 지표를 봐야 하는지부터 정리해줘.
필요하면 나에게 확인 질문을 해줘.

10계획 검토 기준

Plan Mode의 핵심은 "계획을 만든 뒤 사용자가 검토하고 실행 여부를 결정한다"는 점입니다. 계획을 받은 뒤에는 다음 기준으로 검토합니다.

목표 파악

목표를 정확히 이해했는가

범위 점검

변경 범위가 너무 넓지 않은가

위험 파일

위험한 파일을 건드리지 않는가

테스트 계획

테스트 계획이 있는가

복구 전략

rollback이 가능한가

PR 분리

PR을 나눌 필요가 있는가

11계획 검토 후 실행 요청 예시

검토 후 실행할 때는 한 번에 전체를 실행시키기보다 작은 단위로 나누는 것이 좋습니다.

좋아. Step 1만 먼저 실행해줘. Step 2 이후는 아직 하지 마.

계획은 괜찮아. 단, DB migration은 제외하고 service layer 정리까지만 진행해줘.

Step 1과 Step 2를 실행하고, 테스트 결과를 보고한 뒤 멈춰줘.

이 계획은 범위가 커. PR 3개로 나눌 수 있게 다시 쪼개줘.

이 흐름을 지키면 Codex가 방향을 벗어나도 빨리 되돌릴 수 있습니다.

12Enter와 Tab으로 작업 흐름 제어하기

Codex가 실행 중일 때 Enter와 Tab으로 작업 흐름을 제어할 수 있습니다.

Enter

지금 실행 중인 작업에 끼어들기 (즉시 중단 또는 수정 지시)

Tab

다음 작업으로 예약하기 (현재 작업 완료 후 실행)

예를 들어 Codex가 계획을 세우는 중인데 중요한 제한을 빠뜨렸다면 Enter로 바로 추가합니다.

잠깐, public API는 절대 바꾸지 말고 계획을 다시 세워줘.

13Tab으로 다음 작업 예약하기

Codex가 현재 작업을 끝낸 뒤 바로 리뷰를 하게 만들고 싶다면 Tab으로 다음 명령을 예약할 수 있습니다.

/review

또는 테스트 실행을 queue에 넣을 수 있습니다.

!pnpm test

작업 중 개입 기준:

Enter 사용

현재 방향이 틀렸거나, 중요한 제약을 빠뜨렸을 때

Tab 사용

다음에 리뷰, 테스트, 후속 질문을 예약하고 싶을 때

14협업형 프롬프트 작성법

Plan Mode를 잘 쓰려면 Codex에게 "정답을 바로 내라"고 요구하기보다, 함께 문제를 좁혀가게 해야 합니다.

나쁜 프롬프트:

전체 구조 개선해줘.

좋은 프롬프트:

/plan 현재 src/modules 구조를 분석하고, import cycle을 줄이는 리팩터링 계획을 세워줘.
공개 API와 route path는 유지해야 해.
먼저 변경 후보 파일을 분류하고, 위험도가 낮은 순서로 단계화해줘.
각 단계마다 실행할 테스트 명령도 포함해줘.

15협업형 프롬프트 기본 구조

협업형 프롬프트의 기본 구조는 다음과 같습니다.

목표
현재 문제
변경하지 말아야 할 것
우선순위
검증 방법
질문 요청
원하는 출력 형식

좋은 프롬프트는 목표와 제약을 명확히 하고, 무엇을 먼저 확인해야 하는지, 어떤 질문을 해야 하는지 구체적으로 지시합니다.

16협업형 프롬프트 템플릿

실제 상황에서 사용할 수 있는 템플릿입니다.

/plan [목표]를 달성하기 위한 계획을 세워줘.

현재 문제:
- [문제 1]
- [문제 2]

제약:
- [바꾸면 안 되는 것]
- [유지해야 하는 동작]

요청:
- 먼저 관련 파일을 파악해줘.
- 모호한 점은 질문해줘.
- 구현 전에 단계별 계획을 제시해줘.

17실무 예시 1: 인증 리팩터링

실제 상황에서 어떻게 프롬프트를 작성할 수 있는지 보여줍니다.

/plan 인증 로직을 정리하려고 해.

목표:
- 로그인, 토큰 갱신, 로그아웃 흐름을 분리
- 기존 API 응답 형식은 유지
- 테스트가 깨지지 않게 점진적으로 변경

제약:
- DB schema 변경 금지
- public route 변경 금지
- 기존 refresh token 동작 유지

요청:
- 현재 인증 관련 파일을 먼저 분류해줘.
- 위험한 변경과 안전한 변경을 나눠줘.
- PR 2~3개로 쪼갤 수 있게 계획해줘.

18실무 예시 2: 성능 개선

성능 개선처럼 병목이 불명확한 경우 Plan Mode가 특히 유용합니다.

/plan 대시보드 초기 로딩 속도를 개선하고 싶어.

목표:
- 첫 화면 렌더링 시간 단축
- 불필요한 API 호출 제거
- UX 변경은 최소화

제약:
- 디자인은 바꾸지 않음
- API contract는 유지

요청:
- 먼저 병목 후보를 찾는 조사 계획을 세워줘.
- 측정 가능한 지표를 제안해줘.
- 바로 구현하지 말고, 어떤 데이터를 확인해야 하는지 먼저 말해줘.

19실무 예시 3: 마이그레이션

기술 마이그레이션은 변경 범위가 크고 위험하므로 Plan Mode가 필수입니다.

/plan Jest에서 Vitest로 테스트 환경을 옮기는 계획을 세워줘.

제약:
- 한 번에 전체 테스트를 바꾸지 말 것
- CI가 깨지지 않게 병행 기간을 둘 것
- 기존 jest-specific mock 사용처를 먼저 파악할 것

출력:
- 영향 범위
- 단계별 마이그레이션 계획
- 위험 요소
- PR 분리안
- 검증 명령

20Plan Mode의 핵심 패턴

작업의 복잡도에 따라 다음과 같이 사용합니다.

작은 수정

직접 실행

애매한 작업

/plan

큰 리팩터링

/plan 후 단계별 승인

위험한 변경

/plan + 테스트 계획 + rollback 기준

장기 작업

/plan 후 /goal로 연결

21가장 실용적인 실행 패턴

여러 단계로 나누어 진행하면 방향을 벗어나도 빨리 되돌릴 수 있습니다.

1/plan으로 계획 수립

2사용자가 범위 조정

3Step 1만 승인

4diff 확인

5테스트 실행

6다음 step 진행

22초보자를 위한 핵심 메시지

Plan Mode의 모든 개념을 한 문장으로 정리하면 다음과 같습니다.

바로 고치지 말고, 먼저 계획을 세우고 내가 승인하면 Step 1부터 진행해줘.

이 원칙만 지켜도 Codex를 훨씬 더 안전하고 예측 가능하게 사용할 수 있습니다.

섹션 20 · 마무리

이 단원에서 기억할 것

Plan Mode는 복잡한 작업을 안전하게 처리하기 위한 협업 모드입니다. Codex가 더 오래 생각하게 만드는 것만이 아니라, 사용자가 작업 방향을 검토하고, 위험을 줄이고, 실행 단위를 통제할 수 있게 만드는 것이 핵심입니다.

계획 수립 → 범위 조정 → 단계별 승인 → 검증 → 다음 단계 진행 의 흐름을 지키면, Codex가 방향을 벗어나도 빨리 되돌릴 수 있습니다.

다음 단원

21단원. Goal Mode

21. Goal Mode

01Goal Mode란 무엇인가

Goal Mode는 Codex가 하나의 지속 목표를 기준으로 여러 단계의 작업을 계속 이어가게 하는 기능입니다. 20장의 Plan Mode가 "먼저 계획을 세우는 모드"라면, Goal Mode는 "그 계획을 끝까지 밀고 가는 모드"에 가깝습니다.

기본 형태는 다음과 같습니다.

/goal Finish the migration and keep tests green

한국어 예시:

/goal 인증 리팩터링을 완료하고, 관련 테스트가 모두 통과하는 상태까지 진행해줘.

02Goal Mode가 적합한 작업

Goal Mode는 다음과 같은 작업에 특히 적합합니다.

마이그레이션 완료

데이터베이스, 프레임워크, 라이브러리 전환

테스트 실패 끝까지 고치기

모든 테스트가 통과할 때까지 진행

릴리즈 준비 작업

변경사항 정리, 문서, 버전 업데이트

대규모 리팩터링

코드베이스 정리, 구조 개선

문서와 테스트 함께 업데이트

기능 추가 시 관련 모든 자료 동시 수정

평가 점수 개선

기준을 넘을 때까지 반복 개선

핵심은 "작업 한 번"이 아니라 "완료 조건이 있는 장기 목표"를 준다는 점입니다.

03좋은 Goal 만들기 — 완료 조건 필수

좋은 goal에는 반드시 완료 조건이 있어야 합니다.

나쁜 goal:

/goal 코드를 개선해줘.

이 목표는 너무 넓어서 무엇을 개선해야 하는지, 언제 끝났다고 봐야 하는지 알기 어렵습니다.

좋은 goal:

/goal 결제 모듈의 타입 오류를 모두 해결하고,
pnpm test:payment와 pnpm lint가 통과하는 상태까지 진행해줘.

이 goal은 목표, 범위, 완료 조건을 명확히 포함합니다.

04좋은 Goal 작성 템플릿

goal을 명확하게 작성하기 위한 템플릿입니다.

/goal [작업 목표]를 완료해줘.

범위:
- [대상 파일/모듈/기능]

완료 조건:
- [테스트 명령] 통과
- [빌드 명령] 통과
- [문서 업데이트]
- [diff 요약 보고]

제약:
- [건드리면 안 되는 것]
- [유지해야 할 API]
- [허용하지 않는 변경]

실무 예시:

/goal 사용자 설정 페이지의 접근성 문제를 개선해줘.

범위:
- src/pages/settings
- src/components/settings

완료 조건:
- 키보드 탐색 가능
- aria-label 누락 해결
- pnpm test settings 통과
- 변경 파일과 이유를 마지막에 요약

제약:
- 디자인 토큰은 변경하지 말 것
- 라우트 경로는 유지할 것

05goal 생성하기

CLI 또는 앱 composer에서 /goal <objective> 형식으로 goal을 만듭니다.

/goal Finish the Vitest migration and keep CI green.

한국어 예시:

/goal Jest에서 Vitest로의 1차 마이그레이션을 완료하고,
기존 테스트가 통과하는 상태까지 진행해줘.

현재 goal을 확인하려면 인자 없이 /goal을 입력합니다.

/goal

goal objective는 최대 4,000자까지 허용됩니다. 더 긴 지침은 별도 파일에 작성한 뒤 goal에서 참조하는 방식이 권장됩니다.

/goal docs/goals/vitest-migration.md의 완료 조건을 기준으로
Vitest 마이그레이션을 진행해줘.

06goal 일시 중지하기

Goal Mode가 진행 중일 때 잠시 멈추려면 /goal pause를 사용합니다.

/goal pause

일시 중지가 필요한 상황:

방향이 맞는지 중간 검토

예상과 다른 방향으로 진행될 때

diff가 예상보다 커짐

변경 범위가 의도한 것보다 넓을 때

테스트 실패 원인 확인

사용자가 직접 확인이 필요할 때

외부 승인이나 리뷰 필요

진행 전 다른 사람의 검토 필요

범위 재조정

Codex가 너무 넓게 작업할 때

사용 예시:

/goal pause
현재까지 변경한 파일과 남은 작업을 요약해줘.

07goal 재개 및 삭제하기

goal 재개 — 멈춘 goal을 다시 시작하려면 /goal resume을 사용합니다.

/goal resume

재개할 때는 사용자가 수정한 조건을 함께 전달합니다.

/goal resume
다만 Step 3은 제외하고, 현재 변경분의 테스트 안정화까지만 진행해줘.

goal 삭제 — 현재 goal을 제거하려면 /goal clear를 사용합니다.

/goal clear

goal을 clear해야 하는 경우: 목표가 바뀌었을 때, 현재 thread를 다른 작업에 쓰고 싶을 때, 목표가 너무 넓게 설정되었을 때, 이미 완료되었을 때, 새로운 Plan Mode 흐름으로 다시 시작하고 싶을 때입니다.

goal을 바꾸려면 기존 goal을 clear한 뒤 새 goal을 설정하는 방식이 가장 명확합니다.

08장기 작업에서 goal을 쓰는 방법

장기 작업에서 추천되는 흐름:

/plan으로 먼저 계획을 만든다.
계획을 검토하고 범위를 줄인다.
완료 조건을 명확히 정한다.
/goal로 지속 목표를 설정한다.
중간중간 diff와 테스트 결과를 확인한다.
필요하면 /goal pause로 멈춘다.
방향을 조정한 뒤 /goal resume으로 이어간다.
완료 후 /goal clear로 정리한다.

예시: 테스트 마이그레이션

/plan Jest에서 Vitest로 마이그레이션하는 계획을 세워줘.
단, 한 번에 전체를 바꾸지 말고 packages/auth부터 시작하는 단계별 계획으로 만들어줘.

계획 검토 후:

/goal packages/auth의 Jest 테스트를 Vitest로 옮기고,
pnpm test --filter auth가 통과하는 상태까지 진행해줘.
제약: 공통 테스트 유틸은 아직 바꾸지 말고, auth 패키지 내부 변경만 허용해.

09장기 작업 예시 ① — 릴리즈 준비

릴리즈 준비 goal:

/goal v2.3.0 릴리즈 준비를 완료해줘.

완료 조건:
- changelog 초안 작성
- version bump 후보 확인
- breaking change 여부 점검
- pnpm test 통과
- PR 설명 초안 작성

제약:
- 실제 tag 생성이나 publish는 하지 말 것

10장기 작업 예시 ② — 어려운 문제 반복 개선

평가 점수 기반 goal:

/goal eval 점수가 0.85 이상이 될 때까지 프롬프트와 테스트 케이스를
반복 개선해줘.

완료 조건:
- npm run eval 통과
- score >= 0.85
- 변경한 프롬프트와 실패 사례 요약

어려운 작업에서는 평가 시스템이나 스크립트를 주고, 점수가 충분히 좋아질 때까지 Codex가 반복 개선하도록 하는 패턴이 효과적입니다.

11CLI, Desktop App, IDE에서 Goal Mode

CLI에서 사용

Slash command로 제어합니다.

/goal <objective>
/goal
/goal pause
/goal resume
/goal clear

/goal이 보이지 않으면 config.toml에서 기능 플래그를 켭니다.

[features]
goals = true

또는:

codex features enable goals

Desktop App에서 사용

Composer에서 /goal을 입력합니다. Goal이 활성화되면 composer 위에 progress row가 표시되며, 버튼으로 pause, resume, goal 편집, clear를 제어할 수 있습니다.

12IDE extension에서 Goal Mode

IDE extension에서도 Goal Mode를 사용할 수 있습니다. 현재 열려 있는 파일, 선택 영역, diagnostics, test failure를 바탕으로 goal을 주기 좋습니다.

IDE 사용 예시:

/goal 현재 열려 있는 checkout flow 관련 타입 오류를 해결하고,
이 모듈의 테스트가 통과하는 상태까지 진행해줘.

IDE에서는 범위를 좁히는 것이 중요합니다.

나쁜 목표:

/goal 전체 프로젝트 타입 오류를 다 고쳐줘.

좋은 목표:

/goal src/features/checkout 안의 타입 오류를 해결하고,
pnpm typecheck --filter checkout이 통과하는 상태까지 진행해줘.

섹션 21 · 마무리

Goal Mode 핵심 정리

Goal Mode는 Codex에게 지속 목표를 주고, 완료 조건을 기준으로 여러 단계의 작업을 이어가게 하는 기능입니다.

Plan Mode

무엇을 어떻게 할지 먼저 계획

Goal Mode

정해진 목표를 끝까지 진행

가장 좋은 사용 패턴:

/plan으로 계획 수립 → 사용자가 범위와 완료 조건 확정 → /goal로 지속 목표 설정 → 중간에 /goal pause로 검토 → /goal resume으로 재개 → 완료 후 /goal clear

초보자가 바로 쓸 수 있는 기본 문장:

/goal [작업]을 완료하고, [검증 명령]이 통과하는 상태까지 진행해줘.
제약: [바꾸면 안 되는 것]은 유지해줘.

다음 단원

22단원. Memory System

22. Memory System

01Codex memory란 무엇인가

Codex memory는 Codex가 과거 thread에서 얻은 유용한 정보를 이후 작업에 참고할 수 있게 해주는 로컬 기억 시스템입니다. 예를 들어 사용자가 자주 쓰는 기술 스택, 선호하는 작업 방식, 프로젝트 관례, 반복되는 실수, 자주 쓰는 명령어 같은 정보를 기억해두면 새 세션마다 같은 설명을 반복하지 않아도 됩니다.

Memory가 켜져 있으면 Codex는 이런 반복 패턴을 기억하고, 이후 비슷한 작업에서 참고할 수 있습니다.

예를 들어 매번 이렇게 말하지 않아도 됩니다.

이 프로젝트는 pnpm을 써.
테스트는 npm test가 아니라 pnpm test로 돌려.
DB migration 파일은 직접 수정하지 말고 새 migration을 추가해야 해.
API 응답 타입은 zod schema에서 먼저 수정해야 해.

02Memory의 본질: 규칙이 아닌 회상 레이어

단, memory는 "규칙 파일"이 아니라 "도움이 되는 회상 레이어"에 가깝습니다. 반드시 지켜야 하는 팀 규칙, 빌드 명령, 금지 작업, 보안 지침은 memory가 아니라 AGENTS.md나 저장소 문서에 넣어야 합니다.

공식 문서도 필수 팀 지침은 AGENTS.md 또는 체크인된 문서에 보관하고, memory는 로컬 recall layer로 다루라고 권장합니다.

반드시 지켜야 하는 것은 memory가 아니라 AGENTS.md에 둡니다.

03memory와 AGENTS.md의 차이

초보자가 가장 헷갈리는 부분은 memory와 AGENTS.md의 역할 차이입니다.

AGENTS.md는 Codex에게 주는 명시적 지침입니다. 프로젝트에 들어 있는 작업 규칙, 코딩 스타일, 테스트 명령, 금지 사항, 리뷰 기준 같은 내용을 사람이 직접 작성합니다.

반면 memory는 Codex가 이전 세션에서 반복적으로 유용하다고 판단한 정보를 저장해두는 시스템입니다. 사람이 직접 "이 규칙을 반드시 지켜라"라고 선언하는 문서가 아니라, Codex가 과거 맥락에서 배운 내용을 이후 세션에 참고하는 방식입니다.

구분

AGENTS.md

Memory

성격

명시적 지침

자동 또는 반자동 기억

작성 주체

사람

Codex가 이전 thread에서 생성

위치

프로젝트 또는 Codex home

기본적으로 ~/.codex/memories/

용도

반드시 지켜야 할 규칙

반복되는 선호·맥락·작업 패턴 회상

팀 공유

가능, 저장소에 커밋 가능

기본적으로 로컬 상태

보안 민감도

관리 가능한 문서

자동 생성물이므로 검토 필요

04초보자를 위한 구분법

초보자 기준으로는 이렇게 기억하면 됩니다.

반드시 지켜야 하면 AGENTS.md
반복적으로 참고하면 memory
팀 전체가 알아야 하면 AGENTS.md
나만 자주 쓰는 습관이면 memory

05memory가 유용한 상황 ①②

Memory는 매번 설명하기 귀찮은 반복 맥락을 줄여줄 때 가장 유용합니다.

첫 번째: 개인 작업 습관

나는 변경 전에 항상 plan을 먼저 받고 싶다.
큰 변경은 작은 diff 단위로 나눠서 처리해라.
답변은 한국어로 하되 코드 주석은 영어로 유지해라.

두 번째: 프로젝트별 반복 패턴

이 저장소는 pnpm workspace 구조다.
프론트엔드는 apps/web에 있고, 백엔드는 services/api에 있다.
테스트는 루트가 아니라 패키지별로 실행한다.

06memory가 유용한 상황 ③④

세 번째: 자주 발생하는 실수 방지

이 프로젝트에서는 generated 파일을 직접 수정하지 않는다.
schema 변경 후에는 반드시 codegen을 다시 실행한다.
마이그레이션 파일 이름은 timestamp prefix를 붙인다.

네 번째: 장기 작업의 맥락 유지

여러 날에 걸쳐 리팩터링하거나, 특정 모듈의 설계 방향을 계속 이어가야 할 때 memory가 도움이 됩니다. Codex는 memory가 활성화된 뒤 eligible prior thread에서 유용한 context를 local memory file로 만들 수 있고, active 또는 short-lived session은 건너뛰며, memory 업데이트도 즉시가 아니라 background에서 처리될 수 있습니다.

07고급 기능: Chronicle

고급 기능으로는 Chronicle도 있습니다. Chronicle은 Codex app의 memory 기능을 화면 context와 결합해 최근 작업 흐름을 더 잘 기억하게 해주는 opt-in research preview 기능입니다.

다만 macOS의 Screen Recording 및 Accessibility 권한이 필요하고, rate limit을 빠르게 소모할 수 있으며, prompt injection 위험과 민감정보 노출 위험이 커질 수 있습니다.

초보자는 Chronicle부터 켜기보다 일반 memory부터 이해하는 것이 좋습니다.

08memory 사용 시 주의점 ① 오래된 정보

Memory는 편리하지만, 무조건 많이 저장한다고 좋은 기능이 아닙니다. 잘못된 기억이 쌓이면 Codex가 반복적으로 잘못된 가정을 할 수 있습니다.

주의점 1. 오래된 정보

예를 들어 예전에는 npm을 썼지만 지금은 pnpm으로 바꿨다면, memory에 남아 있는 오래된 정보가 작업을 방해할 수 있습니다. 이런 경우에는 memory를 점검하거나 삭제해야 합니다.

09memory 사용 시 주의점 ② 임시 결정

주의점 2. 임시 결정과 장기 규칙 구분

이번 작업에서만 임시로 테스트를 생략한다.
오늘은 빠르게 mock으로 처리한다.
이 브랜치에서는 일단 타입 에러를 무시한다.

이런 내용은 memory로 남으면 위험합니다. "이번만" 필요한 판단이 장기 규칙처럼 작동할 수 있기 때문입니다.

10memory 사용 시 주의점 ③ 외부 context

주의점 3. 외부 context가 섞인 작업

Codex memory 설정에는 MCP tool call, web search, tool search 같은 외부 context를 사용한 thread를 memory 생성 대상에서 제외하는 옵션이 있습니다. 공식 설정 키로는 memories.disable_on_external_context가 있으며, 외부 도구에서 가져온 일시적 정보가 장기 memory로 굳어지는 것을 줄이는 데 도움이 됩니다.

11초보자 권장 설정

초보자에게는 다음 설정을 권장합니다.

[features]
memories = true

[memories]
use_memories = true
generate_memories = true
disable_on_external_context = true
min_rate_limit_remaining_percent = 20

이 설정은 memory를 사용하되, 외부 context가 섞인 thread는 memory 생성에서 제외하고, rate limit이 너무 낮을 때는 memory 생성을 줄이는 방향입니다.

12팀 프로젝트에서 memory 다루기

팀 프로젝트에서는 memory를 "팀 규칙 저장소"로 쓰면 안 됩니다. 팀 전체가 반드시 따라야 하는 내용은 다음 위치에 둬야 합니다.

AGENTS.md
README.md
CONTRIBUTING.md
docs/
architecture 문서
코딩 컨벤션 문서

Memory는 기본적으로 로컬 상태이기 때문에 팀원마다 다를 수 있습니다. 따라서 팀 규칙을 memory에만 의존하면 재현성이 떨어집니다.

13팀에서 안전하게 사용하는 기준

팀에서 memory를 안전하게 사용하는 기준은 다음과 같습니다.

팀 규칙

AGENTS.md

개인 선호

memory

반드시 재현되어야 하는 명령

AGENTS.md

자주 반복되는 개인 작업 흐름

memory

보안·배포·권한 규칙

AGENTS.md 또는 관리 문서

14AGENTS.md 예시

다음 내용은 AGENTS.md에 넣는 것이 좋습니다.

# AGENTS.md

## Test commands

- Frontend: pnpm --filter web test
- API: pnpm --filter api test
- Typecheck: pnpm typecheck

## Rules

- Do not edit generated files directly.
- Do not commit .env files.
- Ask before adding new production dependencies.

15Memory에 적합한 개인 선호

반면 다음은 memory에 남아도 괜찮은 개인 선호에 가깝습니다.

나는 리팩터링 전에 변경 범위 요약을 먼저 받고 싶다.
답변은 한국어로 설명하고, 코드 식별자는 원문 그대로 유지해라.
작업 후에는 내가 확인할 수 있도록 diff 중심으로 요약해라.

팀에서는 memory가 아니라 AGENTS.md를 기준 문서로 삼고, memory는 개인 생산성 보조 도구로만 사용하는 것이 안전합니다.

16개인정보와 보안 고려사항

Memory에는 민감정보가 들어가면 안 됩니다. Codex는 memory 생성 과정에서 secret을 redaction할 수 있지만, 공식 문서도 memory file이나 generated memory artifact를 공유하기 전에는 반드시 검토하라고 경고합니다.

memory file은 기본적으로 Codex home 아래에 저장되며, 기본 경로는 ~/.codex/memories/입니다.

17절대 memory에 남기면 안 되는 정보

절대 memory에 남기면 안 되는 정보는 다음과 같습니다.

API key
access token
비밀번호
DB 접속 문자열
고객 개인정보
내부 장애 보고서의 민감 내용
비공개 계약 정보
보안 취약점 세부 exploit

18Memory 파일 다루기

Memory 관련 파일은 생성된 상태값으로 취급해야 합니다. 문제를 디버깅하거나 Codex home 디렉터리를 공유하기 전에 열어볼 수는 있지만, 일반적인 제어 방식으로 직접 편집하는 데 의존하면 안 됩니다.

현재 thread에서 memory 사용 여부를 조정하고 싶다면 Codex app이나 TUI에서 /memories를 사용할 수 있습니다. 이 명령은 현재 thread가 기존 memory를 사용할지, 현재 thread가 미래 memory 생성에 사용될 수 있을지를 제어하는 데 쓰입니다. 단, thread-level 선택은 global memory 설정을 바꾸지는 않습니다.

19실무에서 안전하게 쓰는 6가지 원칙

실무에서 안전하게 쓰려면 다음 원칙을 지키면 됩니다.

secret은 prompt에도 넣지 말고 memory에도 남기지 않는다.
팀 규칙은 AGENTS.md에 둔다.
memory는 개인 로컬 보조 기억으로만 본다.
외부 context가 섞인 작업은 memory 생성을 끄는 편이 안전하다.
Codex home 디렉터리를 공유하기 전에는 memories 폴더를 확인한다.
오래되거나 잘못된 memory는 정리한다.

섹션 22 · 마무리

이 단원에서 기억할 것

Memory는 Codex가 나를 덜 반복하게 해주는 기능입니다. 하지만 반드시 지켜야 하는 규칙은 memory가 아니라 AGENTS.md에 둬야 합니다. 민감정보는 memory에 남기지 않습니다.

Memory는 개인 보조 기억, 팀 규칙은 AGENTS.md입니다.

다음 단원

23단원. Session Management

23. Session Management

01session이란 무엇인가

Codex에서 session은 단순한 채팅 기록이 아니라, 특정 작업을 이어가기 위한 작업 공간에 가깝습니다.

초보자는 session을 이렇게 이해하면 됩니다.

session = Codex와 함께 진행 중인 하나의 작업 단위

예를 들어 다음은 각각 별도 session으로 나누는 것이 좋습니다.

세션 A: 로그인 버그 수정
세션 B: 결제 API 리팩터링
세션 C: README 문서 정리
세션 D: 테스트 실패 원인 분석

한 session 안에는 Codex가 본 파일, 사용자의 지시, Codex가 실행한 명령, 수정한 코드, 결정한 방향이 누적됩니다.

02thread란 무엇인가

thread는 Codex와 사용자 사이의 실제 대화 흐름입니다. thread는 사용자와 Codex agent 사이의 대화이며, 그 안에는 여러 turn이 들어갑니다. turn은 하나의 사용자 요청과 그에 따른 agent 작업입니다.

구조로 보면 이렇게 볼 수 있습니다.

Thread
 ├─ Turn 1: "이 프로젝트 구조 설명해줘"
 │   ├─ User message
 │   ├─ Agent message
 │   └─ File reads
 │
 ├─ Turn 2: "로그인 버그 고쳐줘"
 │   ├─ User message
 │   ├─ Shell command
 │   ├─ File edit
 │   └─ Agent summary
 │
 └─ Turn 3: "테스트도 돌려줘"
     ├─ User message
     ├─ Test command
     └─ Result summary

03session, thread, turn의 관계

초보자 기준으로는 session과 thread를 엄격히 구분하지 않아도 됩니다. 다만 실무에서는 이렇게 생각하면 편합니다.

session

저장되고 재개할 수 있는 작업 묶음

thread

그 작업 안에서 이어지는 대화 줄기

turn

한 번의 요청과 응답/작업

04resume

resume은 이전에 저장된 대화를 다시 불러와 이어가는 기능입니다.

CLI에서는 다음처럼 사용합니다.

/resume

/resume을 입력하면 저장된 session picker가 열리고, 선택한 대화의 transcript를 다시 불러와 원래 이력을 유지한 채 이어갈 수 있습니다.

사용 예시:

어제 하던 로그인 버그 수정 세션을 /resume으로 불러온다.
Codex가 이전에 어떤 파일을 봤고 어떤 결정을 했는지 유지한다.
이어서 "아까 수정한 부분 기준으로 테스트도 추가해줘"라고 요청한다.

05resume을 써야 할 때

resume을 사용할 시기는 명확합니다.

같은 문제를 이어서 해결할 때

이전 진행 상황 유지

이전 논의와 결정이 중요한 작업일 때

컨텍스트 보존 필수

Codex가 이미 프로젝트 구조를 파악한 상태일 때

재분석 불필요

아직 커밋하지 않은 변경 흐름을 계속 검토할 때

진행 중인 작업 이어가기

반대로 완전히 다른 일을 시작한다면 resume보다 /new가 더 낫습니다.

06fork

fork는 현재 대화를 복제해서 새로운 thread로 분기하는 기능입니다. /fork는 현재 대화를 새 ID를 가진 thread로 복제하며, 원본 transcript는 그대로 둔 채 다른 접근을 병렬로 실험할 수 있게 합니다.

CLI에서는 이렇게 사용합니다.

/fork

07fork를 사용하는 실무 사례

fork가 가장 유용한 상황들입니다.

방법 A와 방법 B를 비교하고 싶을 때

병렬 실험

리팩터링 방향을 바꿔보고 싶을 때

다른 접근 시도

원래 작업은 보존하면서 과감한 수정을 실험하고 싶을 때

안전한 실험

리뷰용 thread와 구현용 thread를 분리하고 싶을 때

역할 분리

예를 들어 로그인 버그를 고치는 중이라면 원본 thread에서는 최소 수정으로 버그만 해결하고, fork thread에서는 인증 로직 전체 리팩터링을 시도할 수 있습니다.

08fork 사용 시 좋은 습관

fork할 때 권장 패턴입니다.

작은 수정

같은 thread에서 계속한다

방향 분기

fork한다

fork한 thread의 첫 메시지

목적을 명확히 다시 적는다

fork한 thread 시작 예시:

이 fork에서는 기존 수정 방향은 유지하지 말고,
auth middleware를 기준으로 더 구조적인 해결책을 제안해줘.
단, 아직 파일 수정은 하지 말고 plan만 작성해줘.

09compact

compact는 긴 대화의 앞부분을 요약해서 context를 가볍게 만드는 기능입니다.

CLI에서는 다음처럼 사용합니다.

/compact

/compact는 긴 대화 후 이전 turn들을 간결한 요약으로 대체해 중요한 내용은 유지하면서 context를 확보합니다.

초보자가 이해해야 할 핵심:

compact는 대화 삭제가 아니라, 긴 작업 기록을 요약본으로 압축하는 것입니다.

10compact를 사용할 타이밍

compact를 사용하기 좋은 타이밍들입니다.

대화가 너무 길어졌을 때

context 확보

Codex가 이전 내용을 헷갈리기 시작할 때

정보 정리

이미 끝난 탐색 과정이 너무 많이 쌓였을 때

불필요한 기록 압축

다음 단계부터는 결론만 필요할 때

집중력 복구

11compact 전후 안전한 진행

compact 전에 이렇게 요청하면 더 안전합니다.

지금까지의 핵심 결정, 수정한 파일, 남은 작업, 주의할 점을 먼저 정리해줘.
그다음 /compact를 실행할게.

compact 후에는 바로 다음 메시지로 작업 기준을 다시 고정하는 것이 좋습니다.

방금 압축된 요약을 기준으로 계속 진행해줘.
현재 목표는 로그인 실패 시 500이 아니라 401을 반환하도록 고치는 거야.
수정 범위는 auth middleware와 관련 테스트로 제한해줘.

12context window 관리

Codex는 thread 안에 많은 정보를 담을 수 있지만, 무한히 기억하는 것은 아닙니다. 대화가 길어질수록 중요한 정보가 묻히거나, 오래된 탐색 과정이 현재 작업 판단을 방해할 수 있습니다.

context window 관리는 다음 세 가지를 뜻합니다.

필요한 정보만 Codex에게 보여주기

집중도 향상

오래된 정보는 요약해서 정리하기

중요 내용 보존

작업 단위가 바뀌면 thread를 나누기

맥락 일관성

13context window 관리 예시

좋은 예시와 나쁜 예시입니다.

나쁜 방식:

"전체 프로젝트를 다 보고 문제를 찾아서 고쳐줘."

좋은 방식:

"src/auth와 tests/auth를 중심으로 로그인 실패 시 500이 나는 원인을 찾아줘.
먼저 원인 후보를 3개 이하로 정리하고, 수정 전에는 계획을 보여줘."

14긴 작업을 위한 효과적인 루틴

긴 작업에서는 아래 루틴이 효과적입니다.

작업 목표를 짧게 고정한다.
관련 파일만 언급한다.
Codex가 찾은 결론을 중간중간 요약시킨다.
방향이 바뀌면 fork한다.
대화가 길어지면 compact한다.
끝난 작업은 diff와 테스트 결과로 마무리한다.

15대화가 길어질 때 정리하는 법

대화가 길어지면 Codex에게 먼저 작업 상태 보고서를 만들게 하는 것이 좋습니다.

16상황별 다음 액션

작업 상태 보고서를 작성한 후, 상황에 따라 선택합니다.

같은 방향으로 계속한다

/compact

다른 접근을 시도한다

/fork

완전히 새 작업을 한다

/new

예전 작업으로 돌아간다

/resume

17긴 대화에서 피해야 할 패턴

피해야 할 패턴들입니다.

한 thread에서 unrelated 작업을 계속 추가하기
이전 결정이 틀렸는데 같은 thread에서 억지로 방향 바꾸기
파일을 너무 많이 한꺼번에 첨부하기
compact 없이 수십 turn을 계속 밀어붙이기
fork하지 않고 실험성 리팩터링을 원본 흐름에 섞기

18좋은 마무리 프롬프트

thread를 마무리할 때 사용하면 좋은 프롬프트입니다.

현재 thread를 마무리할 수 있게 최종 요약을 작성해줘.
포함할 내용:
- 변경 파일
- 핵심 변경점
- 실행한 테스트
- 남은 리스크
- 커밋 메시지 초안

19작업별 session 분리 전략

session은 작업 단위로 나누는 것이 가장 안전합니다. 추천 기준:

작은 버그 수정

하나의 session 유지

같은 버그의 다른 해결책 비교

원본 유지 후 /fork

큰 리팩터링

처음부터 별도 session

문서 작업

코드 수정 session과 분리

테스트 추가

관련 구현 session 안에서 진행 가능

리뷰 작업

구현 thread와 별도 thread 권장

장기 기능 개발

기능별 session 분리

실험적 변경

반드시 fork 또는 별도 worktree 사용

20실무형 session 분리 예시

여러 session을 병렬로 운영하는 실무 사례입니다.

Session 1: auth-login-bugfix
- 로그인 실패 500 오류 수정
- 관련 테스트 추가
- 최소 변경 원칙

Session 2: auth-refactor-experiment
- auth middleware 구조 개선
- 원본 버그 수정과 분리
- fork 또는 별도 worktree 사용

Session 3: auth-docs-update
- README와 API 문서 업데이트
- 코드 변경과 분리

Codex app은 여러 thread를 병렬로 다루는 데 초점을 둔 데스크톱 환경이며, 장기 작업은 로컬 thread와 cloud task의 경계를 명확히 잡는 것이 좋습니다.

21핵심 slash command 정리

session 관리의 핵심 slash command들입니다.

/resume

예전 작업 이어가기

/fork

현재 작업을 복제해서 다른 방향 실험하기

/compact

긴 대화를 요약해 context 확보하기

/new

같은 CLI 안에서 새 대화 시작하기

/status

현재 session 상태 확인하기

섹션 23 · 마무리

이 단원에서 기억할 것

Session management는 Codex를 효율적으로 사용하는 핵심입니다. session과 thread를 구분하고, 작업의 성격에 맞는 도구를 선택하는 것이 중요합니다.

가장 중요한 원칙은 하나입니다.

하나의 thread에는 하나의 coherent work unit만 담는다.

작업이 이어지면 /resume, 방향이 갈라지면 /fork, 대화가 길어지면 /compact, 작업이 완전히 바뀌면 /new를 사용하면 됩니다.

다음 단원

24단원. 비대화형 모드: codex exec

24. 비대화형 모드: codex exec

01codex exec란 무엇인가

codex exec는 Codex를 비대화형 모드로 실행하는 명령어입니다. 일반 codex가 터미널 안에서 대화형 TUI를 여는 방식이라면, codex exec는 프롬프트를 한 번 전달하고 Codex가 작업한 뒤 결과를 출력하는 방식입니다.

기본 형태:

codex exec "이 저장소 구조를 요약하고 위험한 영역 5개를 알려줘"

짧게 쓰면:

codex e "최근 변경사항을 리뷰해줘"

초보자는 이렇게 이해하면 됩니다:

codex

대화하면서 작업하는 모드

codex exec

한 번 시키고 결과를 받는 자동화 모드

codex exec는 다음 상황에서 특히 유용합니다:

CI에서 테스트 실패

원인 분석

자동 생성

릴리즈 노트, PR 리뷰

자동화

로그 요약, JSON 생성, 코드 점검

02TUI와 exec의 차이

대화형 TUI와 codex exec의 가장 큰 차이는 사람이 중간에 개입하느냐입니다.

구분

대화형 TUI codex

실행 방식

대화 화면 진입

사용 목적

탐색, 협업, 수정 검토

중간 승인

사람이 보면서 승인 가능

구분

비대화형 codex exec

실행 방식

명령 실행 후 종료

사용 목적

자동화, CI, 스크립트

중간 승인

사전 설정이 중요

출력

stdout, stderr, JSONL, 파일

적합한 작업

반복 작업, 검사, 요약, 자동 리뷰

핵심 기준:

사람이 중간에 보고 방향 조정

codex

정해진 작업 자동 실행, 결과만

codex exec

03한 번에 작업 실행하기

가장 기본적인 사용법은 작업 지시를 문자열로 넘기는 것입니다.

codex exec "README를 읽고 이 프로젝트의 목적을 5문장으로 요약해줘"

코드 리뷰:

codex exec "현재 git diff를 검토하고, 버그 가능성이 높은 부분만 지적해줘"

테스트 실패 로그 분석:

npm test 2>&1 | codex exec "실패한 테스트 원인을 요약하고 가장 작은 수정 방향을 제안해줘"

stdin이 pipe되고 동시에 prompt argument가 있으면, prompt는 지시문으로 쓰이고 pipe된 내용은 추가 context로 취급됩니다.

좋은 프롬프트 예시:

codex exec "현재 변경사항을 리뷰해줘.
   출력 형식:
   1. 치명적 버그 가능성
   2. 테스트 누락
   3. 보안 위험
   4. 수정 우선순위
   코드 수정은 하지 말고 리뷰만 해줘."

파일을 실제로 수정시키려면 sandbox 권한을 명시합니다:

codex exec --sandbox workspace-write \
     "실패한 테스트를 재현하고, 가장 작은 코드 변경으로 통과하게 고쳐줘"

04출력 파일로 저장하기

codex exec의 결과는 stdout으로 나오므로 리다이렉션이나 tee와 잘 맞습니다. 실행 중 진행 상황은 stderr로 stream하고, 최종 agent message만 stdout에 출력됩니다.

릴리즈 노트를 파일로 저장:

codex exec "최근 10개 커밋을 기준으로 릴리즈 노트를 작성해줘" \
     > release-notes.md

화면과 파일 동시 저장:

codex exec "현재 변경사항을 리뷰해줘" \
     | tee codex-review.md

-o 옵션으로 최종 메시지를 파일에 쓰기:

codex exec "프로젝트 메타데이터를 요약해줘" \
     -o project-summary.md

자동화 패턴:

mkdir -p reports
codex exec "현재 git diff를 리뷰하고 위험도를 요약해줘" \
     -o reports/codex-review.md

05JSON output 사용하기

자동화에서는 사람이 읽는 문장보다 기계가 처리하기 쉬운 출력이 필요할 때가 많습니다. 이때 --json을 사용합니다.

codex exec --json "저장소 구조를 요약해줘" | jq

--json을 사용하면 stdout이 JSON Lines, 즉 JSONL stream이 되며, thread.started, turn.started, turn.completed, turn.failed, item.*, error 등의 event를 받을 수 있습니다.

일반 출력

사람이 읽기 좋음

--json

스크립트가 처리하기 좋음

예시:

codex exec --json "현재 변경사항을 리뷰해줘" \
     > codex-events.jsonl

JSONL 형식 (한 줄에 JSON 객체 하나):

{"type":"thread.started","thread_id":"..."}
{"type":"turn.started"}
{"type":"item.completed","item":{"type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":1000,"output_tokens":200}}

CI에서 특정 event만 추출:

codex exec --json "테스트 실패 원인을 분석해줘" \
     | jq -r 'select(.type=="item.completed")'

중요: --json은 실행 과정 전체를 event stream으로 받는 기능이고, 최종 결과의 구조를 강제하는 기능은 아닙니다. 최종 결과의 필드를 고정하고 싶다면 다음 섹션의 --output-schema를 써야 합니다.

06--output-schema

--output-schema는 Codex의 최종 응답을 정해진 JSON Schema에 맞춰 출력하게 만드는 옵션입니다. downstream 자동화에서 안정적인 필드가 필요할 때 사용합니다.

예를 들어 리뷰 결과를 다음 구조로 받고 싶다면:

{
     "risk_level": "low | medium | high",
     "summary": "string",
     "issues": ["string"],
     "recommended_action": "string"
   }

스키마 파일을 만듭니다 (schemas/review.schema.json):

{
     "type": "object",
     "properties": {
       "risk_level": {
         "type": "string",
         "enum": ["low", "medium", "high"]
       },
       "summary": { "type": "string" },
       "issues": {
         "type": "array",
         "items": { "type": "string" }
       },
       "recommended_action": { "type": "string" }
     },
     "required": ["risk_level", "summary", "issues", "recommended_action"],
     "additionalProperties": false
   }

그다음 실행합니다:

codex exec "현재 git diff를 리뷰하고 위험도를 평가해줘" \
     --output-schema schemas/review.schema.json \
     -o reports/review.json

이 방식이 좋은 작업: PR 자동 리뷰, 릴리즈 노트 메타데이터, 테스트 실패 분류, 보안 위험도 분류, 이슈 triage 결과

--json과 --output-schema의 차이:

--json

실행 과정 전체를 JSONL event stream으로 받기

--output-schema

최종 답변의 JSON 구조를 강제하기

-o

최종 메시지를 파일로 저장하기

세 옵션을 함께 사용:

codex exec --json \
     "현재 변경사항을 리뷰하고 schema에 맞춰 결과를 작성해줘" \
     --output-schema schemas/review.schema.json \
     -o reports/review.json \
     > logs/codex-events.jsonl

07CI/CD에서 exec 사용하기

codex exec를 CI/CD에서 쓰는 대표 목적:

분석

테스트 실패 원인, 실패 로그 요약

리뷰

변경사항 리뷰, 보안 위험 탐지

생성

릴리즈 노트, 이슈 분류

검증

문서 변경 누락 확인

GitHub Actions 예시:

name: Codex Review
on:
  pull_request:

jobs:
  codex-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test 2>&1 | tee test.log
      - name: Analyze test result with Codex
        env:
          CODEX_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          cat test.log | codex exec \
            "테스트 로그를 분석해 실패 원인과 최소 수정 방향을 요약해줘" \
            -o codex-test-analysis.md
      - name: Upload Codex report
        uses: actions/upload-artifact@v4
        with:
          name: codex-test-analysis
          path: codex-test-analysis.md

보안상 중요한 점: OPENAI_API_KEY나 CODEX_API_KEY를 job 전체 환경변수로 두지 않습니다. 빌드 스크립트, 테스트, dependency lifecycle hook, 손상된 action이 같은 job 환경변수를 읽을 수 있기 때문입니다.

더 안전한 구조:

의존성 설치와 테스트 실행
로그 파일 생성
Codex 실행 시점에만 API key 주입
결과를 artifact로 저장
PR 생성이나 push 권한은 별도 job에서 처리

08자동화 스크립트 예시

로컬에서 반복 실행할 스크립트 (scripts/codex-review.sh):

#!/usr/bin/env bash
set -euo pipefail

mkdir -p reports

echo "[1/3] Collecting git diff..."
git diff --stat > reports/diff-stat.txt
git diff > reports/diff.patch

echo "[2/3] Running Codex review..."
codex exec \
  --sandbox read-only \
  "reports/diff.patch를 기준으로 변경사항을 리뷰해줘.
   코드 수정은 하지 말고 아래 항목만 작성해줘.

   1. 핵심 변경 요약
   2. 잠재적 버그
   3. 테스트 누락
   4. 보안 위험
   5. 병합 전 확인사항" \
  -o reports/codex-review.md

echo "[3/3] Done."
echo "Report: reports/codex-review.md"

실행 권한을 주고 실행:

chmod +x scripts/codex-review.sh
./scripts/codex-review.sh

테스트 실패 분석용 스크립트:

#!/usr/bin/env bash
set -euo pipefail

mkdir -p reports

npm test 2>&1 | tee reports/test.log || true

cat reports/test.log | codex exec \
  --sandbox read-only \
  "이 테스트 로그를 분석해줘.
   출력:
   - 실패한 테스트
   - 직접 원인
   - 가장 가능성 높은 코드 위치
   - 최소 수정 방향
   - 추가로 확인할 명령어" \
  -o reports/test-analysis.md

파일 수정까지 허용하는 자동 수정 스크립트 (더 조심 필요):

codex exec \
     --sandbox workspace-write \
     "npm test를 실행해 실패를 재현하고,
      가장 작은 변경으로 테스트를 통과시켜줘.
      관련 없는 리팩터링은 하지 마.
      수정 후 npm test를 다시 실행해줘."

실무 조건: 작업 디렉터리 깨끗함 확인, 수정 범위 명확히 제한, 테스트 명령 명시, 결과 diff 사람이 검토, CI에서는 patch artifact로만 저장

09sandbox와 approval 추천값

codex exec는 자동화에서 쓰이므로 권한 설정이 매우 중요합니다. 기본 sandbox는 read-only이며, 파일 수정을 허용하려면 --sandbox workspace-write, 더 넓은 접근이 필요하면 --sandbox danger-full-access를 사용할 수 있습니다.

24번 핵심 정리

codex exec = Codex를 자동화용으로 한 번 실행하는 비대화형 모드

자주 쓰는 명령:

codex exec "현재 저장소 구조를 요약해줘"
codex e "현재 변경사항을 리뷰해줘"
codex exec "릴리즈 노트를 작성해줘" -o release-notes.md
codex exec --json "저장소를 분석해줘" > codex-events.jsonl
codex exec --sandbox workspace-write \
     "실패한 테스트를 최소 변경으로 고쳐줘"

가장 중요한 원칙:

읽기 작업은 read-only
수정 작업은 workspace-write
danger-full-access는 격리된 환경에서만
CI에서는 API key 노출 범위를 최소화
자동화 결과는 사람이 검토 가능한 파일이나 patch로 남기기

다음 단원

25단원. Codex Cloud와 Background Tasks

25. Codex Cloud와 Background Tasks

01Codex Cloud란 무엇인가

Codex Cloud는 Codex가 사용자의 로컬 컴퓨터가 아니라 OpenAI가 제공하는 격리된 클라우드 환경에서 코드를 읽고, 수정하고, 명령을 실행하게 하는 방식입니다.

초보자는 이렇게 이해하면 됩니다.

로컬 Codex = 내 컴퓨터에서 Codex가 작업
Codex Cloud = 클라우드 컨테이너에서 Codex가 작업

Codex Cloud가 유용한 상황:

긴 리팩터링을 맡겨두고 다른 일을 해야 할 때
여러 버그를 병렬로 고치게 하고 싶을 때
내 로컬 환경을 건드리지 않고 실험시키고 싶을 때
GitHub issue나 PR에서 바로 작업을 위임하고 싶을 때
IDE에서 하던 대화를 클라우드 작업으로 넘기고 싶을 때

02로컬 작업과 클라우드 작업의 차이

Codex thread는 로컬에서도 실행될 수 있고, 클라우드에서도 실행될 수 있습니다.

실행 위치

로컬 = 내 컴퓨터 / Cloud = 클라우드 컨테이너

코드 기준

로컬 = 로컬 working tree / Cloud = GitHub repo, branch, commit

장점

로컬 = 내 도구와 환경 그대로 사용 / Cloud = 백그라운드·병렬 작업 가능

위험

로컬 = 내 파일을 직접 수정 / Cloud = 환경 설정이 맞지 않으면 재현 실패 가능

적합한 작업

로컬 = 직접 검토하며 수정 / Cloud = 맡겨두는 작업, 병렬 작업, PR 작업

내가 계속 보면서 조정할 작업 → 로컬 / Codex에게 맡겨두고 결과를 받을 작업 → Cloud

03Cloud Task 생성

Cloud task는 Codex에게 클라우드에서 수행할 작업을 위임하는 단위입니다.

가장 기본 흐름:

GitHub repository 연결
Codex Cloud environment 설정
작업할 branch 또는 상태 선택
Codex에게 task prompt 전달
Codex가 클라우드 컨테이너에서 작업
결과 diff 확인
PR 생성 또는 로컬 적용

04Cloud Task 실행 명령

CLI에서는 codex cloud 명령을 사용합니다.

기본 사용:

codex cloud exec --env ENV_ID "작업 내용"

예시:

codex cloud exec --env ENV_ID \
  "로그인 실패 시 500이 아니라 401을 반환하도록 수정하고 관련 테스트를 추가해줘"

여러 해결안을 받고 싶다면 --attempts를 사용할 수 있습니다. (범위: 1~4)

codex cloud exec --env ENV_ID --attempts 3 \
  "결제 실패 재시도 로직을 더 안전하게 개선하는 방법을 제안하고 구현해줘"

05좋은 Task Prompt 작성

초보자에게 좋은 task prompt는 구체적이고, 조건을 명확하게 제시합니다.

목표:
로그인 실패 시 서버가 500을 반환하는 문제를 수정해줘.

조건:
- auth middleware와 관련 테스트 중심으로 확인
- unrelated refactor 금지
- 수정 후 테스트 실행
- 결과 요약에 변경 파일, 테스트 결과, 남은 리스크 포함

06Cloud Task 목록 확인

터미널에서 최근 Cloud task를 확인할 수 있습니다.

기본 명령:

codex cloud

이 명령은 interactive picker를 열어 active task와 finished task를 둘러볼 수 있게 해줍니다.

최근 task 목록 보기:

codex cloud list

특정 environment 또는 JSON 형식으로 확인:

codex cloud list --limit 10
codex cloud list --env ENV_ID
codex cloud list --env ENV_ID --json

07완료된 작업 로컬에 적용하기

Cloud task가 끝나면 결과를 바로 merge하기보다, 먼저 diff를 확인해야 합니다.

Codex CLI의 codex apply 명령으로 diff를 로컬에 적용합니다.

기본 형태:

codex apply TASK_ID
codex a TASK_ID  # 짧은 별칭

08PR 생성 흐름

Codex Cloud의 큰 장점은 작업 결과를 PR로 만들 수 있다는 점입니다.

09PR 생성 전 필수 확인사항

PR 생성 전에는 반드시 아래를 확인합니다.

변경 범위

task prompt와 일치하는가

리팩터링

불필요한 리팩터링이 섞이지 않았는가

테스트

테스트가 실제로 실행되었는가

CI 재현성

CI에서 재현 가능한 변경인가

민감 정보

secret, token, 개인정보가 포함되지 않았는가

GitHub 통합에서는 PR comment로도 호출할 수 있습니다.

@codex fix the CI failures
@codex fix the P1 issue

10장기 실행 작업에 적합한 사례

Codex Cloud는 "내가 옆에서 계속 보고 있어야 하는 작업"보다 "명확한 목표를 맡겨두는 작업"에 잘 맞습니다.

좋은 사례:

테스트 실패 원인 분석 후 수정
작은 기능 구현과 테스트 추가
반복적인 타입 오류 수정
문서와 코드 간 불일치 정리
lint, format, import 정리
PR 리뷰 지적사항 반영
마이그레이션 초안 생성
여러 접근법 비교

11병렬 작업 설계

Codex Cloud는 백그라운드에서 작업할 수 있고, 여러 작업을 병렬로 실행할 수 있습니다.

좋은 병렬 작업 예시:

Task A

auth 테스트 보강

Task B

README 설치 가이드 업데이트

Task C

CI 실패 로그 분석

Task D

admin 페이지 타입 오류 수정

피해야 할 병렬 작업: 같은 파일을 동시에 수정하면 diff 충돌이나 방향 충돌이 생길 수 있습니다.

auth middleware 리팩터링
auth middleware 버그 수정
auth middleware 테스트 구조 변경

12Cloud 사용 시 주의점

Codex Cloud는 강력하지만, "클라우드에서 돌아간다"는 특성 때문에 로컬 Codex와 다른 주의점이 있습니다.

Environment 설정

repo에 AGENTS.md가 있으면 프로젝트별 lint/test 명령을 찾는 데 사용됨

Secret 처리

암호화로 저장되지만, setup script 단계에서만 사용 가능 (agent phase 전 제거)

Internet Access

기본적으로 꺼져 있음 (setup script는 사용, agent는 필요 시만 설정)

주의할 핵심 사항:

Cloud environment가 로컬 개발환경과 다르면 테스트 결과가 달라질 수 있음
setup script에 필요한 의존성 설치 명령을 명확히 적어야 함
Secret은 agent가 직접 읽는 용도로 설계하지 않음
Agent internet access는 필요한 경우에만 켤 것
여러 Cloud task가 같은 파일을 동시에 수정하지 않기
Cloud 결과는 바로 merge하지 말고 diff와 테스트를 확인

13Experimental 기능 다루는 법

Codex Cloud 관련 CLI 일부 기능은 experimental로 표시될 수 있습니다.

Stable 기능

팀 표준 워크플로에 넣어도 비교적 안전, 문서화하고 반복 사용 가능

Experimental 기능

개인 생산성 향상용으로 먼저 테스트, CI 핵심 경로에 바로 넣지 않기

Cloud task를 안정적으로 쓰려면 다음 원칙을 따릅니다.

작업 단위를 작게 나눈다.
task prompt에 성공 조건과 테스트 명령을 넣는다.
AGENTS.md에 프로젝트 규칙을 정리한다.
environment setup script를 최신 상태로 유지한다.
Cloud 결과는 PR 또는 local diff로 검토한다.
팀 전체 자동화에 넣기 전 개인 워크플로에서 검증한다.

14핵심 명령 정리

가장 자주 쓰는 Codex Cloud 명령들:

# Cloud task 탐색
codex cloud

# Cloud task 생성
codex cloud exec --env ENV_ID "작업 내용을 적는다"

# 여러 해결안 요청
codex cloud exec --env ENV_ID --attempts 3 "작업 내용을 적는다"

# 최근 task 목록
codex cloud list

# JSON으로 task 목록 확인
codex cloud list --json

# 완료된 Cloud task diff를 로컬에 적용
codex apply TASK_ID
codex a TASK_ID  # 짧은 별칭

섹션 25 · 마무리

25단원의 핵심 원칙

로컬에서 직접 조정할 작업은 local thread. / 맡겨두고 병렬로 돌릴 작업은 cloud task. / Cloud 결과는 항상 diff, 테스트, CI, PR 리뷰를 거쳐 반영한다.

Codex Cloud는 개발 속도를 높이는 강력한 도구입니다. 하지만 클라우드 환경의 특성을 이해하고, task prompt를 구체적으로 작성하고, 결과를 항상 검토하는 습관이 중요합니다.

다음 단원

26단원. Codex Desktop App

26. Codex Desktop App

01Desktop App의 역할

Codex Desktop App은 Codex 작업을 한곳에서 관리하는 데스크톱 작업 허브입니다. 여러 Codex thread를 병렬로 다루기 위한 focused desktop experience이며, built-in worktree support, automations, Git functionality를 제공합니다.

초보자는 이렇게 이해하면 됩니다.

CLI

터미널 중심 작업

IDE Extension

코드 편집기 안에서 페어 프로그래밍

Cloud

클라우드에 맡기는 백그라운드 작업

Desktop App

여러 Codex 작업을 한 화면에서 관리하는 지휘소

Desktop App이 특히 유용한 상황:

여러 프로젝트를 동시에 다룰 때
여러 Codex thread를 병렬로 실행할 때
작업별 diff를 눈으로 검토하고 싶을 때
Codex가 만든 변경을 stage, revert, commit, push까지 처리하고 싶을 때
로컬 작업, worktree 작업, cloud 작업을 한 화면에서 오가고 싶을 때

02multi-tasking

Desktop App의 핵심 장점은 여러 작업을 동시에 관리하는 것입니다. 하나의 Codex app window에서 여러 프로젝트의 task를 실행하고, 각 codebase를 project로 추가해 전환할 수 있습니다.

예를 들면 다음처럼 나눌 수 있습니다.

Project A: trading-dashboard
- Thread 1: 차트 렌더링 버그 수정
- Thread 2: 테스트 실패 원인 분석
- Thread 3: README 업데이트
Project B: api-server
- Thread 1: auth middleware 수정
- Thread 2: rate limit 로직 검토

좋은 사용 패턴:

하나의 thread에는 하나의 작업만 넣는다
서로 다른 코드베이스는 project를 분리한다
같은 repo 안에서도 앱·패키지가 명확히 다르면 별도 project로 나눈다
동시에 돌릴 작업은 worktree나 cloud로 분리한다

03git worktree isolation

Worktree는 Codex가 내 현재 작업을 건드리지 않고 별도 checkout에서 독립적으로 작업하게 만드는 기능입니다. 같은 project에서 여러 독립 작업을 서로 방해하지 않고 병렬로 실행할 수 있게 해줍니다.

초보자는 이렇게 이해하면 됩니다.

Local

지금 내가 열어둔 실제 프로젝트 폴더

Worktree

같은 repo의 별도 작업 복사본

예시: 내가 로컬에서 결제 화면을 고치고 있는데, Codex에게 로그인 테스트 보강을 맡기고 싶을 때 worktree가 좋습니다.

04inline diff review

Desktop App의 review pane은 Codex가 만든 변경사항을 눈으로 확인하고, 필요한 부분만 받아들이는 공간입니다. Codex가 무엇을 바꿨는지 이해하고, targeted feedback을 주고, 무엇을 유지할지 결정하는 데 쓰입니다.

Review pane에서 할 수 있는 일:

Codex가 바꾼 파일 확인
내가 직접 바꾼 uncommitted changes 확인
branch 전체 diff 확인
마지막 assistant turn의 변경만 확인
file, hunk, 전체 diff 단위로 stage 또는 revert
특정 줄에 inline comment 남기기

특히 inline comment가 중요합니다. 특정 diff 줄에 직접 피드백을 달면 Codex가 일반 지시보다 더 정확하게 수정 의도를 이해할 수 있습니다.

05inline diff review · 실무 흐름

좋은 리뷰 프롬프트 예시:

방금 남긴 inline comments만 반영해줘.
관련 없는 리팩터링은 하지 말고,
수정 후 테스트 명령도 실행해줘.

실무 흐름:

1Codex가 코드 수정

2Review pane 열기

3마음에 안 드는 줄에 inline comment 작성

4수정 범위 최소화 요청

5필요한 hunk만 stage

06integrated terminal

Desktop App의 각 thread에는 현재 project 또는 worktree에 scope된 built-in terminal이 있습니다. 변경 검증, script 실행, Git 작업을 수행하며, Codex는 현재 terminal output을 읽고 실패한 build나 실행 중인 dev server 상태를 참고할 수 있습니다.

대표적으로 실행하는 명령:

git status
npm test
npm run lint
npm run dev
git diff

이 방식의 장점은 CLI를 따로 열지 않아도 같은 화면에서 "수정 → 실행 → 실패 확인 → 재수정" 루프를 만들 수 있다는 것입니다.

07conversation forking

Desktop App에서도 conversation forking을 활용할 수 있습니다. Fork가 필요한 순간은 다음과 같습니다.

해결책 A와 B를 비교하고 싶을 때
현재 접근이 마음에 들지 않아 다른 방향을 실험할 때
원본 대화는 보존하고 과감한 리팩터링을 시도할 때
review thread와 implementation thread를 분리할 때

예시: 원본 thread는 로그인 버그를 최소 수정으로 해결하고, fork thread에서는 auth middleware 구조를 리팩터링하는 방식으로 해결합니다.

Fork 후 첫 요청은 명확해야 합니다.

이 fork에서는 기존 최소 수정 방향을 버리고,
auth middleware 구조 자체를 더 단순하게 만드는 접근을 검토해줘.
먼저 plan만 작성하고 파일은 수정하지 마.

08floating pop-out windows

Floating pop-out window는 현재 thread를 별도 작은 창으로 띄워 작업 위치 근처에 붙여두는 기능입니다. 브라우저·에디터·디자인 preview 근처에 두고 빠르게 반복 작업할 때 유용합니다.

프론트엔드 작업 배치 예:

왼쪽: 코드 편집기
오른쪽: 브라우저 preview
위쪽 작은 창: Codex pop-out thread

09automations

Desktop App의 automations는 반복 작업을 background에서 실행하도록 예약하는 기능입니다. Recurring tasks를 background에서 자동화할 수 있고, findings를 inbox에 추가하거나 보고할 내용이 없으면 자동 archive할 수 있습니다.

활용 예시:

매일 아침 main branch의 테스트 실패 여부 확인
최근 에러 로그를 보고 원인 후보 정리
주간 코드 변경사항 보고서 생성
오래된 dependency나 TODO 목록 정리
특정 thread를 주기적으로 깨워 진행 상태 점검

Worktree에서 automation을 실행하면 내 unfinished local work와 충돌하지 않아 더 안전합니다.

10automations · 좋은 프롬프트

좋은 automation prompt 예시:

매주 월요일 오전에 이 project의 최근 변경사항을 요약해줘.
출력:
1. 주요 변경 파일
2. 테스트 실패 가능성이 있는 부분
3. 문서 업데이트가 필요한 부분
4. follow-up이 필요한 작업
코드 수정은 하지 말고 보고서만 작성해줘.

11Appshots · in-app browser · Computer Use

Appshots

Appshots는 macOS에서 현재 가장 앞에 있는 앱 창을 Codex thread로 보내는 기능입니다. 주의할 점은 Appshot에 화면 정보가 포함된다는 것이므로, 계정 정보, 토큰, 고객 데이터, 개인정보가 보이는 창은 캡처하지 않는 것이 안전합니다.

in-app browser

Desktop App에는 web app을 preview하고 시각적으로 comment할 수 있는 in-app browser가 있습니다. Local development server, file-backed preview, 로그인하지 않아도 되는 public page를 thread 안에서 함께 보며 리뷰할 때 사용합니다. Browser use를 활성화하면 Codex가 in-app browser 안에서 직접 클릭, 입력, 검사, screenshot 확인 등을 수행할 수 있습니다.

Computer Use

Computer Use는 Codex가 macOS 또는 Windows 앱을 보고, 클릭하고, 입력할 수 있게 하는 기능입니다. 데스크톱 앱 테스트, browser 또는 simulator flow 확인, GUI-only bug 재현에 유용합니다.

12Desktop App이 CLI보다 좋은 상황

CLI는 빠르고 가볍습니다. 하지만 Desktop App은 여러 작업을 눈으로 관리하고, diff를 검토하고, browser·terminal·Git·automation을 한 화면에 묶는 데 강합니다.

여러 thread 병렬 관리

CLI는 불편, Desktop App은 좋음

worktree 기반 병렬 작업

CLI는 가능하지만 수동 관리 필요, Desktop App은 좋음

diff를 보며 line comment

CLI는 제한적, Desktop App은 좋음

stage/revert/commit/push

CLI는 터미널 명령 중심, Desktop App은 앱 내 Git 기능

frontend visual review

CLI는 별도 브라우저 필요, Desktop App은 in-app browser comments

반복 작업 예약

CLI는 별도 스크립트 필요, Desktop App은 automations

GUI 앱 조작

CLI는 제한적, Desktop App은 Computer Use

Desktop App을 쓰는 대표 흐름: Project 추가 → 작업별 thread 생성 → 위험한 작업은 Worktree로 시작 → plan 작성 → 구현 → terminal에서 테스트 → review pane에서 diff 확인 → inline comment로 수정 → 필요한 변경만 stage → commit/push 또는 PR 생성

섹션 26 · 마무리

이 단원에서 기억할 것

Codex Desktop App = Codex 작업을 병렬로 관리하는 로컬 작업 허브

가장 중요한 원칙:

직접 보며 빠르게 수정할 작업은 Local. 내 작업과 분리해야 할 작업은 Worktree. 오래 걸리고 독립적인 작업은 Cloud. 결과는 항상 Review pane에서 diff를 확인한 뒤 반영한다.

다음 단원

27단원. IDE Extension

27. 개발 환경 통합: IDE Extension, Chrome, CI/CD, SDK

01이 단원의 목적

Codex는 CLI에서만 쓰는 도구가 아닙니다. 같은 Codex 작업을 다음 환경으로 확장할 수 있습니다.

IDE Extension  → 내가 보는 코드와 연결
Chrome         → 로그인된 웹사이트와 연결
GitHub Action  → CI/CD와 연결
SDK            → 직접 만든 자동화 시스템과 연결

즉, 27번 단원은 이렇게 이해하면 됩니다.

Codex를 개발자의 실제 작업 환경에 붙이는 방법

02IDE Extension 개념

IDE Extension은 Codex를 코드 편집기 안에 붙이는 방식입니다.

CLI에서는 Codex에게 프로젝트 폴더를 기준으로 작업을 시키지만, IDE에서는 다음 정보가 자연스럽게 context가 됩니다.

현재 열려 있는 파일
선택한 코드
활성 editor
프로젝트 폴더
현재 작업 중인 branch
IDE 안의 진단 정보

지원 흐름은 다음과 같이 정리할 수 있습니다.

VS Code

기본 추천 IDE

Cursor

VS Code 계열 IDE에서 Codex 사용

Windsurf

VS Code 계열 IDE에서 Codex 사용

03VS Code, Cursor, Windsurf에서 사용하기

설치 흐름은 세 IDE 모두 비슷합니다.

1. IDE에서 Codex Extension 설치
2. Codex 사이드바 열기
3. ChatGPT 계정 또는 API Key로 로그인
4. 프로젝트 폴더 열기
5. 현재 파일 또는 전체 repo 기준으로 작업 요청

처음 사용할 때는 파일 수정을 바로 맡기기보다, 프로젝트 이해부터 시키는 것이 좋습니다.

이 프로젝트 구조를 설명해줘.
먼저 파일은 수정하지 말고,
주요 폴더와 실행 흐름만 요약해줘.

04현재 파일 중심 요청

현재 파일 중심으로 요청할 때는 이렇게 씁니다.

현재 열려 있는 파일을 기준으로,
에러 처리 흐름을 검토해줘.
수정 전에는 원인 후보와 수정 계획을 먼저 보여줘.

Cursor나 Windsurf에 자체 AI 기능이 있더라도, Codex는 더 무거운 agent 작업에 쓰는 것이 좋습니다.

가벼운 한 줄 수정

IDE 기본 AI 기능

여러 파일 수정

Codex

테스트 실행 포함 작업

Codex

Cloud 위임

Codex

PR 리뷰·리팩터링

Codex

05agent mode

agent mode는 Codex가 단순히 답변만 하는 것이 아니라, 직접 파일을 읽고 수정하고 명령을 실행하는 모드입니다.

사용하기 좋은 작업은 다음과 같습니다.

버그 원인 찾기
여러 파일을 함께 수정하기
테스트 추가하기
리팩터링 수행하기
빌드 실패 원인 분석하기

06agent mode 요청 예시

좋은 요청 예시:

로그인 실패 시 500이 반환되는 문제를 찾아줘.
수정 범위는 auth 관련 파일과 테스트로 제한해줘.
먼저 plan을 보여주고, 내가 승인하면 수정해줘.

나쁜 요청 예시:

전체 프로젝트를 보고 알아서 고쳐줘.

agent mode에서는 항상 다음 3가지를 명시하는 것이 좋습니다.

목표

무엇을 해결할 것인가

수정 범위

어디까지 변경할 것인가

검증 명령

결과를 어떻게 확인할 것인가

07agent mode 예시

명확한 요청의 예시:

목표:
회원가입 실패 시 에러 메시지가 비어 있는 문제 수정

수정 범위:
src/auth, src/components/signup, tests/auth

검증:
npm test -- auth

08inline edits

inline edits는 특정 코드 블록이나 현재 선택한 영역을 기준으로 Codex에게 수정 요청을 하는 방식입니다.

작은 수정에는 agent mode보다 inline edit이 더 적합합니다.

함수 이름 변경
조건문 단순화
타입 오류 수정
주석 정리
작은 validation 추가

예시:

선택한 함수의 동작은 유지하면서,
중복 조건문만 줄여줘.
함수 시그니처는 바꾸지 마.

09inline edits 원칙

inline edit에서 중요한 원칙은 "선택 영역 밖으로 작업을 넓히지 말라"고 명시하는 것입니다.

선택한 코드 안에서만 수정해줘.
다른 파일은 건드리지 마.

10CLI와 IDE session 공유

Codex는 CLI, Desktop App, IDE Extension, Cloud를 서로 완전히 따로 보는 것이 아니라, 같은 작업 흐름의 여러 표면으로 보는 것이 좋습니다.

빠른 질문

CLI

현재 파일 중심 수정

IDE

여러 작업 병렬 관리

Desktop App

오래 걸리는 작업 위임

Cloud

자동화·CI

codex exec 또는 GitHub Action

직접 만든 시스템 연동

SDK

11IDE 환경 이동 흐름

예를 들어 다음처럼 이동할 수 있습니다.

IDE에서 버그 발견
→ Codex에게 원인 분석 요청
→ 작업이 커지면 Cloud로 위임
→ 결과 diff를 IDE에서 적용
→ 테스트는 로컬 terminal에서 실행
→ 반복 작업은 CI로 자동화

12활성 파일 중심 작업법

IDE Extension의 가장 큰 장점은 "내가 지금 보고 있는 파일"을 기준으로 Codex에게 작업을 시킬 수 있다는 점입니다.

좋은 패턴:

1. 문제가 있는 파일을 연다.
2. 관련 코드를 선택한다.
3. Codex에게 현재 파일 기준으로 설명을 요청한다.
4. 수정 전 plan을 받는다.
5. 작은 diff로 수정시킨다.
6. 테스트를 실행한다.

13활성 파일 예시

현재 열려 있는 파일에 대한 예시:

현재 열려 있는 파일에서 useEffect가 불필요하게 여러 번 실행되는 원인을 찾아줘.
파일 수정은 아직 하지 말고,
원인 후보와 수정 방향만 알려줘.

수정 요청:

방금 설명한 2번 원인만 수정해줘.
컴포넌트 구조는 바꾸지 말고,
dependency array와 상태 업데이트 흐름만 최소 변경해줘.

14compile-test loop에서 활용하기

IDE 안에서 Codex를 가장 잘 쓰는 방식은 수정 → 컴파일 → 테스트 → 실패 로그 전달 → 재수정 루프입니다.

1. Codex에게 수정 요청
2. IDE terminal에서 테스트 실행
3. 실패 로그 확인
4. 실패 로그를 Codex에게 전달
5. 최소 수정 요청
6. 다시 테스트

프롬프트 예시:

방금 terminal에 나온 TypeScript 에러를 기준으로 수정해줘.
타입을 any로 우회하지 말고,
기존 타입 구조에 맞춰 고쳐줘.

15테스트 실패 분석

테스트 실패 분석 예시:

이 테스트 실패 로그를 보고,
실패 원인을 3개 이하로 정리해줘.
그다음 가장 가능성 높은 원인부터 최소 수정해줘.

이 방식은 초보자에게 특히 좋습니다. Codex가 코드를 한 번에 크게 바꾸게 하기보다, 작은 검증 루프를 반복하게 만들 수 있기 때문입니다.

16Codex for Chrome

Codex for Chrome은 Codex가 Chrome 브라우저 안의 웹사이트를 사용할 수 있게 하는 확장입니다.

초보자는 이렇게 이해하면 됩니다.

IDE Extension

코드 편집기 안에서 Codex 사용

Chrome Extension

브라우저 안의 업무 화면에서 Codex 사용

사용하기 좋은 작업:

admin console에서 설정 확인
dashboard에서 데이터 읽기
CMS에서 콘텐츠 수정
내부 도구에서 반복 작업 수행
로그인된 웹앱 상태 확인

17브라우저 작업과 local repo 작업 구분

Chrome Extension은 웹사이트 작업용이고, IDE Extension은 코드 작업용입니다.

React 컴포넌트 수정

IDE Extension

로그인된 admin 페이지에서 설정 변경

Chrome Extension

CMS 글 수정

Chrome Extension

API 코드 수정

IDE Extension

dashboard 화면 확인 후 코드 수정

Chrome + IDE 조합

브라우저에서 버그 재현 후 테스트 추가

Chrome + IDE 조합

18브라우저 작업 흐름

예시 흐름:

1. Chrome에서 dashboard 버그 재현
2. Codex에게 화면 상태 설명 또는 조작 요청
3. 원인 후보 확인
4. IDE에서 관련 코드 수정
5. 다시 Chrome에서 화면 확인

주의할 점은 브라우저에는 민감한 정보가 많다는 것입니다.

고객 데이터
관리자 권한
결제 정보
내부 지표
개인정보
세션 쿠키

19Chrome 보안

따라서 Chrome Extension에는 사이트별 권한을 최소로 주고, 필요 없는 사이트는 허용하지 않는 것이 좋습니다.

20GitHub Action 및 CI/CD

GitHub Action은 Codex를 CI/CD 파이프라인에 붙이는 방식입니다. openai/codex-action@v1은 GitHub Actions workflow에서 Codex를 실행하고, patch를 적용하거나 review를 게시하는 데 사용할 수 있습니다.

대표 사용 사례:

PR 자동 리뷰
테스트 실패 원인 분석
이슈 triage
릴리즈 노트 초안 생성
보안 위험 요약
문서 업데이트 누락 확인

21CI/CD 기본 흐름

간단한 흐름:

1. PR 생성
2. GitHub Action 실행
3. codex exec로 diff 또는 test log 분석
4. 결과를 comment 또는 artifact로 저장
5. 사람이 최종 확인

CI에서 가장 중요한 원칙은 보안입니다.

API key를 job 전체에 무작정 노출하지 않는다.
repository-controlled script 실행 전에 secret을 주입하지 않는다.
쓰기 권한은 필요한 job에만 준다.
자동 수정 결과는 바로 merge하지 않는다.

22codex exec와 CI 연결

CI에서는 대화형 codex보다 비대화형 codex exec가 적합합니다.

예시:

codex exec "현재 git diff를 리뷰하고 잠재적 버그만 요약해줘"

테스트 로그 분석:

npm test 2>&1 | tee test.log

cat test.log | codex exec \
  "이 테스트 실패 로그를 분석하고,
   실패 원인과 최소 수정 방향을 요약해줘" \
  -o codex-test-analysis.md

23PR 리뷰용 codex exec

PR 리뷰용:

git diff origin/main...HEAD | codex exec \
  "이 PR diff를 리뷰해줘.
   출력:
   1. 치명적 버그 가능성
   2. 테스트 누락
   3. 보안 위험
   4. 병합 전 확인사항" \
  -o codex-review.md

CI에서 권장되는 기본 조합:

리뷰·분석 작업   → read-only
patch 생성       → workspace-write
자동 merge       → 비추천
approval_policy  → never

24Codex SDK

Codex SDK는 Codex를 CLI나 IDE가 아니라, 직접 만든 Python 또는 TypeScript 프로그램 안에서 호출하는 방식입니다.

초보자는 이렇게 이해하면 됩니다.

CLI

사람이 터미널에서 직접 사용

IDE

사람이 코드 편집기에서 직접 사용

GitHub Action

CI에서 자동 실행

SDK

내가 만든 프로그램이 Codex를 호출

25SDK 사용 사례

SDK가 필요한 상황:

사내 코드 리뷰 봇 만들기
테스트 실패 자동 분석 시스템 만들기
이슈 triage 자동화
반복 리팩터링 파이프라인 만들기
보안 스캔 결과를 Codex에게 해석시키기
커스텀 dashboard와 Codex 연결하기

예시 구조:

1. Python 스크립트가 GitHub issue를 읽는다.
2. Codex SDK로 thread를 만든다.
3. issue 내용과 관련 파일을 context로 전달한다.
4. Codex가 분석 결과를 반환한다.
5. 스크립트가 comment나 report로 저장한다.

26SDK와 CLI의 차이

사용 주체

CLI: 사람 / SDK: 프로그램

실행 방식

CLI: 터미널 명령 / SDK: 코드에서 호출

적합한 작업

CLI: 직접 분석·수정 / SDK: 제품화된 자동화

설정 난이도

CLI: 낮음 / SDK: 높음

반복 실행

CLI: 스크립트로 가능 / SDK: 구조화하기 쉬움

결과 처리

CLI: stdout, 파일 / SDK: 객체, JSON, DB 저장 가능

27CLI로 충분한 경우

CLI로 충분한 경우:

개인 자동화
단순 리뷰
테스트 로그 요약
릴리즈 노트 생성

SDK가 필요한 경우:

여러 repo를 순회해야 할 때
결과를 DB에 저장해야 할 때
사내 시스템과 연결해야 할 때
사용자별 권한·상태·이력을 관리해야 할 때
정해진 workflow를 제품처럼 운영해야 할 때

28초보자 추천 통합 워크플로

처음에는 네 가지를 한꺼번에 쓰지 말고, 아래 순서로 확장하는 것이 좋습니다.

1IDE Extension현재 파일 설명, 작은 수정, 테스트 실패 원인 분석

2IDE + CLI코드 확인, repo 분석, 반복 작업 자동화

3IDE + Cloud긴 작업 위임, 결과 diff 검토

4Chrome Extension로그인된 웹앱, admin console, dashboard 작업

5GitHub ActionPR 리뷰, 테스트 실패 분석, 릴리즈 노트 자동화

6SDK사내 봇, 커스텀 자동화, 대규모 workflow 구축

29초보자 첫 루틴

초보자에게 가장 좋은 첫 루틴은 다음입니다.

1. VS Code에서 프로젝트를 연다.
2. Codex Extension을 연다.
3. 현재 파일을 기준으로 설명을 요청한다.
4. 작은 수정만 맡긴다.
5. IDE terminal에서 테스트한다.
6. 실패 로그를 Codex에게 다시 준다.
7. diff를 직접 확인한다.
8. 익숙해지면 Cloud, Chrome, CI로 확장한다.

섹션 27 · 마무리

이 단원의 핵심

IDE Extension

코드 편집기 안에서 Codex 사용

Chrome Extension

로그인된 브라우저 작업에 Codex 사용

GitHub Action

CI/CD에서 Codex 자동 실행

SDK

직접 만든 시스템 안에서 Codex 호출

가장 중요한 기준은 다음입니다.

코드를 고친다 → IDE Extension / 브라우저에서 일한다 → Chrome Extension / PR·CI를 자동화한다 → GitHub Action / 제품처럼 연결한다 → SDK

다음 단원

28단원. 운영 최적화: 성능, 디버깅, 보안, 엔터프라이즈

28. 운영 최적화: 성능, 디버깅, 보안, 엔터프라이즈

01Codex 운영 최적화의 핵심

Codex를 잘 운영한다는 것은 단순히 "더 빠르게 답하게 하는 것"이 아닙니다. 실제 목표는 다음 네 가지를 동시에 만족시키는 것입니다.

속도

불필요한 탐색과 대화 낭비 줄이기

안정성

세션, 설정, Git 상태를 예측 가능하게 유지하기

보안

sandbox, approval, secret, network를 통제하기

조직 운영

팀 공통 설정과 감사 가능한 기준 만들기

Codex 설정은 사용자 설정, 프로젝트 설정, profile, system config, managed requirements 등 여러 층에서 결정되며, 설정 우선순위는 CLI flag와 override가 가장 높고, 그다음 project config, profile, user config, system config, built-in default 순서입니다.

28-A · 성능 최적화

02Codex가 느려지는 이유

Codex가 느려지는 대표 원인은 모델 자체가 느려서만은 아닙니다. 대부분은 입력 context가 너무 크거나, 작업 범위가 불명확하거나, 도구 출력이 너무 길거나, MCP·파일·로그를 과하게 붙였기 때문입니다.

대표 원인

대화가 너무 길어짐
@file로 너무 많은 파일을 한꺼번에 첨부함
MCP 서버를 많이 붙여 매 세션마다 도구 목록이 커짐
테스트·빌드 로그 전체를 그대로 붙임
reasoning effort를 항상 high/xhigh로 사용함
수정 범위를 명확히 제한하지 않음

긴 대화에 noisy output이 쌓이면 context pollution과 context rot이 생겨 세션 신뢰도가 떨어집니다. 핵심 요구사항과 결정은 main thread에 두고, 탐색·테스트·로그 분석 같은 noisy work는 subagent나 별도 thread로 분리하는 편이 낫습니다.

03context window 관리

context window는 Codex가 현재 작업을 판단할 때 참고하는 작업 기억 공간입니다. 많이 넣을수록 무조건 좋아지는 것이 아니라, 필요한 정보만 잘 넣는 것이 중요합니다.

나쁜 방식

이 repo 전체를 보고 성능 문제를 찾아서 고쳐줘.

좋은 방식

src/api/orders와 tests/orders를 중심으로,
주문 생성 API가 느려지는 원인을 찾아줘.
먼저 파일 수정 없이 병목 후보 3개만 정리해줘.

context 관리 원칙

작업마다 thread를 분리한다.
관련 파일만 언급한다.
긴 로그는 요약해서 준다.
이미 끝난 탐색 과정은 compact한다.
결론, 결정, 남은 작업만 남긴다.

04/compact 사용법

/compact는 길어진 대화를 요약해 context를 정리하는 기능입니다. 대화를 삭제하는 것이 아니라, 오래된 turn들을 요약본으로 바꿔 중요한 정보만 남기는 방식입니다.

사용하기 좋은 시점

대화가 길어져 Codex가 이전 결정을 헷갈릴 때
긴 로그와 탐색 결과가 많이 쌓였을 때
현재부터는 결론과 남은 작업만 필요할 때
다음 단계로 넘어가기 전에 작업 상태를 정리하고 싶을 때

05@file을 남발하지 않는 법

@file은 특정 파일을 명확히 context로 넣을 수 있는 강력한 기능입니다. 하지만 파일을 너무 많이 붙이면 Codex가 중요한 정보를 찾는 데 더 오래 걸리고, 비용도 늘어납니다.

기준

원인 분석 전 → 관련 진입점 파일 1~3개
수정 직전 → 실제 수정 후보 파일
테스트 작성 → 테스트 대상 파일 + 기존 테스트 파일
리팩터링 → public interface 파일 + 호출부 일부

나쁜 예

@src 전체를 보고 문제를 찾아줘.

좋은 예

@src/auth/middleware.ts
@src/auth/session.ts
@tests/auth/session.test.ts

이 세 파일을 중심으로 로그인 만료 처리 문제를 봐줘.
먼저 수정 없이 원인 후보만 정리해줘.

06MCP 서버 수 줄이기

MCP는 repo 밖의 외부 context를 Codex에 연결하는 표준 방식입니다. 필요한 context가 repo 밖에 있거나, 자주 바뀌거나, 반복 가능한 통합이 필요할 때 MCP를 씁니다. 처음부터 모든 도구를 붙이지 말고, 실제 workflow를 제거해주는 1~2개 도구부터 시작해야 합니다.

운영 기준

매일 쓰는 도구만 기본 활성화한다.
가끔 쓰는 MCP는 profile로 분리한다.
사용하지 않는 MCP는 비활성화한다.
팀 표준 MCP는 문서화한다.
외부 SaaS MCP는 권한과 데이터 범위를 확인한다.

기본 설정 예시

[mcp_servers.github]
enabled = true

[mcp_servers.figma]
enabled = false

[mcp_servers.sentry]
enabled = false

07MCP profile 분리 전략

실무에서는 profile을 작업 성격에 따라 나누는 것이 좋습니다.

08tool output token limit 조정

테스트 로그, 빌드 로그, grep, find, npm test, pytest 출력은 쉽게 수천 줄이 됩니다. 모든 raw output을 그대로 주면 느려지고, 중요한 실패 원인이 묻힙니다.

출력량 줄이기

# 전체 로그 대신 마지막 120줄만 전달
npm test 2>&1 | tail -n 120

# 실패 줄 주변만 전달
pytest 2>&1 | grep -A 20 -B 10 "FAILED"

# TypeScript 에러만 저장
npm run typecheck 2>&1 | grep "error TS" > ts-errors.log

지시 방법

Codex에게 이렇게 말하면 됩니다: "전체 로그를 다 읽으려 하지 말고, 실패한 테스트 이름, 첫 번째 stack trace, 관련 파일 경로만 기준으로 원인을 찾아줘."

09fast profile 활용

빠른 반복 작업에는 항상 최고 reasoning effort를 쓸 필요가 없습니다. Codex의 Fast mode는 속도를 높이는 대신 더 높은 credit rate를 사용합니다.

빠른 작업용 profile 예시

model = "gpt-5.4-mini"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
fast_mode = true

service_tier = "fast"

실행

codex --profile fast

10fast profile 추천 사용처

비추천 사용처

보안 민감 코드 변경
대규모 마이그레이션
복잡한 concurrency 버그
결제·인증·권한 로직 수정

11subagent 작업 분리

Subagent는 큰 작업을 여러 작은 agent에게 나눠 맡기는 방식입니다. 각 subagent가 자체 model·tool 작업을 수행하므로 token을 더 쓸 수 있지만, 탐색, 테스트, triage, 요약처럼 독립적인 read-heavy 작업에는 병렬 처리 이점이 있습니다.

좋은 예

이 branch를 병렬 subagent로 리뷰해줘.
- agent 1: 보안 위험
- agent 2: 테스트 누락
- agent 3: 유지보수성 문제

세 agent가 끝난 뒤,
중복을 제거하고 우선순위별로 요약해줘.

운영 기준

읽기 중심 작업 → subagent 좋음
쓰기 중심 작업 → 충돌 가능성 때문에 조심
최종 판단 → main thread에서 통합

12큰 repo에서 탐색 최적화

큰 repo에서는 "전체를 다 봐줘"가 가장 느린 요청입니다. 먼저 구조를 좁히고, 그다음 파일을 좁히고, 마지막에 수정 범위를 제한해야 합니다.

프롬프트 예시

이 repo 전체를 다 읽지 말고,
결제 API와 관련된 entrypoint 후보만 찾아줘.
파일 수정은 하지 말고,
관련 디렉터리와 핵심 파일 후보를 10개 이하로 정리해줘.

13비용과 속도 균형 잡기

비용과 속도는 다음 세 가지에 크게 좌우됩니다: 모델 선택, reasoning effort, context와 tool output 크기입니다.

초보자 기본값

model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

28-B · 문제 디버깅

14Codex 문제 해결 기본 순서

Codex가 이상하게 동작할 때는 프롬프트를 다시 쓰기 전에 운영 상태부터 확인합니다.

확인 순서

Git 상태 확인
현재 working directory 확인
Codex session 상태 확인
config 적용값 확인
인증 상태 확인
sandbox / approval 확인
MCP / plugin 비활성화 후 재현
shell 환경 확인
로그와 doctor report 확인

기본 명령

pwd
git status
codex doctor --summary
codex doctor --json > codex-doctor.json

15codex doctor

codex doctor는 로컬 설치, config, auth, runtime, Git, terminal, app-server, thread inventory 상태를 점검하는 stable 명령입니다.

사용 방법

간단 요약만:
codex doctor --summary

지원 요청용 JSON:
codex doctor --json > codex-doctor.json

확인할 항목

설치 경로
CLI 버전
인증 상태
config 충돌
Git repo 상태
terminal 환경
app-server 상태
thread inventory 상태

주의할 점은 doctor report가 "현재 Codex 자체 상태"를 보여줄 뿐, 사용자의 프롬프트가 좋은지 나쁜지까지 판단해주는 것은 아니라는 점입니다.

16/status 확인

세션 중에는 /status로 현재 작업 상태를 확인합니다.

확인할 것

현재 workspace root
sandbox mode
approval policy
사용 중인 model
network access 여부
현재 session/thread 정보

특히 sandbox 관련 문제가 생기면 먼저 workspace root가 맞는지 확인해야 합니다. 예를 들어 apps/frontend에서 실행했는데 실제 수정 대상이 packages/shared라면 Codex는 권한 밖 파일을 수정하려고 하거나 계속 approval을 요구할 수 있습니다.

해결 예

codex --cd apps/frontend --add-dir ../shared

17/config 확인

설정 문제는 대부분 "내가 생각한 config와 실제 적용 config가 다를 때" 발생합니다.

확인할 것

user config
project config
profile config
CLI override
managed requirements
system config

Codex는 user-level config를 ~/.codex/config.toml에서 읽고, trusted project에서는 .codex/config.toml도 읽습니다. Project config는 일부 provider, auth, telemetry routing 등 machine-local 성격의 키를 override할 수 없으며, profile 파일은 ~/.codex/profile-name.config.toml 형태로 config.toml 옆에 둡니다.

일회성 override 예시

codex --config model='"gpt-5.4"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

18인증 문제

인증 문제의 증상과 확인 방법을 알아봅시다.

문제 증상

로그인이 풀림
모델 목록이 이상함
API key 사용량이 예상과 다름
Cloud task 생성 실패
IDE와 CLI의 계정이 다름

확인 명령

codex login
codex logout
codex doctor --summary

문제 해결 순서

CLI와 IDE가 같은 계정인지 확인
ChatGPT 로그인인지 API Key 로그인인지 확인
회사 workspace 계정인지 개인 계정인지 확인
모델 권한과 플랜 권한 확인
필요하면 logout 후 재로그인

19sandbox 문제

sandbox 문제의 대표 증상과 해결 방법을 알아봅시다.

문제 증상

파일을 읽지 못함
파일을 수정하지 못함
명령이 permission denied로 실패함
네트워크 요청이 막힘
workspace 밖 파일 접근이 거부됨

sandbox_mode는 read-only, workspace-write, danger-full-access 값을 사용할 수 있으며, command execution 중 파일시스템과 네트워크 접근 정책을 결정합니다.

20approval 문제

approval 문제는 Codex가 계속 "승인해도 되냐"고 물어보거나, 반대로 물어보지 않고 너무 많이 실행할 때 발생합니다.

approval_policy 옵션

untrusted
on-request
never
granular 설정

Interactive run에는 on-request, non-interactive run에는 never를 사용하는 것이 권장됩니다.

21auto-review 설정

Auto-review를 붙이면 approval이 필요한 요청을 reviewer agent로 먼저 보낼 수 있습니다.

설정 예시

approval_policy = "on-request"
approvals_reviewer = "auto_review"

approvals_reviewer = "auto_review"는 approval이 필요한 요청을 reviewer agent로 먼저 보내는 설정입니다. Reviewer는 sandbox escalation, blocked network request, permission request, side-effecting app/MCP tool call 등을 검토하며, data exfiltration, credential probing, destructive action 같은 위험을 평가합니다.

자동 리뷰는 추가 모델 호출을 사용하므로 usage가 증가할 수 있습니다.

22MCP / plugin 문제

MCP 문제의 증상과 확인 방법을 알아봅시다.

문제 증상

세션 시작이 느림
도구 목록이 너무 많음
외부 서비스 인증 실패
MCP tool call이 계속 실패
모델이 엉뚱한 도구를 쓰려 함

확인 방법

codex mcp list
codex doctor --summary

MCP가 의심되면 먼저 전부 비활성화하고 재현해봅니다. Plugin 문제는 최근 설치한 plugin을 비활성화하거나, hook 포함 plugin인지 확인하고, plugin이 추가한 MCP 서버를 확인한 뒤 최소 구성으로 실행합니다.

23shell 환경 문제

shell 환경 문제는 초보자가 가장 자주 만나는 문제입니다.

문제 증상

npm이 없다고 함
python venv를 못 찾음
환경변수가 없음
테스트 명령이 내 terminal에서는 되는데 Codex에서는 안 됨
PATH가 다름

24shell_environment_policy 설정

shell_environment_policy를 쓰면 subprocess에 전달되는 환경변수를 통제할 수 있습니다.

보수적 설정 예시

[shell_environment_policy]
inherit = "core"
include_only = ["PATH", "HOME", "USER", "SHELL", "NODE_ENV"]
exclude = ["*SECRET*", "*TOKEN*", "*KEY*"]

include_only는 허용할 변수 패턴만 남기고, exclude는 특정 패턴을 제거하며, inherit은 all, core, none 값을 사용할 수 있습니다.

25Git 상태 문제

Codex 작업 전후에는 항상 Git 상태를 봅니다.

확인 명령

git status
git diff
git branch --show-current

문제 증상

Codex가 수정한 내용과 내 수정이 섞임
원하지 않는 파일이 변경됨
generated file이 대량 변경됨
다른 branch에서 작업 중이었음
worktree가 꼬임

안전 루틴

git status
git stash push -m "before codex work"
codex
git diff
npm test

26로그 확인과 자주 나오는 에러

문제를 재현할 때는 다음 형식으로 Codex에게 전달합니다.

좋은 프롬프트 구조

문제: 무엇이 실패했는가
재현 명령: 실행한 명령
실제 결과: 에러 로그의 핵심 100줄 이하
기대 결과: 어떤 상태가 되어야 하는가
제약: 수정 범위, 금지 작업, 테스트 명령

자주 나오는 에러별 대응

파일 수정 실패

sandbox, writable root 확인

명령 실행 실패

approval, shell env 확인

네트워크 실패

network_access 확인

MCP 실패

MCP 인증, 서버 실행 여부 확인

느림

context, MCP 수, reasoning effort 확인

28-C · 보안 가이드

27Codex 사용 시 보안 원칙

Codex 보안의 기본은 "똑똑한 agent를 믿는 것"이 아니라, agent가 할 수 있는 일을 제한하는 것입니다.

핵심 원칙

최소 권한으로 시작한다.
workspace 밖 파일 접근을 제한한다.
network access는 기본 off로 둔다.
secret은 환경변수와 파일에서 최대한 분리한다.
위험한 명령은 approval이나 rules로 막는다.
diff와 테스트를 반드시 확인한다.

workspace-write sandbox는 기본적으로 network access가 꺼져 있습니다. Network access를 켜려면 [sandbox_workspace_write] network_access = true를 설정해야 합니다.

28OS 수준 sandbox 이해

Sandbox는 Codex가 실행하는 command의 파일시스템·네트워크 접근 범위를 제한합니다.

sandbox_mode 옵션

read-only - 파일 읽기 중심, 수정 불가, 안전한 분석용
workspace-write - 현재 workspace 안에서 읽기/수정 가능, 로컬 개발 기본 추천
danger-full-access - sandbox와 approval 우회 가능, 매우 위험, 격리 container에서만 사용

danger-full-access 또는 --dangerously-bypass-approvals-and-sandbox 사용 시 주의해야 하며, 필요한 경우 Docker 같은 격리 환경 안에서 사용해야 합니다.

29민감한 파일 보호

다음 파일들은 특별히 조심해야 합니다.

민감한 파일 예시

.env, .env.local
*.pem, *.key
id_rsa
~/.ssh
credentials.json, service-account.json
production database dump
customer export CSV

팀 정책 예시

[permissions.filesystem]
deny_read = [
  "/**/*.env",
  "~/.ssh",
  "~/.aws",
]

개인 설정에서는 shell environment에서 secret을 줄이고, 팀 설정에서는 managed requirements로 deny-read를 강제하는 편이 좋습니다.

30환경 변수와 secret 관리

환경변수는 편하지만, agent가 shell 명령을 실행할 수 있으면 의도치 않게 노출될 수 있습니다.

위험한 예

export OPENAI_API_KEY=...
export PROD_DB_PASSWORD=...
codex --sandbox danger-full-access

더 안전한 방식

[shell_environment_policy]
inherit = "core"
exclude = ["*SECRET*", "*TOKEN*", "*KEY*", "*PASSWORD*"]

운영 원칙

production secret은 로컬 Codex session에 넣지 않는다.
CI secret은 필요한 step에서만 주입한다.
secret이 필요한 setup은 사람이 직접 수행한다.
Codex에게 secret 값을 출력하거나 파일에 쓰게 하지 않는다.

31shell_environment_policy 심화

shell_environment_policy는 Codex가 subprocess를 실행할 때 어떤 환경변수를 물려줄지 정하는 설정입니다.

핵심 키

inherit

기본 환경 상속 범위. all, core, none

include_only

허용할 변수 패턴 whitelist

exclude

제거할 변수 패턴

set

모든 subprocess에 넣을 명시적 변수

ignore_default_excludes

KEY/SECRET/TOKEN 포함 변수의 기본 제거를 무시

ignore_default_excludes는 KEY, SECRET, TOKEN이 포함된 변수를 다른 filter 전에 유지하게 하므로 보안상 매우 조심해야 합니다.

32네트워크 접근 제한

Codex가 network access를 가지면 외부 문서 확인, package 설치, API 호출 같은 작업이 쉬워집니다. 그러나 보안 관점에서는 data exfiltration과 prompt injection 위험이 커집니다.

기본 권장

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

필요한 경우에만 켠다

[sandbox_workspace_write]
network_access = true

팀 환경에서는 domain allowlist를 requirements로 통제하는 것이 낫습니다. 중앙 네트워크 요구사항을 [experimental_network]로 정의할 수 있으며, allowed/denied domains 및 managed allowlist 전용 모드를 설정할 수 있습니다.

33danger-full-access 사용 기준

danger-full-access는 편하지만 기본 작업 모드가 되어서는 안 됩니다.

사용 가능한 경우

일회성 disposable container
격리된 CI runner
비밀값이 없는 sandbox VM
실험용 repo
재현 가능한 테스트 환경

사용하면 안 되는 경우

개인 노트북의 home directory
회사 production credential이 있는 환경
고객 데이터가 있는 폴더
untrusted repository
외부에서 받은 코드

실행 전 체크

현재 폴더가 맞는가
Git 상태가 깨끗한가
secret이 환경변수에 없는가
network가 필요한가
실패해도 버릴 수 있는 환경인가

34Guardian review / Auto-review

Auto-review는 approval 요청을 사람이 보기 전에 reviewer agent가 먼저 위험도를 검토하게 하는 방식입니다.

설정

approval_policy = "on-request"
approvals_reviewer = "auto_review"

Reviewer는 sandbox escalation, blocked network request, permission request, side-effecting app/MCP tool call 등 이미 approval이 필요한 action만 평가하며, data exfiltration, credential probing, destructive action 같은 위험을 검토합니다.

팀에서 좋은 사용처

민감 repo 작업
외부 MCP 사용
network access 요청
destructive command 요청
CI runner에서 자동 patch 생성

35hooks와 보안

Hooks는 Codex lifecycle event에 맞춰 자동으로 script를 실행하는 기능입니다. 보안 관점에서는 강력하지만, 잘못 쓰면 hook 자체가 새로운 공격 표면이 됩니다.

보안 hook 예시

prompt 안에 secret 패턴이 있는지 검사
rm -rf 같은 명령 차단
git push 전 승인 요구
작업 종료 시 테스트 실행 권고
외부 URL 업로드 시 차단

팀에서는 managed hooks로 통제하는 것이 좋습니다. Admins가 requirements.toml 안에 lifecycle hooks를 정의할 수 있고, allow_managed_hooks_only = true를 사용하면 user, project, session, plugin hook은 건너뛰고 managed hook만 로드합니다.

36팀 보안 체크리스트

팀 표준 체크리스트

기본 sandbox는 workspace-write인가
danger-full-access가 금지되어 있는가
approval_policy never가 CI 외부에서 제한되어 있는가
network_access 기본값이 false인가
secret 파일 deny-read가 설정되어 있는가
MCP allowlist가 있는가
hooks 신뢰 정책이 있는가
AGENTS.md에 보안 규칙이 있는가
CI에서 API key 노출 범위가 최소화되어 있는가
diff review가 필수인가

팀용 기본 config 예시

model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

[shell_environment_policy]
inherit = "core"
exclude = ["*KEY*", "*SECRET*", "*TOKEN*", "*PASSWORD*"]

28-D · Enterprise 배포

37조직 단위 Codex 운영

조직에서 Codex를 운영할 때는 개인 생산성보다 다음 항목이 중요합니다.

조직 운영의 핵심

권한 표준화
모델과 reasoning effort 통제
network와 secret 통제
MCP와 plugin allowlist
감사 가능한 설정
팀별 profile 표준화
문제 발생 시 diagnostic report 확보

Enterprise admins는 두 가지 방식으로 Codex 동작을 통제할 수 있습니다. 하나는 사용자가 override할 수 없는 requirements이고, 다른 하나는 시작 기본값을 제공하지만 사용자가 session 중 바꿀 수 있는 managed defaults입니다.

38system config

System config는 machine 단위 기본값을 제공하는 설정입니다.

Unix 계열 위치

/etc/codex/config.toml이 system config 계층으로 사용될 수 있습니다.

설정 우선순위

System config는 user config보다 낮고 built-in default보다 높습니다.

예시

# /etc/codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

System config는 "권장 기본값"으로 쓰고, 강제 통제는 requirements.toml로 합니다.

39requirements.toml

requirements.toml은 조직 관리자가 보안 민감 설정을 강제하는 파일입니다.

강제하기 좋은 항목

허용 approval policy
허용 sandbox mode
허용 web search mode
auto-review 사용 여부
MCP server allowlist
feature flags
network domain policy
deny-read path
managed hooks
command rules

예시

allowed_approval_policies = ["untrusted", "on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]
allowed_web_search_modes = ["cached"]

[permissions.filesystem]
deny_read = [
  "/**/*.env",
  "~/.ssh",
]

40모델과 reasoning effort 제한

조직에서는 비용·보안·품질 균형을 위해 모델과 reasoning effort 사용 기준을 정해야 합니다.

예시 정책

일반 개발자 기본값: medium
리뷰/보안 작업: high 허용
xhigh: 팀 리드 또는 특정 profile에서만 허용
mini 모델: 탐색·subagent에 권장

profile 예시

# ~/.codex/review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "read-only"

Profile 파일은 ~/.codex/profile-name.config.toml 형태로 base user config 위에 overlay됩니다.

41permission profile 관리

Permission profile은 팀이 "어떤 작업에는 어떤 권한"을 줄지 표준화하는 방법입니다.

security-review profile 예시

model = "gpt-5.5"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = false

42감사 로그와 OpenTelemetry

대규모 조직에서는 Codex 사용량, 실패, 승인 흐름, 설정 drift를 추적해야 합니다.

관찰할 항목

어떤 repo에서 Codex가 사용되는가
어떤 profile이 많이 쓰이는가
approval request가 어디서 많이 발생하는가
danger-full-access 시도가 있는가
network access 요청이 있는가
auto-review가 무엇을 차단했는가
CI 자동화가 얼마나 실패하는가

OTel 설정 예시

[otel]
environment = "prod"
exporter = "otlp-http"
log_user_prompt = false

43SSO / 계정 관리

조직에서는 개인 API key 중심 운영보다 workspace 계정과 중앙 관리가 낫습니다.

운영 기준

개인 계정과 회사 workspace 계정을 분리한다.
팀원에게 동일한 로그인 방식을 안내한다.
퇴사자 access를 즉시 회수한다.
Cloud, CLI, IDE, App에서 같은 workspace 기준으로 운영한다.
API key는 CI나 서버 자동화에만 제한적으로 사용한다.

문서화 항목

로그인 방식
허용 계정
허용 모델
허용 workspace
지원되는 Codex surface
문제 발생 시 doctor report 제출 방식

44대규모 조직 운영 전략

대규모 조직에서는 "Codex를 쓰게 허용"하는 것보다 "어떻게 쓰게 할지"가 더 중요합니다.

도입 순서

개인 생산성 실험
팀별 profile 표준화
AGENTS.md 표준 템플릿 배포
MCP allowlist 정리
requirements.toml로 위험 설정 제한
CI/CD 자동 리뷰 연결
telemetry와 doctor report 기반 운영
보안·법무·플랫폼 팀과 정책 정례 점검

조직 운영 원칙

기본값은 안전하게 둔다.
강제 정책은 최소한으로 시작한다.
위험 권한은 예외 승인제로 운영한다.
MCP와 plugin은 allowlist 중심으로 관리한다.
자동화 결과는 사람이 검토할 수 있게 남긴다.
비용이 큰 모델과 xhigh는 목적 기반으로 제한한다.

섹션 28 · 마무리

이 단원에서 기억할 것

Codex를 빠르게 만들려면 context를 줄이고, Codex를 안전하게 만들려면 권한을 줄이고, Codex를 조직에서 쓰려면 설정을 표준화한다.

성능 최적화

Context를 줄인다.
긴 대화는 /compact한다.
@file과 로그를 최소화한다.
MCP는 필요한 것만 켠다.
fast profile과 낮은 reasoning effort를 작업별로 쓴다.

문제 디버깅

git status, /status, /config, codex doctor를 먼저 본다.
인증, sandbox, approval, MCP, shell 환경을 순서대로 확인한다.
로그는 짧고 재현 가능하게 정리한다.

보안과 엔터프라이즈

기본은 workspace-write + on-request + network off.
Secret과 민감 파일은 deny-read 또는 shell 환경 정책으로 보호한다.
danger-full-access는 격리 환경에서만 쓴다.
Hooks와 auto-review로 위험 동작을 통제한다.
System config는 기본값, requirements.toml은 강제 정책.
Managed config와 OTel로 조직 운영을 표준화한다.

다음 단원

29단원. 실전 워크플로와 마이그레이션

29. 실전 워크플로와 마이그레이션

01이 단원의 핵심

Codex를 잘 쓰는 사람은 "큰 일을 한 번에 맡기는 사람"이 아니라, 작업을 작게 나누고 검증 루프를 만드는 사람입니다.

나쁜 흐름:

전체 프로젝트를 보고 알아서 개선해줘.

좋은 흐름:

1. 문제 범위를 좁힌다.
2. 먼저 plan을 받는다.
3. 작은 변경만 시킨다.
4. diff를 확인한다.
5. 테스트를 실행한다.
6. 실패하면 로그를 다시 준다.
7. 최종 요약과 커밋 메시지를 받는다.

OpenAI의 Codex best practices도 어려운 작업은 먼저 plan을 세우고, 반복되는 지침은 AGENTS.md로 재사용 가능하게 만들라고 권장합니다.

02좋은 프롬프트 작성법

좋은 프롬프트는 다음 5가지를 포함합니다.

1. 목표

무엇을 해야 하는가

2. 수정 범위

어디서만 확인해야 하는가

3. 금지할 작업

하지 말아야 할 것은 무엇인가

4. 검증 명령

어떻게 확인할 것인가

5. 원하는 출력 형식

어떤 형태로 답변받을 것인가

03좋은 프롬프트 예시

목표:
로그인 실패 시 500이 아니라 401을 반환하도록 수정해줘.

수정 범위:
src/auth, tests/auth 안에서만 확인해줘.

금지:
전체 인증 구조 리팩터링은 하지 마.
관련 없는 formatting 변경도 하지 마.

검증:
npm test -- auth

출력:
- 원인
- 수정 파일
- 테스트 결과
- 남은 리스크

Codex는 사용자의 prompt를 받은 뒤 모델 호출, 파일 읽기, 파일 편집, tool call 같은 작업을 반복하며 task를 완료합니다. 처음 prompt가 구체적일수록 Codex가 불필요한 탐색을 줄이고 더 정확하게 행동합니다.

04나쁜 프롬프트 패턴

피해야 할 프롬프트는 대부분 범위가 너무 넓습니다.

이 프로젝트를 개선해줘.
버그를 다 찾아줘.
성능을 좋게 만들어줘.
보안을 강화해줘.
전체 코드를 리팩터링해줘.
테스트도 알아서 추가해줘.

이런 요청이 나쁜 이유는 Codex가 무엇을 성공으로 봐야 하는지 알기 어렵기 때문입니다.

05나쁜 프롬프트 개선 예시

나쁜 요청:

성능 개선해줘.

좋은 요청:

orders API 응답 시간이 느린 원인을 찾아줘.
먼저 src/api/orders와 src/db/orders 관련 파일만 확인하고,
수정 전에는 병목 후보 3개 이하로 정리해줘.

06작은 작업으로 쪼개기

Codex 작업은 작을수록 성공률이 높습니다.

큰 작업:

결제 시스템을 리팩터링해줘.

작게 쪼갠 작업:

1. 결제 생성 흐름의 entrypoint를 찾아줘.
2. 실패 처리 로직만 설명해줘.
3. retry 조건이 중복된 부분을 찾아줘.
4. 수정 계획을 세워줘.
5. 한 파일만 먼저 수정해줘.
6. 관련 테스트를 추가해줘.
7. 전체 diff를 리뷰해줘.

07작업 크기별 추천 방식

5분짜리 수정

바로 수정 요청 가능

30분짜리 버그

원인 분석 → plan → 수정

반나절 리팩터링

/plan 또는 별도 thread

여러 모듈 변경

task 분리 또는 subagent

장기 작업

Cloud / Worktree / PR 단위

08plan 먼저, 실행은 나중에

복잡한 작업은 먼저 plan을 받아야 합니다.

먼저 plan만 작성해줘.
파일 수정은 하지 마.
수정 대상 파일, 변경 이유, 테스트 전략을 보여줘.

좋은 plan 요청:

결제 실패 시 중복 결제가 발생할 수 있는지 검토해줘.
먼저 코드를 수정하지 말고,
1. 관련 파일
2. 현재 흐름
3. 위험 지점
4. 수정 계획
5. 필요한 테스트
순서로 정리해줘.

09plan 승인 후 실행

그다음 실행을 승인합니다.

좋아. 2번 계획대로 진행해줘.
단, public API 시그니처는 바꾸지 말고,
수정 후 npm test -- payments를 실행해줘.

공식 best practices도 어려운 작업에서는 Codex에게 먼저 plan을 요청하고, 사용자가 방향을 확인한 뒤 구현시키는 흐름을 권장합니다.

10diff를 반드시 확인하는 습관

Codex가 코드를 수정한 뒤에는 반드시 diff를 확인해야 합니다.

git diff

확인할 항목:

수정 범위가 요청과 일치하는가
관련 없는 파일이 바뀌지 않았는가
테스트 코드가 실제 동작을 검증하는가
불필요한 리팩터링이 섞이지 않았는가
민감한 값이 새로 추가되지 않았는가

11diff 리뷰 요청 예시

방금 변경한 diff를 스스로 리뷰해줘.
특히 아래 항목만 확인해줘.

1. 관련 없는 변경
2. 테스트 누락
3. edge case
4. 보안 위험
5. 더 작은 수정으로 줄일 수 있는 부분

Codex app은 여러 thread를 병렬로 다루고, Git 기능과 worktree support를 제공합니다. diff를 눈으로 검토하고 stage/revert하는 흐름이 필요하면 Desktop App이 CLI보다 편합니다.

12테스트 명령을 명시하는 법

Codex에게 "테스트도 해줘"라고만 말하면 충분하지 않습니다. 프로젝트마다 테스트 명령이 다르기 때문입니다.

좋은 예시(Node.js):

수정 후 아래 명령을 실행해줘.

npm test -- auth
npm run typecheck
npm run lint

13Python / Rust 테스트 명령

Python 프로젝트:

수정 후 아래 명령을 실행해줘.

pytest tests/auth -q
ruff check .
mypy .

Rust 프로젝트:

수정 후 아래 명령을 실행해줘.

cargo test auth
cargo clippy

14테스트 실패 시 대응

테스트 실패 시에는 전체 로그를 붙이지 말고 핵심만 전달합니다.

아래 실패 로그를 기준으로 최소 수정해줘.
전체 리팩터링은 하지 마.

명령:
npm test -- auth

실패:
...

15AGENTS.md를 방치하지 않기

반복해서 말하는 지침은 prompt에 매번 쓰지 말고 AGENTS.md에 넣는 것이 좋습니다.

AGENTS.md에 넣기 좋은 내용:

프로젝트 구조
코딩 스타일
테스트 명령
빌드 명령
금지 작업
PR 리뷰 기준
보안 주의사항
파일 생성 규칙

16AGENTS.md 예시

# AGENTS.md

## 작업 원칙
- 관련 없는 리팩터링 금지
- public API 변경 전 반드시 plan 작성
- 테스트 없이 완료 보고 금지

## 테스트
- unit test: npm test
- typecheck: npm run typecheck
- lint: npm run lint

## 보안
- .env, secret, token 파일 읽기 금지
- 인증/결제 로직 변경 시 edge case를 반드시 설명

Codex는 작업 전에 AGENTS.md 파일을 읽으며, global guidance와 project-specific override를 계층적으로 적용합니다. 좋은 AGENTS.md는 짧고 명확해야 합니다.

17MCP를 과하게 붙이지 않기

MCP는 강력하지만, 모든 도구를 항상 연결하면 Codex가 느려지고 context가 복잡해집니다.

좋은 기준:

자주 쓰는 MCP만 기본 활성화
가끔 쓰는 MCP는 profile로 분리
민감한 외부 서비스는 read-only로 시작
팀 MCP는 allowlist로 관리

OpenAI best practices는 MCP를 repo 밖의 context가 필요하거나, 자주 변하는 외부 정보가 있거나, 반복 가능한 통합이 필요할 때 쓰라고 설명합니다. 처음부터 많은 도구를 붙이기보다 실제 workflow를 줄여주는 1~2개부터 시작하는 편이 좋습니다.

18reasoning effort 올바르게 사용

xhigh 같은 높은 reasoning effort는 복잡한 판단에는 유용하지만, 모든 작업에 쓸 필요는 없습니다.

low

로그 요약, 간단한 문서 정리, 작은 타입 오류

medium

일반 기능 수정, 테스트 추가, 보통 난이도 버그

high

여러 파일이 얽힌 버그, 리팩터링 계획, 보안 리뷰

xhigh

아키텍처 결정, 복잡한 동시성 문제, 결제/인증/권한 로직

작은 작업에 xhigh를 계속 쓰면 비용과 시간이 늘어납니다. 처음에는 medium을 기본으로 두고, 실패하거나 위험도가 높을 때만 올리는 것이 좋습니다.

19Codex에게 맡기면 안 되는 작업

Codex에게 시키면 안 되는 작업도 있습니다.

검토 없이 production 배포
고객 데이터 전체 분석
secret, token, private key 읽기
법률·의료·재무 판단을 단독 결정
보안 우회 방법 구현
권한 없는 시스템 접근
대규모 삭제 명령 자동 실행
테스트 없이 자동 merge

20위험한 작업 올바르게 요청하기

위험한 작업은 이렇게 바꿔야 합니다.

나쁜 요청:

production DB에서 문제를 찾아서 고쳐줘.

좋은 요청:

아래 anonymized error log를 기준으로 원인 후보를 분석해줘.
실제 DB 접근이나 수정은 하지 마.

21처음 보는 코드베이스 분석

처음 보는 repo에서는 바로 수정시키지 않습니다.

22코드베이스 분석 단계적 접근

첫 설명 후 더 좁혀서 물어봅니다.

인증 흐름만 더 자세히 설명해줘.
관련 파일 후보를 10개 이하로 정리하고,
아직 수정은 하지 마.

CLI는 repository를 읽고, 파일을 수정하고, 명령을 실행하면서 사용자와 대화형으로 반복 작업할 수 있는 환경입니다. 처음 보는 코드베이스에서는 interactive CLI나 IDE에서 구조 파악부터 시작하는 것이 좋습니다.

23실패한 테스트 고치기

테스트 실패는 Codex가 잘하는 작업 중 하나입니다. 전체 로그를 던지는 것보다 실패 범위를 좁혀야 합니다.

흐름:

실패한 테스트 명령 실행
핵심 로그만 전달
원인 후보 먼저 요청
최소 수정 요청
테스트 재실행
diff 리뷰

24테스트 실패 프롬프트

아래 테스트 실패를 분석해줘.
먼저 원인 후보를 3개 이하로 정리하고,
가장 가능성 높은 원인부터 최소 수정해줘.

명령:
npm test -- auth

로그:
...

수정 후:

수정한 부분을 설명하고,
왜 이 테스트가 통과해야 하는지 알려줘.
관련 없는 변경이 있는지도 확인해줘.

25신규 API 엔드포인트 추가

API 추가는 범위가 넓어지기 쉽습니다. 구조를 먼저 찾게 합니다.

새 API 엔드포인트를 추가하려고 해.
먼저 기존 API 패턴을 조사해줘.

목표:
POST /api/orders/:id/cancel 추가

먼저 수정하지 말고 아래만 정리해줘.
1. 기존 route 정의 위치
2. controller/service 구조
3. validation 방식
4. 테스트 위치
5. 구현 계획

26API 엔드포인트 구현 및 마무리

계획 확인 후:

좋아. 기존 패턴을 유지해서 구현해줘.
수정 범위:
- route
- controller
- service
- tests/orders

금지:
공통 error handler 리팩터링 금지

마무리:

변경 파일, 테스트 결과, API 사용 예시를 정리해줘.

27리팩터링 계획 세우기

리팩터링은 바로 실행하면 위험합니다. 반드시 plan부터 받아야 합니다.

이 모듈을 리팩터링하고 싶어.
아직 파일은 수정하지 마.

목표:
중복된 validation 로직을 줄이고 테스트 가능성을 높이기

출력:
1. 현재 구조 문제
2. 리팩터링 후보
3. 위험도
4. 단계별 plan
5. 각 단계마다 실행할 테스트

28리팩터링 단계별 실행

좋은 리팩터링은 한 번에 끝내지 않습니다.

1단계: 코드 이동 없이 중복 함수 추출
2단계: 테스트 추가
3단계: 호출부 교체
4단계: deprecated 코드 제거
5단계: 전체 테스트

Worktree를 쓰면 같은 repository에서 독립 작업을 병렬로 실행하면서 서로 방해하지 않게 할 수 있습니다. 실험적 리팩터링은 기존 작업과 섞지 말고 worktree 또는 별도 branch에서 진행하는 것이 안전합니다.

29보안 리뷰하기

보안 리뷰는 read-only로 시작하는 것이 좋습니다.

현재 branch의 diff를 보안 관점에서 리뷰해줘.
파일 수정은 하지 마.

집중할 항목:
1. 인증 우회 가능성
2. 권한 체크 누락
3. 입력값 검증 부족
4. secret 노출
5. SSRF / SQL injection / XSS 가능성
6. 로그에 민감정보가 남는지

30보안 리뷰 결과 형식 및 수정

리뷰 결과 형식:

각 이슈마다 아래 형식으로 작성해줘.

- 위험도: high / medium / low
- 위치:
- 문제:
- 공격 시나리오:
- 수정 방향:
- 테스트 제안:

수정은 별도 단계로 넘깁니다.

위 리뷰 중 high 위험도 1번만 수정해줘.
수정 후 관련 테스트를 추가하고,
다른 항목은 건드리지 마.

31PR 리뷰 자동화

PR 리뷰는 사람의 리뷰를 대체하기보다, 놓치기 쉬운 항목을 먼저 걸러내는 용도로 쓰는 것이 좋습니다.

로컬에서:

git diff origin/main...HEAD | codex exec \
  "이 PR diff를 리뷰해줘.
   출력:
   1. 치명적 버그 가능성
   2. 테스트 누락
   3. 보안 위험
   4. 불필요한 변경
   5. 병합 전 확인사항" \
  -o codex-pr-review.md

32PR 리뷰 CI 자동화

CI에서:

PR 생성
GitHub Action 실행
diff를 Codex에게 전달
리뷰 결과를 artifact 또는 comment로 저장
사람이 최종 확인

Codex GitHub Action은 GitHub Actions workflow에서 반복 가능한 Codex 작업을 실행해 PR 리뷰, release prep, migration 같은 작업을 자동화할 수 있게 합니다.

33문서 자동 업데이트

코드 변경 후 문서가 따라가지 않는 경우가 많습니다. Codex에게 문서 차이를 찾게 하면 좋습니다.

현재 git diff를 기준으로 문서 업데이트가 필요한 부분을 찾아줘.
아직 문서는 수정하지 말고,
업데이트 후보와 이유만 정리해줘.

수정 요청:

README의 API 사용 예시만 업데이트해줘.
코드 파일은 수정하지 마.
기존 문체와 형식을 유지해줘.

34마이그레이션 작업 계획

마이그레이션은 실패 위험이 크므로 단계별로 나눠야 합니다.

예시: 라이브러리 v1에서 v2로 이동

라이브러리 v1에서 v2로 마이그레이션하려고 해.
먼저 파일 수정 없이 영향 범위를 조사해줘.

출력:
1. v1 API 사용 위치
2. 변경이 필요한 패턴
3. 위험한 호출부
4. 단계별 마이그레이션 계획
5. 테스트 전략

35마이그레이션 단계별 실행

그다음 작은 단위로 실행합니다.

1단계만 진행해줘.
deprecated import를 새 import로 바꾸되,
동작 로직은 바꾸지 마.
수정 후 typecheck만 실행해줘.

좋은 마이그레이션 원칙:

한 번에 전체 변경 금지
검색 결과 먼저 확인
자동 변경 후 diff 리뷰
테스트를 작은 범위부터 실행
fallback plan 준비

36릴리즈 노트 생성

릴리즈 노트는 codex exec와 잘 맞습니다.

git log --oneline v1.2.0..HEAD | codex exec \
  "이 커밋 목록을 사용자용 릴리즈 노트로 정리해줘.
   내부 구현 세부사항보다 사용자 영향 중심으로 작성해줘." \
  -o release-notes.md

더 좋은 입력:

git log --oneline v1.2.0..HEAD > commits.txt
git diff --stat v1.2.0..HEAD > diff-stat.txt

37릴리즈 노트 상세 실행

codex exec \
  "commits.txt와 diff-stat.txt를 기준으로 릴리즈 노트를 작성해줘.
   섹션:
   - Added
   - Changed
   - Fixed
   - Migration Notes
   - Known Issues" \
  -o release-notes.md

codex exec는 대화형 TUI를 열지 않고 script나 CI에서 Codex를 실행하는 non-interactive mode입니다. 릴리즈 노트처럼 반복 가능한 출력 생성 작업에 적합합니다.

38이슈 triage

이슈 triage는 "수정"보다 "분류"에 집중합니다.

아래 GitHub issue를 triage해줘.
코드는 수정하지 마.

출력:
1. 유형: bug / feature / question / docs
2. 우선순위: P0 / P1 / P2 / P3
3. 재현 가능성
4. 필요한 추가 정보
5. 관련 코드 후보
6. 다음 담당자에게 줄 요약

39이슈 triage 자동화 schema

여러 이슈를 자동화할 때는 schema를 정하면 좋습니다.

{
  "type": "bug",
  "priority": "P2",
  "needs_reproduction": true,
  "missing_info": ["version", "logs"],
  "suggested_owner": "frontend"
}

40팀 온보딩 자료 만들기

Codex는 기존 repo를 읽고 온보딩 문서 초안을 만드는 데 유용합니다.

신입 개발자를 위한 온보딩 문서 초안을 작성해줘.
파일은 아직 만들지 말고 먼저 목차만 제안해줘.

포함:
1. 프로젝트 목적
2. 로컬 실행 방법
3. 테스트 방법
4. 주요 디렉터리
5. 배포 흐름
6. 자주 나는 오류
7. 첫 번째 추천 이슈

41온보딩 문서 생성 및 원칙

그다음 문서 생성:

좋아. docs/onboarding.md 파일로 작성해줘.
단, 확실하지 않은 내용은 "확인 필요"로 표시해줘.

중요한 원칙:

Codex가 추측한 내용은 반드시 사람이 확인한다.
실행 명령은 실제로 테스트한다.
비밀값이나 내부 URL은 그대로 넣지 않는다.

42브라우저 기반 작업 자동화

브라우저 작업은 코드 작업과 분리해서 생각해야 합니다.

적합한 작업:

admin console에서 설정 확인
dashboard 데이터 요약
CMS 콘텐츠 수정
로그인된 웹앱에서 버그 재현
반복적인 form 입력

이 admin 페이지에서 사용자 권한 설정을 확인해줘.
변경은 하지 말고,
현재 설정값과 위험해 보이는 항목만 요약해줘.

43브라우저 자동화 주의사항

수정이 필요한 경우:

아래 항목만 변경해줘.
그 외 설정은 건드리지 마.

변경:
- Role: Viewer
- Export permission: Off

브라우저 자동화에서는 권한과 데이터 노출을 조심해야 합니다. 고객 데이터, 관리자 권한, 결제 정보, 내부 지표가 보이는 화면에서는 작업 범위를 좁히고, 필요한 사이트에만 권한을 주는 것이 안전합니다.

44다른 도구에서 Codex로 이동하기

다른 AI 코딩 도구에서 Codex로 넘어올 때는 "명령어를 그대로 바꾸는 것"보다 작업 습관을 Codex 방식으로 바꾸는 것이 중요합니다.

핵심 전환:

단발성 질문 중심 → session/thread 중심
현재 파일 수정 중심 → repo context + plan + diff 중심
즉석 지시 반복 → AGENTS.md와 profile로 재사용
수동 리뷰 → diff review + codex exec + CI 자동화
한 화면 작업 → CLI, IDE, Desktop, Cloud, Chrome 조합

45Claude Code 사용자 → Codex

Claude Code 같은 터미널 기반 agent에 익숙하다면 Codex CLI는 가장 자연스러운 시작점입니다.

전환 포인트:

터미널 대화형 작업 → Codex CLI
프로젝트 규칙 → AGENTS.md
권한 통제 → sandbox / approval
반복 자동화 → codex exec
병렬 작업 → Desktop App Worktree 또는 Cloud

46Cursor 사용자 → Codex

Cursor 사용자라면 IDE 안에서 Codex Extension을 먼저 쓰는 것이 자연스럽습니다.

전환 포인트:

현재 파일 질문 → IDE Extension
여러 파일 수정 → Codex agent mode
긴 작업 → Codex Cloud
반복 리뷰 → codex exec 또는 GitHub Action
프로젝트 규칙 → AGENTS.md

Cursor에서는 기존 IDE AI 기능과 Codex를 역할 분리하면 좋습니다.

47Cursor 역할 분리 세부 사항

IDE 기본 AI:

짧은 inline 수정
자동완성
현재 파일 설명

Codex:

여러 파일 수정
테스트 실행
리팩터링 plan
PR 리뷰
Cloud 위임

48Copilot 사용자 → Codex

Copilot에 익숙한 사용자는 "자동완성"과 "agent 작업"을 구분해야 합니다.

전환 포인트:

코드 자동완성 → 기존 IDE 보조 기능 유지 가능
여러 파일 수정 → Codex
테스트 실패 원인 분석 → Codex
PR 리뷰 자동화 → Codex GitHub Action
팀 규칙 적용 → AGENTS.md + requirements/profile

Copilot을 완전히 버려야 하는 것이 아니라, Codex를 더 큰 작업 단위에 붙이는 방식이 좋습니다.

49Copilot 작업 단계별 역할

한 줄 작성 → IDE 자동완성
함수 단위 수정 → inline edit
여러 파일 변경 → Codex agent
반복 CI 리뷰 → Codex Action

50Aider 사용자 → Codex

Aider처럼 Git 기반 코드 수정 흐름에 익숙하다면 Codex에서도 Git discipline이 중요합니다.

전환 포인트:

작업 전 git status 확인
작은 변경 단위 유지
diff 리뷰
테스트 실행
커밋 메시지 생성

51Aider 흐름 및 커밋 메시지

52기존 프로젝트에 AGENTS.md 추가하기

마이그레이션의 첫 번째 실무 작업은 AGENTS.md 추가입니다.

초기 프롬프트:

이 repo에 적합한 AGENTS.md 초안을 만들어줘.
먼저 파일은 만들지 말고,
포함해야 할 항목과 근거를 설명해줘.

그다음 생성:

좋아. 루트에 AGENTS.md를 생성해줘.
내용은 짧고 실무 지침 중심으로 작성해줘.

53AGENTS.md 초기 템플릿

# AGENTS.md

## 프로젝트 개요
- 이 프로젝트의 목적을 간단히 설명한다.

## 작업 원칙
- 관련 없는 리팩터링 금지
- 수정 전 plan 작성
- 변경 후 테스트 실행

## 명령어
- install:
- test:
- typecheck:
- lint:

## 코드 스타일
- 기존 패턴 유지
- public API 변경 전 확인

## 보안
- secret 파일 읽기 금지
- 인증/결제/권한 로직 변경 시 edge case 설명

54기존 자동화에 codex exec 붙이기

기존 shell script나 CI에 Codex를 붙일 때는 codex exec가 가장 단순합니다.

기존 테스트 스크립트:

npm test

Codex 분석 추가:

npm test 2>&1 | tee test.log || true

cat test.log | codex exec \
  "이 테스트 실패 로그를 분석해줘.
   출력:
   1. 실패한 테스트
   2. 직접 원인
   3. 관련 파일 후보
   4. 최소 수정 방향" \
  -o reports/test-analysis.md

55기존 PR workflow에 Codex 붙이기

기존 PR workflow:

git diff origin/main...HEAD

Codex 리뷰 추가:

git diff origin/main...HEAD | codex exec \
  "이 PR diff를 리뷰해줘.
   치명적 버그, 테스트 누락, 보안 위험만 지적해줘." \
  -o reports/codex-review.md

CI에서는 기본적으로 다음 조합이 안전합니다.

분석만 한다 → read-only
patch 생성 → workspace-write
승인 정책 → never
결과 저장 → artifact 또는 PR comment
자동 merge → 비추천

56팀 마이그레이션 체크리스트

팀 단위로 Codex를 도입할 때는 아래 순서가 좋습니다.

파일럿 repo 1개 선정
기본 AGENTS.md 작성
팀 공통 profile 정의
sandbox / approval 기본값 합의
MCP는 최소 1~2개만 연결
PR 리뷰 자동화 실험
실패 사례와 좋은 prompt 수집
docs/onboarding에 Codex 사용법 추가
CI 자동화 범위 확대
Enterprise 정책과 requirements 검토

57팀 표준 문서 항목

팀 표준 문서에 포함할 항목:

권장 실행 방식
금지 작업
테스트 명령
리뷰 기준
보안 규칙
MCP 사용 기준
Cloud 사용 기준
CI 자동화 기준
문제 발생 시 doctor report 수집 방법

58마이그레이션 성공 기준

마이그레이션 성공 기준:

개발자가 반복 프롬프트를 덜 쓴다.
AGENTS.md로 팀 규칙이 재사용된다.
PR 리뷰에서 누락되는 항목이 줄어든다.
테스트 실패 분석 시간이 줄어든다.
Codex가 만든 diff를 사람이 안정적으로 검토한다.
보안·권한 설정이 팀 표준으로 유지된다.

5929번 핵심 정리 ① · 좋은 사용법

좋은 사용법:

작업을 작게 나눈다.
plan을 먼저 받는다.
diff를 확인한다.
테스트 명령을 명시한다.
반복 지침은 AGENTS.md에 넣는다.
자동화는 codex exec로 시작한다.
위험 작업은 read-only 또는 plan-only로 시작한다.

6029번 핵심 정리 ② · 나쁜 사용법

나쁜 사용법:

전체 프로젝트를 한 번에 맡긴다.
테스트 없이 수정 완료로 본다.
xhigh를 항상 쓴다.
MCP를 과하게 붙인다.
secret이 있는 환경에서 danger-full-access를 쓴다.
Codex 결과를 검토 없이 merge한다.

61최종 원칙

Codex는 "대신 일하는 개발자"가 아니라, 작업을 작게 나누고 검증 루프를 빠르게 돌려주는 agent입니다.

작게 시키고, 계획을 확인하고, diff를 보고, 테스트로 닫는 흐름이 가장 안정적입니다.

섹션 29 · 마무리

이 단원에서 기억할 것

좋은 작업 습관이 Codex의 가장 중요한 성능 향상입니다.

Codex는 여러분이 어떻게 작업하는지 학습합니다. 작은 작업으로 나누고, 계획을 먼저 받고, diff를 확인하고, 테스트를 명시하는 습관이 생기면 Codex는 더 정확하고 신뢰할 수 있는 도구가 됩니다.

작게 → 계획 → 실행 → 검증 → 자동화

이 흐름을 반복하면 팀의 개발 속도와 안정성을 모두 높일 수 있습니다.

다음 단원

30단원. 빠른 참조, 업데이트, 참고 자료

30. 빠른 참조, 업데이트, 참고 자료

01이 단원의 목적

30번은 처음부터 읽는 단원이 아닙니다. 필요할 때 바로 찾는 단원입니다.

설치가 기억 안 난다

30.2로 이동

로그인이 꼬였다

30.3으로 이동

CLI 명령이 헷갈린다

30.4로 이동

slash command가 기억 안 난다

30.5로 이동

sandbox/approval 조합이 필요하다

30.6으로 이동

profile 실행법이 필요하다

30.7로 이동

Cloud 명령이 필요하다

30.10으로 이동

문제가 생겼다

30.11로 이동

업데이트 후 뭘 봐야 할지 모르겠다

30.12로 이동

공식 자료를 찾아야 한다

30.18로 이동

Codex CLI는 터미널에서 로컬 코드를 읽고, 변경하고, 명령을 실행할 수 있는 coding agent이며, 명령어와 설정은 공식 CLI reference와 configuration reference에서 확인하는 것이 가장 안전합니다.

02설치 명령어

여러 방식으로 설치할 수 있습니다.

npm 설치

npm install -g @openai/codex

Homebrew 설치

brew install codex

설치 확인

codex --version
codex --help

진단

codex doctor --summary

codex doctor는 설치, config, auth, Git, terminal, app-server, thread inventory 같은 상태를 점검하는 진단 명령입니다.

03인증 명령어

로그인과 로그아웃, 상태 확인 명령입니다.

codex login

로그인

codex logout

로그아웃

codex doctor --summary

상태 확인

문제가 있으면 이 순서로 확인

개인 계정인지 회사 workspace 계정인지 확인
CLI와 IDE가 같은 계정인지 확인
ChatGPT 로그인인지 API Key 로그인인지 확인
모델 권한과 플랜 권한 확인
필요하면 logout 후 다시 login

04기본 실행 명령어

대화형 실행과 비대화형 실행 방식입니다.

codex

대화형 CLI 실행

codex --cd path/to/project

특정 폴더에서 실행

codex "이 프로젝트 구조를 요약해줘"

프롬프트 바로 전달

codex exec "현재 git diff를 리뷰해줘"

비대화형 실행

codex e "테스트 실패 원인을 분석해줘"

짧은 별칭(exec)

Codex CLI는 interactive session뿐 아니라 codex exec 같은 non-interactive 실행도 지원하며, script나 CI에서 반복 작업을 자동화할 때 사용할 수 있습니다.

05자주 쓰는 slash commands

대화형 session에서 /를 입력해 빠르게 열 수 있는 명령들입니다.

/new

새 대화 시작

/resume

이전 session 이어가기

/fork

현재 대화를 분기

/model

모델 변경

/compact

긴 대화 압축

/diff

변경사항 확인

/review

리뷰 요청

/plan

계획 모드

/goal

장기 목표 설정

/status

현재 상태 확인

/permissions

권한 확인·변경

/mcp

MCP 상태 확인

/skills

Skills 확인

/config

설정 확인

/logout

로그아웃

06sandbox / approval 조합

작업 성격에 따라 권한 조합을 선택합니다. 각각의 조합은 서로 다른 상황을 위해 설계되었습니다.

기본 추천

sandbox_mode = "workspace-write"
approval_policy = "on-request"

읽기 전용 분석

sandbox_mode = "read-only"
approval_policy = "on-request"

CI 분석

sandbox_mode = "read-only"
approval_policy = "never"

CI patch 생성

sandbox_mode = "workspace-write"
approval_policy = "never"

고위험 전체 접근 (매우 주의)

sandbox_mode = "danger-full-access"
approval_policy = "never"

danger-full-access는 격리된 container, disposable VM, trusted CI runner처럼 실패해도 버릴 수 있는 환경에서만 사용해야 합니다.

07profile 실행 명령어

profile은 작업 모드를 저장해두는 방법입니다. 같은 설정을 반복해서 쓸 때 유용합니다.

codex --profile fast

저장된 profile 실행

codex --profile review

리뷰용 profile

codex exec --profile ci "현재 PR diff를 리뷰해줘"

CI용 profile

08model 변경 명령어

모델은 여러 방법으로 변경할 수 있습니다.

/model

session 중 대화형으로 변경

codex --model gpt-5.5

실행 시 지정

config 파일에서 지정

model = "gpt-5.5"
model_reasoning_effort = "medium"

일회성 override

codex --config model='"gpt-5.5"'
codex --config model_reasoning_effort='"high"'

Codex CLI는 ~/.codex/config.toml의 기본값을 상속하고, 명령줄에서 넘긴 override가 더 높은 우선순위를 가집니다.

09config 확인 명령어

설정 파일의 위치와 확인 방법입니다.

설정 파일 위치 (우선순위 순)

~/.codex/config.toml

사용자 전역 설정

.codex/config.toml

프로젝트 로컬 설정

/etc/codex/config.toml

시스템 전역 설정

확인 방법

/config

session에서 대화형 확인

codex doctor --summary

진단으로 확인

codex doctor --json > codex-doctor.json

JSON으로 저장

10Cloud 명령어

Codex Cloud에서 background 작업을 수행하고 결과를 가져오는 명령입니다.

codex cloud

Cloud task 탐색

codex cloud list

Cloud task 목록

codex cloud list --json

JSON 출력

codex cloud exec --env ENV_ID "작업"

Cloud task 생성

codex cloud exec --env ENV_ID --attempts 3 "작업"

여러 시도 요청

codex apply TASK_ID

완료된 Cloud task를 로컬에 적용

codex a TASK_ID

짧은 별칭(apply)

11troubleshooting 명령어

문제가 생겼을 때 이 순서로 확인합니다.

가장 먼저 확인

pwd
git status
codex doctor --summary

세부 확인 항목

/config

config 문제 확인

/status

session 상태 확인

codex mcp list

MCP 문제 확인

codex cloud list --json

Cloud 문제 확인

git diff

Git 상태 확인

codex doctor --json > codex-doctor.json

문제 보고용 저장

문제가 생겼을 때는 프롬프트를 다시 쓰기 전에 Git 상태, session 상태, config 적용값, 인증 상태, sandbox/approval, MCP, shell 환경 순서로 확인하는 것이 안전합니다.

12버전 업데이트를 봐야 하는 이유

Codex는 CLI, Desktop App, IDE Extension, Cloud, MCP, Skills, Plugins 같은 여러 영역이 함께 발전합니다. 따라서 업데이트 후에는 기능 추가뿐 아니라 deprecated, removed, experimental 상태도 확인해야 합니다.

특히 확인할 항목

CLI 명령 변경
config 키 변경
sandbox / approval 동작 변경
Cloud task 명령 변경
IDE slash command 변경
MCP / plugin 호환성
실험 기능의 안정화 여부
deprecated 기능 제거 여부

Codex changelog는 Goal mode, app, IDE, CLI 등 Codex surface별 기능 변화를 확인하는 공식 업데이트 문서입니다.

13Stable 기능

Stable 기능은 일반 사용과 팀 표준 workflow에 넣기 좋은 기능입니다.

codex CLI

stable

codex exec

stable

config.toml

stable

AGENTS.md

stable

sandbox / approval

stable

slash commands

stable

codex doctor

stable

Codex app의 기본 Git workflow

stable

Stable 기능이라고 해도 무조건 안전하다는 뜻은 아닙니다. danger-full-access는 기능이 제공되더라도 사용 환경 자체가 위험할 수 있습니다. 실제 보안 판단은 sandbox, approval, network, secret 상태까지 함께 봐야 합니다.

14Experimental 기능

Experimental 기능은 빠르게 변할 수 있으므로 신중해야 합니다.

일부 subagent workflow
새로운 Cloud CLI 흐름
새로운 permission profile 기능
일부 plugin / skills 연동

Experimental 기능은 개인 실험이나 작은 팀 파일럿에는 쓸 수 있지만, CI 핵심 경로, production 배포 자동화, 조직 표준 workflow에 바로 넣는 것은 조심해야 합니다.

15Deprecated 기능

Deprecated는 아직 남아 있지만 앞으로 제거되거나 대체될 수 있는 기능입니다.

확인할 것

대체 명령이 있는가
config 키 이름이 바뀌었는가
기존 profile이 계속 동작하는가
CI script가 deprecated flag에 의존하는가
팀 문서에 오래된 방식이 남아 있는가

업데이트 후에는 deprecated 항목을 바로 지우기보다, 먼저 대체 방식으로 migration plan을 세우는 것이 좋습니다.

16Removed 기능

Removed는 더 이상 사용할 수 없는 기능입니다.

업데이트 후 갑자기 깨지는 경우 확인할 것

CLI flag가 사라졌는가
config key가 제거되었는가
profile 방식이 바뀌었는가
MCP 설정 방식이 바뀌었는가
plugin이 현재 Codex 버전과 호환되는가

App Server 문서와 CLI reference에는 기능 stage가 beta, underDevelopment, stable, deprecated, removed처럼 표시될 수 있으므로, 자동화나 팀 표준에 넣은 기능은 업데이트 때 maturity 상태를 함께 확인해야 합니다.

17업데이트 후 체크리스트

Codex 업데이트 후 이 순서로 확인합니다.

codex --version 확인
codex doctor --summary 실행
/config로 실제 적용 설정 확인
profile이 정상 적용되는지 확인
sandbox / approval 기본값 확인
MCP 서버 연결 확인
hooks / plugins 오류 확인
CI의 codex exec workflow 확인
Cloud task 생성과 apply 확인
팀 문서와 AGENTS.md 업데이트

가장 위험한 상황은 "명령은 실행되지만 이전과 다른 권한·설정으로 실행되는 것"입니다. 따라서 version만 보지 말고 실제 적용 config와 sandbox/approval 상태까지 확인해야 합니다.

18공식 문서

가장 먼저 볼 문서들입니다. 모두 OpenAI 공식 문서입니다.

Codex overview
Codex CLI
Command line options
Slash commands
Config basics
Configuration reference
Agent approvals & security
Codex Cloud
Codex App
IDE Extension

Codex overview는 Codex가 OpenAI의 software development용 coding agent이며, CLI, app, IDE, cloud 등 여러 surface에서 사용할 수 있음을 설명합니다.

19GitHub Releases와 Changelog

업데이트 세부사항은 GitHub release와 Codex changelog를 함께 봅니다.

확인할 것

CLI version
breaking change
deprecated flag
new command
bug fix
security fix
config migration note

Changelog는 기능 추가와 변경 흐름을 빠르게 보는 곳이고, CLI reference는 현재 명령과 flag의 정확한 동작을 확인하는 곳입니다.

20모델 및 가격 페이지

모델과 가격은 변할 수 있으므로 항상 최신 정보를 확인해야 합니다.

확인 기준

사용 가능한 모델
plan별 포함 여부
reasoning effort 지원 여부
Fast mode 지원 여부
Codex credit rate
Cloud 사용 가능 여부
팀 workspace 정책

Codex overview 문서는 Codex가 여러 플랜에 포함된다고 설명하지만, 실제 사용 가능 모델·요금·한도는 계정과 시점에 따라 달라질 수 있으므로 공식 플랜/가격 정보와 workspace 설정에서 확인해야 합니다.

21MCP 관련 자료

MCP를 설정할 때 확인할 문서들입니다.

MCP 기본 개념
Codex MCP 설정
MCP server allowlist
MCP tool approval
MCP 보안 주의사항
외부 서비스별 MCP 문서

Codex CLI features 문서는 MCP 서버를 ~/.codex/config.toml 또는 codex mcp 명령으로 관리할 수 있고, 세션 시작 시 MCP 도구가 Codex에 노출된다고 설명합니다.

22AGENTS.md 관련 자료

AGENTS.md는 프로젝트별 작업 규칙을 Codex에게 알려주는 핵심 문서입니다.

포함할 것

프로젝트 개요
코딩 스타일
테스트 명령
빌드 명령
금지 작업
보안 규칙
PR 리뷰 기준
문서 작성 기준

반복해서 말하는 지침은 prompt에 매번 쓰지 말고 AGENTS.md에 넣는 것이 좋습니다. 이렇게 하면 CLI, IDE, Cloud 등 여러 surface에서 일관된 작업 기준을 제공할 수 있습니다.

23보안 및 엔터프라이즈 자료

보안에서 반드시 볼 문서들입니다.

Agent approvals & security
Sandboxing
Permissions
Managed configuration
Hooks
Configuration Reference

Agent approvals & security 문서는 Codex가 OS-level mechanism으로 sandbox policy를 적용하고, 기본적으로 active workspace에 쓰기 권한을 제한하며 network access도 통제할 수 있다고 설명합니다.

Hooks는 Codex lifecycle에 deterministic script를 삽입하는 확장 프레임워크이므로, 팀 보안 정책이나 반복 검사를 붙일 때 유용하지만 hook 자체의 신뢰성도 함께 관리해야 합니다.

24학습 순서

처음부터 모든 문서를 읽을 필요는 없습니다. 이 순서가 가장 효율적입니다.

Codex overview
CLI overview
Slash commands
Config basics
Configuration reference
Agent approvals & security
AGENTS.md / Skills / MCP
Cloud
Desktop App
IDE Extension
GitHub Action / CI
Changelog

개인 사용자는 CLI, slash commands, config, security까지만 먼저 익히면 충분합니다. 팀 리드나 플랫폼 담당자는 여기에 managed configuration, permissions, hooks, telemetry, CI/CD 자동화까지 확장하면 됩니다.

빠른 치트시트

25기본 명령과 session 관리

기본 명령

codex
codex "이 프로젝트 구조를 요약해줘"
codex exec "현재 git diff를 리뷰해줘"
codex doctor --summary

session 관리 (slash command)

/new

새 대화 시작

/resume

이전 session 이어가기

/fork

현재 대화를 분기

/compact

긴 대화 압축

/status

현재 상태 확인

26리뷰, 계획, 설정

리뷰와 계획

/plan

계획 모드

/review

리뷰 요청

/diff

변경사항 확인

설정과 권한 확인

/config

설정 확인

/permissions

권한 확인·변경

/model

모델 변경

27권한 조합과 Cloud

권한 조합 (config.toml)

일반 개발:

sandbox_mode = "workspace-write"
approval_policy = "on-request"

안전 리뷰:

sandbox_mode = "read-only"
approval_policy = "on-request"

CI 분석:

sandbox_mode = "read-only"
approval_policy = "never"

Cloud 명령

codex cloud
codex cloud list
codex cloud exec --env ENV_ID "작업 내용"
codex apply TASK_ID

28문제 해결 명령

문제가 생겼을 때 바로 실행할 명령들입니다.

pwd
git status
codex doctor --summary
codex doctor --json > codex-doctor.json

이 네 명령으로 대부분의 문제 원인을 파악할 수 있습니다.

pwd — 현재 위치 확인
git status — Git 상태 확인
codex doctor --summary — 설치·config·auth 진단
codex doctor --json — 상세 진단 저장

전 과정 완주

Codex 가이드를 끝까지 완주했습니다

이 가이드는 처음부터 끝까지 Codex를 배우는 방법을 보여주었습니다. 설치부터 인증, CLI, 설정, 모델, sandbox, approval, AGENTS.md, MCP, Skills, Cloud, Desktop, IDE, 자동화, 보안, 실전 워크플로까지 모든 영역을 다루었습니다.

이제 더 이상 가이드의 시작점으로 돌아갈 필요는 없습니다. 필요할 때마다 이 30번 단원에서 빠른 참조를 찾고, 더 자세한 내용이 필요하면 공식 문서를 참고하면 됩니다.

Codex를 잘 쓰는 법은 기능을 많이 아는 것이 아니라, 작업 범위·권한·검증 루프를 명확히 잡는 것입니다.

수고하셨습니다

필요할 때 이 가이드를 빠른 참조로 다시 펼쳐 보세요. 설치부터 자동화·보안·팀 운영까지 — 이제 Codex를 안전하게 실전에 쓸 수 있습니다.

실무에서 쓰는 AI 도구,한 장씩 넘기며 익히세요

Codex 실전 가이드

0. 이 가이드를 읽기 전에

01이 가이드의 목적

02이 가이드가 다루는 범위

03이 가이드를 읽는 방법

04초보자 추천 학습 순서

05초보자가 반드시 알아야 할 기본 개념

06초보자가 가장 먼저 익혀야 할 5가지

1. 프로젝트에서 Codex 실행하기

2. 프로젝트 구조 물어보기

3. 복잡한 작업은 먼저 계획시키기

4. 변경사항 확인하기

5. 안전한 기본 권한으로 사용하기

07원칙 1. 안전한 기본값으로 시작한다

08원칙 2. 큰 작업은 바로 실행하지 않는다

09원칙 3. 변경사항은 반드시 검토한다

10원칙 4. 테스트를 실행한다

11원칙 5. 반복 지시는 AGENTS.md에 적는다

12가이드에서 사용하는 예시 기준

터미널 명령:

설정 (TOML 형식):

Codex 안 명령:

13권장 기본 설정

14실습을 위한 준비물

15처음 실습할 때 추천 흐름

16절대 처음부터 하지 말아야 할 것

이 단원에서 기억할 것

1. Codex 핵심 요약

01Codex는 무엇인가?

02초보자를 위한 Codex의 정의

03Codex가 단순 챗봇이 아닌 이유

04핵심 시스템 1: config.toml

05핵심 시스템 2: Sandbox / Approval

06초보자 추천 조합

07핵심 시스템 3: AGENTS.md

08좋은 AGENTS.md의 효과

09핵심 시스템 4: MCP

10MCP의 역할

11핵심 시스템 5: Skills

12Skills의 효과

13Codex의 주요 사용 화면

14초보자 추천 시작점

15Codex의 핵심 작업 흐름

16Codex 실행 예시

17변경사항 확인

18초보자가 반드시 기억할 명령어

19주요 명령어 (계속)

20원칙 1: 큰 작업은 계획부터

21원칙 2: 변경 후 반드시 diff 확인

22원칙 3: 프로젝트 규칙은 AGENTS.md에

23원칙 4: 상황에 맞는 profile 사용

24원칙 5: 컨텍스트 관리

25실수 1: 처음부터 danger-full-access 사용하기

26실수 2: diff를 확인하지 않고 바로 커밋하기

27실수 3: 너무 넓고 모호하게 요청하기

28실수 4: AGENTS.md 없이 팀 프로젝트에 적용하기

29실수 5: MCP를 너무 많이 연결하기

30Codex 학습 로드맵

이 장의 핵심 정리

2. Codex 작동 방식 이해하기

01Codex의 전체 구조

02Core Layer: Codex의 두뇌

Core Layer가 담당하는 작업

03Core Layer의 사고 흐름

04Core Layer에서 사용하는 도구

05Security Layer: 안전장치

06Sandbox 모드

07Approval Policy

08OS 수준의 샌드박스

09Extension Layer 개요

10MCP (Model Context Protocol)

11Skills와 Apps

12Web Search

13Surface Layer: Codex를 사용하는 화면

14CLI (Command Line Interface)

15Desktop App

16IDE Extension

17Codex Cloud와 Chrome Extension

18표면별 사용 추천

실무에서 쓰는 AI 도구,
한 장씩 넘기며 익히세요