SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

Headless VPS에서 Gemini CLI 실행 및 설정 방법

Headless VPS 환경에서 Gemini CLI를 안정적으로 구동하는 방법을 안내합니다. 최신 Node.js 설치부터 브라우저 없는 API 키 인증, tmux를 활용한 SSH 세션 유지까지 실무적인 설정 과정을 단계별로 설명합니다.

구축할 시스템

직접 소유한 서버에서 항상 실행되는 Gemini CLI를 구축합니다. SSH를 통해 접속할 수 있으며, 노트북을 닫아도 에이전트 작업이 계속 수행됩니다. 설치 과정은 3개의 명령어로 이루어집니다. 데스크톱 환경을 전제로 하는 부분들이 작업의 난관입니다. Google CLI는 로그인 시 브라우저를 실행하려 하지만, 서버에는 브라우저가 없습니다. 따라서 이 가이드의 대부분은 헤드리스(headless) 환경 설정, 배포판이 제공하지 않는 최신 Node 버전 설치, root 권한이 필요 없는 전역 npm 설치, 셸 기록에 남지 않는 API 키를 이용한 브라우저 없는 인증, 그리고 SSH 세션이 끊겨도 작업이 유지되도록 하는 tmux 설정에 집중합니다.

Gemini CLI는 Google의 Gemini 모델과 통신하며 파일을 읽고 쓰고, 셸 명령어를 실행하고, 작업 디렉터리에서 도구를 제어할 수 있는 오픈 소스(Apache-2.0) Node 프로그램(@google/gemini-cli)입니다. VPS에서 이 프로그램은 항상 가동되는 작은 에이전트 역할을 합니다. 그렇기 때문에 이 프로그램이 실행되는 계정과 서버에 저장된 자격 증명은 이 문서의 어떤 설정보다 중요합니다.

사전 요구 사항 및 주의 사항

  • root 또는 sudo 권한이 있는 Ubuntu 24.04 KVM VPS가 필요합니다. KVM 플랜이면 충분하며, CLI 자체는 가벼워 유휴 상태에서 수백 MB의 RAM만 사용합니다.
  • Node.js 20 이상이 필요합니다. 이는 필수 최소 버전이며, 배포판 패키지는 이보다 낮으므로 다음 섹션을 참조하십시오. Node 20은 2026년 4월 30일에 수명이 종료되었으므로 24 버전을 설치하십시오.
  • Google API로 향하는 아웃바운드 HTTPS(포트 443) 연결이 필요합니다. 인바운드 포트는 필요하지 않습니다. 이 도구는 서버가 아닌 클라이언트이므로 방화벽을 개방할 필요가 없습니다.
  • 서버에서 브라우저를 사용하지 않고 인증하는 방법이 필요합니다. Google AI Studio에서 발급받은 유료 Gemini API key를 사용하거나, 헤드리스 환경에서 터미널에 코드를 붙여넣는 Google 로그인을 사용할 수 있습니다. API key 방식은 스크립트나 자동화된 실행 환경에 적합합니다.
  • Docker 또는 Podman은 --sandbox 격리가 필요한 경우에만 사용합니다. 이는 선택 사항이며 마지막 부분에서 다룹니다.

현재 가장 흔히 발생하는 문제는 브라우저가 아닌 계정 관련 사항입니다. Google은 2026년 5월 19일에 2026년 6월 18일부터 Gemini CLI가 Google AI Pro 및 Ultra 구독자와 무료 사용자의 요청 처리를 중단한다고 발표했습니다. 해당 사용자들은 대체 도구인 Antigravity CLI(agy)를 사용해야 합니다. Gemini CLI는 유료 Gemini API key, Gemini Enterprise Agent Platform API key, 그리고 조직의 Gemini Code Assist Standard 또는 Enterprise 라이선스가 있는 경우에만 계속 작동합니다. 시작하기 전에 인증 방식을 결정하십시오.

배포판 패키지 버전이 너무 오래된 경우

Ubuntu 24.04는 자체 저장소에서 Node 18.19.1과 npm 9.2.0을 제공합니다. Gemini CLI의 package.json는 engines: { node: ">=20" }을 요구하지만, npm은 기본적으로 버전 불일치를 이유로 설치를 중단하지 않습니다. 대신 설치를 진행하고 다음과 같은 경고 메시지를 출력합니다:

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '@google/gemini-cli@0.50.0',
npm WARN EBADENGINE   required: { node: '>=20' },
npm WARN EBADENGINE   current: { node: 'v18.19.1', npm: '9.2.0' }
npm WARN EBADENGINE }

이 경고를 무시하고 CLI를 실행하면 지원되지 않는 런타임 환경에서 동작하게 됩니다. 이 경우 CLI가 기대하는 Node 20 이상의 API를 호출하는 순간 오작동하거나 비정상 종료됩니다. Node 18은 2025년 4월에 이미 수명이 종료되었으므로 어떤 방식으로든 더 이상 사용할 수 없습니다. CLI를 설치하기 전에 최신 LTS 버전을 설치하십시오. 가장 깔끔한 방법은 NodeSource(시스템 전체에 적용되는 서명된 apt 저장소)를 사용하거나 nvm(사용자별 버전 관리자)을 사용하는 것입니다. 둘 중 하나를 선택하십시오.

시스템의 모든 사용자가 Node를 사용할 수 있게 하려면 NodeSource를 사용하십시오:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version

CLI 요구 사항을 충족하려면 node --version 명령이 v20.x 이상의 버전을 출력해야 합니다. 하지만 Node 20은 2026년 4월 30일에 수명이 종료되었으므로, 현재 활성 LTS 버전인 v24.x을 목표로 하십시오. Node 26은 2026년 10월 28일에 활성 LTS가 될 예정입니다. 최신 설치 스크립트는 NodeSource 페이지에서 확인하십시오. URL에 포함된 setup_24.x는 더 새로운 LTS 버전이 출시될 때마다 변경해야 하는 부분입니다.

Node를 특정 사용자의 홈 디렉터리에 유지하고 sudo 권한을 사용하지 않으려면 nvm을 사용하십시오:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node --version

이 URL의 v0.40.1는 작성 시점의 최신 버전입니다. 실행하기 전에 nvm의 README를 확인하여 최신 릴리스 버전을 확인하고 해당 버전으로 교체하십시오. nvm은 이 작업에 있어 확실한 장점이 있습니다. Node와 전역 패키지를 ~/.nvm 아래에 설치하므로, 다음 섹션에서 다룰 전역 설치 권한 문제가 발생하지 않습니다. nvm을 선택했다면 npm-prefix 단계는 건너뛰어도 됩니다.

sudo npm -g 없이 CLI 설치하기

sudo npm install -g @google/gemini-cli 명령어를 사용하고 싶은 유혹이 들겠지만, 절대 사용하지 마십시오. root 소유의 전역 접두사(global prefix)를 사용하면 이후 모든 설치 과정에서 권한 오류가 발생하며, npm 캐시에 root 소유 파일이 남아 몇 달 뒤 문제를 일으킵니다. 시스템 Node 환경에서 sudo 없이 npm install -g 명령을 실행하면 다음과 같은 오류가 발생합니다.

npm error code EACCES
npm error syscall mkdir
npm error path /usr/lib/node_modules/@google
npm error errno -13
npm error Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/@google'

이는 npm이 /usr/lib 디렉터리에 쓰기를 시도하지만, 현재 사용자에게는 해당 권한이 없기 때문입니다. 해결책은 sudo를 사용하는 것이 아니라, npm의 전역 접두사를 홈 디렉터리로 지정하여 전역 설치 파일이 사용자가 소유한 경로에 저장되도록 하는 것입니다.

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @google/gemini-cli
gemini --version

~/.profile이 아닌 ~/.bashrc를 사용하는 것은 의도적인 선택입니다. 두 섹션 뒤에 CLI를 실행할 환경인 tmux는 비로그인 셸(non-login shell)을 시작합니다. 이 셸은 ~/.bashrc을 읽고 ~/.profile은 건너뛰기 때문에, 잘못된 파일에 PATH 줄을 추가하면 정작 필요한 곳에서 gemini을 인식할 수 없게 됩니다. gemini --version 명령을 실행하여 버전 번호가 출력되면 테스트가 완료된 것입니다. 만약 gemini: command not found가 출력된다면 PATH 내보내기가 적용되지 않은 것이니, 실패 유형을 확인하십시오. nvm을 사용하는 경우, nvm은 이미 홈 디렉터리 하위에 전역 패키지를 설치하므로 접두사 설정 줄을 완전히 생략하십시오.

이전에 sudo npm를 실행하여 현재 Your cache folder contains root-owned files 오류가 발생한다면, sudo chown -R $(id -u):$(id -g) ~/.npm 명령으로 한 번 복구하십시오.

헤드리스 인증 문제와 해결 방법

gemini을 처음 실행하면 Google 계정으로 로그인하라는 안내가 나옵니다. 데스크톱 환경에서는 브라우저 탭이 열리지만, 헤드리스 Linux VPS에서는 CLI가 먼저 디스플레이 환경을 확인합니다. DISPLAY, WAYLAND_DISPLAY, MIR_SOCKET이 설정되어 있지 않으면 브라우저를 실행하지 않고 로그인 링크를 출력한 뒤 코드를 입력받을 때까지 대기합니다.

Please visit the following URL to authorize the application:

https://accounts.google.com/o/oauth2/v2/auth?...

Enter the authorization code:

이 방식은 일반적인 SSH 환경에서 작동하지만, 매번 브라우저를 직접 조작해야 합니다. 또한 2026년 6월 18일부터는 Gemini CLI가 지원하는 Google 계정으로만 로그인이 가능합니다.

이를 해결하는 정석적인 방법은 두 가지입니다.

첫 번째는 API 키를 사용하는 방법이며, 서버 환경에서는 이 방식이 기본값으로 적합합니다. Gemini CLI는 더 이상 무료 사용을 지원하지 않으므로, 결제가 활성화된 프로젝트에서 Google AI Studio (aistudio.google.com)를 통해 키를 생성하십시오. 생성한 키를 환경 변수로 전달하면 CLI가 GEMINI_API_KEY을 읽어 브라우저 인증 과정을 완전히 건너뜁니다. 이때 키가 셸 기록이나 누구나 읽을 수 있는 파일에 남지 않도록 주의해야 합니다. 프롬프트에 직접 export GEMINI_API_KEY=AIza...를 입력하면 ~/.bash_history에 평문으로 저장되므로 절대 금물이며, 타인이 읽을 수 있는 파일에 저장해서도 안 됩니다. 셸이 시작될 때 불러오는 모드 600 파일에 다음과 같이 작성하십시오.

umask 077
printf 'export GEMINI_API_KEY=%s\n' 'AIzaSyYOUR_KEY_HERE' > ~/.gemini_env
chmod 600 ~/.gemini_env
echo '[ -f ~/.gemini_env ] && . ~/.gemini_env' >> ~/.bashrc
source ~/.bashrc

chmod 600는 해당 파일을 본인만 읽을 수 있게 제한합니다. printenv GEMINI_API_KEY를 실행하여 키가 환경 변수에 정상적으로 적용되었는지 확인하십시오. 아무것도 출력되지 않으면 CLI는 키를 사용하지 않고 인증 선택 화면으로 돌아갑니다. 이 설정은 ~/.gemini/ 경로의 .env 파일에서도 동일한 규칙으로 적용할 수 있으므로, 필요에 따라 chmod 600 ~/.gemini/.env을 사용하십시오.

두 번째 방법은 Google 직접 로그인 방식입니다. 헤드리스 환경에서는 별도의 터널이나 포트 개방이 필요 없습니다. 2026년 6월 18일 이후로는 주로 조직의 Gemini Code Assist Standard 또는 Enterprise 라이선스(GOOGLE_CLOUD_PROJECT도 함께 설정)를 사용할 때 유용하며, 개인 무료 계정이나 Google AI Pro 또는 Ultra 구독은 더 이상 지원되지 않습니다. 일반 SSH 세션에서 CLI를 시작하고 Google 로그인을 선택하십시오.

gemini

출력된 URL을 노트북 브라우저에 복사하여 승인하십시오. Google이 https://codeassist.google.com/authcode으로 리다이렉트하며 인증 코드를 보여줍니다. 이 코드를 VPS의 Enter the authorization code: 프롬프트에 붙여넣으면 로그인이 완료됩니다. 서버 측에서 콜백을 대기하지 않으므로 포트를 고정하거나 ssh -L를 설정할 필요가 없습니다. OAUTH_CALLBACK_PORT은 CLI가 디스플레이를 감지했을 때 사용하는 루프백 흐름에서만 중요합니다. X11 포워딩(ssh -X)으로 접속하면 DISPLAY가 설정되어 CLI가 서버의 http://127.0.0.1:PORT/oauth2callback으로 리다이렉트하는 루프백 흐름을 시도합니다. 이때 NO_BROWSER=true gemini을 실행하면 코드 붙여넣기 흐름을 강제로 사용할 수 있습니다. 이 방식도 작동은 하지만 브라우저를 직접 조작해야 하므로 스크립트 자동화에는 적합하지 않습니다. 상시 실행되는 작업에는 반드시 API 키를 사용하십시오.

AI Studio 대신 Vertex AI나 Google Cloud 프로젝트를 사용하는 경우, GOOGLE_GENAI_USE_VERTEXAI=true와 함께 GOOGLE_API_KEY을 설정하거나 Code Assist 라이선스를 위해 GOOGLE_CLOUD_PROJECT을 설정하십시오. 환경 변수 관리 규칙과 모드 600 파일 사용법은 동일합니다.

SSH 세션이 끊겨도 프로세스가 종료되지 않도록 tmux 내부에서 실행하기

SSH 셸에서 직접 실행한 gemini 프로세스는 해당 셸의 자식 프로세스입니다. 연결이 끊기거나, 노트북을 닫거나, Wi-Fi가 해제되거나, 유휴 시간 초과가 발생하면 sshd는 의사 터미널(pseudo-terminal)을 종료합니다. 이때 셸은 SIGHUP 신호를 받고 CLI 프로세스도 함께 종료됩니다. 파일 편집 중 10분 동안 작업한 내용이 사라지며, 재연결해도 복구할 프로세스가 남아있지 않게 됩니다.

tmux는 sshd 대신 셸을 소유함으로써 이 문제를 해결합니다. 이는 tmux 내부에서 원격 VPS의 AI 코딩 에이전트 실행하기와 동일한 패턴이며, 여기서도 똑같이 작동합니다.

sudo apt install -y tmux
tmux new -A -s gemini
# inside the session:
gemini
# detach with Ctrl-b then d, the task keeps running
# reconnect later from any machine:
tmux attach -t gemini

tmux new -A -s gemini는 gemini라는 이름의 세션이 존재하면 해당 세션에 연결하고, 없으면 새로 생성합니다. 따라서 로그인 직후 실행해야 할 유일한 명령어입니다. 내부 셸은 SSH 세션이 아닌 분리된(detached) tmux 서버에 속하므로, 연결이 끊겨도 CLI 작업은 계속 유지됩니다. 재연결 후 다시 연결(attach)하면 이전 스크롤 기록을 그대로 확인할 수 있습니다. 한 서버에서 여러 에이전트 세션을 tmux 세션당 하나씩 실행하는 경우, 한 세션이 동일한 VPS의 다른 세션으로 텍스트를 전달할 수 있는 Claude Code와 달리 이들은 서로 통신할 수 없습니다. 따라서 각 Gemini 작업은 독립적으로 유지하거나 디스크의 파일을 통해 조정해야 합니다.

비대화형 스크립트 실행을 위해 Gemini CLI는 헤드리스(headless) 모드를 지원합니다. gemini -p "summarise the failing tests in this repo"은 답변을 출력하고 종료하며, --output-format json은 다른 곳으로 파이프할 수 있는 기계 판독 가능한 출력을 제공합니다. API 키를 사용하는 헤드리스 모드는 긴 배치 작업을 실행하는 tmux 세션 내부나 cron 항목에서 실행할 때 적합합니다. 단, 한 가지 주의할 점은 cron 작업은 로그인 파일을 로드하지 않는다는 것입니다. 따라서 crontab 라인에 자체 GEMINI_API_KEY을 지정하거나 명령어가 ~/.gemini_env를 소스(source)하도록 설정해야 합니다. 그렇지 않으면 자격 증명 부족으로 실행이 실패합니다.

운영 환경이 포함된 서버에서의 샌드박싱 및 권한 관리

셸 접근 권한을 가진 에이전트는 곧 셸 그 자체입니다. Gemini CLI는 명령을 실행할 수 있으며, 기본적으로 위험한 명령을 실행하기 전에 사용자에게 확인을 요청합니다. 하지만 사용자가 --yolo(모든 도구 호출 자동 승인) 옵션을 사용하게 되면, 에이전트는 실행 중인 사용자의 전체 권한을 사용하여 파일을 삭제하거나, git에 푸시하거나, 내부 서비스에 접근할 수 있습니다. 운영 환경이 함께 돌아가는 서버에서 이는 가상의 위협이 아니라 실제적인 폭발 반경(blast radius)을 의미합니다.

효과가 큰 순서대로 세 가지 제어 방법을 제안합니다.

  • 전용 비특권 사용자로 실행하십시오. root 계정이나 sudo 그룹의 멤버가 아닌 사용자를 사용해야 합니다. 별도의 홈 디렉터리를 가진 agent 사용자를 생성하고 그곳에 Node와 CLI를 설치하십시오. 이렇게 하면 잘못된 명령이 실행되더라도 해당 계정 내에만 영향이 국한됩니다. 이는 보안을 위해 취할 수 있는 가장 가치 있는 결정입니다.
  • 운영 환경의 자격 증명을 서버에 두지 마십시오. 운영 환경의 ~/.aws/credentials, 운영 환경에서 복사해 온 .env, 중요한 데이터베이스에 쓰기 권한이 있는 비밀번호 등을 서버에 저장하지 마십시오. 대신 스테이징 환경용 자격 증명이나 읽기 전용 자격 증명을 부여하십시오.
  • 내장 샌드박스를 사용하십시오. Docker나 Podman이 설치된 환경에서 gemini --sandbox(또는 GEMINI_SANDBOX=docker)를 사용하면, 에이전트의 도구 호출이 호스트 파일 시스템 전체가 아닌 현재 프로젝트 디렉터리만 마운트된 컨테이너 내부에서 실행됩니다. 이는 비특권 사용자 사용을 대체할 수는 없지만, 동일한 VPS에서 실제 운영 업무를 병행할 때 강력한 2차 방어선이 됩니다.

Gemini CLI를 다른 자체 호스팅 도구와 함께 실행하는 경우, 예를 들어 동일한 VPS에서 에이전트에 도구를 노출하는 MCP 서버를 사용하는 상황이라면, 추가되는 각 기능을 에이전트가 접근할 수 있는 공격 표면으로 간주하십시오. 또한 에이전트에 부여되는 토큰은 정확히 하나의 작업만 수행할 수 있도록 범위를 제한하십시오.

할당량, 비용 및 인증 경로 선택

인증 경로는 과금 방식을 결정하며, 2026년 6월 18일부터는 서비스 이용 가능 여부까지 결정합니다. Google의 발표에 따라 해당 날짜부터 Gemini CLI는 Google AI Pro 및 Ultra 구독자와 무료 계층(개인 계정 무료 티어 및 미청구 API 키 포함) 사용자에 대한 요청 처리를 중단했습니다. 현재는 토큰당 과금되는 유료 Gemini API 키 및 Gemini Enterprise Agent Platform API 키를 사용하거나, Gemini Code Assist Standard 또는 Enterprise 라이선스를 보유한 조직, 혹은 Google Cloud를 통해 과금되는 기타 Google Cloud 접근 권한을 가진 경우에 이용할 수 있습니다. 각 티어에는 여전히 분당 및 일일 제한이 존재하며, 이를 초과하면 제한 시간이 초기화될 때까지 요청 시 rate-limit 오류가 반환됩니다.

두 가지 실무적인 참고 사항입니다. 루프 내에서 실행되는 무인 에이전트는 할당량을 빠르게 소진할 수 있으므로, cron job으로 자동화하기 전에 처음 몇 번은 직접 모니터링하십시오. 만약 서버 측 모델을 사용하는 이유가 Google의 호스팅 모델이 아닌 개인정보 보호나 무제한 추론에 있다면, 이는 다른 도구의 영역입니다. Ollama를 사용하여 VPS에서 오픈 LLM을 직접 호스팅하는 방법은 가중치와 프롬프트를 자신의 서버 내에 유지할 수 있게 해주지만, Gemini보다 훨씬 작은 모델을 운영해야 한다는 비용이 따릅니다.

업데이트 유지하기

Gemini CLI는 자주 릴리스됩니다. 사용자 소유의 경로에 설치했으므로 업데이트 시 sudo 권한이 필요하지 않습니다.

npm install -g @google/gemini-cli@latest
gemini --version

릴리스 채널이 존재합니다. @latest은 안정 버전, @preview은 주간 미리보기 버전, @nightly는 최신 개발 버전입니다. 운영 환경에서는 @latest으로 고정하십시오. nvm을 사용하는 경우 전역 패키지는 활성화된 Node 버전에 종속되므로, nvm use를 사용하여 Node 버전을 변경한 후에는 CLI를 다시 설치해야 할 수 있습니다. 모든 패치를 일일이 쫓기보다는 릴리스 노트를 확인하십시오.

실패 유형 및 정확한 문자열

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' } 및 런타임 시 CLI 충돌. Node 버전이 너무 낮습니다. 배포판의 18.19.1 버전은 이미 지원이 종료되었습니다. NodeSource나 nvm을 통해 최신 LTS 버전을 설치하십시오(Node 20은 CLI의 최소 요구 사항을 충족하지만 2026년 4월부로 지원이 종료되었습니다). node --version 명령으로 설치를 확인하고, 여러 Node 버전이 설치되어 있다면 which node가 /usr/bin/node이 아닌 새 버전을 가리키고 있는지 확인하십시오.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. root 소유의 경로에 전역으로 설치된 경우입니다. sudo를 사용하지 말고 npm config set prefix ~/.npm-global을 설정한 뒤, ~/.npm-global/bin를 PATH에 추가하고 일반 사용자 권한으로 다시 설치하십시오. 이전 sudo npm 실행으로 인해 root 소유의 캐시 파일(Your cache folder contains root-owned files)이 남아 있다면 sudo chown -R $(id -u):$(id -g) ~/.npm을 실행하십시오.

Failed to open browser 또는 http://127.0.0.1:PORT을 가리키는 redirect_uri에 도달할 수 없는 경우. CLI가 (주로 ssh -X에서 유래한) 디스플레이 변수를 감지하여 루프백 흐름을 시도했으나, 콜백이 서버에서 멈춘 상태입니다. NO_BROWSER=true gemini을 실행하여 코드를 붙여넣는 흐름을 사용하거나 API 키 경로(GEMINI_API_KEY)를 이용하십시오. 일반적인 SSH 세션에서는 Enter the authorization code:가 표시되어야 합니다. 노트북 브라우저에서 해당 URL을 승인하고 Google이 제공하는 코드를 붙여넣으십시오.

SSH 연결이 끊기자 프로세스가 사라짐. SSH 셸에서 직접 gemini을 실행했기 때문에 해당 셸의 자식 프로세스로 동작하다가 연결 해제 시 pty와 함께 종료된 것입니다. 복구할 방법은 없습니다. 모든 세션은 tmux new -A -s gemini로 시작하고 그 안에서 CLI를 실행하십시오.

키를 설정했음에도 인증 실패, CLI가 인증 선택 화면으로 돌아감, 또는 요청 시 HTTP 400와 함께 API key not valid 반환. CLI가 인식하는 환경 변수에 키가 없는 상태입니다. printenv GEMINI_API_KEY으로 확인하십시오. 값이 비어 있다면 ~/.gemini_env이 로드되지 않은 것입니다. 해당 줄이 ~/.bashrc에 포함되어 있는지 확인하십시오. 대화형 셸(tmux 포함)은 이 파일을 읽지만, cron과 같은 비대화형 셸은 읽지 않습니다. 키 값 내부에 불필요한 공백이나 따옴표가 포함되어 있어도 API key not valid 오류가 발생합니다.

429 / RESOURCE_EXHAUSTED / 속도 제한 메시지. 인증 계층의 할당량을 초과했습니다. 제한이 초기화될 때까지 기다리거나, 에이전트의 속도를 늦추거나, 유료 API 키로 전환하십시오. 재시도 루프에 빠진 에이전트는 계속해서 이 오류를 발생시키므로, 에이전트를 중단하고 동작을 확인하십시오.

FAQ

헤드리스 서버에서 Gemini CLI를 어떻게 인증합니까?

브라우저 로그인이 아닌 유료 API 키를 사용하십시오. 결제가 설정된 프로젝트의 Google AI Studio에서 키를 생성한 뒤, 셸이 참조하는 모드 600 파일(export GEMINI_API_KEY=...)에 저장하십시오. 이렇게 하면 CLI가 OAuth 브라우저 흐름을 완전히 건너뜁니다. Code Assist Standard 또는 Enterprise 라이선스처럼 Google 계정으로 로그인하는 경우, 헤드리스 서버의 CLI가 URL을 출력합니다. 이 URL을 노트북에서 열어 승인한 뒤, Google이 제공하는 코드를 Enter the authorization code: 프롬프트에 붙여넣으십시오. 고정할 포트나 터널은 필요 없으나, 브라우저를 사용할 수 있는 사용자가 직접 조작해야 하므로 스크립트 자동화에는 적합하지 않습니다. 2026년 6월 18일부터 개인용 무료 계정은 Gemini CLI를 지원하지 않습니다.

npm 전역 설치 시 왜 sudo를 요구하며, 이를 피하는 방법은 무엇입니까?

npm의 기본 전역 접두사가 /usr/lib/node_modules로 설정되어 있는데, 일반 사용자는 이곳에 쓰기 권한이 없기 때문에 npm install -g 명령을 실행하면 EACCES 오류가 발생합니다. sudo npm -g를 사용하는 것은 잘못된 해결책이며, root 소유의 파일이 생성되어 추후 설치 시 문제를 일으킵니다. 올바른 해결책은 접두사를 홈 디렉터리(npm config set prefix ~/.npm-global)로 지정하고 해당 bin를 PATH에 추가하는 것입니다. 또는 홈 디렉터리 아래에 전역 패키지를 자동으로 설치해 주는 nvm을 사용하십시오.

연결을 끊은 뒤에도 Gemini CLI를 계속 실행하려면 어떻게 해야 합니까?

tmux 내부에서 실행하십시오. SSH 셸에서 시작한 프로세스는 해당 셸의 자식 프로세스이므로 연결이 끊기면 종료됩니다. tmux는 연결이 끊겨도 유지되는 분리된 서버 환경에서 셸을 실행합니다. tmux new -A -s gemini을 사용하고, 내부에서 gemini을 실행한 뒤, Ctrl-b d로 분리하고, 나중에 tmux attach -t gemini로 다시 접속하십시오.

운영 서버에서 Gemini CLI를 실행해도 안전합니까?

셸 접근 권한이 있는 에이전트는 해당 사용자가 할 수 있는 모든 작업을 수행할 수 있으므로 주의가 필요합니다. sudo 권한이 없는 전용 비권한 사용자로 실행하고, 운영용 자격 증명을 해당 장비에 두지 마십시오. --yolo 자동 승인 기능을 피하고, --sandbox(Docker 또는 Podman)을 사용하여 도구 호출을 호스트로부터 격리하십시오. 어떤 플래그를 설정하는지보다 어떤 계정으로 실행하는지가 훨씬 중요합니다.

Gemini CLI를 위해 방화벽 포트를 열어야 합니까?

아니요. Gemini CLI는 Google API로 아웃바운드 HTTPS 호출을 보내는 클라이언트이므로 아웃바운드 443 포트만 필요하며 인바운드 포트는 필요 없습니다. 헤드리스 서버에서의 Google 로그인 또한 포트가 필요하지 않습니다. 서버에서 콜백을 받는 대신 터미널에 코드를 직접 붙여넣기 때문입니다. 인바운드 포트는 계속 차단 상태로 유지하십시오.

#gemini-cli#node#tmux#headless#ai#vps