วิธีติดตั้ง Gemini CLI บน VPS แบบ Headless ผ่าน SSH

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

Gemini CLI ที่ทำงานตลอดเวลาบนเซิร์ฟเวอร์ส่วนตัวของคุณ ซึ่งเข้าถึงได้ผ่าน SSH และรันงานเอเจนต์ระยะยาวที่ยังคงทำงานต่อไปแม้คุณจะปิดแล็ปท็อปไปแล้ว การติดตั้งใช้เพียง 3 คำสั่ง สิ่งที่ต้องจัดการเพิ่มเติมคือส่วนที่ออกแบบมาสำหรับเดสก์ท็อป: CLI ของ Google ต้องการเปิดเบราว์เซอร์เพื่อล็อกอิน แต่เซิร์ฟเวอร์ของคุณไม่มีเบราว์เซอร์ ดังนั้นเนื้อหาส่วนใหญ่ในคู่มือนี้จึงเป็นแนวทางแบบ headless, การใช้ Node เวอร์ชันปัจจุบันที่ distro ของคุณไม่มีให้, การติดตั้ง npm แบบ global โดยไม่ต้องใช้สิทธิ์ root, การยืนยันตัวตนแบบไม่มีเบราว์เซอร์ด้วย API key ที่คุณต้องเก็บไว้ไม่ให้ปนใน shell history และการใช้ tmux เพื่อป้องกันไม่ให้งานที่รันอยู่ถูกตัดการเชื่อมต่อเมื่อเซสชัน SSH หลุด

Gemini CLI เป็นโปรแกรม Node แบบโอเพนซอร์ส (Apache-2.0) (@google/gemini-cli) ที่สื่อสารกับโมเดล Gemini ของ Google โดยสามารถอ่านและเขียนไฟล์, รันคำสั่ง shell และใช้งานเครื่องมือต่างๆ ในไดเรกทอรีที่ทำงานอยู่ได้ บน VPS มันคือเอเจนต์ขนาดเล็กที่พร้อมใช้งานตลอดเวลาซึ่งคุณสามารถปล่อยให้ทำงานทิ้งไว้ได้ ด้วยเหตุนี้ บัญชีผู้ใช้ที่รันโปรแกรมและข้อมูลรับรองที่เก็บไว้บนเครื่องจึงมีความสำคัญมากกว่าการตั้งค่าใดๆ ในคู่มือนี้

ข้อกำหนดเบื้องต้นและข้อควรระวังที่สำคัญ

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

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

หมายเหตุ: แพ็กเกจใน distro มีเวอร์ชันเก่าเกินไป

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 ที่ไม่รองรับ ซึ่งอาจทำงานผิดพลาดหรือ crash ทันทีที่เรียกใช้ Node 20+ API ที่คาดว่าจะต้องมี นอกจากนี้ Node 18 ยังสิ้นสุดระยะเวลาสนับสนุน (end-of-life) ในเดือนเมษายน 2025 ดังนั้นจึงถือเป็นทางตันในทุกกรณี ควรติดตั้ง LTS เวอร์ชันปัจจุบัน ก่อน ที่จะติดตั้ง CLI โดยมีวิธีที่สะอาดอยู่ 2 วิธี คือ NodeSource (apt repo ที่มีการเซ็นกำกับสำหรับทั้งระบบ) หรือ 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 สำหรับสคริปต์การตั้งค่าล่าสุด โดย 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 เพื่อดู release ล่าสุดและเปลี่ยนเวอร์ชันก่อนที่จะรันคำสั่ง nvm มีข้อได้เปรียบที่แท้จริงสำหรับงานนี้คือ มันจะติดตั้ง Node และแพ็กเกจ global ไว้ภายใต้ ~/.nvm ดังนั้นปัญหาเรื่องสิทธิ์ในการติดตั้งแบบ global ในหัวข้อถัดไปจึงไม่เกิดขึ้น หากคุณเลือกใช้วิธี nvm คุณสามารถข้ามขั้นตอน npm-prefix ไปได้เลย

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

คำสั่งที่น่าใช้คือ sudo npm install -g @google/gemini-cli แต่ห้ามทำเช่นนั้น การใช้ global prefix ที่เป็นของ root จะทำให้เกิดข้อผิดพลาดด้านสิทธิ์ในการติดตั้งครั้งต่อๆ ไป และทิ้งไฟล์ที่เป็นของ root ไว้ใน npm cache ซึ่งจะสร้างปัญหาให้คุณในอีกหลายเดือนข้างหน้า หากคุณรัน npm install -g แบบปกติ (ไม่ใช้ sudo) กับ 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 ซึ่งผู้ใช้ของคุณไม่มีสิทธิ์ วิธีแก้ไขไม่ใช่การใช้ sudo แต่เป็นการกำหนด global prefix ของ npm ให้ชี้ไปยังโฮมไดเรกทอรีของคุณ เพื่อให้การติดตั้งแบบ 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 ของคุณไม่สำเร็จ ให้ดูที่หัวข้อรูปแบบความล้มเหลว สำหรับ nvm ให้ข้ามบรรทัดการกำหนด prefix ไปได้เลย เพราะ nvm ติดตั้งแพ็กเกจแบบ global ไว้ในโฮมไดเรกทอรีของคุณอยู่แล้ว

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

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

ให้รัน gemini แบบโต้ตอบในครั้งแรก ระบบจะเสนอให้คุณล็อกอินด้วยบัญชี Google บนเดสก์ท็อปขั้นตอนนี้จะเปิดแท็บเบราว์เซอร์ขึ้นมา แต่บน 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 นั้นบนแล็ปท็อปและกดยืนยัน แต่ Google จะเปลี่ยนเส้นทางไปยัง http://localhost:PORT ซึ่งเป็น localhost บนเซิร์ฟเวอร์ ซึ่งเป็นพอร์ตที่ไม่มีอะไรบนแล็ปท็อปของคุณเข้าถึงได้ การล็อกอินจึงไม่สำเร็จ

มีวิธีที่ถูกต้องสองวิธีในการจัดการเรื่องนี้

วิธีแรกคือการใช้ API key ซึ่งเป็นค่าเริ่มต้นที่เหมาะสมสำหรับเซิร์ฟเวอร์ ให้สร้างคีย์ใน Google AI Studio (aistudio.google.com) แล้วส่งให้ CLI ผ่านตัวแปรสภาพแวดล้อม (environment variable) ระบบจะอ่านค่า GEMINI_API_KEY และข้ามขั้นตอนการใช้เบราว์เซอร์ไปโดยสิ้นเชิง สำหรับส่วนที่ว่า "เก็บให้พ้นจากประวัติการใช้งานและไฟล์ที่ผู้อื่นอ่านได้" นั้น ห้ามพิมพ์ export GEMINI_API_KEY=AIza... ที่พรอมต์โดยตรง เพราะมันจะถูกบันทึกใน ~/.bash_history เป็นข้อความธรรมดา และห้ามใส่ไว้ในไฟล์ที่ผู้อื่นอ่านได้ ให้เขียนลงในไฟล์ที่มีสิทธิ์ 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 หมายความว่าเฉพาะผู้ใช้ของคุณเท่านั้นที่อ่านไฟล์นี้ได้ ตรวจสอบว่าคีย์ถูกโหลดเข้าสู่สภาพแวดล้อมแล้วด้วย printenv GEMINI_API_KEY หากคำสั่งนี้ไม่แสดงผลลัพธ์ใดๆ CLI จะกลับไปใช้ขั้นตอนผ่านเบราว์เซอร์และล้มเหลว นอกจากนี้ระบบยังอ่านไฟล์ .env ใน ~/.gemini/ ได้หากคุณต้องการรูปแบบนั้น โดยใช้กฎเดียวกันคือ chmod 600 ~/.gemini/.env

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

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

รันโปรแกรมภายใน tmux เพื่อป้องกันไม่ให้กระบวนการถูกยกเลิกเมื่อการเชื่อมต่อ SSH หลุด

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

tmux แก้ไขปัญหานี้โดยการเป็นเจ้าของ shell แทนที่ sshd จะเป็นเจ้าของ ซึ่งเป็นรูปแบบเดียวกับการ รัน AI coding agent บน 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 หากมีอยู่แล้ว หรือสร้างขึ้นใหม่หากยังไม่มี ดังนั้นนี่คือคำสั่งเดียวที่คุณควรเรียกใช้ทันทีหลังจาก login เข้าสู่ระบบ shell ที่อยู่ภายในจะขึ้นตรงกับ tmux server ที่ทำงานแยกส่วน (detached) ไม่ใช่ขึ้นตรงกับ SSH session ของคุณ ดังนั้นหากการเชื่อมต่อหลุดไป CLI ก็จะยังคงทำงานต่อไปได้ เมื่อเชื่อมต่อกลับเข้ามาและ attach เข้าไปใหม่ คุณจะพบหน้าจอเดิมพร้อมประวัติการเลื่อนดูข้อมูล หากคุณรัน agent หลาย session บนเครื่องเดียวกัน โดยแยก session ละหนึ่ง tmux จะไม่มีช่องทางให้พวกมันสื่อสารกันเอง ต่างจาก Claude Code ที่ หนึ่ง session สามารถส่งข้อความไปยังอีก session บน VPS เดียวกันได้ ดังนั้นควรให้งาน Gemini แต่ละงานทำงานเป็นอิสระต่อกัน หรือประสานงานผ่านไฟล์บนดิสก์แทน

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

การทำ Sandboxing และการจัดการสิทธิ์บนเซิร์ฟเวอร์ที่รันงาน Production

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

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

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

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

โควตา ค่าใช้จ่าย และเส้นทางการยืนยันตัวตนที่คุณเลือก

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

มีข้อควรทราบในทางปฏิบัติ 2 ประการ ประการแรก เอเจนต์ที่ทำงานแบบอัตโนมัติในลูปอาจใช้โควตาจนหมดอย่างรวดเร็ว ดังนั้นควรเฝ้าสังเกตการทำงานในช่วงแรกก่อนที่จะปล่อยให้ทำงานผ่าน cron job ประการที่สอง หากเหตุผลที่คุณเลือกใช้โมเดลฝั่งเซิร์ฟเวอร์คือเรื่องความเป็นส่วนตัวหรือการอนุมานแบบไม่จำกัดจำนวนแทนที่จะใช้โมเดลที่โฮสต์โดย Google นั่นถือเป็นเครื่องมือคนละประเภทกัน โดยการ โฮสต์ LLM แบบเปิดด้วยตนเองโดยใช้ Ollama บน VPS จะช่วยเก็บทั้งน้ำหนักโมเดล (weights) และคำสั่ง (prompts) ไว้บนเครื่องของคุณเอง แต่ต้องแลกกับการที่ต้องรันโมเดลที่มีขนาดเล็กกว่า Gemini มาก

การอัปเดตให้เป็นปัจจุบัน

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

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

มีช่องทางการปล่อยซอฟต์แวร์ให้เลือก: @latest คือรุ่นเสถียร, @preview คือรุ่นพรีวิวรายสัปดาห์, @nightly คือรุ่นล่าสุดที่ยังไม่ผ่านการทดสอบอย่างเต็มที่ สำหรับบริการที่คุณต้องใช้งานจริง ให้ล็อกเวอร์ชันไว้ที่ @latest ในกรณีที่ใช้ nvm แพ็กเกจส่วนกลางจะถูกเก็บไว้ภายใต้เวอร์ชันของ Node ที่กำลังใช้งานอยู่ ดังนั้นหลังจากใช้ nvm use เพื่อเปลี่ยนเวอร์ชัน Node คุณอาจจำเป็นต้องติดตั้ง CLI ใหม่ ให้อ่านบันทึกการเปลี่ยนแปลง (release notes) แทนการไล่อัปเดตทุกแพตช์ย่อย

รูปแบบความล้มเหลวและข้อความแจ้งเตือนที่เกี่ยวข้อง

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' } ตามด้วย CLI หยุดทำงานขณะรันไทม์ เวอร์ชันของ Node เก่าเกินไป โดยเวอร์ชัน 18.19.1 ของ distro นั้นสิ้นสุดระยะเวลาสนับสนุนแล้ว ให้ติดตั้ง 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 และติดตั้งใหม่ด้วยผู้ใช้ปกติของคุณ หากการติดตั้ง sudo npm ก่อนหน้านี้ทิ้งไฟล์แคชที่เป็นของ root ไว้ (Your cache folder contains root-owned files) ให้รัน sudo chown -R $(id -u):$(id -g) ~/.npm

Failed to open browser, การล็อกอินที่ค้าง หรือ redirect_uri=http://localhost:PORT ที่เข้าถึงไม่ได้ กระบวนการ OAuth ต้องการเบราว์เซอร์ซึ่งเซิร์ฟเวอร์ไม่มี และ callback ของ localhost ชี้ไปยังเซิร์ฟเวอร์ไม่ใช่เครื่องแล็ปท็อปของคุณ ให้ใช้วิธี API-key (GEMINI_API_KEY) หรือระบุ OAUTH_CALLBACK_PORT, ทำการ forward พอร์ตผ่าน SSH ด้วย ssh -L แล้วเปิด URL ในเครื่องของคุณ

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

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

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

FAQ

ฉันจะยืนยันตัวตน Gemini CLI บนเซิร์ฟเวอร์แบบ headless ได้อย่างไร?

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

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

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

ฉันจะให้ Gemini CLI ทำงานต่อไปได้อย่างไรหลังจากตัดการเชื่อมต่อ?

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

การรัน Gemini CLI บนเครื่อง production ปลอดภัยหรือไม่?

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

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

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