Chapter 03. 환경 설정 - macOS, Windows, WSL

설치에서 막히면 바이브 코딩은 시작도 못 한다. Codex는 잘 붙으면 정말 빠른데, 운영체제와 터미널, 인증 방식이 어긋나면 첫인상부터 삐걱거린다. 이 장의 목표는 단순하다. macOS 사용자든, Windows 사용자든, 앱·CLI·IDE 확장 중 자기에게 맞는 시작점을 고르고, 인증·인코딩·권한 문제까지 한 번에 정리하는 것이다.

핵심만 먼저 말하면 이렇다. macOS는 비교적 편하게 시작할 수 있고, Windows는 네이티브보다 WSL2를 기본값으로 잡는 편이 안정적이다. OpenAI 공식 문서도 Windows에서는 네이티브 방식과 WSL2 방식을 모두 안내하지만, WSL2 쪽이 Linux 샌드박스를 그대로 활용할 수 있어 실무 감각에 더 가깝다.¹

어디서 시작할지 먼저 결정하자

같은 Codex라도 시작점이 다르면 체감이 완전히 다르다. 처음부터 CLI만 고집할 필요는 없다.

CLI는 npm install -g @openai/codex로 가장 보편적으로 설치하고, GitHub Releases의 네이티브 바이너리를 받아 쓰는 방법도 있다.² VS Code 쪽은 마켓플레이스의 Codex – OpenAI's coding agent 확장을 쓰면 되고, JetBrains 계열은 별도 통합 플러그인을 설치하면 된다.³⁴

공통 준비물

운영체제와 무관하게 먼저 확인할 것들이 있다.

1. 계정 개인 사용자는 보통 ChatGPT 계정 로그인부터 시작하는 편이 가장 간단하다. Plus, Pro, Business, Edu, Enterprise 플랜 사용자는 별도 키 관리 없이 바로 연결하기 쉽다.³

2. Git Codex는 깃 저장소 안에서 훨씬 똑똑하게 움직인다. diff를 보여주고, 변경 범위를 추적하고, 나중에 PR까지 이어가기 좋다. 설치만 하고 Git 없이 쓰면 발은 달렸는데 신발이 없는 느낌이다.

3. Node.js 22+ npm으로 CLI를 설치할 생각이라면 Node가 필요하다. 특히 Windows는 예전 Node가 남아 있어서 설치가 꼬이는 일이 잦다. node -v, npm -v부터 확인하자.

4. 편집기 VS Code 또는 JetBrains 중 하나는 있는 편이 좋다. CLI만으로도 가능하지만, 실제로는 diff를 눈으로 보는 순간 생산성이 확 올라간다.

macOS 설정: 가장 편한 길부터 시작하기

macOS는 Codex를 쓰기 가장 수월한 축에 속한다. 입문자라면 데스크톱 앱부터, 개발자라면 CLI와 IDE 확장을 함께 붙이는 구성이 무난하다.

데스크톱 앱으로 시작하기

앱은 가장 부담이 적다. 프로젝트 폴더를 열고, 작업을 요청하고, 변경사항을 리뷰하는 흐름이 직관적이다. 특히 터미널보다 창 하나에서 끝나는 방식을 선호한다면 앱이 좋다.

처음 실행할 때는 폴더 접근 권한을 물을 수 있다. 이때는 프로젝트 루트만 허용하는 습관을 들이는 편이 안전하다. 처음부터 디스크 전체 권한을 넓게 주면 편하긴 하지만, 나중에 왜 그런 권한이 필요한지 모른 채 습관이 굳는다.

CLI 설치: npm이 기본, 바이너리는 대안

가장 일반적인 설치는 아래처럼 간단하다.²

npm install -g @openai/codex
codex

Node 환경을 깔끔하게 관리하고 싶다면 nvm을 쓰는 편이 좋다. 프런트엔드 프로젝트마다 Node 버전이 달라지는 한국 개발자에게는 거의 보험 같은 도구다.

npm이 싫다면 GitHub Releases의 네이티브 바이너리를 받아 PATH에 넣는 방법도 있다.² 이 방식의 장점은 Node 의존성을 줄일 수 있다는 점이다. 터미널 도구를 가볍게 유지하고 싶은 사람에게 잘 맞는다.

VS Code 확장 붙이기

VS Code에서는 확장만 설치하면 된다. 패널에서 Codex를 열고 ChatGPT 계정으로 로그인하면, 열린 파일과 선택한 코드 문맥을 자연스럽게 활용할 수 있다.³ 실무에서는 이 조합이 꽤 강하다. 코드 일부를 고치고 싶을 때는 IDE가 빠르고, 저장소 전체를 뒤지는 작업은 CLI가 더 시원하다.

Windows 설정: 네이티브보다 WSL2를 기본값으로 생각하자

Windows에서 가장 흔한 실수는 "일단 PowerShell에서 다 되겠지"라고 시작하는 것이다. 돌아갈 때도 있지만, 실무에서는 인코딩, 권한, 파일 I/O, 샌드박스 차이 때문에 작은 삐끗함이 연쇄적으로 커진다. 그래서 Windows 개발자에게는 WSL2를 기본값으로 권한다.¹

왜냐하면 이유가 세 가지다.

1. Linux 기준 도구 체인과 더 잘 맞는다.

2. 샌드박스 동작이 더 성숙해 있다.¹

3. 예제, 스크립트, 빌드 환경이 서버와 더 비슷하다.

네이티브 Windows가 완전히 쓸모없다는 뜻은 아니다. 가벼운 확인 작업이나 앱 중심 사용은 충분히 가능하다. 다만 CLI를 오래 쓸 계획이면 WSL2가 덜 아프다.

WSL2 설치: Windows 사용자의 사실상 정답

PowerShell을 관리자 권한으로 열고 아래부터 시작한다.

wsl --install
wsl --update

설치가 끝나면 재부팅 후 Ubuntu를 열고, 리눅스 사용자 이름과 비밀번호를 만든다. 설치 상태는 아래처럼 확인할 수 있다.

wsl --status

기본 버전이 2로 잡혀 있지 않다면 설정을 다시 확인하자. 여기서부터 중요한 규칙이 하나 있다. 프로젝트를 /mnt/c/...에 두지 말고, WSL 내부의 ~/code 아래에 두자. 이 차이 하나로 Git, 검색, 파일 수정 속도가 체감될 정도로 달라진다.⁵

권장 흐름은 이렇다.

mkdir -p ~/code
cd ~/code
git clone <your-repo-url>
cd <repo>

Windows 탐색기에서 파일을 보고 싶다면 \wsl$Ubuntuhome사용자명 경로로 들어가면 된다.⁵

WSL 안에 Node와 Codex CLI 설치하기

Ubuntu 터미널에서 아래 순서대로 진행하자.

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.bashrc

nvm install 22
node -v
npm -v

npm install -g @openai/codex
codex

여기서 막히는 포인트는 대체로 두 가지다.

첫째, nvm: command not found가 뜨는 경우다. 대부분 셸을 다시 열지 않았거나 source ~/.bashrc를 안 해서 그렇다.

둘째, codex: command not found가 뜨는 경우다. 이건 대개 Codex를 Windows 쪽에 설치하고 WSL 안에서는 안 깔았거나, 반대로 WSL 안에만 설치했는데 Windows 터미널에서 찾는 상황이다. 어디에 설치했는지와 어디서 실행하는지를 일치시켜야 한다.

Windows에서 VS Code를 제대로 붙이는 법

Windows에서 가장 좋은 조합은 VS Code + Remote - WSL + WSL 안의 Codex CLI다.⁵ 방법은 어렵지 않다.

1. VS Code에 WSL 확장을 설치한다.

2. Ubuntu 터미널에서 프로젝트 폴더로 이동한다.

3. 그 상태에서 code .을 실행한다.

4. 상태바에 WSL: Ubuntu가 보이면 성공이다.

이렇게 열면 통합 터미널도 Linux 셸로 뜬다. 즉, 에디터는 Windows의 편의성을 쓰고, 실행 환경은 Linux의 안정성을 가져가는 셈이다. 한국 개발자 입장에서는 이 구성이 가장 덜 스트레스받는다. 특히 Next.js, Node, Python, Docker, Supabase CLI를 섞는 순간 차이가 확 느껴진다.

JetBrains IDE 설정

IntelliJ IDEA, WebStorm, PyCharm, Rider를 쓴다면 JetBrains 통합을 설치하면 된다. 이 통합은 ChatGPT 로그인, API 키, JetBrains AI 구독 방식으로 인증할 수 있다.⁴

JetBrains를 주력으로 쓰는 백엔드 개발자라면 두 가지를 기억하면 된다.

첫째, 일상적인 편집과 탐색은 IDE 확장이 편하다.

둘째, 저장소 전체를 건드리는 자동 수정이나 긴 작업은 CLI가 더 잘 맞는다.

즉, JetBrains 사용자도 IDE만 고집하지 말고 IDE + CLI의 투트랙을 생각하는 편이 좋다.

인증: ChatGPT 로그인부터, API 키는 필요할 때

처음에는 ChatGPT 로그인이 가장 쉽다. 브라우저로 인증하고 바로 시작할 수 있어서, 로컬 개발자 입장에서는 설정 비용이 거의 없다.²³

API 키는 다음 경우에 더 잘 맞는다.

1. CI/CD나 서버 자동화에 붙일 때

2. 개인 계정과 업무 계정을 분리하고 싶을 때

3. 사용량을 별도로 추적하고 싶을 때

가끔 계정에 프로모션 크레딧이 남아 있는 경우도 있다. 이럴 때는 작은 실험을 API 키 방식으로 돌려볼 수 있다. 다만 모든 계정에 공짜 크레딧이 있는 것은 아니니, 반드시 Usage와 Billing 화면을 먼저 확인하자.

한국어 환경 트러블슈팅: 한글 깨짐은 모델보다 환경 문제다

한국 개발자에게 가장 짜증 나는 문제는 역시 한글 깨짐이다. 특히 i18n JSON, TSX 안의 UI 문구, 주석 파일에서 글자가 �로 바뀌면 기분도 같이 깨진다.

중요한 건, 이 문제를 "Codex가 한국어를 못해서"라고 보면 해결이 어렵다는 점이다. 실제로는 Windows의 인코딩 경로와 PowerShell 동작 때문에 깨지는 경우가 많다.⁶ 특히 PowerShell 5.1의 오래된 기본 동작이 끼어들면 비라틴 문자 처리에서 문제가 생기기 쉽다.⁷

가장 안전한 해결책

제일 깔끔한 방법은 Windows에서 CLI 작업을 WSL2로 옮기는 것이다. 이 한 줄로 끝나는 문제가 정말 많다.

그래도 네이티브 Windows를 써야 한다면 다음 순서로 정리하자.

1. PowerShell 7을 설치한다.

2. VS Code 기본 터미널을 PowerShell 7로 바꾼다.

3. VS Code 파일 인코딩을 UTF-8로 고정한다.

4. 한글이 많은 파일은 작은 범위만 수정하게 시킨다.

5. 적용 직후 diff와 빌드를 바로 확인한다.

VS Code 설정은 대략 이런 방향이면 된다.

{
  "files.encoding": "utf8",
  "files.autoGuessEncoding": false
}

PowerShell 쪽은 문자 인코딩 기본값과 cmdlet별 인코딩 차이를 이해해야 한다. Microsoft 문서에서도 PowerShell 5.1과 7+의 기본 인코딩 동작이 다르고, PowerShell 7+는 utf8NoBOM이 기본이라고 설명한다.⁷

왜 작은 범위 수정이 중요할까

에이전트형 도구는 내가 요청한 것보다 더 넓게 고치는 일이 있다. 한국어 문자열이 섞인 JSON이나 TSX에서는 이게 특히 위험하다. 작은 텍스트 손상이 바로 파싱 오류, 빌드 실패, 화면 깨짐으로 이어지기 때문이다.⁶

그래서 한글이 많은 파일에는 이렇게 지시하는 편이 좋다.

이 파일 전체를 정리하지 말고, login.title 키와 login.description 키만 수정해줘.
다른 포맷팅 변경은 하지 마.

이 한 문장이 사고를 꽤 많이 줄여준다.

PowerShell 프로필 설정 시 주의할 점

검색해보면 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8를 무조건 넣으라는 팁이 많이 나온다. 방향은 맞다. 하지만 Windows의 제한된 샌드박스 세션에서는 이 설정이 경고를 내는 사례도 보고되어 있다.⁸

즉, 원리는 맞지만 만능은 아니다. 네이티브 Windows에서 Codex가 제한 모드로 PowerShell을 띄웠을 때 이상한 경고가 계속 보이면, 억지로 레지스트리와 프로필을 파기보다 WSL2로 옮기는 게 더 빠른 해결인 경우가 많다.

샌드박스와 권한: 넓게 주기보다 좁게 시작하기

처음 Codex를 붙이면 "그냥 다 허용할까?"라는 유혹이 온다. 하지만 초반에는 작업 폴더 기준의 제한된 권한으로 시작하는 편이 좋다.

추천 습관은 이렇다.

1. 저장소 루트에서 실행한다.

2. Git 저장소 안에서만 작업한다.

3. 프로젝트 밖 파일 수정은 필요한 순간에만 허용한다.

4. 네트워크 접근도 처음엔 최소화한다.

특히 Windows 네이티브에선 권한과 샌드박스 동작이 더 민감하다. 반면 WSL2는 Linux 기준으로 행동하므로 예측하기가 쉽다.¹

설치가 끝났는지 확인하는 5분 점검표

아래 다섯 가지가 되면 준비는 끝났다.

1. codex --version이 정상적으로 나온다.

2. 프로젝트 폴더에서 codex 실행 후 로그인 화면 또는 대화형 화면이 뜬다.

3. VS Code 또는 JetBrains에서 Codex 패널이 열린다.

4. Git 저장소 안에서 파일 diff를 확인할 수 있다.

5. 한글이 들어간 파일을 작은 범위로 수정해도 깨지지 않는다.

마지막으로, Windows 사용자라면 이것만 기억해도 절반은 성공이다. WSL2 안에 프로젝트를 두고, VS Code는 WSL로 열고, Codex도 WSL 안에 설치하자. 이 구성이 한국 개발 환경에서 가장 재현성이 좋고, 가장 덜 싸운다.

다음 장부터는 이제 설치가 아니라 실제 작업이다. 즉, 환경을 세팅하는 시간을 줄이고, Codex가 첫 PR을 떨어뜨리게 만드는 단계로 넘어간다.

참고

¹Windows - Codex  OpenAI Developers

²openai/codex GitHub 저장소

³Codex – OpenAI's coding agent - Visual Studio Marketplace

⁴IDE extension - Codex  OpenAI Developers

⁵Codex를 Windows에서 제대로 쓰는 법 (WSL, 샌드박스, 성능까지)

⁶Is "Codex Korean Text Corruption" Still a Thing? (2026 Update)

⁷about_Character_Encoding - PowerShell  Microsoft Learn

⁸Powershell: issue with '' [Console]::OutputEncoding=[System.Text.Encoding]::UTF8' · Issue #9767 · openai/codex