본문으로 건너뛰기

Codex CLI 기술 레퍼런스

핵심 요약

Codex CLI는 단순히 코드를 생성하는 챗봇이 아니라, 코드베이스를 읽고, 패치를 만들고, 명령을 실행하고, 테스트 결과를 반영하는 개발 에이전트입니다.

개발자가 Codex를 효과적으로 사용하려면 다음 5가지를 먼저 이해해야 합니다.

핵심 시스템목적개발자가 얻는 효과
config.toml모델, 권한, MCP, 프로필 설정세션마다 반복 설정하지 않음
Sandbox / Approval파일·네트워크·명령 실행 범위 통제안전한 자동화 가능
AGENTS.md프로젝트별 작업 규칙 제공팀 표준을 에이전트에 내장
MCP외부 도구·문서·API 연결GitHub, Figma, Sentry, 사내 API 연동
Skills / Plugins반복 워크플로 패키징긴 프롬프트를 재사용 가능한 기능으로 전환

실무 사용 루프는 다음과 같습니다.

요구사항 입력
→ 관련 파일 지정
→ 계획 수립
→ 패치 생성
→ 테스트/빌드 실행
→ diff 검토
→ 커밋/PR

Codex를 어떻게 이해해야 하나?

Codex는 하나의 모델이 여러 실행 표면(surface)에서 동작하는 구조로 이해하면 쉽습니다.

실행 표면적합한 상황
CLI터미널 중심 개발, 빠른 수정, 자동화 스크립트
IDE ExtensionVS Code, Cursor 등에서 열린 파일·선택 영역 기반 작업
Desktop App여러 작업 스레드, Git worktree, 시각적 diff 리뷰
Codex Cloud / Web장시간 작업, 비동기 분석, PR 생성
Browser / App 통합웹 기반 디버깅, 문서·외부 서비스와의 연결

개발자는 보통 CLI만으로 시작해도 충분하지만, 팀 단위로 확장하려면 다음 순서로 적용하는 것이 좋습니다.

CLI 사용
→ AGENTS.md 작성
→ config.toml 표준화
→ MCP 연결
→ 반복 업무를 Skill로 분리
→ 공유가 필요하면 Plugin으로 패키징

설치 및 인증

macOS / Linux 설치

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

또는 npm으로 설치할 수 있습니다.

npm install -g @openai/codex

macOS에서는 Homebrew도 사용할 수 있습니다.

brew install --cask codex

Windows 설치

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

또는 npm을 사용할 수 있습니다.

npm install -g @openai/codex

Windows에서 샌드박스 안정성과 Linux 개발 환경 호환성이 중요하다면 WSL2 기반 실행을 우선 검토합니다.

로그인

codex

처음 실행하면 ChatGPT 계정 로그인 또는 API 키 인증을 선택할 수 있습니다.

일반적으로는 ChatGPT 계정 로그인을 권장합니다.

codex login
codex login status
codex logout

API 키 기반 사용이 필요한 경우:

export CODEX_API_KEY="sk-..."
codex login --with-api-key

첫 번째 세션

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

cd ~/projects/my-app
codex

처음에는 코드 변경보다 읽기와 요약 작업으로 시작하는 것이 좋습니다.

이 프로젝트의 구조를 요약해 줘.
주요 진입점, 빌드 명령, 테스트 명령을 찾아서 정리해 줘.
변경하지 말고 분석만 해 줘.

이후 작은 작업을 시킵니다.

src/api/users.ts의 getUser 함수에서 null 반환 가능성을 방어해 줘.
변경 후 관련 테스트만 실행해 줘.

작업이 끝나면 diff를 검토합니다.

/diff
/review
/status

기본 명령과 슬래시 명령

CLI 실행 명령

명령용도
codex대화형 TUI 실행
codex "prompt"초기 프롬프트와 함께 실행
codex exec "prompt"비대화형 실행
codex app데스크톱 앱 실행 또는 handoff
codex mcpMCP 서버 관리
codex completion <shell>셸 자동완성 생성

예시:

codex "이 저장소의 테스트 실행 방법을 찾아줘"
codex exec "README의 오타를 수정하고 diff를 요약해줘"
codex mcp --help

자주 쓰는 슬래시 명령

명령용도
/status현재 모델, 권한, 토큰, AGENTS 로딩 상태 확인
/model모델 변경
/permissions승인·샌드박스 모드 변경
/plan계획 모드 진입
/diff변경 사항 확인
/review변경 사항 리뷰
/compact대화 컨텍스트 압축
/initAGENTS.md 초안 생성
/mcpMCP 서버 상태 확인
/skills사용 가능한 Skill 확인
/pluginsPlugin 탐색·관리

설정 시스템: config.toml

Codex 설정은 개인, 프로젝트, 시스템 레벨로 나눌 수 있습니다.

기본 위치

범위경로용도
사용자 기본값~/.codex/config.toml개인 기본 모델, 권한, MCP
프로젝트 설정.codex/config.toml저장소별 규칙
프로필 설정~/.codex/<profile>.config.toml빠른 전환용 프리셋
시스템 설정/etc/codex/config.toml조직 공통 설정
강제 정책/etc/codex/requirements.toml사용자가 완화할 수 없는 제약

설정 우선순위

최신 공식 문서 기준으로 우선순위는 다음과 같습니다.

1. CLI 플래그와 --config 오버라이드
2. 프로젝트 .codex/config.toml
3. --profile 로 선택한 프로필 파일
4. 사용자 ~/.codex/config.toml
5. 시스템 /etc/codex/config.toml
6. 내장 기본값

기본 설정 예시

# ~/.codex/config.toml

model = "gpt-5.5"
model_reasoning_effort = "medium"

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

[features]
hooks = true

[sandbox_workspace_write]
network_access = false

프로필 예시

반복 작업과 신중한 작업을 분리합니다.

# ~/.codex/fast.config.toml
model = "gpt-5.5"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
# ~/.codex/careful.config.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy = "untrusted"
sandbox_mode = "read-only"

실행:

codex --profile fast
codex --profile careful

Sandbox와 Approval

Codex 보안 모델은 두 계층으로 나뉩니다.

Sandbox = 기술적으로 무엇을 할 수 있는가
Approval = 언제 사람에게 물어볼 것인가

Sandbox 모드

모드설명권장 상황
read-only읽기 전용분석, 코드 리뷰, 보안 검토
workspace-write현재 작업공간 쓰기 가능일반 개발 작업
danger-full-access전체 시스템 접근격리된 컨테이너 내부, 매우 신뢰된 작업만

권장 기본값:

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

분석만 할 때:

codex --sandbox read-only

Approval 정책

정책설명권장 상황
untrusted대부분의 작업에 승인 요청처음 보는 저장소
on-request경계 밖 작업에만 승인 요청일반 개발
never승인 없이 진행CI/CD, 완전 자동화

비대화형 자동화에서는 다음 조합을 사용할 수 있지만, 신뢰된 환경에서만 사용합니다.

codex exec \
--sandbox workspace-write \
--ask-for-approval never \
"테스트 실패 원인을 수정하고 결과를 요약해 줘"

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

AGENTS.md는 Codex에게 전달되는 프로젝트 수준의 운영 규칙입니다. 매번 긴 프롬프트를 쓰는 대신, 팀 규칙을 문서화해 자동으로 로딩되게 하는 방식입니다.

언제 필요한가?

다음과 같은 지시를 반복하고 있다면 AGENTS.md로 옮깁니다.

- 테스트는 npm test로 실행해.
- API 변경 시 OpenAPI 문서도 업데이트해.
- SQL은 반드시 파라미터 바인딩을 사용해.
- Controller에는 비즈니스 로직을 넣지 마.
- 변경 후 /review로 diff를 검토해.

위치와 병합 방식

~/.codex/AGENTS.md                 # 개인 기본 지침
repo-root/AGENTS.md # 저장소 공통 지침
repo-root/services/api/AGENTS.md # 하위 디렉터리 지침

더 가까운 디렉터리의 지침이 더 구체적인 규칙으로 작동합니다.

예시

# AGENTS.md

## Repository overview

- Backend: .NET Core
- Frontend: Vue
- Database: SQL Server
- Do not use Entity Framework in this repository.

## Build and test

- Backend build: `dotnet build`
- Backend test: `dotnet test`
- Frontend install: `pnpm install`
- Frontend test: `pnpm test`

## Engineering rules

- Do not change public API contracts without updating docs.
- Prefer small, reviewable patches.
- Do not add new production dependencies without asking first.
- After code changes, run the smallest relevant test suite.

## Definition of done

- Code compiles.
- Relevant tests pass.
- Diff is reviewed.
- Risky changes are called out in the final summary.

초기 파일은 다음 명령으로 생성할 수 있습니다.

/init

Plan Mode와 작업 제어

Plan Mode

복잡한 작업은 바로 수정하지 말고 /plan으로 시작합니다.

/plan 인증 모듈의 refresh token 처리 방식을 개선해 줘.
현재 구조를 먼저 분석하고, 변경 계획과 위험 요소를 제안해 줘.

적합한 상황:

- 3개 이상의 파일을 수정해야 함
- 아키텍처 변경이 포함됨
- DB 마이그레이션이 있음
- 테스트 전략이 필요함
- 성능/보안 영향이 있음

작업 중 방향 전환

작업 중간에 개입할 수 있습니다.

잠깐, 이 방식 말고 기존 인터페이스는 유지하고 내부 구현만 바꿔.

또는 현재 작업이 끝난 뒤 이어서 처리하도록 요청할 수 있습니다.

이 작업이 끝나면 lint와 unit test도 실행해 줘.

MCP: 외부 도구 연결

MCP(Model Context Protocol)는 Codex가 외부 도구나 데이터 소스를 사용할 수 있게 해주는 연결 계층입니다.

예시:

- Context7: 최신 라이브러리 문서 조회
- GitHub: PR, issue, Actions 로그 확인
- Figma: 디자인 스펙 확인
- Sentry: 런타임 오류 확인
- 사내 API: 배포, 로그, 검색, 업무 시스템 연동

CLI로 MCP 서버 추가

codex mcp add context7 -- npx -y @upstash/context7-mcp

상태 확인:

/mcp

또는:

codex mcp --help

config.toml 직접 설정

[mcp_servers.context7]
enabled = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

환경변수가 필요한 경우:

[mcp_servers.github]
enabled = true
command = "npx"
args = ["-y", "github-mcp-server"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }

MCP 도입 기준

MCP는 “있으면 좋은 도구”가 아니라, 반복적인 수동 조회를 줄일 수 있을 때 도입합니다.

반복 작업MCP 후보
PR 상태 확인GitHub MCP
프론트엔드 구현 중 디자인 확인Figma MCP
장애 분석Sentry / 로그 MCP
최신 API 사용법 조회Context7
내부 업무 API 호출사내 MCP 서버

Skills

Skill은 Codex가 필요할 때만 로드하는 재사용 가능한 작업 패키지입니다.

긴 프롬프트를 매번 붙여 넣는 대신, 다음과 같은 반복 업무를 Skill로 만듭니다.

- PR 리뷰 체크리스트
- 릴리스 노트 생성
- 장애 로그 분석
- DB 마이그레이션 검토
- 보안 점검
- 프로젝트 표준 코드 생성

Skill 구조

my-skill/
SKILL.md # 필수: 지침과 메타데이터
scripts/ # 선택: 실행 스크립트
references/ # 선택: 참고 문서
assets/ # 선택: 템플릿, 이미지 등
agents/openai.yaml # 선택: UI, 의존성, MCP 등

SKILL.md 예시

---
name: dotnet-api-review
description: Use this skill when reviewing .NET Core API changes for contract safety, SQL safety, test coverage, and deployment risk.
---

# .NET API Review Skill

## Goal

Review API changes before merge.

## Steps

1. Identify changed controller, service, repository, and contract files.
2. Check whether public request/response contracts changed.
3. Check SQL access for parameter binding.
4. Check exception handling and logging.
5. Check relevant tests.
6. Produce a review summary with:
- blocking issues
- non-blocking issues
- test gaps
- deployment risk

## Do not

- Do not rewrite code unless explicitly asked.
- Do not approve changes without listing risks.

호출 방법

명시적으로 호출:

$dotnet-api-review 이 PR 변경 사항을 리뷰해 줘.

또는 설명이 명확하면 Codex가 자동으로 선택할 수 있습니다.

이 API 변경 사항을 계약 안정성, SQL 안전성, 테스트 관점에서 리뷰해 줘.

Skill 작성 원칙

원칙설명
하나의 Skill은 하나의 일만범위가 넓으면 정확도가 떨어짐
description이 중요자동 선택은 description에 크게 의존
입력과 출력 형식을 명확히결과 품질이 안정됨
스크립트는 필요할 때만지침만으로 충분하면 단순하게 유지
반복 수정 후 개선처음부터 모든 예외를 넣지 않음

Plugins

Plugin은 Skill, MCP 서버, app connector, hooks 등을 하나로 묶은 설치 가능한 배포 단위입니다.

Skill이 “워크플로 작성 형식”이라면, Plugin은 “배포와 공유 형식”입니다.

언제 Plugin이 필요한가?

상황SkillPlugin
개인 반복 업무적합과함
한 저장소 안에서만 사용적합보통 불필요
팀 전체 배포가능적합
MCP 설정 포함가능적합
hooks 포함제한적적합
marketplace 배포불가적합

Plugin 사용 흐름

codex plugin list
codex plugin install <name>
codex plugin remove <name>

TUI 안에서는:

/plugins

채팅 중에는 @plugin 멘션으로 컨텍스트에 포함할 수 있습니다.

@gmail 오늘 받은 중요 메일을 요약해 줘.
@github 이 PR의 실패한 체크 원인을 분석해 줘.

Skill을 Plugin으로 전환하는 기준

다음 조건 중 2개 이상이면 Plugin화를 검토합니다.

- 팀원 여러 명이 같은 Skill을 사용한다.
- MCP 서버 설정이 함께 필요하다.
- 사내 표준 hooks가 포함되어야 한다.
- 버전 관리와 배포가 필요하다.
- 설치/업데이트 경로를 통일해야 한다.

Hooks

Hooks는 Codex 세션 라이프사이클 중 특정 시점에 스크립트를 실행하는 확장 기능입니다.

활용 예시

- 세션 시작 시 현재 브랜치, 티켓 번호, 빌드 환경 주입
- 프롬프트 제출 전에 민감정보 탐지
- 도구 실행 후 lint 검사
- 작업 종료 시 로그 저장
- compact 전후 상태 백업

설정 예시

[features]
hooks = true
{
"hooks": [
{
"event": "SessionStart",
"command": "echo Current branch: $(git branch --show-current)"
},
{
"event": "PostToolUse",
"command": "echo Tool completed >> .codex/tool.log"
}
]
}

Hooks는 강력하지만, 팀 환경에서는 “무엇을 자동 실행할지”에 대한 보안 검토가 필요합니다.


비대화형 모드와 CI/CD

codex exec는 TUI 없이 Codex를 실행하는 헤드리스 모드입니다.

기본 사용

codex exec "실패한 테스트 원인을 분석하고 수정 후보를 제안해 줘"

자동화용 사용

codex exec \
--sandbox workspace-write \
--ask-for-approval never \
"lint 오류를 수정하고 변경 요약을 출력해 줘"

JSON 출력

자동화 파이프라인에서는 구조화된 출력을 요구하는 것이 좋습니다.

codex exec --json "변경된 파일과 테스트 결과를 JSON으로 요약해 줘"

CI에서 안전하게 쓰는 원칙

- main 브랜치에 직접 적용하지 않는다.
- 별도 브랜치 또는 worktree에서 실행한다.
- 네트워크 접근은 기본 차단한다.
- secret 출력 가능성이 있는 명령은 금지한다.
- 결과는 PR diff로 검토한다.
- 자동 merge는 별도 정책으로 제한한다.

성능과 비용 최적화

Codex 성능 저하는 대부분 다음 원인에서 발생합니다.

- 작업 범위가 너무 넓음
- 관련 파일을 지정하지 않음
- 대화 컨텍스트가 너무 커짐
- 테스트 명령을 모름
- AGENTS.md가 없거나 모호함
- MCP/외부 도구 설정이 불완전함

프롬프트 최적화

나쁜 예:

에러 고쳐줘.

좋은 예:

tests/auth/RefreshTokenTests.cs의 실패 원인을 분석해 줘.
관련 파일은 src/auth/AuthService.cs와 src/auth/TokenRepository.cs야.
public API는 바꾸지 말고, 테스트 통과 후 변경 요약을 알려줘.

컨텍스트 관리

/compact

다음과 같이 파일을 명시합니다.

@src/auth/AuthService.cs @tests/auth/RefreshTokenTests.cs
이 두 파일 기준으로 실패 원인을 분석해 줘.

모델·추론 강도 선택

작업권장 추론 강도
오타, 포맷팅low
단순 버그 수정medium
테스트 실패 분석medium~high
아키텍처 변경high
보안 검토high 이상

개발자 실무 레시피

새 프로젝트 분석

이 저장소를 변경하지 말고 분석만 해 줘.

출력:
1. 프로젝트 구조
2. 주요 실행 진입점
3. 빌드 명령
4. 테스트 명령
5. 배포 관련 파일
6. 위험해 보이는 설정

기능 개발

목표:
- 사용자 프로필 수정 API에 nickname 검증을 추가한다.

범위:
- src/users/**
- tests/users/**

제약:
- public API route는 변경하지 않는다.
- 새 패키지는 추가하지 않는다.
- 실패 테스트가 있으면 원인과 수정 내용을 요약한다.

완료 조건:
- 관련 테스트 통과
- 변경 파일 목록 출력
- 남은 위험 요소 출력

리팩토링

/plan

OrderService의 결제 검증 로직을 별도 클래스로 분리하고 싶다.

먼저:
- 현재 의존성 구조 분석
- 변경 후보 파일 목록 제안
- public API 영향 여부 판단
- 단계별 마이그레이션 계획 작성

승인 전까지 파일은 수정하지 마.

코드 리뷰

/review

이번 브랜치의 변경 사항을 main 기준으로 리뷰해 줘.

관점:
- 버그 가능성
- 예외 처리
- SQL injection 가능성
- 테스트 누락
- 배포 위험

Skill 생성

$skill-creator

다음 반복 작업을 Skill로 만들고 싶다.

작업명:
- SQL Server 저장 프로시저 리뷰

트리거:
- 프로시저 변경 리뷰
- T-SQL 성능 점검
- SQL injection 위험 분석

검토 기준:
- WHERE 조건 누락
- 동적 SQL 파라미터 처리
- 인덱스 사용 가능성
- 트랜잭션 범위
- TRY/CATCH와 로그 처리

출력:
- blocking issue
- performance risk
- maintainability issue
- suggested fix

팀 도입 전략

팀에 Codex를 도입할 때는 기능보다 운영 규칙을 먼저 정해야 합니다.

단계: 개인 사용

- CLI 설치
- 기본 로그인
- read-only 분석
- 작은 버그 수정

단계: 저장소 표준화

- repo-root/AGENTS.md 작성
- .codex/config.toml 추가
- 빌드/테스트 명령 명문화
- 금지 작업 명문화

단계: 반복 작업 패키징

- 자주 쓰는 리뷰 프롬프트를 Skill로 분리
- 배포 전 점검을 Skill로 분리
- 장애 분석 루틴을 Skill로 분리

단계: 외부 도구 연결

- GitHub MCP
- Sentry MCP
- 내부 문서 검색 MCP
- 사내 배포/로그 API MCP

단계: Plugin 배포

- 팀 공통 Skill 묶음
- MCP 설정 포함
- hooks 포함
- marketplace 또는 내부 저장소로 배포

안티패턴

안티패턴문제대안
“알아서 고쳐줘”범위가 넓어 토큰 낭비와 오작동 증가파일·목표·검증 명시
main 브랜치에서 직접 실행위험한 변경이 섞임feature branch/worktree 사용
danger-full-access 상시 사용시스템 전체 위험기본은 workspace-write
테스트 명령 미제공검증 불완전AGENTS.md에 명령 작성
긴 프롬프트 반복유지보수 어려움Skill 또는 AGENTS.md로 이동
모든 도구를 MCP로 연결보안/속도/컨텍스트 비용 증가실제 반복 작업부터 연결
Skill 하나에 모든 업무 포함자동 선택 실패하나의 Skill은 하나의 업무만
자동화를 너무 빨리 도입실패가 반복 자동화됨수동 루프가 안정된 뒤 자동화

권장 기본 세팅

개인 개발자 기준:

# ~/.codex/config.toml

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

[features]
hooks = true

[sandbox_workspace_write]
network_access = false

처음 보는 저장소:

codex --sandbox read-only --ask-for-approval untrusted

일반 개발:

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

CI 자동화:

codex exec \
--sandbox workspace-write \
--ask-for-approval never \
"지정된 검증 작업을 수행하고 JSON으로 결과를 출력해 줘"

격리 컨테이너 내부에서만 예외적으로:

codex --sandbox danger-full-access --ask-for-approval never

도입 체크리스트

개인 개발자

[ ] Codex CLI 설치
[ ] ChatGPT 또는 API 키 로그인
[ ] 기본 프로젝트에서 read-only 분석 실행
[ ] /status 확인
[ ] 작은 파일 수정 후 /diff 검토
[ ] ~/.codex/AGENTS.md 작성
[ ] ~/.codex/config.toml 작성

프로젝트

[ ] repo-root/AGENTS.md 작성
[ ] .codex/config.toml 작성
[ ] 빌드/테스트/lint 명령 문서화
[ ] public API 변경 규칙 문서화
[ ] DB/보안/배포 금지 규칙 문서화
[ ] PR 리뷰 기준 작성

[ ] 공통 Skill 후보 선정
[ ] MCP 도입 후보 선정
[ ] Plugin 패키징 기준 정의
[ ] hooks 보안 검토
[ ] CI 실행 정책 정의
[ ] 권한 정책과 secret 처리 기준 정의

빠른 참조

# 시작
codex

# 초기 프롬프트와 함께 시작
codex "이 프로젝트 구조를 요약해 줘"

# 비대화형 실행
codex exec "테스트 실패 원인을 분석해 줘"

# 권한 제한
codex --sandbox read-only
codex --sandbox workspace-write --ask-for-approval on-request

# 프로필 사용
codex --profile fast
codex --profile careful

# MCP
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp --help

# 자동완성
codex completion bash
codex completion zsh
codex completion fish

슬래시 명령:

/status       현재 상태 확인
/model 모델 변경
/permissions 권한 변경
/plan 계획 모드
/diff 변경 사항 확인
/review 코드 리뷰
/compact 컨텍스트 압축
/init AGENTS.md 생성
/mcp MCP 상태 확인
/skills Skill 확인
/plugins Plugin 관리

결론

Codex CLI를 잘 쓰는 핵심은 “더 강한 권한을 주는 것”이 아니라 좋은 작업 경계와 검증 루프를 만드는 것입니다.

개발자 개인은 다음 3가지만 먼저 적용해도 효과를 볼 수 있습니다.

1. 프로젝트 루트에서 codex 실행
2. AGENTS.md에 빌드/테스트/금지 규칙 작성
3. 작업마다 파일 범위와 완료 조건을 명확히 지정

팀 단위에서는 다음 순서가 가장 안정적입니다.

AGENTS.md
→ config.toml
→ Skills
→ MCP
→ Plugins
→ CI/CD 자동화

Codex는 개발자를 대체하는 도구라기보다, 잘 정의된 개발 루프를 빠르게 반복하는 에이전트 실행 환경에 가깝습니다. 따라서 좋은 결과는 모델 성능만이 아니라, 저장소 규칙, 테스트 체계, 권한 정책, 반복 워크플로 설계 품질에 의해 결정됩니다.


참고 자료