AI 코딩 CLI 오류 해결 길잡이: 설치·로그인·한도·MCP 증상별 순서

설치는 끝났는데 claude를 치니 빨간 글씨가 뜹니다. 보통은 그 문구를 그대로 검색하죠. 그런데 같은 문구라도 막힌 자리가 다르면 해결책이 정반대일 수 있어서, 검색 결과를 따라 하기 전에 어디서 막혔는지부터 가르는 편이 훨씬 빠릅니다.

순서는 단순해요. 먼저 claude doctor나 codex doctor를 돌리고, 그다음 두 가지만 봅니다.

--version이 버전을 찍지 않으면 설치·PATH 문제, 버전은 찍히는데 대화가 시작되지 않으면 로그인·계정 문제예요. 대화는 되는데 요청이 거부되면 한도, 붙인 MCP 서버만 안 보이면 MCP 설정, 오류 없이 설정이 안 먹으면 설정 파일을 보면 됩니다.

이 사이트 글에 실린 오류 사례를 다시 세어 보니 43건 중 18건이 도구가 시작되기도 전, 설치·셸·경로에서 났습니다. 막히면 설치 쪽부터 의심하세요.

진단 명령은 2026년 9월 21일 공식 문서 기준이고, 사례 건수와 분류는 9월 23일까지 발행한 글에 실린 사례를 다시 세어 직접 확인한 결과입니다. 여러 도구의 설치 층을 한 번에 가르는 확인은 10월 17일 Windows 11 · PowerShell 5.1에서 돌려 봤습니다. 오류마다 실제 출력과 해결 순서는 링크한 글에 있어요.

어디서 막혔는지부터

같은 “not found”라도 'claude' is not recognized는 도구가 PATH에 없는 것이고, Executable not found in $PATH는 도구는 멀쩡한데 붙인 MCP 서버의 실행 파일이 없는 것입니다. 문구만 보고 검색하면 엉뚱한 해결책을 따라 하기 쉬워요. 아래 그림 순서대로 위에서부터 확인해 보세요.

1. 진단 명령 돌리기

진단 명령은 Claude Code가 claude doctor, Codex CLI가 codex doctor입니다. claude doctor는 세션을 시작하지 않고 설치 상태, 설정 파일 검증 오류, 경고와 권장 조치를 읽기 전용으로 보여 줘요. codex doctor는 설치·설정·인증·네트워크를 점검하는데, 로그인 전에는 인증과 네트워크만 비정상으로 나오니 나머지가 정상인지 먼저 확인할 수 있습니다.

Gemini CLI에는 같은 명령이 없습니다(0.59.0 기준). gemini --help의 명령 목록에 진단 명령이 없어서, gemini --version부터 보고 아래 질문으로 직접 가릅니다.

2. --version이 버전을 찍나

안 찍히면 층 1(설치·셸·경로)입니다. 도구가 시작조차 못 한 상태라 인증이나 설정은 볼 필요가 없어요.

PowerShell이라면 여러 도구를 한 번에 볼 수 있습니다. 10월 17일 Windows 11 · PowerShell 5.1 테스트 환경에서 돌린 결과예요.

foreach ($c in 'claude','codex','agy','gemini') {
  if (Get-Command $c -ErrorAction SilentlyContinue) { "{0,-7} {1}" -f $c, (& $c --version 2>&1 | Select-Object -First 1) }
  else { "{0,-7} (설치·PATH 확인 필요)" -f $c }
}

claude  2.1.296 (Claude Code)
codex   codex-cli 0.162.1
agy     1.3.4
gemini  (설치·PATH 확인 필요)

깔지 않은 gemini만 걸렸고, 그대로 gemini --version을 치면 CommandNotFoundException 오류가 났습니다. 버전이 찍힌 셋은 층 1을 지난 것이니 다음 질문으로 넘어가면 됩니다. 같은 자리에서 claude doctor와 codex doctor --summary의 종료 코드도 둘 다 0이었어요.

3. 실행하면 대화가 시작되나

안 되면 층 2(로그인·계정·네트워크)입니다. 대화는 되는데 요청이 거부되면 층 3(한도), 붙인 MCP 서버만 안 보이면 층 4(MCP), 오류 없이 설정이 안 먹으면 층 5(설정)고요.

여러 층에 걸친 것 같으면 위에서부터 보세요. 설치본이 둘이면 고친 쪽과 실제로 실행되는 쪽이 달라서, 아래층을 아무리 고쳐도 반응이 없는 것처럼 보이거든요.

버전이 안 찍힐 때

층 1의 오류는 도구가 아니라 셸이나 패키지 매니저가 냅니다. 43건 중 18건으로 가장 많은 층이에요.

• 'irm' is not recognized, The token '&&' is not a valid statement separator — 명령에 맞지 않는 셸에서 쳤습니다. 프롬프트 앞에 PS가 있는지 보세요. → Claude Code Windows 설치 오류 6가지
• 'claude' is not recognized as the name of a cmdlet — PATH에 아직 없습니다. 새 터미널을 열고, 그래도 안 되면 PATH에 들어갔는지 보세요. 재부팅하면 풀리는 것처럼 보이는 것도 이 때문입니다. → 같은 글
• EACCES: permission denied, mkdir …, Unable to locate … binaries — npm 전역 설치 폴더의 소유자 문제입니다. → Codex CLI 설치 글, Gemini CLI 설치 글
• Error: claude native binary not installed., Illegal instruction — 명령은 찾았지만 실행 파일이 자리표시자이거나 CPU·아키텍처와 맞지 않습니다. → Claude Code 설치·로그인 오류 글
• 업데이트했는데 버전이 그대로 — Codex CLI는 버전이 세 곳에 따로 있어 npm ls -g와 codex --version이 다를 수 있습니다. Claude Code는 claude doctor로 지금 도는 설치본부터 확인하세요. → 설치 방식별 업데이트 명령
• $'\r': command not found, 폴더 이름의 공백·한글에서 깨짐 — Windows 경로와 줄 끝 문자 문제입니다. → 공백·한글·CRLF가 깨뜨리는 곳
• 오류 없이 한글만 깨짐 — Windows PowerShell 5.1의 기본 인코딩 때문입니다. → 프로필 네 줄과 BOM 저장으로 고치는 법

대화가 시작되지 않을 때

층 2(7건)는 오류 문구가 계정 문제인지 설정 문제인지 알려 주지 않아서 헷갈립니다. 그래서 먼저 볼 건 몇 개가 막혔느냐예요. 세 도구 중 하나만 막히면 그 도구의 계정이나 인증 경로를, 셋이 동시에 막히면 네트워크나 인증서를 먼저 보세요.

• Claude Code: OAuth error: Invalid code, API Error: 403, 구독이 살아 있는데 조직이 비활성이라고 나옴 — 마지막 것은 계정 문제처럼 보이지만, 환경 변수에 남은 ANTHROPIC_API_KEY가 구독 자격 증명을 덮은 것입니다. → Claude Code 설치·로그인 오류 글
• Codex CLI: 401 Unauthorized: Missing bearer와 401 Unauthorized: Incorrect API key provided — 앞의 것은 요청에 인증 정보가 아예 없고, 뒤의 것은 서버가 키를 거부한 것입니다. → Codex CLI 오류 7가지
• Gemini CLI: 로그인 실패, 종료 코드 41·55·1 — 종료 코드로 계정 쪽인지 환경 변수 쪽인지 먼저 가릅니다. GOOGLE_CLOUD_PROJECT를 지워서 풀린 사례와 넣어서 풀린 사례가 둘 다 있어요. → Gemini CLI 인증 오류 글
• Gemini CLI를 무료 계정이나 Google AI Pro·Ultra로 쓰던 중 — 설정보다 계정 자격이 먼저입니다. 이 이용자들의 요청은 2026년 6월 18일부터 처리되지 않는다고 메인테이너가 공식 저장소 토론 글에서 공지했습니다(9월 28일 확인). → Antigravity CLI로 옮기는 법
• 브라우저 승인까지 했는데 토큰 교환에서 인증서 오류로 끊김 — 회사 네트워크가 TLS 트래픽을 가로채는 환경입니다. 계정을 바꿔도 풀리지 않아요.

대화는 되는데 막힐 때

여기부터는 한도, MCP, 설정 셋 중 하나입니다.

요청이 거부되면 문구부터

층 3(5건)은 문구가 갈래를 정확히 알려 주는 유일한 층입니다. 그런데 대충 읽고 “한도에 걸렸다”로 뭉뚱그리기 쉬워요. 제가 보기엔 그게 가장 흔한 실수입니다.

• 어느 한도인지 모르겠다 — 전체 이용자 대상 용량(529), 서버의 단기 스로틀, 플랜 한도, 키·프로젝트에 설정한 한도, 결제 상한이 각각 다른 문구를 씁니다. → 한도·과부하 오류 메시지별 해결
• 한도에 자주 걸린다 → /usage 화면과 5시간·주간 한도, Claude Code 비용·한도 길잡이
• Codex에서 한도에 걸린다 → 5시간·주간 한도의 남은 양과 리셋 시각 보는 법

MCP 서버만 안 될 때

층 4(8건)는 도구는 멀쩡하고 붙인 서버만 동작하지 않는 경우입니다. 상태 줄 끝부터 읽어 보세요.

• 상태 기호 뒤에 실패 문구가 붙어 있다 — 연결 실패입니다. 문구가 실행 파일·서버 프로세스·URL·자격 증명 중 어디를 볼지 알려 줘요. → MCP 서버 연결 실패 오류 4가지
• 서버 이름이 목록에 아예 없거나 승인 대기 상태다 — 설정을 못 읽은 것입니다. 등록 범위를 잘못 골랐을 가능성이 커요. → stdio·HTTP 설정과 local·project·user 범위
• Antigravity CLI에서 서버가 안 보인다 → agy mcp add와 설정 파일 위치

오류가 아무것도 없을 때

층 5(5건)는 화면에 아무것도 안 떠서 찾기가 가장 어렵습니다. 설정이 읽혔는지부터 보세요. claude doctor가 조용하다는 건 설정이 스키마에 맞는다는 뜻일 뿐, 적용됐다는 뜻은 아니거든요.

• 훅이 목록에 안 보인다, 발동하지 않는다, 고친 설정이 세션에 반영되지 않는다, “다시 묻지 않음”을 골랐는데 또 묻는다 → 무엇이 읽혔는지부터 보는 설정 진단 순서
• 훅이 목록에 있고 매처도 맞는데 조용하다 → 훅이 어디서 멈췄는지 4단계 점검
• deny 규칙을 넣었는데 그 파일이 읽히거나 고쳐진다 — Read·Edit deny 규칙은 파일 이름을 대지 않고 읽는 명령이나 스스로 파일을 여는 하위 프로세스에는 적용되지 않습니다. 모든 프로세스를 막으려면 샌드박스를 켜세요. → allow·deny 규칙에서 자주 새는 패턴, 샌드박스와 권한 규칙의 차이

실행 중에 Claude Code process exited with code 137로 끊기는 건 이 분류 밖입니다. 프로세스가 강제 종료 신호를 받은 것이고, 원인을 찾는 순서는 exit code 137 글에 따로 정리했어요.

그래도 안 풀려서 물어볼 때

남에게 묻거나 이슈를 올릴 때 아래 내용을 같이 적으면, 답하는 쪽이 처음부터 다시 묻지 않아도 됩니다.

1. 도구 버전: claude --version·codex --version·gemini --version 중 해당하는 것
2. 설치 방법: 네이티브, npm, 패키지 매니저 중 무엇인지
3. 종료 코드: 실행 직후 Linux·macOS는 echo $?, Windows PowerShell은 $LASTEXITCODE
4. 오류 문구 전문: 요약하지 말고 그대로. (not your usage limit) 같은 괄호 안 문구가 갈래를 정하기도 합니다
5. 어디까지 배제했는지: “버전은 찍힌다”, “대화는 시작된다” 두 문장이 층 1과 층 2를 한 번에 지웁니다

주의: 진단 명령 출력에는 설정 파일 경로가 그대로 찍힙니다. 붙이기 전에 계정 이름, 홈 폴더 경로, 키 값이 섞여 있지 않은지 먼저 보세요.

마치며

오류를 만나면 문구부터 검색하고 싶어지는 게 당연하지만, 그 전에 --version과 첫 대화 두 가지만 확인해 보세요. 그것만으로 다섯 층 중 어디를 볼지가 정해집니다. 사례 43건 중 18건이 설치 단계에서 났다는 숫자도, 막혔을 때 어디부터 의심할지 알려 준다고 생각해요.

지금 막혀 있다면 터미널을 새로 열고 claude --version(또는 쓰는 도구의 --version)부터 실행해 보세요. 같은 문제가 반복된다면, 막히지 않게 미리 세워 두는 방법을 Claude Code 자동화 길잡이에서 이어 보시면 됩니다.