📦 1. 安装与认证 >>>

安装方式

• npm install -g @google/gemini-cli
• npx @google/gemini-cli (免安装运行)

认证模式

• OAuth (Google 账号)
  gemini auth
  限制：60 RPM / 1000 RPD。不支持 Token Cache。
• API Key Pro
  export GEMINI_API_KEY=...
  100 RPD (免费)。支持 Token Cache。
• Vertex AI (企业级)
  export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=...

🎮 2. 核心交互

启动与会话

• gemini：默认交互模式
• gemini -i "prompt"：带初始提示词
• gemini --resume [id]：恢复指定会话
• gemini --sandbox：在沙盒中启动

会话指令 (Slash)

• /clear：清除当前屏幕
• /model [name]：切换模型 (如 gemini-2.5-flash)
• /stats：查看 Token 消耗与节省
• /session list：查看历史会话列表
• /session delete [id]：删除指定会话

⚙️ 3. 配置管理 >>>

settings.json 结构

{
  "ui": { "theme": "dark", "showLineNumbers": true },
  "general": { "checkpointing": { "enabled": true } },
  "security": { "folderTrust": { "enabled": true } },
  "context": { "includeDirectories": ["src"] }
}

常用环境变量

• GEMINI_API_ENDPOINT：自定义 API 基准 URL
• GEMINI_SYSTEM_MD：自定义 System Prompt 文件
• GEMINI_DEBUG：启用详细调试日志

🤖 4. 自动化与脚本 >>>

Headless 模式

• JSON 输出
  gemini -p "prompt" --output-format json
• 流式输出
  gemini -p "prompt" --output-format stream-json

管道与自定义

• git diff | gemini "生成 commit message"
• cat log.txt | gemini "提取错误摘要"

自定义命令 (.toml)

prompt = """
分析此代码段的复杂度：
{{args}}
!{git status}
@{src/core.js}
"""

🧰 5. 内置工具集 >>>

文件与系统

• read_file / write_file
• list_directory (浏览目录)
• run_shell_command (执行 Shell)

搜索与联网

• google_web_search (实时搜索)
• web_fetch (抓取网页内容)

任务与记忆

• save_memory (跨会话持久记忆)
• write_todos (内置待办事项管理)

🔌 6. 扩展能力 (MCP) >>>

MCP Server 配置

"mcpServers": {
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"]
  }
}

生命周期钩子 (Hooks)

• BeforeTool / AfterTool
• BeforeModel (修改发送给模型的 Prompt)

🚀 7. 高级特性

检查点 (Checkpointing)

• 开启："checkpointing": { "enabled": true }
• 回滚：交互模式下使用 /restore
• 作用：工具修改文件前自动备份，防止损毁

Token 缓存 (Caching)

• 优势：大幅降低重复长上下文的成本
• 触发：前缀匹配时长于 1024 tokens 时触发
• 注意：仅限 API Key 模式可用

自定义沙盒

• 支持通过 .gemini/sandbox.Dockerfile 定制容器

🛡️ 8. 安全与合规 >>>

受信任文件夹 (Trusted Folders)

• 限制工具在未授权目录执行写操作
• 配置项：security.folderTrust

隐私与脱敏

• Telemetry：默认开启数据收集
• 禁用：gemini --no-telemetry
• Redaction：自动隐藏环境变量中的敏感信息

YOLO 模式

• --yolo：自动批准所有工具调用 危险

🧩 9. 配置文件解析

设置加载优先级 (由低到高)

1. Defaults (内置默认值)
2. User Config (~/.gemini/settings.json)
3. Project Config (.gemini/settings.json)
4. .env / Environment Vars
5. CLI Args (命令行参数)

上下文组装 (GEMINI.md)

• 全局：~/.gemini/GEMINI.md
• 父级：路径上的所有祖先目录
• 当前：当前工作目录
• 子级：递归搜索子目录

忽略规则 (.geminiignore)

• 语法兼容 .gitignore
• 用于排除不应被 AI 读取的敏感文件或大文件

⚙️ 10. 配置详解 (一)

General (通用)

"general": {
  "previewFeatures": false,
  "disableAutoUpdate": false,
  "checkpointing": {
    "enabled": false // 开启检查点
  },
  "sessionRetention": {
    "enabled": false, 
    "maxAge": "30d"
  }
}

UI (界面)

"ui": {
  "theme": "dark",
  "showLineNumbers": true,
  "showCitations": false,
  "useAlternateBuffer": false
}

Context (上下文)

"context": {
  "fileName": "GEMINI.md",
  "includeDirectories": [],
  "fileFiltering": {
    "respectGitIgnore": true,
    "respectGeminiIgnore": true
  }
}

⚙️ 11. 配置详解 (二)

Tools (工具)

"tools": {
  "sandbox": undefined,
  "autoAccept": false,
  "useRipgrep": true,
  "allowed": ["run_shell_command(git status)"]
}

Security (安全)

"security": {
  "disableYoloMode": false,
  "folderTrust": { "enabled": false },
  "environmentVariableRedaction": {
    "enabled": true,
    "blocked": ["MY_SECRET"]
  }
}

MCP Servers

"mcpServers": {
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"]
  }
}