Shell 工具
Gemini CLI Shell 工具的使用边界：运行测试、构建、Git、后台进程、确认提示、sandbox 和危险命令。
Shell 工具让 Gemini CLI 能跑测试、构建、脚本和 Git 命令。它是最有用也最危险的工具之一。
Shell 工具一旦授权过宽，风险会从“回答错”变成“真实执行错”。
官方工具名是 run_shell_command。在 Windows 上通过 cmd.exe /c 执行，在 macOS / Linux 上通过 bash -c 执行。返回结果会包含 command、directory、stdout、stderr、error、exit code、signal，以及后台进程 PID。
适合执行
git statusnpm testpnpm run buildpytestrg "keyword"- 项目已有只读诊断脚本
谨慎执行
rmmvchmod- 数据库迁移。
- 部署脚本。
- Git push / release。
- 任何带 token 的命令。
| 命令类型 | 默认策略 | 说明 |
|---|---|---|
| 只读诊断 | 可执行但要看目录 | git status、rg、ls |
| 测试 / 构建 | 可执行 | 要记录失败原因和 exit code |
| 安装依赖 | 谨慎 | 可能改 lockfile 或下载大量包 |
| 删除 / 移动 | 高风险 | 必须人工确认具体路径 |
| 发布 / push / 部署 | 高风险 | 不应让模型连续试错 |
配置项
Shell 工具可以通过 settings.json 调整：
tools.shell.enableInteractiveShell：启用交互式 shell，适合需要 pty 的命令。tools.shell.showColor：保留彩色输出，通常依赖 interactive shell。tools.shell.pager：设置输出 pager，默认类似cat。tools.shell.inactivityTimeout：长时间无输出时终止进程。
交互式 shell 能跑 vim、nano、htop、git rebase -i 这类命令，但也更容易让 session 卡住。教程和新手任务里，优先使用非交互命令。
命令如果以 & 结尾，可以启动后台进程。教程里启动 dev server 时，要要求 agent 记录端口、PID 和停止方式；不要让后台进程默默留在系统里。
Policy 控制
不要用 prompt 管 shell 权限。官方更推荐用 policy engine。针对 shell，可以用 commandPrefix 或 commandRegex 写规则，例如让 git 需要确认，让 rm -rf 直接拒绝。
tools.core 是所有内置工具的 allowlist，不只是 shell。误设 tools.core 可能连 read_file、glob、replace 这类工具一起禁掉，所以团队配置前要单独测试。
也可以用 tools.exclude 做 blocklist，但官方文档提醒命令级字符串匹配不是安全边界，命令链和 shell 包装容易绕过。企业或团队教程里，优先展示 allowlist 和 policy，而不是展示一堆看似完整的禁用命令。
Gemini CLI 执行 shell 时会设置 GEMINI_CLI=1。脚本可以利用这个环境变量识别是否由 CLI 启动，但不要因此降低安全校验。
推荐 prompt
先列出你准备执行的命令、原因和风险。不要直接运行。后台进程要额外约束：
如果需要启动 dev server，请说明端口、退出方式和任务结束后是否保留进程。长任务里不要让 Shell 工具无限重试。失败后应先分析 stderr、环境、依赖和路径，再决定下一条命令。
失败处理边界
Shell 失败时，先判断失败类型：
- 命令不存在：检查项目脚本、PATH 和运行环境。
- 权限不足：确认是否应该提升权限，不要默认加
sudo。 - 测试失败：读失败用例，不要直接改实现。
- 网络失败：区分临时网络、代理、认证和服务端错误。
- 目录错误：重新确认 cwd，而不是在多个目录里盲跑。
真正危险的是“为了让命令过而改命令”。例如跳过测试、加 --force、删除 lockfile、清空缓存、扩大权限，都必须单独解释风险并等待确认。
验收方式
每条命令都看三件事：运行目录是否正确，exit code 是否为 0，stderr 是否包含真实错误。启动 dev server、watcher 或后台任务后，还要记录 PID 或端口，任务结束时明确是否需要保留。
接下来去哪
Web 工具
继续看 google_web_search 和 web_fetch 的来源核验边界。
Sandbox
命令执行需要和 sandbox、approval、policy 一起控制。
Automation
把 shell 放进自动化前，继续看 headless 和 CI 边界。