Gemini CLI 执行 Shell 命令实战指南：直接执行、后台进程与安全防护

2026-09-04 13:47:27作者：俞予舒Fleming

本文基于 gemini-cli 官方教程 shell-commands.md 整理，系统讲解如何在 Gemini CLI 对话中执行 Shell 命令：通过 ! 前缀直接运行命令并进入 Shell 模式、借助 run_shell_command 工具让模型自动化“跑测试—读错误—修代码—再验证”的闭环、用 /shells 管理后台进程，以及确认提示与沙箱（Sandbox）两层安全机制。读完本篇，你可以安全地让 AI Agent 在你的终端里跑构建、管理 git、启动并监控长期运行的服务，并理解其背后的工具实现与配置方式。

前置条件

已安装并完成认证的 Gemini CLI。
对系统所用 Shell（Bash、Zsh、PowerShell 等）有基本了解。

用 `!` 前缀直接执行命令

当你只是想查一下文件大小或 git 状态、并不需要 AI 代理代劳时，可以在输入框中以 ! 开头直接下发命令，例如：

!ls -la

命令会被立即交给你的 Shell 执行，输出直接打印到终端。更重要的是，该命令及其输出会被记录到当前会话上下文中，模型在后续对话里可以引用这些结果；非常大的输出可能会被截断。

从源码实现看，这一行为由 UI 层处理：当用户提交以 ! 开头的输入时，消息会以用户 Shell 消息的形式呈现，展示时剥离 ! 前缀（见 UserShellMessage.tsx），而命令的输出会进入会话历史供模型引用。

场景：进入 Shell 模式

如果你需要连续执行多条手动命令，可以输入单独的 ! 然后按 Enter 切换进入 "Shell Mode"（Shell 模式）。进入后，你输入的一切都会直接发送给 Shell，直到退出（通常按 Esc 或输入 exit）。

源码中，Shell 模式是一个受控的 UI 状态位（shellModeActive），在 InputPrompt.tsx 中通过切换逻辑进入/退出，界面会显示 Shell 模式指示器（ShellModeIndicator.tsx）；在此模式下，队列消息和斜杠命令会被明确拒绝（“Shell commands cannot be queued”），以保证手动输入直接下发。

自动化复杂任务：跑测试并修复失败

将 Gemini CLI 与 Shell 命令结合，可以自动化多步工作流。

场景：运行测试并修复失败

目标：跑单测，如有失败则分析错误并尝试修复。

提示词：

Run the unit tests. If any fail, analyze the error and try to fix the code.

实际工作流：

Gemini 调用 run_shell_command('npm test')；
你看到确认提示：Allow command 'npm test'? [y/N]；
你按 y 批准；
测试运行。若有失败，Gemini 读取错误输出；
Gemini 用 read_file 查看失败的测试文件；
Gemini 用 replace 修复 Bug；
Gemini 再次运行 npm test 验证修复。

这个“执行—观察—修复—复验”的循环让模型可以自主推进任务。其基础是核心包中的 Shell 工具实现 shell.ts，它把模型生成的命令交给 ShellExecutionService 执行，并将标准输出、标准错误、退出码等结构化返回给模型——正是这份结构化的返回让模型能够判断命令成功与否并决定下一步动作。

Shell 工具（`run_shell_command`）参数与返回

官方工具参考 shell.md 对 run_shell_command 的定义如下，这里完整列出，方便你理解自动化流程中每一步的底层调用：

平台执行方式：Windows 上命令通过 powershell.exe -NoProfile -Command 执行；其他平台通过 bash -c 执行。

参数：

command（string，必填）：要执行的精确 Shell 命令；
description（string，可选）：展示给用户用于确认的简短描述；
dir_path（string，可选）：命令运行的绝对路径，或相对于工作区根目录的相对路径；
is_background（boolean，可选）：启动后立即将进程转入后台。

从源码看，ShellToolParams 中还包含 delay_ms 等内部字段，用于后台化前的输出时序控制。

返回值（JSON 对象）：

Command：实际执行的命令字符串；
Directory：执行目录；
Stdout / Stderr：输出流；
Exit Code：进程返回码；
Background PIDs：后台进程的 PID 列表。

判断命令是否成功，应检查 Stderr、Error 与 Exit Code 字段。此外，工具执行时会设置环境变量 GEMINI_CLI=1，脚本可以据此检测自己是否运行在 Gemini CLI 内部。

管理后台进程

对于开发服务器、文件监听器等长期运行的任务，可以直接要求模型在后台启动它们。

提示词： Start the React dev server in the background.

Gemini 会执行命令（例如 npm run dev）并将其转入后台。实现上，shell.ts 中的 wrapCommandForBackgroundPIDs 会在非 Windows 平台用子 Shell 包裹命令，通过 trap ... EXIT 机制把子进程 PID 写入临时文件，再回传到返回值的 Background PIDs 字段——这样模型和 /shells 面板都能准确追踪到底哪些进程在后台运行。

场景：查看活跃的后台 Shell

使用 /shells 命令查看当前后台运行的进程：

/shells

这会打开一个仪表盘（dashboard），你可以查看各后台 Shell 的日志，或终止失控的进程（见 commands.md 中 /shells 的说明，该命令亦可写作 /bashes）。后台 Shell 工具集的实现位于 shellBackgroundTools.ts。

交互式命令的处理

Gemini CLI 会尝试通过流式输出处理交互式命令（如 git add -p、各类确认提示）。但对于高度交互式的工具（如 vim、top），更建议你在独立终端窗口中运行，或使用 ! 前缀直接执行。

如需让模型代理本身运行真正的交互式程序（文本编辑器、TUI、git rebase -i 等），可以在 settings.json 中开启交互式 Shell（基于 node-pty，不可用时回退到不支持交互的 child_process 实现）：

{
  "tools": {
    "shell": {
      "enableInteractiveShell": true
    }
  }
}

安全机制

赋予 AI 访问 Shell 的能力强大但存在风险，Gemini CLI 内置了多层防护。

确认提示

默认情况下，Agent 请求的每一条 Shell 命令都需要你显式批准：

Allow once：只允许本次执行；
Allow always：在本次会话内信任该特定命令；
Deny：拒绝并终止该操作。

命令白名单与黑名单

除逐条确认外，还可通过配置限制模型可请求的命令（见 shell.md）：

tools.core：命令前缀白名单，格式为 run_shell_command(<command>)，例如 "tools": {"core": ["run_shell_command(git)"]} 只允许 git 命令；包含通用的 run_shell_command 则等价于通配符放行。注意该设置是所有内置工具的白名单，而非仅 Shell 工具；
tools.exclude（已废弃，建议改用策略引擎）：命令前缀黑名单，黑名单优先级始终高于白名单。

校验逻辑有两条关键规则：命令链被拆分验证——用 &&、||、; 链接的命令会被拆开逐段校验，任何一段被禁止则整条命令被阻断；前缀匹配——允许 git 即可运行 git status、git log 等。