OpenAI Codex CLI 실전 가이드

설치 없이 먼저 맛보기 (초보는 여기부터)

Codex는 Claude처럼 클릭만으로 들어가는 데스크톱 'Code 탭' 화면이 없습니다. 진짜 Codex(터미널 도구)는 명령어를 쳐야 하는 도구라, 비개발자가 첫날 바로 깔기엔 문턱이 높습니다. 그래서 순서를 거꾸로 권합니다 — 설치는 나중에, 먼저 ChatGPT로 'AI가 코드를 봐주는 느낌'부터 가볍게 경험하세요.

가장 쉬운 길은 브라우저로 chatgpt.com에 들어가 로그인하는 것입니다(설치 0). 스마트폰이라면 ChatGPT 앱을 받아도 똑같습니다. 그다음 대화창에 코드나 파일을 붙여넣고 한국어로 "이 코드가 뭐 하는 거야?", "여기 오류 좀 고쳐줘"처럼 사람한테 부탁하듯 물어보면 됩니다. 이 단계만으로도 'AI 코딩'이 무엇인지 충분히 감이 옵니다.

터미널 도구인 Codex CLI는 '터미널(검은 명령창)을 쓸 줄 알게 된 다음'에 넘어가는 단계입니다. 저장소를 직접 읽고 파일을 고치는 더 강력한 동료지만, 명령어 입력이 익숙하지 않다면 서두를 필요가 전혀 없습니다. 먼저 ChatGPT 웹/앱으로 한동안 써보고, 터미널이 편해질 때 아래 '(고급)' 설치로 내려오세요.

그림으로 따라 하는 설치·첫 화면이 필요하면 '왕초보 시작하기' 가이드를 함께 보세요. Codex는 보여줄 앱 화면이 없어 이 가이드는 글·구조 중심으로 안내합니다.

(고급) 터미널이 익숙한 분만: macOS·리눅스에서 'curl -fsSL https://chatgpt.com/codex/install.sh | sh' 한 줄로 설치되고, macOS는 'brew install --cask codex', Node를 쓰면 'npm install -g @openai/codex'(Node 22+)도 됩니다. 윈도우는 PowerShell이나 WSL2에서 돌립니다. 설치 후 작업 폴더에서 codex 를 치면 첫 실행 때 로그인을 묻고, 기본은 'ChatGPT 계정으로 로그인'(브라우저로 인증)이라 가장 단순합니다. 쓴 만큼 내는 OpenAI API 키 방식도 있는데, 이건 자동화·팀 정산에 어울리는 선택이니 지금은 몰라도 됩니다(요금 비교는 이 장 마지막 절에서).

첫 세션과 승인 흐름

codex 를 켜면 대화형 터미널 UI가 뜹니다. 여기서부터는 명령어 암기가 아니라 '말'로 시작합니다. "이 프로젝트 구조를 설명해줘" 같은 평범한 요청이면 충분하고, 특정 파일을 붙이고 싶으면 /mention 으로 끌어옵니다.

Codex의 첫인상은 '바로 안 고친다'입니다. 엔지니어형답게, 파일을 바꾸거나 명령을 실행하기 전에 승인을 묻고 샌드박스(접근 경계) 안에서만 움직입니다. 처음엔 답답해 보여도 이 멈춤이 사고를 막는 핵심 설계입니다. 자세한 건 2장에서 다룹니다.

권한과 샌드박스는 실행 옵션으로도 정합니다. --sandbox(read-only · workspace-write · danger-full-access)와 --ask-for-approval(untrusted · on-request · never)로 '어디까지 손대고 언제 물을지'를 잡고, 세션 안에서는 /permissions 로 조정합니다. 모든 안전장치를 끄는 --yolo(우회)는 이름 그대로 위험하니 평소엔 쓰지 마세요.

스크립트나 CI에 태울 때는 대화 없이 'codex exec "할 일"'로 한 번에 돌립니다. 옆에서 승인할 사람이 없는 환경이니 권한을 미리 좁혀 두는 게 전제입니다(4장). 첫 세션에서 외울 건 셋뿐입니다 — 현황은 /status, 파일은 /mention, 변경 확인은 /diff.

어떤 요금제를 고를까

Codex도 모델을 쓰려면 둘 중 하나가 필요합니다. ChatGPT 요금제이거나, OpenAI API 키입니다. 두 방식은 과금 구조가 달라, 쓰는 패턴에 맞춰 고르면 한도와 지출을 함께 통제할 수 있습니다.

ChatGPT 요금제는 무료부터 Go(월 8달러 수준)·Plus(월 20달러 수준)·Pro(월 100달러대 이상)·Business·Enterprise로 나뉩니다. 사용량은 '몇 시간 단위 창'의 메시지 한도로 제한되고, 상위 요금제일수록 한도가 큽니다. 모델은 최신 GPT-5.x 및 코덱스 특화(GPT-5.x-codex) 계열을 씁니다.

API(플랫폼) 방식은 토큰당 과금입니다. 모델별 입력·출력 단가가 다르고 쓴 만큼 냅니다. 사용량이 들쭉날쭉하거나 CI·자동화에 태우는 경우, 그리고 여러 명이 정산해야 하는 팀에 맞습니다. 실제 비용은 개발자 1인당 월 100~200달러대로 편차가 크다고 알려져 있습니다.

고르는 기준은 단순합니다. 매일·예측 가능하게 쓰면 요금제가 마음 편하고, 가끔·몰아서·자동화에 쓰면 API가 합리적입니다. 어느 쪽이든 4장의 비용 관리(/usage·/compact·/new)를 함께 쓰면 한도와 지출이 조용히 새는 걸 막습니다.

AGENTS.md, 사람이 적어 두는 정적 지침

AGENTS.md는 사람이 직접 작성하는 지침 파일입니다. 빌드 명령, 코딩 규칙, 테스트 방법, 그리고 하지 말아야 할 것을 적어 두면 Codex가 작업을 시작할 때 자동으로 읽어 컨텍스트에 넣습니다. 새 팀원에게 첫날 건네는 온보딩 문서와 같은 역할을 합니다 — 다른 점이 있다면 이 문서는 매 세션 빠짐없이 읽힌다는 것입니다.

왜 이게 중요할까요. 에이전트는 매번 빈손으로 시작합니다. 어제 알려준 '우리는 pnpm을 쓴다' '커밋 메시지는 한국어로' 같은 약속을 다음 세션은 기억하지 못합니다. AGENTS.md는 그 약속을 코드처럼 저장소에 박아 두는 장치입니다. 사람이 바뀌어도, 세션이 끊겨도, 규칙은 파일에 남습니다.

지침은 계층으로 쌓입니다. 전역 지침은 ~/.codex/AGENTS.md에 두고, 프로젝트 공통 규칙은 저장소 루트에, 특정 작업 디렉터리에만 해당하는 규칙은 그 디렉터리에 둡니다. Codex는 루트에서 작업 디렉터리 방향으로 내려오며 이 파일들을 차례로 읽습니다. 그래서 '회사 전체 규칙 → 이 프로젝트 규칙 → 이 폴더만의 규칙' 순으로 점점 구체화하는 식으로 설계하면 깔끔합니다.

흔한 실수는 한 파일에 모든 것을 욱여넣는 것입니다. AGENTS.md는 기본적으로 32KiB(project_doc_max_bytes)까지만 읽히므로, 분량이 넘치면 뒷부분은 무시됩니다. '자주 쓰이는 핵심 규칙'을 앞에 두고, 디렉터리별로 나눠 쓰는 편이 안전합니다. 또 하나, 지침은 추상적인 다짐('깨끗한 코드를 써라')이 아니라 검증 가능한 규칙('새 함수에는 단위 테스트를 함께 추가하라')으로 적어야 효과가 있습니다.

Memories, Codex가 스스로 쌓는 기억

AGENTS.md가 사람이 적는 정적 레이어라면, Memories는 Codex가 작업하며 자동으로 만들어 두는 세션 요약 레이어입니다. ~/.codex/memories/ 아래에 쌓이며, 다음 세션에서 맥락을 이어 갈 때 참고됩니다. '지난번에 이 모듈을 이렇게 고쳤다' 같은 흐름의 기억을 사람이 매번 다시 설명하지 않아도 되게 해 줍니다.

두 레이어는 역할이 분명히 다릅니다. '반드시 지켜야 할 규칙'은 사람이 AGENTS.md에 명시하고, '지난번에 이렇게 했었지' 같은 맥락은 Memories가 채웁니다. 이 구분을 헷갈리면 위험합니다. 자동 요약은 사라지거나 바뀔 수 있고, 잘못 요약될 수도 있습니다. 그러니 절대 지켜야 할 제약을 Memories에만 맡기지 마세요.

Memories는 편리하지만 맹신할 대상은 아닙니다. 가끔 /memories 로 들여다보면, Codex가 의외의 것을 기억하거나 오해한 채 기억하고 있는 경우를 발견하게 됩니다. 그중 '규칙'에 해당하는 것은 AGENTS.md로 끌어올려 고정하고, 잘못된 맥락은 정리합니다. 메모리를 관리한다는 것은 곧 에이전트의 머릿속을 정돈하는 일입니다.

/init 와 config.toml 로 골격 만들기

빈 프로젝트에 손으로 AGENTS.md를 쓰는 건 막막합니다. 그럴 때는 /init 을 먼저 칩니다. Codex가 코드베이스를 훑어 디렉터리 구조와 빌드 방식을 파악하고 AGENTS.md 초안을 스캐폴드해 줍니다. 백지에서 시작하는 것보다, 생성된 초안을 보며 틀린 부분을 고치고 빠진 규칙을 더하는 편이 훨씬 빠릅니다.

다만 /init 의 결과물은 어디까지나 초안입니다. 자동으로 파악한 내용에는 추측이 섞여 있을 수 있으니, 그대로 믿지 말고 한 번 읽어 내려가며 검증하세요. 특히 '하지 말아야 할 것'은 사람만이 알고 있는 맥락이라 자동 생성이 채워 주지 못합니다.

도구 자체의 동작은 ~/.codex/config.toml 에서 정합니다. 어떤 모델을 쓸지(model), 샌드박스를 어떻게 둘지(sandbox), 원격 설정(remote), 단축키 매핑(tui.keymap)까지 여기서 조정합니다. AGENTS.md가 '무엇을 할지'를 적는 문서라면, config.toml은 '어떤 환경·어떤 권한으로 할지'를 정하는 설정입니다. 둘을 헷갈리지 않는 것이 중요합니다 — 규칙은 AGENTS.md로, 환경은 config.toml로.

config.toml은 한 번 잘 잡아 두면 팀 전체의 기본값이 됩니다. 예컨대 기본 샌드박스 수준을 보수적으로 잡아 두면, 누가 어떤 세션을 열든 '읽기부터 시작'하는 안전한 출발선을 공유하게 됩니다. 개인 취향(테마·키맵)과 팀 정책(모델·샌드박스)을 한 파일에서 함께 관리한다는 점을 기억하세요.

/permissions, 어디까지 허용할지 정하기

Codex의 핵심은 '함부로 실행하지 않는다'입니다. /permissions 로 권한 수준을 조정합니다. Read Only는 읽기만 허용해 코드를 분석만 시킬 때 쓰고, Auto는 정해진 울타리 안에서 편집과 실행을 자동으로 진행하게 합니다. 두 모드 사이에서 작업 성격에 맞는 지점을 고르는 것이 Codex 운용의 출발점입니다.

왜 권한을 일부러 좁히느냐고 물을 수 있습니다. 에이전트가 빠를수록 사고도 빠르기 때문입니다. 잘못된 명령 하나가 순식간에 파일을 덮어쓰거나 의존성을 망가뜨립니다. 권한을 좁힌다는 것은 '에이전트를 못 믿어서'가 아니라, 실수가 번지는 속도를 사람이 따라잡을 수 있는 범위로 묶어 두는 안전장치입니다.

처음에는 좁게 시작하는 것이 안전합니다. 낯선 저장소나 운영 코드에서는 Read Only로 먼저 구조를 파악하고, 신뢰가 쌓이고 작업 범위가 분명해지면 Auto로 올립니다. 권한은 한 번 정하면 끝이 아니라, 작업 성격에 따라 그때그때 조정하는 다이얼입니다. 탐색 단계에서는 내리고, 손에 익은 반복 작업에서는 올리는 식으로 움직입니다.

흔한 실수는 '귀찮으니 처음부터 Auto'로 두는 것입니다. 익숙해질수록 그 유혹이 커집니다. 하지만 권한을 높이는 순간은 곧 사람의 검토 책임이 커지는 순간이기도 합니다. 권한을 올렸다면, 그만큼 변경분을 더 자주·더 꼼꼼히 들여다봐야 균형이 맞습니다.

샌드박스, 움직일 수 있는 울타리

샌드박스는 Codex가 접근할 수 있는 파일·명령의 경계입니다. 기본적으로 작업 중인 저장소 안쪽으로 범위를 제한해, 엉뚱한 디렉터리를 건드리거나 시스템 전체를 헤집지 못하게 합니다. 권한 모드가 '얼마나 적극적으로 행동하느냐'라면, 샌드박스는 '어디까지 손이 닿느냐'를 정합니다. 둘은 다른 축이고, 함께 쓰여 한 겹의 안전망을 만듭니다.

작업하다 보면 저장소 밖의 파일을 읽어야 할 때가 있습니다. 공유 라이브러리나 다른 폴더의 설정을 참조해야 할 때입니다. 그럴 때는 /sandbox-add-read-dir 로 읽기 디렉터리를 명시적으로 추가합니다. 핵심은 '필요한 만큼만, 그때그때 열어 준다'입니다. 한 번에 전부 열어 두는 게 아니라, 막혔을 때 필요한 한 칸씩 넓히는 식으로 운용합니다.

왜 처음부터 넓게 열지 않을까요. 경계가 넓을수록 실수의 영향 범위도 넓어지기 때문입니다. 좁은 샌드박스는 설령 에이전트가 엉뚱한 일을 하더라도 피해를 작업 폴더 안에 가둡니다. '넓게 열어 편하게'와 '좁게 닫아 안전하게' 사이에서, Codex는 후자를 기본값으로 삼습니다.

샌드박스 설정과 현재 상태가 헷갈릴 때는 /status 를 칩니다. 어떤 모델로, 어떤 권한·샌드박스에서, 어느 작업 디렉터리에 있는지를 한눈에 보여 줍니다. 작업을 시작하기 전과 권한을 바꾼 직후에 /status 로 현재 위치를 확인하는 습관이 사고를 줄입니다.

/approve, 멈춰 선 작업을 다시 보내기

권한이 좁을 때 Codex는 위험하거나 범위를 벗어나는 작업 앞에서 멈추고 거부합니다. 그 작업이 사실 안전하고 의도한 것이라면 /approve 로 재시도시킵니다. 이 '거부 → 확인 → 승인'의 한 박자가 Codex를 안전하게 만드는 핵심 장치입니다. 멈춤은 버그가 아니라 설계된 안전핀입니다.

이 한 박자를 귀찮아하는 순간 안전은 무너집니다. 자동화의 비결은 권한을 높게 두는 게 아니라, 멈춤을 귀찮아하지 않는 데 있습니다. Codex가 멈춰 물을 때마다 '이게 정말 해도 되는 일인가'를 사람이 한 번 더 보는 것 — 그 한 번의 확인이 되돌릴 수 없는 사고를 막습니다.

반대로, 같은 작업에서 /approve 를 반복하게 된다면 그건 신호입니다. '이 종류의 작업은 항상 안전하다'고 판단된다면, 매번 승인하는 대신 권한 모드나 샌드박스 설정을 조정해 흐름을 매끄럽게 만드는 편이 낫습니다. 멈춤이 잦다면 권한이 너무 좁다는 뜻이고, 멈춤 없이 위험한 일이 일어난다면 권한이 너무 넓다는 뜻입니다. /approve 의 빈도는 권한 다이얼을 어디에 맞춰야 할지 알려 주는 계기판입니다.

REQUIREMENTS.md + AGENT_TASKS.md 로 작업을 구조화하기

큰 작업은 한 세션에 다 담기 어렵습니다. 컨텍스트가 길어지면 앞에서 정한 것을 뒤에서 잊고, 한 사람이 처음부터 끝까지 붙어 있기도 힘듭니다. Codex 워크플로는 이를 두 파일로 나눕니다. REQUIREMENTS.md에는 '무엇을 만들 것인가'(요구사항·제약)를 적고, AGENT_TASKS.md에는 '누가 어떤 순서로 할 것인가'(역할별 작업 목록)를 적습니다.

이렇게 해 두면 여러 역할과 여러 세션 사이에서 맥락이 끊기지 않고 넘어갑니다. 한 세션이 요구사항을 정하고, 다른 세션이 작업을 실행하고, 또 다른 세션이 검토하는 핸드오프가 가능해집니다. 사람 팀이 기획서와 작업 보드를 나눠 쓰는 것과 같은 구조입니다 — 다만 그 보드를 읽고 채우는 주체에 에이전트가 끼어 있을 뿐입니다.

왜 두 파일로 나눌까요. '무엇을'과 '어떻게'를 섞으면 둘 다 흐려지기 때문입니다. 요구사항이 작업 목록에 묻히면 나중에 '원래 뭘 하려던 거였지'를 잃고, 작업 목록이 요구사항에 묻히면 진척을 추적하지 못합니다. 분리해 두면 요구사항은 안정적인 기준으로 남고, 작업 목록은 진행에 따라 자유롭게 갱신됩니다.

실전에서는 AGENT_TASKS.md의 각 항목을 체크박스로 관리하고, 세션이 바뀔 때마다 완료/미완료를 갱신하는 식으로 씁니다. 그래야 새 세션이 파일만 읽고도 '어디까지 됐고 다음은 무엇인지'를 즉시 파악합니다. 핸드오프가 깨끗하다는 것은 곧, 이 두 파일만 보면 누구든(사람이든 에이전트든) 이어받을 수 있다는 뜻입니다.

MCP, 외부 도구를 연결하기

Codex는 MCP(Model Context Protocol)로 외부 도구·서비스에 연결됩니다. MCP는 에이전트와 외부 도구를 잇는 개방 표준으로, STDIO 방식과 스트리밍 HTTP 방식의 서버를 붙일 수 있습니다. 덕분에 DB 조회나 사내 API 호출, 외부 문서 검색 같은 작업을 Codex 대화 안에서 직접 처리할 수 있습니다.

MCP가 바꾸는 것은 에이전트의 '손이 닿는 범위'입니다. 기본 Codex는 저장소 안의 파일과 명령만 다루지만, MCP 서버를 붙이면 저장소 밖 세계와도 대화할 수 있게 됩니다. 코드를 고치다 말고 '이 값이 운영 DB에 실제로 어떻게 들어가 있지'를 그 자리에서 물어볼 수 있다는 뜻입니다.

연결 상태는 /mcp 로 확인하고 관리합니다. 여기서 어떤 서버가 붙어 있고 어떤 도구가 노출되는지 점검합니다. 주의할 점은 도구를 무작정 많이 붙이는 것이 능사가 아니라는 것입니다. 도구가 늘수록 컨텍스트가 무거워지고, 무엇보다 외부로 손이 닿는 통로가 늘어나 권한 관리가 복잡해집니다. 지금 작업에 필요한 것만 연결하는 절제가 컨텍스트도 보안도 깔끔하게 유지합니다.

MCP 서버는 신뢰의 경계를 넘나드는 통로라는 점을 잊지 마세요. 출처가 분명한 서버만 붙이고, 외부 데이터를 가져오는 도구일수록 그 결과를 곧이곧대로 실행에 옮기기 전에 한 번 검증하는 습관이 필요합니다. 편리함과 위험이 같은 문으로 들어옵니다.

/review 와 /diff, 변경을 눈으로 확인하기

Codex가 코드를 고쳤다면 그대로 믿고 넘어가지 말고 검토합니다. /diff 로 이번 세션에서 무엇이 바뀌었는지 변경분을 확인하고, /review 로 변경 내용을 점검합니다. 엔지니어형 도구의 마지막 단계는 '실행'이 아니라 '검토'입니다. 자동으로 빠르게 고쳤다는 사실은, 그만큼 빠르게 틀렸을 수도 있다는 뜻이기도 합니다.

검토의 핵심은 결과물 전체가 아니라 '변경분'에 시선을 모으는 것입니다. 파일 전체를 다시 읽으려 하면 지치고 놓칩니다. /diff 가 보여 주는 것은 정확히 '이번에 달라진 곳'이고, 사람이 봐야 할 곳도 거기로 좁혀집니다. 에이전트에게 더 많이 맡길수록, 사람의 일은 '코드를 쓰는 것'에서 '변경을 읽는 것'으로 옮겨 갑니다.

컨텍스트가 길어졌다면 /compact 로 대화를 요약해 작업 공간을 확보합니다. 긴 세션을 통째로 끌고 다니면 응답이 느려지고 초점이 흐려지므로, 한 단락의 작업이 끝나면 압축하고 다음으로 넘어가는 리듬이 좋습니다. 결과를 다른 곳에 옮길 때는 /copy 로 깔끔하게 가져갑니다.

마무리는 항상 같습니다. 사람이 변경을 한 번 보고, 사람의 손으로 커밋합니다. Codex가 커밋까지 대신할 수 있더라도, 무엇이 저장소에 들어가는지를 최종적으로 책임지는 것은 사람이어야 합니다. 이 마지막 한 단계를 생략하지 않는 것이, 자동화를 신뢰할 수 있게 만드는 마지막 매듭입니다.

승인 전략, 작업 위험도에 다이얼을 맞추기

권한 모드는 한 번 정하는 것이 아니라 작업마다 다르게 맞추는 전략의 문제입니다. 핵심 기준은 '되돌릴 수 있는가'입니다. 되돌리기 쉬운 작업(코드 탐색, 로컬 리팩터, 테스트 작성)은 권한을 올려도 사고의 폭이 좁습니다. 반대로 되돌리기 어려운 작업(의존성 변경, 마이그레이션, 배포)은 권한을 낮추고 멈춤을 늘리는 편이 안전합니다.

실전 전략은 단순합니다. '탐색은 Read Only, 실행은 Auto, 위험한 한 걸음은 직접 승인'으로 단계를 나누는 것입니다. 같은 세션 안에서도 코드를 읽을 때는 좁게, 반복적인 편집을 굴릴 때는 넓게, 그리고 운영에 영향을 주는 명령 앞에서는 다시 좁혀 멈추게 합니다. 권한을 고정값이 아니라 작업의 위험 곡선을 따라 움직이는 다이얼로 다루는 것이 요령입니다.

팀에서는 이 전략을 개인 취향에 맡기지 말고 config.toml의 기본값과 AGENTS.md의 규칙으로 못 박아 두는 편이 좋습니다. 예를 들어 '운영 관련 작업 디렉터리에서는 항상 좁은 권한으로 시작한다'는 약속을 파일로 남기면, 누가 어떤 세션을 열든 같은 안전 기준에서 출발합니다.

가장 흔한 사고는 '익숙함'에서 옵니다. 처음엔 신중하던 사람도 며칠 쓰다 보면 Auto를 기본으로 두고 멈춤을 습관적으로 넘기게 됩니다. 위험한 작업일수록 의식적으로 다이얼을 내리는 규율 — 그것이 자동화를 오래 안전하게 쓰는 사람과 한 번 크게 데는 사람을 가릅니다.

샌드박스 경계와 비밀정보 관리

샌드박스는 단순한 폴더 제한이 아니라, 사고가 번지는 범위를 가두는 둑입니다. 잘 설계된 샌드박스는 '작업에 꼭 필요한 곳까지만' 손이 닿게 합니다. 그래서 새 작업을 시작할 때는 '이 작업이 정말 닿아야 하는 디렉터리는 어디까지인가'를 먼저 묻고, 거기에 맞춰 경계를 잡는 습관이 중요합니다.

특히 비밀정보(API 키, 토큰, 인증 파일)는 샌드박스 설계에서 가장 신경 써야 할 지점입니다. 에이전트가 읽을 수 있는 범위 안에 .env나 자격증명 파일이 들어 있다면, 그 내용이 컨텍스트로 빨려 들어가거나 로그에 남을 수 있습니다. 비밀정보가 든 디렉터리는 샌드박스 밖에 두거나, 꼭 필요하지 않다면 /sandbox-add-read-dir 로도 열지 않는 것이 원칙입니다.

경계를 넓힐 때는 항상 '읽기'부터 고려하세요. /sandbox-add-read-dir 는 이름 그대로 읽기 권한을 더하는 명령입니다. 쓰기까지 함부로 넓히면, 에이전트가 실수로 작업 범위 밖의 파일을 덮어쓸 수 있습니다. '읽을 수만 있으면 되는 곳'과 '고쳐도 되는 곳'을 분리해 두는 것이 사고를 줄이는 기본기입니다.

샌드박스 우회를 임의로 시도하는 것은 가장 위험한 선택입니다. 막힌 작업을 빨리 끝내려고 경계 자체를 무력화하면, 그 순간부터 Codex가 멈춰 서던 모든 안전판이 함께 사라집니다. 막혔다면 경계를 통째로 걷어낼 게 아니라, 필요한 한 칸만 명시적으로 여는 것 — 이 차이가 안전과 사고를 가릅니다.

CI 통합과 멱등한 작업 설계

Codex를 사람의 터미널을 넘어 CI나 자동화 파이프라인에 끼워 넣으려면, 사고방식을 한 단계 바꿔야 합니다. 사람이 옆에서 멈춤을 보고 승인하던 안전망이 사라지기 때문입니다. 비대화식 환경에서는 '무엇을 허용하고 무엇을 막을지'를 사람이 미리 config로 못 박아 두어야 합니다 — 실행 중에 물어볼 사람이 없으니까요.

그래서 자동화에 태우는 작업은 가능한 한 멱등하게(여러 번 돌려도 같은 결과가 되게) 설계하는 것이 좋습니다. '있으면 만들지 않고, 없으면 만든다' 같은 방식으로 짜 두면, 재시도가 사고로 번지지 않습니다. 반대로 '무조건 새로 생성' '무조건 덮어쓰기' 같은 작업은 파이프라인에서 두 번 돌면 곧장 문제가 됩니다.

비밀정보와 권한은 CI에서 특히 조심스럽습니다. 파이프라인 로그는 여러 사람이 보고 오래 남으므로, 에이전트가 출력한 내용에 토큰이나 키가 섞여 들어가지 않도록 샌드박스 경계를 보수적으로 잡아야 합니다. 자동화 환경의 권한은 '되도록 좁게, 작업이 끝나면 회수'가 기본입니다.

마지막으로, 자동화라고 해서 검토를 건너뛰지 마세요. CI에서 Codex가 만든 변경은 사람이 보는 PR로 모이게 설계하는 것이 안전합니다. 에이전트가 빠르게 일하더라도, 저장소에 무엇이 들어가는지를 최종 승인하는 단계에는 사람이 있어야 합니다. 자동화는 '사람을 빼는 것'이 아니라 '사람이 봐야 할 지점을 한곳으로 모으는 것'입니다.

토큰과 비용, 컨텍스트를 가볍게 유지하기

에이전트는 컨텍스트를 먹고 움직입니다. 대화가 길어질수록, 붙인 도구가 많을수록 모델이 매 턴 처리해야 할 양이 늘고, 그만큼 응답은 느려지고 비용은 올라갑니다. Codex를 오래 쓰다 보면 '왜 점점 느려지고 답이 흐려지지'를 느끼게 되는데, 대개 컨텍스트가 비대해진 탓입니다.

사용량은 /usage 로 확인합니다. 지금 얼마나 쓰고 있는지를 눈으로 보면, 막연한 불안 대신 구체적인 관리가 가능해집니다. 작업이 한 단락 끝났을 때 사용량을 한 번 점검하고, 무겁다 싶으면 정리하는 리듬을 들이는 것이 좋습니다.

컨텍스트를 가볍게 유지하는 가장 쉬운 방법은 /compact 로 대화를 요약하는 것입니다. 한 작업이 끝났는데 다음 작업이 앞 맥락을 꼭 필요로 하지 않는다면, 깔끔하게 새 세션(/new)으로 시작하는 것도 방법입니다. 긴 한 세션을 끝없이 끌고 다니기보다, 작업 단위로 끊고 압축하는 편이 속도·비용·정확도 모두에 유리합니다.

도구와 메모리도 비용입니다. 안 쓰는 MCP 서버를 붙여 두면 그만큼 컨텍스트가 무거워지고, 부풀어 오른 AGENTS.md는 매 세션 32KiB 한도를 잡아먹습니다. '필요한 것만 연결하고, 핵심만 적는다'는 절제가 결국 가장 효과적인 비용 관리입니다. 비용을 줄이는 비결은 비싼 작업을 피하는 게 아니라, 매 순간 컨텍스트를 군더더기 없이 유지하는 데 있습니다.

설치·로그인이 안 풀릴 때

가장 흔한 첫 벽은 'codex: command not found'입니다. npm으로 깔았다면 nvm이나 전역 npm bin 경로가 PATH에 없는 경우가 많습니다. 터미널을 새로 열어도 안 되면, curl이나 Homebrew로 받는 네이티브 바이너리 방식으로 바꾸면 PATH 문제에서 자유로워집니다.

로그인이 꼬이는 대표 사례는 인증 전환입니다. ChatGPT 구독으로 로그인된 상태에서는 API 키로 바꾸려 해도 막히는 경우가 있습니다. 이때는 키 설정을 의심하기 전에 먼저 로그아웃하고 원하는 방식으로 다시 인증하세요. 캐시된 자격증명은 CLI와 IDE 확장이 공유하므로, 한쪽에서 로그아웃하면 양쪽이 함께 풀립니다.

지금 어떤 모델·권한·샌드박스에 있는지 헷갈리면 /status 가 먼저입니다. 작업 디렉터리, 권한 모드, 샌드박스 경계, 토큰 사용량을 한 화면에 보여 줍니다. 무엇이 잘못됐는지 모를 때, 현황부터 보는 것이 헤매지 않는 길입니다.

정리하면 첫날 문제는 거의 셋 안에 있습니다 — PATH(설치 경로), 인증 충돌(로그아웃 후 재로그인), 그리고 '지금 내가 어디 있는지' 모름(/status). 이 셋만 먼저 보면 대부분 풀립니다.

자꾸 멈추거나 거부될 때

Codex가 작업 앞에서 멈추고 거부하는 건 대개 정상입니다(2장). 샌드박스 경계나 승인 정책에 걸린 것이니, 그 작업이 정말 안전하고 의도한 것이라면 /approve 로 한 번 재시도시키면 됩니다. 멈춤은 버그가 아니라 설계된 안전핀입니다.

같은 작업에서 /approve 를 반복하게 된다면, 그건 권한이 너무 좁다는 신호입니다. /permissions 로 모드를 올리거나, 실행 시 --sandbox workspace-write 로 작업 폴더 쓰기를 열어 흐름을 매끄럽게 만드세요. 저장소 밖의 파일을 읽어야 한다면 경계를 통째로 풀지 말고 /sandbox-add-read-dir 로 필요한 디렉터리 한 칸만 엽니다.

반대로, 멈춤 없이 위험한 일이 그냥 일어난다면 권한이 너무 넓은 것입니다. 모든 안전장치를 끄는 --yolo 로 돌리고 있지는 않은지 확인하세요. /approve 의 빈도는 권한 다이얼을 어디에 맞춰야 할지 알려 주는 계기판입니다 — 너무 잦으면 좁은 것이고, 전혀 없는데 불안하면 넓은 것입니다.

엉뚱한 파일을 건드린다면 /mention 으로 작업 대상을 명확히 짚어 주고, 큰 변경은 /plan 으로 계획을 먼저 받아 어디를 손댈 작정인지 확인하세요. 범위를 좁혀 주는 것만으로 '엉뚱한 곳을 고치는' 사고의 대부분이 사라집니다.

느리거나 한도에 부딪힐 때

세션이 느려지고 답이 흐려진다면 거의 컨텍스트 과포화 신호입니다(4장). /compact 로 대화를 요약해 여유를 만들고, 다음 작업이 앞 맥락을 안 쓰면 /new 로 깔끔하게 새 세션을 여세요. 느려졌다고 더 강한 모델로 올리는 건 대개 정반대 처방입니다.

ChatGPT 요금제로 쓰다 한도(메시지 창)에 부딪히면, 창이 리셋될 때까지 기다리거나 /model 로 더 가벼운 모델로 내려 한도를 아끼는 방법이 있습니다. 사용량이 꾸준히 한도를 넘는다면 상위 요금제로 올리거나, 사용량이 들쭉날쭉하다면 API 키 방식으로 바꾸는 편이 합리적입니다.

사용량과 한도는 /usage 와 /status 로 확인합니다. 막연히 '왜 안 되지' 하기 전에, 지금 얼마나 썼고 언제 리셋되는지를 눈으로 보는 것이 먼저입니다. 비용은 모델 가격보다 '무거운 컨텍스트를 오래 끌고 다니는' 데서 더 많이 새어 나갑니다.

안 쓰는 MCP 서버나 부풀어 오른 AGENTS.md도 비용입니다(4장). 매 세션 컨텍스트를 잡아먹으니, 필요한 것만 연결하고 핵심만 적는 절제가 결국 가장 효과적인 속도·비용 관리입니다.

복구하고, 신고하기

세션을 실수로 닫았어도 작업이 사라지진 않습니다. 'codex resume'(대화형 선택), 'codex resume --last'(가장 최근), 'codex resume <세션ID>'로 지난 세션을 이어갈 수 있습니다. 한 가지 주의 — 이것은 세션 안 슬래시 명령이 아니라 셸에서 치는 CLI 서브커맨드입니다.

도구 자체의 버그로 보이면 공식 GitHub 저장소(github.com/openai/codex)의 이슈로 신고합니다. 재현 방법과 /status 에 나온 버전·환경 정보를 함께 적으면 처리가 빠릅니다. 내 설정 문제인지 도구 문제인지 헷갈릴 때는 역시 /status 로 먼저 가른 뒤 신고하는 편이 낫습니다.

복구가 잦다면 습관을 점검할 때입니다. 큰 작업을 /plan→실행→/diff 의 작은 루프로 쪼개고 중간중간 변경을 확인하면, 애초에 크게 되돌릴 일이 줄어듭니다(3장). 사고는 늘 '확인하지 않은 한 번'에서 납니다.

마지막으로, 이 장의 문제 절반은 1·2장을 건너뛴 결과입니다. 지침(AGENTS.md)과 권한·샌드박스를 먼저 갖춰 두면 막힐 일 자체가 크게 줄어듭니다. 막힐 때 펴보는 장이지만, 진짜 처방은 앞 장에 있는 셈입니다.