OpenAI Codex 사용법 2026 CLI 세팅부터 goal 배포 체크리스트

OpenAI Codex는 2026년 5월 23일 기준 코드 작성, 이해, 리뷰, 디버그, 반복 개발 작업 자동화를 돕는 OpenAI의 코딩 에이전트다. 처음 쓸 때 핵심은 “코딩을 빨리 시킨다”가 아니라, 권한과 목표 조건을 먼저 잡고 작은 앱을 끝까지 검증하는 것이다.

Codex를 처음 켜면 마음이 조금 급해진다. “휴가 ERP 만들어줘”, “회의록 앱 만들어줘”, “Vercel에 배포해줘” 같은 문장을 바로 던지고 싶다. 나도 이 유혹을 안다. 새 장난감 포장 뜯자마자 설명서 버리는 그 손맛, 기술 블로그 쓰는 사람에게도 있다.

그런데 Codex는 설명서 없이 막 굴릴수록 이상하게 더 많이 돌아간다. 파일을 읽고, 명령을 실행하고, 실패하면 다시 고치고, 중간에 방향이 틀어지면 멋진 속도로 옆길을 판다. 빠른 도구일수록 처음 10분 세팅이 더 중요하다. 자동차가 빠르면 브레이크도 같이 봐야 하는 것과 비슷하다.

이 글은 빌더 조쉬 영상에서 정리된 Codex CLI, 플러그인, 문서화, /goal, API 연동 흐름을 바탕으로, 공식 OpenAI 문서 기준과 TECHTAEK 운영 경험을 합쳐 만든 사용법이다. 비개발자나 1인 개발자가 처음 내부 도구를 만들 때 어디서 시작하고, 어디서 멈춰 검수해야 하는지에 초점을 맞춘다.

먼저 잡을 답

Codex 첫 실행의 좋은 순서는 설치 -> 프로젝트 폴더 선택 -> AGENTS.md 작성 -> 권한 설정 -> 작은 목표 실행 -> 테스트와 배포 검증이다. 앱을 바로 만들기보다, Codex가 어떤 파일을 읽고 어떤 명령을 실행해도 되는지부터 정해야 한다.

OpenAI 공식 Quickstart 기준으로 Codex는 앱, IDE extension, CLI, cloud 인터페이스로 쓸 수 있다. CLI는 npm install -g @openai/codex 또는 Homebrew 설치 흐름이 있고, 터미널에서 codex를 실행해 ChatGPT 계정이나 OpenAI API key로 로그인한다.

처음에는 CLI가 제일 직관적이다. 현재 디렉터리에서 바로 작업하게 만들 수 있고, Git diff와 테스트 결과를 눈으로 확인하기 쉽다. 반대로 로그인된 웹사이트 작업은 Codex Chrome extension이나 앱 플러그인 쪽이 맞고, 긴 백그라운드 작업은 cloud가 편할 수 있다. 도구가 여러 개라서 복잡한 게 아니라, 작업 종류가 다르기 때문에 입구가 나뉜다.

1단계: CLI 설치보다 프로젝트 폴더를 먼저 고른다

Codex CLI 설치 명령은 짧다. 문제는 설치 뒤 어디에서 실행하느냐다. 아무 폴더에서나 codex를 켜면 Codex는 그 폴더를 기준으로 파일을 읽고 작업을 시작한다. 그래서 첫 작업은 “새 프로젝트 폴더를 만든다”가 아니라 “작업 경계를 만든다”에 가깝다.

처음 앱을 만든다면 빈 폴더나 실험용 repo가 낫다. 기존 업무 repo에서 바로 Full Access에 가까운 권한을 열면 실수의 반경이 커진다. 특히 .env, 인증키, 고객 데이터, 빌드 산출물, 배포 토큰이 섞인 폴더라면 시작 전에 읽기 금지와 실행 금지 규칙을 분리해야 한다.

가장 작은 시작은 아래처럼 잡을 수 있다.

mkdir codex-vacation-erp
cd codex-vacation-erp
git init
codex

여기서 바로 “사내 ERP 만들어줘”라고 하지 말자. 먼저 “이 프로젝트가 무엇이고, 어떤 파일을 건드리지 말아야 하는지”를 남기는 편이 좋다. Codex 공식 문서에서도 /init은 현재 디렉터리에 AGENTS.md scaffold를 만드는 명령으로 안내된다. 이 파일은 프로젝트의 지속 지침이다.

2단계: AGENTS.md에 금지선부터 적는다

AGENTS.md는 멋진 세계관 문서가 아니다. Codex가 매번 다시 읽을 작업 규칙이다. 처음에는 길게 쓰기보다 금지선과 완료 기준을 짧게 쓰는 편이 낫다.

예를 들어 휴가 등록 ERP를 만든다면 이런 식이다.

# AGENTS.md

- 이 프로젝트는 사내 휴가 신청 데모 앱이다.
- 새 의존성은 필요할 때만 추가하고 이유를 설명한다.
- `.env`, `secrets/`, 실제 직원 정보 파일은 읽거나 수정하지 않는다.
- UI는 모바일보다 데스크톱 내부 도구 화면을 우선한다.
- 완료 기준은 `npm test` 또는 최소 수동 검증 체크리스트를 남기는 것이다.

이 정도만 있어도 Codex의 작업 방향이 달라진다. “예쁘게 만들어줘”보다 “내부 도구이고, 비밀 파일은 건드리지 말고, 테스트 증거를 남겨라”가 훨씬 운영에 가깝다. AI에게 자유를 주는 것보다 경계를 주는 편이 결과가 더 안정적일 때가 많다.

빌더 조쉬 영상에서 강조한 Plan, Design, DESIGN.md, AGENTS.md 흐름도 같은 맥락이다. 무작정 구현으로 들어가기보다 상위 기획, 상세 설계, 디자인 규칙, 에이전트 행동 규칙을 먼저 만든다. 이름은 거창하지만 핵심은 단순하다. 사람 머릿속에만 있던 조건을 파일로 내리는 것이다.

3단계: 권한은 빠른 모드보다 확인 모드로 시작한다

Codex에는 /permissions 같은 권한 관련 slash command가 있다. 공식 slash commands 문서 기준으로 /permissions는 Codex가 묻지 않고 할 수 있는 작업을 조정하는 명령이다. 작업 중에도 Auto와 Read Only 같은 방향으로 요구 수준을 조절할 수 있다.

처음부터 모든 것을 자동 승인하면 빠르다. 그런데 빠른 만큼 사고도 빠르다. 실험 폴더에서는 괜찮아도, 실제 repo에서는 읽기, 쓰기, 명령 실행, 네트워크, 배포를 단계별로 여는 편이 안전하다.

내가 추천하는 첫 주 기본값은 이렇다.

단계	권한 감각	맡길 작업
1차 탐색	읽기 중심	구조 설명, 파일 위치 찾기, 변경 계획
2차 구현	제한된 쓰기	새 컴포넌트, 작은 스크립트, 테스트 추가
3차 검증	명령 실행 허용	lint, test, build 실행
4차 배포	사람 확인 후 실행	Vercel, GitHub, WordPress, DB 변경

권한을 나누면 귀찮아 보인다. 하지만 나중에 “왜 이 파일이 바뀌었지”를 추적하는 것보다 훨씬 싸다. 자동화에서 제일 비싼 비용은 실행 시간이 아니라 원인 모를 변경을 되감는 시간이다.

4단계: /goal은 긴 작업의 목적지로 쓴다

OpenAI slash commands 문서 기준으로 /goal은 task goal을 설정, 일시정지, 재개, 확인, 삭제하는 명령이다. Codex에게 큰 작업을 맡길 때 “이번 스레드가 따라갈 목표”를 붙이는 기능으로 보면 된다.

중요한 건 /goal이 마법 주문이 아니라는 점이다. 목표가 흐리면 Codex도 흐리게 간다. 좋은 goal은 작업 범위, 완료 조건, 검증 방법을 같이 넣는다.

/goal 휴가 신청 데모 앱을 만든다. 기능은 잔여 연차 표시, 휴가 신청 폼, 신청 목록까지로 제한한다. 실제 인증과 DB는 만들지 말고 로컬 mock data만 쓴다. 완료 조건은 빌드 성공, 핵심 화면 스크린샷 또는 수동 검증 체크리스트, 변경 파일 요약이다.

이렇게 쓰면 Codex가 무엇을 만들고 어디서 멈춰야 하는지 알기 쉽다. 반대로 “ERP 만들어줘”는 너무 넓다. ERP라는 단어 하나에 인사, 회계, 권한, 문서, 승인, 감사 로그, 배포까지 다 붙는다. 한 문장 안에 회사가 들어가면 보통 첫 버전은 터진다.

빌더 조쉬 영상의 휴가 등록 ERP와 회의록 전사 앱 사례도 이 관점에서 보면 좋다. 핵심은 Codex가 앱을 만들 수 있다는 사실이 아니라, 작은 업무 흐름을 목표 단위로 잘라 구현과 검증을 반복한다는 점이다.

5단계: 배포는 마지막 버튼이 아니라 별도 단계다

Codex가 Vercel 배포나 API 연동까지 도와줄 수 있다고 해서, 배포를 구현의 마지막 줄처럼 취급하면 위험하다. 배포에는 환경변수, 접근 권한, 빌드 로그, 도메인, 데이터 보존, 비용이 붙는다.

처음 배포할 때는 아래 네 가지를 따로 확인하자.

확인 항목	질문
환경변수	API key가 repo에 들어가지 않았나?
빌드 로그	실패 로그에 비밀값이 찍히지 않았나?
권한	배포 토큰이 너무 넓은 권한을 갖고 있지 않나?
롤백	배포가 깨지면 이전 버전으로 돌아갈 방법이 있나?

Codex를 CI나 스케줄러에 붙일 계획이라면 배포 전에 Codex Hooks와 Programmatic Access Token 시크릿 스캔 운영표도 같이 보는 편이 좋다. CLI 세팅 글은 시작 순서를 잡는 용도이고, Hooks/PAT 글은 자동화 identity, token 만료, secret 로그 차단선을 정하는 용도다. 시작 버튼과 브레이크 설명서를 한 화면에 두자는 뜻이다.

OpenAI의 Codex multi-agent workflow 문서는 Codex CLI를 MCP server로 노출하고 Agents SDK와 함께 deterministic, reviewable workflow를 만들 수 있다고 설명한다. 여기서 중요한 단어는 “reviewable”이다. 배포 자동화도 마찬가지다. 자동으로 됐다는 말보다, 나중에 검토할 증거가 남는지가 더 중요하다.

실수 TOP 6

첫 번째 실수는 Codex를 켜자마자 큰 앱을 한 번에 맡기는 것이다. 내부 도구는 작게 잘라야 한다. 휴가 신청, 회의록 전사, 고객 목록, 승인 대기 화면처럼 하나의 업무 흐름으로 시작하는 편이 낫다.

두 번째 실수는 AGENTS.md 없이 작업하는 것이다. 사람에게도 업무 인수인계가 필요한데, 에이전트에게 아무 규칙 없이 “알아서 해”라고 하면 매번 다른 기준으로 움직인다. 파일 하나로 기본값을 고정해두자.

세 번째 실수는 권한을 속도 문제로만 보는 것이다. 빠른 모드는 실험 폴더에서는 좋지만, 업무 repo에서는 읽기 금지, 실행 금지, 배포 전 확인이 필요하다. 보안은 거창한 팀만의 문제가 아니다. 개인 repo의 .env도 한 번 새면 충분히 피곤하다.

네 번째 실수는 /goal에 완료 조건을 안 쓰는 것이다. “끝까지 해줘”는 완료 조건이 아니다. “빌드 성공, 테스트 결과, 변경 요약, 남은 리스크 보고”처럼 증거를 적어야 한다.

다섯 번째 실수는 API 연동을 너무 빨리 붙이는 것이다. 회의록 전사 앱이라면 먼저 mock transcript로 UI와 저장 흐름을 검증하고, 그다음 OpenAI API key와 실시간 음성 입력을 붙이는 편이 안전하다. 실시간 기능은 멋있지만 디버깅도 실시간으로 난리 난다.

여섯 번째 실수는 배포 성공만 보고 끝내는 것이다. 배포 URL이 떴다고 제품이 된 건 아니다. 모바일 화면, 빈 데이터, 실패 상태, 권한 없는 사용자, 비용 한도, 로그 노출까지 봐야 한다.

첫 프로젝트 추천 순서

처음 Codex로 앱을 만든다면 아래 순서가 무난하다.

README.md에 앱 목적과 제외 범위를 쓴다.
/init 또는 직접 작성으로 AGENTS.md를 만든다.
“화면 1개 + mock data”만 목표로 /goal을 건다.
Codex가 만든 계획을 /diff로 확인한다.
테스트나 수동 검증 체크리스트를 요구한다.
로컬에서 확인한 뒤 배포는 별도 goal로 분리한다.

이 순서는 느려 보이지만 실패 복구가 쉽다. 첫 goal은 화면을 만드는 goal이고, 두 번째 goal은 API를 붙이는 goal이며, 세 번째 goal은 배포하는 goal이다. 한 goal에 전부 넣으면 멋진 데모가 나올 수는 있어도, 어디서 틀어졌는지 추적하기 어렵다.

내가 Codex를 업무에 붙인다면 첫 기준은 이렇다. Codex에게 속도를 맡기되, 목표 조건과 검수 증거는 사람이 정한다. 구현은 빨라질 수 있지만 책임은 자동으로 사라지지 않는다.

FAQ

Codex CLI와 Codex 앱 중 무엇부터 쓰면 좋나?

로컬 repo에서 코드 변경과 테스트를 바로 확인하려면 CLI가 좋다. 프로젝트 폴더를 선택하고 대화형으로 작업하기에는 앱도 편하다. 로그인된 웹사이트나 외부 앱 작업이 많으면 앱의 플러그인과 Chrome extension 흐름을 따로 검토하면 된다.

/goal은 /plan과 무엇이 다른가?

/plan은 구현 전에 실행 계획을 잡는 데 가깝고, /goal은 스레드에 지속 목표를 붙이는 기능이다. 긴 작업에서는 먼저 계획을 확인하고, 그 계획을 더 작은 goal로 나눠 진행하는 편이 안전하다.

비개발자도 Codex로 앱을 만들 수 있나?

작은 내부 도구나 데모 앱은 가능하다. 다만 실제 업무에 쓰려면 인증, 권한, 데이터 보존, 예외 처리, 비용 한도, 배포 로그를 사람이 확인해야 한다. “만들 수 있다”와 “운영해도 된다”는 다른 문장이다.

API key는 어디에 둬야 하나?

repo에 직접 넣지 말고 환경변수나 배포 플랫폼의 secret 관리 기능을 써야 한다. Codex에게도 .env와 secret 폴더를 읽지 말라는 규칙을 AGENTS.md나 권한 설정에 남기는 편이 좋다.

첫 프로젝트로 무엇을 추천하나?

휴가 신청 데모, 회의록 요약 저장, 주간 업무 정리, 블로그 초안 검수처럼 입력과 출력이 선명한 내부 도구가 좋다. 결제, 세금, 고객 개인정보 자동화는 나중에 붙이는 편이 안전하다.

OpenAI Codex 사용법 2026 – CLI 세팅부터 /goal 배포까지 실패 줄이는 체크리스트