Gemini CLI auf einem Headless-VPS ausführen

Was Sie aufbauen

Eine dauerhaft laufende Gemini CLI auf einem Server, den Sie selbst verwalten. Sie greifen über SSH darauf zu. Die CLI führt lang laufende Agent-Aufgaben aus, die auch dann weiterlaufen, wenn Sie den Laptop schließen. Für die Installation benötigen Sie drei Befehle. Der eigentliche Aufwand liegt in allem, was eine Desktop-Umgebung voraussetzt: Die CLI von Google möchte zum Anmelden einen Browser öffnen. Auf Ihrem Server ist jedoch kein Browser vorhanden. Deshalb behandelt der größte Teil dieser Anleitung den Betrieb ohne grafische Oberfläche, eine aktuelle Node-Version, die die Distribution nicht bereitstellt, eine globale npm-Installation ohne root, die Anmeldung ohne Browser mit einem API-Schlüssel, der nicht in der Shell-History landet, sowie tmux, damit eine getrennte SSH-Sitzung keine laufende Aufgabe beendet.

Gemini CLI ist ein Open-Source-Programm (Apache-2.0) für Node (@google/gemini-cli). Es kommuniziert mit den Gemini-Modellen von Google, kann Dateien lesen und schreiben, Shell-Befehle ausführen und Tools im Arbeitsverzeichnis steuern. Auf einem VPS ist es ein kleiner, jederzeit verfügbarer Agent, den Sie laufend arbeiten lassen können. Deshalb sind das Konto, unter dem er ausgeführt wird, und die auf dem Server gespeicherten Zugangsdaten wichtiger als jede einzelne Einstellung in dieser Anleitung.

Voraussetzungen und wichtige Einschränkungen

• Ein frischer Ubuntu-24.04-KVM-VPS mit root oder sudo. Jeder KVM-Tarif ist geeignet. Die CLI selbst benötigt nur wenige hundert MB RAM im Ruhezustand.
• Node.js 20 oder neuer. Dies ist die einzige feste Mindestversion. Das Distributionspaket liegt darunter, siehe den nächsten Abschnitt. Node 20 hat am April 30, 2026 das End-of-Life erreicht. Installieren Sie daher Node.js 24.
• Ausgehendes HTTPS (Port 443) zu den APIs von Google. Eingehende Ports sind nicht erforderlich. Dies ist ein Client und kein Server. Sie müssen dafür keine Firewall-Regel für eingehenden Verkehr öffnen.
• Eine Authentifizierungsmethode, die keinen Browser auf dem Server benötigt: entweder einen kostenpflichtigen Gemini-API-Schlüssel aus Google AI Studio oder die Google-Anmeldung. Bei einem Headless-System müssen Sie dabei einen Code zurück in das Terminal einfügen. Die API-Key-Methode eignet sich für Skripte und unbeaufsichtigte Ausführungen.
• Docker oder Podman, nur wenn Sie die --sandbox-Isolation verwenden möchten. Dies ist optional und wird gegen Ende behandelt.

Die Einschränkung, die derzeit viele überrascht, betrifft das Konto und nicht den Browser. Google hat am May 19, 2026 angekündigt, dass Gemini CLI ab June 18, 2026 keine Anfragen mehr für Abonnenten von Google AI Pro und Ultra sowie für Nutzer ohne kostenpflichtigen Zugang ausführt. Diese Nutzer werden auf den Ersatz Antigravity CLI (agy) verwiesen. Gemini CLI funktioniert weiterhin mit kostenpflichtigen Gemini-API-Schlüsseln, Gemini Enterprise Agent Platform API-Schlüsseln sowie mit der Gemini Code Assist Standard- oder Enterprise-Lizenz einer Organisation. Legen Sie den Authentifizierungsweg fest, bevor Sie beginnen.

Node: Das Distributionspaket ist zu alt

Ubuntu 24.04 stellt in seinen eigenen Paketquellen Node 18.19.1 zusammen mit npm 9.2.0 bereit. Die package.json von Gemini CLI deklariert engines: { node: ">=20" }. npm bricht bei einer Abweichung standardmäßig nicht ab, sondern installiert das Paket trotzdem und gibt eine Warnung aus, die den Unterschied nennt:

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 }

Wenn Sie diese Warnung ignorieren, läuft die CLI mit einer nicht unterstützten Runtime. Sie verhält sich fehlerhaft oder stürzt ab, sobald sie eine Node-20+-API verwendet, die vorhanden sein sollte. Node 18 hat außerdem im April 2025 das Ende seiner Lebensdauer erreicht. Diese Version ist daher unabhängig davon keine sinnvolle Option. Installieren Sie eine aktuelle LTS-Version, bevor Sie die CLI installieren. Dafür gibt es zwei saubere Wege: NodeSource, ein systemweit verfügbares signiertes apt-Repository, oder nvm, ein Versionsmanager pro Benutzer. Wählen Sie einen davon.

NodeSource, wenn Node für alle Benutzer auf dem System verfügbar sein soll:

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

node --version muss v20.x oder höher ausgeben, damit die CLI unterstützt wird. Node 20 hat jedoch seit dem 30. April 2026 das Ende seiner Lebensdauer erreicht. Verwenden Sie daher möglichst v24.x, die aktuell aktive LTS-Version. Node 26 soll am 28. Oktober 2026 zur aktiven LTS-Version werden. Prüfen Sie die NodeSource-Seite auf das aktuelle Einrichtungsskript. Das setup_24.x in der URL ist die Versionsangabe, die Sie anpassen müssen, sobald eine neuere LTS-Version verfügbar ist.

nvm, wenn Node im Home-Verzeichnis eines einzelnen Benutzers bleiben und niemals mit sudo verwaltet werden soll:

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

v0.40.1 in dieser URL war zum Zeitpunkt der Erstellung dieses Textes aktuell. Prüfen Sie die README von nvm auf die neueste Version und ersetzen Sie die Versionsangabe, bevor Sie das Skript ausführen. nvm bietet für diesen Anwendungsfall einen wesentlichen Vorteil: Node und seine global installierten Pakete werden unter ~/.nvm installiert. Das Berechtigungsproblem bei globalen Installationen aus dem nächsten Abschnitt tritt dadurch nicht auf. Wenn Sie nvm verwenden, können Sie den Schritt zur npm-Präfixkonfiguration überspringen.

CLI ohne sudo npm -g installieren

Der naheliegende Befehl ist sudo npm install -g @google/gemini-cli. Verwenden Sie ihn nicht. Ein globales, root-eigenes Präfix führt bei jeder späteren Installation zu Berechtigungsfehlern. Außerdem bleiben root-eigene Dateien in Ihrem npm-Cache zurück, die Ihnen noch Monate später Probleme bereiten. Wenn Sie ein einfaches (ohne sudo) npm install -g mit einem systemweiten Node ausführen, tritt der andere Fehler auf:

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 versucht dabei, in /usr/lib zu schreiben. Ihr Benutzer hat dort keine Berechtigung. Die Lösung ist nicht sudo. Setzen Sie stattdessen das globale Präfix von npm auf Ihr Home-Verzeichnis. Dann landen globale Installationen an einem Ort, den Sie besitzen:

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

~/.bashrc und nicht ~/.profile ist beabsichtigt. tmux, in dem Sie die CLI zwei Abschnitte später ausführen, startet eine Nicht-Login-Shell. Diese liest ~/.bashrc und überspringt ~/.profile. Eine PATH-Zeile in der falschen Datei lässt gemini genau dort unsichtbar, wo Sie es benötigen. Wenn gemini --version eine Versionsnummer ausgibt, ist der Test abgeschlossen. Erhalten Sie stattdessen gemini: command not found, wurde Ihr PATH-Export nicht übernommen. Weitere Informationen finden Sie unter den Fehlerursachen. Bei nvm überspringen Sie die Präfixzeilen vollständig. nvm installiert globale Pakete bereits unter Ihrem Home-Verzeichnis.

Wenn Sie zuvor sudo npm ausgeführt haben und jetzt Your cache folder contains root-owned files sehen, beheben Sie das einmalig mit sudo chown -R $(id -u):$(id -g) ~/.npm.

Das Headless-Authentifizierungsproblem und wie Sie es umgehen

Führen Sie gemini beim ersten Mal interaktiv aus. Das Programm bietet Ihnen dann die Anmeldung mit Ihrem Google-Konto an. Auf einem Desktop wird ein Browser-Tab geöffnet. Auf einem Headless-Linux-VPS prüft die CLI zuerst, ob eine Anzeige verfügbar ist. Wenn DISPLAY, WAYLAND_DISPLAY und MIR_SOCKET nicht gesetzt sind, versucht sie nicht, einen Browser zu starten. Stattdessen gibt sie einen Anmeldelink aus und wartet darauf, dass Sie einen Code zurückkopieren:

Please visit the following URL to authorize the application:

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

Enter the authorization code:

Dieser Ablauf funktioniert über eine normale SSH-Verbindung. Sie müssen dafür jedoch jedes Mal einen Browser verwenden. Seit dem 18. Juni 2026 erhalten Sie damit außerdem nur Zugriff, wenn Ihr Google-Konto weiterhin von Gemini CLI unterstützt wird.

Dafür gibt es zwei praktikable Möglichkeiten.

Die erste Möglichkeit ist ein API-Schlüssel. Für einen Server ist dies die richtige Standardlösung. Erstellen Sie in Google AI Studio (aistudio.google.com) einen Schlüssel für ein Projekt, in dem die Abrechnung aktiviert ist, da Gemini CLI keine kostenlose Nutzung mehr anbietet. Übergeben Sie den Schlüssel als Umgebungsvariable an die CLI. Sie liest GEMINI_API_KEY und überspringt den Browser-Ablauf vollständig. Nun zum Schutz vor Einträgen in der Shell-Historie und vor Dateien mit globalem Lesezugriff: Geben Sie export GEMINI_API_KEY=AIza... nicht direkt an der Eingabeaufforderung ein. Der Wert landet dort im Klartext in ~/.bash_history. Legen Sie ihn auch nicht in einer Datei ab, die andere Benutzer lesen können. Schreiben Sie ihn in eine Datei mit den Berechtigungen mode 600, die die Shell beim Start einliest:

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 bedeutet, dass nur Ihr Benutzer die Datei lesen kann. Prüfen Sie mit printenv GEMINI_API_KEY, ob der Schlüssel in der Umgebung angekommen ist. Gibt dieser Befehl nichts aus, verwendet die CLI den Schlüssel nicht, sondern wechselt zurück zur Auswahl der Authentifizierungsmethode. Sie liest außerdem eine Datei .env unter ~/.gemini/, wenn Sie dieses Layout bevorzugen. Dabei gilt dieselbe Regel: chmod 600 ~/.gemini/.env.

Die zweite Möglichkeit ist die Anmeldung bei Google selbst. Auf einem Headless-System benötigen Sie dafür weder einen Tunnel noch einen offenen Port. Seit dem 18. Juni 2026 ist diese Methode hauptsächlich für eine Gemini-Code-Assist-Lizenz vom Typ Standard oder Enterprise einer Organisation sinnvoll. Setzen Sie zusätzlich GOOGLE_CLOUD_PROJECT. Kostenlose persönliche Konten sowie Google-AI-Pro- oder -Ultra-Abonnements werden nicht mehr unterstützt. Starten Sie die CLI über eine normale SSH-Sitzung und wählen Sie Sign in with Google:

gemini

Kopieren Sie die ausgegebene URL in den Browser Ihres Laptops und bestätigen Sie die Anmeldung. Google leitet Sie zu https://codeassist.google.com/authcode weiter. Dort wird ein Autorisierungscode angezeigt. Fügen Sie diesen am Enter the authorization code:-Prompt auf dem VPS ein. Danach ist die Anmeldung abgeschlossen. Auf dem Server wartet nichts auf einen Callback. Daher müssen Sie keinen Port festlegen und kein ssh -L einrichten. OAUTH_CALLBACK_PORT ist nur für den Loopback-Ablauf relevant, den die CLI verwendet, wenn sie eine Anzeige erkennt. Wenn Sie eine Verbindung mit X11-Forwarding (ssh -X) hergestellt haben, ist DISPLAY gesetzt. Die CLI verwendet dann stattdessen diesen Loopback-Ablauf und leitet zu http://127.0.0.1:PORT/oauth2callback auf dem Server weiter. Führen Sie NO_BROWSER=true gemini aus, um den Ablauf mit dem Zurückkopieren eines Codes zu erzwingen. Das funktioniert, erfordert aber einen Browser und ist daher für Skripte ungeeignet. Verwenden Sie für dauerhaft laufende Prozesse den API-Schlüssel.

Für Vertex AI oder ein Google-Cloud-Projekt anstelle von AI Studio setzen Sie GOOGLE_API_KEY zusammen mit GOOGLE_GENAI_USE_VERTEXAI=true. Für eine Code-Assist-Lizenz verwenden Sie GOOGLE_CLOUD_PROJECT. Auch hier gelten dieselben Regeln für Umgebungsvariablen und für eine Datei mit den Berechtigungen mode 600.

Führen Sie es innerhalb von tmux aus, damit eine getrennte SSH-Sitzung den Prozess nicht beendet

Ein gemini-Prozess, den Sie direkt aus Ihrer SSH-Shell starten, ist ein Kindprozess dieser Shell. Wenn die Verbindung verloren geht, der Laptop geschlossen wird, das WLAN ausfällt oder ein Leerlauf-Timeout eintritt, baut sshd das Pseudo-Terminal ab. Die Shell empfängt SIGHUP und beendet daraufhin ebenfalls die CLI. Ein Prozess, der seit zehn Minuten Dateien bearbeitet, wird dabei beendet. Nach der erneuten Verbindung gibt es keinen Prozess, den Sie wieder aufnehmen können.

tmux löst dieses Problem, indem es die Shell besitzt, statt dass sshd sie besitzt. Das entspricht demselben Muster wie beim Ausführen eines KI-Coding-Agenten auf einem entfernten VPS innerhalb von tmux und funktioniert auch hier identisch:

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 verbindet Sie mit einer Sitzung namens gemini, falls diese existiert, und erstellt sie andernfalls. Deshalb ist dies der eine Befehl, den Sie direkt nach jeder Anmeldung ausführen sollten. Die darin laufende Shell gehört zum getrennten tmux-Server und nicht zu Ihrer SSH-Sitzung. Wenn die Verbindung abbricht, arbeitet die CLI weiter. Verbinden Sie sich erneut, hängen Sie die Sitzung wieder ein, und Sie sehen denselben Scrollback. Wenn Sie auf einem Server mehrere Agent-Sitzungen ausführen, verwenden Sie jeweils eine eigene tmux-Sitzung. In diesem Fall können sie nicht miteinander kommunizieren. Das ist anders als bei Claude Code, bei dem eine Sitzung Text an eine andere Sitzung auf demselben VPS übergeben kann. Halten Sie daher jeden Gemini-Auftrag unabhängig oder koordinieren Sie ihn über Dateien auf dem Datenträger.

Für nicht interaktive, skriptgesteuerte Ausführungen bietet Gemini CLI einen Headless-Modus: gemini -p "summarise the failing tests in this repo" gibt eine Antwort aus und wird beendet, während --output-format json eine maschinenlesbare Ausgabe für die Weiterleitung an andere Prozesse liefert. Der Headless-Modus mit einem API-Schlüssel eignet sich genau für eine tmux-Sitzung, in der ein längerer Batch-Auftrag läuft, oder für den Start aus einem Cron-Eintrag. Es gibt jedoch eine Einschränkung: Ein Cron-Auftrag lädt keine Ihrer Login-Dateien. Geben Sie der Crontab-Zeile daher ein eigenes GEMINI_API_KEY mit, oder lassen Sie den Befehl ~/.gemini_env laden. Andernfalls schlägt die Ausführung wegen fehlender Zugangsdaten fehl.

Sandboxing und Berechtigungen auf einem System, auf dem auch Produktionsdienste laufen

Ein Agent mit Shell-Zugriff ist eine Shell. Gemini CLI kann Befehle ausführen. Standardmäßig fragt es vor jedem riskanten Befehl nach. Viele greifen jedoch zu --yolo (automatische Genehmigung jedes Tool-Aufrufs). Dann kann der Agent Dateien löschen, in git pushen oder interne Dienste mit den vollständigen Berechtigungen des Benutzers aufrufen, unter dem er läuft. Auf einem System, auf dem auch Produktionsdienste laufen, ist das ein realer Schadensradius und keine hypothetische Möglichkeit.

Drei Schutzmaßnahmen, geordnet nach ihrem Nutzen:

• Führen Sie den Agenten unter einem eigenen, nicht privilegierten Benutzer aus. Nicht als root und nicht als Mitglied von sudo. Erstellen Sie einen agent-Benutzer mit eigenem Home-Verzeichnis und installieren Sie Node sowie die CLI dort. Eine falsch verstandene Anweisung bleibt dann auf dieses Konto beschränkt. Dies ist die wichtigste einzelne Entscheidung.
• Halten Sie Produktionszugangsdaten vom System fern. Keine Produktions-~/.aws/credentials, kein aus der Produktion kopiertes .env und kein Datenbankpasswort mit Schreibzugriff auf relevante Ressourcen. Verwenden Sie Zugangsdaten für Staging oder mit Leseberechtigung.
• Verwenden Sie die integrierte Sandbox. Wenn Docker oder Podman installiert ist, führt gemini --sandbox (oder GEMINI_SANDBOX=docker) die Tool-Aufrufe des Agenten in einem Container aus. Dieser bindet nur das aktuelle Projektverzeichnis ein, nicht das übrige Dateisystem des Hosts. Die Sandbox ersetzt den nicht privilegierten Benutzer nicht. Sie ist jedoch eine starke zweite Schutzschicht, wenn derselbe VPS produktive Aufgaben ausführt.

Wenn Sie Gemini CLI neben anderen selbst gehosteten Tools ausführen, etwa neben einem MCP-Server, der dem Agenten auf demselben VPS Tools bereitstellt, betrachten Sie jede zusätzliche Fähigkeit als weitere Angriffsfläche, die der Agent erreichen kann. Beschränken Sie die übergebenen Token genau auf jeweils eine Aufgabe.

Kontingent, Kosten und der gewählte Authentifizierungspfad

Der Authentifizierungspfad bestimmt, wie Sie abgerechnet werden und seit dem 18. Juni 2026 auch, ob Sie den Dienst überhaupt nutzen können. Seit diesem Datum verarbeitet Gemini CLI laut der Ankündigung von Google keine Anfragen mehr für Abonnenten von Google AI Pro und Ultra sowie für Nutzer, die es kostenlos verwenden. Dazu gehören die kostenlose Nutzung mit einem persönlichen Konto und nicht abgerechnete API-Schlüssel. Der Dienst bleibt über kostenpflichtige Gemini API-Schlüssel und Gemini Enterprise Agent Platform API-Schlüssel verfügbar. Diese werden pro Token abgerechnet. Er bleibt außerdem für Organisationen mit einer Gemini Code Assist Standard- oder Enterprise-Lizenz oder mit anderem Google Cloud-Zugriff verfügbar. Die Abrechnung erfolgt in diesen Fällen über Google Cloud. Für jede Stufe gelten weiterhin Limits pro Minute und pro Tag. Wenn Sie diese überschreiten, geben Anfragen bis zum Zurücksetzen des Zeitfensters einen Rate-Limit-Fehler zurück.

Zwei praktische Hinweise: Ein unbeaufsichtigter Agent in einer Schleife kann ein Kontingent schnell aufbrauchen. Überwachen Sie ihn daher in den ersten Durchläufen, bevor Sie ihn einem cron-Job anvertrauen. Wenn Sie ein serverseitiges Modell wegen Datenschutz oder nicht gemessener Inferenz statt wegen der gehosteten Modelle von Google einsetzen möchten, handelt es sich um ein anderes Werkzeug. Das Self-Hosting eines offenen LLM mit Ollama auf einem VPS hält die Gewichte und Prompts auf Ihrem eigenen System. Dafür führen Sie ein deutlich kleineres Modell als Gemini aus.

Aktualisierung

Gemini CLI wird häufig veröffentlicht. Da Sie es in einem Präfix installiert haben, das Ihrem Benutzer gehört, benötigen Aktualisierungen niemals sudo:

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

Es gibt mehrere Release-Kanäle: @latest ist stabil, @preview ist die wöchentliche Vorschauversion und @nightly ist die neueste Entwicklungsversion. Fixieren Sie bei allem, worauf Sie angewiesen sind, die Version auf @latest. Bei nvm werden globale Pakete unter der aktiven Node-Version installiert. Nach nvm use zum Wechseln der Node-Version müssen Sie die CLI daher möglicherweise erneut installieren. Lesen Sie die Release Notes, statt jedem Patch nachzulaufen.

Fehlerbilder mit den genauen Zeichenfolgen

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, danach stürzt die CLI zur Laufzeit ab. Node ist zu alt. Die Distribution enthält 18.19.1, das ebenfalls bereits das Ende seines Lebenszyklus erreicht hat. Installieren Sie eine aktuelle LTS-Version über NodeSource oder nvm. Node 20 erfüllt zwar die Mindestversion der CLI, hat aber selbst seit April 2026 das Ende seines Lebenszyklus erreicht. Prüfen Sie dies mit node --version. Wenn mehrere Node-Versionen installiert sind, prüfen Sie, ob which node auf die neue Version und nicht auf /usr/bin/node zeigt.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. Die globale Installation erfolgt in ein root-eigenes Präfix. Verwenden Sie dafür nicht sudo. Setzen Sie npm config set prefix ~/.npm-global, nehmen Sie ~/.npm-global/bin in PATH auf und installieren Sie anschließend als normaler Benutzer neu. Wenn ein früheres sudo npm root-eigene Cache-Dateien hinterlassen hat (Your cache folder contains root-owned files), führen Sie sudo chown -R $(id -u):$(id -g) ~/.npm aus.

Failed to open browser oder ein redirect_uri, das auf http://127.0.0.1:PORT zeigt, das Sie nicht erreichen können. Die CLI hat eine Display-Variable gefunden, häufig aus ssh -X, und den Loopback-Ablauf verwendet. Dessen Callback landet auf dem Server. Führen Sie NO_BROWSER=true gemini aus, um den Ablauf zum Einfügen eines Codes zu verwenden, oder verwenden Sie den API-Key-Ablauf (GEMINI_API_KEY). In einer einfachen SSH-Sitzung sollte stattdessen Enter the authorization code: angezeigt werden. Öffnen Sie die URL im Browser Ihres Laptops, bestätigen Sie sie und fügen Sie den von Google angezeigten Code ein.

Der Prozess verschwand, als die SSH-Verbindung getrennt wurde. Sie haben gemini direkt aus der SSH-Shell gestartet. Dadurch war der Prozess ein Kindprozess dieser Shell und wurde beim Trennen zusammen mit dem pty beendet. Es gibt nichts wiederherzustellen. Starten Sie jede Sitzung mit tmux new -A -s gemini und führen Sie die CLI darin aus.

Die Authentifizierung schlägt trotz gesetztem Schlüssel weiterhin fehl, die CLI wechselt zurück zur Authentifizierungsauswahl oder eine Anfrage liefert API key not valid mit HTTP 400. Der Schlüssel befindet sich nicht in der Umgebung, die die CLI sieht. Prüfen Sie dies mit printenv GEMINI_API_KEY. Wenn die Ausgabe leer ist, wurde Ihre ~/.gemini_env nie eingelesen. Prüfen Sie, ob die Zeile in ~/.bashrc steht. Interaktive Shells, einschließlich tmux, lesen diese Datei ein, cron und andere nicht interaktive Shells jedoch nicht. Ein überflüssiges Leerzeichen oder Anführungszeichen im Schlüsselwert erzeugt ebenfalls API key not valid.

429 / RESOURCE_EXHAUSTED / eine Meldung zur Ratenbegrenzung. Sie haben das Kontingent der Authentifizierungsstufe erreicht, die Ihre Authentifizierung verwendet. Warten Sie, bis das Zeitfenster zurückgesetzt wird, verlangsamen Sie den Agenten oder wechseln Sie zu einem abgerechneten API-Key. Ein Agent, der in einer Wiederholungsschleife festhängt, löst diesen Fehler weiterhin aus. Stoppen Sie ihn und prüfen Sie, was er tut.

FAQ

Wie authentifiziere ich Gemini CLI auf einem Server ohne grafische Oberfläche?

Verwenden Sie einen kostenpflichtigen API-Schlüssel, nicht die Browseranmeldung. Erstellen Sie den Schlüssel in Google AI Studio in einem abgerechneten Projekt, speichern Sie ihn in einer Datei mit den Berechtigungen 600, die Ihre Shell einliest (export GEMINI_API_KEY=...), und die CLI überspringt den OAuth-Browserablauf vollständig. Wenn Sie sich stattdessen mit Google anmelden, beispielsweise mit einer Code Assist Standard- oder Enterprise-Lizenz, gibt die CLI auf einem Server ohne grafische Oberfläche eine URL aus. Öffnen Sie diese auf Ihrem Laptop, bestätigen Sie die Anmeldung und fügen Sie den von Google angezeigten Code an der Enter the authorization code:-Eingabeaufforderung ein. Dafür muss kein Port reserviert und kein Tunnel eingerichtet werden. Sie müssen jedoch an einem Browser anwesend sein, daher eignet sich dieses Verfahren nicht für Skripte. Kostenlose persönliche Konten werden von Gemini CLI seit June 18, 2026 nicht mehr unterstützt.

Warum verlangt die globale npm-Installation sudo, und wie kann ich das vermeiden?

Der Standardpräfix für globale npm-Pakete ist /usr/lib/node_modules. Ihr Benutzer kann dort nicht schreiben, daher schlägt ein einfaches npm install -g mit EACCES fehl. Die falsche Lösung ist sudo npm -g. Dadurch bleiben Dateien im Besitz von root zurück, die spätere Installationen behindern. Die richtige Lösung besteht darin, den Präfix auf Ihr Home-Verzeichnis (npm config set prefix ~/.npm-global) zu setzen und dessen bin zu PATH hinzuzufügen. Alternativ können Sie nvm verwenden. nvm installiert globale Pakete automatisch in Ihrem Home-Verzeichnis.

Wie lasse ich Gemini CLI nach dem Trennen der Verbindung weiterlaufen?

Führen Sie es innerhalb von tmux aus. Ein Prozess, der aus Ihrer SSH-Shell gestartet wird, endet, wenn die Verbindung abbricht, weil er ein Kindprozess dieser Shell ist. tmux führt die Shell unter einem getrennten Server aus, der die Verbindung überlebt. Verwenden Sie tmux new -A -s gemini, führen Sie darin gemini aus, trennen Sie die Sitzung mit Ctrl-b d und stellen Sie später mit tmux attach -t gemini wieder eine Verbindung her.

Ist es sicher, Gemini CLI auf einem Produktionsserver auszuführen?

Nur mit Vorsicht. Ein Agent mit Shell-Zugriff kann alles ausführen, was der Benutzer ausführen darf, unter dessen Konto er läuft. Führen Sie ihn als dedizierten Benutzer ohne erhöhte Rechte und ohne sudo aus. Halten Sie Produktionsanmeldedaten vom Rechner fern, vermeiden Sie --yolo zur automatischen Bestätigung und verwenden Sie --sandbox (Docker oder Podman), um Tool-Aufrufe vom Host zu isolieren. Das Konto, unter dem der Agent läuft, ist wichtiger als jedes einzelne gesetzte Flag.

Muss ich für Gemini CLI Firewall-Ports öffnen?

Nein. Gemini CLI ist ein Client, der ausgehende HTTPS-Anfragen an die APIs von Google stellt. Es benötigt daher ausgehend Port 443, aber keine eingehenden Ports. Auch die Google-Anmeldung auf einem Server ohne grafische Oberfläche benötigt keinen Port. Sie fügen den Code stattdessen im Terminal ein, anstatt einen Callback auf dem Server zu empfangen. Lassen Sie eingehende Verbindungen weiterhin gesperrt.