Shell 工具（run_shell_command）

run_shell_command 用于在 CLI 中执行系统命令。默认在 macOS/Linux 下通过 bash -c，Windows 下通过 cmd.exe /c 运行。

参数

  • command（必填）：完整命令字符串。
  • description：向用户展示的简要说明。
  • directory：执行目录（相对项目根）。

执行结果

工具会返回：

  • Command / Directory
  • Stdout / Stderr
  • Error（若子进程报错）
  • Exit Code / Signal
  • Background PIDs（若使用 & 启动后台任务）

示例：

run_shell_command(command="ls -la")
run_shell_command(command="./scripts/build.sh", directory="scripts", description="编译项目")
run_shell_command(command="npm run dev &", description="后台启动开发服务器")

配置

在 settings.json 中可调整行为：

{
  "tools": {
    "shell": {
      "enableInteractiveShell": true,
      "showColor": true,
      "pager": "less"
    }
  }
}
  • enableInteractiveShell：启用 node-pty，支持交互式命令（如 vim、git rebase -i）；
  • showColor：在交互模式下保留彩色输出；
  • pager：指定分页器（默认 cat）。

当交互模式运行时，可在 CLI 中按 Ctrl+F 聚焦到交互终端并输入命令。

环境变量

命令执行时会注入 GEMINI_CLI=1，方便脚本判断是否在 CLI 内运行。

命令限制

可通过 tools.core 与 tools.exclude 控制允许/阻止的命令前缀：

{
  "tools": {
    "core": ["run_shell_command(git)", "run_shell_command(npm)"],
    "exclude": ["run_shell_command(git push)"]
  }
}
  • core：允许列表（支持前缀匹配）；
  • exclude：阻止列表（优先级更高）；
  • 命令中若包含 && / || / ; 会拆分逐个校验；
  • 若需要完全禁用 Shell 命令，可将 run_shell_command 加入 exclude。

excludeTools 对 Shell 的限制仅基于字符串匹配，无法作为严密的安全策略，若需安全隔离请结合沙箱使用。

安全提示

执行命令前需谨慎，尤其是含用户输入的命令；检查 Stderr、Exit Code 以确认是否成功；使用 & 启动后台任务时，CLI 会立即返回并提供后台 PID。