한 줄 요약

이 페이지에서 배우는 것

  • Local Environment가 무엇이고 왜 필요한지
  • Setup Script를 작성하는 방법 (코드 한 줄씩 설명)
  • .codex 폴더의 역할과 구조
  • 플랫폼(macOS, Windows, Linux)별 스크립트 차이
  • Actions(커스텀 버튼)를 만들어 반복 작업을 원클릭으로 실행하는 법
  • TypeScript, Python 등 실전 프로젝트에 바로 적용하는 시나리오
  • 자주 묻는 질문(FAQ) 5가지

Local Environment가 뭔가요?

새 컴퓨터를 샀다고 상상해보세요. 박스를 열고 전원을 켜면 바로 코딩을 할 수 있나요? 아닙니다. 먼저 프로그램을 설치하고, 설정을 맞추고, 필요한 파일을 다운로드해야 합니다.

Codex의 Worktree도 마찬가지입니다. Worktree는 여러분의 프로젝트를 새 폴더에 복사해서 작업하는 공간인데, 코드 파일만 복사될 뿐 "설치된 프로그램"이나 "빌드 결과물"은 따라오지 않습니다.

Local Environment는 바로 이 문제를 해결합니다. "새 작업 공간이 만들어질 때마다 이런 준비를 자동으로 해줘"라고 알려주는 설정 레시피입니다. 한 번만 만들어두면, Codex가 worktree를 생성할 때마다 알아서 환경을 세팅해줍니다.

프로젝트가 worktree에서 깨진다면, 대부분은 코드 문제가 아니라 환경 초기화가 빠진 경우입니다. Setup Script를 먼저 확인하세요!

Setup Script란?

Setup Script는 "자동 설치 레시피"입니다. 요리 레시피가 "1. 양파를 썬다, 2. 기름을 두른다, 3. 볶는다"처럼 순서대로 적혀있듯이, Setup Script에도 "1. 필요한 패키지를 설치한다, 2. 코드를 빌드한다, 3. 설정 파일을 복사한다"가 순서대로 적혀있습니다.

이 레시피가 있으면 어떤 장점이 있을까요?

  • 1 누구나 같은 환경을 만들 수 있습니다 — 신입 개발자가 와도, Codex AI가 작업해도, 동일한 환경이 보장됩니다
  • 2 실수가 줄어듭니다 — 사람이 직접 하면 한 단계를 빼먹을 수 있지만, 스크립트는 매번 정확히 같은 순서로 실행됩니다
  • 3 시간이 절약됩니다 — 클릭 한 번(또는 자동)으로 모든 준비가 끝납니다

Setup Script 워크플로

Setup Script를 만들고 사용하는 과정은 딱 4단계입니다.

1
Settings 열기
Codex 앱에서 메뉴 또는 Cmd + , (Mac) / Ctrl + , (Windows)를 눌러 Settings 화면에 들어갑니다.
2
Setup Script 작성
"이 프로젝트를 실행하려면 무엇이 필요한가?"를 생각하며, 필요한 명령어를 순서대로 적습니다. 예: 패키지 설치, 빌드, 환경 변수 복사 등
3
.codex 폴더에 저장
작성한 스크립트가 프로젝트 안의 .codex 폴더에 저장됩니다. 이 폴더를 Git에 커밋하면 팀원 모두가 같은 설정을 공유할 수 있습니다.
4
Worktree에서 자동 실행
이후 새 worktree(작업 스레드)를 만들 때마다, Codex가 이 스크립트를 자동으로 실행해서 환경을 준비합니다. 여러분이 직접 할 필요가 없습니다!
⚠️ 비공식 예시 안내. 공식 Local Environments 문서는 설정을 Codex 앱의 Settings UI에서 구성하고, 결과를 프로젝트 루트의 .codex 폴더에 저장한다고만 안내합니다 — 구체적인 파일명·포맷은 공식 문서에 명시되어 있지 않습니다. 이 페이지에 등장하는 setup.sh, setup-macos.sh, setup-windows.ps1, setup-linux.sh, actions.json는 모두 이해를 돕기 위한 비공식 예시이며, 실제 파일명은 Codex 버전과 Settings UI가 결정합니다. 본인 환경에서 정확한 파일명을 확인하려면 Codex 앱의 Settings → Local Environments에서 "Reveal in Finder/Explorer"로 확인하세요.

.codex 폴더란?

여러분의 프로젝트 폴더 안에는 보이지 않는 숨겨진 폴더들이 있습니다. Git을 사용하면 .git 폴더가 자동으로 생기는 것처럼, Codex를 사용하면 .codex 폴더가 생깁니다.

이 폴더 안에는 Codex가 참고하는 설정 파일들이 들어있습니다. 폴더 이름 앞에 점(.)이 붙으면 운영체제가 기본적으로 숨김 처리하기 때문에, 파일 탐색기에서 "숨김 파일 보기"를 켜야 보입니다.

.codex 디렉터리 구조 시각화
project-root/
.codex/
setup.sh ← 공통 셋업 스크립트 (모든 OS)
setup-macos.sh ← macOS 전용 스크립트
setup-windows.ps1 ← Windows 전용 스크립트
actions.json ← 커스텀 버튼(Actions) 정의

팁: .codex 폴더는 .gitignore에 넣지 마세요! Git에 커밋해야 팀원 모두가 같은 환경 설정을 사용할 수 있습니다.

예시 Setup Script (줄별 상세 설명)

아래는 Node.js 프로젝트에서 사용하는 기본적인 Setup Script입니다. 각 줄이 무엇을 하는지 하나씩 설명합니다.

#!/bin/bash # ^ "이 파일은 bash라는 프로그램으로 실행해주세요"라는 의미입니다. # 모든 셸 스크립트의 첫 줄에 적는 관례입니다. set -e # ^ "에러가 나면 즉시 멈춰라"라는 의미입니다. # 이게 없으면 에러가 나도 다음 줄로 넘어가서 # 문제를 발견하기 어려울 수 있습니다. npm install # ^ 프로젝트에 필요한 패키지(라이브러리)를 설치합니다. # package.json 파일에 적힌 목록을 보고 # 인터넷에서 자동으로 다운로드합니다. # (파이썬의 pip install과 비슷한 역할) npm run build # ^ 소스 코드를 "완성품"으로 변환합니다. # 예: TypeScript -> JavaScript 변환, # 여러 파일을 하나로 합치기 등 cp .env.example .env.local 2>/dev/null || true # ^ 환경 변수 파일(.env.example)을 # 실제 사용할 파일(.env.local)로 복사합니다. # "2>/dev/null || true" 부분은 # "파일이 없어도 에러 내지 말고 넘어가"라는 뜻입니다. echo "Setup complete!" # ^ 화면에 "Setup complete!" 메시지를 출력합니다. # 설정이 끝났다는 것을 확인하기 위한 용도입니다.

플랫폼별 Setup Script

팀원들이 서로 다른 운영체제(macOS, Windows, Linux)를 사용할 수 있습니다. 아래 표는 OS별 셋업 명령 예시이지만, OS별 자동 선택/공통 스크립트 동시 실행 같은 동작은 공식 문서에 명시되지 않았습니다 — 실제 파일명과 실행 순서는 Codex Settings UI에서 확인하세요.

플랫폼 스크립트 형식 실행 환경 예시 파일명 스크립트 내용 예시
macOS Shell (bash/zsh) Terminal setup-macos.sh brew install node
Windows PowerShell PowerShell / WSL setup-windows.ps1 winget install OpenJS.NodeJS.LTS
Linux Shell (bash) Terminal setup-linux.sh sudo apt install nodejs
한 번 더 알림: 위 표의 파일명(setup-macos.sh 등)은 비공식 예시입니다. 공식 문서는 OS별 자동 선택과 공통 스크립트 동시 실행 동작을 명시하지 않았으며, 실제 파일명·실행 순서는 Codex Settings UI가 결정합니다.

핵심 포인트

  • 1 설정은 앱 Settings에서 구성하며, .codex 폴더에 저장됩니다. Git에 커밋하면 팀 전체가 동일한 환경을 공유합니다.
  • 2 Setup Script는 새 worktree 스레드가 시작될 때 자동으로 실행됩니다. 사람이 기억하고 실행할 필요가 없습니다.
  • 3 macOS, Windows, Linux 각각에 맞는 전용 스크립트를 따로 만들 수 있습니다. 팀원의 OS가 달라도 문제없습니다.
  • 4 Actions를 정의하면 "개발 서버 시작", "테스트 실행" 같은 반복 작업을 버튼 하나로 빠르게 실행할 수 있습니다.

Actions이란?

웹 브라우저에서 자주 방문하는 사이트를 즐겨찾기(북마크)에 저장하듯이, 자주 사용하는 개발 명령어를 Actions에 등록할 수 있습니다.

공식 문서 기준 Actions의 핵심 동작은 다음과 같습니다.

  • Codex 앱의 top bar에 노출되어 어떤 화면에서도 한 번에 호출할 수 있습니다.
  • 실행은 Codex의 통합 터미널에서 이뤄지므로 출력/오류를 즉시 확인할 수 있습니다.
  • 각 Action을 등록할 때 아이콘 선택이 필수입니다(top bar에서 식별을 위해).

Actions는 .codex/actions.json 파일에 정의합니다. 아래는 예시입니다.

// .codex/actions.json // Actions는 JSON 형식으로 정의합니다. // 각 항목이 하나의 버튼이 됩니다. { "actions": [ { "name": "Dev Server", // ^ 버튼에 표시될 이름 "command": "npm run dev" // ^ 버튼을 누르면 실행될 명령어 }, { "name": "Test", "command": "npm test" // ^ 테스트 실행 버튼 }, { "name": "Lint", "command": "npm run lint" // ^ 코드 스타일 검사 버튼 } ] }

Actions 활용 예시

Dev Server
개발 서버를 한 번의 클릭으로 시작합니다. 코드를 수정하면 브라우저에서 바로 결과를 확인할 수 있습니다. 터미널에서 npm run dev를 직접 치는 것과 같습니다.
Test Run
작성한 코드가 제대로 작동하는지 자동으로 검사합니다. GitHub에 올리기(push) 전에 로컬에서 먼저 확인하면 실수를 줄일 수 있습니다.
Lint Check
코드의 띄어쓰기, 변수 이름 규칙 등 스타일을 검사합니다. 맞춤법 검사기처럼, 코드의 "문법"을 점검해줍니다. 커밋 전에 한 번 돌려보세요.

실전 시나리오

실제 프로젝트에서 Setup Script를 어떻게 작성하는지 3가지 시나리오를 살펴봅니다.

시나리오 1: TypeScript 프로젝트

TypeScript는 JavaScript에 "타입"을 추가한 언어입니다. 브라우저는 TypeScript를 직접 실행할 수 없으므로, JavaScript로 변환(빌드)하는 과정이 필요합니다.

#!/bin/bash set -e # TypeScript 프로젝트 Setup Script # 파일 위치: .codex/setup.sh # 1단계: 패키지 설치 # package.json에 적힌 라이브러리를 모두 다운로드합니다. # typescript, react, express 등이 여기서 설치됩니다. npm install # 2단계: TypeScript를 JavaScript로 변환 # tsconfig.json 설정에 따라 .ts 파일을 .js로 컴파일합니다. npx tsc --build # 3단계: 환경 변수 파일 복사 # API 키나 DB 주소 같은 비밀 정보를 담는 파일입니다. # .env.example은 "틀"이고, .env.local은 실제 사용 파일입니다. cp .env.example .env.local 2>/dev/null || true echo "TypeScript 프로젝트 준비 완료!"

시나리오 2: Python 프로젝트 (가상환경 포함)

Python 프로젝트에서는 가상환경(venv)을 사용하는 것이 일반적입니다. 가상환경이란, 프로젝트마다 별도의 "방"을 만들어서 패키지를 설치하는 것입니다. 이렇게 하면 프로젝트 A에서 쓰는 패키지 버전과 프로젝트 B에서 쓰는 버전이 충돌하지 않습니다.

#!/bin/bash set -e # Python 프로젝트 Setup Script # 파일 위치: .codex/setup.sh # 1단계: 가상환경 만들기 # "venv"라는 이름의 가상 공간을 생성합니다. # python3 -m venv = "Python의 venv 모듈을 사용해서" # .venv = "현재 폴더에 .venv라는 이름으로 만들어줘" python3 -m venv .venv # 2단계: 가상환경 활성화 # 이 줄 이후로 설치되는 패키지는 모두 .venv 안에만 들어갑니다. # source = "이 파일의 내용을 현재 셸에서 실행해줘" source .venv/bin/activate # 3단계: 패키지 설치 # requirements.txt에 적힌 패키지를 모두 설치합니다. # -r = "이 파일을 읽어서(read)" 라는 뜻입니다. pip install -r requirements.txt # 4단계: 데이터베이스 초기화 (Django 프로젝트인 경우) # 테이블 구조를 만들어줍니다. Django가 아니면 이 줄은 삭제하세요. # python manage.py migrate echo "Python 가상환경 준비 완료!"

시나리오 3: "테스트 실행" 버튼 만들기

테스트를 자주 실행하는 프로젝트라면, Actions에 등록해두면 편리합니다. 아래는 Python 프로젝트에서 pytest를 실행하는 Action 예시입니다.

// .codex/actions.json { "actions": [ { "name": "테스트 실행", // ^ Codex 상단 바에 "테스트 실행" 버튼이 나타남 "command": "source .venv/bin/activate && pytest -v" // ^ 가상환경을 켜고(&&) pytest를 실행 // -v는 verbose(자세히)의 약자로, // 어떤 테스트가 통과/실패했는지 하나씩 보여줍니다. }, { "name": "서버 시작", "command": "source .venv/bin/activate && python manage.py runserver" // ^ Django 개발 서버를 시작합니다. } ] }

실전 팁

처음엔 간단하게 시작하세요
처음부터 완벽한 스크립트를 만들려고 하지 마세요. npm install 한 줄로 시작해서, 필요할 때 하나씩 추가하면 됩니다.
Actions 이름은 짧고 명확하게
Actions는 팀 공용 버튼처럼 쓰이므로 이름을 짧게 두는 편이 좋습니다. 예: "Dev", "Test", "Lint", "Build"
에러 메시지를 잘 읽으세요
스크립트가 실패하면 에러 메시지가 나옵니다. 대부분 "이 프로그램이 설치되지 않았습니다" 또는 "이 파일을 찾을 수 없습니다" 같은 내용이니, 메시지를 읽고 해당 부분을 수정하면 됩니다.
worktree에서 코드가 실행되지 않거나 빌드가 실패한다면, 코드 자체의 문제보다 환경 초기화가 빠진 경우가 대부분입니다. setup script에 의존성 설치와 빌드 단계가 포함되어 있는지 먼저 확인하세요.

자주 묻는 질문 (FAQ)

Q: Setup Script를 안 만들면 어떻게 되나요?

A: Codex는 worktree(새 작업 공간)를 만들 때 코드 파일만 복사합니다. Setup Script가 없으면 패키지 설치, 빌드 등이 안 된 상태로 작업이 시작됩니다. 간단한 프로젝트(HTML/CSS만 있는 경우 등)는 괜찮을 수 있지만, Node.js나 Python 프로젝트처럼 패키지 설치가 필요한 경우에는 "모듈을 찾을 수 없습니다(Module not found)" 같은 에러가 발생합니다.

Q: 팀원이 만든 setup script를 내가 수정할 수 있나요?

A: 네, 가능합니다! Setup Script는 일반 파일이므로 누구나 수정할 수 있습니다. .codex/setup.sh 파일을 텍스트 에디터로 열어서 수정한 뒤, Git에 커밋하면 됩니다. 다만 팀 프로젝트에서는 수정 전에 팀원과 상의하는 것이 좋습니다. 모든 사람의 환경에 영향을 주기 때문입니다.

Q: Setup Script가 실패하면 어떻게 되나요?

A: set -e가 스크립트 상단에 있으면, 에러가 발생한 시점에서 스크립트가 멈춥니다. Codex가 에러 메시지를 보여주므로, 해당 메시지를 읽고 문제를 수정하면 됩니다. 흔한 원인: Node.js나 Python이 설치되지 않음, 인터넷 연결 문제, 파일 경로 오타 등. 수정 후 worktree를 다시 만들면 스크립트가 다시 실행됩니다.

참고: set -e는 본 가이드의 권고이지 Codex의 공식 요구사항이 아닙니다. Cloud 환경에서는 npm registry 일시 장애 같은 transient 실패까지 차단되는 트레이드오프가 있어, best-effort 실행 + 로깅을 선호하는 팀도 있습니다.

Q: Actions와 Setup Script의 차이는 무엇인가요?

A: 두 가지의 역할이 다릅니다.

  • Setup Script = 환경 준비. worktree가 만들어질 때 자동으로 한 번 실행됩니다. (예: 패키지 설치, 빌드)
  • Actions = 개발 중 반복 사용. 버튼을 누를 때마다 수동으로 실행됩니다. (예: 테스트 실행, 서버 시작)

비유하면, Setup Script는 "이사할 때 가구 배치하기"이고, Actions는 "매일 아침 커피 내리기"입니다.

Q: Node.js가 뭔가요? 꼭 설치해야 하나요?

A: Node.js는 JavaScript를 컴퓨터에서 실행할 수 있게 해주는 프로그램입니다. 웹 브라우저 없이도 JavaScript 코드를 돌릴 수 있게 됩니다. npm은 Node.js에 포함된 패키지 관리자입니다. 여러분의 프로젝트가 JavaScript/TypeScript 기반이라면 반드시 필요합니다. Python 프로젝트라면 Node.js 대신 Python이 설치되어 있으면 됩니다. 프로젝트에서 사용하는 언어에 맞는 실행 환경만 설치하면 됩니다.

참고: Codex Cloud 환경

본 페이지는 로컬 환경(Local Environments)을 다루지만, 동일한 개념이 Codex Cloud(chatgpt.com/codex) 환경에도 적용됩니다. 클라우드 환경의 핵심 차이는 다음과 같습니다.

  • Setup vs Maintenance Script 분리 — 컨테이너를 처음 만들 때 한 번 실행되는 Setup과, 캐시된 컨테이너가 오래되었을 때 보강용으로 실행되는 Maintenance Script가 따로 존재합니다.
  • Secrets vs 환경 변수 — Secrets는 암호화 저장되며 설치 단계 후 컨테이너에서 제거됩니다. 일반 환경 변수는 에이전트 단계까지 유지됩니다. 주의: 설치 스크립트가 secret 값을 일반 env var나 파일에 복사하면 에이전트 단계에서도 접근 가능해져 의도한 격리가 깨질 수 있습니다.
  • 인터넷 접근 디폴트 — 설치 단계에는 인터넷이 허용되지만, 에이전트 단계는 기본적으로 격리됩니다(공식: "Internet connectivity is enabled during setup but restricted during the agent phase by default — configurable based on your needs"). 필요하면 환경 설정에서 명시적으로 허용해야 합니다.
  • 컨테이너 캐시 12시간 — 동일 환경의 컨테이너는 최대 12시간 재사용되어 setup 시간을 절약합니다. 만료되면 새 컨테이너로 재구축됩니다.
  • 기본 베이스 이미지 — 공식 "universal" 컨테이너 이미지가 사용되며 일반적인 언어/툴체인이 사전 설치되어 있습니다(정확한 Docker handle은 공식 Cloud Environments 문서 참조).

자동 코드 리뷰: codex review

앱의 Review Pane 외에 CLI에도 codex review 서브커맨드가 있어 커밋 전에 변경 사항을 자동 점검할 수 있습니다. 동일한 명령을 CI에서 실행하면 PR 워크플로 일부로 통합 가능.

  • 기본 사용codex review는 현재 working tree와 base ref(보통 main) 사이의 diff를 분석합니다. base ref는 codex review main..HEAD처럼 명시적으로 줄 수도 있습니다.
  • JSON 출력codex review --json로 리뷰 결과를 구조화된 JSON으로 받아 후처리할 수 있습니다(이슈별 severity, 파일·라인 위치 포함).
  • CI 통합 — GitHub Actions에서 codex exec로 비대화형 실행 후 --json 결과를 PR 코멘트로 게시할 수 있습니다. exit code로 차단 정책을 결정.

앱 리뷰 워크플로는 Review Pane 가이드를 참고하세요. 정확한 플래그 목록은 codex review --help 또는 공식 CLI 문서를 확인하세요.

Remote Connections — 모바일·다른 Mac·SSH 호스트에서 Codex 사용

공식 Remote Connections는 인증된 ChatGPT 디바이스 간에 안전한 relay 계층을 만들어, 떨어진 곳에서도 Codex 호스트를 그대로 사용하게 합니다. 3가지 시나리오를 지원하며 모두 알파 기능이라 명시적 활성화가 필요합니다.

  • Feature flag 활성화~/.codex/config.toml[features]
    remote_connections = true
    추가 (모든 시나리오 공통).
① Mobile → Codex App Host
Codex가 켜진 Mac을 휴대폰의 ChatGPT 앱에서 그대로 제어합니다. QR 코드로 1회 인증한 뒤 출근길·이동 중에도 데스크 작업을 이어갈 수 있습니다.
② Device-to-Device (Mac ↔ Mac)
하나의 Codex 호스트를 다른 Codex 앱에서 연결해 머신 간 핸드오프합니다 — 데스크탑에서 시작한 작업을 노트북에서 계속.
③ SSH 원격 호스트
사내 GPU 서버·빌드 서버처럼 SSH로 접근 가능한 머신에서 Codex 실행. ~/.ssh/config에 호스트 등록 + 원격 측에 Codex 설치(PATH 포함) 필요. 인터넷 노출 대신 VPN/Tailscale 권장.

호스트에서 상속되는 자산 — 원격 세션은 호스트의 저장소·자격증명·plugins·MCP 서버·Browser 접근·Computer Use 권한을 그대로 상속합니다. 즉 호스트에 설정해 둔 환경이 모바일/원격 끝점에서 그대로 동작합니다.

QR 인증 절차, 디바이스 페어링 화면, SSH 설정 세부는 공식 Remote Connections 문서를 확인하세요.

다음 단계

Local Environment와 Setup Script를 이해했다면, 다음으로 알아볼 것은 Automations입니다. Automations는 Setup Script보다 더 넓은 범위의 자동화를 다룹니다. "PR이 올라오면 자동으로 코드 리뷰를 해줘", "매일 아침 테스트를 돌려줘" 같은 것이 가능합니다.

  • Automations 배우기: 반복 작업을 예약하고 자동 실행하는 방법
  • Settings 살펴보기: Codex 앱의 다양한 설정 옵션 알아보기
  • 문제 해결: 잘 안 될 때 확인할 체크리스트

장점 / 단점 / 한계점

✅ 장점

  • 로컬에서 직접 실행하여 빠른 응답 속도
  • 프로젝트별 맞춤 환경 구성 가능 (setup script)
  • 네트워크 지연 없이 파일 접근
  • OS 내장 샌드박스로 안전한 격리 보장

❌ 단점

  • 로컬 머신 성능에 따라 실행 속도 차이 발생
  • Setup script 작성에 초기 학습 비용 발생
  • 플랫폼별(macOS/Windows/Linux) 설정이 달라 팀 통일 어려움

⚠️ 한계점

  • Local Environments 자체는 OS 아키텍처를 가리지 않으며, 시스템 요구사항은 Codex 앱 자체의 플랫폼별 가이드를 참고
  • Windows는 데스크톱 앱 설치 시 native Windows 샌드박스가 즉시 동작합니다(Microsoft의 Hyper-V "Windows Sandbox" 기능과는 별개 — Windows Pro 에디션 불필요). WSL은 선택이며 Codex 0.115부터 WSL1은 미지원(bubblewrap 기반으로 변경) — WSL2를 사용하세요. CLI는 experimental.
  • 대형 프로젝트의 의존성 설치 시 초기 시간 소요

공식 출처