공식 문서 대조 보완 항목
공식 문서를 항목별로 훑으며 가이드에서 빠지기 쉬운 운영 포인트를 보강했습니다. 모두 96건이고, 카드마다 어느 영역인지와 근거가 된 공식 문서를 함께 적었습니다.
각 문서 페이지에 이미 반영된 내용입니다. 여기서는 무엇을 왜 보강했는지만 모아 두었으니, 관심 있는 영역이 보이면 해당 문서로 넘어가 자세히 읽는 편이 빠릅니다.
앱 기본 흐름 대조 33건
앱 시작, 인증, 프로젝트, Review, Worktree, Local environment, Automations, Settings, Commands, Windows, 문제 해결을 공식 문서와 맞춰 본 결과입니다.
macOS와 Windows 앱 지원 범위 명확화
Codex app은 macOS와 Windows에서 사용할 수 있고, Linux는 별도 알림 등록 흐름으로 안내됩니다.
Codex appChatGPT 계정과 API 키 로그인 차이 보강
ChatGPT 계정 또는 OpenAI API 키로 로그인할 수 있지만 API 키 로그인은 cloud threads 같은 일부 기능이 제한될 수 있습니다.
Codex app사용 가능 플랜 표현 정리
Plus, Pro, Business, Edu, Enterprise 플랜 포함을 기본 기준으로 적고, Free/Go 제공은 한시 정책으로 분리했습니다.
Help CenterLocal, Worktree, Cloud 실행 모드 구분
스레드 시작 시 현재 디렉터리에서 작업하는 Local, Git worktree로 격리하는 Worktree, 원격 환경에서 실행하는 Cloud를 구분했습니다.
Features모노레포 프로젝트 분리 기준 추가
하나의 저장소에 여러 앱이나 패키지가 있으면 프로젝트를 나눠 sandbox 범위를 좁히도록 설명했습니다.
Features앱, CLI, IDE Extension 간 Skills 공통성 반영
Codex app이 CLI와 IDE Extension과 동일한 agent skills를 지원하고, 사이드바에서 탐색할 수 있음을 보강했습니다.
FeaturesReview pane이 Git 상태 전체를 보여준다는 점 강조
Codex가 만든 변경뿐 아니라 사용자가 만든 미커밋 변경도 표시된다는 FAQ성 내용을 명확히 했습니다.
ReviewReview scope 3종 보강
미커밋 변경, 전체 브랜치 변경, 마지막 assistant turn 변경을 비교해 볼 수 있다는 설명을 추가했습니다.
Review인라인 코멘트 피드백 흐름 보강
diff 라인에 코멘트를 남긴 뒤 스레드에 다시 명시 요청해야 Codex가 정확히 반영한다는 순서를 정리했습니다.
ReviewPR 피드백 처리와 GitHub CLI 조건 추가
PR 브랜치에서 리뷰어 피드백을 앱 안에서 처리하려면 GitHub 접근과 인증된 gh CLI가 필요하다는 점을 반영했습니다.
Review기본 detached HEAD 동작 보강
Worktree 스레드는 선택한 브랜치에서 시작하되 기본적으로 detached HEAD에서 작업할 수 있음을 설명했습니다.
WorktreesHandoff 개념 추가
Local과 Worktree 사이에서 스레드와 작업 코드를 옮기는 Handoff 흐름을 별도 개념으로 정리했습니다.
Worktrees.codex 폴더 공유 기준 보강
Local environments 설정은 프로젝트 루트의 .codex 폴더에 저장되며 Git에 포함해 팀과 공유할 수 있음을 적었습니다.
Local environmentsSetup script 실행 시점 명확화
새 worktree thread 시작 시 setup script가 자동 실행되어 의존성 설치와 초기 빌드를 처리한다는 설명을 추가했습니다.
Local environmentsActions의 상단 바 실행 흐름 보강
개발 서버 시작이나 테스트 실행 같은 공통 action이 앱 top bar에서 실행되고 integrated terminal에서 수행됨을 정리했습니다.
Local environmentsTriage inbox 동작 추가
자동화 결과는 Triage에 쌓이고, findings가 없으면 자동 보관될 수 있다는 운영 흐름을 반영했습니다.
AutomationsStandalone automation과 thread automation 구분
매번 새 실행을 시작하는 자동화와 같은 대화를 주기적으로 깨우는 thread automation의 차이를 설명했습니다.
AutomationsSandbox와 rules 위험도 보강
자동화는 기본 sandbox 설정을 따르며 full access는 위험하므로 rules allowlist를 함께 고려해야 함을 추가했습니다.
AutomationsIn-app browser 사용 범위 수정
Codex app은 로컬 서버, 파일 기반 미리보기, 공개 페이지를 열 수 있고 시각 코멘트를 남길 수 있습니다.
In-app browser인증/쿠키/확장 제한 명확화
로그인 상태, 기존 브라우저 프로필, 쿠키, 확장 프로그램, 기존 탭은 지원하지 않는다는 제한을 적었습니다.
In-app browser브라우저 코멘트 단축 조작 추가
comment mode에서 Shift 클릭으로 영역 선택, Cmd 클릭으로 즉시 코멘트 전송이 가능하다는 조작을 보강했습니다.
In-app browser지역 및 플랫폼 제한 추가
Computer Use는 macOS에서 제공되며 출시 시점 기준 EEA, 영국, 스위스에서는 제공되지 않는다는 제한을 반영했습니다.
Computer UseScreen Recording과 Accessibility 권한 구분
화면을 보기 위한 권한과 클릭/입력을 위한 권한이 별도이며, 앱별 승인도 따로 관리된다는 점을 설명했습니다.
Computer UseAppearance 세부 설정 보강
기본 테마뿐 아니라 accent, background, foreground, UI font, code font 조정이 가능하다는 내용을 추가했습니다.
SettingsMCP 설정 공유 위치 보강
앱의 MCP 설정은 CLI와 IDE Extension에도 적용되며 config.toml을 통해 공유된다는 점을 정리했습니다.
SettingsPersonalization, suggestions, Memories, archive 항목 추가
성격 설정, custom instructions, context-aware suggestions, Memories, archived threads를 설정 범위에 포함했습니다.
Settings공식 slash command 5종 정리
/feedback, /mcp, /plan-mode, /review, /status를 공식 문서 기준으로 다시 정리했습니다.
Commandscodex:// deeplink 파라미터 보강
codex://new는 prompt, originUrl, path를 받을 수 있고 path가 유효하면 우선 적용된다는 점을 추가했습니다.
CommandsWindows native sandbox와 WSL2 구분
PowerShell에서는 Windows sandbox를, WSL2에서는 Linux sandboxing을 사용한다는 실행 모델을 설명했습니다.
Windows통합 터미널 선택지 보강
PowerShell, Command Prompt, Git Bash, WSL 중 기본 terminal을 고를 수 있고 새 세션부터 적용된다는 점을 추가했습니다.
Windows누락 스레드와 archive 확인 절차 추가
스레드가 일부만 보이면 필터를 Chronological로 바꾸고 Settings의 archived threads를 확인하도록 정리했습니다.
Troubleshooting잘못된 target 선택 후 prompt 복구 추가
Local, Worktree, Cloud를 잘못 골랐을 때 실행을 취소하고 composer에서 위쪽 화살표로 이전 prompt를 복구할 수 있음을 반영했습니다.
Troubleshooting앱과 CLI 버전 차이 확인 명령 추가
CLI와 app bundle의 agent 버전이 다를 수 있으므로 codex --version과 앱 내부 codex 경로 확인법을 추가했습니다.
Troubleshooting기능 심화 대조 34건
In-app browser, Computer Use, Web search, 이미지 생성·입력, Chats, 알림, 전원 설정처럼 실제 작업 중에 자주 부딪히는 기능을 파고든 항목입니다.
로컬 태스크의 Web search 기본 동작 추가
Codex app의 local tasks에서는 web search가 기본 활성화되고 캐시된 검색 결과를 사용한다는 점을 보강했습니다.
FeaturesFull access에서 live web search 전환 기준 추가
sandbox를 full access로 설정하면 web search가 최신 live results를 기본으로 사용할 수 있음을 설명했습니다.
FeaturesWeb search 비활성화/라이브 전환 위치 보강
Config basics에서 web search를 끄거나 live results로 전환할 수 있다는 설정 경로를 추가했습니다.
Features스레드 내 이미지 생성 기능 추가
UI asset, banner, background, illustration, sprite sheet, placeholder를 Codex thread 안에서 생성하거나 편집할 수 있음을 반영했습니다.
Features$imagegen 명시 호출 보강
자연어 요청뿐 아니라 $imagegen skill을 prompt에 넣어 이미지 생성을 명시 호출할 수 있음을 추가했습니다.
Featuresgpt-image-2와 사용량 한도 설명 추가
내장 이미지 생성은 gpt-image-2를 사용하고 일반 Codex 사용량 한도에 포함된다는 점을 명시했습니다.
Features대량 이미지 생성 시 API 키 사용 기준 추가
큰 배치 이미지 생성은 OPENAI_API_KEY를 환경 변수로 설정해 API 과금 흐름으로 처리할 수 있음을 설명했습니다.
Features이미지 드래그 앤 드롭 맥락 추가
prompt composer에 이미지를 끌어 넣어 context로 포함하고, Shift를 누른 채 드롭하면 맥락 추가 동작이 된다는 점을 보강했습니다.
Features시스템 이미지 확인 요청 활용 추가
Codex가 사용 중인 앱의 스크린샷을 보고 작업 결과를 검증하도록 요청할 수 있다는 실무 흐름을 추가했습니다.
Features프로젝트 없는 Chats 사용 기준 추가
특정 프로젝트 폴더나 Git 저장소가 필요 없는 research, triage, planning, plugin-heavy workflow에는 Chats를 쓰도록 정리했습니다.
FeaturesCodex-managed threads 디렉터리 위치 추가
Chats는 기본적으로 Codex home 아래 ~/.codex/threads 작업 위치를 사용한다는 경로 정보를 추가했습니다.
Features백그라운드 완료/승인 알림 기준 추가
앱이 백그라운드에 있을 때 작업 완료 또는 approval 필요 상태에서 알림을 보낸다는 기본 동작을 보강했습니다.
Features알림 정책 3단계 보강
알림을 끄거나, 기본값을 쓰거나, 앱이 focus 상태여도 항상 보내도록 설정할 수 있음을 추가했습니다.
FeaturesPrevent sleep while running 설정 추가
장시간 태스크를 위해 Codex app이 컴퓨터 sleep을 방지하도록 설정할 수 있음을 설명했습니다.
FeaturesFriendly/Pragmatic/None personality 선택 추가
Settings에서 기본 personality를 Friendly, Pragmatic, None 중 선택하고 None으로 personality instructions를 끌 수 있음을 반영했습니다.
SettingsCustom instructions와 AGENTS.md 연결 추가
custom instructions를 편집하면 개인 지시가 AGENTS.md에 반영된다는 연결 관계를 보강했습니다.
SettingsContext-aware suggestions 복귀 흐름 추가
Codex를 시작하거나 다시 돌아왔을 때 이어서 할 작업을 제안하는 context-aware suggestions를 설명했습니다.
SettingsThread automation의 heartbeat 성격 추가
thread automation은 현재 스레드를 주기적으로 깨우는 heartbeat 방식이며 문맥 보존이 필요할 때 쓰는 기능으로 정리했습니다.
Automations분 단위 interval 사용 사례 추가
thread automation은 active follow-up loop에 분 단위 interval을 쓸 수 있고, daily/weekly check-in도 가능함을 보강했습니다.
Automations자동화 prompt 내구성 기준 추가
매 실행마다 무엇을 하고, 보고할 조건은 무엇이며, 언제 멈추거나 사용자 입력을 요구할지 prompt에 포함해야 함을 설명했습니다.
Automations수동 테스트 후 예약 원칙 추가
자동화를 예약하기 전에 일반 thread에서 prompt를 수동 테스트하고 diff가 reviewable한지 확인하도록 보강했습니다.
Automations잦은 worktree 생성 정리 원칙 추가
Git 저장소 자동화를 worktree로 자주 실행하면 worktree가 많이 쌓이므로 필요 없는 run을 archive하고 pinning을 제한해야 함을 추가했습니다.
AutomationsRead-only sandbox 실패 조건 추가
read-only sandbox에서는 파일 수정, 네트워크 접근, 데스크톱 앱 조작이 필요한 tool call이 실패할 수 있음을 설명했습니다.
AutomationsWorkspace-write sandbox 실패 조건 추가
workspace-write에서도 workspace 밖 파일 접근, 네트워크 접근, 데스크톱 앱 조작은 실패할 수 있고 rules allowlist가 필요할 수 있음을 보강했습니다.
Automations브라우저 작업 범위 제한 원칙 추가
route, local URL, 시각 상태(loading/empty/error/success)를 명시하고 한 번에 review 가능한 크기로 browser task를 제한하도록 정리했습니다.
In-app browserBrowser comments와 Review pane 역할 분리
렌더링 화면 문제는 browser comments로, repository 변경 검토는 review pane으로 처리하라는 역할 분리를 추가했습니다.
In-app browser@Computer Use와 @AppName 호출법 추가
prompt에서 @Computer Use 또는 @AppName을 언급해 대상 앱, 창, 흐름을 정확히 지정하는 사용법을 보강했습니다.
Computer Use구조화된 integration 우선 원칙 추가
전용 plugin이나 MCP server가 있으면 Computer Use보다 구조화된 integration을 우선 사용하라는 판단 기준을 추가했습니다.
Computer UseAlways allow 관리 기준 추가
앱 사용을 Always allow로 승인할 수 있지만, 신뢰 가능한 앱에만 쓰고 Settings에서 제거할 수 있음을 설명했습니다.
Computer Use민감한 웹 작업 안전 기준 추가
브라우저 사용 시 로그인된 페이지의 클릭과 제출은 사용자 계정 행동으로 처리될 수 있으므로 민감한 흐름에서는 사용자가 지켜봐야 함을 보강했습니다.
Computer Use자동화 불가 대상 명확화
Computer Use는 terminal app이나 Codex 자체를 자동화할 수 없고 관리자 인증 또는 보안/개인정보 권한 prompt도 승인할 수 없음을 추가했습니다.
Computer UsemacOS 보호 폴더 접근 prompt 설명 추가
Music, Downloads, Desktop 같은 macOS 보호 폴더 접근 시 추가 승인이 필요할 수 있음을 설명했습니다.
TroubleshootingFeedback session ID 흐름 추가
composer에서 /로 feedback을 보내면 세션 공유 여부를 선택하고 session ID를 받을 수 있다는 흐름을 보강했습니다.
Troubleshooting로그 공유 전 민감정보 검토 추가
앱 로그, session transcripts, archived sessions 위치를 안내하면서 공유 전 민감정보를 확인해야 함을 추가했습니다.
Troubleshooting설정과 확장 대조 29건
config.toml, Sandbox, Rules, AGENTS.md, MCP, 인증, 원격 연결, Hooks 등 환경을 직접 손볼 때 필요한 내용입니다.
config.toml 적용 범위 추가
Codex 설정은 주로 Codex home의 config.toml에서 관리되고, 앱·CLI·IDE가 같은 agent configuration 계층을 공유한다는 점을 보강했습니다.
Config basicsmodel과 reasoning effort 분리 설명 추가
모델 선택과 추론 강도는 별도 설정이며, 작업 난도에 따라 기본값·프로필·세션 옵션으로 나눠 관리할 수 있음을 정리했습니다.
Config reference프로필 기반 설정 전환 추가
업무 유형별 profile을 만들어 모델, sandbox, approval 정책을 빠르게 바꿀 수 있는 운영 방식을 추가했습니다.
Config basics프로젝트별 설정과 사용자 설정 충돌 점검 추가
개인 기본값과 프로젝트 설정이 동시에 존재할 때 어느 값이 적용되는지 확인하도록 체크리스트를 보강했습니다.
Config referencesandbox mode와 approval policy 분리 추가
sandbox mode는 접근 범위를 정하고 approval policy는 그 범위를 벗어날 때 언제 묻는지를 정한다는 차이를 설명했습니다.
Agent approvals & securityworkspace-write 기본 위험 경계 추가
workspace-write는 작업공간 내부 쓰기를 허용하지만 네트워크나 외부 경로 접근은 별도 승인·규칙이 필요할 수 있음을 보강했습니다.
Agent approvals & securityread-only 모드 사용처 추가
감사, 코드 설명, 위험 분석처럼 수정이 필요 없는 작업은 read-only sandbox를 우선 선택할 수 있음을 정리했습니다.
Sandboxfull access 사용 조건 명확화
full access 계열 설정은 격리 범위를 크게 줄이므로 신뢰 가능한 저장소와 명확한 작업에서만 쓰도록 경고를 추가했습니다.
Agent approvals & securityrules allowlist 운영 방식 추가
자주 승인하는 명령은 rules로 허용해 반복 승인을 줄이되, 범위를 명령 접두사 단위로 좁게 유지해야 함을 설명했습니다.
Rules네트워크 접근 규칙 분리 추가
패키지 설치, GitHub API, 문서 조회처럼 네트워크가 필요한 작업은 파일 쓰기 권한과 별개로 규칙을 설계하도록 보강했습니다.
Rules파괴적 명령 allowlist 금지 기준 추가
reset, clean, 삭제, force push 같은 되돌리기 어려운 명령은 일반 allowlist에 넣지 말고 매번 검토하도록 안내했습니다.
RulesAGENTS.md 탐색 순서 추가
Codex가 프로젝트 루트에서 현재 작업 디렉터리까지 내려오며 AGENTS.override.md, AGENTS.md, fallback 파일을 확인한다는 흐름을 추가했습니다.
AGENTS.mdAGENTS.override.md 우선순위 추가
특정 디렉터리에서 상위 지시를 임시로 덮어써야 할 때 AGENTS.override.md가 AGENTS.md보다 우선될 수 있음을 설명했습니다.
AGENTS.md하위 디렉터리별 지시 분리 추가
테스트, 프론트엔드, 백엔드처럼 규칙이 다른 영역은 각 디렉터리에 별도 AGENTS.md를 둬 맥락을 줄이도록 보강했습니다.
AGENTS.mdREADME와 AGENTS.md 역할 분리 추가
README는 사람용 안내, AGENTS.md는 에이전트용 빌드·테스트·PR 규칙을 담는 문서로 분리하라는 기준을 추가했습니다.
AGENTS.md개인 지시와 저장소 지시 충돌 방지 추가
개인 선호는 전역 지시로, 팀 규칙은 저장소 지시로 분리하고 충돌 시 프로젝트 규칙을 우선 검토하도록 안내했습니다.
AGENTS.mdMCP 서버 연결 방식 추가
Codex에서 MCP 서버를 등록해 외부 도구와 문서 검색을 연결할 수 있고, CLI와 IDE가 같은 설정을 공유할 수 있음을 보강했습니다.
MCPOpenAI Docs MCP 활용 추가
OpenAI 공식 문서를 다루는 작업에서는 OpenAI developer docs MCP를 연결해 최신 문서 검색과 페이지 읽기를 사용할 수 있음을 추가했습니다.
Docs MCPMCP 도구 신뢰 경계 추가
MCP 서버는 외부 시스템 접근 권한을 가질 수 있으므로 읽기 전용인지, 쓰기/실행 권한이 있는지 구분해 승인해야 함을 설명했습니다.
MCPChatGPT 로그인과 API 키 인증 선택 기준 추가
ChatGPT 계정은 제품 기능과 사용량 정책을 따르고, API 키는 API 과금·키 관리 책임을 따르므로 팀 운영 기준을 분리하도록 보강했습니다.
Authentication조직/프로젝트 선택 확인 추가
여러 OpenAI 조직이나 프로젝트를 쓰는 사용자는 인증 후 실제 과금·권한 컨텍스트가 맞는지 확인하도록 체크리스트를 추가했습니다.
AuthenticationAPI 키 보관 위치 주의 추가
API 키를 AGENTS.md, README, 저장소 파일에 넣지 말고 환경 변수나 안전한 secret 관리 흐름으로 분리하도록 안내했습니다.
Authentication원격 개발 환경 연결 기준 추가
로컬 앱이 원격 머신이나 컨테이너 기반 개발 환경과 연결될 때 파일 경로, shell, 인증, 네트워크 경계를 먼저 확인하도록 보강했습니다.
Remote connections원격 환경에서 sandbox 기대치 점검 추가
원격 연결은 로컬과 파일시스템·권한·네트워크 조건이 다를 수 있으므로 동일한 sandbox 설정이라도 실제 동작을 재검증해야 함을 추가했습니다.
Remote connectionsagent-turn-complete hook 활용 추가
작업 턴이 끝났을 때 알림, 로그 수집, 후처리 스크립트를 실행하는 hook 기반 운영 흐름을 설명했습니다.
Hookshook 실패 격리 기준 추가
hook은 보조 자동화이므로 실패해도 핵심 작업 판단을 흐리지 않도록 로그와 실패 처리를 분리해야 함을 보강했습니다.
Hooks민감정보 출력 방지 추가
hook 로그에는 prompt, 경로, 실행 결과가 포함될 수 있으므로 외부 전송 전에 민감정보 필터링을 적용해야 함을 설명했습니다.
Hooks설정 변경 후 버전 표기 추가
설정 문제를 재현할 때 앱 번들 Codex 버전, CLI 버전, config.toml, AGENTS.md 위치를 함께 기록하도록 운영 절차를 보강했습니다.
Troubleshooting팀 온보딩 체크리스트 확장
새 팀원에게 프로젝트 경로, AGENTS.md, local environment, rules, MCP, 인증 방식을 한 번에 확인시키는 순서를 추가했습니다.
Config basics공식 출처
-
ChatGPT · Codex 문서 홈
learn.chatgpt.com/docs -
Features 개요
learn.chatgpt.com/docs/features