Windows CLI 설치와 문제 해결

Codex 학습 목차로 돌아가기

목표와 대상 환경

Windows 네이티브 CLI에는 WSL이 필수가 아닙니다. Ubuntu 터미널이고 경로가 /home으로 시작하면 Linux / WSL을 보세요. 이 글은 PowerShell용입니다. CLI 기초에서 환경을 구분한 후 설치를 마치고 한 줄 수정 실습으로 돌아갑니다. 그림의 1은 설치, 2는 위치와 인증, 3은 독립적인 파일 확인입니다.

설치 전에 winver로 Windows 버전을 확인하세요. 현재 공식 문서는 Windows 11을 권장하며 최신 콘솔 기능을 갖추고 업데이트된 Windows 10은 가능한 범위에서만 지원합니다. 오래된 버전까지 같은 수준으로 지원된다고 판단하지 마세요. 기본 샌드박스 설정에는 winget과 관리자 승인 등 추가 조건이 있으므로 공식 Windows 샌드박스 문서를 확인합니다. CLI 설치와 샌드박스 설정을 별도 단계로 나누고 어느 단계에서 실패했는지 기록하세요.

1단계: PowerShell과 설치 경로 선택하기

시작 메뉴에서 PowerShell을 검색하거나 Windows Terminal 프로필에서 선택합니다. 일반 사용자 창으로 시작하며 일상 작업을 모두 관리자 권한으로 실행할 필요는 없습니다. 아래 첫 명령을 셸에서 실행하세요. codex가 있으면 버전과 Source를 기록하고 중복 설치 대신 폴더 준비로 넘어갈 수 있습니다.

Get-Command codex -All | Select-Object CommandType, Name, Source
codex --version

설치 전에는 명령을 찾지 못해도 정상입니다. 아래 공식 Windows 독립 설치 명령은 스크립트를 다운로드해 실행하므로 공식 페이지의 URL을 확인한 후 사용하세요. ByPass는 이번 자식 프로세스의 인수이지 실행 정책을 영구 해제하라는 뜻이 아닙니다. 조직 정책이 막으면 구체적인 오류를 기록하고 관리자 승인 설치 경로를 사용합니다.

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

완료를 기다리고 마지막에 표시된 설치 경로와 PATH 안내를 남깁니다. 터미널을 닫고 새 PowerShell에서 Get-Command codex -All과 codex --version을 다시 실행합니다. 실행 가능한 원본과 버전이 확인되어야 합니다. 다운로드 완료, 폴더 존재, 오류 없음만으로는 명령을 사용할 수 있다는 검증이 아닙니다.

Node.js가 이미 있을 때 npm 대안

npm 방식을 선택한 경우에만 세 줄을 실행합니다. 처음 두 줄에서 버전이 나오지 않으면 설치 명령을 반복하지 말고 Node.js부터 해결하세요. npm.cmd는 Windows 명령 래퍼를 명시해 npm.ps1 실행 정책 문제와 Codex 설치 실패를 구분합니다. 독립 설치 프로그램에 npm은 필수가 아닙니다.

node --version
npm.cmd --version
npm.cmd install -g @openai/codex

2단계: 공백 경로를 만들고 확인하기

실제 프로젝트 밖의 쓰기 가능한 위치를 고릅니다. & {부터 마지막 }까지 블록 전체를 붙여 넣어 새 codex windows lab을 만드세요. 존재 확인에 실패하면 블록이 중단됩니다. 같은 이름이 이미 있으면 내용을 보존하고 새 이름을 선택하며 확인을 건너뛰고 쓰기 줄만 실행하지 않습니다. 성공하면 새 폴더로 이동해 목록과 note.txt를 읽습니다. 따옴표는 공백을 보존하고 LiteralPath는 와일드카드 해석을 막습니다.

& {
  $cliLab = Join-Path (Get-Location) 'codex windows lab'
  if (Test-Path -LiteralPath $cliLab) { throw 'Choose a new practice folder name.' }
  New-Item -ItemType Directory -Path $cliLab -ErrorAction Stop
  Set-Location -LiteralPath $cliLab -ErrorAction Stop
  Set-Content -LiteralPath 'note.txt' -Value 'WINDOWS-CLI-01' -Encoding utf8 -ErrorAction Stop
  Get-Location
  Get-ChildItem
  Get-Content -LiteralPath 'note.txt'
}

현재 경로가 codex windows lab으로 끝나고 note.txt가 있으며 내용이 WINDOWS-CLI-01이면 준비가 됐습니다. 읽기 전후 비교용 해시도 기록합니다. 해시는 파일 바이트의 지문이며 UTF-8 BOM과 줄바꿈 차이로 컴퓨터마다 다를 수 있으므로 게시된 고정값이 아닌 자신의 전후 값을 비교하세요.

Get-FileHash -LiteralPath 'note.txt' -Algorithm SHA256

3단계: 인증, 샌드박스, 파일 읽기

연습 폴더에서 codex login과 codex login status를 차례로 실행한 후 읽기 전용 세션을 시작합니다. 브라우저에서 계정과 워크스페이스를 확인하세요. 유효한 로그인이 있으면 로그아웃해 초기화할 필요가 없습니다. 인증을 공유하는 IDE 확장도 로그아웃의 영향을 받을 수 있습니다. 공개 화면에 인증 정보를 넣지 마세요.

codex login
codex login status
codex --sandbox read-only

Windows 샌드박스 설정에는 일회성 관리자 승인이 필요할 수 있으며 일상 PowerShell을 관리자로 실행하는 것과는 다릅니다. 공식 안내는 더 강한 elevated를 우선하고 unelevated를 제한된 대안으로 제공하지만 조직이 금지할 수 있습니다. 실패하면 Windows 버전, 모드, 실패 단계를 기록하고 전체 접근으로 바꾸기 전에 권한과 샌드박스를 확인하세요.

Read note.txt in the current practice folder. Report the exact content and current working directory. Do not edit, create files, or use external services. If it is missing or inaccessible, report the actual error.

이 요청은 PowerShell이 아닌 Codex에 입력합니다. 응답과 읽기 기록에서 WINDOWS-CLI-01과 올바른 폴더를 확인합니다. 성공 기준을 기록한 뒤 같은 Codex 세션에서 missing-note.txt를 요청해 생성 없이 없다고 보고하는지 시험합니다. 이어서 /exit로 PowerShell에 돌아온 뒤 다시 읽고 목록과 해시를 확인해 내용 변경이나 추가 연습 파일이 없는지 봅니다. 다른 내용이 나오면 먼저 작업 위치를 바로잡으세요.

업데이트와 세 가지 문제 구분

업데이트 전 CLI를 종료하고 작업 요약과 커밋하지 않은 파일을 보존합니다. 독립 버전은 같은 공식 설치 명령, npm 버전은 npm.cmd install -g @openai/codex를 사용합니다. 새 PowerShell에서 Source와 버전을 확인합니다. 구버전이면 중복 원본을 찾으세요. 한 설치본만 갱신되고 PATH가 다른 것을 선택할 수 있어 실행 파일 확인 없이 반복 업데이트하면 해결되지 않습니다.

PATH는 셸의 실행 파일 검색 목록이며 프로젝트 목록이 아닙니다. 설치 출력과 Source를 비교합니다. 직접 수정해야 하면 Windows의 계정 환경 변수 편집기에서 사용자 Path를 열어 기존 항목을 유지하고 확인된 설치 폴더를 추가한 뒤 저장하고 터미널을 다시 엽니다. 전체 PATH를 예제로 덮거나 확인하지 않은 다운로드 폴더를 추가하지 마세요.

완료 조건과 다음 단계

어느 CLI가 실행되는지, 작업 폴더, 인증 상태, 파일 표식, 전후 해시 일치 여부를 설명할 수 있어야 합니다. 설치 경로, 버전, 오류와 해결법을 실습 노트에 적되 인증 내용은 저장하지 않습니다. CLI 기초로 돌아가 수정과 재개를 연습하거나 편집기 작업은 IDE 확장으로 이어가세요.

Codex 학습 목차로 돌아가기

자세한 설명 보기

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI 도구
• 튜토리얼
• Codex