SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 已更新 2026-10-30

無頭 VPS 執行 Gemini CLI:安裝與 SSH 常駐

在無瀏覽器的 Ubuntu 24.04 VPS 執行 Gemini CLI,涵蓋 Node 26、免 sudo 全域安裝、API key 驗證與 tmux,避免 SSH 中斷終止工作。

你要建置的內容

在你擁有的伺服器上執行常駐的 Gemini CLI,透過 SSH 存取,執行即使關閉筆電後仍會持續工作的長時間代理程式工作。安裝只需 3 個命令。真正需要處理的是所有以桌面環境為前提的部分:Google 的 CLI 會要求開啟瀏覽器登入,但你的伺服器沒有瀏覽器。因此,本指南大多說明無頭模式的流程、發行版不會提供的新版 Node、不需要 root 的全域 npm 安裝、將 API key 保存在 shell 歷史記錄之外的免瀏覽器驗證方式,以及 tmux,避免 SSH 連線中斷時一併終止執行中的工作。

Gemini CLI 是採用 Apache-2.0 授權的開放原始碼 Node 程式(@google/gemini-cli),可與 Google 的 Gemini 模型通訊,讀寫檔案、執行 shell 命令,並操作工作目錄中的工具。在 VPS 上,它是一個小型且隨時可用的代理程式,你可以讓它持續執行。因此,執行它的帳戶,以及儲存在伺服器上的憑證,比本指南中的任何單一設定更重要。

先決條件與必須留意的限制

  • 一台全新的 Ubuntu 24.04 KVM VPS,並具備 root 或 sudo 權限。Google 的安裝指南建議,日常使用至少需要 4 GB RAM;長時間工作階段及大型程式碼庫則建議至少 16 GB。
  • Node.js 20 或更新版本。這是唯一的最低版本要求,而發行版套件低於此版本,請參閱下一節。Node 20 本身已於 April 30, 2026 終止支援,因此請安裝 26。
  • 可對 Google API 建立對外 HTTPS 連線(port 443)。不需要任何對內連接埠;這是用戶端而非伺服器,因此不必為此開放防火牆規則。
  • 不需在伺服器上使用瀏覽器的驗證方式:可使用 Google AI Studio 提供的 Gemini API key,選擇免費或付費方案;也可使用 Google sign-in,在無頭伺服器上將驗證碼貼回終端機。API key 方式適合延伸至指令碼及無人值守執行。
  • Docker 或 Podman,只有在需要 --sandbox 隔離時才需要。這是選用項目,內容將在接近結尾處說明。

目前最容易造成問題的是帳戶,而不是瀏覽器。Google 於 May 19, 2026 宣布,自 June 18, 2026 起,Gemini CLI 將停止為 Google AI Pro 和 Ultra 訂閱者,以及 Gemini Code Assist for individuals 的免費使用者提供請求服務,並引導這些使用者改用替代產品 Antigravity CLI(agy)。Gemini CLI 仍可搭配 Gemini API key 使用,包括其獨立的免費層級、Gemini Enterprise Agent Platform API key,以及組織的 Gemini Code Assist Standard 或 Enterprise 授權。開始前請先決定驗證方式。

Node:發行版套件版本過舊

Ubuntu 24.04 在自己的套件庫中提供 Node 18.19.1。Gemini CLI 的 package.json 宣告 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 會在不受支援的執行環境中執行。當它使用預期存在的 Node 20+ API 時,可能會行為異常或當機。Node 18 也已於 April 2025 終止支援,因此無論如何都不適合使用。請在安裝 CLI 之前 安裝目前的 LTS 版本。可採用 NodeSource(系統範圍的簽署 apt 套件庫)或 nvm(每位使用者獨立的版本管理器)。請擇一使用。

如果希望所有使用者都能在此主機上使用 Node,請使用 NodeSource:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version

node --version 必須輸出 v20.x 或更高版本,才能符合 CLI 的要求。但 Node 20 已於 April 30, 2026 終止支援,因此建議使用 v26.x,也就是目前的 active LTS。Node 26 已於 October 28, 2026 以 26.13.0 版本進入 LTS。請查看 NodeSource 頁面上的目前設定指令;URL 中的 setup_26.x 是之後有新版 LTS 發行時需要更新的部分。

如果希望將 Node 限制在單一使用者的 home 目錄中,且完全不使用 sudo 操作它,請使用 nvm:

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

URL 中的 v0.40.1 用於固定安裝程式版本;請查看 nvm 的 README 取得最新發行版本,並在執行安裝程式前替換該版本。nvm 對此用途有一項實際優勢:它會將 Node 及其全域套件安裝在 ~/.nvm 下,因此下一節的全域安裝權限問題不會發生。如果採用 nvm,可以略過 npm-prefix 步驟。

安裝 CLI,但不要使用 sudo npm -g

看似合理的指令是 sudo npm install -g @google/gemini-cli。不要這樣做。由 root 擁有的全域 prefix 會導致後續每次安裝都發生權限錯誤,也會在 npm 快取中留下由 root 擁有的檔案,幾個月後造成問題。對系統 Node 執行一般的(不使用 sudo)npm install -g,則會遇到另一個錯誤:

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,而是將 npm 的全域 prefix 指向家目錄,讓全域安裝內容寫入你擁有的路徑:

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 會讓這項 export 設定持續套用至互動式 Bash shell。tmux 預設會啟動 login shell;在 Ubuntu 上,預設的 ~/.profile 也會載入 ~/.bashrc。如果你自訂過 login 檔案,請確認這些檔案仍會載入該設定。執行 gemini --version 並輸出版本號碼,就是完整的測試。如果改為看到 gemini: command not found,表示你的 PATH export 未生效,請參閱失敗模式。使用 nvm 時,完全略過 prefix 設定行:nvm 已經會將全域套件安裝在你的家目錄下。

如果你先前曾執行 sudo npm,現在看到 Your cache folder contains root-owned files,請使用 sudo chown -R $(id -u):$(id -g) ~/.npm 修復一次。

無頭環境的驗證問題,以及解決方法

第一次以互動方式執行 gemini 時,CLI 會提供使用 Google 帳戶登入的選項。在桌面環境中,這會開啟瀏覽器分頁。在無頭 Linux VPS 上,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 使用,但初次登入需要瀏覽器;成功驗證後,憑證會在本機快取,供後續工作階段使用。自 June 18, 2026 起,只有在你的 Google 帳戶仍屬於 Gemini CLI 提供服務的帳戶時,這個流程才可登入。

有兩種直接可行的方法。

第一種是使用 API key,這也是伺服器的預設建議。請在 Google AI Studio(aistudio.google.com)建立金鑰;API key 有獨立的免費方案,因此開始使用時不需要啟用計費。將金鑰交給 CLI,設定為 GEMINI_API_KEY,接著執行 gemini,並在驗證方式選擇器中選取 Gemini API Key;只設定變數不會覆寫已儲存的驗證方式。接著處理「避免金鑰進入歷程記錄及其他使用者可讀取的檔案」的問題。請勿在提示字元中輸入 export GEMINI_API_KEY=AIza...,因為它會以純文字寫入 ~/.bash_history;也不要將它放入其他使用者可讀取的檔案。請在隱藏提示中讀取金鑰,再將它寫入 shell 啟動時會讀取的 mode-600 檔案:

umask 077
read -rsp 'Gemini API key: ' GEMINI_API_KEY
printf '\n'
printf 'export GEMINI_API_KEY=%s\n' "$GEMINI_API_KEY" > ~/.gemini_env
chmod 600 ~/.gemini_env
echo '[ -f ~/.gemini_env ] && . ~/.gemini_env' >> ~/.bashrc
source ~/.bashrc

chmod 600 表示只有你的使用者能讀取該檔案。使用 printenv GEMINI_API_KEY 確認金鑰已進入環境;如果沒有輸出,表示變數未設定,但 CLI 也可能使用已儲存的金鑰。CLI 也會在 ~/.gemini/ 讀取 .env 檔案;如果你偏好這種配置,規則相同,因此請 chmod 600 ~/.gemini/.env。

第二種方法是直接使用 Google 登入。這在無頭主機上不需要 tunnel,也不需要開放連接埠。自 June 18, 2026 起,這主要適用於組織使用的 Gemini Code Assist Standard 或 Enterprise 授權(也請設定 GOOGLE_CLOUD_PROJECT);個人免費版 Gemini Code Assist,以及 Google AI Pro 或 Ultra 訂閱存取權,已不再提供服務。透過一般 SSH 工作階段啟動 CLI,並選擇 Sign in with Google:

gemini

將顯示的 URL 複製到筆記型電腦的瀏覽器中並核准。Google 會重新導向至 https://codeassist.google.com/authcode,該頁面會顯示 authorization code;將它貼到 VPS 上的 Enter the authorization code: 提示字元,登入即完成。伺服器不需要等待 callback,因此不必指定連接埠,也不需要設定 ssh -L。只有 CLI 偵測到顯示器,並採用 loopback 流程時,OAUTH_CALLBACK_PORT 才會有作用。如果你使用 X11 forwarding(ssh -X)連線,會設定 DISPLAY,CLI 也會改採該 loopback 流程,並重新導向至伺服器上的 http://127.0.0.1:PORT/oauth2callback;請執行 NO_BROWSER=true gemini,強制使用貼上驗證碼的流程。初次登入時必須在瀏覽器前操作,但快取的憑證也可用於無頭的腳本化執行。對於需要持續執行的工作,請使用 API key。

如果要使用 Vertex AI 或 Google Cloud project,而不是 AI Studio,請設定 GOOGLE_API_KEY 並在 CLI 中選取 Vertex AI;若使用 Code Assist 授權,則設定 GOOGLE_CLOUD_PROJECT。環境變數的管理規則相同,也應使用 mode-600 檔案。

在 tmux 中執行,避免 SSH 連線中斷時程序終止

您直接從 SSH shell 啟動的 gemini 程序,會成為該 shell 的子程序。連線中斷、筆電關機、Wi-Fi 斷線或閒置逾時時,sshd 會拆除虛擬終端機,shell 會收到 SIGHUP,接著也會對 CLI 發出掛斷訊號。已執行 10 分鐘、正在編輯檔案的工作會一併終止。重新連線後,也沒有程序可供復原。

tmux 會接管 shell,而不是讓 sshd 接管 shell,因此能解決這個問題。這與 在遠端 VPS 的 tmux 中執行 AI coding agent 使用相同模式,在這裡的運作方式也完全相同:

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

如果名為 gemini 的工作階段已存在,tmux new -A -s gemini 會連接該工作階段;如果不存在,則建立該工作階段。因此,每次登入後立即執行這個指令即可。裡面的 shell 隸屬於已分離的 tmux server,而不是 SSH 工作階段,因此即使連線中斷,CLI 仍會繼續執行。重新連線後重新附加,就能回到相同的捲動緩衝區。如果您在同一台主機上執行多個 agent 工作階段,為每個工作階段使用一個 tmux 工作階段,tmux 不會連接這些工作階段的對話。Gemini CLI 支援透過 A2A protocol 使用遠端 subagent,但需個別設定;對於相互獨立的工作,請透過磁碟上的檔案進行協調。如需 Claude Code 的使用模式,請參閱如何讓同一台 VPS 上的一個工作階段將文字傳給另一個工作階段。

對於非互動式的指令碼執行,Gemini CLI 提供 headless mode:gemini -p "summarise the failing tests in this repo" 會輸出答案後結束,--output-format json 會產生可供管線傳遞至其他位置的機器可讀輸出。在使用 API key 的 tmux 工作階段中執行長時間批次工作,或從 cron 項目啟動工作時,headless mode 正是適合的選擇。但有一項注意事項:cron job 不會載入任何 login file,因此在此設定中,請讓指令載入 ~/.gemini_env。快取的認證資料或由 CLI 載入的 .env 檔案也能正常運作;單獨缺少 shell 變數,並不能證明此次執行沒有認證資料。

同時執行正式環境的主機:沙箱與權限

具備 shell 存取權的代理程式,就是具備 shell 存取權的程式。Gemini CLI 可以執行命令;預設會在每次執行高風險命令前詢問確認,但使用者可能會啟用 --yolo(自動核准每次工具呼叫)。如此一來,代理程式便能以其設定的沙箱可用權限刪除檔案、推送至 git,或存取內部服務。針對 --yolo,目前的預設值會啟用沙箱。在同時執行正式環境服務的主機上,這是實際的影響範圍,不是假設性的風險。

以下列出 3 項控制措施,依能降低風險的程度排序:

  • 使用專用的非特權使用者執行。 不要使用 root,也不要加入 sudo。建立 agent 使用者,為其配置獨立的 home 目錄,並在該使用者環境中安裝 Node 與 CLI。即使誤解指示,影響也會限制在該帳號內。這是價值最高的單一決策。
  • 不要將正式環境的憑證放在該主機上。 不要放置正式環境的 ~/.aws/credentials,不要從正式環境複製 .env 到主機,也不要提供可寫入重要資源的資料庫密碼。改用 staging 或唯讀憑證。
  • 使用內建沙箱。 安裝 Docker 或 Podman 後,gemini --sandbox(或 GEMINI_SANDBOX=docker)會在容器內執行代理程式的工具呼叫。容器只掛載目前的專案目錄,不會掛載主機檔案系統的其餘部分。這不能取代非特權使用者,但在同一台 VPS 也執行正式工作時,能提供強而有力的第二層防護。

如果你在其他自架工具旁執行 Gemini CLI,例如使用在同一台 VPS 上向代理程式提供工具的 MCP server,應將每項新增功能視為代理程式可存取範圍的擴大,並將提供給它的 token 限制在單一工作所需的範圍內。

配額、費用,以及你選擇的驗證方式

驗證方式會決定計費方式;自 2026 年 6 月 18 日起,也會決定你是否能繼續使用服務。根據 Google 的公告,自該日起,Gemini CLI 不再為 Google AI Pro 和 Ultra 訂閱者,以及 Gemini Code Assist for individuals 的免費使用者提供請求服務。Gemini API keys 保留獨立的免費層級,付費用量則依模型與 token 用量計費。Gemini Enterprise Agent Platform API keys,以及組織的 Gemini Code Assist Standard 或 Enterprise 授權仍受支援。限制取決於驗證方法、模型與層級;共用服務容量不足時,請求也可能失敗。

有兩點實務注意事項。未受人工監控、持續迴圈執行的 agent 可能會快速耗盡配額,因此在交由 cron job 執行前,前幾次應先監看它的行為。若你在伺服器端使用模型的原因是隱私,或需要不受用量計費限制的推論,而不是使用 Google 託管的模型,那是不同的工具;在 VPS 上使用 Ollama 自行託管開放式 LLM,可讓模型權重與提示保留在自己的主機上,但代價是只能執行遠小於 Gemini 的模型。

保持更新

Gemini CLI 經常發布新版本。由於您將它安裝到使用者擁有的 prefix 中,因此更新時不需要 sudo:

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

Gemini CLI 提供多個發行通道:@latest 是穩定版,@preview 是每週預覽版,@nightly 是最新開發版。對於任何相依的環境,請固定使用 @latest。使用 nvm 時,全域套件會安裝在目前啟用的 Node 版本下。因此,在執行 nvm use 切換 Node 版本後,可能需要重新安裝 CLI。請閱讀發行說明,不要追逐每個修補程式版本。

失敗模式與確切字串

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' },接著 CLI 在執行階段當機。 Node 版本過舊;發行版提供的是 18.19.1,而且該版本也已超過支援期限。請從 NodeSource 或 nvm 安裝目前的 LTS 版本,並以 node --version 確認。若安裝了多個 Node,請確認 which node 指向新版本,而不是 /usr/bin/node。

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'。 這表示全域安裝目標位於 root 擁有的 prefix。不要使用 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://127.0.0.1:PORT。 CLI 找到了顯示器變數(通常來自 ssh -X),因此採用了 loopback 流程;其 callback 會回到伺服器。請執行 NO_BROWSER=true gemini 以使用貼上程式碼的流程,或改用 API key 路徑(GEMINI_API_KEY)。在一般 SSH 工作階段中,應改為看到 Enter the authorization code:;請在筆記型電腦的瀏覽器中核准該 URL,再貼上 Google 顯示的程式碼。

SSH 中斷後,程序就消失了。 你直接在 SSH shell 中執行了 gemini,因此它是該 shell 的子程序,連線中斷時也隨 pty 一起結束。沒有可復原的內容。每次工作階段都應先啟動 tmux new -A -s gemini,再在其中執行 CLI。

已設定 key,但驗證仍失敗;CLI 返回驗證選擇器;或請求以 HTTP 400 返回 API key not valid。 請同時檢查選取的驗證方法與 key。在驗證選擇器中選取 Gemini API Key;即使存在 GEMINI_API_KEY,CLI 仍會遵循已儲存的驗證選擇。以 printenv GEMINI_API_KEY 確認;若結果為空,請檢查是否已載入 ~/.gemini_env,或透過 CLI 支援的儲存方式或 .env 檔案提供 key。API key not valid 表示提供的 key 不正確、格式錯誤或已不存在;請在 AI Studio 中核對該 key,並移除前導或尾端空白。

429 / RESOURCE_EXHAUSTED / 速率限制訊息。 你已達到配額或速率限制,或 Google Cloud 路徑沒有可用的共享容量。請檢查錯誤詳細資訊與方案的限制。若配額耗盡,請等待限制視窗重設、降低 agent 的執行速度,或申請提高配額;若是暫時性的容量錯誤,請使用指數退避重試。改用付費 API key 不代表一定有可用容量。陷入重試迴圈的 agent 會持續觸發此問題;請停止它並檢查其執行內容。

FAQ

如何在無頭伺服器上驗證 Gemini CLI?

使用 Google AI Studio 提供的 API key;其獨立的免費方案不需要計費。將金鑰放入由 shell 載入的 mode-600 檔案(export GEMINI_API_KEY=...),執行 gemini,並選取 Gemini API Key,以使用無瀏覽器驗證。如果改用 Google 登入,例如使用 Code Assist Standard 或 Enterprise 授權,無頭主機上的 CLI 會顯示 URL;請在筆記型電腦上開啟該 URL、完成核准,然後將 Google 顯示的代碼貼回 Enter the authorization code: 提示。無須固定任何埠,也不需要 tunnel。初次登入需要瀏覽器,但後續工作階段與無頭執行可使用快取的憑證。個人使用者的免費 Gemini Code Assist 存取權已於 June 18, 2026 結束;這項變更不影響 API key 免費方案。

為什麼 npm 的全域安裝需要 sudo?如何避免?

因為 npm 的預設全域 prefix 是 /usr/lib/node_modules,目前使用者沒有寫入權限,因此直接執行 npm install -g 會因 EACCES 而失敗。錯誤的作法是使用 sudo npm -g;這會留下由 root 擁有的檔案,導致後續安裝失敗。正確作法是將 prefix 指向家目錄(npm config set prefix ~/.npm-global),並將其 bin 加入 PATH;也可以使用 nvm,這會自動將全域套件安裝到家目錄下。

如何在中斷連線後讓 Gemini CLI 持續執行?

在 tmux 中執行。從 SSH shell 啟動的程序是該 shell 的子程序;連線中斷時,程序也會結束。tmux 會在分離的伺服器中執行 shell,因此即使連線中斷仍可持續運作。使用 tmux new -A -s gemini,在其中執行 gemini,使用 Ctrl-b d 分離,稍後再以 tmux attach -t gemini 重新連接。

在 production 主機上執行 Gemini CLI 是否安全?

只有在審慎設定下才安全,因為具備 shell 存取權的 agent 可以執行其使用者可執行的任何操作。請使用專用的非特權使用者執行,且不要授予 sudo 權限;不要將 production 憑證存放在該主機上;避免使用 --yolo 自動核准,並使用 --sandbox(Docker 或 Podman)將工具呼叫與主機隔離。執行該程序的帳戶,比任何單一旗標設定更重要。

Gemini CLI 需要開放任何防火牆埠嗎?

不需要。它是會向 Google API 發出對外 HTTPS 請求的 client,因此只需要對外連線的 443 埠,不需要任何對內開放的埠。無頭主機上的 Google 登入也不需要開放埠:將代碼貼回終端機即可,不必在伺服器上接收 callback。請持續封鎖對內連線。

這篇文章對您有幫助嗎?

#gemini-cli#node#tmux#headless#ai#vps