harness-edu
설치가이드 · 두 번째 AI 붙이기

Codex CLI 설치가이드

ChatGPT Plus 구독으로 OpenAI의 터미널 AI를 붙입니다. "같은 일을 두 도구에 시켜 비교한다"가 이 과정의 핵심 실습 중 하나입니다.

설치 2 / 3 ⏱ 10~15분 💻 Windows / 🍎 macOS 🔑 ChatGPT Plus 이상 구독 필요

작성일: 2026-08-20 (명령어는 이 날짜에 공식 저장소로 확인)
선행 조건: 공통 준비 (Windows) 또는 공통 준비 (macOS) 완료
끝나면: codex 명령이 동작하고 ChatGPT 계정으로 로그인된 상태

ChatGPT 구독이 없으면 이 문서를 건너뛰세요. Codex는 Plus / Pro / Business / Edu / Enterprise 플랜에서 쓸 수 있고, 무료 플랜으로는 쓸 수 없습니다. Codex를 쓰지 않아도 Claude Code만으로 대부분의 모듈을 진행할 수 있습니다. (비교 실습만 관찰 학습으로 대체)

빠른 설치 (아는 사람용 · 5분)

Windows (PowerShell)

PowerShell에 붙여넣기
irm https://chatgpt.com/codex/install.ps1 | iex

macOS

터미널에 붙여넣기
curl -fsSL https://chatgpt.com/codex/install.sh | sh

창을 새로 열고 확인 → 로그인 → 확인

터미널에 붙여넣기
codex --version
터미널에 붙여넣기
codex login
터미널에 붙여넣기
codex login status

1. 이 도구는 무엇인가

Codex CLI 는 OpenAI가 만든 터미널 AI 에이전트입니다. Claude Code와 하는 일이 거의 같고, 모델이 다릅니다(OpenAI GPT 계열). 그래서 이 과정에서는 두 가지 용도로 씁니다.

용도무엇을 배우나관련 모듈
두 번째 의견같은 지시서를 두 도구에 주고 결과 차이를 본다 → "지시가 구체적이면 도구가 달라도 결과가 비슷해진다"를 체감지시서·하네스 모듈
도구 이식성 확인내가 만든 스킬·MCP 도구를 다른 도구에도 붙여 본다 → "자산은 도구에 종속되지 않는다"MCP 서버 모듈

왜 두 도구를 쓰나: 한 도구만 쓰면 "이 AI가 원래 잘하는 것"과 "내 지시가 좋아서 잘된 것"을 구분할 수 없습니다. 두 도구에 같은 지시서를 주면 지시서의 품질이 눈에 보입니다. 이것이 하네스를 배우는 가장 빠른 길입니다.

2. 설치 전 확인

항목필요한 것확인·대처
선행 설치공통 준비 완료Windows / macOS
구독ChatGPT Plus 이상chatgpt.com 왼쪽 아래 계정에서 확인
OpenAI API Key필요 없음구독 계정 로그인으로 사용 (별도 과금 없음)
저장 공간300MB 이상—
관리자 권한필요 없음사용자 폴더에 설치됩니다

계정 주의 — 회사 ChatGPT 계정(Business/Enterprise)으로 로그인하면 회사 정책에 따라 사용 기록이 관리될 수 있습니다. 실습은 가상 데이터만 사용하고, 실제 업무 파일이 있는 폴더에서 실행하지 않습니다.

3. 설치 절차

3-1. 터미널 열기

Windows: 시작 → PowerShell 검색 → 실행 (관리자 권한 불필요)
macOS: Command+스페이스 → 터미널 → 실행

3-2. 설치 명령 실행

Windows

PowerShell에 붙여넣기
irm https://chatgpt.com/codex/install.ps1 | iex

macOS

터미널에 붙여넣기
curl -fsSL https://chatgpt.com/codex/install.sh | sh

예상 결과: 다운로드 진행 표시가 흐르고 설치 완료 메시지가 나옵니다. 1~3분.

이렇게 나오면 오류: Windows에서 'irm'은(는) 내부 또는 외부 명령이 아닙니다 → PowerShell이 아니라 CMD입니다. 프롬프트 앞에 PS 가 있어야 합니다. 스크립트 실행이 정책으로 막히면 문제 해결 ①.

3-3. 터미널 창을 닫고 새로 열기

이 단계를 건너뛰면 다음 명령이 "찾을 수 없다"고 나옵니다. 설치 프로그램이 등록한 경로는 새 창에서만 반영됩니다.

새 창에 붙여넣기
codex --version

예상 결과: codex-cli 0.143.0 형태의 버전 번호. 숫자는 달라도 됩니다.

이렇게 나오면 오류: codex 를 찾을 수 없다 → 문제 해결 ②

4. 설치 확인

터미널에 붙여넣기
codex --version

버전 번호가 나오면 설치는 끝났습니다. 아직 로그인은 하지 않은 상태입니다.

5. 초기 설정·연동 (ChatGPT 계정 연결)

5-1. 실습 폴더로 이동

Windows

PowerShell에 붙여넣기
cd C:\harness-edu

macOS

터미널에 붙여넣기
cd ~/harness-edu

5-2. ChatGPT 계정으로 로그인

터미널에 붙여넣기
codex login

브라우저가 열리면 Sign in with ChatGPT 를 선택하고 구독 계정으로 로그인합니다.

예상 결과: 브라우저에 "로그인 완료" 화면이 뜨고, 터미널에도 성공 메시지가 나옵니다.

브라우저가 안 열리면: 터미널에 표시된 https://... 주소를 복사해 직접 붙여넣으세요. 원격 접속·서버 환경이라면 codex login --device-auth 를 씁니다.

5-3. 로그인 확인

터미널에 붙여넣기
codex login status

예상 결과: ChatGPT 계정으로 로그인되어 있다는 한 줄.

예상 화면
Logged in using ChatGPT

최종 체크리스트

  • ChatGPT Plus 이상 구독 확인
  • codex --version 이 버전 번호를 출력
  • codex login status 가 로그인 상태를 표시
  • 아래 6절 첫 동작 테스트 통과

6. 첫 동작 테스트 (5분)

6-1. 읽기 전용으로 한 번 (가장 안전)

실습 폴더에서 아래를 실행합니다. 파일을 절대 수정하지 않는 모드입니다.

터미널에 붙여넣기
codex exec --sandbox read-only --skip-git-repo-check "이 폴더에 어떤 실습 폴더가 있는지 한국어로 3줄 요약해라"

예상 결과: 진행 로그가 흐른 뒤 한국어 요약 3줄이 출력되고 프롬프트로 돌아옵니다. 30초~2분.

옵션무엇인가언제
codex대화형 화면 (사람이 직접 대화)탐색·질문할 때
codex exec "..."한 번 시키고 끝 (화면 점유 없음)정해진 작업을 돌릴 때
--sandbox read-only파일을 읽기만 함처음엔 항상 이것
--sandbox workspace-write현재 폴더 안에서 파일 생성·수정 허용결과물을 만들 때

6-2. 두 도구 비교 (이 과정의 핵심 감각)

같은 지시를 Claude Code와 Codex에 각각 주고 결과를 비교해 보세요.

두 도구에 똑같이 주는 지시
xlsx 폴더의 생산보고서 6개를 읽고, 라인별 불량률을 계산해서
불량률이 높은 순으로 표를 만들어줘. 계산 근거도 함께 적어줘.

관찰 포인트: 두 결과의 표 형식·기준·용어가 서로 다를 것입니다. 어느 쪽이 더 낫냐가 아니라, "지시가 느슨하면 도구마다 다르게 해석한다" 는 사실이 중요합니다. 이 간극을 없애는 것이 뒤에 배울 지시서(Skill) 와 도구(Tool) 입니다.

6-3. 이미지 생성 (선택)

Codex에는 이미지 생성 도구가 내장되어 있어 추가 설치가 필요 없습니다. 발표자료 표지 같은 것을 만들 때 씁니다.

터미널에 붙여넣기 — 사용 가능한지 확인
codex features list

목록에 image_generation 이 보이면 아래처럼 생성할 수 있습니다.

터미널에 붙여넣기
codex exec --sandbox workspace-write --skip-git-repo-check "이미지 생성 도구로 '스마트 공장 품질관리 대시보드, 미니멀 일러스트' 이미지를 만들고 ./cover.png 로 저장해라. 저장 경로만 한 줄로 보고."

예상 결과: 현재 폴더에 cover.png 가 생깁니다. 1장당 1~2분 걸리고 ChatGPT 구독 사용량을 씁니다. 해상도를 정확히 지정하기는 어렵습니다(모델이 프롬프트에 맞춰 결정).

7. 문제 해결

① Windows: 스크립트 실행이 막힙니다

이 시스템에서 스크립트를 실행할 수 없으므로... 가 나오면 아래를 한 번 실행하고(Y 승인) 설치를 다시 시도합니다.

PowerShell에 붙여넣기
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

회사 노트북에서 그룹 정책에 의해 재정의됩니다 / 액세스가 거부되었습니다 로 실패하면 우회하지 말고 IT 담당자에게 요청하세요.

② 설치했는데 codex 를 찾을 수 없습니다

  • 1순위: 터미널을 완전히 닫고 새로 열어 codex --version 재확인 (원인 대부분이 이것입니다).
  • 2순위: PC 재부팅 후 재확인.
  • 3순위: macOS라면 아래를 실행하고 새 창을 엽니다.
터미널에 붙여넣기 (macOS)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

③ "구독이 필요합니다" / 사용량이 초과되었다고 나옵니다

  • 원인: 무료 플랜 계정으로 로그인했거나, 구독 사용량을 이미 다 썼습니다.
  • 해결: codex login status 로 계정을 확인하고, 필요하면 codex logout → codex login 으로 구독 계정으로 다시 로그인합니다. 사용량 초과라면 시간이 지나 초기화될 때까지 기다립니다.

④ 로그인 브라우저가 열리지 않습니다

  • 터미널에 표시된 주소를 복사해 브라우저에 직접 붙여넣습니다.
  • 그래도 안 되면 codex login --device-auth — 화면에 코드가 나오고, 다른 기기 브라우저에서 그 코드를 입력합니다.

⑤ 실행하면 not a git repository 라고 나옵니다

  • 원인: Codex는 기본적으로 Git 저장소 안에서 실행되기를 기대합니다.
  • 해결: 명령에 --skip-git-repo-check 를 붙이면 됩니다. 이 문서의 예시에는 모두 포함되어 있습니다.

⑥ 한글이 깨져 보입니다 (Windows)

  • Windows 11의 터미널(Windows Terminal) 로 여세요. 시작 → 터미널 검색 → 실행.

8. 제거·연동 해제

1) 로그아웃 (계정 연결만 끊기)

터미널에 붙여넣기
codex logout

2) 프로그램 제거

Windows · PowerShell
Remove-Item -Path "$env:USERPROFILE\.local\bin\codex.exe" -Force -ErrorAction SilentlyContinue
macOS · 터미널
rm -f ~/.local/bin/codex

3) 설정·기록까지 지우기 (선택 — 되돌릴 수 없습니다) — ~/.codex (Windows: %USERPROFILE%\.codex) 폴더를 삭제합니다.

4) 권한 회수 — ChatGPT 계정에 연결된 앱 권한을 정리하려면 chatgpt.com 설정에서 확인하세요.

9. 다른 설치 방법 (본문이 막힐 때만)

  • Homebrew (macOS): brew install --cask codex — brew를 이미 쓰는 분만. 갱신은 brew upgrade codex.
  • npm: Node.js가 이미 있는 분만 npm install -g @openai/codex. Node.js를 새로 깔 필요는 없습니다.
  • 자동 스크립트로 함께 설치 (Windows): 공통 준비의 점검 스크립트를 .\setup-windows.ps1 -Codex 로 실행하면 이 문서의 3절을 자동 처리합니다.
  • WSL2: 이 과정에서는 쓰지 않습니다.

10. 다음 단계

설치 3 / 3MCP 서버 (Tool)같은 도구를 Claude Code와 Codex 양쪽에 붙여 "도구 이식성"을 확인합니다. 교육커리큘럼 보기두 도구 비교 실습이 포함된 모듈로 이동합니다. 설치설치가이드 홈전체 설치 현황을 다시 확인합니다.

확인한 출처