Codex CLI 설치부터 VS Code 없이 첫 코드 수정까지 10분 순서

VS Code를 열기 전에 터미널에서 먼저 끝내고 싶은 사람에게 맞는 흐름

Codex CLI 설치를 찾는 사람은 대개 거창한 개발 환경보다, 지금 쓰는 폴더에서 바로 읽고 고치고 끝나는 흐름을 원합니다. Windows 사용자라면 더 그렇습니다. 편집기를 새로 맞추는 일보다 PowerShell에서 바로 들어가서 로그인하고, 짧은 요청 하나를 통과시키는 쪽이 훨씬 빠르거든요. 이 글은 그 지점만 봅니다. PowerShell로 시작할지 WSL2로 갈지 먼저 정하고, 설치와 로그인, 첫 명령, 문서 MCP 연결까지 10분 안에 이어지는 순서입니다.

처음부터 PowerShell과 WSL2를 같이 만지면 설치보다 경로가 더 헷갈립니다. 작업 파일이 Windows 쪽에 있고 평소에도 PowerShell을 많이 쓴다면 그대로 가는 편이 단순합니다. 반대로 Bash 도구를 자주 쓰고 프로젝트가 이미 Linux 홈 디렉터리 안에 있다면 WSL2가 더 자연스럽습니다. 중요한 건 둘 중 하나를 먼저 정하고 그 흐름으로 끝까지 가보는 일입니다.

Step 1: 시작점은 명령어보다 작업 위치로 고르기

많이 막히는 지점은 설치 명령 자체가 아니라 어디서 실행하느냐입니다. Windows 파일 탐색기 기준으로 폴더를 열고 PowerShell을 쓰는 패턴이 익숙하면 native 환경이 편합니다. 관리자 권한, 경로 표기, 파일 열기까지 익숙한 방식으로 이어지기 때문입니다. 반면 Node 도구를 Bash 중심으로 써왔거나 앞으로도 Linux 흐름을 유지할 생각이면 WSL2 쪽이 더 맞습니다.

문서 정리, 스크립트 실행, 간단한 코드 수정이 주력이라면 PowerShell이 빠릅니다. Linux 패키지 흐름이나 Bash 유틸리티 의존도가 높다면 WSL2가 낫구요. WSL2를 골랐다면 프로젝트 위치도 같이 챙기는 편이 좋습니다. `/mnt/c/...` 아래에서 오래 작업하는 것보다 Linux 홈 디렉터리 안쪽에 프로젝트를 두면 경로와 권한 이슈가 덜합니다.

Step 2: 설치는 한 줄로 끝내고 바로 다음 동작으로 넘어가기

터미널 세팅 글을 보다 보면 우회 스크립트나 별도 런처가 붙은 경우가 있는데, 처음에는 그렇게 갈 이유가 거의 없습니다. 글로벌 설치 한 줄이면 시작할 수 있습니다.

여기서 멈추면 반쪽입니다. 설치 성공 메시지를 보는 것보다 중요한 건 설치 직후 `codex` 명령이 실제로 열리는지입니다. PowerShell이든 WSL2든 설치가 끝났으면 바로 다음 단계로 넘어가서 인증과 폴더 인식을 확인하는 편이 낫습니다. WSL2에서 Node 버전을 따로 관리하고 있다면 `nvm`으로 버전을 맞춘 뒤 진행하면 흐름이 안정적입니다.

Step 3: 첫 실행에서는 로그인보다 현재 폴더를 같이 보기

다음 단계는 첫 실행입니다. 보통 여기서 브라우저 인증으로 넘어가고, ChatGPT 계정 로그인이나 API key 방식 중 하나를 고르게 됩니다.

혼자 쓰는 환경이라면 ChatGPT 계정 로그인이 단순합니다. 팀 자동화처럼 과금 분리나 키 관리가 필요한 상황이면 API key 방식이 더 어울릴 수 있습니다. 다만 첫 진입에서는 인증 방식을 오래 고민하기보다 로그인 완료 후 현재 폴더에서 명령이 이어지는지 확인하는 쪽이 실용적입니다.

브라우저 인증은 끝났는데 터미널이 바로 반응하지 않는 경우도 있습니다. 이럴 때 인증 실패라고 단정하기보다 현재 세션과 작업 폴더를 먼저 보는 편이 빠릅니다. 인증은 끝났는데 파일을 못 읽는다면 원인이 계정보다 디렉터리 위치에 있을 때가 많습니다.

Step 4: 첫 코드 수정은 5줄짜리 요청으로 확인하기

이 도구가 정말 준비됐는지는 화면이 떴는지가 아니라, 지금 폴더 안 파일을 읽고 짧게 응답하는지로 판단하는 편이 좋습니다. 인터랙티브 모드로 들어가도 되지만 처음에는 결과가 바로 보이는 짧은 요청 하나가 더 낫습니다.

가장 무난한 출발은 README를 읽게 하는 방식입니다. 파일 접근, 응답 형식, 작업 범위를 한 번에 볼 수 있어서 그렇습니다.

이 예시는 길지 않지만 확인 포인트가 분명합니다. 현재 폴더를 읽는지, 작업 범위를 workspace 안으로 제한하는지, 답변이 과하게 늘어지지 않는지 바로 알 수 있습니다. 처음부터 여러 파일 수정이나 큰 리팩토링을 던지면 설치 문제인지 지시 문제인지 구분이 흐려집니다.

예전 예시에서 자주 보이던 `codex exec --full-auto`도 아직 눈에 띄지만, 새로 시작하는 흐름은 `codex exec --sandbox workspace-write` 쪽이 더 매끈합니다. 오래된 명령을 붙여 넣는 것보다 지금 문법으로 첫 요청을 통과시키는 편이 덜 헷갈립니다. 그리고 `codex exec`는 빈 폴더보다 Git 프로젝트 안에서 쓸 때 훨씬 자연스럽습니다. 작업 위치에 코드가 이미 있다면 그 폴더에서 시작하는 게 좋습니다.

Step 5: 문서 MCP까지 붙여두면 다시 검색하는 시간이 줄어든다

설치 뒤에 한 번 더 해둘 만한 설정이 있습니다. OpenAI 개발자 문서를 MCP로 연결해두면 명령어 옵션이나 API 흐름을 찾을 때 브라우저 탭을 여러 개 열 필요가 줄어듭니다.

Responses API나 MCP 관련 작업을 자주 볼 예정이라면 특히 유용합니다. 명령 이름이 살짝 헷갈릴 때도 터미널 흐름 안에서 다시 확인할 수 있어서 작업이 끊기지 않습니다. 처음 세팅할 때 이 단계까지 같이 해두면 다음 진입 속도가 확실히 좋아집니다.

10분 안에 끊기지 않게 가는 순서

이 글의 포인트는 복잡한 IDE 세팅이 아니라 시작점을 좁히는 데 있습니다. Windows 작업 폴더가 중심이면 PowerShell에서 시작하고, Linux 셸이 꼭 필요한 경우에만 WSL2로 넘어가면 됩니다. 그다음 `npm i -g @openai/codex`, `codex`, `codex exec --sandbox workspace-write` 순서로 이어가면 첫 수정까지 한 호흡으로 갑니다.

VS Code 없이도 여기까지는 충분합니다. 처음 한 번은 README 5줄 정리처럼 짧고 눈에 보이는 요청으로 통과시키세요. 그 한 번이 지나가면 이후에는 파일 설명, 작은 수정, 문서 정리까지 같은 흐름으로 넓히기 쉬워집니다.