Google Gemini CLI 完全上手指南

2025-07-24 17 min

Google Gemini CLI 完全上手指南

Gemini CLI 一个开源的 AI 代理，将 Google 强大的 Gemini 模型无缝集成到您的终端中。本指南将带您从零开始，一步步掌握这个效率神器。

🚀 第一步：入门指南

1. 安装

您可以选择以下任意一种方式安装 gemini-cli：

全局安装 (推荐):
```
npm install -g @google/gemini-cli
```
无需安装，直接运行:
```
npx @google/gemini-cli
```

2. 使用 Gemini API 密钥进行身份验证

首次使用前，您需要一个 API 密钥来“唤醒”AI。

获取密钥: 前往 Google AI Studio 免费获取您的 API 密钥。
设置密钥:
- 方法一: 环境变量 (推荐) 将此行添加到您的 Shell 配置文件中 (如 ~/.bashrc, ~/.zshrc)，即可永久生效。
```
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
```
- 方法二: 环境文件 在 ~/.gemini/ (全局) 或 ./.gemini/ (项目特定) 目录下创建一个 .env 文件，并写入：
```
GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
```

3. 基本调用

交互模式 (REPL): 启动一个可以持续对话的会话。
```
gemini
```

非交互模式: 使用 -p 参数快速提问。

gemini -p "总结一下这个文件的要点。 @./summary.txt"

管道输入: 将其他命令的输出传递给 Gemini。
```
echo "从1数到10" | gemini
```
沙盒模式: 在一个安全的环境中运行工具 (需要 Docker 或 Podman)。
```
gemini --sandbox -p "你的指令"
```

4. 其他常用标志

-m, --model <model>: 使用指定的模型。
-d, --debug: 启用调试输出，查看更多过程信息。
--yolo: “You Only Live Once”模式，自动批准所有工具调用，跳过确认步骤 (请谨慎使用)。
--checkpointing: 开启“检查点”功能，在修改文件前创建快照。

⚙️ 第二步：配置你的 CLI

1. 配置文件 (settings.json)

通过创建 settings.json 文件来自定义 CLI 的行为。CLI 会按以下优先级加载配置：项目 > 用户 > 系统。

项目级: .gemini/settings.json
用户级: ~/.gemini/settings.json
系统级: /etc/gemini-cli/settings.json

settings.json 示例:

{
  "theme": "GitHub",
  "autoAccept": false,
  "sandbox": "docker",
  "checkpointing": {
    "enabled": true
  },
  "fileFiltering": {
    "respectGitIgnore": true
  },
  "usageStatisticsEnabled": true
}

autoAccept: 自动批准安全的、只读的工具调用。
sandbox: 隔离工具的执行环境，如 "docker"。
checkpointing: 启用 /restore 命令以撤销文件更改。
usageStatisticsEnabled: 设置为 false 可禁用匿名使用统计。

2. 上下文文件 (GEMINI.md)

这是 gemini-cli 的精髓之一。通过 GEMINI.md 文件为 AI 提供项目背景和行为指令，就像是为它设定了“记忆”和“人设”。

分层加载: CLI 会智能地合并所有找到的 GEMINI.md 文件，具体文件会覆盖通用文件。加载顺序为：全局 -> 项目根目录 -> … -> 当前子目录。
查看上下文: 使用 /memory show 命令可以查看最终合并后发送给模型的完整上下文。
模块化导入: 您可以在 GEMINI.md 中使用 @./path/to/another.md 语法导入其他 Markdown 文件，使上下文管理更清晰。

GEMINI.md 示例:

# 主项目背景: 我的超赞应用

## 通用指令
- 所有 Python 代码必须符合 PEP 8 规范。
- 所有新文件使用2个空格缩进。

## 组件专属风格指南
@./src/frontend/react-style-guide.md
@./src/backend/fastapi-style-guide.md

🛠️ 第三步：与 AI 的工具箱协作

gemini-cli 内置了强大的工具集。您无需记住具体函数，只需用自然语言下达指令。

内置工具一览

文件系统工具: list_directory, glob, read_file, write_file, replace, search_file_content 等，用于与本地文件和目录交互。
Shell 工具: 执行 shell 命令。请谨慎使用。您可以在 settings.json 中使用 excludeTools 来禁用危险命令，例如: "excludeTools": ["run_shell_command(rm)"]。
Web 工具: google_web_search (在线搜索), web_fetch (获取网页内容)。
记忆工具: save_memory，让 AI 跨会话记住特定信息，例如: > 记住我的首选CSS框架是Tailwind CSS。

通过 MCP 服务器自定义工具

您可以通过运行模型上下文协议 (MCP) 服务器来扩展 CLI，添加您自己的工具。在 settings.json 中配置即可。

mcpServers 配置示例:

"mcpServers": {
  "myPythonServer": {
    "command": "python",
    "args": ["-m", "my_mcp_server", "--port", "8080"],
    "cwd": "./mcp_tools/python",
    "env": {
      "DATABASE_URL": "$DB_URL_FROM_ENV"
    },
    "timeout": 15000,
    "trust": false,
    "includeTools": ["safe_tool_1", "safe_tool_2"],
    "excludeTools": ["dangerous_tool"]
  }
}

⚡ 第四步：核心命令

实用的斜杠命令 (`/`)

命令	描述
`/compress`	用摘要替换整个聊天上下文以节省令牌。
`/mcp`	列出已配置的 MCP 服务器及其可用工具。
`/clear`	清除终端屏幕和上下文 (`Ctrl+L` 也有效)。
`/tools`	列出所有可用工具。
`/extensions`	列出已激活的扩展。
`/stats`	显示会话令牌使用情况和节省量。
`/memory show`	显示所有 `GEMINI.md` 文件合并后的完整上下文。
`/memory refresh`	重新加载所有 `GEMINI.md` 文件。
`/chat save <tag>`	使用标签保存当前对话。
`/chat resume <tag>`	恢复已保存的对话。
`/restore`	列出或恢复项目状态检查点。
`/auth`	更改当前的身份验证方法。
`/bug`	提交关于 Gemini CLI 的问题或错误报告。
`/help`	显示帮助信息和可用命令。
`/theme`	更改 CLI 的视觉主题。
`/quit`	退出 Gemini CLI。

上下文命令 (`@`)

在提示中引用文件或目录。

包含单个文件: > 帮我解释一下这段代码。 @./src/main.js
包含整个目录 (递归): > 将这个目录中的代码重构为使用 async/await。 @./src/

Shell 命令 (`!`)

直接在 CLI 中运行 shell 命令。

运行单个命令: > !git status
切换 Shell 模式: 单独输入 ! 可进入持久的 shell 模式，再次输入 ! 退出。

✨ 第五步：高级功能

1. 自定义命令

使用 TOML 文件创建您自己的命令别名。

位置: ~/.gemini/commands/ (全局) 或 <project>/.gemini/commands/ (项目特定)。

示例: ~/.gemini/commands/test/gen.toml

# 调用方式: /test:gen "为登录按钮创建一个测试"
description = "根据描述生成一个单元测试。"
prompt = """
你是一位资深测试工程师。请根据以下需求，使用 Jest 测试框架编写一个全面的单元测试。
 
需求: {{args}}
"""

2. 扩展

创建扩展来添加新功能，如打包一组自定义工具和上下文文件。

位置: <workspace>/.gemini/extensions/ 或 ~/.gemini/extensions/。

示例: <workspace>/.gemini/extensions/my-extension/gemini-extension.json

{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": {
    "my-server": {
      "command": "node my-server.js"
    }
  },
  "contextFileName": "GEMINI.md",
  "excludeTools": ["run_shell_command"]
}

3. 检查点与恢复

这是一个“后悔药”功能，在工具修改文件前保存项目快照。

开启: 使用 --checkpointing 标志启动。

恢复:

# 列出可用的检查点
/restore
 
# 恢复到一个特定的检查点
/restore <checkpoint_file_name>

EOF

Google Gemini CLI 完全上手指南