한 줄 요약: Codex는 파일 정리·문서 형식 맞추기·브라우저 점검처럼 반복되는 작업을 덜어 주는 도구이고, 공개 전 최종 판단은 사람이 맡아야 합니다. 이 글은 시작 순서, 승인·샌드박스 설정 고르는 법, 잘 맞는 작업과 안 맞는 작업을 한 번에 정리한 실사용 기준입니다.
Codex는 어떤 도구인가
Codex CLI는 터미널 안에서 코드를 읽고, 파일을 고치고, 명령을 실행하게 해 주는 도구입니다. OpenAI 공식 문서는 이를 "터미널을 떠나지 않고 코드를 살펴보고, 변경하고, 명령을 실행하고, 반복 작업을 자동화"하는 도구로 소개합니다. 채팅창에 답만 받아 오는 방식과 달리, 내 작업 폴더 안에서 직접 파일을 열고 수정한다는 점이 가장 큰 차이입니다.
문서가 밝히는 사용 범위는 코드 살펴보기, 변경, 명령 실행, 반복 작업 자동화입니다. 터미널을 거의 쓰지 않는 분이라면 이 도구가 맞는지부터 따져 보셔야 하니, 아래 항목을 순서대로 읽으시면 시작 방법과 위험 관리까지 이어서 볼 수 있습니다.
그래서 평가 기준도 달라집니다. 한 번 나온 결과가 좋은지보다, 같은 종류의 작업을 반복했을 때 어디까지 믿고 맡길 수 있는지를 봐야 합니다. 저는 도구를 볼 때 결과 하나보다 작업 흐름을 먼저 봅니다. 파일 구조를 읽고 정리하거나, 문서 형식을 맞추거나, 브라우저에서 현재 화면을 점검하는 작업은 반복 확인의 부담을 줄여 주었습니다. 반면 공개 글의 최종 문구, 이미지에 개인정보가 보이는지, 실제 화면이 어색한지는 자동 결과만으로 판단할 수 없었습니다.
시작하는 순서와 자주 쓰는 명령
공식 문서 기준으로 macOS와 Linux에서는 한 줄 설치 명령이 안내되어 있고, 같은 명령으로 이미 설치된 버전을 업데이트할 수도 있습니다. 윈도우, npm, Homebrew용 설치 방법도 문서에 따로 있습니다. 설치가 끝나면 작업할 프로젝트 폴더에서 codex를 실행하고, 로그인 화면에서 ChatGPT 계정으로 로그인하는 방법이나 그 밖에 제공되는 로그인 방법 중 하나를 고르면 됩니다.
처음 쓰는 분이 알아 두면 좋은 명령은 아래 표에 모았습니다. 이 표는 공식 문서의 CLI 안내에 나온 명령만 옮긴 것입니다. 특히 처음 한 번은 /init으로 지침 파일을 만들고, /permissions로 지금 어떤 권한으로 도는지부터 보는 순서를 권합니다.
| 명령 | 하는 일 | 언제 쓰나 |
|---|---|---|
| codex | 대화형 세션 시작 | 프로젝트 폴더에서 작업을 시작할 때 |
| /init | Codex용 지침 파일(AGENTS.md) 생성 | 프로젝트에 처음 붙일 때 |
| /permissions | 파일 수정·명령 실행을 묻지 않고 할 수 있는 범위 설정, 현재 샌드박스와 쓰기 가능한 폴더 확인 | 시작 직후, 권한이 헷갈릴 때 |
| /status | 현재 세션 설정 표시 | 지금 설정이 맞는지 볼 때 |
| /model | 모델과 추론 강도 선택 | 작업 난이도에 맞춰 바꿀 때 |
| /review | 변경 내용을 검토해 문제점 찾기 | 수정이 끝난 뒤 |
| codex exec | 스크립트·파이프라인에서 비대화형 실행 | 반복 작업을 자동으로 돌릴 때 |
| codex resume | 저장된 대화 다시 열기 | 어제 하던 작업을 이어갈 때 |
설치와 로그인 방법은 OpenAI의 Codex 저장소 README(GitHub)에도 적혀 있습니다. README는 Codex CLI를 "내 컴퓨터에서 실행되는 OpenAI의 코딩 에이전트"로 소개하고, npm install -g @openai/codex 또는 brew install --cask codex로 설치한 뒤 codex를 실행해 "Sign in with ChatGPT"를 고르면 된다고 안내합니다. Plus, Pro, Business, Edu, Enterprise 플랜 사용자에게는 ChatGPT 로그인을, 그 밖에는 API 키 로그인을 쓸 수 있다고 하며 API 키 쪽은 추가 설정이 필요하다고 설명합니다. 요금제와 지원 범위는 바뀔 수 있으니 README와 공식 안내를 함께 확인하세요.
승인과 샌드박스, 어떻게 고를까
Codex를 쓸 때 가장 먼저 정할 것은 "어디까지 알아서 하게 둘 것인가"입니다. 공식 문서는 이를 두 축으로 나눕니다. 하나는 파일을 어디까지 건드릴 수 있는지를 정하는 샌드박스 모드(read-only, workspace-write, danger-full-access)이고, 다른 하나는 사람에게 언제 물어볼지를 정하는 승인 정책(on-request, never 등)입니다. 기본값은 버전 관리가 되는 폴더에서는 Auto 프리셋, 버전 관리가 안 되는 폴더에서는 read-only입니다.
네트워크 접근은 기본적으로 꺼져 있고, workspace-write에서 켜려면 설정 파일에서 따로 허용해야 합니다. 또 workspace-write 상태에서도 .git, .agents, .codex, .aws 폴더는 읽기 전용으로 남습니다. 공식 문서는 필요하지 않다면 네트워크를 계속 꺼 두고, 웹 검색 결과는 신뢰할 수 없는 자료로 다루라고 권합니다. 상황별로 고르는 기준을 표로 정리했습니다.
| 내 상황 | 샌드박스 | 승인 정책 | 이유 |
|---|---|---|---|
| 처음 써 보는 프로젝트, 코드를 읽기만 할 때 | read-only | on-request | 파일을 바꾸지 못하니 사고가 없습니다 |
| Git으로 관리되는 폴더에서 일반 작업 | workspace-write | on-request | Auto 프리셋과 같은 조합이며, 샌드박스 밖 동작만 물어봅니다 |
| CI에서 점검만 돌릴 때 | read-only | never | 사람이 없는 자리라 묻지 않고, 수정은 막아 둡니다 |
| 모든 제한을 푸는 설정 | danger-full-access | (우회 옵션) | 공식 문서가 권장하지 않는 설정입니다. 신뢰하는 저장소의 컨테이너 안에서만 고려합니다 |
참고로 승인 정책 값 중 untrusted는 더 이상 쓰지 않는 값이라고 문서에 적혀 있고, 설정 파일에 남아 있으면 시작을 막을 수도 있다고 합니다. 예전 글이나 예전 설정 예시를 그대로 복사해 쓰는 분은 이 값이 들어 있는지 먼저 보시기 바랍니다.
잘 맞는 작업과 안 맞는 작업
실제로 편했던 쪽은 세 가지였습니다. 첫째는 작업 맥락 유지입니다. 여러 파일과 기록을 대조할 때 확인 항목을 잊지 않도록 도왔습니다. 둘째는 반복 검수입니다. 제목, 라벨, 영문 주소, 이미지 대체 텍스트 같은 정형 항목을 다시 확인하기 편했습니다. 셋째는 초안 정리입니다. 원문을 그대로 옮기지 않고 공개 가능한 핵심만 새 글로 구성하는 데 쓸 수 있었습니다.
- 맞는 쪽: 반복적인 파일 정리, 형식 변환, 여러 파일에 걸친 같은 패턴의 수정.
- 맞는 쪽: 기존 코드를 읽고 어디를 고쳐야 하는지 찾는 일.
- 안 맞는 쪽: 판단 기준이 사람에게만 있는 일. 무엇이 맞는지 물어봐야 하는 작업입니다.
- 안 맞는 쪽: 되돌리기 어려운 작업. 실수 비용이 큰 곳에서는 승인 단계를 늘려야 합니다.
예시입니다. 같은 문구를 여러 파일에서 바꾸는 일은 변경 결과를 diff로 한눈에 볼 수 있어 맡기기 좋습니다. 반대로 어떤 표현이 독자에게 맞는지 정하는 일은 기준이 사람에게 있으므로, 초안만 받고 고르는 쪽이 낫습니다.
정리하면 기준은 "틀려도 되돌릴 수 있는가"입니다. 되돌릴 수 있는 일은 맡기고, 되돌릴 수 없는 일은 승인 단계를 늘리거나 사람이 직접 합니다.
브라우저 자동화에서 부딪히는 것
브라우저를 조작하는 작업은 파일 작업보다 실패가 조용합니다. 화면이 조금만 바뀌어도 이전에 되던 동작이 에러 없이 실패하는 경우가 있어서, 성공했다고 보고된 결과를 그대로 믿으면 안 됩니다. 아래 네 가지는 브라우저 자동화에서 부딪히는 대표적인 문제입니다.
- 화면이 바뀌면 이전에 되던 동작이 조용히 실패합니다.
- 요소를 찾는 방식이 화면 구조에 의존해서, 같은 사이트라도 페이지마다 다르게 잡아야 합니다.
- 로그인 상태가 필요한 작업은 세션 관리가 별도 문제가 됩니다.
- 성공했는지 확인하는 단계를 따로 두지 않으면 실패를 모르고 넘어갑니다.
가장 먼저 손볼 곳은 마지막 항목입니다. 동작이 끝난 뒤 화면에 실제로 어떤 값이 남았는지 따로 읽어서 기대한 값과 비교하는 단계를 작업마다 넣어 두면, 조용한 실패가 눈에 보이는 실패로 바뀝니다.
가상 예시입니다. 양식 제출을 자동화한다면 버튼을 눌렀는지가 아니라 완료 화면의 문구나 목록에 새 항목이 생겼는지를 성공 기준으로 삼는 식입니다. 기준이 화면에 남은 결과여야 화면이 바뀌었을 때 바로 실패로 잡힙니다.
AGENTS.md로 반복 지시를 한 곳에 두기
매번 같은 주의사항을 대화창에 적고 있다면 AGENTS.md를 쓸 때입니다. 공식 문서에 따르면 AGENTS.md는 Codex가 작업을 시작하기 전에 읽는 지속 지침 파일입니다. 전역 지침은 Codex 홈 폴더(기본은 홈 폴더 안의 .codex)에서, 프로젝트 지침은 프로젝트 루트부터 현재 작업 폴더까지 차례로 읽습니다. 폴더마다 하나의 파일만 쓰고, 루트에서 아래로 내려가며 이어 붙이기 때문에 현재 폴더에 가까운 지침이 뒤에 놓여 앞의 지침보다 우선합니다. 같은 자리에 AGENTS.override.md가 있으면 문서상 그 파일을 먼저 읽으므로, 임시로 지침을 덮어쓸 때 쓸 수 있습니다.
길이에도 한도가 있습니다. 합친 크기가 project_doc_max_bytes에 닿으면 더 읽지 않는데, 기본값은 32 KiB입니다. 그래서 지침은 짧게 쓰고, 폴더별로 나눠 두는 편이 안전합니다. 처음에는 /init으로 틀을 만든 뒤 "수정 전에 테스트 명령을 먼저 돌릴 것", "변경한 파일 목록을 마지막에 보여줄 것"처럼 확인 가능한 문장만 남기는 방식을 권합니다.
실사용에서 정해 둔 규칙
기능을 아는 것보다 쓰는 규칙을 정해 두는 쪽이 사고를 더 많이 막았습니다. 아래 네 가지가 제가 정해 둔 기준입니다. 공식 문서의 버전 관리 권고, 곧 기능 브랜치에서 작업하고 git status를 깨끗하게 유지하며 자주 커밋하고 변경을 PR처럼 검토하라는 내용과도 방향이 같습니다. 문서는 Codex가 바꾼 내용을 일반 PR처럼 읽고, 목표를 좁힌 검증을 돌리고, 결정을 커밋 메시지에 남기라고 안내합니다.
- 버전 관리가 되는 곳에서만 파일을 고치게 합니다. 되돌릴 수 있으면 대부분의 실수는 복구됩니다.
- 변경된 파일 목록을 매번 직접 확인합니다.
- 같은 오류가 두 번 반복되면 접근을 바꿉니다. 세 번째 시도는 대개 같은 결과입니다.
- 결과가 그럴듯해 보일수록 숫자와 고유명사를 따로 확인합니다.
공개 글을 다룰 때는 한 가지를 더 지킵니다. 공개 대상에는 내부 문서, 계정 정보, 경로, 실행 기록이 섞일 수 있으므로 최종 화면은 사람이 다시 봅니다. 자동화가 가능하다는 이유로 결과를 바로 올리지 않는 것, 이 기준을 지키지 않으면 빠른 작업이 오히려 잘못된 공개로 이어질 수 있습니다.
이 리뷰의 결론
제 기준에서 Codex는 반복 작업을 줄여 주는 도구이지만, 검수 책임을 대신해 주는 도구는 아닙니다. 파일·문서·브라우저 작업에서는 확인 항목을 놓치지 않게 도와 주었고, 판단이 사람에게만 있는 일과 되돌리기 어려운 일은 맡기지 않는 편이 맞았습니다.
처음 시작하신다면 읽기 전용으로 코드를 읽히는 것부터, 그다음 Git 폴더에서 Auto 조합으로 작은 수정을, 마지막으로 반복 작업을 자동화하는 순서가 안전합니다. 단계를 올릴 때마다 변경된 파일 목록을 직접 보는 습관을 같이 들이시기 바랍니다. 도구를 고르는 일 자체가 고민이라면 내 작업이 긴 자료 이해인지, 개발 과제인지, 터미널 작업인지 먼저 나눠 보는 비교 글이 도움이 됩니다. 새 AI 기능을 어떤 순서로 써 보면 좋은지는 작업 모드 써 보는 순서를 정리한 글에서 볼 수 있습니다.
공개 범위: 실제 계정 값, 내부 프로젝트명, 비공개 문서, 개인 파일 경로와 작업 로그는 포함하지 않습니다. 공식 문서 내용은 2026년 10월 18일 기준이며, 명령과 옵션은 업데이트에 따라 바뀔 수 있습니다.
확인 자료
- OpenAI, Codex CLI 저장소 README(GitHub) (설치 명령, ChatGPT 로그인과 API 키 로그인)
- OpenAI, Codex CLI 안내 (설치, 명령 목록, /permissions)
- OpenAI, Agent approvals & security (샌드박스 모드, 승인 정책, 네트워크 기본값, 보호 폴더, 버전 관리 권고)
- OpenAI, AGENTS.md 안내 (읽는 위치, 우선순위, 32 KiB 기본 한도)