Cara Jalankan Gemini CLI di Headless VPS

Apa yang anda bina

Satu CLI Gemini yang sentiasa aktif pada pelayan milik anda, boleh dicapai melalui SSH, dan menjalankan tugas ejen jangka panjang yang terus berfungsi selepas anda menutup komputer riba. Pemasangan ini hanya memerlukan tiga arahan. Bahagian yang memerlukan usaha ialah segala perkara yang mengandaikan persekitaran desktop: CLI Google ingin membuka pelayar untuk log masuk anda, sedangkan pelayan anda tidak mempunyainya. Oleh itu, kebanyakan panduan ini adalah mengenai laluan tanpa kepala (headless), Node versi terkini yang tidak disediakan oleh distro anda, pemasangan npm global yang tidak memerlukan root, pengesahan tanpa pelayar dengan kunci API yang anda simpan di luar sejarah shell anda, dan tmux supaya sesi SSH yang terputus tidak menamatkan tugas yang sedang berjalan.

Gemini CLI ialah program Node sumber terbuka (Apache-2.0) (@google/gemini-cli) yang berhubung dengan model Gemini Google dan boleh membaca serta menulis fail, menjalankan arahan shell, dan mengendalikan alatan dalam direktori kerja. Pada VPS, ia merupakan ejen kecil yang sentiasa tersedia yang boleh anda biarkan berfungsi, itulah sebabnya akaun yang menjalankannya, serta kelayakan yang disimpan pada mesin tersebut, lebih penting daripada mana-mana tetapan tunggal di sini.

Prasyarat dan perkara penting yang perlu diketahui

• VPS KVM Ubuntu 24.04 baharu dengan akses root atau sudo. Mana-mana pelan KVM boleh digunakan; CLI ini ringan dan hanya memerlukan beberapa ratus MB RAM semasa melahu.
• Node.js 20 atau lebih baharu. Ini adalah versi minimum yang wajib, dan pakej dalam distro adalah lebih rendah daripada versi ini, sila lihat bahagian seterusnya.
• HTTPS keluar (port 443) ke API Google. Tiada port masuk diperlukan; ini adalah klien, bukan pelayan, jadi anda tidak perlu membuka sebarang lubang firewall untuknya.
• Cara pengesahan yang tidak memerlukan pelayar web pada pelayan: sama ada kunci API Gemini daripada Google AI Studio, atau terowong SSH kembali ke pelayar pada mesin anda sendiri. Laluan kunci API adalah cara yang lebih sesuai untuk skrip dan tugasan yang berjalan tanpa pengawasan.
• Docker atau Podman, hanya jika anda mahukan pengasingan --sandbox. Pilihan, dibincangkan pada bahagian akhir.

Perkara penting yang sering terlepas pandang: aliran log masuk kali pertama gemini yang mesra pengguna dibina untuk desktop. Ia cuba membuka pelayar web dan pada mesin tanpa kepala (headless), ia sama ada gagal atau memberikan pautan yang tidak berfungsi. Tentukan laluan pengesahan sebelum anda bermula.

Nota: pakej distro terlalu lama

Ubuntu 24.04 membekalkan Node 18.19.1 dalam repositorinya sendiri, digandingkan dengan npm 9.2.0. package.json bagi Gemini CLI mengisytiharkan engines: { node: ">=20" }, dan npm tidak menghentikan ketidakpadanan secara lalai; ia tetap memasang dan mencetak amaran yang menyatakan jurang tersebut:

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 }

Abaikan amaran tersebut dan CLI akan berjalan pada runtime yang tidak disokong, di mana ia akan berkelakuan tidak wajar atau terhenti serta-merta apabila mencapai API Node 20+ yang dijangkakan. Node 18 juga telah mencapai penghujung hayat pada April 2025, jadi ia merupakan jalan buntu dalam apa jua keadaan. Pasang LTS semasa sebelum anda memasang CLI. Dua laluan bersih ialah NodeSource (repositori apt bertandatangan seluruh sistem) atau nvm (pengurus versi bagi setiap pengguna). Pilih salah satu.

NodeSource, jika anda mahu Node tersedia kepada setiap pengguna pada mesin tersebut:

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 mesti mencetak v20.x atau lebih tinggi, v24.x ialah LTS aktif semasa. Semak halaman NodeSource untuk skrip penyediaan semasa; setup_24.x dalam URL ialah baris yang perlu dikemas kini apabila LTS yang lebih baharu dilancarkan.

nvm, jika anda lebih suka menyimpan Node di dalam direktori home pengguna dan tidak menyentuhnya dengan sudo:

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 dalam URL tersebut adalah versi semasa apabila dokumen ini ditulis; semak README nvm untuk keluaran terkini dan tukar versi tersebut sebelum anda menjalankannya. nvm mempunyai kelebihan sebenar untuk tugas ini: ia memasang Node dan pakej globalnya di bawah ~/.nvm, jadi masalah kebenaran pemasangan global dalam bahagian seterusnya tidak akan berlaku. Jika anda memilih laluan nvm, anda boleh melangkau langkah npm-prefix.

Install the CLI without sudo npm -g

The tempting command is sudo npm install -g @google/gemini-cli. Do not. A root-owned global prefix produces permission errors on every later install and leaves root-owned files in your npm cache that bite months from now. Run a plain (no-sudo) npm install -g against a system Node and you get the other failure:

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'

That is npm trying to write into /usr/lib, which your user cannot. The fix is not sudo, it is to point npm's global prefix at your home directory so global installs land somewhere you own:

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, not ~/.profile, is deliberate: tmux, which you will run the CLI inside two sections from now, starts a non-login shell that reads ~/.bashrc and skips ~/.profile, so a PATH line in the wrong file leaves gemini invisible in exactly the place you need it. gemini --version printing a version number is the whole test. If you instead get gemini: command not found, your PATH export did not take, see the failure modes. On nvm, skip the prefix lines entirely: it already installs globals under your home.

If you ran sudo npm at some earlier point and now see Your cache folder contains root-owned files, repair it once with sudo chown -R $(id -u):$(id -g) ~/.npm.

Masalah pengesahan tanpa kepala (headless), dan cara mengatasinya

Jalankan gemini secara interaktif pada kali pertama dan ia akan menawarkan untuk melog masuk anda menggunakan akaun Google anda. Pada desktop, tindakan ini membuka tab pelayar. Pada VPS tanpa kepala (headless), tiada pelayar tersedia, jadi aliran tersebut sama ada mencetak URL localhost yang dijangka untuk anda buka, atau gagal terus dengan mesej seperti:

Failed to open browser. Please visit the following URL to authorize:
https://accounts.google.com/o/oauth2/v2/auth?...&redirect_uri=http://localhost:PORT

Perangkapnya ialah redirect_uri=http://localhost:PORT. Walaupun anda membuka URL tersebut pada komputer riba anda dan meluluskannya, Google akan mengubah hala ke http://localhost:PORT, iaitu localhost pada pelayan, satu port yang tidak boleh dicapai oleh komputer riba anda. Proses log masuk tidak akan selesai.

Terdapat dua cara yang sah untuk melaluinya.

Cara pertama ialah menggunakan API key, dan ini merupakan tetapan lalai yang betul untuk pelayan. Cipta kunci dalam Google AI Studio (aistudio.google.com) dan berikannya kepada CLI sebagai pemboleh ubah persekitaran (environment variable); ia membaca GEMINI_API_KEY dan melangkau aliran pelayar sepenuhnya. Sekarang, bahagian "jauhkan daripada sejarah dan fail yang boleh dibaca oleh semua orang". Jangan taip export GEMINI_API_KEY=AIza... pada prompt, kerana ia akan tersimpan dalam ~/.bash_history dalam bentuk teks jelas, dan jangan letakkannya dalam fail yang boleh dibaca oleh orang lain. Tulis kunci tersebut ke dalam fail dengan mod 600 yang dimuatkan oleh shell semasa permulaan:

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 bermaksud hanya pengguna anda yang boleh membaca fail tersebut. Sahkan kunci telah sampai ke persekitaran dengan printenv GEMINI_API_KEY; jika ia tidak mencetak apa-apa, CLI akan kembali kepada aliran pelayar dan gagal. Ia juga membaca fail .env dalam ~/.gemini/ jika anda lebih suka susun atur tersebut, dengan peraturan yang sama, jadi chmod 600 ~/.gemini/.env.

Cara kedua mengekalkan log masuk akaun Google peribadi (dan pelan percuma) dengan melakukan tunneling pada callback OAuth kembali ke komputer riba anda. Masalahnya ialah pelayan loopback CLI mengikat port rawak setiap kali dijalankan, jadi tiada port stabil untuk diforward kecuali anda menetapkannya terlebih dahulu dengan pemboleh ubah persekitaran OAUTH_CALLBACK_PORT, kemudian forward port tersebut dengan tepat:

# from your laptop, forward the callback port into the SSH session:
ssh -L 8085:localhost:8085 user@your-server
# then, on the server, pin the callback to the same port and start the CLI:
export OAUTH_CALLBACK_PORT=8085
gemini

CLI tidak dapat membuka pelayar, jadi ia akan mencetak URL pengesahan; buka URL tersebut dalam pelayar komputer riba anda, luluskan, dan apabila Google mengubah hala ke http://localhost:8085/..., SSH forward akan membawanya ke pelayan loopback pada VPS dan log masuk akan selesai. Jika anda membiarkan port tidak ditetapkan, ia akan mendarat pada port rawak baharu setiap kali dijalankan, yang tidak dapat ditangkap oleh mana-mana ssh -L yang disediakan lebih awal. Ia berfungsi, tetapi ia memerlukan anda berada di hadapan pelayar, jadi ia tidak sesuai untuk skrip. Untuk apa-apa yang anda biarkan berjalan, gunakan API key.

Untuk Vertex AI atau projek Google Cloud dan bukannya AI Studio, tetapkan GOOGLE_API_KEY bersama-sama dengan GOOGLE_GENAI_USE_VERTEXAI=true, atau GOOGLE_CLOUD_PROJECT untuk lesen Code Assist, dengan disiplin pemboleh ubah persekitaran yang sama, dan fail mod 600 yang sama.

Jalankan di dalam tmux supaya sesi SSH yang terputus tidak mematikannya

Proses gemini yang anda lancarkan terus daripada shell SSH adalah anak (child) kepada shell tersebut. Jika sambungan terputus, komputer riba ditutup, Wi-Fi tergendala, atau tamat tempoh melahu, sshd akan meruntuhkan pseudo-terminal, shell akan menerima SIGHUP, dan ia akan menutup CLI secara automatik. Tugas yang sedang berjalan selama sepuluh minit untuk menyunting fail akan mati bersamanya, dan apabila anda menyambung semula, tiada proses yang boleh dipulihkan.

tmux menyelesaikan masalah ini dengan memiliki shell tersebut dan bukannya sshd yang memilikinya. Ini adalah corak yang sama seperti menjalankan ejen pengekodan AI pada VPS jauh di dalam tmux, dan ia berfungsi secara identik di sini:

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 akan melampirkan diri pada sesi bernama gemini jika ia wujud dan menciptanya jika tidak, jadi ini adalah satu-satunya arahan yang perlu dijalankan sejurus selepas setiap log masuk. Shell di dalamnya dimiliki oleh pelayan tmux yang terpisah (detached), bukan sesi SSH anda, jadi memutuskan sambungan tidak akan menghentikan CLI yang sedang berjalan. Sambung semula, lampirkan (attach), dan anda kembali ke skrol belakang yang sama. Jika anda akhirnya menjalankan beberapa sesi ejen pada satu mesin, satu bagi setiap sesi tmux, ia tidak mempunyai cara untuk berkomunikasi antara satu sama lain di sini, tidak seperti Claude Code, di mana satu sesi boleh menghantar teks kepada sesi lain pada VPS yang sama, jadi pastikan setiap tugasan Gemini bebas atau selaraskannya melalui fail pada cakera.

Untuk pelaksanaan skrip yang tidak interaktif, Gemini CLI mempunyai mod tanpa kepala (headless mode): gemini -p "summarise the failing tests in this repo" mencetak jawapan dan keluar, manakala --output-format json memberikan output yang boleh dibaca oleh mesin untuk disalurkan (pipe) ke tempat lain. Mod tanpa kepala dengan API key adalah perkara yang anda perlukan di dalam sesi tmux yang menjalankan tugasan kelompok (batch job) yang panjang, atau dicetuskan daripada entri cron, dengan satu peringatan: tugasan cron tidak memuatkan mana-mana fail log masuk anda, jadi berikan baris crontab itu GEMINI_API_KEY sendiri (atau minta arahan tersebut memuatkan ~/.gemini_env), jika tidak, CLI akan kembali kepada aliran pelayar dan gagal.

Sandboxing dan keizinan pada pelayan yang menjalankan persekitaran pengeluaran

Ejen dengan akses shell adalah shell itu sendiri. Gemini CLI boleh menjalankan arahan, dan secara lalai ia akan meminta pengesahan sebelum setiap arahan yang berisiko, namun pengguna sering menggunakan --yolo (meluluskan setiap panggilan alat secara automatik). Apabila ini berlaku, ia boleh memadam fail, melakukan push ke git, atau mengakses servis dalaman dengan kuasa penuh pengguna yang menjalankannya. Pada pelayan yang turut menjalankan persekitaran pengeluaran, ini merupakan risiko sebenar, bukan sekadar teori.

Tiga kawalan, mengikut tahap keberkesanan:

• Jalankan sebagai pengguna khusus yang tidak mempunyai keistimewaan. Bukan root, dan bukan ahli sudo. Cipta pengguna agent dengan direktori home sendiri, pasang Node dan CLI di situ. Dengan cara ini, arahan yang disalah tafsir akan terhad kepada akaun tersebut sahaja. Ini adalah keputusan paling berharga yang boleh anda buat.
• Jangan simpan kelayakan pengeluaran (production credentials) pada pelayan tersebut. Tiada ~/.aws/credentials pengeluaran, tiada .env yang disalin dari persekitaran pengeluaran, dan tiada kata laluan pangkalan data dengan akses tulis kepada apa-apa yang penting. Berikan kelayakan staging atau akses baca sahaja.
• Gunakan sandbox terbina dalam. Dengan Docker atau Podman dipasang, gemini --sandbox (atau GEMINI_SANDBOX=docker) menjalankan panggilan alat ejen di dalam kontena yang terasing daripada sistem fail dan rangkaian hos. Ia bukan pengganti kepada pengguna tanpa keistimewaan, tetapi ia merupakan lapisan kedua yang kukuh apabila VPS yang sama melakukan kerja sebenar.

Jika anda menjalankan Gemini CLI bersama alatan self-hosted yang lain, contohnya pelayan MCP yang mendedahkan alatan kepada ejen pada VPS yang sama, anggap setiap keupayaan tambahan sebagai permukaan serangan yang boleh dicapai oleh ejen, dan hadkan token yang diberikan kepadanya kepada satu tugasan sahaja.

Kuota, kos, dan laluan pengesahan yang anda pilih

Laluan pengesahan menentukan cara anda dibilkan. Akaun Google peribadi (laluan OAuth) menggunakan tier Gemini Code Assist percuma, dengan had sebenar setiap minit dan setiap hari; jika had tersebut dilampaui, permintaan akan memulangkan ralat kadar had (rate-limit error) sehingga tempoh masa ditetapkan semula. Kunci API daripada AI Studio boleh menjadi tier percuma atau dibilkan bergantung pada projek; kunci yang dibilkan meningkatkan had dan mengenakan caj setiap token. Pengesahan Vertex dan projek Cloud dibilkan melalui Google Cloud.

Dua nota praktikal. Ejen tanpa pengawasan dalam gelung boleh menghabiskan kuota dengan cepat, jadi pantau ia beberapa kali pertama sebelum anda mempercayainya untuk tugasan cron job. Dan jika sebab anda menggunakan model sebelah pelayan (server-side) adalah untuk privasi atau inferens tanpa meter dan bukannya model hos Google, itu adalah alat yang berbeza; mengehos sendiri LLM terbuka dengan Ollama pada VPS menyimpan pemberat (weights) dan prompt pada mesin anda sendiri, dengan kos menjalankan model yang jauh lebih kecil daripada Gemini.

Memastikan ia sentiasa dikemas kini

Gemini CLI kerap mengeluarkan versi baharu. Oleh sebab anda memasangnya ke dalam prefiks milik pengguna, kemas kini tidak memerlukan sudo:

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

Terdapat saluran keluaran: @latest ialah versi stabil, @preview ialah pratonton mingguan, @nightly ialah versi terkini yang masih dalam pembangunan, jadi tetapkan pada @latest untuk sebarang perkara yang anda harapkan. Pada nvm, pakej global berada di bawah versi Node yang aktif, jadi selepas nvm use untuk menukar Node, anda mungkin perlu memasang semula CLI tersebut. Baca nota keluaran daripada mengejar setiap tampalan.

Mod kegagalan, berserta rentetan tepat

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, kemudian CLI terhenti semasa runtime. Versi Node terlalu lama, distro menggunakan 18.19.1, yang juga telah melepasi tarikh akhir hayat (end-of-life). Pasang Node 20+ daripada NodeSource atau nvm, sahkan dengan node --version, dan jika anda mempunyai beberapa versi Node yang dipasang, pastikan which node menghala ke versi baharu dan bukan /usr/bin/node.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. Pemasangan global ke dalam prefiks milik root. Jangan gunakan sudo, tetapkan npm config set prefix ~/.npm-global, letakkan ~/.npm-global/bin pada PATH, dan pasang semula sebagai pengguna biasa anda. Jika sudo npm sebelum ini meninggalkan fail cache milik root (Your cache folder contains root-owned files), jalankan sudo chown -R $(id -u):$(id -g) ~/.npm.

Failed to open browser, log masuk yang tergantung, atau redirect_uri=http://localhost:PORT yang tidak boleh dicapai. Aliran OAuth memerlukan pelayar yang tidak dimiliki oleh pelayan, dan callback localhost menghala ke pelayan, bukan komputer riba anda. Gunakan laluan API-key (GEMINI_API_KEY), atau pin OAUTH_CALLBACK_PORT, majukan (forward) melalui SSH dengan ssh -L, dan buka URL tersebut secara tempatan.

Proses hilang apabila SSH terputus. Anda menjalankan gemini terus daripada shell SSH, jadi ia merupakan anak (child) kepada shell tersebut dan mati bersama pty apabila sambungan terputus. Tiada apa yang boleh dipulihkan. Mulakan setiap sesi dengan tmux new -A -s gemini dan jalankan CLI di dalamnya.

Pengesahan masih gagal walaupun kunci telah ditetapkan, CLI kembali ke pemilih pengesahan, atau permintaan mengembalikan API key not valid dengan HTTP 400. Kunci tersebut tidak berada dalam persekitaran yang dilihat oleh CLI. Sahkan dengan printenv GEMINI_API_KEY; jika ia kosong, ~/.gemini_env anda tidak pernah dimuatkan (sourced), semak sama ada baris tersebut ada dalam ~/.bashrc, yang dibaca oleh shell interaktif (termasuk tmux) tetapi tidak dibaca oleh cron dan shell bukan interaktif yang lain. Ruang kosong atau tanda petikan yang tersilap di dalam nilai kunci juga akan menghasilkan API key not valid.

429 / RESOURCE_EXHAUSTED / mesej had kadar (rate-limit). Anda telah mencapai kuota untuk tier yang digunakan oleh pengesahan anda. Tunggu sehingga tetingkap masa ditetapkan semula, perlahankan ejen, atau beralih kepada kunci API berbayar. Ejen yang tersangkut dalam gelung cuba semula akan terus mencapai had ini, hentikan ejen tersebut dan periksa apa yang sedang dilakukannya.

FAQ

Bagaimanakah cara saya mengesahkan Gemini CLI pada pelayan tanpa kepala (headless)?

Gunakan API key, bukan log masuk pelayar. Cipta kunci dalam Google AI Studio, letakkannya dalam fail dengan mod 600 yang dibaca oleh shell anda (export GEMINI_API_KEY=...), dan CLI akan melangkau aliran OAuth pelayar sepenuhnya. Jika anda secara khusus mahukan pelan percuma akaun peribadi, tetapkan port loopback dengan OAUTH_CALLBACK_PORT=8085, majukan (forward) ia kembali ke komputer riba anda dengan ssh -L 8085:localhost:8085 user@server, dan buka URL yang dipaparkan secara setempat. Walau bagaimanapun, kaedah ini memerlukan anda berada di hadapan pelayar, jadi ia tidak sesuai untuk skrip.

Mengapakah pemasangan global npm memerlukan sudo, dan bagaimanakah cara untuk mengelakkannya?

Ini kerana awalan (prefix) global lalai npm ialah /usr/lib/node_modules, yang tidak boleh ditulis oleh pengguna anda, jadi arahan npm install -g biasa akan gagal dengan EACCES. Penyelesaian yang salah ialah sudo npm -g, yang akan meninggalkan fail milik root dan merosakkan pemasangan pada masa hadapan. Penyelesaian yang betul ialah menghalakan awalan tersebut ke direktori home anda (npm config set prefix ~/.npm-global) dan menambah bin miliknya ke dalam PATH, atau gunakan nvm, yang memasang pakej global di bawah direktori home anda secara automatik.

Bagaimanakah cara untuk memastikan Gemini CLI terus berjalan selepas saya terputus sambungan?

Jalankannya di dalam tmux. Proses yang dimulakan daripada shell SSH anda akan mati apabila sambungan terputus kerana ia merupakan anak (child) kepada shell tersebut; tmux menjalankan shell di bawah pelayan terasing yang kekal aktif walaupun selepas terputus sambungan. Gunakan tmux new -A -s gemini, jalankan gemini di dalamnya, pisahkan (detach) dengan Ctrl-b d, dan sambung semula (reattach) kemudian dengan tmux attach -t gemini.

Adakah selamat untuk menjalankan Gemini CLI pada mesin pengeluaran (production)?

Hanya jika dilakukan dengan berhati-hati, kerana ejen yang mempunyai akses shell boleh melakukan apa sahaja yang boleh dilakukan oleh pengguna yang menjalankannya. Jalankannya sebagai pengguna khusus yang tidak mempunyai keistimewaan (unprivileged) tanpa sudo, jangan simpan kelayakan pengeluaran pada mesin tersebut, elakkan kelulusan automatik --yolo, dan gunakan --sandbox (Docker atau Podman) untuk mengasingkan panggilan alat daripada hos. Akaun yang digunakan untuk menjalankannya adalah lebih penting daripada mana-mana flag tunggal yang anda tetapkan.

Adakah saya perlu membuka sebarang port firewall untuk Gemini CLI?

Tidak. Ia adalah klien yang membuat panggilan HTTPS keluar ke API Google, jadi ia memerlukan port keluar 443 tetapi tiada port masuk. Jika anda menggunakan terowong OAuth, port panggil balik yang ditetapkan (contohnya 8085) berada pada localhost dan dicapai melalui forward SSH anda, bukan port masuk yang terbuka. Pastikan port masuk kekal dikunci.