想把 Gemini CLI 放到 VPS 上，通过 SSH 随时接回同一个代码仓库，难点通常不是 npm install，而是 Ubuntu 自带的 Node 版本、无桌面环境的登录方式，以及 SSH 断开后如何保住会话。这篇教程面向一台 Ubuntu VPS、一个开发者、使用云端模型的场景：创建普通用户，安装受支持的 Node.js 和 Gemini CLI，用 API Key 完成远程认证，再用 tmux 续接交互会话。
先说明边界：Gemini CLI 是运行在 VPS 上的 coding agent，会读取项目文件并按权限执行工具；模型请求发往所选 Google 服务。VPS 不会因为安装 CLI 就变成“本地部署 Gemini 模型”的机器。本文不需要开放额外 Web 端口，远程入口仍是 SSH。
按 Gemini CLI 官方安装文档，运行环境需要 Node.js 20+、网络连接；官方建议短会话、普通任务使用 4 GB 以上内存，长会话和大型代码库则以 16 GB 以上作为建议值。这些是官方的推荐规格，不是所有项目的性能保证。只用 CLI 做小仓库分析时可先从 4 GB 级别 VPS 起步；如果还要在同一台机器跑编译、测试或 Docker，按项目实际峰值增加 CPU、内存和磁盘。
部署前确认 VPS 能通过 SSH 登录、可以访问 npm 和所选模型服务；Google AI Studio 与 Gemini API 的可用地区和账户配额也要以当前官方页面为准。别先买一年套餐再发现网络或地区条件不满足。生产服务器上建议把 agent 与业务服务分开；本文的示例用户不会加入 sudo 组。
下面以 Ubuntu 24.04/26.04 为例，假设当前 SSH 用户有 sudo 权限。先装基础工具并创建 coder 用户；如果这个用户已存在，跳过创建命令：
sudo apt update
sudo apt install -y curl git tmux ca-certificates
sudo adduser --disabled-password --gecos '' coder
sudo -iu coder
接下来的命令都在 coder 用户会话中执行。Ubuntu 24.04 的系统 Node 版本可能低于 Gemini CLI 要求，所以先检查 node -v，不要只看 apt install nodejs 是否成功。这里用 nvm 官方安装方式给普通用户安装当前 LTS Node，不需要全局 sudo npm：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm install --lts
nvm alias default 'lts/*'
node -v
npm -v
确认 node -v 至少是 20，再安装 Gemini CLI 的稳定版。官方安装包名是 @google/gemini-cli：
npm install -g @google/gemini-cli
gemini --version
command -v gemini
如果重新 SSH 登录后提示找不到 nvm 或 gemini，先以 coder 用户执行 . "$HOME/.nvm/nvm.sh"，再检查 ~/.bashrc 是否加载了 nvm。不要用 sudo npm install -g 绕过普通用户的权限问题；那会让安装位置和运行身份混在一起。
Gemini CLI 认证文档列出 API Key 与 Vertex AI 等方式；个人 Google 账号的 Login with Google 路径已经停用，Google 的弃用公告明确指出这也影响 Gemini CLI。本文选择 Google AI Studio 的 Gemini API Key，既适合无桌面 VPS，也避开已停用的个人账号登录路径。先在自己的浏览器打开 Google AI Studio创建密钥，并确认账户、地区、配额与付费条件。不要把密钥贴到仓库、工单或聊天里。
在 coder 用户会话中，通过隐藏输入把密钥写入家目录下权限为 600 的文件。下面的 %q 会把输入转成 Bash 可安全读取的形式，避免直接把密钥写进命令历史：
install -d -m 700 "$HOME/.config/gemini-cli"
read -r -s -p '粘贴 Gemini API Key: ' gemini_api_key
printf '\n'
umask 077
printf 'export GEMINI_API_KEY=%q\n' "$gemini_api_key" > "$HOME/.config/gemini-cli/key.sh"
unset gemini_api_key
chmod 600 "$HOME/.config/gemini-cli/key.sh"
. "$HOME/.config/gemini-cli/key.sh"
test -n "${GEMINI_API_KEY:-}" && echo 'API Key 已加载'
key.sh 不要放在 Git 项目里。API Key 用量可能产生费用，建议在提供商侧设置可用的预算和告警；如果怀疑泄露，立即在提供商侧轮换密钥，然后更新这个文件。首次启动交互界面时，如出现认证方式选择，选 Use Gemini API key。先用一个不会修改文件的小请求验证实际调用：
mkdir -p "$HOME/workspaces/demo"
cd "$HOME/workspaces/demo"
git init
printf '# VPS Gemini CLI 测试仓库\n' > README.md
gemini -p '只用一句话说明当前仓库有什么文件，不要修改文件'
-p 会进入官方 Headless 模式，适合先验证认证与网络。若有配额或地区错误，先查 Google 账户与 API Key 的可用性，不要立刻重装 VPS。实际项目再由 coder 用户克隆到 ~/workspaces/；私有仓库尽量使用仅针对该仓库的部署凭据，而不是复制个人主力 SSH 私钥。
正常 SSH 终端断开会结束前台进程；tmux 能把交互会话留在 VPS 上。仍在 coder 用户下执行：
tmux new -s gemini
export NVM_DIR="$HOME/.nvm"
. "$NVM_DIR/nvm.sh"
. "$HOME/.config/gemini-cli/key.sh"
cd "$HOME/workspaces/demo"
gemini
在 tmux 内按 Ctrl-b 再按 d，可以退出显示但不关闭会话。下次 SSH 登录后，执行 sudo -iu coder，再运行：
tmux ls
tmux attach -t gemini
如果 tmux ls 说没有 server，先确认是否登录了同一个 Linux 用户，以及上次的 Gemini CLI 是否已经退出。tmux 保住的是 SSH 断线后的进程，不保证 VPS 重启后自动恢复会话，也不代表 agent 会无休止地继续执行任务。 重启后要重新进入项目、加载密钥并检查 Git 状态。
Gemini CLI 可以申请执行 shell 命令；官方 shell 工具教程说明默认会让用户确认。首次使用先让它解释代码和提出计划，再批准写入或安装依赖。不要为了省去提示就启用自动批准所有操作；特别是同一台 VPS 还承载生产网站时，先在测试仓库演练。
普通用户不是完整沙箱。 coder 仍能读取它有权限访问的文件。把项目、凭据和备份边界安排好，不要赋予 sudo 权限，也不要把生产 .env、数据库备份、云密钥放进可读工作区。需要更强隔离时可按照 Gemini CLI 沙箱文档配置 Docker/Podman，但先确认容器运行时和工作目录挂载方式；不要把 coder 随意加入具有宿主机管理能力的 Docker 组。
每次让 agent 改代码后，先看 git status、git diff 和测试结果，再决定是否提交。重要项目要有远端 Git 和站外备份。VPS 快照不能代替可验证的项目备份，区别可参考站内快照、备份与镜像说明。
gemini: command not found：先运行 node -v、command -v npm 和 command -v gemini；在 coder 用户下重新加载 ~/.nvm/nvm.sh。不要在 root 账户里安装一份，再期待普通用户自动找到。
VPS 无法完成 Google 浏览器登录：个人账号的 Login with Google 已停用，先改用本文的 API Key 方式，并检查 test -n "${GEMINI_API_KEY:-}" 是否成功。官方对无界面模式给出的路径是 API Key 或 Vertex AI；不要复制浏览器里的令牌文件到 VPS 充当通用登录方案。
出现 401、配额或模型不可用：核对密钥所属项目、账户地区和配额，检查 VPS 的出站网络。认证成功不等于当前模型有可用配额；各认证方式的额度和费用以官方配额与价格页为准。
SSH 重连后项目不对：先 pwd 和 git status，再回到原来的项目目录；tmux attach 连接的是已有会话，里面保留的是上次的工作目录。任务结束没看到修改：用 git diff 和 CLI 输出确认，别把“会话仍在”当成“改动已完成”。
更新前记下 gemini --version，在 coder 用户下备份项目与 ~/.gemini/ 配置，再运行 npm install -g @google/gemini-cli@latest，重新验证版本和一个只读请求。Gemini CLI 稳定版会持续更新，遇到新版本异常时先查官方发布说明并回到已测试版本，不要在生产项目里直接试预览版。
Gemini CLI 需要 GPU VPS 吗？ 本文使用云端模型，不需要为模型推理购买 GPU。VPS 配置主要取决于代码库规模、编译测试负载和并发任务。
可以用个人 Google 账号直接在无桌面 VPS 登录吗？ 截至本文发布时，个人账号的 Gemini CLI “Login with Google” 已停用。本文使用 Gemini API Key；有 Gemini Code Assist Standard/Enterprise 或 Vertex AI 的组织应按对应认证文档配置，先核对自身授权方式。
tmux 是让 Gemini CLI 24 小时自动写代码吗？ 不是。它只保存正在运行的终端会话，SSH 断开后可以重新接回。无人值守任务应另行设计触发、权限、日志和失败处理，不能把交互会话当成自动化系统。
已经部署 Codex CLI 或 Claude Code，还需要这篇吗？ 如果你要使用 Gemini 的模型与 CLI 工作流，这篇解决的是它在 VPS 上的 Node 版本和无桌面认证问题。其他工具的远程部署步骤分别见 Codex CLI 教程和 Claude Code 教程。