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 Code | Codex CLI | |
|---|---|---|
| Windows 버전 | Windows 10 1809 이상, Windows Server 2019 이상 | Windows 11 권장, 최신 Windows 10은 "최선 노력" 지원 |
| 프로세서 | x64 또는 ARM64, 32비트 불가 | x64 또는 ARM64 |
| 계정 | 유료 Claude 요금제 또는 Console 계정 | ChatGPT 요금제 또는 OpenAI API 키 |
| Node.js | npm 방식만, 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 |
| CMD | curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd |
| WinGet | winget 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" |
| npm | npm 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 | iex | WSL 안에서 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을 쓴다면 지킬 규칙 세 가지:
- 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로 변환하세요. - 설치도 실행도 WSL 안에서. Linux 명령은 PowerShell이 아니라 WSL 터미널에서 실행하세요.
exec: node: not found는 WSL에서 Windows의 Node.js를 실행할 때 생깁니다. Node.js는 배포판 안에 패키지 관리자나 nvm으로 설치하세요. - 코드는 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 recognized | PowerShell 줄을 CMD에 붙여 넣음 | PowerShell을 열거나 CMD 줄 쓰기 |
The token '&&' is not a valid statement separator | CMD 줄을 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 PowerShell | Claude Code가 두 셸 모두 찾지 못함 | Git for Windows를 설치하거나, PowerShell이 PATH에 있는지 확인 |
npm install 중 EBADENGINE | Node.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 Code | Codex 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을 쓰세요.
AgentsRoom 다운로드
모든 AI 에이전트를, 모든 프로젝트에서, 하나의 창으로 실행하세요.
컴패니언 앱: 이동 중에도 에이전트를 모니터링
Claude, Codex, Antigravity CLI 또는 다른 AI 공급자를 사용하세요.
버그와 요청을 공개 백로그로 바로 보내세요.
계속 읽기
Codex, OpenCode, Antigravity, Claude Code의 음성 모드: 어떤 CLI에 있을까?
2026년 10월 13일에 코딩 에이전트 CLI 다섯 개와 앱 두 개를 확인했습니다. Codex CLI와 oh-my-pi는 음성으로 대화하고, Claude Code와 Antigravity CLI는 프롬프트에 받아쓰기만 하며, OpenCode에는 내장된 것이 없습니다. 각각을 시작하는 방법, 오디오가 어디로 가는지, 그리고 음성이 토큰으로 얼마나 드는지 정리했습니다.
기사 읽기Claude Code vs Codex CLI: 2026년에는 무엇을 골라야 할까 (그리고 왜 둘 다 쓰는 게 정답인가)
Claude Code와 Codex CLI를 솔직하게 비교한다. 가격, 속도, MCP, 통제권까지. 그리고 몇 주를 써보고 나서 왜 둘 중 하나를 고르길 그만뒀는지 이야기한다.
기사 읽기Git 커밋에서 Co-Authored-By Claude를 제거하는 방법
Claude Code는 커밋에 Co-Authored-By trailer를, 풀 리퀘스트에 Generated with Claude Code 한 줄을 붙입니다. 이를 없애는 설정, 그 설정을 넣을 파일, 이미 푸시한 커밋을 정리하는 방법을 알아봅니다.
기사 읽기
