AI 코딩 CLI 설치 길잡이: 계정별 도구 고르기와 첫 설정 4가지

Claude 구독만 있는데 Codex CLI부터 깔면, 설치는 끝나도 로그인에서 더 나아가지 못합니다. 설치는 누구나 할 수 있어도 로그인을 넘으려면 도구마다 맞는 계정이나 API 키가 필요하거든요. 그래서 저는 무엇을 깔지보다 이미 무엇을 결제했는지부터 보길 권합니다.

답은 간단합니다. Claude 유료 플랜이 있으면 Claude Code, ChatGPT 유료 플랜이 있으면 Codex CLI부터 까세요.

Gemini CLI는 2026년 6월 18일부터 무료 이용자와 Google AI Pro·Ultra 구독자의 요청을 처리하지 않으니, 그런 계정이라면 Antigravity CLI로 갑니다. 설치는 셋 다 명령 한 줄이고, 깐 날에는 지시 파일과 실행 경계 두 가지만 정하면 돼요.

설치 명령은 2026년 9월 21일, Gemini CLI 계정 조건은 9월 28일에 공식 문서와 저장소에서 확인했습니다. 세 도구를 한 컴퓨터에 같이 둔 모습은 10월 17일 Windows 11 · PowerShell 5.1 테스트 환경에서 확인했고, 도구별 설치 출력과 오류 해결은 아래 글에 있습니다.

상황별로 먼저 열 글

처음 까는 중이든, 깔다가 멈췄든, 업데이트가 안 되든 찾는 답은 대개 아래 중 하나에 있습니다.

처음 깔 때:

• Windows에서 Claude Code를 처음 깐다 → PowerShell 한 줄 설치부터 첫 작업, 자주 나는 오류 6가지까지
• 터미널 대신 데스크톱 앱으로 쓸지 고민된다 → Claude 앱·Claude Code·Cowork 중 하려는 일별로 무엇을 열지
• Codex CLI를 깐다 → npm과 Homebrew 중 무엇으로 깔지와 로그인 전 명령 구조
• Gemini CLI를 무료 계정이나 Google AI Pro·Ultra로 쓰고 있었다 → Antigravity CLI를 설치하고 기존 GEMINI.md·AGENTS.md를 옮기는 법
• Gemini CLI를 조직 라이선스나 유료 API 키로 쓴다 → 설치 경로 비교와 인증 방식 세 가지 고르는 기준

막혔을 때:

• Windows에서 claude가 안 먹힌다 → Windows 설치 오류 6가지의 증상별 순서, 폴더 이름의 공백·한글이 문제라면 Windows 경로 문제 글
• claude는 찾는데 버전 대신 안내문이 나오거나, Illegal instruction이 뜨거나, 로그인 코드가 거부된다 → Claude Code 설치·로그인 오류를 단계별로 가르는 글
• Codex CLI 설치가 실패한다(npm 전역 폴더 소유자 문제가 가장 흔함) → Codex CLI 설치 글의 오류 절, 실행 중 401 Unauthorized가 나면 Codex CLI 오류 7가지
• Gemini CLI 로그인이 멈춘다 → 종료 코드 41·55·1로 계정 문제와 환경 변수 문제를 가르는 법
• 업데이트했는데 버전이 그대로다 → Claude Code 설치 방식별 업데이트 명령

어디서 막혔는지부터 모르겠다면 AI 코딩 CLI 오류 해결 길잡이에서 증상으로 먼저 가르세요.

가진 계정으로 도구 고르기

맨 앞의 이야기를 표로 옮기면 이렇습니다.

이미 가진 것	먼저 깔 도구	알아 둘 것
Claude 유료 플랜(Pro·Max 등)	Claude Code	무료 플랜은 미포함
ChatGPT 유료 플랜(Plus 이상)	Codex CLI	“Sign in with ChatGPT” 선택
Gemini 조직 라이선스, 유료 Gemini API 키	Gemini CLI	6월 18일 이후에도 사용 가능
무료 Google 계정, Google AI Pro·Ultra	Antigravity CLI	Gemini CLI 요청 처리 중단
어느 회사든 API 키	그 회사의 CLI	플랜 대신 API 키로 로그인

Gemini CLI 쪽은 메인테이너 Dmitry Lyalin이 2026년 5월 19일 공식 저장소 토론 글에서 공지했습니다. 무료 이용자와 Google AI Pro·Ultra 구독자의 요청은 6월 18일부터 처리하지 않고, 이들은 Antigravity CLI로 옮기라는 안내예요.

계속 쓸 수 있는 쪽은 Gemini Code Assist Standard·Enterprise 라이선스, Google Cloud로 쓰는 조직, 유료 Gemini API 키 사용자입니다.

회사·학교·Workspace 계정은 길이 하나 더 있습니다. Gemini CLI는 이런 조직 계정과 Gemini Code Assist 라이선스에 Google Cloud 프로젝트 설정을 따로 요구합니다. 개인 계정은 대부분 필요 없지만 모두가 그런 것은 아니며, 실제로 막힌 사례는 Gemini CLI 인증 방식 글에 모아 두었습니다.

셋 중 하나만 고를 필요는 없습니다. 명령 이름이 claude·codex·gemini로 달라서 셋을 한 컴퓨터에 같이 깔아도 충돌하지 않고, 프로젝트마다 다른 도구를 불러도 돼요.

10월 17일 테스트 환경의 Windows 11에는 세 CLI가 같이 깔려 있었습니다. PowerShell에서 Get-Command와 --version으로 보면 이렇습니다.

명령	--version	실행 파일 위치
claude	2.1.296 (Claude Code)	%APPDATA%\npm\claude.ps1(npm)
codex	codex-cli 0.162.1	%APPDATA%\npm\codex.ps1(npm)
agy	1.3.4	%LOCALAPPDATA%\agy\bin\agy.exe(설치 프로그램)

npm으로 깐 둘은 같은 폴더에 .ps1 래퍼로, Antigravity CLI는 따로 설치 폴더에 있었고 서로 덮어쓰지 않았어요. npm 설치본은 PowerShell 실행 정책에 걸릴 수 있으니, 그때는 Windows 설치 글의 실행 정책 절을 보세요. 실제로 갈리는 건 매달 나가는 돈이라, 비용이 궁금하면 Claude Code 비용·한도 길잡이를 함께 보세요.

설치, 확인, 그리고 업데이트

1. 설치 명령을 실행합니다

주 설치 경로만 모았습니다. Homebrew·WinGet 같은 다른 경로와 실제 출력은 각 도구 글에 있습니다.

Claude Code(Windows PowerShell):

irm https://claude.ai/install.ps1 | iex

Claude Code(macOS·Linux):

curl -fsSL https://claude.ai/install.sh | bash

Codex CLI(macOS는 brew install --cask codex도 됩니다):

npm install -g @openai/codex

Gemini CLI(설치 없이 한 번 써 보려면 npx @google/gemini-cli):

npm install -g @google/gemini-cli

2. 새 터미널을 열고 버전을 확인합니다

이미 열려 있던 터미널에는 설치 프로그램이 바꾼 PATH가 반영되지 않습니다. 재부팅하면 풀리는 것처럼 보이는 것도 이 때문인데, 새 터미널만 열어도 같아요.

• Claude Code: claude --version, 더 자세히는 claude doctor
• Codex CLI: codex --version, 더 자세히는 codex doctor
• Gemini CLI: gemini --version(0.59.0 기준 진단 명령은 없음)

새 터미널에서도 안 되면 설치 경로가 PATH에 들어갔는지 봅니다. 피할 것은 같은 도구를 두 가지 방법으로 두 번 까는 거예요. 네이티브와 npm으로 둘 다 깔았다면 어느 쪽이 실행되는지 헷갈리므로 하나만 남기세요.

3. 업데이트 방법을 알아 둡니다

9월 8~13일에 쓴 세 도구의 설치 글을 2026년 9월 21일에 공식 문서와 한 줄씩 맞대 직접 확인한 결과, 설치·확인 명령은 그대로였고 달라진 것은 npm 설치본의 업데이트 명령 하나였습니다. 오래된 설치 글은 설치 한 줄이 맞아도 업데이트 절이 틀려 있을 수 있다는 얘기죠.

• npm으로 깐 Claude Code는 npm update -g 대신 npm install -g @anthropic-ai/claude-code@latest로 올립니다. npm update -g는 처음 설치할 때의 버전 범위를 지켜 최신으로 안 올라갈 수 있습니다.
• Claude Code npm 패키지는 v2.1.198부터 Node.js 22 이상이 필요합니다. 낮은 버전에서는 설치가 실패하지 않고 경고만 내고 넘어가니, 깔렸는데 이상하면 Node.js 버전부터 봅니다.
• Claude Code 네이티브 설치본은 백그라운드에서 스스로 올라가지만, Homebrew·WinGet·Linux 패키지 매니저로 깐 것은 기본적으로 자동으로 올라가지 않습니다.
• Codex CLI는 버전이 래퍼 패키지·플랫폼 패키지·실행 파일 세 곳에 따로 있어, 업데이트했다는 표시와 실제로 도는 버전이 다를 수 있습니다.

깐 날 정해 둘 것

로그인까지 끝나면 바로 일을 시킬 수 있습니다. 다만 아래 1·2를 안 해 두면 같은 설명을 세션마다 반복하고, 사소한 명령마다 승인을 누르게 돼요. 3·4는 필요해질 때 해도 늦지 않습니다.

1. 매번 하는 설명을 지시 파일로 옮깁니다

세 도구 모두 프로젝트 폴더의 지시 파일을 자동으로 읽습니다. 빌드 명령, 코드 규칙, 하지 말아야 할 일을 적어 둡니다.

• Claude Code: CLAUDE.md를 어디에 두고 /init 초안을 어디까지 줄일지
• Gemini CLI: GEMINI.md를 어느 위치에 두어야 실제로 읽히는지
• 한 저장소를 여러 도구로 쓸 때: CLAUDE.md·AGENTS.md·GEMINI.md가 겹치는 곳과 갈라지는 곳

2. 무엇을 묻지 않고 실행하게 둘지 정합니다

기본값은 안전한 쪽이라 그대로 두면 승인을 자주 누르게 되고, 넓게 열면 열어 둔 줄 몰랐던 것까지 열립니다.

• Claude Code 규칙: allow·deny 규칙의 평가 순서와 자주 새는 패턴
• Claude Code 프로세스 격리: 샌드박스를 켜는 법과 권한 규칙과의 차이
• Codex CLI: 샌드박스 모드와 승인 정책 조합이 각각 무엇을 막는지
• 세 도구 비교: 샌드박스가 감싸는 범위

3. 외부 도구가 필요해지면 MCP로 붙입니다

데이터베이스를 조회하거나 이슈 트래커를 읽게 하고 싶어질 때 붙입니다. 연결 방법은 stdio·HTTP 설정과 local·project·user 범위에 있습니다. 범위를 잘못 고르면 혼자 쓸 서버를 팀 전체에 커밋하게 되니 조심하세요.

4. 쌓이는 데이터는 가끔 정리합니다

에이전트는 대화 기록과 스냅샷을 계속 남기고, 처음엔 안 보이다가 용량으로 드러납니다. 지워도 되는 것은 .claude 안에서 무엇이 읽히고 무엇이 쌓이기만 하는지에 갈라 두었습니다.

마치며

세 도구를 놓고 보면 설치 자체는 어느 쪽이든 한 줄이라, 고민할 건 설치 방법보다 계정과 그 뒤의 첫 설정입니다. 이미 결제한 계정에 맞는 도구를 하나 깔고, 새 터미널에서 버전을 확인한 다음, 지시 파일과 실행 경계만 정해 두면 첫날은 충분해요.

설치를 마쳤다면 지금 작업하는 프로젝트 폴더에 지시 파일부터 하나 만들어 빌드 명령과 코드 규칙을 적어 두세요. 그다음 무엇을 얼마나 맡길지는 Claude Code 자동화 길잡이에서 이어서 정하면 됩니다.