“코딩도 이제 AI가 터미널에서 뚝딱? 윈도우 환경 Claude Code 오류 해결과 활용법”

터미널 안으로 들어온 AI, 개발 방식이 완전 바뀌었습니다

요즘 개발자 커뮤니티에서 가장 핫한 화두를 하나 꼽으라면 단연 ‘터미널 기반 AI 에이전트’일 겁니다. 기존에는 브라우저를 열고 ChatGPT나 Claude 웹 화면에 코드를 복사해서 붙여넣고, 수정된 코드를 다시 내 프로젝트로 가져오는 번거로운 과정을 거쳐야 했죠.

하지만 앤트로픽(Anthropic)에서 선보인 Claude Code를 접하고 나서는 개발 흐름이 아예 달라졌습니다. 터미널 명령 줄 하나로 내 프로젝트 파일 구조를 이해하고, 직접 코드를 수정하며, 브라우저까지 띄워 테스트해 주는 모습은 사뭇 충격적이었습니다.

하지만 윈도우(Windows 11) 환경에서 이 도구를 세팅하는 과정은 생각보다 만만치 않았습니다. 온갖 권한 에러와 환경 변수 문제 때문에 몇 번이나 막혔었는데요. 제가 직접 겪은 시행착오와 해결책, 그리고 또 다른 강력한 후보인 Gemini CLI와의 솔직한 비교까지 한 번에 정리해 드립니다.

1. 윈도우 터미널 처음 켤 때 무조건 터지는 오류 2가지

새로운 도구를 설치하려 할 때 가장 먼저 우리를 좌절시키는 건 까만 화면에 뜨는 붉은색 에러 메시지입니다. 저도 처음에 똑같이 겪었던 대표적인 오류 2가지와 확실한 해결법입니다.

① git : 'git' 용어가 cmdlet, 함수... 오류 발생 시

터미널에서 git clone을 입력했는데 명령어를 찾을 수 없다는 에러가 나온다면, 십중팔구 시스템에 Git이 설치되어 있지 않거나 환경 변수(PATH) 연결이 끊어진 상태입니다.

• 해결법:
  1. Git 공식 홈페이지(git-scm.com)에 접속해서 64-bit Windows용 Git을 다운로드하여 설치합니다.
  2. 설치할 때 옵션은 기본값(Default)으로 넘어가도 무방합니다.
  3. 가장 중요한 점: 설치가 끝난 후 열려 있던 PowerShell 창을 완전히 닫고 새 창으로 다시 열어야 환경 변수가 적용됩니다.
  4. git --version을 입력해서 버전 숫자가 정상적으로 출력되면 해결입니다.

② 이 시스템에서 스크립트를 실행할 수 없으므로... 보안 오류

PowerShell에서 .ps1 스크립트를 실행할 때 자주 마주치는 이 문제는 윈도우의 기본 보안 정책(ExecutionPolicy)이 외부 스크립트 실행을 막고 있기 때문에 발생합니다.

• 해결법:시스템 전체 보안 설정을 영구적으로 훼손하지 않으면서 해결하는 가장 안전한 방법은 현재 열려 있는 터미널 세션에만 임시 권한을 부여하는 것입니다. 아래 명령어를 현재 PowerShell에 복사해 넣으세요.

PowerShell

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

이 명령은 현재 터미널 창을 닫으면 자동으로 효력이 소멸하므로 보안 걱정 없이 설치를 계속 진행할 수 있습니다.

2. Windows PowerShell 어떤 걸 써야 할까?

윈도우 11 검색창에 ‘PowerShell’을 검색하면 여러 프로그램이 나와서 당황스러울 수 있습니다. 각각의 차이점을 명확히 정리해 드립니다.

💡 실무 에디터 팁:

윈도우 11 사용자라면 기본 제공되는 ‘터미널(Terminal)’ 앱을 실행하거나, 개발 작업 시 VS Code 내부 터미널을 이용하는 것이 가장 깔끔하고 편합니다.

3. Claude Code 설치 및 인증 세팅

환경 준비가 끝났다면 본격적으로 Claude Code CLI 도구를 설치해 볼 차례입니다.

PowerShell 명령어 순서대로 실행하기

다운로드한 압축 파일(예: gateway-cli-*.zip)을 해제하고 스크립트를 실행하는 과정입니다. 터미널에 순서대로 입력합니다.

PowerShell

# 1. 다운로드 폴더에 있는 압축 파일 해제
Expand-Archive -Path "$env:USERPROFILE\Downloads\gateway-cli-0.1.0-windows-amd64.zip" -DestinationPath "$env:USERPROFILE\Downloads\gateway-cli" -Force

# 2. 압축 해제된 폴더로 이동
cd "$env:USERPROFILE\Downloads\gateway-cli"

# 3. 임시 스크립트 실행 권한 부여
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

# 4. 설치 스크립트 실행
.\install.ps1

최초 1회 SSO 계정 로그인 인증

설치가 완료되면 사내 망이나 게이트웨이 서버와 연결하기 위한 인증 절차가 필요합니다. 아래 형태로 명령어를 입력해 줍니다.

PowerShell

gateway-cli login --issuer-url https://your-auth-issuer-url.com --client-id YOUR_CLIENT_ID --admin-api-url https://your-admin-api-url.com

명령어를 실행하면 자동으로 웹 브라우저가 열립니다. 로그인 과정을 마치면 터미널에 Login successful 메시지가 뜨며 인증 토큰이 안전하게 저장됩니다.

4. 환경 설정 파일(.claude/settings.json) 손쉽게 만들기

Claude Code가 제대로 작동하려면 사용자 홈 디렉터리에 .claude/settings.json 파일이 존재해야 합니다. 여기서 ~ 표시나 $HOME은 윈도우 사용자 계정 기본 폴더(C:\Users\내계정명)를 의미합니다.

리눅스나 맥처럼 cat 명령어가 익숙하지 않은 윈도우 사용자를 위해, PowerShell에서 바로 폴더와 설정 파일을 생성하는 명령어 스크립트입니다.

PowerShell

# 1. .claude 디렉터리 생성
New-Item -ItemType Directory -Path "$HOME\.claude" -Force

# 2. settings.json 파일 생성 (UTF-8 인코딩)
@'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-api-gateway-url.com"
  },
  "apiKeyHelper": "api-key-helper"
}
'@ | Out-File -FilePath "$HOME\.claude\settings.json" -Encoding utf8

5. 실전 테스트: 자연어로 웹 계산기 앱 3분 만에 만들기

설정을 마쳤으니 실제 성능을 시험해 볼 차례입니다.

⚠️ 시작 전 주의사항: 작업 디렉터리 이동

PowerShell을 처음 켜자마자 claude를 실행하면 현재 위치가 C:\WINDOWS\system32로 지정되어 있을 수 있습니다. 시스템 중요한 폴더에서 AI 에이전트를 작동시키면 파일 변경 시 심각한 오류가 생길 수 있으니, 반드시 개인 전용 작업 폴더를 만들고 이동해서 실행하세요.

PowerShell

# 전용 작업 폴더 생성 및 이동
mkdir C:\claude-workspace
cd C:\claude-workspace

# Claude Code 실행
claude

실행 시 Is this a project you created or one you trust? 라는 보안 안내 메시지가 나오면 1. Yes, I trust this folder를 선택해 줍니다.

🚀 3단계 프롬프트 실습

Claude Code 프롬프트(>) 창에 아래 내용을 순서대로 요청해 보세요.

1. 1단계 (기본 코드 작성):“HTML, CSS, JavaScript를 사용해서 깔끔하고 모던한 디자인의 웹 계산기를 만들어줘. index.html 파일 하나로 작성해 줘.”(팁: 파일 생성/수정 권한을 물어보는 팝업이 뜨면 2. Yes, allow all edits during this session을 누르면 매번 허용하지 않고 알아서 연속으로 코드를 작성해 줍니다.)
2. 2단계 (기능 고도화 요청):“계산기 아래쪽에 이전에 계산한 기록(History)이 리스트로 남는 기능이랑, 기록 전체 삭제 버튼도 추가해 줘.”
3. 3단계 (결과물 확인):“완성된 index.html 파일을 내 기본 웹 브라우저로 띄워줘.”

직접 테스트해 보면, 프롬프트 입력 몇 번 만에 코딩부터 파일 생성, 수정, 그리고 브라우저 실행까지 일괄적으로 완벽히 처리되는 것을 확인할 수 있습니다.

6. Claude Code vs Gemini CLI 솔직 비교

AI 개발 도구를 선택할 때 가장 많이 비교되는 두 축은 Anthropic의 Claude와 Google의 Gemini입니다. 직접 사용하며 느낀 두 도구의 차이점입니다.

📊 주요 특징 비교표

Gemini CLI도 터미널에서 써보고 싶다면?

Gemini 역시 웹 인터페이스(gemini.google.com) 외에 터미널 환경에서 CLI 도구로 활용할 수 있습니다.

PowerShell

# Gemini CLI 전역 설치
npm install -g @google/gemini-cli

# API 키 설정 후 실행
$env:GEMINI_API_KEY="본인의_GEMINI_API_KEY"
gemini "웹 계산기 index.html 파일을 작성해줘"

7. 자주 묻는 질문 (FAQ)

Q1. 실행할 때마다 파일 수정 권한 팝업이 계속 떠서 불편해요.

A: 팝업 발생 시 2. Yes, allow all edits during this session을 선택해 현재 세션 동안 일괄 승인하거나, Claude 실행 시 claude --dangerously-skip-permissions 플래그를 붙여 실행하면 권한 확인 단계를 건너뛸 수 있습니다.

Q2. .claude/settings.json 파일은 왜 설정해야 하나요?

A: 사내 망이나 엔터프라이즈 게이트웨이를 통해 AI 모델을 호출할 때 필요한 API 엔드포인트(ANTHROPIC_BASE_URL) 및 인증 도구 헬퍼를 유기적으로 연결하기 위한 필수 작업입니다.

Q3. PowerShell에서 claude 명령어가 실행되지 않습니다.

A: Node.js 기반 환경이라면 npm 전역 패키지 경로가 윈도우 환경 변수(PATH)에 잘 추가되어 있는지 확인한 후, PowerShell 창을 완전히 닫았다가 다시 켜보세요.

💡 마치며

Windows 11 환경에서 Claude Code나 Gemini CLI 같은 터미널 에이전트를 구축해 두면, 반복적인 boilerplate 코딩이나 환경 세팅 시간을 획기적으로 줄일 수 있습니다.

단순히 질문을 주고받는 AI를 넘어, 내 개발 환경에서 직접 움직이는 파트너를 원하신다면 이번 가이드를 따라 차근차근 구축해 보시길 강력히 추천합니다!

전문가의 인사이트 : 함께 읽어 보세요.

회사 컴퓨터에서 리눅스 테스트 서버 만들기: WSL2 Rocky Linux 9 설치

참조 및 출처 URL:

https://platform.claude.com/docs/en/home