วิธีติดตั้ง Gemini CLI บน headless VPS

สิ่งที่คุณกำลังสร้าง

คุณกำลังสร้าง Gemini CLI แบบ always-on บน server ของคุณเอง ซึ่งสามารถเข้าถึงผ่าน SSH ได้ โดยโปรแกรมจะทำงานในรูปแบบ agent ที่ทำงานต่อเนื่องแม้คุณจะปิด laptop ไปแล้ว การติดตั้งใช้เพียง 3 commands เท่านั้น ส่วนที่ต้องใช้ความพยายามคือการจัดการส่วนที่ต้องใช้ desktop เนื่องจาก Google's CLI ต้องการเปิด browser เพื่อให้คุณ log in แต่ server ของคุณไม่มี browser ดังนั้นเนื้อหาหลักในคู่มือนี้จึงเป็นแนวทางแบบ headless ซึ่งประกอบด้วยการใช้ Node เวอร์ชันปัจจุบันที่ distro ทั่วไปไม่มีให้, การใช้ npm install แบบ global โดยไม่ต้องใช้ root, การทำ browserless auth ด้วย API key เพื่อไม่ให้ข้อมูลหลุดไปใน shell history และการใช้ tmux เพื่อป้องกันไม่ให้ task ที่กำลังทำงานอยู่หยุดลงเมื่อการเชื่อมต่อ SSH หลุดไป

Gemini CLI เป็นโปรแกรม Node (@google/gemini-cli) แบบ open-source (Apache-2.0) ที่สื่อสารกับ Google's Gemini models โดยสามารถอ่านและเขียนไฟล์, รัน shell commands และควบคุมเครื่องมือต่างๆ ใน working directory ได้ เมื่อติดตั้งบน VPS โปรแกรมนี้จะเป็น agent ขนาดเล็กที่พร้อมทำงานตลอดเวลา ดังนั้น user account ที่ใช้รันโปรแกรมและ credentials ที่เก็บไว้ในเครื่องจึงมีความสำคัญมากกว่าการตั้งค่าอื่นๆ ในคู่มือนี้

สิ่งที่ต้องเตรียมและข้อควรระวัง

• Ubuntu 24.04 KVM VPS ที่ติดตั้งใหม่และมีสิทธิ์ root หรือ sudo แผนบริการ KVM ใดก็ได้สามารถใช้งานได้ เนื่องจาก CLI ใช้ทรัพยากรน้อยมาก โดยใช้ RAM เพียงไม่กี่ร้อย MB ขณะไม่ได้ทำงาน
• Node.js เวอร์ชัน 20 หรือใหม่กว่า เนื่องจากเวอร์ชันใน package ของ distro นั้นต่ำกว่าเกณฑ์ที่กำหนด โปรดดูรายละเอียดในส่วนถัดไป
• การเชื่อมต่อ HTTPS (port 443) ขาออกไปยัง Google APIs ไม่จำเป็นต้องเปิด port ขาเข้า เนื่องจากระบบนี้ทำหน้าที่เป็น client ไม่ใช่ server จึงไม่ต้องเปิด firewall
• วิธีการยืนยันตัวตนที่ไม่ต้องใช้ browser บน server: สามารถใช้ Gemini API key จาก Google AI Studio หรือใช้ SSH tunnel กลับไปยัง browser บนเครื่องของคุณ การใช้ API-key เหมาะสำหรับการใช้งานผ่าน script และการทำงานแบบอัตโนมัติ
• Docker หรือ Podman หากต้องการใช้งาน --sandbox isolation (เป็นทางเลือกเสริม ซึ่งจะกล่าวถึงในช่วงท้าย)

ข้อควรระวังที่ผู้ใช้ทุกคนมักพบ: ขั้นตอนการ login ครั้งแรกของ gemini ถูกออกแบบมาสำหรับ desktop ระบบจะพยายามเปิด browser ซึ่งหากใช้งานบน headless box จะทำให้เกิดข้อผิดพลาดหรือได้รับ link ที่ใช้งานไม่ได้ โปรดเลือกวิธีการยืนยันตัวตนให้เรียบร้อยก่อนเริ่มดำเนินการ

Node: distro package มีเวอร์ชันเก่าเกินไป

Ubuntu 24.04 มาพร้อมกับ Node 18.19.1 ใน repository ของระบบ และใช้ npm 9.2.0 โดยที่ package.json ของ Gemini CLI ระบุว่าต้องใช้ 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 จะทำงานบน runtime ที่ไม่รองรับ ซึ่งจะทำให้เกิดข้อผิดพลาดหรือโปรแกรมหยุดทำงานทันทีเมื่อมีการเรียกใช้ Node 20+ API ที่ระบบต้องการ นอกจากนี้ Node 18 ได้สิ้นสุดระยะเวลาสนับสนุน (end-of-life) ไปแล้วเมื่อเดือนเมษายน 2025 ดังนั้นจึงไม่สามารถใช้งานในระยะยาวได้ ควรติดตั้ง Node เวอร์ชัน LTS ปัจจุบัน ก่อน การติดตั้ง CLI โดยมี 2 วิธีที่แนะนำ คือ NodeSource (apt repo แบบ signed สำหรับทั้งระบบ) หรือ nvm (เครื่องมือจัดการเวอร์ชันสำหรับผู้ใช้แต่ละคน) โปรดเลือกวิธีใดวิธีหนึ่ง

NodeSource หากต้องการให้ Node ใช้งานได้สำหรับผู้ใช้ทุกคนในระบบ:

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 จะต้องเป็นเวอร์ชัน v20.x หรือสูงกว่า โดย v24.x คือเวอร์ชัน LTS ปัจจุบัน โปรดตรวจสอบหน้าเว็บของ NodeSource เพื่อดู script การติดตั้งล่าสุด โดยต้องเปลี่ยนเลข setup_24.x ใน URL เมื่อมี LTS เวอร์ชันใหม่เปิดตัว

nvm หากต้องการเก็บ Node ไว้ใน home directory ของผู้ใช้คนเดียวและไม่ต้องการใช้ 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 ใน URL คือเวอร์ชันล่าสุดขณะที่เขียนบทความนี้ โปรดตรวจสอบ README ของ nvm เพื่อดูเวอร์ชันล่าสุดและเปลี่ยนเลขเวอร์ชันก่อนเริ่มรันคำสั่ง nvm มีข้อดีสำหรับงานนี้คือ จะติดตั้ง Node และ global packages ไว้ภายใต้ ~/.nvm ทำให้ไม่เกิดปัญหาเรื่อง permission ในการติดตั้งแบบ global ในหัวข้อถัดไป หากเลือกใช้ nvm คุณสามารถข้ามขั้นตอนการตั้งค่า npm-prefix ได้

การติดตั้ง CLI โดยไม่ใช้ sudo npm -g

คำสั่งที่ดูเหมือนจะใช้ได้คือ sudo npm install -g @google/gemini-cli แต่ห้ามใช้ เนื่องจาก global prefix ที่เป็นของ root จะทำให้เกิดข้อผิดพลาดด้าน permission ในการติดตั้งครั้งต่อๆ ไป และจะทิ้งไฟล์ที่เป็นของ root ไว้ใน npm cache ซึ่งจะสร้างปัญหาในอีกไม่กี่เดือนข้างหน้า หากรัน npm install -g แบบปกติ (ไม่ใช้ sudo) กับ system Node คุณจะพบข้อผิดพลาดอีกรูปแบบหนึ่ง:

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 ซึ่ง user ของคุณไม่มีสิทธิ์ วิธีแก้ไขไม่ใช่การใช้ sudo แต่คือการกำหนดให้ npm global prefix ชี้ไปยัง home directory ของคุณ เพื่อให้การติดตั้งแบบ global ไปอยู่ในตำแหน่งที่คุณเป็นเจ้าของ:

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 แทนที่จะเป็น ~/.profile เป็นความตั้งใจ: tmux ซึ่งคุณจะต้องใช้รัน CLI ในอีกสองส่วนถัดไป จะเริ่มทำงานแบบ non-login shell ที่อ่านไฟล์ ~/.bashrc และข้ามไฟล์ ~/.profile ดังนั้นหากมีบรรทัด PATH อยู่ในไฟล์ที่ผิด จะทำให้ gemini ไม่ปรากฏในตำแหน่งที่จำเป็น การใช้ gemini --version เพื่อพิมพ์เลขเวอร์ชันคือการทดสอบที่สำคัญ หากคุณได้รับผลลัพธ์เป็น gemini: command not found แสดงว่าการ export PATH ไม่สำเร็จ ให้ตรวจสอบรูปแบบข้อผิดพลาด (failure modes) หากคุณใช้ nvm ให้ข้ามบรรทัดการตั้งค่า prefix ทั้งหมด เนื่องจาก nvm ติดตั้ง globals ไว้ใน home ของคุณอยู่แล้ว

หากคุณเคยรัน sudo npm มาก่อนหน้านี้และพบ Your cache folder contains root-owned files ให้แก้ไขด้วยคำสั่ง sudo chown -R $(id -u):$(id -g) ~/.npm เพียงครั้งเดียว

ปัญหาการยืนยันตัวตนแบบ headless และวิธีการแก้ไข

เมื่อรัน gemini แบบ interactive ในครั้งแรก ระบบจะเสนอให้คุณเข้าสู่ระบบด้วยบัญชี Google หากเป็นเครื่อง desktop ระบบจะเปิดแท็บเบราว์เซอร์ขึ้นมา แต่สำหรับ VPS แบบ headless ที่ไม่มีเบราว์เซอร์ ระบบจะแสดง URL ของ localhost เพื่อให้คุณเปิดเอง หรือไม่ก็เกิดข้อผิดพลาดทันที เช่น:

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

ปัญหาเกิดจาก redirect_uri=http://localhost:PORT แม้ว่าคุณจะเปิด URL นั้นบน laptop และกดยืนยันแล้ว แต่ Google จะ redirect ไปยัง http://localhost:PORT ซึ่งเป็น localhost บนเซิร์ฟเวอร์ และเป็นพอร์ตที่ laptop ไม่สามารถเข้าถึงได้ ทำให้การเข้าสู่ระบบไม่สำเร็จ

มี 2 วิธีในการแก้ไขปัญหาอย่างถูกต้อง

วิธีแรกคือการใช้ API key ซึ่งเป็นวิธีมาตรฐานที่เหมาะสมสำหรับเซิร์ฟเวอร์ ให้สร้าง key ใน Google AI Studio (aistudio.google.com) และส่งค่าให้ CLI ผ่าน environment variable โดย CLI จะอ่านค่าจาก GEMINI_API_KEY และข้ามขั้นตอนการใช้เบราว์เซอร์ไปทั้งหมด สำหรับข้อควรระวังเรื่องความปลอดภัย ห้าม พิมพ์ export GEMINI_API_KEY=AIza... ลงใน prompt โดยตรง เพราะค่าจะถูกบันทึกเป็น cleartext ใน ~/.bash_history และ ห้าม เก็บไว้ในไฟล์ที่ผู้อื่นสามารถอ่านได้ ให้เขียนค่าลงในไฟล์ที่มี permission แบบ mode-600 เพื่อให้ shell เรียกใช้ตอนเริ่มต้น:

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 หมายถึงอนุญาตให้เฉพาะ user ของคุณเท่านั้นที่อ่านไฟล์ได้ ตรวจสอบว่า key ถูกโหลดเข้าสู่ environment หรือยังด้วยคำสั่ง printenv GEMINI_API_KEY หากคำสั่งนี้ไม่แสดงผลใดๆ แสดงว่า CLI จะกลับไปใช้วิธีการผ่านเบราว์เซอร์และจะล้มเหลว นอกจากนี้ CLI ยังสามารถอ่านไฟล์ .env ใน ~/.gemini/ ได้หากคุณต้องการใช้รูปแบบนั้น โดยต้องใช้กฎความปลอดภัยเดียวกันคือ chmod 600 ~/.gemini/.env

วิธีที่สองคือการใช้การเข้าสู่ระบบด้วยบัญชี Google ส่วนบุคคล (เพื่อใช้ free tier) โดยการทำ tunnel เพื่อส่ง OAuth callback กลับมายัง laptop ของคุณ ข้อจำกัดคือ loopback server ของ CLI จะสุ่มพอร์ตใหม่ทุกครั้งที่รัน ดังนั้นคุณต้องกำหนดพอร์ตให้คงที่ก่อนด้วย environment variable OAUTH_CALLBACK_PORT แล้วจึงทำการ forward พอร์ตนั้น:

# 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 ไม่สามารถเปิดเบราว์เซอร์ได้ ระบบจะแสดง auth URL ให้ ให้คุณเปิด URL นั้นในเบราว์เซอร์บน laptop และกดยืนยัน เมื่อ Google redirect ไปยัง http://localhost:8085/... การทำ SSH forward จะส่งข้อมูลไปยัง loopback server บน VPS และการเข้าสู่ระบบจะเสร็จสมบูรณ์ หากคุณไม่กำหนดพอร์ตให้คงที่ ระบบจะสุ่มพอร์ตใหม่ทุกครั้ง ซึ่งการตั้งค่า ssh -L ไว้ล่วงหน้าจะไม่สามารถดักจับพอร์ตที่เปลี่ยนไปได้ วิธีนี้ใช้งานได้จริงแต่ต้องมีคนคอยกดเบราว์เซอร์อยู่ตลอดเวลา จึงไม่เหมาะสำหรับใช้งานใน script สำหรับงานที่ต้องรันทิ้งไว้ ให้ใช้วิธี API key

หากใช้ Vertex AI หรือ Google Cloud project แทน AI Studio ให้ตั้งค่า GOOGLE_API_KEY ร่วมกับ GOOGLE_GENAI_USE_VERTEXAI=true หรือใช้ GOOGLE_CLOUD_PROJECT สำหรับ Code Assist licence โดยต้องใช้หลักการจัดการ environment variable และการใช้ไฟล์ mode-600 เช่นเดียวกัน

รันคำสั่งภายใน tmux เพื่อป้องกันไม่ให้การหลุดของ SSH session ทำให้กระบวนการหยุดทำงาน

กระบวนการ gemini ที่คุณเริ่มใช้งานโดยตรงจาก SSH shell จะเป็น child process ของ shell นั้น หากการเชื่อมต่อขาดหายไป ไม่ว่าจะเป็นกรณีปิด laptop, สัญญาณ Wi-Fi หลุด หรือเกิด idle timeout จะส่งผลให้ sshd ทำการปิด pseudo-terminal ซึ่งทำให้ shell ได้รับสัญญาณ SIGHUP และปิดการทำงานของ CLI ตามไปด้วย หากคุณกำลังแก้ไขไฟล์อยู่เป็นเวลา 10 นาที งานนั้นจะหยุดทำงานทันที และเมื่อเชื่อมต่อใหม่จะไม่มีกระบวนการใดให้กู้คืนได้

tmux แก้ปัญหานี้โดยการเป็นเจ้าของ shell แทนที่ sshd ซึ่งเป็นรูปแบบเดียวกับ การรัน AI coding agent บน remote VPS ภายใน tmux และมีหลักการทำงานที่เหมือนกันดังนี้:

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 จะทำการ attach เข้ากับ session ที่ชื่อว่า gemini หากมีอยู่แล้ว หรือสร้าง session ใหม่หากยังไม่มี ดังนั้นจึงเป็นคำสั่งเดียวที่ควรใช้ทันทีหลังจาก login ทุกครั้ง Shell ที่อยู่ภายในจะขึ้นตรงกับ tmux server ที่ถูก detach ไว้ ไม่ได้ขึ้นตรงกับ SSH session ของคุณ ดังนั้นเมื่อการเชื่อมต่อขาดหายไป CLI จะยังคงทำงานต่อไป เมื่อคุณเชื่อมต่อใหม่และทำการ attach คุณจะกลับเข้าสู่หน้าจอเดิมที่เคยใช้งานค้างไว้

สำหรับการรันแบบ script ที่ไม่มีการโต้ตอบ Gemini CLI มี headless mode: gemini -p "summarise the failing tests in this repo" จะพิมพ์คำตอบแล้วจบการทำงาน และ --output-format json จะให้ output ในรูปแบบ machine-readable เพื่อส่งต่อไปยังคำสั่งอื่น Headless mode พร้อมกับ API key คือสิ่งที่คุณต้องการเมื่อใช้งานภายใน tmux session ที่กำลังรันงานแบบ batch ขนาดใหญ่ หรือรันผ่าน cron — อย่างไรก็ตาม มีข้อควรระวังหนึ่งประการคือ cron job จะไม่โหลดไฟล์ login ใดๆ ของคุณ ดังนั้นคุณต้องระบุ GEMINI_API_KEY ไว้ในบรรทัด crontab (หรือสั่งให้คำสั่งทำการ source ~/.gemini_env) มิฉะนั้น CLI จะเปลี่ยนไปใช้ browser flow และทำงานล้มเหลว

Sandboxing และการกำหนดสิทธิ์บนเครื่องที่รันระบบ Production

Agent ที่มีสิทธิ์เข้าถึง shell คือ shell อย่างหนึ่ง Gemini CLI สามารถรันคำสั่งได้ และโดยปกติจะมีการถามก่อนรันคำสั่งที่มีความเสี่ยง แต่หากผู้ใช้เลือกใช้ --yolo (อนุมัติทุกการเรียกใช้ tool โดยอัตโนมัติ) Agent จะสามารถลบไฟล์, push ไปยัง git หรือเรียกใช้งาน internal services ได้ด้วยสิทธิ์สูงสุดของผู้ใช้ที่รันโปรแกรมนั้น หากใช้งานบนเครื่องที่รันระบบ production อยู่ด้วย จะถือเป็นความเสี่ยงที่เกิดขึ้นจริง ไม่ใช่เพียงแค่การสมมติ

มาตรการควบคุม 3 ประการ เรียงตามลำดับความสำคัญ:

• รันโปรแกรมด้วย user ที่ไม่มีสิทธิ์พิเศษ (unprivileged user) และแยกต่างหาก ห้ามใช้ root หรือ user ที่เป็นสมาชิกของ sudo ให้สร้าง user agent ที่มี home directory ของตัวเอง ติดตั้ง Node และ CLI ไว้ในนั้น เพื่อจำกัดขอบเขตหากมีการรันคำสั่งที่ผิดพลาดให้อยู่เฉพาะใน account นั้น นี่คือการตัดสินใจที่มีความสำคัญสูงสุด
• ไม่เก็บข้อมูลสำคัญของระบบ production ไว้บนเครื่องนี้ ห้ามมี prod ~/.aws/credentials, ห้ามคัดลอก .env จากระบบ production มาไว้ที่นี่ และห้ามมีรหัสผ่านฐานข้อมูลที่มีสิทธิ์เขียน (write access) ในส่วนที่สำคัญ ให้ใช้ข้อมูลรับรอง (credential) ของระบบ staging หรือแบบ read-only แทน
• ใช้ sandbox ที่มีมาให้ หากติดตั้ง Docker หรือ Podman ไว้ gemini --sandbox (หรือ GEMINI_SANDBOX=docker) จะรันการเรียกใช้ tool ของ agent ภายใน container ที่แยกออกจาก filesystem และ network ของ host วิธีนี้ไม่ใช่สิ่งที่จะนำมาใช้แทนการใช้ unprivileged user แต่เป็นชั้นป้องกันที่สองที่มีประสิทธิภาพเมื่อต้องใช้งาน VPS เครื่องเดียวกันในการทำงานจริง

หากคุณรัน Gemini CLI ควบคู่ไปกับเครื่องมือ self-hosted อื่นๆ เช่น MCP server ที่เปิดใช้งาน tools ให้กับ agent บน VPS เครื่องเดียวกัน ให้ถือว่าความสามารถที่เพิ่มเข้ามาแต่ละอย่างคือพื้นที่ที่ agent สามารถเข้าถึงได้มากขึ้น และควรจำกัดขอบเขตของ token ที่มอบให้ agent ให้ทำงานได้เพียงงานเดียวเท่านั้น

Quota, cost, and which auth path you chose

วิธีการยืนยันตัวตน (auth path) เป็นตัวกำหนดรูปแบบการเรียกเก็บเงิน บัญชี Google ส่วนบุคคล (OAuth path) จะใช้ Gemini Code Assist ระดับฟรี ซึ่งมีข้อจำกัดต่อนาทีและต่อวัน หากใช้งานเกินกำหนด ระบบจะส่งข้อความแสดงข้อผิดพลาด rate-limit จนกว่าจะถึงรอบเวลาที่กำหนด ส่วน API key จาก AI Studio อาจเป็นระดับฟรีหรือแบบเรียกเก็บเงินขึ้นอยู่กับโปรเจกต์ โดยคีย์แบบเรียกเก็บเงินจะเพิ่มขีดจำกัดการใช้งานและคิดค่าบริการตามจำนวน token สำหรับ Vertex และ Cloud-project auth จะเรียกเก็บเงินผ่าน Google Cloud

ข้อควรระวังในการใช้งานจริง 2 ประการ ประการแรก การใช้ agent ที่ทำงานแบบอัตโนมัติใน loop อาจทำให้ quota หมดอย่างรวดเร็ว จึงควรเฝ้าสังเกตในช่วงแรกก่อนจะตั้งค่าให้ทำงานผ่าน cron job ประการที่สอง หากเหตุผลในการใช้ model ฝั่ง server คือเรื่องความเป็นส่วนตัวหรือต้องการใช้งานแบบไม่จำกัดจำนวนครั้ง แทนการใช้ hosted models ของ Google คุณต้องใช้เครื่องมืออื่น เช่น self-hosting an open LLM with Ollama on a VPS ซึ่งจะเก็บ weights และ prompts ไว้ในเครื่องของคุณเอง แต่จะมีข้อจำกัดคือต้องใช้ model ที่มีขนาดเล็กกว่า Gemini มาก

การรักษาเวอร์ชันให้เป็นปัจจุบัน

Gemini CLI มีการออกเวอร์ชันใหม่อยู่บ่อยครั้ง เนื่องจากคุณติดตั้งไว้ใน user-owned prefix การอัปเดตจึงไม่จำเป็นต้องใช้ sudo:

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

มีช่องทางการปล่อยเวอร์ชัน (release channels) ดังนี้: @latest คือเวอร์ชัน stable, @preview คือเวอร์ชัน weekly preview และ @nightly คือเวอร์ชัน bleeding edge — แนะนำให้เลือกใช้ @latest สำหรับระบบที่ต้องการความเสถียร หากใช้ nvm แพ็กเกจแบบ global จะอยู่ภายใต้ Node version ที่ใช้งานอยู่ ดังนั้นหลังจากใช้ nvm use เพื่อเปลี่ยน Node คุณอาจต้องติดตั้ง CLI ใหม่ ควรตรวจสอบ release notes แทนการคอยติดตามทุก patch

Failure modes, with the exact strings

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' } ตามด้วย CLI crash ขณะทำงาน เนื่องจาก Node มีเวอร์ชันเก่าเกินไป โดย distro ใช้เวอร์ชัน 18.19.1 ซึ่งหมดอายุการใช้งาน (end-of-life) แล้ว ให้ติดตั้ง Node 20+ จาก NodeSource หรือ nvm ตรวจสอบความถูกต้องด้วย node --version หากมีการติดตั้ง Node ไว้หลายเวอร์ชัน ให้ตรวจสอบว่า which node ชี้ไปยังเวอร์ชันใหม่ ไม่ใช่ /usr/bin/node

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...' เกิดจากการติดตั้งแบบ global ลงใน prefix ที่เป็นของ root ห้ามใช้ sudo ให้ตั้งค่า npm config set prefix ~/.npm-global กำหนด ~/.npm-global/bin ไว้ที่ PATH และติดตั้งใหม่ด้วย user ปกติ หากการติดตั้ง sudo npm ก่อนหน้านี้ทิ้งไฟล์ cache ที่เป็นของ root ไว้ (Your cache folder contains root-owned files) ให้รัน sudo chown -R $(id -u):$(id -g) ~/.npm

Failed to open browser การ login ค้าง หรือ redirect_uri=http://localhost:PORT ที่ไม่สามารถเข้าถึงได้ เนื่องจาก OAuth flow ต้องการ browser ซึ่งไม่มีอยู่ใน server และ localhost callback ชี้ไปที่ server แทนที่จะเป็น laptop ของคุณ ให้ใช้วิธี API-key (GEMINI_API_KEY) หรือ pin OAUTH_CALLBACK_PORT แล้ว forward ผ่าน SSH ด้วย ssh -L และเปิด URL ในเครื่อง local

กระบวนการหายไปเมื่อ SSH หลุด เนื่องจากคุณรัน gemini ผ่าน SSH shell โดยตรง ทำให้กระบวนการนั้นเป็น child ของ shell และถูกปิดตัวลงพร้อมกับ pty เมื่อการเชื่อมต่อขาดหาย ไม่สามารถกู้คืนได้ ให้เริ่มทุก session ด้วย tmux new -A -s gemini และรัน CLI ภายในนั้น

การยืนยันตัวตนยังล้มเหลวแม้ตั้งค่า key แล้ว — CLI กลับไปที่หน้าเลือกวิธี auth หรือ request ส่งคืน API key not valid พร้อม HTTP 400 เนื่องจาก key ไม่ได้อยู่ใน environment ที่ CLI มองเห็น ตรวจสอบด้วย printenv GEMINI_API_KEY หากค่าว่าง แสดงว่ายังไม่ได้โหลด ~/.gemini_env ให้ตรวจสอบว่ามีบรรทัดดังกล่าวใน ~/.bashrc หรือไม่ ซึ่ง interactive shells (รวมถึง tmux) จะอ่านไฟล์นี้ แต่ cron และ non-interactive shells อื่นๆ จะไม่อ่าน นอกจากนี้ การมีช่องว่างหรือเครื่องหมายคำพูดเกินมาในค่าของ key จะทำให้เกิด API key not valid

429 / RESOURCE_EXHAUSTED / ข้อความ rate-limit คุณใช้งานเกินโควตาของระดับการใช้งาน (tier) ที่ใช้ยืนยันตัวตนอยู่ ให้รอจนกว่าจะถึงรอบการรีเซ็ต ลดความเร็วของ agent หรือเปลี่ยนไปใช้ API key แบบเสียเงิน หาก agent ติดอยู่ใน loop การ retry จะทำให้เกิดปัญหานี้ซ้ำๆ ให้หยุดการทำงานและตรวจสอบการทำงานของมัน

FAQ

วิธีการยืนยันตัวตน Gemini CLI บน headless server

ให้ใช้ API key แทนการเข้าสู่ระบบผ่าน browser หากสร้าง key ใน Google AI Studio และเก็บไว้ในไฟล์ mode-600 ที่ shell เรียกใช้ (export GEMINI_API_KEY=...) ตัว CLI จะข้ามขั้นตอน OAuth browser flow ไปโดยสิ้นเชิง หากต้องการใช้สิทธิ์ใช้งานฟรีแบบบัญชีส่วนตัว ให้กำหนด port loopback ด้วย OAUTH_CALLBACK_PORT=8085 แล้วทำ port forwarding กลับมายัง laptop ของคุณด้วย ssh -L 8085:localhost:8085 user@server จากนั้นจึงเปิด URL ที่แสดงขึ้นมาบนเครื่อง local — แต่วิธีนี้ต้องมีการใช้งานผ่าน browser จึงไม่เหมาะสำหรับใช้งานใน script

ทำไมการติดตั้ง npm แบบ global ถึงต้องใช้ sudo และจะหลีกเลี่ยงได้อย่างไร

เนื่องจากค่า default global prefix ของ npm คือ /usr/lib/node_modules ซึ่ง user ทั่วไปไม่มีสิทธิ์เขียนไฟล์ ทำให้การใช้ npm install -g ปกติจะเกิดข้อผิดพลาด EACCES วิธีแก้ไขที่ผิดคือการใช้ sudo npm -g เพราะจะทำให้มีไฟล์ที่ถูกครอบครองโดย root ซึ่งจะส่งผลเสียต่อการติดตั้งในภายหลัง วิธีแก้ไขที่ถูกต้องคือการเปลี่ยน prefix ไปที่ home directory (npm config set prefix ~/.npm-global) และเพิ่ม bin ลงใน PATH หรือใช้ nvm ซึ่งจะติดตั้ง global packages ไว้ใน home directory ให้โดยอัตโนมัติ

วิธีทำให้ Gemini CLI ทำงานต่อไปได้หลังจากตัดการเชื่อมต่อ

ให้รันผ่าน tmux กระบวนการ (process) ที่เริ่มจาก SSH shell จะถูกปิดลงเมื่อการเชื่อมต่อขาดหายไป เนื่องจากเป็น child process ของ shell นั้น tmux จะรัน shell ภายใต้ detached server ซึ่งยังคงทำงานอยู่แม้การเชื่อมต่อจะขาดไป ให้ใช้ tmux new -A -s gemini รัน gemini ไว้ภายใน จากนั้น detach ด้วย Ctrl-b d และกลับมา reattach ภายหลังด้วย tmux attach -t gemini

การรัน Gemini CLI บน production box มีความปลอดภัยหรือไม่

ต้องใช้งานด้วยความระมัดระวัง เนื่องจาก agent ที่มีสิทธิ์เข้าถึง shell สามารถทำงานได้ทุกอย่างที่ user นั้นทำได้ ควรใช้งานภายใต้ user ที่ไม่มีสิทธิ์ sudo และไม่มีสิทธิ์ระดับสูง (unprivileged user) โดยเฉพาะ ห้ามเก็บ production credentials ไว้บนเครื่องดังกล่าว หลีกเลี่ยงการใช้ --yolo แบบ auto-approval และใช้ --sandbox (Docker หรือ Podman) เพื่อแยกการเรียกใช้ tool ออกจาก host สิทธิ์ของบัญชีที่ใช้รันมีความสำคัญมากกว่าการตั้งค่า flag ใดๆ

จำเป็นต้องเปิด port ของ firewall สำหรับ Gemini CLI หรือไม่

ไม่จำเป็น เนื่องจากเป็น client ที่ส่งคำขอ HTTPS ออกไปยัง Google's APIs จึงต้องการเพียง outbound port 443 แต่ไม่ต้องเปิด inbound port หากคุณใช้ OAuth tunnel port สำหรับ callback (เช่น 8085) จะทำงานบน localhost และเข้าถึงผ่าน SSH forward เท่านั้น ไม่ใช่การเปิด inbound port ให้ปิดการเข้าถึงจากภายนอก (inbound) ไว้เสมอ