Windows에 Claude Code와 Codex CLI 설치하는 방법

Windows 10과 11에서 Claude Code 설치, Codex CLI 설치에 쓰는 정확한 PowerShell, CMD, WinGet, npm 명령어, WSL을 골라야 할 때, 그리고 'claude'은(는) 내부 또는 외부 명령이 아니라는 오류를 비롯해 마주칠 오류의 해결법을 정리했습니다.

이제 두 CLI 모두 Windows에서 한 줄로 설치됩니다. 문제는 대개 그다음입니다. 명령을 찾지 못하는 터미널, npm을 막는 실행 정책, 오래된 WSL 1 배포판, 엉뚱한 셸에 붙여 넣은 명령. 이 가이드는 설치 방법별 정확한 명령어와 오류별 해결법을 정리합니다.

두 CLI에 관한 내용은 Anthropic과 OpenAI의 문서와 설치 스크립트를 2026년 11월 16일에 읽고 확인한 것입니다(Claude Code 2.1.318, Codex CLI 0.169.0). 둘 다 빠르게 바뀌니, 명령이 실패하면 각 섹션의 공식 페이지를 확인하세요.

짧은 답. CMD가 아닌 PowerShell을 열고 실행하세요.

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

그다음 새 터미널에서 claude --version과 codex --version을 실행합니다. Windows가 claude를 인식하지 못하면 PATH 해결법은 아래 오류 표에 있습니다.

Windows에서 각 CLI에 필요한 것

Claude CodeCodex CLI
Windows 버전Windows 10 1809 이상, Windows Server 2019 이상Windows 11 권장, 최신 Windows 10은 "최선 노력" 지원
프로세서x64 또는 ARM64, 32비트 불가x64 또는 ARM64
계정유료 Claude 요금제 또는 Console 계정ChatGPT 요금제 또는 OpenAI API 키
Node.jsnpm 방식만, 22 이상npm 방식만
Git for Windows선택 사항필요 없음
네이티브 Windows 샌드박스없음, WSL 2에서만있음, 자체 Windows 샌드박스
설치 시 관리자 권한필요 없음필요 없음

이 표에서 의외인 점이 두 가지입니다. Claude Code는 더 이상 Git for Windows를 요구하지 않고, 없으면 PowerShell을 셸 도구로 씁니다. 그리고 Codex는 네이티브 Windows에서도 명령을 샌드박스에 격리하지만, Claude Code는 WSL 2 안에서만 그렇습니다.

Windows에 Claude Code 설치하기

Anthropic의 설치 페이지는 네 가지 방법을 안내합니다. 권장 방법은 네이티브 설치 프로그램으로, Node.js가 필요 없고 백그라운드에서 스스로 업데이트됩니다.

방법명령어
PowerShell(권장)irm https://claude.ai/install.ps1 | iex
CMDcurl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
WinGetwinget install Anthropic.ClaudeCode
npm(Node.js 22+)npm install -g @anthropic-ai/claude-code@latest

방법별로 남는 것:

  • 네이티브 설치 프로그램: claude.exe는 %USERPROFILE%\.local\bin에, 버전들은 %USERPROFILE%\.local\share\claude에 들어갑니다. .local\bin이 PATH에 없으면 경고만 하고 추가해 주지는 않습니다.
  • WinGet: 자동 업데이트가 없습니다. winget upgrade Anthropic.ClaudeCode로 업데이트하며, Anthropic에 따르면 Windows가 실행 파일을 잠그기 때문에 Claude Code가 실행 중이면 업데이트가 실패할 수 있습니다.
  • npm: Node.js가 22보다 오래되면 설치 끝에 EBADENGINE 경고가 나옵니다.

최신보다 한 릴리스 뒤에 머물려면 stable 채널을 쓰세요.

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

설치를 확인합니다. claude --version은 버전을 출력하고, claude doctor는 설치와 설정을 읽기 전용으로 진단합니다.

Git for Windows가 있으면 Claude Code는 C:\Program Files\Git, C:\Program Files (x86)\Git, PATH의 git 순서로 Git Bash를 찾습니다. 다른 것을 강제하려면 settings.json의 env 블록에 CLAUDE_CODE_GIT_BASH_PATH를 설정하세요. git-bash.exe가 아니라 bash.exe 또는 sh.exe라는 파일을 가리켜야 합니다.

Windows에 Codex CLI 설치하기

OpenAI의 Windows 페이지는 분명합니다. 기본은 Windows 샌드박스와 함께 네이티브 Codex, 도구가 이미 Linux에 있으면 WSL입니다. 뒤처진 출처가 하나 있는데, GitHub 저장소의 설치 페이지에는 아직 "Windows 11 via WSL2"라고 적혀 있습니다. 공식 문서도 설치 프로그램도 이미 바뀌었습니다.

방법명령어
PowerShell 설치 프로그램powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
npmnpm install -g @openai/codex

쉬운 쪽은 PowerShell 설치 프로그램입니다. 스크립트를 보면 Codex를 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin에 설치하고, 이 폴더를 사용자 PATH와 현재 세션에 추가한 뒤, 새 PowerShell 창을 열라고 안내합니다. 같은 명령을 다시 실행하면 Codex가 업데이트됩니다. npm도 설치 명령을 다시 실행하면 됩니다.

이제 로그인합니다. codex를 실행해 Sign in with ChatGPT를 고르거나 codex login을 실행하세요. 브라우저가 없는 컴퓨터에서는 codex login --device-auth가 다른 기기에 입력할 코드를 줍니다. codex login status는 어떤 계정으로 로그인했는지 알려 줍니다.

Windows 샌드박스

Codex는 Windows에서 세 가지 샌드박스 구현을 제공합니다.

  • mxc: 권장 구현으로, 관리자 설정이 필요 없습니다. Windows 11 24H2(빌드 26100.9278) 또는 25H2(빌드 26200.9278)가 필요합니다.
  • elevated: 우선 대안입니다. 관리자가 승인하는 일회성 설정이 필요합니다.
  • unelevated: 네트워크 격리가 약하고, 읽기 전용 경로가 없습니다.

선택은 config.toml에서 합니다.

[features]
prefer_mxc = true

[windows]
sandbox = "elevated" # or "unelevated"

샌드박스가 오류 1385로 실패하면 Windows가 샌드박스 계정의 로그온 유형을 거부한 것으로, OpenAI는 이때 CODEX_HOME/.sandbox/sandbox.log를 요청합니다. .sandbox-secrets/의 내용은 절대 공유하지 마세요.

네이티브 Windows와 WSL 중 무엇을?

네이티브(PowerShell, CMD)WSL 2
Claude Code 설치irm https://claude.ai/install.ps1 | iexWSL 안에서 curl -fsSL https://claude.ai/install.sh | bash
Codex 설치PowerShell 설치 프로그램WSL 안에서 curl -fsSL https://chatgpt.com/codex/install.sh | sh
Claude Code 샌드박스쓸 수 없음쓸 수 있음, bubblewrap과 socat 필요
Codex 샌드박스Windows 샌드박스Linux 샌드박스
저장소 위치어디든/mnt/c/가 아니라 ~/ 아래

프로젝트를 어차피 Linux에서 빌드하고 실행하거나, Claude Code가 실행하는 명령을 샌드박스에 격리하고 싶다면 WSL 2를 고르세요. .NET, PowerShell 스크립트, Windows 경로투성이인 Windows 프로젝트라면 네이티브가 맞습니다.

WSL을 쓴다면 지킬 규칙 세 가지:

  1. WSL 2만, WSL 1은 쓰지 않기. Codex는 0.115 버전부터 WSL 1을 지원하지 않습니다. Claude Code의 샌드박스는 Sandboxing requires WSL2로 WSL 1을 거부하고, WSL 1에서 설치하면 Exec format error로 실패할 수 있습니다. 배포판은 wsl --set-version <DistroName> 2로 변환하세요.
  2. 설치도 실행도 WSL 안에서. Linux 명령은 PowerShell이 아니라 WSL 터미널에서 실행하세요. exec: node: not found는 WSL에서 Windows의 Node.js를 실행할 때 생깁니다. Node.js는 배포판 안에 패키지 관리자나 nvm으로 설치하세요.
  3. 코드는 Linux 파일 시스템에. 두 업체 모두 저장소를 /mnt/c/ 밖에 두라고 하며, Anthropic은 거기서 Claude Code의 검색이 덜 완전하다고 밝힙니다. Linux 홈 디렉터리 아래에 클론하세요.

"claude를 인식하지 못함" 오류와 그 밖의 오류

보이는 것원인해결
'claude' is not recognized as an internal or external command(CMD), The term 'claude' is not recognized(PowerShell)%USERPROFILE%\.local\bin이 PATH에 없음사용자 PATH에 추가(아래 명령)한 뒤 새 터미널 열기
추가한 뒤에도 인식되지 않음터미널이나 이를 감싼 에디터가 변경 전에 시작됨터미널(에디터 안이면 에디터도) 다시 열기
업데이트 직후 인식되지 않음교체 도중 중단된 업데이트가 claude.exe를 남기지 않음가장 최근 claude.exe.old.*의 이름을 claude.exe로 되돌리기(아래 명령)
'irm' is not recognizedPowerShell 줄을 CMD에 붙여 넣음PowerShell을 열거나 CMD 줄 쓰기
The token '&&' is not a valid statement separatorCMD 줄을 Windows PowerShell에 붙여 넣음PowerShell 줄 쓰기
npm.ps1 cannot be loaded because running scripts is disabled on this system실행 정책이 npm의 PowerShell 래퍼를 막음Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser, 또는 npm.cmd 호출
64비트 PC인데 32비트 Windows 관련 오류시작 메뉴에서 "Windows PowerShell (x86)"을 엶일반 64비트 PowerShell 열기
claude가 CLI 대신 데스크톱 앱을 엶예전 Claude 데스크톱 앱이 WindowsApps에 둔 Claude.exe가 PATH에서 CLI보다 앞에 있음Claude 데스크톱 앱 업데이트
requires either Git for Windows (for bash) or PowerShellClaude Code가 두 셸 모두 찾지 못함Git for Windows를 설치하거나, PowerShell이 PATH에 있는지 확인
npm install 중 EBADENGINENode.js가 22보다 오래됨Node.js를 업데이트하거나 네이티브 설치 프로그램 쓰기

PowerShell에서 현재 사용자의 PATH를 고치는 명령(관리자 권한 불필요):

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

바꾸기 전에 Windows가 어디를 찾는지 확인하려면:

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
where.exe claude

망가진 업데이트 뒤 이름 되돌리기:

Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

실행 정책에 대해: Windows에 기본 포함된 Windows PowerShell 5.1은 클라이언트 PC에서 기본값이 Restricted라서 새 노트북이 npm.ps1을 막습니다. CurrentUser 범위는 관리자 권한이 필요 없습니다. 네이티브 Claude 설치 프로그램과 Codex 설치 프로그램은 영향이 없습니다. irm | iex와 -ExecutionPolicy ByPass는 디스크에서 스크립트 파일을 불러오지 않기 때문입니다.

업데이트와 제거

Claude CodeCodex CLI
지금 업데이트claude update(네이티브), winget upgrade Anthropic.ClaudeCode, 또는 npm 설치 다시 실행지원하는 릴리스에서는 codex update, PowerShell 설치 프로그램 다시 실행, 또는 npm install -g @openai/codex
자동 업데이트네이티브 설치만, DISABLE_AUTOUPDATER=1로 끔문서에 없음
제거%USERPROFILE%\.local\bin\claude.exe와 %USERPROFILE%\.local\share\claude 삭제, 또는 winget uninstall Anthropic.ClaudeCode, 또는 npm uninstall -g @anthropic-ai/claude-code설치 폴더 삭제, 또는 npm uninstall -g @openai/codex
남는 설정%USERPROFILE%\.claude와 %USERPROFILE%\.claude.json%USERPROFILE%\.codex

Windows에서 에이전트 CLI를 돌리며 배운 것

AgentsRoom은 Claude Code, Codex 등 에이전트 CLI를 나란히 실행합니다. 그 Windows 버전에서 이런 설치가 터미널 밖에서 어디서 깨지는지 배웠습니다. 저희 앱을 쓰지 않아도 알아 둘 만한 네 가지입니다.

시작 메뉴에서 실행한 프로그램은 시작할 때의 PATH를 계속 씁니다. Claude Code를 설치하고 .local\bin을 PATH에 추가해도, 이미 열린 데스크톱 앱은 claude를 찾지 못합니다. CLI를 대신 실행하는 앱에는 터미널 재시작만으로는 부족합니다. AgentsRoom은 CLI를 찾을 때 사용자와 컴퓨터의 PATH를 레지스트리에서 다시 읽어, 방금 성공한 설치를 없다고 하지 않습니다.

npm은 .exe를 설치하지 않습니다. npm install -g @openai/codex는 %APPDATA%\npm에 codex, codex.cmd, codex.ps1 세 파일을 씁니다. codex를 직접 실행하는 프로그램은 spawn codex ENOENT를 받습니다. Windows는 확장자 없는 이름에 .exe만 붙여 보기 때문입니다. PowerShell과 CMD는 PATHEXT를 읽어서 터미널에서는 드러나지 않습니다. 실행 파일을 제대로 설치하는 네이티브 설치 프로그램을 쓸 이유가 하나 더 있습니다.

npm 래퍼는 실행할 때 Node.js가 필요합니다. 같은 세션에서 Node.js와 CLI를 이어서 설치하면, Node.js가 PATH에 들어가기 전에 시작된 프로그램에서는 .cmd 래퍼를 찾고도 "node is not recognized"로 실패합니다. 래퍼가 비활성 버전을 가리키는 Node 버전 관리자에서도 증상은 같습니다.

Windows에서는 프로세스 시작 비용이 훨씬 큽니다. 측정해 보니 프로세스 생성에 Windows는 2080 ms, macOS는 13 ms가 걸렸고, 백신 검사 때문에 파일 확인 한 번의 비용도 더 큽니다. 초기 CLI 감지는 모든 폴더, 이름, 확장자를 시도해 Windows에서 앱을 최대 1초 멈추게 했습니다. 폴더마다 한 번만 읽도록 바꿔 해결했습니다.

앱에서는 설치 도우미가 빠진 CLI를 OS에 맞는 공식 설치 프로그램으로 설치하고(Claude Code는 irm https://claude.ai/install.ps1 | iex, Codex는 OpenAI의 스크립트), 실패하면 npm으로 대체하며, 지켜볼 수 있는 터미널에서 실행합니다. CLI가 시작되지 않으면 CLI Doctor가 오류와 실제 실행된 명령을 읽고 무엇이 깨졌는지 알려 줍니다. 두 CLI가 --version에 응답하면 시작 가이드가 이어받고, 앱이 Windows에서 하는 일은 Windows 출시 소식에 있습니다.

자주 묻는 질문

Windows에 Claude Code를 설치하려면 어떻게 하나요?

PowerShell을 열고 irm https://claude.ai/install.ps1 | iex를 실행하세요. CMD는 Anthropic 설치 페이지의 install.cmd 줄, WinGet은 winget install Anthropic.ClaudeCode입니다. 바이너리는 %USERPROFILE%\.local\bin에 들어가는데, 설치 프로그램은 이 폴더를 PATH에 추가하지 않습니다. claude가 인식되지 않으면 직접 추가한 뒤 새 터미널을 열고 claude --version을 실행하세요.

Windows에서 Claude Code나 Codex를 쓰려면 WSL이 필요한가요?

아니요. 둘 다 Windows 10과 11의 PowerShell이나 CMD에서 네이티브로 동작합니다. WSL 2는 프로젝트가 이미 Linux에 있거나, 네이티브 Windows에서 동작하지 않는 Claude Code의 샌드박스를 쓰고 싶을 때 의미가 있습니다. WSL 1이 아닌 WSL 2를 쓰세요. Codex는 0.115 버전에서 WSL 1 지원을 중단했습니다.

설치 직후인데 Windows가 'claude'를 인식하지 못하는 이유는 무엇인가요?

네이티브 설치 프로그램은 claude.exe를 %USERPROFILE%\.local\bin에 두고, 이 폴더가 PATH에 없으면 경고를 표시하지만 PATH 자체는 바꾸지 않습니다. 이 폴더를 사용자 PATH에 추가하고 터미널을 다시 여세요(터미널이 에디터 안에 있으면 에디터도). 이미 열린 터미널은 예전 PATH를 그대로 씁니다.

Claude Code에 Git for Windows가 필요한가요?

이제는 필요 없습니다. Anthropic 설치 페이지에서 Git for Windows는 선택 사항입니다. 없으면 Claude Code는 PowerShell을 셸 도구로 씁니다. 있으면 Claude Code가 C:\Program Files\Git에서 Git Bash를 찾고, CLAUDE_CODE_GIT_BASH_PATH 설정으로 다른 bash.exe를 지정할 수 있습니다.

Node.js 없이 Windows에 Codex CLI를 설치할 수 있나요?

네. OpenAI의 PowerShell 설치 프로그램은 독립 실행형 Codex를 내려받아 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin에 두고, 이 폴더를 사용자 PATH에 추가합니다. Node.js가 필요한 건 npm 방식, 즉 npm install -g @openai/codex뿐입니다.

설치할 때 PowerShell과 CMD 중 무엇을 써야 하나요?

PowerShell입니다. 공식 한 줄 명령은 둘 다 PowerShell용이고, 흔한 오류는 대부분 PowerShell 줄을 CMD에 붙여 넣거나 그 반대일 때 생깁니다. 'irm' is not recognized(한국어 Windows에서는 "'irm'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다.")가 뜨면 CMD에 있는 것이고, '&&' is not a valid statement separator가 뜨면 PowerShell에 있는 것입니다. 시작 메뉴의 "Windows PowerShell (x86)"이 아니라 64비트 PowerShell을 쓰세요.

DevOps 엔지니어콘텐츠 에디터프론트엔드 개발자영업 담당자백엔드 개발자코치·트레이너소프트웨어 아키텍트법무 담당QA 엔지니어재무·총무풀스택 개발자크리에이티브 디자이너모바일 개발자리서처보안 엔지니어인사·채용
프로젝트 매니저번역가Git 전문가데이터 분석가SEO 전문가회계 담당자로컬라이제이션 전문가홍보·PR브레인스토머운영·물류마케팅 전문가고객 지원프로젝트 어시스턴트구매 담당자커뮤니티 매니저개인 비서

AgentsRoom 다운로드

모든 AI 에이전트를, 모든 프로젝트에서, 하나의 창으로 실행하세요.

AgentsRoom 다운로드무료

컴패니언 앱: 이동 중에도 에이전트를 모니터링

Claude, Codex, Antigravity CLI 또는 다른 AI 공급자를 사용하세요.

확장 프로그램 설치
Chrome Web Store

버그와 요청을 공개 백로그로 바로 보내세요.

대화처럼 읽는 에이전트

에이전트마다 역할과 얼굴이 있고, 메신저 앱처럼 스레드를 읽을 수 있습니다.

대화 보기

AgentsRoom 대화 보기: AI 코딩 에이전트의 작업이 채팅 스레드로 표시된 화면
멀티 프로젝트
멀티 프로바이더
멀티 에이전트
실시간 상태
파일 diff & 커밋
모바일 앱
라이브 프리뷰
에이전트 팀
브라우저 자동화
백로그 기반 개발
프롬프트 라이브러리
스킬 라이브러리
모든 기능 보기

계속 읽기