---
title: "Shell 工具"
description: "Gemini CLI Shell 工具的使用边界：运行测试、构建、Git、后台进程、确认提示、sandbox 和危险命令。"
verifiedAt: "2026-05-09"
---

Shell 工具让 Gemini CLI 能跑测试、构建、脚本和 Git 命令。它是最有用也最危险的工具之一。

> [!WARNING]
> Shell 工具一旦授权过宽，风险会从“回答错”变成“真实执行错”。

官方工具名是 `run_shell_command`。在 Windows 上通过 `cmd.exe /c` 执行，在 macOS / Linux 上通过 `bash -c` 执行。返回结果会包含 command、directory、stdout、stderr、error、exit code、signal，以及后台进程 PID。

## 适合执行

- `git status`
- `npm test`
- `pnpm run build`
- `pytest`
- `rg "keyword"`
- 项目已有只读诊断脚本

## 谨慎执行

- `rm`
- `mv`
- `chmod`
- 数据库迁移。
- 部署脚本。
- 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

```text
先列出你准备执行的命令、原因和风险。不要直接运行。
```

后台进程要额外约束：

```text
如果需要启动 dev server，请说明端口、退出方式和任务结束后是否保留进程。
```

长任务里不要让 Shell 工具无限重试。失败后应先分析 stderr、环境、依赖和路径，再决定下一条命令。

## 失败处理边界

Shell 失败时，先判断失败类型：

- 命令不存在：检查项目脚本、PATH 和运行环境。
- 权限不足：确认是否应该提升权限，不要默认加 `sudo`。
- 测试失败：读失败用例，不要直接改实现。
- 网络失败：区分临时网络、代理、认证和服务端错误。
- 目录错误：重新确认 cwd，而不是在多个目录里盲跑。

真正危险的是“为了让命令过而改命令”。例如跳过测试、加 `--force`、删除 lockfile、清空缓存、扩大权限，都必须单独解释风险并等待确认。

## 验收方式

每条命令都看三件事：运行目录是否正确，exit code 是否为 0，stderr 是否包含真实错误。启动 dev server、watcher 或后台任务后，还要记录 PID 或端口，任务结束时明确是否需要保留。

## 接下来去哪

<Cards>
  <Card title="Web 工具" description="继续看 google_web_search 和 web_fetch 的来源核验边界。" href="/docs/gemini-cli/official/03-tools-mcp/33-web-tools" />
  <Card title="Sandbox" description="命令执行需要和 sandbox、approval、policy 一起控制。" href="/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
  <Card title="Automation" description="把 shell 放进自动化前，继续看 headless 和 CI 边界。" href="/docs/gemini-cli/official/07-integrations-automation/73-automation" />
</Cards>

## 官方来源

- [Google Developers Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli?hl=zh-cn)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
