AI 에이전트 설치 2026: 맥·윈도우 설치 순서부터 첫 로그인, 막힐 때 해결법까지 한 번에
AI 에이전트 설치 2026: 맥·윈도우 설치 순서부터 첫 로그인, 막힐 때 해결법까지 한 번에
AI 에이전트: 에이전트(스스로 판단해 작업을 처리하는 AI) 가운데 내 컴퓨터에 설치해서 파일을 읽고, 고치고, 명령까지 실행하는 프로그램을 말해요. 질문에 답만 하는 채팅 AI와 달리 시킨 일을 끝까지 해 주는 쪽에 가깝습니다.
어떤 AI 에이전트를 깔아야 하나요?
AI 에이전트라는 말은 들었는데 정작 무엇을 깔아야 할지 모르는 분이 많아요. 내 컴퓨터에 직접 설치해서 쓰는 대표 에이전트는 2개예요.
첫째는 Claude Code예요. Anthropic(앤트로픽, 클로드를 만든 AI 회사)이 만들었어요. Anthropic 공식 개요 문서는 이렇게 소개해요.
"an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools"
작업 폴더의 코드를 읽고, 파일을 고치고, 명령을 실행하고, 개발 도구와 이어지는 코딩 도구라는 뜻이에요.
둘째는 Codex(코덱스, 코딩을 대신 해주는 AI 도구) CLI(명령어를 타이핑해서 쓰는 까만 화면 프로그램)예요. OpenAI(오픈에이아이, 챗지피티를 만든 회사)가 만들었어요. Codex 공식 README에 따르면 이렇게 정의돼요.
"Codex CLI is a coding agent from OpenAI that runs locally on your computer."
OpenAI가 만든 코딩 에이전트이고 내 컴퓨터에서 직접 돌아간다는 뜻이에요.
둘 중 하나만 깔아도 충분해요. 처음이라면 Claude Code부터 따라 하세요. 클로드 코드만 더 자세히 보고 싶다면 클로드 코드 설치 가이드도 있어요. 이 글의 앞부분이 그 순서이고, 코덱스는 뒤에서 따로 설명해요. 기억할 점은 Claude Code는 무료 요금제로 쓸 수 없고, 코덱스는 무료 요금제에서 CLI가 아니라 데스크톱 앱만 안내돼 있다는 거예요. 조건은 아래 절에 정리했어요.
설치 전에 무엇이 필요한가요?
Anthropic 공식 설치 문서에 따르면 Claude Code를 쓰려면 아래 조건을 갖춰야 해요.
| 항목 | 필요한 것 |
|---|---|
| 맥 | macOS 13.0 이상 |
| 윈도우 | Windows 10 1809 이상 |
| 메모리 | 4GB 이상 |
| 계정 | Pro, Max, Ultra, Team, Enterprise 요금제 또는 Console 계정 |
계정 조건이 가장 자주 발목을 잡아요. 같은 문서에 이런 문장이 있어요.
"The free claude.ai plan does not include Claude Code access."
무료 claude.ai 요금제는 Claude Code를 쓸 수 있는 권한이 없다는 뜻이에요. 그래서 설치와 별개로, 무료 계정으로는 Claude Code를 쓸 수 없어요.
Claude 요금 페이지 기준으로 Pro는 월 20달러이고, 연간 결제하면 월 17달러(200달러를 먼저 결제)예요. 2026년 11월 12일 공식 요금 페이지 기준이고, 세금은 별도이며, 바뀔 수 있어요. 지금 가격은 Claude 요금제 페이지에서 확인하세요.
Node.js(노드제이에스, 프로그램을 돌리는 바탕 소프트웨어)는 필요 없어요. npm(엔피엠, 프로그램 설치 도구)으로 설치하는 길은 Node.js 22 이상을 요구하고(구버전이면 경고가 뜨지만 설치는 된다고 안내돼 있어요), 이 글에서 쓰는 공식 권장 방식에는 해당하지 않아요.
터미널은 어떻게 여나요?
터미널(명령어를 글자로 입력해 컴퓨터를 조종하는 창)은 처음 열면 낯설어요. 그래도 키 2개를 같이 누르는 것으로 시작하면 돼요. 터미널이 부담스럽다면 Claude Code 데스크톱 앱으로 터미널 없이 쓰는 길도 있어요. 이 글은 터미널 방식을 따라 해요. Anthropic 터미널 가이드에 소개된 여는 방법은 아래와 같아요.
맥에서 여는 순서예요.
- Cmd + Space 키를 같이 눌러요. 검색창이 떠야 앱 이름을 입력할 수 있어요.
- Terminal을 입력해요. 터미널 앱을 찾기 위해서예요.
- Enter 키를 눌러요. 그러면 글자를 입력하는 창이 열려요.
윈도우에서 여는 순서예요.
- Win + X 키를 같이 눌러요. 작은 메뉴가 떠야 터미널 항목을 고를 수 있어요.
- Windows PowerShell(파워셸, 윈도우의 명령어 입력 프로그램) 또는 Terminal을 골라요. 이 창에서 명령을 입력해요.
창이 열렸는지는 맨 앞 글자로 알 수 있어요. PowerShell이면 줄 앞에 PS C:\Users\이름> 처럼 PS가 붙어요. CMD(윈도우의 옛 명령어 입력 프로그램)라면 PS 없이 C:\Users\이름> 로 시작해요. 둘은 쓰는 설치 명령이 달라서 이 구분이 중요해요.
맥에서는 어떻게 설치하나요?
macOS 13.0 이상이면 아래 순서로 설치해요. 명령은 1개예요.
- 위에서 연 터미널에 아래 명령을 붙여넣고 Enter를 눌러요.
curl -fsSL https://claude.ai/install.sh | bash
이 명령은 공식 설치 파일을 내려받아 바로 실행해요. 한 줄로 설치가 끝나게 해 주는 공식 권장 방식이에요.
- 기다려요. 설치하는 동안 진행 표시가 나오지 않아요. 멈춘 것처럼 보여도 정상이에요.
- 끝나면 새 터미널 창을 열어요. 새 창이어야 컴퓨터가 방금 설치한 프로그램을 알아봐요.
이 방식으로 설치하면 백그라운드에서 자동으로 업데이트돼요. 반대로 Homebrew(홈브루, 맥용 프로그램 설치 도구)나 WinGet(윈젯, 윈도우용 프로그램 설치 도구)으로 설치하면 자동 업데이트가 안 돼서 직접 갱신해야 해요.
윈도우에서는 어떻게 설치하나요?
Windows 10 1809 이상이어야 해요. 관리자 권한으로 실행할 필요는 없어요. 방법은 2개이고, 앞에서 확인한 창에 맞는 쪽을 골라요.
PowerShell(줄 앞에 PS가 보이는 창)이라면 아래 명령을 붙여넣고 Enter를 눌러요.
irm https://claude.ai/install.ps1 | iex
이 명령은 PowerShell 전용이고, 설치 파일을 내려받아 실행해요.
CMD(줄 앞에 PS가 없는 창)라면 아래 명령을 써요.
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
이 명령은 설치 파일을 내려받고, 실행하고, 남은 파일을 지우는 일을 한 줄에서 차례로 해요.
설치 중에는 맥과 마찬가지로 진행 표시가 없어요. 끝나면 새 창을 열어요. 창을 헷갈려서 엉뚱한 명령을 넣으면 오류가 나는데, 해결법은 아래 「처음 하면 여기서 막힙니다」에 모아 뒀어요.
설치가 됐는지, 첫 로그인은 어떻게 하나요?
새 터미널 창에서 명령 2개로 설치를 확인한 뒤 로그인해요.
- 먼저 버전을 확인해요.
claude --version
이 명령은 설치된 버전 번호를 보여 줘요. 예를 들어 2.1.211 (Claude Code) 같은 형태로 찍혀요. 2.1.211은 공식 문서에 나온 예시일 뿐 최신 버전이 아니에요. 번호가 달라도 숫자가 나왔다면 성공이에요.
- 필요하면 상태를 점검해요.
claude doctor
이 명령은 대화 창을 열지 않고 설치 상태만 점검해요. 버전이 안 찍히거나 이상할 때 써요.
- 이제 로그인해요.
claude
이 명령으로 Claude Code를 처음 실행해요. 안내에 따라 브라우저 창이 1개 열리고, 거기서 계정으로 로그인하면 돼요. 앞에서 본 대로 Pro 같은 유료 요금제 계정이 있어야 Claude Code를 쓸 수 있어요.
로그인이 끝나면 AI 에이전트 설치가 끝난 거예요. 이제 원하는 작업 폴더에서 claude를 실행해 일을 시키면 돼요.
코덱스는 어떻게 설치하나요?
Codex 공식 README에 따르면 명령은 운영체제별로 달라요. 맥과 리눅스는 아래 한 줄이에요.
curl -fsSL https://chatgpt.com/codex/install.sh | sh
이 명령은 코덱스 설치 파일을 내려받아 실행해요. 윈도우는 아래 한 줄을 써요.
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
이 명령은 PowerShell을 띄워 설치 파일을 받아 실행해요. 위 방법이 안 맞으면 대안이 있어요. 아래 두 줄 중 하나를 골라요.
npm install -g @openai/codex
brew install --cask codex
첫 줄은 npm으로, 둘째 줄은 Homebrew로 설치하는 명령이에요. 이렇게 설치 명령은 모두 4개가 나와 있어요.
설치가 끝나면 작업할 폴더에서 터미널을 열고 아래 명령으로 실행해요.
codex
이 명령이 코덱스를 처음 실행하고, 로그인 선택 화면을 띄워요. 여기서 ChatGPT(챗지피티, 오픈AI가 만든 대화형 AI) 계정으로 로그인하는 항목인 "Sign in with ChatGPT"를 골라요.
요금 조건은 꼭 확인해야 해요. OpenAI 요금 페이지 기준으로 ChatGPT Plus는 월 20달러이고 Go는 월 8달러예요. 다만 Free와 Go 요금제의 코덱스는 데스크톱 앱에서 단계적으로 제공된다고 적혀 있어요. 웹, CLI, 코드 편집기 확장 프로그램, 아이폰 앱에서 쓸 수 있다고 CLI가 명시된 건 Plus 항목부터예요. 2026년 11월 12일 공식 요금 페이지 기준이고, 바뀔 수 있어요. 지금 조건은 Codex 요금 안내에서 확인하세요.
처음 하면 여기서 막힙니다
Anthropic 문제 해결 문서는 오류 문구별 해결법을 표로 정리해 뒀어요. 아래 증상 중 앞의 7개는 그 문서에 적힌 것이고, 마지막 하나는 공식 설치 문서의 요금제 조건에서 온 것이에요. 오류 문구는 화면에 나온 그대로 찾아보세요.
command not found: claude 또는 'claude' is not recognized가 떠요
PATH(컴퓨터가 프로그램 위치를 찾는 길 목록) 문제예요. 먼저 새 터미널 창을 열고 다시 시도해요. 그래도 안 되면 설치된 폴더를 PATH에 추가해야 해요.
'irm' is not recognized가 떠요
CMD에서 PowerShell 명령을 입력한 거예요. 줄 앞에 PS가 보이는 PowerShell을 열어서 다시 실행하거나, CMD용 명령을 쓰세요.
The token '&&' is not a valid statement separator가 떠요
반대로 PowerShell에서 CMD 명령을 입력한 거예요. &&가 들어간 긴 명령은 CMD용이에요. PowerShell에서는 irm으로 시작하는 명령을 쓰세요.
A parameter cannot be found that matches parameter name 'fsSL'이 떠요
윈도우 PowerShell에 맥용 명령(curl -fsSL)을 넣었을 때 나와요. 윈도우에서는 위 「윈도우에서는 어떻게 설치하나요?」의 명령을 쓰세요.
syntax error near unexpected token '<' 또는 403이 떠요
설치 주소가 설치 파일 대신 웹페이지나 오류 응답을 돌려줘서 생긴 오류예요. 403만 보이면 회사 네트워크의 프록시(중간에서 인터넷 연결을 대신 처리하는 서버)나 방화벽이 막은 경우도 있어요. 몇 분 뒤에 다시 시도하세요. 그래도 안 되면 Homebrew나 WinGet으로 설치하는 대안이 있어요. 다만 지원 국가인데 403만 계속 뜬다면 다른 설치 방법도 같은 서버에 접속하니, 회사 네트워크와 프록시 설정부터 점검하세요. 오류에 App unavailable in region이 함께 보이면 사용하는 나라가 지원 대상이 아니라는 뜻이에요.
64비트 PC인데 32비트 오류가 떠요
Claude Code는 32비트 윈도우를 지원하지 않아요. 64비트 PC에서 'Windows PowerShell (x86)' 항목을 열면 이 오류가 나요. x86이 붙지 않은 항목으로 다시 열어 보세요.
로그인 뒤 API(프로그램끼리 정보를 주고받는 연결 통로) 오류 403이 떠요
로그인 뒤 아래 문구가 나오면 구독 상태를 확인해야 해요.
API Error: 403
claude.ai의 설정 화면에서 구독이 활성인지 확인하세요. 회사 네트워크의 프록시가 요청을 막을 때도 생길 수 있어요.
무료 요금제 계정으로는 Claude Code가 안 돼요
고장이 아니라 요금제 조건 때문이에요. 위에서 인용한 문장처럼 무료 claude.ai 요금제에는 Claude Code가 들어 있지 않아요. 유료 요금제로 올리거나, 비용이 부담되면 코덱스 쪽 조건을 비교해 보세요.
마무리
AI 에이전트 설치는 운영체제 확인, 터미널 열기, 명령 1개 붙여넣기, 새 창에서 버전 확인, 로그인 순서로 끝나요. 막히는 곳은 거의 창과 명령이 안 맞거나 요금제가 맞지 않는 경우예요. 오류 문구를 그대로 검색하면 해결법이 대부분 공식 문서에 있어요. 설치를 마쳤다면 AI 에이전트 사용법 글로 이어 가세요.
자주 묻는 질문
AI 에이전트 설치에는 얼마나 걸리나요?
필자 추정으로는 30분 정도 잡아 두면 여유가 있어요. 공식 문서에 정해진 소요 시간은 없어요. 설치 중에는 진행 표시가 없으니 멈춘 것처럼 보여도 기다리세요.
무료로 쓸 수 있나요?
Claude Code는 무료 claude.ai 요금제로는 쓸 수 없어요. 유료 요금제가 필요해요. 코덱스도 CLI가 명시된 건 Plus 요금제부터예요. 금액은 2026년 11월 12일 공식 요금 페이지 기준으로 Claude Pro가 월 결제 기준 월 20달러, ChatGPT Plus가 월 20달러, Go가 월 8달러이고 바뀔 수 있어요.
윈도우에서 irm이나 && 오류가 나면 어떻게 하나요?
창과 명령이 서로 맞지 않는 거예요. irm으로 시작하는 명령은 줄 앞에 PS가 보이는 PowerShell에서, &&가 들어간 긴 명령은 CMD에서 써요.
설치가 됐는지 어떻게 알 수 있나요?
새 터미널 창에서 claude --version을 실행해 버전 번호가 나오면 설치된 거예요. 상태를 더 자세히 보려면 claude doctor를 실행해요.
터미널 없이 쓸 수 있나요?
Claude Code는 데스크톱 앱으로 터미널 없이 쓰는 길이 있어요. 코덱스는 Free와 Go 요금제에서 데스크톱 앱만 안내돼 있고, 단계적으로 적용되는 중이에요.


