OpenAI Codex CLI 사용 한도 초과 — Gemini로 즉시 대체하는 법

오늘 아침 갑자기 AI 에이전트가 멈췄습니다. 텔레그램으로 봇 상태를 확인하다 보니 이런 메시지가 떠 있었어요.

You've hit your usage limit. Upgrade to Plus to continue using Codex
(https://chatgpt.com/explore/plus), or try again at May 21st, 2026 5:19 PM.

Approaching rate limits
Switch to gpt-5.4-mini for lower credit usage?

OpenAI Codex CLI의 무료 크레딧이 소진된 겁니다. 저는 AI 에이전트를 Codex CLI에 연결해서 코딩 작업을 처리하고 있었는데, 이 게이트웨이가 한도 초과로 다운되면서 연동 전체가 끊겨버렸습니다.

재개 가능 시간은 다음날 오후 5시. 하루를 그냥 기다릴 수는 없었습니다. 그래서 Gemini API로 즉시 대체하는 방법을 찾았고, 생각보다 훨씬 간단했습니다.

OpenAI Codex CLI란?

OpenAI Codex CLI는 터미널에서 실행하는 AI 코딩 에이전트입니다. GPT 계열 모델을 사용해 코드 작성, 수정, 실행을 자연어로 지시할 수 있어요. 현재 버전은 v0.130.0이며 기본 모델은 gpt-5.4입니다.

# 설치
npm install -g @openai/codex

# 실행
codex

무료 플랜에서는 사용량 한도가 있고, 한도를 초과하면 위와 같은 오류가 발생합니다. Plus(유료) 업그레이드나 한도 초기화까지 기다리는 방법 외에, 다른 AI API로 전환하는 방법이 있습니다.

Gemini API로 대체하는 법

Claude Code에 Gemini MCP 서버를 추가하는 방식으로 해결했습니다. Google AI Studio에서 API 키를 무료로 발급받고, @fre4x/gemini MCP 패키지를 연동하면 됩니다.

1단계: Google AI Studio에서 API 키 발급

https://aistudio.google.com/apikey 접속
“Create API key” 클릭
발급된 키 복사 (AIzaSy… 형태)

Google AI Studio 무료 티어는 Gemini 2.5 Flash 기준 분당 15회, 하루 1,500회 요청까지 무료입니다. 개인 프로젝트 수준에서는 충분한 용량이에요.

2단계: Claude Code settings.json에 Gemini MCP 추가

~/.claude/settings.json 파일의 mcpServers 항목에 아래 내용을 추가합니다.

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@fre4x/gemini"],
      "env": {
        "GEMINI_API_KEY": "여기에_발급받은_API_키_입력"
      }
    }
  }
}

3단계: Claude Code 재시작

설정 저장 후 Claude Code를 재시작하면 Gemini MCP가 활성화됩니다. 이후 이미지 분석, 텍스트 생성 등 Gemini 도구를 바로 사용할 수 있어요.

Codex CLI vs Gemini MCP 비교

항목	OpenAI Codex CLI	Gemini MCP
기본 모델	gpt-5.4	Gemini 2.5 Flash/Pro
무료 한도	크레딧 소진 시 중단	일 1,500회 (무료)
사용 방식	터미널 CLI	MCP 서버 (Claude Code 연동)
멀티모달	텍스트 중심	이미지·영상·오디오 분석 가능
한도 초과 시	다음날까지 대기	유료 전환 또는 키 교체

실제로 써보니

Codex CLI 한도가 초과된 당일 아침, Gemini MCP로 전환 후 작업을 이어갔습니다. 코드 리뷰, 파일 수정 등 기존 Codex CLI로 하던 작업 대부분을 문제없이 처리할 수 있었어요.

특히 Gemini 2.5 Flash는 응답 속도가 빠르고 한국어 처리도 자연스러워서 실사용에 무리가 없었습니다. 이미지 분석 기능은 Codex CLI에 없던 기능이라 오히려 더 활용도가 높았어요.

자주 묻는 질문 (FAQ)

Q. Codex CLI 한도는 언제 초기화되나요?

A. 한도 초과 메시지에 표시된 시간(예: “try again at May 21st, 2026 5:19 PM”)까지 기다리면 자동 초기화됩니다. 보통 24시간 단위로 리셋됩니다.

Q. Gemini API 키는 유료인가요?

A. Google AI Studio에서 발급하는 API 키는 무료입니다. Gemini 2.5 Flash 기준으로 하루 1,500회 요청까지 무료로 사용할 수 있습니다.

Q. Claude Code 없이도 Gemini MCP를 쓸 수 있나요?

A. MCP(Model Context Protocol)를 지원하는 환경이라면 사용 가능합니다. 현재 Claude Code, Cursor 등 주요 AI 코딩 도구들이 MCP를 지원합니다.

마치며

OpenAI Codex CLI 한도 초과는 예고 없이 찾아옵니다. 미리 Gemini API 키를 발급받아두고 MCP 설정을 준비해두면, 한도가 소진되더라도 5분 안에 전환할 수 있어요. Codex CLI 한도로 작업이 중단되는 상황이 생겼다면 이 방법을 바로 시도해 보세요.