วิธีติดตั้ง 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 มีเวอร์ชันต่ำกว่านี้ โปรดดูส่วนถัดไป ทั้งนี้ Node 20 ได้สิ้นสุดระยะเวลาสนับสนุน (end-of-life) ไปเมื่อวันที่ 30 เมษายน 2026 ดังนั้นควรติดตั้งเวอร์ชัน 24
• การเชื่อมต่อ HTTPS ขาออก (พอร์ต 443) ไปยัง Google APIs ไม่จำเป็นต้องเปิดพอร์ตขาเข้า เนื่องจากเครื่องนี้ทำหน้าที่เป็นไคลเอนต์ไม่ใช่เซิร์ฟเวอร์ คุณจึงไม่ต้องเปิดพอร์ตใดๆ บนไฟร์วอลล์
• วิธีการยืนยันตัวตนที่ไม่ต้องใช้เบราว์เซอร์บนเซิร์ฟเวอร์: สามารถใช้ Gemini API key แบบชำระเงินจาก Google AI Studio หรือใช้การลงชื่อเข้าใช้ผ่าน Google ซึ่งบนเครื่องที่ไม่มีหน้าจอ (headless) คุณจะต้องคัดลอกรหัสมาวางในเทอร์มินัล วิธีการใช้ API key เป็นวิธีที่เหมาะสมสำหรับการรันสคริปต์และงานที่ไม่มีผู้ดูแล
• Docker หรือ Podman เฉพาะในกรณีที่คุณต้องการการแยกส่วนด้วย --sandbox ซึ่งเป็นทางเลือกเสริมและจะกล่าวถึงในช่วงท้าย

ข้อควรระวังที่มักเป็นปัญหาสำหรับทุกคนในขณะนี้คือเรื่องบัญชีผู้ใช้ ไม่ใช่เรื่องเบราว์เซอร์ Google ได้ประกาศเมื่อวันที่ 19 พฤษภาคม 2026 ว่าตั้งแต่วันที่ 18 มิถุนายน 2026 เป็นต้นไป 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 ขององค์กร โปรดตัดสินใจเลือกวิธีการยืนยันตัวตนก่อนเริ่มดำเนินการ

หมายเหตุ: แพ็กเกจใน distro เก่าเกินไป

Ubuntu 24.04 มาพร้อมกับ Node 18.19.1 ใน repository ของระบบเอง ซึ่งใช้คู่กับ npm 9.2.0 โดยที่ package.json ของ Gemini CLI ได้ระบุ engines: { node: ">=20" } เอาไว้ แม้ว่าโดยปกติแล้ว npm จะไม่หยุดการทำงานเมื่อพบเวอร์ชันที่ไม่ตรงกัน แต่ 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 ดังนั้นการใช้เวอร์ชันนี้จึงไม่ใช่ทางเลือกที่ดี คุณควรติดตั้ง 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 หรือสูงกว่าเพื่อให้ตรงตามข้อกำหนดของ CLI แต่เนื่องจาก Node 20 ได้สิ้นสุดระยะเวลาสนับสนุนไปแล้วตั้งแต่วันที่ 30 เมษายน 2026 คุณจึงควรตั้งเป้าไปที่ v24.x ซึ่งเป็น LTS เวอร์ชันปัจจุบันที่ยังได้รับการสนับสนุนอยู่ โดย Node 26 มีกำหนดการที่จะเป็น LTS เวอร์ชันหลักในวันที่ 28 ตุลาคม 2026 โปรดตรวจสอบหน้าเว็บไซต์ของ 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 เพื่อดูเวอร์ชันล่าสุดและเปลี่ยนเวอร์ชันก่อนที่จะรันคำสั่ง nvm มีข้อได้เปรียบที่สำคัญสำหรับงานนี้คือ มันจะติดตั้ง Node และแพ็กเกจส่วนกลางไว้ภายใต้ ~/.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 บนเดสก์ท็อปการดำเนินการนี้จะเปิดแท็บเบราว์เซอร์ขึ้นมา แต่บน Linux VPS แบบ headless ตัว 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 ปกติได้ แต่คุณต้องเข้าถึงเบราว์เซอร์ทุกครั้ง และตั้งแต่วันที่ 18 มิถุนายน 2026 เป็นต้นมา วิธีนี้จะใช้งานได้ก็ต่อเมื่อบัญชี Google ของคุณเป็นบัญชีที่ Gemini CLI ยังคงให้บริการอยู่เท่านั้น

มีวิธีที่ตรงไปตรงมา 2 วิธีในการดำเนินการ

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

วิธีที่สองคือการลงชื่อเข้าใช้ด้วย Google โดยตรง ซึ่งบนเครื่อง headless ไม่จำเป็นต้องใช้ tunnel หรือเปิดพอร์ตใดๆ ตั้งแต่วันที่ 18 มิถุนายน 2026 วิธีนี้จะมีประโยชน์หลักสำหรับผู้ที่มีสิทธิ์ใช้งาน Gemini Code Assist Standard หรือ Enterprise ขององค์กร (ต้องตั้งค่า GOOGLE_CLOUD_PROJECT ด้วย) ส่วนบัญชีส่วนบุคคลแบบฟรีและการสมัครสมาชิก Google AI Pro หรือ Ultra จะไม่ได้รับบริการอีกต่อไป ให้เริ่มรัน CLI ผ่านเซสชัน SSH ปกติแล้วเลือก Sign in with Google:

gemini

คัดลอก URL ที่แสดงขึ้นมาไปวางในเบราว์เซอร์บนแล็ปท็อปของคุณแล้วกดยืนยัน Google จะเปลี่ยนเส้นทางไปยัง https://codeassist.google.com/authcode ซึ่งจะแสดงรหัสยืนยันตัวตน ให้คัดลอกรหัสนั้นมาวางที่พรอมต์ Enter the authorization code: บน VPS เพื่อให้การล็อกอินเสร็จสมบูรณ์ ไม่มีกระบวนการใดบนเซิร์ฟเวอร์ที่รอการเรียกกลับ (callback) ดังนั้นจึงไม่มีพอร์ตที่ต้องระบุและไม่มี ssh -L ที่ต้องตั้งค่า OAUTH_CALLBACK_PORT จะมีความสำคัญเฉพาะกับขั้นตอน loopback ที่ CLI ใช้เมื่อตรวจพบการแสดงผลเท่านั้น หากคุณเชื่อมต่อด้วย X11 forwarding (ssh -X) ค่า DISPLAY จะถูกตั้งไว้และ CLI จะเลือกใช้ขั้นตอน loopback นั้นแทน โดยมีการเปลี่ยนเส้นทางไปยัง http://127.0.0.1:PORT/oauth2callback บนเซิร์ฟเวอร์ ให้รัน NO_BROWSER=true gemini เพื่อบังคับให้ใช้ขั้นตอนการวางรหัส วิธีนี้ใช้งานได้จริงแต่คุณต้องนั่งอยู่หน้าเบราว์เซอร์ จึงไม่เหมาะสำหรับสคริปต์ สำหรับงานใดๆ ที่คุณต้องการให้รันค้างไว้ ให้ใช้ API key

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

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

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

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

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

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

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

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

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

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

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

เส้นทางการยืนยันตัวตนเป็นตัวกำหนดวิธีการเรียกเก็บเงิน และตั้งแต่วันที่ 18 มิถุนายน 2026 เป็นต้นมา ยังเป็นตัวกำหนดว่าคุณจะสามารถใช้บริการได้หรือไม่ ตามประกาศของ Google นับจากวันดังกล่าว Gemini CLI ได้หยุดให้บริการแก่สมาชิก Google AI Pro และ Ultra รวมถึงผู้ใช้งานฟรีทุกคน ซึ่งครอบคลุมถึงบัญชีส่วนบุคคลระดับฟรีและ API key ที่ไม่มีการเรียกเก็บเงิน บริการยังคงใช้งานได้ผ่าน Gemini API key แบบชำระเงินและ Gemini Enterprise Agent Platform API key ซึ่งคิดค่าบริการตามจำนวน token รวมถึงองค์กรที่มีสิทธิ์ใช้งาน Gemini Code Assist Standard หรือ Enterprise หรือการเข้าถึง Google Cloud อื่นๆ ซึ่งจะเรียกเก็บเงินผ่าน Google Cloud แต่ละระดับยังคงมีข้อจำกัดต่อนาทีและต่อวัน หากใช้งานเกินกำหนด คำขอจะได้รับข้อผิดพลาด rate-limit จนกว่าจะถึงรอบการรีเซ็ต

ข้อควรทราบในทางปฏิบัติมี 2 ประการ ประการแรก Agent ที่ทำงานอัตโนมัติในลูปอาจใช้โควตาจนหมดอย่างรวดเร็ว ดังนั้นควรเฝ้าสังเกตการทำงานในช่วงแรกก่อนที่จะมอบหมายให้ทำงานผ่าน 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 เก่าเกินไป โดย distro ใช้ 18.19.1 ซึ่งหมดระยะสนับสนุน (end-of-life) แล้ว ให้ติดตั้ง LTS เวอร์ชันปัจจุบันจาก NodeSource หรือ nvm (Node 20 เป็นเวอร์ชันขั้นต่ำที่ CLI รองรับ แต่ก็หมดระยะสนับสนุนไปตั้งแต่เดือนเมษายน 2026 แล้ว) ตรวจสอบด้วย 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 หรือ redirect_uri ที่ชี้ไปยัง http://127.0.0.1:PORT ซึ่งคุณเข้าถึงไม่ได้ CLI ตรวจพบตัวแปร display (มักมาจาก ssh -X) จึงเลือกใช้ flow แบบ loopback ซึ่ง callback จะส่งกลับมาที่เซิร์ฟเวอร์ ให้รัน NO_BROWSER=true gemini เพื่อใช้ flow แบบวางรหัส หรือใช้ช่องทาง API-key (GEMINI_API_KEY) ในการเชื่อมต่อผ่าน SSH ปกติ คุณควรจะเห็น Enter the authorization code: แทน ให้เปิด URL นั้นในเบราว์เซอร์บนแล็ปท็อปของคุณเพื่อยืนยันตัวตน แล้วนำรหัสที่ Google แสดงมาวาง

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

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

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

FAQ

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

ให้ใช้ API key แบบเสียค่าบริการแทนการล็อกอินผ่านเบราว์เซอร์ โดยสร้างคีย์ใน Google AI Studio ภายใต้โปรเจกต์ที่มีการเรียกเก็บเงิน จากนั้นนำไปใส่ไว้ในไฟล์ที่มีสิทธิ์การเข้าถึงแบบ 600 ซึ่ง shell ของคุณจะโหลดใช้งาน (export GEMINI_API_KEY=...) วิธีนี้จะทำให้ CLI ข้ามขั้นตอนการทำ OAuth ผ่านเบราว์เซอร์ไปโดยสิ้นเชิง หากคุณเลือกใช้วิธีล็อกอินด้วยบัญชี Google แทน เช่น กรณีใช้สิทธิ์การใช้งาน Code Assist Standard หรือ Enterprise ตัว CLI บนเครื่อง headless จะแสดง URL ขึ้นมา ให้คุณเปิด URL นั้นบนแล็ปท็อปเพื่อกดยืนยัน แล้วนำรหัสที่ Google แสดงกลับมาวางที่ prompt Enter the authorization code: วิธีนี้ไม่มีพอร์ตให้ระบุและไม่ต้องทำ tunnel แต่จำเป็นต้องมีคุณอยู่หน้าเบราว์เซอร์ จึงไม่เหมาะสำหรับการรันสคริปต์อัตโนมัติ ทั้งนี้ บัญชีส่วนบุคคลแบบฟรีไม่สามารถใช้งาน Gemini CLI ได้ตั้งแต่วันที่ 18 มิถุนายน 2026 เป็นต้นมา

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

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

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

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

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

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

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

ไม่จำเป็น เพราะมันเป็นไคลเอนต์ที่ทำการเรียก HTTPS ออกไปยัง API ของ Google จึงต้องการเพียงพอร์ตขาออก 443 เท่านั้น ไม่ต้องเปิดพอร์ตขาเข้า การล็อกอิน Google บนเครื่อง headless ก็ไม่จำเป็นต้องใช้พอร์ตเช่นกัน เนื่องจากคุณต้องนำรหัสกลับมาวางใน terminal แทนการรับ callback บนเซิร์ฟเวอร์ ให้คงการปิดกั้นพอร์ตขาเข้าไว้ตามเดิม