Gemini CLI 命令速查表 - Google 终端 AI 代理全参数

现象agent 反复读 .env 或在 node_modules 里搜索，每次会话都浪费时间并有泄漏风险

原因agent 默认扫描整个工作区，没有告诉它哪些路径应被忽略。

处置在项目根写 .geminiignore 列出 .env、node_modules/ 等敏感与冗余目录，缩小工作区映射范围。

现象会话进行到中途开始重复已有结论、响应变慢或被截断

原因对话累计 token 逼近上下文上限，早期内容被挤压，模型可用空间变小。

处置用 /context 查看当前用量，执行 /compress 总结压缩历史；长任务跨天用 /save 保存检查点，下次 /restore 接着做。

现象脚本里跑 -p 一直卡在某步不动，非交互环境没人点确认

原因默认审批模式下工具调用会等待人工确认，而 -p 无头会话没有终端可以响应。

处置无人值守场景显式指定 --approval-mode=yolo（比 -y 语义更清晰），并先用 --approval-mode plan 在只读模式验证任务可行性。

现象agent 直接改动了本分支的多个文件，想丢弃却只能手工 git 恢复

原因直接在主工作区运行，且未启用检查点，回滚只能靠版本控制。

处置运行前加 --checkpointing 以便 /restore 回退，或加 -w feat/xxx 在独立 git worktree 里干活，主分支不受影响。

现象想让 agent 参考某个设计文档，它说找不到文件或凭空编造内容

原因文件不在工作区映射范围内，或提示词里没有显式引用。

处置在提示词开头用 @./docs/architecture.md 显式注入；文件在工作区之外时用 --include-directories 加入映射。

现象改了 GEMINI.md 但 agent 行为没变化，仍按旧约定执行

原因会话启动时已加载上下文文件，磁盘上的新内容不会自动生效。

处置执行 /memory refresh 重新加载，或 /memory list 确认当前实际加载的是哪些文件。

现象接了多个 MCP 服务器后启动明显变慢，工具列表长到找不到想用的那个

原因所有 MCP 服务器与扩展都会在本会话注册，工具数量膨胀。

处置用 gemini mcp disable 停用暂时不用的服务器，或用 -e 限定本会话加载的扩展集合，用 /tools 确认实际可用工具。

现象在 CI / 服务器上跑时报认证错误，本机交互登录却正常

原因本机走的是浏览器 OAuth 凭据，而无头环境没有浏览器也没有凭据文件。

处置CI 场景改用 gemini --auth-method=api-key 并预先 export GEMINI_API_KEY；企业内可用 GOOGLE_GENAI_USE_VERTEXAI=true 走 Vertex AI。