Google Gemini 2.5 Pro와 Open Codex CLI 사용 방법 (Open Codex CLI)

Open Codex CLI는 대형 언어 모델(LLM)의 힘을 직접 여러분의 터미널 워크플로우에 가져다주는 오픈 소스 도구입니다. 이 가이드는 Open Codex CLI 환경 내에서 오늘날 사용 가능한 가장 진보된 모델 중 하나인 구글의 Gemini 2.5 Pro를 활용하는 데 중점을 둡니다.

Open Codex CLI는 원래 OpenAI Codex CLI의 포크로, 핵심 기능은 유지하면서 구글 Gemini를 포함한 여러 AI 제공업체 지원을 추가하여 기능을 대폭 확장합니다. 이를 통해 개발자는 익숙한 터미널 인터페이스 내에서 작업에 가장 적합한 모델을 선택할 수 있습니다. 복잡한 코딩 질문을 하거나, 보일러플레이트 코드를 생성하거나, 기존 기능을 리팩토링하거나, 복잡한 스크립트를 설명하거나, 심지어 빌드 명령을 조정하는 등 모든 작업을 Gemini의 지능에 따라 명령줄을 떠나지 않고 수행할 수 있습니다.

이 기사에서는 구글 Gemini 2.5 Pro와 함께 Open Codex CLI를 설치하고 구성하며 사용하는 방법에 대한 포괄적이고 단계별 가이드를 제공합니다(작성 당시 Open Codex CLI 구성에서 지정된 gemini-2.5-pro-preview-03-25 모델 버전을 참조) 및 gemini-2.0-flash와 같은 형제 모델. 워크플로우를 최적화하려는 경험 많은 개발자이든 AI 코딩 어시스턴트에 처음 접하는 사람이든 이 강력한 조합을 활용하는 방법을 배울 수 있습니다.

왜 Gemini와 함께 Open Codex CLI인가요?

이건 대단합니다. 불과 몇 시간 만에 내 친구가 Open AI Codex를 Gemini 2.5 Pro와 함께 작업할 수 있도록 포크했습니다 🤯 pic.twitter.com/gENT01q82P

— Sawyer Hood (@sawyerhood) 2025년 4월 17일

Open Codex CLI와 Gemini 2.5 Pro의 결합은 여러 가지 유익한 이점을 제공합니다:

• 터미널 네이티브 워크플로우: 커맨드 라인을 선호하는 개발자를 위해 Open Codex CLI는 매끄러운 통합을 제공합니다. AI 지원을 위해 편집기, 터미널 및 별도의 브라우저 창 간에 컨텍스트를 전환할 필요가 없습니다. 이는 더 빠른 반복과 더 적은 방해로 이어집니다.
• 오픈 소스 및 유연성: 오픈 소스(open-codex on npm)인 이 도구는 투명성과 커뮤니티 기여 가능성을 제공합니다. Gemini, OpenAI, OpenRouter, Ollama 등의 다중 제공자 지원을 통해 필요에 따라 모델이나 제공자를 전환할 수 있는 유연성을 제공합니다.
• 강력한 AI 기능: Gemini 2.5 Pro는 최첨단 추론, 코드 생성 및 이해 기능을 제공합니다. 이를 통해 CLI 내에서 더 복잡한 작업, 더 나은 코드 품질 제안 및 심층 분석을 할 수 있습니다.
• 액션 지향적: 단순한 챗봇과는 달리, Open Codex CLI는 액션을 위해 설계되었습니다. 로컬 파일을 읽어 컨텍스트를 제공할 수 있고, 파일 수정(패치)을 제안하며, 안전한 샌드박스 내에서 셸 명령을 실행할 수 있어 진정한 채팅 기반 개발이 가능합니다.
• 보안 중심: 이 CLI는 잠재적으로 위험한 작업인 셸 명령을 안전하게 실행하기 위해 샌드박스 메커니즘(맥OS의 Apple Seatbelt, 리눅스의 Docker 추천)을 통합하여 자동 승인 모드를 사용할 때 특히 그렇습니다. 명령은 기본적으로 더 높은 자율성 모드에서 네트워크 비활성화 및 디렉터리 샌드박스로 실행됩니다.
• 버전 제어 통합: 이 도구는 Git과 함께 작동하도록 설계되었습니다. 기본적으로 파일을 수정하기 전에 승인이 필요하므로, 변경 사항이 작업 디렉터리에 영향을 미치기 전에 검토할 수 있어 언제나 안전망을 가질 수 있습니다.

사전 요구 사항

시작하기 전에 다음 사항을 확인하십시오:

1. 운영 체제: macOS 12 이상, 최신 리눅스 배포판(예: Ubuntu 20.04+, Debian 10+), 또는 Windows 10/11에서 Windows Subsystem for Linux(WSL2)를 사용하는 경우. 직접적인 Windows 지원은 제공되지 않습니다.
2. Node.js: 버전 22 이상이 필요합니다. LTS(장기 지원) 버전이 일반적으로 권장됩니다. 터미널에서 node -v를 실행하여 버전을 확인할 수 있습니다. nodejs.org에서 Node.js를 다운로드하십시오.
3. 구글 클라우드 계정 및 Gemini API 키: Gemini 모델에 대한 요청을 인증하기 위해 API 키가 필요합니다. Google AI Studio 또는 Google Cloud Console를 통해 얻을 수 있습니다. 이 키는 계정과 연결되어 있으므로 안전하게 보관하십시오.
4. 터미널 친숙도: 시스템의 명령줄 인터페이스(터미널, iTerm, Bash, Zsh 등)를 사용하는 기본적인 지식이 필요합니다.

1단계: Open Codex CLI 설치하기

Open Codex CLI를 설치하는 권장 방법은 Node.js에 포함된 npm(노드 패키지 관리자)을 통해 전역적으로 설치하는 것입니다. 터미널을 열고 다음을 실행하십시오:

npm install -g open-codex

또는 패키지 관리자로 Yarn을 사용하는 경우, 다음을 실행할 수 있습니다:

yarn global add open-codex

이 명령은 open-codex 패키지를 다운로드하고 터미널 어디에서나 open-codex 명령을 사용할 수 있게 만듭니다. 전역 npm 설치에 sudo를 사용하지 마십시오. 권한 문제가 발생하면 npm 권한 수정하기가 더 좋습니다.

open-codex --version 또는 open-codex --help를 실행하여 설치를 확인할 수 있습니다.

2단계: Gemini 접근 설정하기

Gemini 모델을 사용하려면 Open Codex CLI에 API 키를 제공해야 하며 gemini 제공자를 사용하겠다고 알려야 합니다. 이를 구성하는 두 가지 주요 방법이 있습니다:

방법 1: 환경 변수 (빠른 시작/테스트에 권장)

API 키를 제공하는 가장 간단한 방법은 환경 변수를 사용하는 것입니다. Open Codex CLI는 gemini 제공자가 선택되었을 때 GOOGLE_GENERATIVE_AI_API_KEY를 특별히 찾습니다.

터미널에서 다음 명령을 실행하되, "YOUR_API_KEY_HERE"를 실제 Gemini API 키로 교체하세요:

export GOOGLE_GENERATIVE_AI_API_KEY="YOUR_API_KEY_HERE"

중요: 이 명령은 현재 터미널 세션에 대해서만 환경 변수를 설정합니다. 터미널을 닫거나 새로 열면 명령을 다시 실행해야 합니다.

API 키를 영구적으로 사용할 수 있게 하려면 export 행을 셸 구성 파일에 추가해야 합니다. 일반 파일로는 다음이 있습니다:

• ~/.zshrc (Zsh의 경우, 최신 macOS의 기본값)
• ~/.bashrc 또는 ~/.bash_profile (Bash의 경우)

적절한 파일에 export GOOGLE_GENERATIVE_AI_API_KEY="YOUR_API_KEY_HERE" 행을 추가하고, 이를 저장한 후 터미널을 다시 시작하거나 source ~/.zshrc (또는 해당 파일 경로)를 실행하여 변경 사항을 적용하세요.

그런 다음 각 호출에서 --provider 플래그를 사용하여 Gemini를 제공자로 지정할 수 있습니다:

open-codex --provider gemini "프랑스의 수도는 어디인가요?"

방법 2: 구성 파일 (지속적인 설정에 권장)

특히 Gemini를 지속적으로 사용할 계획이라면 Open Codex CLI 구성 파일을 사용할 수 있습니다. CLI는 ~/.codex/config.json에 있는 구성 파일을 찾습니다.

존재하지 않는 경우 디렉토리를 생성하세요: mkdir -p ~/.codex

구성 파일을 생성하고 엽니다: nano ~/.codex/config.json (또는 선호하는 텍스트 편집기를 사용하세요).

다음 JSON 내용을 추가하여 Gemini를 기본 제공자로 설정합니다:

{
  "provider": "gemini"
}

기본 Gemini 모델도 선택적으로 설정할 수 있습니다. Open Codex CLI는 gemini-2.5-pro-preview-03-25를 기본 "에이전틱" 모델로, gemini-2.0-flash를 기본 "전체 컨텍스트" 모델로 정의합니다. 대부분의 상호 작용에 대해 강력한 2.5 Pro 모델을 기본값으로 설정하려면 다음을 사용하세요:

{
  "provider": "gemini",
  "model": "gemini-2.5-pro-preview-03-25"
}

파일을 저장하고 편집기를 종료합니다.

중요하게도, 제공자 및 모델을 설정하기 위해 구성 파일을 사용하는 경우에도 GOOGLE_GENERATIVE_AI_API_KEY 환경 변수를 여전히 설정해야 합니다 방법 1에서 설명한 대로. 구성 파일은 CLI에게 어떤 제공자를 사용할지 알려주고, 환경 변수는 해당 제공자에 대한 자격 증명을 제공합니다.

구성 파일이 설정되면 이제 간단히 open-codex를 실행하면 지정된 Gemini 제공자를 기본값으로 사용합니다:

open-codex "프랑스의 수도는 어디인가요?"

3단계: Gemini와 기본 사용법

이제 Open Codex CLI가 설치되고 Gemini에 대해 구성되었으니, 상호작용하는 방법을 살펴보겠습니다.

인터랙티브 모드 (REPL)

채팅 같은 경험을 위해 특정 프롬프트 없이 CLI를 실행하세요:

open-codex
# 또는 config.json에서 기본 제공자를 설정하지 않았다면:
# open-codex --provider gemini

이 명령은 Read-Eval-Print Loop(REPL)를 시작하며, 여기에서 프롬프트를 입력하고 응답을 받아 Gemini와 지속적인 대화를 나눌 수 있습니다.

❯ open-codex --provider gemini
Open Codex CLI에 오신 것을 환영합니다! 요청을 입력한 후 Enter 키를 두 번 눌러 전송하세요.
> Gemini 2.5 Pro 모델에 대해 설명해 주세요.

프롬프트를 보내려면 Enter를 두 번 눌러야 합니다. Gemini는 터미널 내에서 응답할 것입니다. 후속 질문을 입력하여 대화를 이어갈 수 있습니다.

직접 프롬프트 입력

단발성 요청의 경우 프롬프트를 인수로 직접 전달할 수 있습니다. config.json에서 기본값을 설정하지 않은 경우 제공자 플래그가 필요합니다. --model 또는 -m 플래그를 사용하여 정확한 모델을 지정할 수도 있습니다:

• 기본 Gemini 모델 사용(설정되어 있는 경우):

open-codex "Python에서 클로저 개념을 설명해 주세요."

• 제공자 및 모델을 명시적으로 지정:

open-codex --provider gemini --model gemini-2.5-pro-preview-03-25 "현재 디렉터리와 하위 디렉터리에서 크기가 10MB 이상인 모든 파일을 찾는 bash 스크립트를 작성하세요."

• 다른 Gemini 모델 사용(예: 더 빠르거나 저렴한 작업을 위한 Flash):

open-codex --provider gemini --model gemini-2.0-flash "React 훅 문서의 주요 사안을 요약해 주세요."

CLI는 Gemini를 통해 요청을 처리하고 응답을 표준 출력으로 직접 인쇄합니다.

4단계: Gemini와 함께 Open Codex 기능 활용하기

Open Codex CLI의 진정한 힘은 Gemini의 안내에 따라 로컬 개발 환경과 상호작용할 수 있는 능력에 있습니다.

파일 시스템 상호작용

Open Codex CLI를 통해 Gemini는 현재 프로젝트의 파일을 읽어 요청에 대한 컨텍스트를 얻을 수 있습니다. 또한 파일에 대한 변경 사항(쓰기 또는 패치)을 제안할 수도 있습니다.

• 파일 읽기: 프롬프트에서 파일명을 언급하면 CLI가 종종 자동으로 해당 파일을 읽어 Gemini에 대한 컨텍스트를 제공합니다.

# 'calculate.js'라는 파일이 있다고 가정
open-codex --provider gemini "calculate.js를 읽고 가독성을 향상시킬 수 있는 개선점을 제안해주세요."

• 파일 쓰기/패치: Gemini에게 파일을 수정해 달라고 요청하면, CLI는 변경 사항 요약(diff)을 생성하여 변경 사항을 적용하기 전에 승인을 요청합니다.

open-codex --provider gemini "두 개의 인수를 받아 그 차이를 반환하는 'subtract'라는 새 기능을 'calculate.js'에 추가하세요."

CLI는 제안된 변경 사항을 출력하고 승인 대화 상자를 표시합니다: 패치 적용하시겠습니까? [y/N]. y를 눌러 수락하거나 n을 눌러 거부합니다.

명령 실행

Open Codex CLI는 Gemini가 제안한 셸 명령을 실행할 수 있습니다. 이는 강력하지만 주의가 필요합니다.

• 승인 모드: --approval-mode (또는 -a) 플래그는 자율성을 제어합니다:
• suggest (기본값): 모든 파일 변경 및 모든 셸 명령에 대해 명시적 승인이 필요합니다. 시작할 때 권장됨.
• auto-edit: 파일 변경 사항을 자동으로 적용하지만 여전히 셸 명령에 대해 승인을 요청합니다.
• full-auto: 파일 변경 사항을 자동으로 적용하며, 셸 명령도 실행합니다(샌드박스 내에서). 신뢰할 수 없는 저장소에서는 특히 주의해서 사용하세요.
• 샌드박스: auto-edit 및 full-auto 모드에서는 네트워크가 비활성화되고 현재 작업 디렉터리 및 임시 파일로 제한되어 안전성이 보장됩니다.
• 예시(기본 '제안' 모드 사용):

open-codex --provider gemini "pip을 사용하여 'requests' 라이브러리를 설치합니다."

Gemini는 pip install requests 명령을 제안할 수 있습니다. CLI는 명령을 보여주고 질문합니다: 명령을 실행하시겠습니까? [y/N].

프로젝트 컨텍스트 (codex.md)

지속적인 지침이나 프로젝트에 대한 컨텍스트를 Gemini에 제공하기 위해 codex.md 파일을 생성할 수 있습니다. CLI는 다음 순서로 이러한 파일을 읽습니다:

1. ~/.codex/instructions.md (전역 및 개인 지침)
2. codex.md (저장소 루트에 있는 프로젝트 전반의 노트)
3. codex.md (현재 작업 디렉터리에 있는 하위 디렉터리 전용 노트)

이를 통해 매 프롬프트에서 반복하지 않고도 Gemini의 동작을 안내하거나 프로젝트 표준, 사용되는 라이브러리 등에 대한 정보를 제공할 수 있습니다.

문제 해결 및 팁

• API 키 오류: GOOGLE_GENERATIVE_AI_API_KEY가 올바르게 설정되고 내보내지고 현재 터미널 세션에서 접근 가능하도록 확인하세요. 오타가 없는지 다시 확인하십시오.
• 모델을 찾을 수 없음: 모델 이름(gemini-2.5-pro-preview-03-25, gemini-2.0-flash 등)이 지원되거나 구성된 이름과 일치하는지 확인하세요. ~/.codex/config.json을 확인하거나 --model 플래그를 올바르게 사용하세요.
• 제공자 오류: config.json 또는 --provider gemini 플래그를 통해 제공자가 gemini로 설정되었는지 확인하세요.
• 상세 로깅: 디버깅을 위해 명령을 DEBUG=true 환경 변수를 앞에 붙여 실행하세요: DEBUG=true open-codex --provider gemini "내 프롬프트". 이 경우 요청/응답에 대한 상세 정보를 출력합니다.
• 기본적으로 시작하세요: 간단한 프롬프트로 시작하여 Gemini와 CLI의 상호작용 방식에 익숙해지면 점차 복잡성을 증가시켜 보세요.
• 승인 사항을 신중히 검토하세요: 특히 파일 수정이나 명령 실행 시, 항상 제안된 변경 사항이나 명령을 승인하기 전에 검토하세요(답변 y).

결론

Open Codex CLI는 구글의 Gemini 2.5 Pro에 의해 강화되어 여러분의 터미널을 지능형 코딩 어시스턴트로 변형시킵니다. 이 가이드에서 설명한 단계를 따르면 고급 AI 기능을 일상 개발 워크플로우에 매끄럽게 통합할 수 있습니다, 직접 명령줄에서.

빠른 코드 스니펫 및 설명부터 복잡한 리팩토링 및 스크립트 실행까지, 이 조합은 생산성을 높이고 작업을 간소화할 수 있는 상당한 잠재력을 제공합니다. 도구는 보안을 위해 샌드박스화 및 사용자 승인을 중시하며, 다중 제공자 지원의 유연성과 오픈 소스 특성을 결합하여 터미널 내에서 AI를 활용하려는 개발자에게 매력적인 선택입니다.

다양한 프롬프트를 실험하고, 다양한 승인 모드를 탐색하며(신중하게!), Gemini와 Open Codex CLI가 여러분의 코딩 경험을 어떻게 개선할 수 있는지 발견하세요.