Codex CLI 설치와 사용법: 첫 작업부터 팀 공통 설정까지

프로젝트를 실행할 수 있고 Codex에 접근 가능한 계정도 있다는 전제에서, 처음 15분을 초기 설정에 배정합니다. 설치나 로그인, 느린 테스트 스위트 때문에 더 오래 걸릴 수도 있습니다. 첫 작업의 목표는 검증을 마친 작은 변경 사항을 만들거나, 작업을 막는 원인을 정확히 설명하는 것입니다. 이 글의 명령어는 2026년 10월 11일에 확인했습니다.

Codex CLI 설치 후 첫 작업까지 마치는 방법

Codex는 프로젝트 안에서 파일을 살펴보고 수정하며, 컴퓨터에 설치된 툴을 실행할 수 있습니다. 별도의 작업대에서 일하는 동료라고 생각하면 이해하기 쉽습니다. 할 일과 작업 범위는 사람이 정하고, 결과를 제품에 반영할지도 사람이 판단합니다. OpenAI CLI 가이드

0~3분: 설치 방법 하나 선택하기

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"

위 방법은 현재 CLI 문서와 공식 저장소에 안내된 설치 경로입니다. Codex를 시작하기 전에 터미널에서 프로젝트 디렉터리로 이동합니다.

3~5분: ChatGPT 로그인과 API 키 중 선택하기

처음 대화형 세션을 시작할 때는 요금제와 워크스페이스에서 접근을 허용한다면 ChatGPT 로그인을 사용합니다. codex login을 실행하고 브라우저 안내에 따라 로그인합니다. 로그인하지 않은 상태에서 codex를 시작해도 ChatGPT로 로그인 옵션이 표시됩니다.

프로그래밍 방식의 워크플로 등 OpenAI Platform 계정을 사용하려는 경우에는 API 키 인증을 선택합니다. 셸 환경에 OPENAI_API_KEY가 이미 설정되어 있다면, 문서에 안내된 macOS/Linux 명령어는 printenv OPENAI_API_KEY | codex login --with-api-key입니다. 키를 저장소 파일에 넣지 않도록 합니다.

codex login status로 현재 인증 방식을 확인합니다. 팀에서는 이 구분이 중요합니다. ChatGPT 인증에는 ChatGPT 워크스페이스의 제어 정책이 적용되고, API 인증에는 API 조직의 제어 정책이 적용되기 때문입니다. 인증 가이드

비용: ChatGPT 로그인은 해당 요금제에 포함된 이용 권한을 사용합니다. API 키를 통한 사용량은 OpenAI Platform에서 API 요율에 따라 별도로 청구됩니다. 요금제 비교는 Codex 요금 가이드를 참고합니다. 팀에서 시험 도입할 때는 사람이 직접 처리하는 데 걸리는 시간과 프롬프트 작성·검토·수정에 드는 시간을 비교합니다. 그런 다음 실제로 절약한 시간의 가치에서 추가 사용 비용을 뺍니다. 초안이 빨리 나와도, 최종적으로 수용하기까지 드는 전체 작업량이 줄어야 이득입니다. OpenAI의 인증 방식과 과금 구분

5~8분: 수정하기 전에 먼저 살펴보기

먼저 Git으로 복구 지점을 만듭니다. 프로젝트의 셸 프롬프트에서 문서에 안내된 codex --sandbox read-only --ask-for-approval on-request 명령어를 실행해 코드를 살펴보는 세션을 시작합니다.

조사할 범위를 좁혀서 요청합니다. 예를 들어 다음 프롬프트를 프로젝트에 맞게 바꿔 사용할 수 있습니다.

이 프롬프트는 작업 방식의 예시이며, Codex 전용 명령어가 아닙니다. 답변을 읽고 애플리케이션에서 올바른 부분을 찾았는지 확인합니다. 읽기 전용 샌드박스에서는 허용된 범위 안에서 내용을 살펴보고 명령어를 실행할 수 있습니다. 그 범위를 벗어나는 작업에는 승인이 필요할 수 있습니다. 승인 및 샌드박스 가이드

8~12분: 작은 변경 하나 허용하기

수정할 준비가 되면 /permissions로 워크스페이스 편집을 허용합니다. 새 세션을 시작한다면 문서에 안내된 조합인 codex --sandbox workspace-write --ask-for-approval on-request를 사용합니다.

이어서 완료 조건을 제시합니다.

결과를 빠르게 판단할 수 있는 일부터 시작합니다. 첫 과제로는 아키텍처를 개선하라는 포괄적인 요청보다, 이미 알고 있는 동작을 검증하는 테스트가 적합합니다.

12~15분: 변경 내역과 검증 결과 확인하기

/diff로 패치를 살펴보고 /review로 리뷰를 요청합니다. 실제 테스트 출력, 수정한 파일, 완료 조건 충족 여부를 확인합니다. 직접 검토한 다음에만 커밋합니다. 이 슬래시 명령어는 셸 프롬프트가 아니라 Codex 세션 안에서 실행합니다. CLI 명령어 레퍼런스

비교 기준을 잡은 뒤 모델 선택하기

먼저 세션에서 사용할 수 있는 모델로 시작합니다. 이후 /model로 다른 모델을 선택하거나 추론 강도를 조정합니다. OpenAI가 현재 제시하는 실행 예시는 codex --model gpt-6.1-sol입니다.

현재 권장 모델은 계정과 클라이언트에서 접근할 수 있다는 전제하에 복잡한 코딩에는 GPT-6.1 Sol, 범위가 명확하고 반복적인 작업에는 GPT-6 Luna입니다. 추론 강도를 높이면 어려운 분석에 도움이 될 수 있지만, 시간과 토큰도 더 많이 사용합니다. 결과를 비교할 때는 첫 과제와 추론 강도 설정을 동일하게 유지합니다. Codex 모델 가이드

팀 온보딩 과정에서는 작업 내용, 테스트 결과와 함께 사용한 모델도 기록합니다. 모델 이름을 선택한다고 해서 계정에 해당 모델의 이용 권한이 생기지는 않습니다.

샌드박스 접근 범위와 승인 정책은 별도로 설정하기

샌드박스는 명령어가 어디까지 접근할 수 있는지를 정합니다. 승인 정책은 Codex가 어떤 작업을 하기 전에 허락을 받아야 하는지를 정합니다. 샌드박스가 작업실의 벽이라면, 승인 정책은 문을 열어도 되는지 판단하는 규칙입니다.

대화형 작업에는 on-request를 사용합니다. 샌드박스 안에서 허용된 작업은 진행할 수 있고, 더 넓은 접근 권한이 필요한 작업에서는 승인 요청이 표시될 수 있습니다. never는 Codex가 승인을 요청할 수 없다는 뜻이며, 샌드박스를 해제한다는 뜻은 아닙니다. 차단된 작업은 계속 차단될 수 있습니다.

쓰기 가능 범위를 정했다고 해서 수정할 때마다 승인을 요청하는 것은 아닙니다. workspace-write와 on-request를 함께 사용하면 Codex는 워크스페이스 파일을 변경하고 허용된 명령어를 자동으로 실행할 수 있습니다. /permissions로 현재 설정을 확인합니다. OpenAI의 샌드박스 및 승인 동작

기존 팀 템플릿에 approval_policy = "untrusted"가 있다면 수정합니다. OpenAI는 이 명시적 설정을 폐지했으며, 해당 설정이 있으면 시작되지 않을 수 있다고 안내합니다. 이전 방식인 codex exec --full-auto도 더 이상 권장되지 않습니다. 대신 문서에 안내된 샌드박스와 승인 설정을 사용합니다. 현재 마이그레이션 가이드

AGENTS.md에 팀의 작업 규칙 정리하기

AGENTS.md를 활용하면 저장소의 작업 방식을 매번 설명할 필요가 줄어듭니다. Codex는 실행을 시작할 때 이 지침을 읽습니다. /init으로 기본 틀을 생성할 수 있으며, 팀에서 사용하기 전에 관리자가 내용을 다듬어야 합니다.

실용적인 저장소 지침은 다음 네 가지 질문에 답합니다.

• 개발자는 의존성을 어떻게 설치하고 프로젝트를 어떻게 실행합니까?
• 변경 사항에 어떤 테스트와 검사를 적용해야 합니까?
• 자동 생성 파일이 있거나 특별히 주의해야 하는 디렉터리는 어디입니까?
• 작업 완료 보고에는 변경된 동작, 실행한 테스트, 해결하지 못한 실패 등 어떤 내용을 담아야 합니까?

추상적인 바람을 나열하기보다 실제 명령어와 팀의 규칙을 적습니다. 개인 선호 사항은 ~/.codex/AGENTS.md에 두고, 함께 사용하는 저장소 지침은 프로젝트 루트에 커밋합니다.

Codex는 전역 지침을 읽은 뒤 프로젝트 루트에서 현재 디렉터리까지 내려오며 지침을 불러옵니다. 현재 위치에 더 가까운 지침이 앞서 읽은 지침보다 우선하며, 같은 디렉터리에서는 AGENTS.override.md가 AGENTS.md보다 우선합니다. 지침을 바꾼 뒤에는 세션을 다시 시작하고, Codex에 불러온 지침을 요약해 달라고 요청합니다. AGENTS.md 탐색 규칙

이 파일은 기여자를 위한 작업 안내서로 사용합니다. 기술적으로 강제할 제한은 구성 설정과 관리되는 필수 정책으로 적용합니다.

config.toml은 간결하고 검토하기 쉽게 유지하기

개인 기본값은 ~/.codex/config.toml에 저장합니다. 팀이 공유할 프로젝트 기본값은 .codex/config.toml에 두며, Codex는 신뢰할 수 있는 프로젝트에서만 이 파일을 읽습니다. 설정에는 이름과 값을 기록하는 텍스트 형식인 TOML을 사용합니다.

다음 시작용 설정은 OpenAI 구성 가이드에 나온 값을 조합한 것입니다. 해당 모델을 계정에서 사용할 수 있을 때만 모델 설정 줄을 포함합니다.

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

CLI 플래그와 --config로 지정한 재정의 값은 프로젝트 설정보다 우선합니다. 신뢰할 수 있는 프로젝트의 설정은 선택한 프로필과 사용자 기본값보다 우선합니다. 조직의 필수 정책은 이런 기본값과 관계없이 허용 범위를 제한할 수 있습니다. 구성 설정의 기초

web_search = "cached"는 캐시된 웹 검색 결과를 사용하도록 지정합니다. 이는 셸 명령어의 네트워크 접근과 별개입니다. Codex에 웹 검색 툴이 있어도 의존성을 다운로드하려면 승인이 필요할 수 있습니다. 명령어가 실패할 때마다 권한을 넓히기보다, 이 차이를 온보딩 문서에 명시합니다.

MCP 서버는 구체적인 필요가 있을 때 추가하기

MCP(Model Context Protocol)는 Codex를 툴과 외부 컨텍스트에 연결합니다. 로컬 서버는 프로세스로 실행되고, 원격 서버에는 HTTP 주소로 접속합니다. 저장소만으로는 제공할 수 없는 정보나 작업이 필요할 때 추가합니다.

OpenAI 문서의 예시는 codex mcp add context7 -- npx -y @upstash/context7-mcp입니다. 이 명령어는 npx로 문서 서버를 실행하므로, 해당 실행 도구를 사용할 수 있어야 합니다. codex mcp list로 설정된 서버를 확인하고, 세션 안에서 /mcp로 활성 연결을 살펴봅니다. OAuth를 지원하는 서버에는 codex mcp login <server-name>을 사용하되, 자리표시자를 설정된 서버 이름으로 바꿉니다.

서버 설정은 동일한 TOML 구성 체계의 [mcp_servers.<server-name>] 아래에 둡니다. 팀은 enabled_tools와 disabled_tools로 노출할 툴을 제한할 수 있습니다. 허용 목록을 적용한 뒤 차단 목록을 적용합니다. 작업에 필요한 최소한의 툴부터 시작합니다. MCP 연결 및 설정

툴 응답이 너무 큰 문제는 Codex CLI MCP 출력 제한 해설을 참고합니다. 서버를 연결하는 것과 서버가 반환하는 출력량을 조절하는 것은 별개의 설정 문제입니다.

작업별로 체크아웃을 분리해야 할 때 워크트리 사용하기

Git 워크트리는 작업에 독립된 저장소 체크아웃을 제공합니다. 실험 중인 수정 사항을 현재 작업 중인 파일과 분리하고 싶을 때 유용합니다.

OpenAI의 0.154.0 릴리스에는 CLI 작업, 대화형 세션, 포크를 위한 관리형 워크트리가 추가됐습니다. 구현상 실험적 기능인 worktrees를 켜야 하며 로컬 세션에서만 사용할 수 있습니다. 문서에 안내된 CLI 기능 활성화 명령어에 따라 codex features enable worktrees로 해당 기능을 켠 뒤, codex --worktree로 시작합니다. 릴리스 노트, 대화형 워크트리 구현, 기능 제어 명령어

지원되는 세션 안에서 /worktree를 사용하면 관리형 체크아웃에서 새 대화를 시작하거나 기존 대화를 포크할 수 있습니다. 포크는 대화 기록을 가져오고, 새 대화는 기록 없이 시작합니다. 이 옵션을 사용하려면 기능이 활성화되어 있어야 하고 로컬 Git 저장소가 있어야 합니다. 워크트리 세션 명령어

결과 검토, 통합, 정리는 직접 수행할 계획을 세웁니다. CLI 구현에서는 관리형 체크아웃의 자동 정리가 비활성화되어 있습니다. 별도 체크아웃을 만든다고 해서 샌드박스 설정이나 병합 검토가 필요 없어지는 것도 아닙니다. 관리형 체크아웃 수명 주기

병렬 작업을 시작할 준비가 되면 Codex CLI 워크트리 가이드를 참고합니다. 첫 테스트 작성 과제에는 체크아웃 하나면 충분합니다.

소규모 팀이 먼저 맡겨 볼 만한 작업 6가지

다음은 작업 제안이며, 생산성 향상을 실측했다는 뜻은 아닙니다. 완료 조건을 가장 쉽게 확인할 수 있는 일부터 시작합니다.

Codex가 빠진 제품 결정을 대신 내려 주거나, 테스트 스위트를 통과했다는 이유만으로 모든 위험을 검증했다고 입증해 주지는 않습니다. 완료 기준을 정하고 결과를 검토하는 일은 여전히 사람의 몫입니다. 더 넓은 관점의 평가는 Codex 리뷰를, 도입을 위한 비교는 Codex와 Claude Code 비교를 참고합니다.

기술 창업자가 만들어 볼 만한 툴 두 가지

더 유망한 기회는 특정 기술 스택에 집중한 회귀 테스트 서비스입니다. 알려진 버그가 있고 테스트 커버리지가 부족한 소규모 팀에 검토를 마친 테스트 패치를 판매합니다. 최소한으로 쓸모 있는 버전은 재현 가능한 사례를 입력받아 별도 체크아웃에서 범위를 한정한 Codex 작업을 실행하고, 패치와 테스트 검증 결과를 반환합니다. 2026년 10월 11일에 조회한 DataForSEO의 미국 키워드 추정치는 “automated software testing services”의 월간 검색량 880회입니다. 이는 해당 업무에 대한 관심을 보여 주며, 이 제품에 돈을 지불할 의향을 뜻하지는 않습니다. 어려운 부분은 신뢰할 수 있는 픽스처와 의미 있는 검증 조건입니다. 구현을 그대로 되풀이하는 테스트는 가치가 크지 않습니다.

두 번째 선택지는 특정 저장소에 맞춘 리뷰 어시스턴트입니다. 엔지니어링 리드는 팀의 문서화된 규칙을 적용하고, 간결하면서 검증 가능한 지적 사항 목록을 돌려주는 리뷰에 비용을 지불할 수 있습니다. 저장소 하나, 그 저장소의 AGENTS.md, 반복 가능한 리뷰 실행 절차부터 시작합니다. 같은 수요 조사에서 추정한 “ai code review”의 미국 월간 검색량은 1,300회입니다. 관건은 차별화입니다. Codex가 이미 코드 리뷰를 수행하므로, 제품은 관련성 높은 지적을 늘리고 오탐을 줄여야 합니다. 테스트 생성은 구매자가 결과물을 직접 살펴보고 실행할 수 있어, 초기 납품물이 더 명확합니다.

Codex 사용법과 초기 설정에서 자주 묻는 질문

월요일에는 관리자 한 명이 팀원 두 명과 같은 작은 과제를 실행해 봅니다. 검토와 수정에 들인 노력을 기록하고, 결과를 인계하는 과정에서 문제가 생긴 부분은 공통 지침을 고칩니다. 팀이 이 과정을 자신 있게 반복할 수 있게 된 뒤에 범위를 넓힙니다.

이런 제어 방식을 바탕으로 저장소 워크플로를 구축하고 싶다면, AI 프로덕션 시스템 구축 서비스를 확인합니다.