윈도우 PowerShell에서 AI CLI 도구 실행이 막힐 때: Claude Code·Codex 설치 후 바로 푸는 순서

윈도우 PowerShell에서 AI CLI 도구 실행이 막힐 때 대부분은 도구 자체 문제가 아니라 PowerShell의 실행 정책, npm의 .ps1 래퍼, PATH 설정 중 하나가 원인입니다. Claude Code, OpenAI Codex CLI, Gemini CLI, Vercel v0 계열 CLI를 설치했는데 running scripts is disabled가 뜬다면 먼저 CurrentUser 범위에서 실행 정책을 확인하면 됩니다.

오류 문구를 기준으로 실행 정책, PATH, 인증 문제를 나눠 점검해 보세요. 먼저 CurrentUser 범위의 RemoteSigned부터 확인하는 것이 가장 빠릅니다.

빌더 입장에서는 이 오류가 은근히 치명적입니다. AI 에이전트에게 코드 수정 지시를 내리려는 순간 터미널이 막히면, 문제는 프롬프트가 아니라 개발 환경이 됩니다. 아래 순서대로 점검하면 대개 5분 안에 원인을 좁힐 수 있습니다.

가장 먼저 확인할 것: 실행 정책과 npm.ps1

PowerShell에서 Node 기반 CLI를 실행하면 실제로는 claude.ps1, codex.ps1, npm.ps1 같은 스크립트가 호출되는 경우가 많습니다. 윈도우가 이 스크립트 실행을 제한하면 AI CLI가 설치되어 있어도 실행되지 않습니다.

1) 현재 실행 정책 확인

Get-ExecutionPolicy -List

CurrentUser가 Restricted이거나 아무 값도 없다면, 사용자 범위에서만 완화하는 편이 안전합니다.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

이 설정은 내 계정에만 적용됩니다. 회사 장비라면 보안 정책이 있을 수 있으니 관리자 권한으로 전체 시스템을 바꾸기 전에 팀 정책을 확인하는 게 좋습니다.

2) 당장 한 번만 실행해야 한다면 Bypass

설정 변경이 부담스럽거나 테스트만 할 때는 현재 세션에서만 우회할 수 있습니다.

powershell -ExecutionPolicy Bypass

또는 VS Code 터미널에서 새 PowerShell 세션을 열고 명령을 다시 실행해 보세요. 이 방식은 영구 변경이 아니라 임시 확인용으로 적합합니다.

직접 겪은 셋업: Claude Code와 Codex CLI가 동시에 막힌 경우

monstereae에서 윈도우 노트북에 Node.js LTS를 설치하고 Claude Code와 OpenAI Codex CLI를 테스트할 때, 설치는 정상인데 실행에서 막힌 적이 있었습니다. 오류는 도구별로 다르게 보였지만 핵심은 같았습니다. PowerShell이 npm이 만든 .ps1 파일을 실행하지 못한 것입니다.

이때 제가 쓴 순서는 단순했습니다. 먼저 node -v, npm -v로 Node 설치를 확인하고, 그다음 Get-ExecutionPolicy -List를 봤습니다. 마지막으로 RemoteSigned를 CurrentUser에만 적용한 뒤 터미널을 완전히 닫았다가 다시 열었습니다.

그 후에는 Claude Code에서 프로젝트 폴더를 열고, Codex CLI는 별도 테스트 폴더에서 실행했습니다. 같은 터미널에서 여러 도구를 섞어 실행하면 인증 토큰, 작업 디렉터리, PATH 문제를 헷갈리기 쉽습니다.

해결 방식 비교: 어떤 방법을 써야 할까

도구별로 자주 보이는 막힘 포인트

Claude Code

프로젝트 폴더 권한과 Git 상태를 함께 봐야 합니다. 실행 정책을 풀었는데도 명령이 안 잡히면 where claude로 실제 실행 파일 위치를 확인하세요. 글로벌 설치 경로가 PATH에 없으면 재부팅이나 터미널 재시작이 필요할 수 있습니다.

OpenAI Codex CLI

인증 관련 오류와 실행 정책 오류를 구분해야 합니다. codex 명령이 아예 실행되지 않으면 PowerShell 또는 PATH 문제이고, 실행은 되지만 모델 호출에서 막히면 API 키나 로그인 상태를 봐야 합니다.

Cursor·VS Code 터미널

앱 안의 터미널은 기존 환경 변수를 물고 있을 때가 있습니다. Node.js를 새로 설치했다면 Cursor나 VS Code를 완전히 종료한 뒤 다시 열어야 합니다. 단순히 탭만 닫는 것으로는 PATH가 갱신되지 않을 수 있습니다.

이런 사용자에게는 이 선택을 추천합니다

개인 프로젝트를 자주 만드는 빌더라면 CurrentUser + RemoteSigned가 가장 현실적입니다. 매번 우회 명령을 치는 것보다 Claude Code, Codex, Gemini CLI를 안정적으로 호출하는 편이 작업 흐름을 덜 끊습니다.

회사 지급 노트북이라면 보안 정책을 먼저 확인하세요. 실행 정책이 그룹 정책으로 잠겨 있으면 개인이 바꿔도 다시 되돌아갈 수 있습니다. 이 경우 Git Bash, CMD, WSL 중 허용된 터미널을 쓰는 편이 안전합니다.

윈도우가 익숙하지만 리눅스 배포 환경도 고려한다면 WSL을 추천합니다. 특히 Docker, Supabase CLI, Vercel CLI, n8n 로컬 테스트를 같이 돌리는 워크플로에서는 WSL이 나중에 덜 꼬입니다.

흔한 실수: Unrestricted로 풀어버리기

검색하다 보면 Set-ExecutionPolicy Unrestricted를 바로 쓰라는 글도 보입니다. 하지만 AI CLI를 실행하려는 목적이라면 대개 필요하지 않습니다. 최소 범위인 CurrentUser에 RemoteSigned를 적용하는 것부터 시작하세요.

또 하나의 실수는 관리자 PowerShell에서만 해결하고 일반 터미널에서는 다시 막히는 경우입니다. 실제로 사용할 터미널, 예를 들어 Cursor 내 PowerShell이나 Windows Terminal에서 같은 명령을 확인해야 합니다.

FAQ

Q. RemoteSigned는 안전한가요?

완전히 위험이 없는 설정은 아니지만, 윈도우에서 개발 도구를 쓰는 현실적인 범위에서는 자주 쓰입니다. 핵심은 LocalMachine 전체가 아니라 CurrentUser에만 적용하는 것입니다.

Q. npm install은 됐는데 명령어를 못 찾는다고 나옵니다.

그 경우는 실행 정책보다 PATH 문제일 가능성이 큽니다. npm config get prefix로 글로벌 설치 경로를 확인하고, Windows 환경 변수 Path에 해당 경로가 포함되어 있는지 보세요.

Q. PowerShell 대신 Git Bash를 써도 되나요?

됩니다. 다만 일부 AI CLI 문서가 PowerShell 기준 명령을 제공할 수 있으니, 경로 표기와 환경 변수 설정 방식이 다르다는 점만 주의하면 됩니다.

지금 할 일

오류가 running scripts is disabled라면 먼저 아래 3줄만 순서대로 확인하세요.

Get-ExecutionPolicy -List
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
where npm

그다음 터미널을 닫고 다시 열어 AI CLI 명령을 실행해 보세요. 그래도 막히면 오류 문구가 바뀌었는지 확인하는 것이 다음 단서입니다. 실행 정책 오류가 사라졌다면 이제 인증, PATH, 도구별 설정 문제로 범위를 좁히면 됩니다.

관련 링크

• ai api 비용 비교: 사이드프로젝트 챗봇 만들 때 실제로 갈리는 지점
• ai 자동화 수익화 사례: 작은 리서치 봇을 팔 수 있는 워크플로로 바꿔본 기록
• ai 툴 교육, 팀이 바로 써먹게 만들려면 ChatGPT보다 워크플로부터 잡아야 합니다
• 관련 태그 더 보기
• 카테고리 더 보기
• 검색 결과 더 보기
• 참고 링크