GeminiDesktop GeminiDesktop
가이드

GeminiDesktop에 Gemini CLI 채팅 모드 추가: API 키 없이 Gemini 2.5 Pro 1일 1000회 무료 사용

게시일 · 작성자: GeminiDesktop Team

GeminiDesktop 채팅 페이지(geminidesktop.app/chat)에 작은 스위치가 하나 추가됐습니다: CLI 토글. 이걸 켜면 이제 모든 메시지가 Gemini API로 직접 가지 않고, 당신의 로컬에 이미 로그인된 gemini CLI로 라우팅됩니다. 즉 OAuth 로그인만으로 1분에 60회, 1일 1000회의 Gemini 2.5 Pro 무료 한도를 사용할 수 있고, 그 긴 AIza... BYOK API 키가 브라우저에 들어올 필요가 없어집니다.

TL;DR 한눈에

  • 활성화 방법: GeminiDesktop 채팅 페이지 입력창 위 툴바 → Search / URL / Code 옆에 추가된 “CLI” 버튼 클릭
  • 인증 방식: 로컬 ~/.gemini/tokens.json (OAuth). API 키가 브라우저에 들어오지 않음
  • 무료 한도: 개인 Google 계정 → 분당 60회, 일일 1000회 Gemini 2.5 Pro, 100만 토큰 컨텍스트
  • 모델 선택기: 상단의 모델 드롭다운 그대로 재사용. 선택된 모델은 --model <id>로 CLI에 전달, 모델명 옆에 “· via CLI” 접미사 표시
  • 데스크톱 전용: 브라우저에서는 토글 비활성화 (서브프로세스 실행 불가). Tauri 데스크톱 앱에서만 동작
  • 설치: bun add -g @google/gemini-cli, 또는 CLI 미설치 시 GeminiDesktop의 원클릭 Install
  • 아키텍처 선택: ACP 대신 Headless 모드 (gemini --output-format stream-json) — 기존 local_agent 이벤트 파이프라인 재사용
  • MVP 제한: 첨부파일, Computer Use, Regenerate/Edit 미지원

입력창 옆에 추가된 “CLI” 토글

GeminiDesktop 데스크톱 앱을 열고 /chat으로 이동하면, 입력창 위 도구 모음의 Search / URL / Code 그라운딩 토글 옆에 새로운 버튼이 하나 보입니다: CLI.

동작 방식은 직관적:

  • 꺼짐 (기본값): 메시지가 @ai-sdk/google을 통해 Gemini API로 직접 전송됨. 설정에 저장된 API 키(BYOK) 사용
  • 켜짐: 이후 메시지가 로컬 gemini CLI로 라우팅, headless 모드로 실행, 로컬 OAuth 토큰으로 인증

전환은 매끄럽습니다. 앱 재시작, 재로그인, 히스토리 초기화 모두 불필요. 토글 켜기 전의 API 모드 메시지는 그대로 남아 있고, 다음 메시지부터 CLI로 흘러갑니다.

상단 모델 선택기 그대로 재사용. 익숙한 “Gemini 3.1 Pro / 3.0 Flash / 2.5 Pro / 2.5 Flash / Flash Lite” 드롭다운이 CLI 모드에서도 똑같이 동작합니다 — 선택한 모델을 --model <id>로 CLI에 전달(Gemini CLI 공식 문서에서 플래그 지원 확인됨). 현재 CLI 경로로 실행 중임을 알려주기 위해 모델명 옆에 조용한 회색 “· via CLI” 접미사가 추가됩니다.

전환할 만한 세 가지 실질적인 이유

1. 무료 한도: OAuth 로그인만으로 일일 1000회 Gemini 2.5 Pro

대부분의 사용자가 이 스위치를 켜는 주된 이유입니다.

Google 공식 발표에 따르면, 개인 Google 계정으로 Gemini CLI에 로그인하면 무료 Gemini Code Assist 라이선스가 자동 부여되어 Gemini 2.5 Pro를 다음 한도로 사용 가능:

  • 분당 60회 요청
  • 일일 1000회 요청
  • 100만 토큰 컨텍스트 윈도우

BYOK 경로와 비교: Google AI Studio에 등록하여 API 키를 발급받고 관리하거나, Google Cloud 신규 고객 $300 크레딧을 쫓아가며 사용량을 걱정해야 합니다. CLI 모드는 이 모든 것을 건너뜁니다. 한 번의 OAuth 브라우저 인증으로 토큰이 ~/.gemini/tokens.json에 저장되고, GeminiDesktop이 CLI를 호출하면 CLI가 직접 토큰을 읽습니다. API 키는 브라우저에도, GeminiDesktop의 어떤 저장소에도 존재하지 않습니다.

2. 로컬 권한: 말만 하는 게 아니라 직접 동작하는 Gemini

CLI 모드의 두 번째 가치: Gemini가 로컬 도구를 호출할 수 있습니다.

API만 사용하는 채팅에서는 Gemini가 오직 말할 수만 있습니다 — 무엇을 해야 할지 알려줄 뿐, 실행은 사용자가 합니다. CLI 채팅에서는 Gemini가 파일을 읽고, 쓰고, 셸 명령을 실행합니다. 진정한 로컬 에이전트가 됩니다.

일상 시나리오 몇 가지:

  • “Downloads 폴더의 모든 PDF 제목을 표로 정리해줘” — CLI 모드 Gemini가 ls ~/Downloads/*.pdf 실행, 메타데이터 읽기, 깔끔한 목록 반환
  • “이 프로젝트의 TypeScript 에러는 뭐야?” — 로그 복사 붙여넣기 불필요. Gemini가 해당 디렉터리로 cd, tsc --noEmit 실행, 출력 읽고 문제 지적
  • “이 회의 녹음을 Markdown으로 변환” — Gemini가 로컬 파일 읽기, 적절한 시스템 도구 호출, 결과 작성

안전을 위해 기본 permissionMode는 --yolo가 아닌 default. CLI가 조용히 파일을 편집하지 않으며, 모든 민감한 작업(파일 쓰기, 셸 명령)은 CLI 레벨에서 승인을 요청합니다. 완전 자율을 원하는 사용자는 나중에 설정에서 YOLO로 전환 가능하지만, 기본값은 보수적으로 유지됩니다.

3. 스트리밍: API 경로와 완전히 동일한 모습

걱정이 될 수 있습니다: CLI는 별도의 프로세스인데, 출력이 채팅 버블에 날것 텍스트로 쏟아지지 않을까?

그렇지 않습니다. 내부적으로 GeminiDesktop의 성숙한 local_agent 이벤트 파이프라인을 재사용합니다. CLI의 stream-json 출력은 Rust 측에서 통합 메시지 포맷으로 파싱되어, Tauri 이벤트로 실시간 프런트엔드에 전달되고, 프런트엔드 어댑터가 메시지 parts로 다시 매핑합니다. 결국 API 경로가 사용하는 동일한 채팅 버블 컴포넌트에서 렌더링됩니다.

UI는 두 모드에서 완전히 동일. 도구 호출(read_file, run_shell)은 접을 수 있는 카드로 렌더링되어 입력 JSON과 출력 텍스트를 확인할 수 있고, 사고(Thinking)는 옅은 색의 별도 버블로 나타나며, 스트리밍 텍스트는 API 모드와 똑같이 한 글자씩 타이핑됩니다. 유일한 차이는 모델명 옆의 조용한 “· via CLI” 접미사뿐.

3단계로 시작하기

단계 1: gemini CLI 설치

두 가지 방법 중 하나:

# 방법 A: 명령어 직접 실행
bun add -g @google/gemini-cli
# 또는: npm install -g @google/gemini-cli

또는 GeminiDesktop 내 원클릭 설치: CLI 토글을 처음 켤 때, CLI가 설치되어 있지 않다고 감지하면 “Install” 버튼 toast가 팝업으로 나타나 명령어를 자동 실행.

단계 2: 최초 OAuth 로그인

터미널에서:

gemini

브라우저 창이 자동으로 Google 로그인 페이지를 엽니다. 개인 Google 계정으로 승인하세요. 토큰이 ~/.gemini/tokens.json에 저장되어 — 이후 GeminiDesktop의 CLI 호출은 이 토큰을 자동으로 읽습니다.

단계 3: “CLI” 토글 켜기

geminidesktop.app/chat으로 이동해서 입력 툴바의 “CLI” 버튼 클릭. 하이라이트 파란색으로 변하면 켜진 상태. 평소처럼 메시지 전송 — 상단에 “Gemini 3.x Pro · via CLI”가 표시되면 CLI가 인계받았다는 의미.

MVP 범위 (솔직하게)

✅ 지원:

  • 텍스트 채팅 (모든 Gemini 모델 선택 가능)
  • 모델 전환 (상단 선택기 → CLI --model)
  • 도구 호출 스트리밍 (read_file / run_shell / code_execution 등)
  • Stop 버튼으로 CLI 프로세스 언제든 중단
  • 멀티턴 컨텍스트 (prompt-prefix 연결 — 다음 섹션 참조)

❌ 아직 미지원:

  • 첨부파일 업로드: CLI는 파일 경로가 필요하지만 브라우저 측 이미지/PDF는 blob. blob을 임시 디렉터리에 쓰는 글루 레이어가 미구현이라 MVP에서는 CLI 모드 중 첨부파일이 toast로 차단됩니다. 후속 업데이트 예정
  • Computer Use: 자주 혼동됨 — Gemini Computer Use는 Gemini 3.1 Pro API 기능(모델이 스크린샷 촬영 후 데스크톱 조작)이지 CLI 기능이 아닙니다. Gemini CLI 자체는 Computer Use 도구를 노출하지 않습니다. Computer Use는 추후 API 경로를 통한 별도 기능으로 전용 실행기와 함께 출시될 예정이며, CLI 토글과 병렬 관계
  • Regenerate / Edit 메시지: CLI 모드에서 생성된 어시스턴트 메시지는 “재생성” 또는 “편집 후 재실행”을 아직 지원하지 않습니다. CLI 버블에서는 해당 버튼이 비활성화. 추후 지원

🔮 향후: Gemini CLI가 공식적으로 headless --resume <id> 플래그 또는 ACP 모드를 지원하면, 네이티브 세션 상태 관리로 전환. 현재의 prompt-prefix 연결은 실용적인 대안.

왜 Headless, ACP가 아닌가 — 아키텍처 노트

기술에 관심 있는 분들을 위한 배경.

Gemini CLI를 채팅 UI에 통합하는 두 가지 방법:

Headless 모드 (gemini --output-format stream-json): 메시지마다 새 CLI 서브프로세스를 스폰, stdout에서 stream-json 이벤트 파싱, 프로세스 종료로 해당 턴 종료. 멀티턴 컨텍스트는 수동 히스토리 연결로 구현 — 이전 user/assistant 메시지를 새 프롬프트 앞에 붙임.

ACP 모드 (Agent Client Protocol): 장기 실행 JSON-RPC 서브프로세스를 운영, initialize / newSession / prompt / cancel 메서드로 CLI와 대화. 네이티브 멀티턴 상태, loadSession 복원, MCP 도구 브로드캐스트 — 기능은 더 완전하지만 구현 비용도 더 큼.

우리는 Headless를 선택했습니다. 현실적인 이유:

  1. 성숙한 파이프라인 재사용: GeminiDesktop의 기반 local_agent 모듈은 Claude Code, OpenCode, Codex, Cursor 등을 Headless로 거의 1년간 실행. 이벤트 브리지, 메시지 프로토콜, 에러 처리, Stop 버튼 모두 이미 존재. Gemini CLI 추가는 executor 확장만으로 충분
  2. 시간 비용 차이: Headless 출시 ~1주, ACP ~1개월 (JSON-RPC 클라이언트, 서브프로세스 라이프사이클, MCP 서버 브로드캐스트 — ACP는 호스트가 파일 I/O를 프록시해야 함)
  3. Headless면 충분: 턴당 ~150-300ms 스폰 비용은 채팅 UX에 허용 범위. Prompt-prefix 멀티턴은 매번 히스토리를 재전송하지만, Gemini 2.5 Pro의 100만 토큰 윈도우는 그 정도 중복에 전혀 부담을 받지 않음

결론: Headless를 먼저 출시해 사용자가 활용하도록 하고, ACP는 후속 업그레이드로 남겨 둠 — 스폰 지연이나 취소 의미론이 실제로 걸림돌이 되면 그때 전환.

Claude Desktop / ChatGPT와 비교

GeminiDesktop의 기반 local_agent 모듈은 사실 Claude Code, OpenCode, Codex, Cursor 등 여러 CLI를 지원합니다. 핵심 차이:

  • Gemini CLI (이번 추가): 개인 Google 계정 무료 (1일 1000회), OAuth 로그인만으로 사용; 긴 컨텍스트(100만 토큰) 우위 뚜렷
  • Claude Code: Anthropic API 구독 또는 Pro 플랜 필요 — 유료 경로. 최상위 추론 품질

선택 기준: 일상 채팅 / 긴 컨텍스트 / “무료로 쓰고 싶다” → Gemini CLI. 복잡한 코드 편집 / Claude 생태계 사용자 → Claude Code. 두 가지는 하나의 GeminiDesktop 설치에서 공존 가능하며, 설정에서 기본 에이전트를 전환할 수 있습니다.

지금까지 Claude Desktop이나 ChatGPT 데스크톱을 써왔다면, Claude Desktop에서 Gemini for Mac으로 전환하는 완전 가이드를 확인하세요 — GeminiDesktop의 CLI 모드와 결합하면 Claude의 유료 플랜을 완전히 건너뛸 수 있습니다.

FAQ

Q1: CLI 모드에서 내 채팅 내용은 어디로 전송되나요?

직접 API 모드와 동일 — 내용은 gemini CLI를 통해 Google의 Gemini 서버로 전달됩니다. 차이:

  • 인증: 로컬 OAuth 토큰 사용, 브라우저 내 API 키 없음
  • 데이터 경로: GeminiDesktop → 로컬 CLI 프로세스 → Google Gemini API (중간에 제3자 백엔드 없음)
  • 채팅 히스토리: 로컬 IndexedDB에 저장, 어떤 서버에도 업로드되지 않음

Q2: CLI 모드와 API 모드를 함께 쓸 수 있나요?

네. 토글은 자유롭게 전환 가능하며, 두 모드의 메시지는 같은 세션에서 자연스럽게 공존합니다. 일반적인 혼합 패턴: 일상적인 가벼운 채팅은 API 모드 + Flash Lite(저렴, 빠름), Gemini가 로컬 파일을 만지거나 코드를 실행하거나 긴 추론이 필요할 때는 CLI 모드 + 2.5 Pro로 전환.

Q3: 토글을 눌러도 반응이 없거나 에러가 나면?

세 가지 흔한 원인:

  1. CLI 미설치: 토글이 Install toast를 표시합니다 — “Install” 클릭하거나 bun add -g @google/gemini-cli 직접 실행
  2. CLI 미인증: “Gemini CLI 미인증” toast가 표시됩니다. 터미널에서 gemini 실행해 OAuth 플로우 완료
  3. 웹 버전이지 데스크톱 앱이 아님: 브라우저에서는 토글이 비활성화됩니다. 풀 경험을 위해 GeminiDesktop 다운로드

Q4: CLI 모드가 Gemini Canvas나 NotebookLM을 대체하나요?

아닙니다, 상호 보완 관계. Canvas는 웹 페이지 / 인포그래픽 / 퀴즈 / 플래시카드 생성 템플릿에 특화 — Gemini Canvas on Desktop 참조. NotebookLM은 RAG 스타일 지식 베이스 도구로 다중 소스 Q&A가 핵심. CLI 모드는 “내 로컬 파일시스템에서 Gemini가 뭔가 해주길 원한다” 시나리오에 최적 — 파일 정리, 코드 디버깅, 셸 실행, 긴 컨텍스트 추론.

Q5: Windows에서도 동작하나요?

네. GeminiDesktop은 macOS와 Windows 모두 지원(Tauri 패키징)하며, CLI 모드는 양쪽 모두에서 동일하게 동작. Windows 환경에서 Gemini를 평가 중이라면 Google이 왜 아직 네이티브 Gemini Windows 앱을 만들지 않았는지의 Windows 생태계 맥락을 참고하세요.

요약

작은 토글 하나가 큰 일을 합니다: Google의 무료 한도를 GeminiDesktop 채팅 경험에 끌어들입니다. 유료 API 키 없음, 터미널 체조 없음, 모델 선택기 재구현 없음. “API 키 관리 없이 Gemini 2.5 Pro를 쓰고 싶다”는 사용자에게 가장 마찰 없는 경로입니다.

MVP 먼저; 첨부파일, Computer Use, ACP 모드 업그레이드는 후속 기능으로 출시 예정. 지금 바로 시도: geminidesktop.app/chat.