Codex CLI: OpenAI가 만든 터미널 코딩 에이전트

터미널에서 코딩 에이전트를 쓰는 분이라면 클로드 코드를 먼저 떠올리실 텐데요. OpenAI도 비슷한 도구를 내놓았습니다. 바로 Codex CLI입니다.

Codex CLI는 2025년 4월 16일 공개된 OpenAI의 코딩 에이전트로, 우리 컴퓨터에서 직접 실행되면서 코드를 읽고 고치고 명령을 실행합니다. 소스 코드가 Apache 2.0 라이선스로 공개되어 있고, ChatGPT 구독이 있으면 추가 비용 없이 쓸 수 있다는 점이 눈에 띄어요. 이번 글에서는 Codex CLI를 설치해서 쓰는 방법과 함께, 이 도구의 가장 큰 특징인 샌드박스(sandbox)가 실제로 무엇을 막는지 직접 확인해 보겠습니다. 🧪

Codex는 하나가 아니다

Codex라는 이름이 여러 곳에 쓰여서 처음에는 헷갈리기 쉽습니다. 2021년에 GitHub Copilot의 바탕이 됐던 OpenAI의 코드 생성 모델도 Codex였거든요. 지금 Codex라고 하면 보통 OpenAI의 코딩 에이전트 제품군을 가리키고, 쓰는 화면에 따라 다음과 같이 나뉩니다.

CLI, IDE 확장, 데스크톱 앱은 같은 에이전트를 바탕으로 하고, 화면만 다르다고 보면 됩니다. Codex CLI는 처음에 TypeScript로 만들어졌다가 지금은 Rust로 다시 작성되어, Node.js 없이도 실행되는 단일 실행 파일로 배포돼요.

설치와 로그인

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"

Homebrew를 쓴다면 Cask로 설치합니다.

brew install --cask codex

npm 패키지로도 배포됩니다.

bun add -g @openai/codex

npm을 쓴다면 다음과 같이 설치합니다.

npm install -g @openai/codex

설치가 끝나면 codex를 실행하고 “Sign in with ChatGPT”를 고릅니다. ChatGPT Plus, Pro, Business, Edu, Enterprise 요금제에는 Codex 사용량이 포함되어 있어서, 로그인만 하면 별도의 API 비용 없이 쓸 수 있어요. API 키로 쓰는 방법도 있지만, 이때는 토큰 단위로 따로 과금됩니다. 로그인 정보와 설정은 ~/.codex 폴더에 저장됩니다.

이미 설치해 두었다면 codex update로 최신 버전으로 올리면 됩니다. 설치 상태, 설정, 인증에 문제가 있는지 헷갈릴 때는 codex doctor로 한 번에 점검해 보세요.

기본 사용법

프로젝트 폴더에서 codex를 실행하면 대화형 화면이 열립니다.

cd /path/to/your/project
codex

여기서 “로그인 페이지의 유효성 검사를 고쳐줘”처럼 자연어로 요청하면 Codex가 파일을 읽고, 수정 계획을 세우고, 코드를 고치고, 테스트까지 실행합니다. 실행할 때 바로 요청을 넘길 수도 있어요.

codex "이 프로젝트의 구조를 설명해줘"

대화 중에는 /로 시작하는 슬래시 명령(slash command)도 씁니다. 자주 쓰는 것만 추리면 다음과 같아요.

• /model: 모델과 추론 강도(reasoning effort) 선택
• /permissions: 샌드박스와 승인 정책 변경
• /init: 프로젝트용 AGENTS.md 생성
• /review: 현재 변경 사항을 리뷰해서 문제 찾기
• /compact: 대화를 요약해서 컨텍스트 한도에 걸리지 않게 하기

이 밖에도 git diff를 보여 주는 /diff, 파일을 대화에 붙이는 /mention, 현재 설정과 토큰 사용량을 보여 주는 /status, 계획만 세우는 /plan 모드가 있습니다. /import로 클로드 코드의 설정과 최근 대화를 가져올 수도 있어서, 클로드 코드를 쓰다가 넘어오는 경우에도 편해요.

지난 대화는 codex resume으로 이어 가고, codex fork로 기존 대화에서 갈라진 새 세션을 만듭니다.

# 가장 최근 세션 이어 가기
codex resume --last

# 세션 목록에서 골라 이어 가기
codex resume

샌드박스와 승인 정책

Codex CLI를 다른 코딩 에이전트와 구분 짓는 가장 큰 특징은 운영체제 수준의 샌드박스입니다. 에이전트가 실행하는 셸 명령을 macOS에서는 Seatbelt, Linux에서도 커널의 샌드박스 기능으로 가둬서, 명령 자체가 허용된 범위 밖을 건드리지 못하게 막아요. “이 명령을 실행해도 될까요?”라고 묻는 것만으로 안전을 지키는 게 아니라, 실수로 허락하더라도 운영체제가 한 번 더 막아 주는 구조죠.

샌드박스 모드(sandbox mode)는 세 가지입니다.

정말 이렇게 동작하는지 궁금해서 codex sandbox 명령으로 직접 확인해 봤습니다. codex sandbox는 로그인 없이도 임의의 명령을 Codex의 샌드박스 안에서 실행해 볼 수 있는 디버깅용 명령이에요. 먼저 read-only에서 작업 폴더에 파일을 써 봤습니다.

codex sandbox -c 'sandbox_mode="read-only"' -- sh -c 'echo a > inside.txt'

sh: inside.txt: Operation not permitted

read-only에서는 작업 폴더에도 쓸 수 없고, 같은 모드에서 보낸 네트워크 요청도 실패했습니다. 이번에는 workspace-write로 작업 폴더, 홈 폴더 아래의 다른 폴더(~/Library/Caches/codex-sandbox-test), /tmp에 차례로 파일을 써 봤어요.

codex sandbox -c 'sandbox_mode="workspace-write"' -- sh -c '
  echo a > inside.txt && echo "작업 폴더 쓰기: 성공"
  echo b > ~/Library/Caches/codex-sandbox-test/outside.txt || echo "바깥 폴더 쓰기: 실패"
  echo c > /tmp/codex-tmp-test.txt && echo "/tmp 쓰기: 성공"
'

작업 폴더 쓰기: 성공
sh: /Users/dale/Library/Caches/codex-sandbox-test/outside.txt: Operation not permitted
바깥 폴더 쓰기: 실패
/tmp 쓰기: 성공

작업 폴더와 /tmp에는 쓸 수 있지만 그 밖의 폴더는 운영체제가 막습니다. 네트워크 요청은 workspace-write에서도 여전히 실패했어요. 테스트 도중 패키지를 설치해야 해서 네트워크가 필요하다면 설정에서 따로 열어 줘야 합니다.

codex sandbox -c 'sandbox_mode="workspace-write"' -c 'sandbox_workspace_write.network_access=true' -- curl -s -o /dev/null -m 5 https://example.com

이렇게 network_access를 켜면 같은 요청이 성공합니다.

샌드박스와 함께 정하는 게 승인 정책(approval policy)인데요. on-request로 두면 샌드박스 밖의 작업이 필요할 때 모델이 판단해서 사용자에게 허락을 구하고, never로 두면 절대 묻지 않고 실패를 그대로 모델에게 돌려줍니다. 매번 답하기 번거롭다면 --approve-for-me를 붙여서 승인 요청을 자동 검토에 맡길 수도 있어요. 예전 글에서 자주 보이던 --full-auto는 최신 버전에서 제거됐으니 이 옵션으로 대신하면 됩니다.

평소에는 /permissions로 대화 중에 바꾸고, 기본값은 설정 파일에 적어 둡니다.

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

한 가지 주의할 옵션이 있습니다. --dangerously-bypass-approvals-and-sandbox(별칭 --yolo)는 샌드박스를 danger-full-access로, 승인 정책을 never로 한꺼번에 바꿔요. 이름 그대로 위험한 옵션이라 이미 컨테이너 같은 격리된 환경 안에서 돌릴 때만 쓰는 게 맞습니다. 클로드 코드의 권한 모드와 비교해 보면, 클로드 코드가 도구 단위로 허용 목록을 관리하는 쪽이라면 Codex는 운영체제 샌드박스로 범위를 긋는 쪽에 무게를 둔다는 차이가 보입니다.

AGENTS.md로 프로젝트 맥락 알려주기

Codex는 프로젝트의 규칙을 AGENTS.md 파일에서 읽습니다. 클로드 코드의 CLAUDE.md와 같은 역할인데, AGENTS.md는 Codex뿐 아니라 OpenCode, goose 같은 여러 에이전트가 함께 읽는 공통 형식이에요. 자세한 작성법은 AGENTS.md와 CLAUDE.md에서 다뤘습니다.

처음이라면 대화 중에 /init을 입력하면 Codex가 프로젝트를 훑어보고 AGENTS.md 초안을 만들어 줍니다. 모든 프로젝트에 공통으로 적용할 지침은 ~/.codex/AGENTS.md에 적어 두면 돼요.

MCP 서버 연결하기

MCP(Model Context Protocol) 서버도 연결됩니다. codex mcp add로 로컬에서 실행하는 서버를 등록하거나, --url로 원격 서버를 등록해요.

# 로컬 명령으로 실행하는 MCP 서버
codex mcp add github -- bunx @modelcontextprotocol/server-github

# 원격 MCP 서버
codex mcp add docs --url https://mcp.example.com/mcp

# 등록한 서버 확인
codex mcp list

등록한 서버는 ~/.codex/config.toml의 [mcp_servers] 아래에 저장되고, 대화 중에 /mcp를 입력하면 쓸 수 있는 도구 목록이 나옵니다.

codex exec으로 자동화하기

codex exec은 대화 화면 없이 작업을 맡기고 결과만 받아 오는 명령입니다. CI 파이프라인이나 셸 스크립트에 Codex를 끼워 넣을 때 씁니다.

codex exec "테스트를 실행하고 실패한 테스트를 고쳐줘"

비대화형으로 실행할 때는 사람이 승인해 줄 수 없으니 샌드박스를 더 신중하게 골라야 해요. 파일을 고치게 할 때는 --sandbox workspace-write로 쓰기 범위를 명시해 두는 게 안전합니다.

codex exec --sandbox workspace-write "린트 오류를 고쳐줘"

다른 프로그램이 결과를 읽어야 한다면 --json으로 진행 이벤트를 JSON Lines로 받거나, --output-schema에 JSON 스키마 파일을 넘겨서 최종 답변을 정해진 형식으로 받으면 됩니다. 코드 리뷰만 필요하다면 codex review로 현재 변경 사항을 바로 리뷰하게 할 수도 있어요. GitHub PR마다 리뷰를 받고 싶다면 Codex 코드 리뷰를 저장소에 연결하면 됩니다.

에디터에서 ACP로 쓰기

Codex는 IDE 확장으로 VS Code 계열 에디터를 공식 지원하지만, Zed나 JetBrains IDE 같은 다른 에디터에서도 쓰는 방법이 있습니다. 여기에는 에디터와 코딩 에이전트를 잇는 표준인 ACP(Agent Client Protocol)를 씁니다. Codex 자체는 ACP를 말하지 않기 때문에 @agentclientprotocol/codex-acp 어댑터가 중간에서 통역을 맡아요.

bun add -g @agentclientprotocol/codex-acp

어댑터 패키지 안에 호환되는 Codex가 함께 들어 있어서 따로 설치할 필요도 없습니다. Zed는 ACP 에이전트 레지스트리에서 Codex를 고르면 이 어댑터를 알아서 설치해 주고, goose에서는 codex-acp를 제공자로 지정해서 ChatGPT 구독으로 Codex를 불러다 쓸 수 있어요.

마치며

Codex CLI는 OpenAI가 만든 오픈소스 터미널 코딩 에이전트입니다. ChatGPT 구독으로 바로 쓸 수 있고, 운영체제 샌드박스로 에이전트가 건드릴 수 있는 범위를 명확하게 긋는다는 점이 가장 큰 특징이에요. AGENTS.md, MCP, ACP처럼 다른 에이전트와 공유하는 표준을 적극적으로 따르기 때문에, 클로드 코드나 OpenCode와 번갈아 쓰기에도 부담이 적습니다.

처음 써 본다면 workspace-write와 on-request 조합으로 작은 작업부터 맡겨 보세요. 더 자세한 내용은 Codex CLI GitHub 저장소를 참고하세요.