Codex 가이드

OpenAI Codex는 코드 작업을 읽고, 수정하고, 실행할 수 있는 코딩 에이전트입니다. Codex CLI는 Rust 기반으로 구축되어 빠른 실행 속도와 낮은 리소스 사용이 특징입니다. 이 문서에서는 Codex의 핵심 개념, 작동 방식, 안전한 사용 흐름, 팀 적용 전략을 정리합니다.
(최신 확인: Codex CLI 0.145.0+, 2026년 7월 기준)

개요

Codex는 클라우드 또는 로컬 환경에서 코딩 작업을 수행하는 에이전트입니다. Codex CLI는 Rust로 작성되어 빠른 시작 시간과 효율적인 메모리 사용을 제공합니다(코드베이스의 96%가 Rust). 코드 수정, 리팩토링, 테스트 실행, 문서화 등 반복적이거나 복잡한 작업을 비동기적으로 처리하도록 설계되었습니다. GPT-5 계열(gpt-5.4, gpt-5.4-mini, gpt-5.3-codex) 모델을 활용하여 로컬 워크플로우를 수행합니다.

코드를 작성하고 검토하며 배포까지의 흐름을 가속화하는 데 초점을 둔 코딩 에이전트라는 점이 특징입니다.

로컬에서는 터미널이나 IDE에서 Codex를 사용해 리포지토리를 탐색하고 파일을 수정하며, 클라우드(Codex Web, chatgpt.com/codex)에서는 독립된 작업 환경에서 병렬로 작업을 수행할 수 있습니다.

Codex는 앱(macOS), IDE 확장(VS Code, Cursor, Windsurf), 터미널(CLI), 웹 등 여러 표면에서 동일한 계정으로 접근할 수 있으며, 작업은 독립된 환경에서 진행됩니다.

접근 가능 여부와 기능 범위는 플랜/워크스페이스 설정(ChatGPT Plus/Pro/Team/Enterprise)에 따라 달라질 수 있습니다.

Codex CLI는 macOS(Apple Silicon/x86), Linux(x86/ARM, musl 빌드), Windows에서 사용할 수 있습니다. IDE 확장이나 CLI로 동일한 작업 흐름을 이어갈 수 있습니다.

Codex 앱(macOS)은 워크트리, 기본 Git 작업, 자동화 기능을 제공해 병렬 작업과 반복 작업을 관리하기 쉽습니다.

Codex 앱과 CLI 모두 서브 에이전트(Sub-agents)를 지원해 여러 에이전트가 동시에 작업을 수행할 수 있도록 구성되어 있습니다.

앱에는 스킬(Skills)과 자동화 기능이 포함되어 코드 이해, 프로토타이핑, 문서화 같은 작업을 반복 가능한 워크플로우로 만들 수 있습니다.

Codex는 여러 작업을 병렬로 수행할 수 있도록 설계되어, 반복 작업을 백그라운드에서 처리하는 데 적합합니다.

메모리(Memories) 기능으로 세션 간 컨텍스트를 영구 저장하고, 훅(Hooks) 시스템으로 프롬프트/작업 단계마다 커스텀 로직을 주입할 수 있습니다.

작동 방식

Codex는 작업 단위로 격리된 실행 환경을 구성하고, 지정된 코드베이스를 로드한 뒤 작업을 수행합니다. 필요한 경우 명령 실행 권한을 요청하고, 실행 로그와 변경 사항을 제공하여 검증 가능하도록 설계되어 있습니다.

Codex Cloud에서는 작업마다 샌드박스 컨테이너가 생성되며, GitHub 레포 연결을 통해 PR 작업을 수행할 수 있습니다.

각 작업은 연결된 레포지토리와 환경을 기준으로 독립적으로 실행되며, 결과는 리뷰 후 병합하거나 로컬로 내려받아 이어서 작업할 수 있습니다.

Codex Cloud는 웹 앱에서 시작하며, 연결된 레포지토리를 기준으로 작업을 수행합니다.

1. 작업 범위 정의 (파일/폴더/목표)
2. Codex에 작업 위임 (질문 또는 수정 요청)
3. 격리된 환경에서 변경/테스트 수행
4. 결과 검토 및 수정 요청
5. PR 또는 패치로 반영

MCP 지원

Codex CLI는 Model Context Protocol(MCP) 서버를 연결하여 외부 도구와 통합할 수 있습니다. STDIO 또는 스트리밍 HTTP 방식의 MCP 서버를 ~/.codex/config.toml 파일에 설정하거나, codex mcp CLI 명령으로 관리할 수 있습니다.

# MCP 서버 설정 예시
[[mcp_servers]]
name = "my-db-tool"
type = "stdio"
command = "npx"
args = ["@my-org/db-mcp-server"]

[[mcp_servers]]
name = "remote-api"
type = "http"
url = "https://mcp.example.com/sse"

# MCP 서버 목록 확인
codex mcp list

# MCP 서버 추가
codex mcp add my-tool -- npx @my-org/mcp-server

# 원격 HTTP MCP 서버 추가
codex mcp add sentry https://mcp.sentry.dev/mcp

# MCP 서버 제거
codex mcp remove my-tool

엔터프라이즈 기능

기업 환경에서 Codex를 안전하게 운영하기 위한 기능들입니다.

# 커스텀 CA 인증서 (프라이빗 레지스트리, 프록시 환경)
codex --ca-cert /etc/ssl/certs/company-ca.pem

# 설정 파일로 영구 적용
[enterprise]
ca_cert = "/etc/ssl/certs/company-ca.pem"
proxy = "http://proxy.company.com:8080"

# 조직 단위 정책 강제 적용
[policy]
require_approval = true
allowed_sandbox_modes = ["read-only", "workspace-write"]
blocked_commands = ["rm -rf", "dd", "mkfs"]
max_execution_time = 600

웹 검색

Codex CLI는 퍼스트파티 웹 검색 도구를 지원합니다. 로컬 작업 시 별도 설정 없이도 최신 라이브러리 문서, API 레퍼런스, 에러 해결 방법 등을 웹에서 검색하여 참조할 수 있습니다.

최신 정보가 필요한 작업에서는 --search 옵션으로 웹 검색을 명시적으로 켜는 것이 안전합니다.

# 웹 검색 활성화
codex --search "React 19 최신 변경사항 정리해줘"

# 검색 없이 로컬 지식만 사용
codex "기존 코드 기반으로 리팩토링"

훅(Hooks) 시스템

Codex는 작업 흐름의 주요 시점에 커스텀 스크립트를 실행하는 훅 시스템을 제공합니다. 훅은 ~/.codex/config.toml의 hooks 섹션에 정의하며, 사용자 프롬프트, 작업 시작/종료, 서브 에이전트 시작 시점에 개입할 수 있습니다.

# 훅 설정 예시 (~/.codex/config.toml)
[hooks]
# 사용자 프롬프트 전 실행 (입력 검증, 컨텍스트 주입)
user_prompt = [
  { command = "python", args = [".scripts/inject_context.py"], timeout_ms = 5000 }
]

# 작업 완료 후 실행 (결과 검증, 알림 전송)
stop = [
  { command = "bash", args = [".scripts/notify.sh"], timeout_ms = 10000 }
]

# 서브 에이전트 시작 시 실행 (권한 위임, 격리 설정)
subagent_start = [
  { command = "python", args = [".scripts/setup_subagent.py"], timeout_ms = 5000 }
]

# 훅 공통 옵션
# command: 실행할 명령어
# args: 인자 배열
# timeout_ms: 최대 실행 시간 (기본 30000)
# env: 추가 환경 변수
# stdin: stdin으로 전달할 데이터
# decision: "block" 시 작업 중단, "continue" 시 계속

스킬(Skills) 시스템

스킬은 재사용 가능한 모듈형 워크플로우로, Codex가 반복적인 작업을 자동화할 수 있게 해줍니다. 크로스 플랫폼 표준으로 설계되어 여러 AI 코딩 도구 간에 공유 가능합니다.

스킬은 ~/.codex/skills/ 디렉토리에 YAML/Markdown 파일로 저장되며, 메타데이터, 프롬프트 템플릿, 실행 단계를 정의합니다.

# ~/.codex/skills/fix-typescript-errors.yaml
name: "fix-typescript-errors"
description: "TypeScript 타입 에러 자동 수정"
version: "1.0.0"
author: "team-platform"
tags: ["typescript", "lint", "auto-fix"]

parameters:
  - name: "target_path"
    type: "string"
    description: "수정할 파일 또는 디렉토리 경로"
    required: true
  - name: "strict"
    type: "boolean"
    default: false
    description: "strict 모드 적용 여부"

steps:
  - name: "run-tsc"
    command: "npx tsc --noEmit"
    args: ["{{target_path}}"]
    capture_output: true
  - name: "analyze-errors"
    prompt: "다음 TypeScript 에러를 분석하고 수정 계획을 세워줘: {{step.run-tsc.output}}"
  - name: "apply-fixes"
    prompt: "계획에 따라 타입 에러를 수정해줘. strict={{strict}} 모드 적용."
  - name: "verify"
    command: "npx tsc --noEmit"
    args: ["{{target_path}}"]
    capture_output: true
    success_condition: "output == ''"

# 스킬 목록 확인
codex skills list

# 스킬 실행
codex skill run fix-typescript-errors --target_path src/

# 스킬 설치 (로컬/원격)
codex skill install ./my-skills/
codex skill install https://github.com/org/skills-repo

# 스킬 생성 템플릿
codex skill new my-skill

서브 에이전트(Sub-agents)

Codex는 서브 에이전트를 통해 여러 에이전트가 동시에 독립된 작업을 수행할 수 있도록 지원합니다. 메인 에이전트가 작업을 분해하고 서브 에이전트에 위임하면, 각 서브 에이전트는 격리된 환경에서 병렬로 실행됩니다.

• 최대 6개 스레드까지 동시 실행 (기본 설정)
• 최대 깊이 1 (서브 에이전트가 다시 서브 에이전트 생성 불가)
• 각 서브 에이전트는 독립된 컨텍스트와 작업 공간을 가짐
• 결과는 메인 에이전트가 수집하여 통합

# 메인 에이전트가 서브 에이전트에게 작업 위임
codex "다음 3개 모듈을 병렬로 리팩토링해줘:
1. src/auth/ - 인증 로직 정리
2. src/payments/ - 결제 모듈 타입 안전성 강화
3. src/utils/ - 유틸리티 함수 문서화
각각 별도 서브 에이전트로 실행하고 결과를 통합해줘."

메모리(Memories)

Codex는 메모리(Memories) 기능을 통해 세션 간 컨텍스트를 영구 저장하고 재사용할 수 있습니다. 프로젝트별, 전역, 서드파티 MCP 메모리 서버 등 여러 계층으로 구성됩니다.

• 네이티브 세션 지속성: 대화 기록, 파일 변경, 결정 사항 자동 저장
• 프로젝트 메모리: .codex/memories/ 디렉토리에 프로젝트별 지식 저장
• 전역 메모리: ~/.codex/memories/에 사용자 공통 설정/패턴 저장
• MCP 메모리 서버: 외부 벡터 DB, 지식 그래프 연동으로 영구 지식 베이스 구축
• /import 명령으로 Cursor, Claude Code 설정/메모리/세션 마이그레이션 지원

# 메모리 목록 확인
codex memory list

# 메모리 추가 (자연어로 지식 저장)
codex memory add "이 프로젝트는 PostgreSQL + Prisma를 사용하며, 스키마 변경 시 마이그레이션 필수"

# 메모리 검색
codex memory search "Prisma 스키마"

# 다른 도구에서 설정/메모리 가져오기
codex import cursor
codex import claude-code
codex import mcp-memory-server

엔터프라이즈 기능

Codex CLI는 기업 환경에서의 활용을 위한 다양한 기능을 제공합니다.

• 커스텀 CA 인증서: 기업 프록시 환경에서 사용할 수 있도록 커스텀 CA 인증서를 지원합니다.
• Hooks 시스템: 작업 흐름의 각 단계에서 훅을 실행할 수 있으며, 사용자 프롬프트 훅(user prompt hook)으로 입력 단계에서도 커스텀 로직을 적용할 수 있습니다.
• CI 친화적 샌드박스: CI/CD 파이프라인에서 안전하게 Codex를 실행할 수 있는 샌드박스 모드를 제공합니다.
• 원격 테스트 워크플로우: 원격 환경에서 테스트를 실행하고 결과를 수집하는 워크플로우를 지원합니다.
• CLI 자동화: exec, review, resume 같은 명령으로 운영 자동화에 연결할 수 있습니다.

# 비대화형 실행
codex exec "src/utils.ts에 타입 누락된 부분만 보완해줘"

# 변경 검토
codex review

# 이전 세션 이어서 작업
codex resume

사용 흐름

Codex는 “잘 정의된 작업”에 가장 강합니다. 목표, 제약, 기대 결과를 명확히 제공하면 품질이 크게 향상됩니다.

Codex CLI는 터미널에서 설치해 사용할 수 있으며, 앱/IDE와 유사한 작업 흐름을 제공합니다.

Codex CLI는 macOS, Linux, Windows에서 사용할 수 있으며, 계정 로그인 또는 API 키 인증을 지원합니다.

앱 환경에서는 작업을 워크트리(작업 브랜치) 단위로 분리해 관리할 수 있어, 여러 변경을 동시에 검토하거나 병합하기에 유리합니다.

IDE 확장은 VS Code, Cursor, Windsurf에서 제공되며, 다른 환경에서는 터미널에서 CLI를 사용하는 방식이 일반적입니다.

목표: [기능/문제 요약]
범위: [수정할 파일/폴더]
제약: [성능/보안/스타일 규칙]
검증: [테스트/린트/재현 방법]
기대 결과: [동작 기준, 예시]

# 목표가 명확한 작업 요청
목표: 결제 API 타임아웃 개선
범위: src/payments/, src/config/
제약: 기존 인터페이스 변경 금지
검증: 단위 테스트 + 통합 테스트 통과
기대 결과: 타임아웃 3초 → 8초, 재시도 2회

npm install -g @openai/codex

# 기본 인터랙티브 세션
codex

# 워크스페이스 쓰기 + 승인 요청
codex -s workspace-write -a on-request

# 읽기 전용 검토
codex -s read-only -a never

# 빠른 자율 실행 프리셋
codex --full-auto

CLI 실행 시나리오

# 1) 작업 요청
codex "auth 모듈에 refresh token 로직 추가해줘"

# 2) 비대화형 작업 실행
codex exec "src/auth/와 tests/auth/ 범위만 수정하고 테스트도 실행해줘"

# 3) 샌드박스/승인 정책 지정
codex -s workspace-write -a on-request "동일 작업 계속"

# 4) 테스트 실행 요청
codex "npm test 실행하고 실패 원인 요약해줘"

# 변경 사항 검증 요청
테스트: npm test
리뷰: 변경된 파일 요약 + 리스크 3개 지적
추가 요청: 실패한 테스트 원인 분석

핵심은 샌드박스와 승인 정책을 작업 특성에 맞게 고르는 것입니다. 작은 읽기 작업은 read-only, 일반 편집은 workspace-write, 완전 자동화는 충분히 격리된 환경에서만 사용하세요.

접근 및 인증

Codex는 ChatGPT 계정으로 로그인해 사용할 수 있으며, 필요 시 API 키 기반으로도 사용할 수 있습니다.

CLI는 첫 실행 시 로그인 안내가 나오며, ChatGPT 계정 또는 API 키로 인증할 수 있습니다. 헤드리스 환경이나 SSH 세션에서는 디바이스 인증이나 API 키 파이프 입력을 쓰면 편합니다.

# 브라우저 로그인
codex login

# 디바이스 인증
codex login --device-auth

# 로그인 상태 확인
codex login status

CLI 인증 흐름

CLI는 계정 로그인 또는 API 키로 인증할 수 있습니다. API 키를 사용하는 경우 환경 변수로 설정합니다.

# API 키 환경 변수
export OPENAI_API_KEY="sk-proj-xxx"

# 또는 stdin으로 직접 로그인
printenv OPENAI_API_KEY | codex login --with-api-key

Codex 앱/웹/CLI/IDE 확장은 동일한 계정으로 연결할 수 있습니다.

보안 및 거버넌스

• 최소 권한: 필요한 경로/명령만 허용
• 비밀 관리: 토큰/키는 환경 변수 또는 비밀 저장소 사용
• 검증 우선: 변경 사항과 로그를 리뷰한 뒤 병합
• 승인 모드: Suggest → Auto-edit → Full-auto 단계적 확장
• 네트워크 제어: 외부 호출은 필요한 범위만 허용
• 로그/감사: 실행 로그와 변경 이력을 보존
• 범위 분리: 작업 단위로 디렉토리/브랜치 분리

Codex 앱은 샌드박싱과 권한 요청 흐름을 제공하며, 기본적으로 작업 범위를 제한하고 필요 시 권한을 요청합니다.

샌드박싱은 오픈소스 구성 요소를 기반으로 하며, 네트워크 접근이나 고위험 명령은 승인 요청을 거치도록 구성할 수 있습니다.

Codex CLI는 로컬에서 실행되며, 파일 읽기/쓰기와 명령 실행이 로컬에서 이뤄집니다. CLI에서는 프롬프트, 고수준 컨텍스트, 선택적 변경 요약만 전송되는 흐름이 기본입니다.

소스 코드는 사용자가 공유를 선택하지 않는 한 외부로 전송되지 않습니다.

Codex CLI는 기본적으로 변경 제안을 보여주고 승인 후 적용하는 방식을 제공합니다.

Full Auto 모드는 네트워크가 차단된 샌드박스 환경에서 실행되며, 디렉토리 범위가 현재 작업 폴더로 제한됩니다.

데이터 사용 정책은 플랜과 설정에 따라 달라질 수 있으므로, 최신 정책은 공식 문서를 확인하세요.

운영 플레이북

Codex는 로컬 실행과 승인 흐름이 강점입니다. 팀 도입 시에는 승인 모드, 샌드박스 범위, 모델 사용 전략을 고정 규칙으로 운영해야 예측 가능한 결과를 얻을 수 있습니다.

승인 모드 운영 기준

팀 정책 템플릿

# Codex 팀 운영 정책 (예시)
- 기본 모드: Suggest
- 자동 수정 허용 경로: src/, tests/, docs/
- 금지 경로: infra/, migrations/, secrets/
- 허용 명령: npm test, npm run lint, npm run build
- 금지 명령: rm -rf, chmod -R, sudo *
- 재시도 횟수 제한: 동일 작업 2회
- 세션 종료 기준: diff 검토 + 테스트 로그 첨부

비용 운영 체크리스트

• 작업 시작 시 요청 범위를 파일 단위로 축소
• 불필요한 컨텍스트를 제외해 토큰 낭비 방지
• 간단 작업은 경량 모델, 복잡 작업은 상위 모델
• 재시도 루프를 방지하기 위해 완료 조건 숫자화

활용 사례

Codex는 다양한 개발 시나리오에서 활용할 수 있습니다. 아래는 실무에서 자주 사용되는 대표적인 사례와 구체적인 작업 흐름입니다.

레거시 코드 리팩토링

대규모 코드베이스에서 점진적으로 코드를 개선할 때 Codex가 효과적입니다. 파일 단위로 범위를 지정하고, 기존 테스트가 통과하는지 확인하면서 리팩토링을 진행합니다.

# Codex에 리팩토링 위임
codex "src/legacy/payment.js 파일을 ES6+ 문법으로 변환해줘.
var → const/let, callback → async/await, CommonJS → ESM.
기존 테스트(tests/payment.test.js)가 통과해야 해."

# 결과 확인 후 추가 요청
codex "변경된 파일의 타입 안전성을 위해 JSDoc 타입 주석을 추가해줘"

테스트 자동 보강

기존 코드에 테스트가 부족한 경우, Codex를 활용해 단위 테스트를 자동으로 생성하고 실패 원인을 분석할 수 있습니다.

# 커버리지가 낮은 모듈에 테스트 추가
codex "src/utils/validator.ts의 모든 public 함수에 대해
Jest 단위 테스트를 작성해줘.
에지 케이스(null, undefined, 빈 문자열, 특수문자)를 포함하고,
커버리지 80% 이상을 목표로 해."

# 실패한 테스트 분석
codex "npm test 실행 후 실패한 테스트의 원인을 분석하고 수정해줘"

문서화 및 코드 설명

코드베이스의 구조를 분석하고 설명을 생성하거나, README와 API 문서를 자동으로 개선할 수 있습니다.

# 코드베이스 구조 설명 생성
codex "이 레포의 전체 아키텍처를 분석하고
README.md에 프로젝트 구조 섹션을 추가해줘.
각 디렉토리의 역할과 주요 모듈 간 의존성을 설명해줘."

# API 문서 자동 생성
codex "src/api/ 디렉토리의 모든 엔드포인트에 대해
OpenAPI 3.0 스펙 문서를 생성해줘"

PR 리뷰 보조

• GitHub PR 자동 리뷰 및 품질 검토 보조
• 변경 사항 요약과 리스크 분석
• 반복적인 운영 작업(테스트 실행, 변경 요약) 자동화

Codex와 다른 도구 비교

Codex는 다른 AI 코딩 도구와 비교하여 고유한 특징을 가지고 있습니다. 아래 표는 주요 차이점을 정리한 것입니다 (2026년 기준).

제한사항과 주의

Codex는 강력한 도구이지만, 올바르게 사용하려면 한계를 이해하고 적절한 대응 전략을 마련해야 합니다.

핵심 정리

• Codex는 Rust 기반 CLI로, 코드 수정, 테스트, 문서화를 비동기적으로 처리하는 코딩 에이전트입니다.
• 승인 정책(on-request, on-failure, never)과 샌드박스(read-only, workspace-write, danger-full-access)를 조합해 작업 안전도를 조절합니다.
• MCP 서버 연동, --search 웹 검색으로 외부 도구 및 최신 정보를 활용할 수 있습니다.
• AGENTS.md로 프로젝트별 규칙 설정, 훅(Hooks)으로 작업 흐름 개입, 스킬(Skills)로 재사용 워크플로우 정의 가능
• 서브 에이전트(병렬 작업), 메모리(세션 간 컨텍스트 영구 저장) 등 최신 기능 지원
• 커스텀 CA 인증서, 프록시, 정책 강제 적용 등 엔터프라이즈 운영 기능 제공
• CLI, IDE 확장, 앱, 웹 등 여러 환경에서 동일한 계정으로 접근 가능합니다.
• 작업 범위를 좁히고, 검증 기준을 명확히 하는 것이 품질 확보의 핵심입니다.

실무 팁

• 재현성 확보: 입력/출력 예시를 고정해 동일한 결과를 반복적으로 얻을 수 있도록 하세요.
• 점진적 확장: Codex 작업 범위를 작게 잡고 성공을 확인한 뒤 단계적으로 넓히세요.
• 에러 문서화: 자주 발생하는 에러 조건을 AGENTS.md에 기록해 대응 시간을 줄이세요.
• 병렬 활용: 독립적인 작업(테스트 보강, 문서화, 린트 수정)은 동시에 여러 에이전트에 위임하세요.
• 검증 자동화: npm test, npm run lint 등 검증 명령을 작업 지시에 항상 포함하세요.
• diff 리뷰 습관: 자동 수정이라도 diff를 반드시 확인하고 의도와 다른 변경이 없는지 점검하세요.

관련 도구

• CLI 도구 개요 - 주요 CLI 비교
• Cline 가이드 - VS Code 에이전트
• Continue 가이드 - IDE 보조형 도구
• Cursor 가이드 - 통합 IDE
• Aider 가이드 - Git 중심 CLI

다음 단계

• OpenAI API - 연동 기본
• CLI 모범 사례 - 안전한 작업 습관
• API 모범 사례 - 운영 품질 개선