Codex — OpenAI 의 코딩 에이전트
를 설치해 프로젝트 폴더에서 첫 작업을 해 보고 네 단계 탭으로 실력을 올립니다. 먼저 필요한 것을 확인하고 에 맞는 설치 명령을 복사하세요.
기초 — 설치하고 첫 작업 해 보기
처음이라면 여기부터 시작하세요. Codex 가 무엇인지 알고, 설치하고, 첫 다섯 걸음을 따라 합니다. 다 해 봤다면 위의 [중급] 탭으로 넘어가세요.
무엇인가요
는 의 입니다. (Codex CLI), , 앱에서 작동합니다. 로 환경에 일을 맡기고 그 결과를 에 적용할 수도 있습니다.
프로젝트의 규칙은 에 적어 둡니다. AGENTS.md 는 여러 코딩 에이전트가 함께 읽는 열린 형식입니다. Codex 가 무엇을 해도 되는지는 / 로 정합니다.
필요한 것
- 계정: Codex 는 모든 ChatGPT 요금제(Free·Go·Plus·Pro·Business·Edu·Enterprise)에 들어 있지만 쓸 수 있는 곳이 다릅니다. Free·Go 는 데스크톱 앱에서만 쓸 수 있고(차례로 열리는 중), 이 화면의 는 Plus 이상이 필요합니다. 로도 CLI 에 로그인할 수 있습니다 — 요금으로 내고 클라우드 기능은 없습니다.
- 컴퓨터: ·() 또는 ( 설치 스크립트). 이나 로도 설치합니다.
- 일할 프로젝트 폴더 — 저장소면 Codex 가 바꾼 것을 / 로 읽고 로 되돌릴 수 있습니다.
설치
macOS·Linux 는 첫 줄, Windows 는 PowerShell 줄을 실행하세요. 설치 스크립트로 설치했다면 같은 을 다시 실행해 업데이트합니다.
- macOS · Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh- Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"- npm
npm install -g @openai/codex- Homebrew
brew install --cask codex
설치 확인
새 터미널 창을 여세요. codex --version 이 번호를 보여 주면 됩니다. "" 가 나오면 터미널을 다시 열고 를 확인하세요.
codex --version
첫 실행 — 다섯 걸음
- 터미널을 열고 <폴더> 로 프로젝트 폴더에 들어간 뒤, codex 를 입력하고 Enter 를 누른 다음 "Sign in with ChatGPT" 로 로그인합니다.
- "이 프로젝트에 대해 알려 줘" 하고 물어 프로젝트를 읽게 합니다.
- 으로 AGENTS.md 를 만들고, 명령과 지킬 규칙을 적습니다.
- /permissions 로 Codex 가 묻지 않고 해도 되는 일을 정합니다.
- 파일·동작·확인 방법을 밝혀 일을 맡기고, diff 를 읽고 테스트를 직접 돌려 본 뒤 합니다.
cd my-project
codex
자주 쓰는 기능
- AGENTS.md — 세션마다 읽는 프로젝트 지시(/init 으로 시작)
- /permissions — 파일 수정·명령 실행을 어디까지 허락할지
- "…" — 대화 화면 없이 실행(·)
- codex cloud — 클라우드 환경에 일을 맡기고 결과를 내 컴퓨터에 적용
- 코드 편집기 확장과 ChatGPT 데스크톱 앱 — 다른 곳에서 쓰는 같은 Codex 입니다. 앱에서는 Codex 를 고르고 New chat 으로 시작합니다. VS Code 에서는 Codex 아이콘을 고르거나, 명령 팔레트에서 Codex: Open Codex Sidebar 를 실행합니다.
- — .agents/skills/ 의 폴더로 반복하는 일 가르치기
안전하게 쓰기
- 부탁보다 많이 바꾸면 멈추게 합니다. 파일 하나는 git restore <파일> 로 되돌리고, 일부만 고르려면 git restore -p <파일> 을 씁니다. 그 파일에서 스테이징하지 않은 변경은 내가 고친 것까지 모두 사라지고, 스테이징한 변경과 새로 만든 파일(untracked)은 남습니다(GIT 4단계). 그다음 정확한 파일 이름을 밝혀 다시 부탁합니다.
- 테스트를 통과해도 diff 를 읽고, 내가 이해한 것만 커밋합니다.
- 큰 일은 먼저 계획을 달라고 하고, 작은 단위로 나눠 맡깁니다. 바꿔도 되는 것, 그대로 둘 것, 일이 끝났음을 보여 줄 증거(예: 통과한 테스트)를 말해 줍니다.
기초 연습 — 처음 한 번 해 보기
막히면: codex 가 시작되지 않으면 codex --version 으로 설치를 확인하고, 로그인에 실패하면 codex login 을 실행하세요. 다섯 가지를 모두 해 봤다면 [중급] 탭으로 넘어가세요.
SONUB 에서 더 배우기
공식 문서
2026-11-02 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.
중급 — 매일 쓰는 습관: AGENTS.md·승인과 샌드박스·명령
모델과 생각 수준(reasoning effort) — 무엇을 쓸까 (추천: GPT-6.1 Sol, High)
)2026년 11월 기준 개발에는 GPT-6.1 Sol 을 High 수준으로 쓰세요. 아래처럼 설정하거나 / 로 고릅니다. 모든 모델과 생각 수준, 언제 낮추고 올릴지는 툴 마스터의 툴 추천 사용법에 있습니다.
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
codex -m gpt-6.1-sol
codex -m gpt-6.1-sol -c model_reasoning_effort=high
codex exec -m gpt-6.1-sol "Review the current changes"
# inside Codex
/model # model → effort (Max · Ultra: More reasoning…)
AGENTS.md 제대로 쓰기
)는 일을 시작할 때 를 읽습니다. 먼저 내 파일(~/.codex/AGENTS.md)을 읽고, 프로젝트 맨 위(보통 맨 위)부터 까지 내려오며 폴더마다 하나씩 찾아 차례로 이어 붙입니다. 지금 폴더에 가까운 파일이 뒤에 오므로 더 힘이 셉니다.
- ~/.codex/AGENTS.md — 내 모든 프로젝트에 쓰는 개인 지시
- 프로젝트 맨 위의 AGENTS.md — 팀이 함께 쓰는 지시()
- 의 AGENTS.md — 그 폴더에서 일할 때만 더해지는 지시
- — 같은 폴더에 있으면 AGENTS.md 대신 이 파일을 읽습니다(잠깐 바꿔 볼 때).
- 합친 크기는 기본 (project_doc_max_bytes)까지만 읽습니다. 다른 이름의 파일을 쓰려면 project_doc_fallback_filenames 에 적습니다.
# AGENTS.md
## Setup
- Install: pnpm install
- Test: pnpm test
- Lint: pnpm lint
## Code style
- TypeScript strict mode, single quotes.
- Keep functions small. Add a test for every bug fix.
## Don't
- Don't edit generated files in dist/.
- Don't commit .env files.
~/.codex/AGENTS.md ← you, every project (read first)
my-project/AGENTS.md ← team rules (commit it)
my-project/web/AGENTS.md ← only for web/ (read last, so it wins)
은 프로젝트를 읽고 첫 AGENTS.md 를 만들어 줍니다. AGENTS.md 는 실행할 때 한 번 읽으므로, 고친 뒤에는 Codex 를 다시 시작하세요.
승인과 샌드박스 — 어디까지 맡길지
)Codex 는 두 가지로 안전을 지킵니다. 는 기술적으로 할 수 있는 범위(파일 쓰기·)를, 은 언제 나에게 물을지를 정합니다. 둘을 함께 정해야 합니다.
- — 읽기만 하고 아무것도 바꾸지 않습니다. 처음 보는 프로젝트를 살펴볼 때 씁니다.
- — 작업 폴더 안에서만 고치고 을 실행합니다. Git 저장소에서 Codex 는 이것과 on-request 를 묶은 "Auto" 를 권하지만, 폴더를 믿는다고 표시하기 전에는 read-only 로 시작할 수 있습니다. 네트워크는 기본으로 꺼져 있고 .git·.agents·.codex·.aws 는 읽기 전용입니다.
- — 샌드박스 없이 무엇이든 합니다. 된 에서만 씁니다.
- 승인 정책(-a): on-request 는 샌드박스 밖이 필요할 때 묻고, never 는 묻지 않습니다(샌드박스 안에서만 일함). --approve-for-me 는 대상이 되는 승인 요청을 자동 검토로 보내며, 파일·네트워크 을 넓히지 않습니다.
- /permissions 로 대화 중에 모드를 바꾸고, /status 로 지금 설정을 봅니다.
codex --sandbox read-only # look only, change nothing
codex --sandbox workspace-write # edit inside this folder ("Auto" in a Git repo)
codex -a never --sandbox workspace-write # never ask, but stay inside the sandbox
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false
예전 글의 --full-auto 는 이제 없습니다. 같은 뜻으로 --sandbox workspace-write 를 쓰세요. = "untrusted" 도 폐지되어 Codex 가 시작되지 않을 수 있으니 지웁니다. 읽기만 할 때는 sandbox_mode = "read-only" 와 approval_policy = "on-request" 를 씁니다. --yolo(--dangerously-bypass-approvals-and-sandbox)는 샌드박스와 승인을 모두 끄므로 격리된 곳에서만 씁니다.
슬래시 명령과 프롬프트 단축 입력
)Codex 대화 화면에서 / 를 입력하면 명령 목록이 뜹니다. 매일 쓰는 것부터 익히세요.
- /model — 모델과 생각하는 정도()를 고릅니다.
- /diff — 작업 폴더의 Git 변경(새로 만든 파일 포함)을 봅니다. /review — 바뀐 를 검토하게 합니다.
- /compact — 대화를 요약해 자리를 비웁니다. /new — 새 대화를 시작합니다.
- — 지난 대화를 골라 이어 갑니다. 터미널에서는 codex resume, codex resume --last.
- /status — 모델·권한·작업 폴더 같은 지금 설정을 봅니다. /mcp — 연결된 를 봅니다.
- @ — 파일을 찾아 부탁에 붙입니다. $ — 을 부릅니다. ! — 명령을 바로 실행합니다(!git status).
- 터미널에서 Codex 를 시작할 때: -i 그림.png 는 을 붙여 시작하고(대화 중에는 붙여 넣기), --search 는 실시간 웹 검색을 켭니다.
- /init — AGENTS.md 를 만듭니다. /plan — 먼저 계획을 세우게 합니다.
- <> — 그 기준을 채울 때까지 계속 일합니다. /goal 만 치면 상태를 보고, /goal pause·resume·clear 로 멈추고 이어 가고 지웁니다(Codex 0.128.0 부터).
클로드 코드를 쓰다 왔다면 /import 로 클로드 코드의 설정과 최근 대화를 가져올 수 있습니다.
컨텍스트 아끼기 — Codex 를 475k 에서 자동 요약하게 설정(SONUB 기준)
)잘 맡기는 법 — 어디·무엇·어떻게 확인
)- 막연한 부탁: "장바구니 고쳐 줘"
- 또렷한 부탁: "@src/cart.ts 에서 수량이 0 이면 합계가 이 돼. 0 이면 그 상품을 빼게 고치고, tests/cart.test.ts 에 를 더해 test 가 통과하는 것까지 확인해 줘."
- 큰 일은 "먼저 계획만 보여 줘"로 시작해, 계획을 고친 뒤 진행하게 합니다.
- 부탁보다 많이 바꾸면 멈추게 하고, 그 파일만 <파일> 로 되돌린 뒤(그 파일에서 내가 스테이징하지 않은 변경도 함께 사라집니다) 파일 이름을 밝혀 다시 부탁합니다.
- 오류는 전체 출력을 붙여 넣습니다 — 요약보다 원문이 정확합니다.
- 끝나면 /diff 로 바뀐 것을 읽고, 테스트를 직접 돌려 본 뒤 커밋합니다.
스스로 확인 — 짧은 질문 세 개
)아래 작은 프로젝트를 보세요. 질문마다 먼저 답을 생각한 뒤 정답을 여세요.
my-shop/
├── AGENTS.md
│ Test with npm test.
│ Never edit .env files.
└── services/api/
├── AGENTS.md
│ Test with go test ./...
└── orders.go
-
services/api 에서 일하는데 두 AGENTS.md 의 테스트 명령이 다릅니다. Codex 는 어느 명령을 쓰고, 규칙은 그대로 적용될까요?
정답 보기
go test ./... 를 씁니다. Codex 는 루트부터 파일을 이어 붙이므로 가까운 파일이 뒤에 오고, 규칙이 부딪히면 그 파일이 이깁니다. .env 규칙은 부딪히는 것이 없으니 그대로 적용됩니다.
-
Codex 에게 이 폴더의 를 고치게 하려 합니다. 폴더 밖으로 나가거나 네트워크를 쓸 때는 먼저 물어야 합니다. 어떤 설정으로 시작하고, AGENTS.md 에 한 줄 적는 것으로는 왜 모자랄까요?
정답 보기
--sandbox workspace-write 와 승인 정책 on-request(Auto 설정)를 씁니다. 샌드박스는 Codex 가 닿을 수 있는 곳을 실제로 막고, on-request 는 그 밖이 필요할 때 먼저 묻게 합니다. AGENTS.md 의 한 줄은 지시일 뿐이라 강제하는 장치가 없습니다.
-
orders.go 를 확인하고 git add 를 했습니다. 그 뒤 Codex 가 orders.go 를 또 고치고 new.go 를 만들었습니다. orders.go 의 새 변경만 버리려면 무엇을 실행하고, new.go 는 어떻게 될까요?
정답 보기
git restore orders.go 를 실행합니다. 스테이지하지 않은 변경만 버리므로 orders.go 는 스테이지한 판으로 돌아갑니다. git add 뒤에 내가 직접 고친 내용도 함께 사라집니다. new.go 는 추적되지 않는 파일이라 직접 지울 때까지 그대로 남습니다.
모범 사례 — OpenAI 가 권하는 Codex 사용법
)줄이면 — 네 가지(목표··제약·끝나는 기준)를 담아 부탁하고, 어려운 일은 먼저 계획하고, Codex 가 스스로 확인하게 하고, 규칙은 AGENTS.md 에 두고, 일 하나에 대화 하나를 씁니다. 좋은 습관 여섯과 두 툴의 명령은 툴 추천 사용법에 있습니다.
흔한 실수 — 그리고 피하는 법
)공식 안내는 실수 여덟을 꼽습니다 — 예를 들어 부탁에 잔뜩 넣은 규칙, 알려 주지 않은 ·테스트 명령, 건너뛴 계획, 너무 이른 전체 권한. 두 안내의 흔한 실수 열 가지와 고치는 법은 툴 추천 사용법에 있습니다.
중급 연습 — 내 프로젝트에서 해 보기
)- /init 으로 AGENTS.md 를 만들고 테스트 명령과 규칙 세 가지를 다듬습니다.
- 클로드 코드도 쓴다면 프로젝트에 CLAUDE.md 가 없는지 확인해, 두 AI 가 같은 AGENTS.md 를 읽게 합니다.
- codex --sandbox read-only 로 프로젝트를 살펴보게 하고, 그다음 workspace-write 로 작은 수정을 맡깁니다.
- /diff 와 /review 로 바뀐 것을 검토합니다.
- /status 로 지금 설정을 보고, codex resume --last 로 대화를 이어 봅니다.
다섯 가지를 모두 해 봤다면 [고급] 탭으로 넘어가세요.
공식 문서
- Codex — AGENTS.md
- Codex — Approvals & security
- Codex — Config reference
- AGENTS.md
- Codex — Models
- Codex — Best practices
- Codex — Common mistakes
2026-11-02 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.
고급 — 넓히기: config.toml·codex exec·MCP·스킬·훅
config.toml 과 프로필 — 내 방식에 맞추기
)의 설정은 ~/.codex/ 에 둡니다. 매번 붙이던 옵션을 여기에 적어 두면 기본값이 됩니다. 일마다 다른 설정은 파일로 나눕니다.
- · model_reasoning_effort — 쓸 모델과 생각하는 정도
- · sandbox_mode — 과 (중급에서 배운 값)
- 프로필은 ~/.codex/<이름>.config.toml 파일입니다. codex -p <이름> 으로 고르면 그 파일의 값이 기본 설정 위에 얹힙니다(예전의 [profiles.x] 표는 이제 읽지 않습니다). 프로필과 헷갈리지 마세요 — 권한 프로필은 파일· 권한을 정하는 Beta 기능이고 sandbox_mode 와 섞어 쓸 수 없습니다.
- -c 키=값 으로 이번 실행에서만 바꿉니다(예: -c sandbox_workspace_write.network_access=true).
- 같은 설정이 여러 곳에 있으면 더 센 곳이 이깁니다. 센 순서는 옵션과 --config, 프로젝트의 .codex/config.toml(가까운 폴더 먼저, 만), --profile 파일, ~/.codex/config.toml, 관리 기본값, /etc/codex/config.toml, 내장 기본값입니다.
- web_search 는 Codex 의 검색 방식을 고릅니다: cached · indexed · live(--search 와 같음) · disabled.
- shell_environment_policy 는 Codex 가 실행하는 에 어떤 를 넘길지 정합니다(inherit = "none" 이나 "core" 면 적게 넘깁니다). [features] 는 선택 기능을 켜고 끕니다. CODEX_HOME 은 설정 폴더를 ~/.codex 가 아닌 곳으로 옮기며, 그 폴더는 미리 있어야 합니다.
- 에서는 호환되는 기기라면 mxc 샌드박스를 권장하고, elevated·unelevated 는 예전 방식의 대안입니다. CLI 만 쓴다면 [features] 에 prefer_mxc = true 를 둡니다.
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
# a profile: codex -p review
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"
codex -p review
codex -c sandbox_workspace_write.network_access=true
프로젝트에 .codex/config.toml 을 두면 그 프로젝트에서만 쓰는 설정이 됩니다 — 믿는 프로젝트로 표시한 곳에서만 읽습니다.
codex exec — 대화 화면 없이 자동화
)"…" 는 대화 화면 없이 일을 한 번 하고 끝납니다. 진행은 로, 마지막 답은 stdout 으로 나오므로 ·· 에 넣기 좋습니다.
- 기본은 입니다. 파일을 고치게 하려면 --sandbox workspace-write 를 붙입니다.
- --json 은 진행을 (JSONL)로, -o <파일> 은 마지막 답을 파일로, --output-schema <파일> 은 에 맞는 답을 받습니다.
- 없이 실행하면 표준 입력이 프롬프트가 되고, 프롬프트와 함께 파이프로 넘기면 입력이 덧붙습니다.
- 밖에서는 --skip-git-repo-check 가 필요합니다. codex exec resume --last 로 앞 실행을 이어 갑니다.
- schema.json 은 마지막 답의 모양을 정합니다. --output-schema schema.json 을 붙이면 답이 summary·files 가 있는 으로 나옵니다. "additionalProperties": false 가 빠지면 "Invalid " 오류와 1 로 멈추니, 넣고 다시 실행합니다.
# Ask once, print the answer (read-only by default)
codex exec "Summarize what changed in the last 5 commits"
# Allow edits inside this folder
codex exec --sandbox workspace-write "Fix the failing test in tests/cart.test.ts"
# Pipe input in
cat error.log | codex exec "Find the cause"
# For scripts: JSON events, the final answer in a file, a JSON Schema answer
codex exec --json "List the TODOs in src/" > events.jsonl
codex exec -o notes.md "Write release notes for this week"
codex exec --output-schema schema.json "Rate the test coverage of each file"
# Continue the last run
codex exec resume --last "Now add tests for it"
{
"type": "object",
"properties": {
"summary": { "type": "string" },
"files": { "type": "array", "items": { "type": "string" } }
},
"required": ["summary", "files"],
"additionalProperties": false
}
CI 에서는 CODEX_API_KEY 를 Codex 를 실행하는 단계에만 넘기세요. 다른 단계의 스크립트가 키를 보지 못하게 합니다.
MCP — 바깥 도구와 잇기
)(Model Context Protocol)는 도구가 바깥 서비스( 관리···문서 도구)를 쓰게 하는 입니다. Codex 에 를 더하면 그 의 도구를 쓸 수 있고, 와 같은 서버를 그대로 쓸 수 있습니다.
- codex mcp add <이름> -- <명령> — 에서 실행하는 서버(stdio)를 더합니다.
- codex mcp add <이름> --url <주소> — 원격 서버()를 더합니다.
- 더한 서버는 config.toml 의 [mcp_servers.<이름>] 표에 저장됩니다. 대화 중에는 /mcp 로 상태를 봅니다.
# A server that runs on your computer (stdio)
codex mcp add playwright -- npx @playwright/mcp@latest
# A remote server (streamable HTTP)
codex mcp add notion --url https://mcp.notion.com/mcp
codex mcp list
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
tool_timeout_sec = 60
에이전트 스킬 — 반복하는 일을 가르치기
)은 가 든 폴더로, 클로드 코드와 같은 열린 형식입니다. Codex 는 평소에는 스킬의 이름과 설명만 알고 있다가, 일이 설명에 맞으면 본문을 읽어 따릅니다. 예전의 사용자 프롬프트(~/.codex/prompts)는 스킬로 바꾸라고 안내합니다.
- .agents/skills/<이름>/SKILL.md 는 이 저장소, ~/.agents/skills/ 는 내 모든 프로젝트에서 씁니다.
- $<스킬 이름> 으로 직접 부르거나 /skills 로 목록에서 고릅니다. 설명이 맞으면 알아서도 씁니다.
- name 과 description 을 적고, 스크립트·참고 문서는 scripts/·references/ 에 둡니다.
- 처음부터 들어 있는 에게 부탁하면 새 스킬을 함께 만들어 줍니다.
---
name: release-notes
description: Write release notes from the git log. Use when the user asks for release notes or a changelog.
---
1. Find the last tag: `git describe --tags --abbrev=0`
2. Read the commits since then: `git log <tag>..HEAD --oneline`
3. Group them under Added / Fixed / Changed, in plain sentences.
훅 — 정해진 때 반드시 실행되는 명령
)은 Codex 가 정해진 순간에 실행하는 명령입니다. 의 부탁은 잊힐 수 있지만 훅은 그 순간이 오면 돕니다. 돌리기, 위험한 명령 막기, 끝나면 알림 받기에 씁니다. 다만 완전한 강제 장치가 아니라 쓸모 있는 안전장치로 여기세요 — 웹 검색 같은 도구는 훅을 거치지 않고, 다른 일부 도구 도 건너뛸 수 있습니다.
- ~/.codex/hooks.json(나) 또는 저장소의 .codex/hooks.json(프로젝트)에 두거나, config.toml 에 [hooks] 표로 씁니다. 한 곳에서는 한 가지 형식만 씁니다.
- ·(도구 앞뒤), (부탁을 보낼 때), Stop(답을 마칠 때), SessionStart(세션을 시작할 때) 같은 때에 겁니다.
- 는 도구를 고릅니다. 종료 코드 2의 효과는 시점마다 다릅니다. PreToolUse 에서는 도구가 실행되기 전에 멈추고, PostToolUse 에서는 도구가 이미 실행된 뒤라 stderr 의 이유가 Codex 에게 피드백으로 갈 뿐 변경은 그대로 남습니다.
- 알림만 필요하면 config.toml 의 notify 에 을 적습니다 — 차례가 끝날 때마다 JSON 을 받아 실행됩니다.
- Codex 는 파일을 apply_patch(Write·Edit 로 매칭)로 고치지만 명령으로 쓰기도 합니다. 그래서 포맷터 훅의 matcher 에는 도 넣어야 합니다. 훅의 입력은 stdin 으로 JSON 이 들어옵니다.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash|Write|Edit",
"hooks": [
{
"type": "command",
"command": "sh .codex/hooks/format.sh",
"statusMessage": "Formatting changed files"
}
]
}
]
}
}
#!/bin/sh
# Codex sends the hook input as JSON on stdin; this formatter does not need it.
cat > /dev/null
git status --porcelain --untracked-files=all | cut -c4- \
| grep -E '\.(js|ts|css|html|json|md)$' | grep -v '^\.codex/' \
| xargs -r npx --yes prettier --write >&2
새 훅은 /hooks 에서 믿는다고 표시해야 돕니다. 남이 준 훅은 명령을 읽고 이해한 뒤에만 믿으세요.
조각들이 함께 일하는 법
)Codex 에는 규칙과 반복하는 일을 담는 곳이 여러 개 있습니다. 하는 일이 서로 다르니, 각각 맞는 자리에 둡니다.
- AGENTS.md — 이 프로젝트에서 Codex 가 일하는 방식을 정하는 오래가는 지시입니다.
- Memories — 앞선 작업에서 얻은 쓸모 있는 을 Codex 가 이어 갑니다.
- Skills — 되풀이하는 과정을 묶어 둔 것으로, 그 일이 나올 때 Codex 가 따라 합니다.
- Plugins — 설치해서 쓰는 꾸러미입니다. 먼저 스킬을 만들고, 나누고 싶을 때 플러그인으로 묶습니다.
- Hooks 와 MCP — 훅은 정해진 순간에 내 명령을 실행하고, MCP 는 Codex 를 로컬 작업 공간 밖의 시스템에 잇습니다.
- — 리뷰 같은 일을 넘겨받는 도우미로, 본 대화가 한 가지에 집중하게 합니다.
- 함께 쓰는 예: AGENTS.md 는 끝내기 전에 test 를 돌리라고 정하고, 는 고치던 파일을 떠올려 주고, 스킬은 를 쓰고, MCP 는 이슈 관리 도구에서 이슈를 읽어 오고, reviewer 서브 에이전트는 변경 내용을 검토합니다.
꼭 지킬 규칙은 AGENTS.md 나 저장소의 문서에 둡니다. 메모리는 기억을 돕는 층일 뿐, 반드시 지켜야 할 규칙의 유일한 출처가 아닙니다.
고급 연습
)- ~/.codex/config.toml 에 기본 승인·샌드박스를 적고, 읽기 전용 리뷰 프로필(review.config.toml)을 만들어 codex -p review 로 써 봅니다.
- codex exec -o 로 이번 주 을 요약해 파일로 받는 스크립트를 만듭니다.
- MCP 서버 하나를 더하고 /mcp 로 확인합니다.
- 자주 하는 일 하나를 .agents/skills/ 에 스킬로 만들고 $이름 으로 불러 봅니다. /skills 에 보여야 합니다. 보이지 않으면 폴더와 SKILL.md 의 name 을 확인하고 Codex 를 다시 시작합니다.
- 훅 단락의 두 파일을 그대로 만들고( 에 가 필요합니다) /hooks 에서 신뢰로 표시한 뒤, Codex 에게 띄어쓰기가 엉망인 demo.js 를 만들어 달라고 합니다. 파일이 정리되어 나오면 성공입니다. 포맷터가 실패하면 훅이 실패로 표시되고 Codex 는 계속 일하므로, 훅이 돌았다고 짐작하지 말고 상태를 읽습니다.
다섯 가지를 모두 해 봤다면 [마스터] 탭으로 넘어가세요.
공식 문서
- Codex — Config reference
- Codex — Non-interactive mode
- Codex — MCP
- Codex — Skills
- Codex — Hooks
- Codex — Customization
- Codex — Plugins
2026-11-02 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.
마스터 — 서브 에이전트·클라우드·GitHub·여러 AI 함께
서브 에이전트 — 일을 나눠 맡기기
)에게 를 띄워 달라고 하면 조사·구현·검토를 나눠 동시에 진행합니다. 각자 자기 대화를 가지므로 메인 대화가 깨끗하게 유지됩니다.
- 처음부터 들어 있는 default·worker·explorer 가 있고, /subagents 로 서브 에이전트 사이를 오갑니다.
- 내 서브 에이전트는 .codex/agents/(프로젝트)나 ~/.codex/agents/(나)에 파일로 만듭니다 — name·description·developer_instructions.
- 서브 에이전트는 부모의 와 승인 설정을 그대로 물려받습니다. 파일의 "Never edit files" 는 지시일 뿐이므로, 실제로 막으려면 부모를 --sandbox read-only 로 시작합니다.
- "reviewer 로 지금 를 검토하고, 그동안 worker 는 를 써 줘" 처럼 역할을 나눠 부탁합니다.
name = "reviewer"
description = "Reviews diffs for bugs and missing tests."
developer_instructions = """
Run git diff. List bugs with file and line, then missing tests.
Never edit files.
"""
model_reasoning_effort = "high"
Codex cloud — 클라우드에 일을 맡기기
)는 의 환경에서 일을 돌립니다. 를 쓰지 않으므로 여러 일을 동시에 맡기고, 끝난 결과만 골라 내 파일에 적용합니다.
- 먼저 환경을 만듭니다: 웹이나 데스크톱 앱의 에서 Work in > Cloud > Select environment > Create environment 를 고릅니다. 를 고르고, Codex 가 준비·시험을 마치면 검토한 뒤 publish 합니다.
- codex cloud 로 일 목록을 보고 새 일을 시작합니다. codex cloud exec --env <환경 > "…" 로 바로 맡길 수도 있습니다.
- codex apply <일 ID> 는 클라우드에서 만든 변경을 내 저장소에 적용합니다().
- 같은 일을 여러 번 시도하게 해(--attempts) 가장 나은 결과를 고를 수 있습니다.
codex cloud # see and start cloud tasks
codex cloud exec --env <ENV_ID> "Add input checks to the signup form"
codex cloud list
codex apply <TASK_ID> # apply the result to your files
GitHub — PR 에서 @codex review
)GitHub 저장소를 Codex 에 연결하면 댓글에 @codex review 라고 쓰는 것만으로 리뷰를 받습니다. (openai/codex-action)으로 PR 마다 자동으로 돌릴 수도 있습니다.
- @codex review — 그 PR 을 검토해 중요한 문제()만 남깁니다. Codex 설정에서 모든 PR 의 자동 리뷰를 켤 수 있습니다.
- 그 밖의 @codex … 댓글은 그 내용으로 클라우드 일을 시작합니다.
- openai/codex-action@v1 은 와 sandbox 를 받아 Codex 를 돌리고 마지막 답을 final-message 로 내놓습니다 — 다음 단계에서 댓글로 올리면 됩니다.
- 키는 저장소 (OPENAI_API_KEY)으로 넘기고, 읽기만 하는 리뷰는 sandbox 를 로 둡니다.
name: Codex review
on:
pull_request:
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- uses: openai/codex-action@v1
id: codex
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt: "Review this pull request. List bugs and missing tests."
sandbox: read-only
# the answer is in steps.codex.outputs.final-message
에 ## Rules 단락을 두면 Codex 의 PR 리뷰가 그 규칙을 따릅니다.
여러 AI 함께 쓰기 — 서로 검토하기
)한 가 쓴 를 다른 AI 가 검토하면 혼자서는 놓치는 문제가 잘 보입니다. AGENTS.md 로 같은 지시를 나눠 두었다면 Codex 와 를 한 프로젝트에서 번갈아 쓰기 쉽습니다.
역할을 나누는 것도 방법입니다. 한 AI 는 계획과 구현, 다른 AI 는 검토와 테스트를 맡고, 사람은 마지막 diff 를 읽고 합칠지 정합니다.
- codex review --uncommitted — 하지 않은 변경을 Codex 가 검토합니다. --base <브랜치> 로 브랜치 전체도 됩니다.
- diff | claude -p "…" — Codex 가 만든 변경을 클로드 코드가 검토합니다.
- 다른 AI 의 세션 안에서 로 일 하나를 Codex 에게 넘길 수 있습니다(예: 테스트 쓰기, 그림 만들기).
- 두 AI 의 의견이 다르면 둘 다 근거(파일·줄·테스트 결과)를 대게 하고, 사람이 확인해 고릅니다.
# Claude Code wrote the change — Codex reviews it
codex review --uncommitted
# Codex wrote the change — Claude Code reviews it
git diff | claude -p "Review this diff. List bugs and missing tests."
# From inside another AI's session, hand one job to Codex
codex exec --sandbox workspace-write "Write unit tests for src/price.ts"
Codex SDK 와 App Server — Codex 위에 만들기
)터미널 으로 모자라면 내 에서 Codex 를 부릅니다. 는 코드에서 Codex 를 실행하고, App 는 내 제품에 Codex 를 깊이 넣을 때 씁니다.
- : install @openai/codex-sdk( 18 이상, 서버 쪽에서). : install openai-codex(Python 3.10 이상).
- thread 는 대화 하나입니다. 같은 thread 에서 thread.run() 을 다시 부르면 일을 이어 갑니다.
- App Server 는 같은 풍부한 를 움직이는 Codex 의 인터페이스입니다. 내 제품에 로그인·대화 기록·승인과 에이전트 이벤트를 실시간으로 받는 기능이 필요할 때 씁니다.
- 와 에는 보통 codex exec 나 SDK 로 충분합니다. app-server 명령은 실험 단계이고 운영 환경용으로 지원되지 않으니, 쓰기 전에 문서를 확인합니다.
import { Codex } from "@openai/codex-sdk";
const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run("Find the failing test and explain why it fails");
console.log(result.finalResponse);
팀 설정 운영 — 같은 설정으로 함께
)- 함께 씀(커밋): AGENTS.md·.codex/config.toml·.codex/hooks.json·.codex/agents/·.agents/skills/
- 나만 씀(커밋 안 함): ~/.codex/config.toml· 파일·~/.codex/AGENTS.md
- AGENTS.md 는 짧게 유지합니다. 같은 실수가 되풀이될 때만 규칙을 더하고, 틀린 규칙은 지웁니다.
- 꼭 지켜야 하는 것은 지시가 아니라 샌드박스와 승인으로 강제합니다. 은 쓸모 있는 안전장치를 더하지만 완전한 강제 장치는 아닙니다.
- CI 의 키는 Codex 를 실행하는 단계에만 넘기고, 리뷰는 read-only 로 돌립니다.
마스터 연습 — 자동화와 다른 AI 와 함께
)- 대화 없이 한 번 실행합니다: codex exec "Find the test command of this project" > report.md 로 결과를 파일로 받고, report.md 를 읽어 봅니다.
- 자주 쓰는 설정(·샌드박스)을 ~/.codex/config.toml 에 적고, codex 를 다시 열어 /status 로 적용됐는지 확인합니다.
- add ../my-project-b -b try-b 로 폴더를 하나 더 만들어 Codex 와 클로드 코드에 서로 다른 일을 맡깁니다. 둘 다 끝나면 서로의 diff 를 검토하게 합니다.
- GitHub 의 풀 리퀘스트에 @codex review 를 남겨 리뷰가 달리는지 봅니다(먼저 저장소에 Codex 를 연결합니다).
- AGENTS.md 에 팀 규칙을 하나 더하고, 같은 일을 Codex 와 클로드 코드에 맡겨 둘 다 그 규칙을 지키는지 비교합니다.
막히면: codex exec 는 기본이 읽기 전용이라 파일을 고쳐야 하면 --sandbox workspace-write 를 붙입니다. 설정이 적용되지 않으면 /status 와 codex --help 로 지금 값을 보세요. 다섯 가지를 모두 해 봤다면 아래 체크리스트로 스스로 점검하세요.
마스터 체크리스트
)- AGENTS.md 에 공통 규칙 — 클로드 코드 같은 다른 AI 도 같은 지시로 일한다
- 샌드박스와 승인을 일에 맞게 고르고, 기본값은 과 프로필에 적었다
- 반복하는 일은 , 바깥 도구는 로 잇고, 꼭 지킬 것은 샌드박스·승인에 두며 훅은 안전장치로 더한다
- codex exec 와 GitHub Action 으로 반복 작업을 했다
- 큰 일은 서브 에이전트와 codex cloud 에 나눠 맡기고 결과만 골라 적용한다
- 다른 AI 와 서로 검토하고, 마지막 diff 와 테스트는 사람이 직접 확인한다
도구는 자주 바뀝니다. 명령이 안 되면 codex --help 와 공식 문서를 먼저 보세요. 예전 글의 옵션(--full-auto·[profiles.x])은 이미 바뀌었을 수 있습니다.
공식 문서
2026-11-02 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.