Gemini CLI Extensions 是将 MCP 服务器、自定义命令、Hooks、上下文文件和 Agent Skills 打包分发的标准格式。一行命令安装，立即获得新工具能力。想扩展 CLI 能力或与团队共享配置，用 Extensions 是最整洁的方式。

扩展插件（Extensions）

Extensions 把 MCP 服务器、自定义命令（/cmd）、GEMINI.md 上下文、Agent Skills、Hooks 和主题打包成一个可安装、可共享的单元。用 Extensions 可以：

• 一行命令为 CLI 增加新工具能力
• 与团队共享标准化的工作流配置
• 通过 Extensions Gallery 发现和分发社区扩展

---

安装与管理

安装扩展

gemini extensions install https://github.com/gemini-cli-extensions/workspace

也可以安装本地路径：

gemini extensions install /path/to/my-extension

查看已安装扩展

# 在 CLI 内
/extensions list

# 在终端
gemini extensions list

链接本地开发版本

开发阶段用 link 创建符号链接，改动立即生效，无需重新安装：

gemini extensions link /path/to/my-extension

---

创建你的第一个扩展

第一步：从模板生成

gemini extensions new my-first-extension mcp-server

生成的目录结构：

my-first-extension/
├── example.js           # MCP 服务器源码
├── gemini-extension.json  # 扩展清单（核心配置）
└── package.json         # Node.js 依赖

第二步：理解清单文件

gemini-extension.json 是扩展的核心配置：

{
  "name": "my-first-extension",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["${extensionPath}${/}example.js"],
      "cwd": "${extensionPath}"
    }
  }
}

• ${extensionPath}：Gemini CLI 自动替换为扩展目录的绝对路径
• ${/}：路径分隔符（跨平台兼容）

第三步：添加可配置项

需要 API Key 等配置时，用 settings 数组：

{
  "name": "my-first-extension",
  "version": "1.0.0",
  "settings": [
    {
      "name": "API Key",
      "description": "接入第三方服务的 API Key",
      "envVar": "MY_SERVICE_API_KEY",
      "sensitive": true
    }
  ],
  "mcpServers": { ... }
}

用户安装时，CLI 会弹出提示要求输入 API Key，sensitive: true 时值存入系统密钥链并注入环境变量 MY_SERVICE_API_KEY。

第四步：开发和测试

cd my-first-extension
npm install
gemini extensions link .

重启 Gemini CLI，测试工具是否可用。

---

扩展能力一览

功能	配置位置	说明
MCP 服务器	mcpServers	为模型添加新工具（数据库查询、API 接入等）
自定义命令	commands/<group>/<cmd>.toml	创建 /group:cmd 快捷指令
上下文文件	contextFileName（GEMINI.md）	每次会话自动加载的模型指令
Agent Skills	skills/<name>/SKILL.md	按需激活的专项能力，不占用主上下文窗口
Hooks	hooks	拦截生命周期事件，自定义行为
自定义主题	themes	个性化 CLI 配色

添加自定义命令

在扩展目录创建 commands/fs/grep-code.toml：

prompt = """
请总结以下 grep 搜索结果（搜索词：{{args}}）：

搜索结果：
!{grep -r {{args}} .}
"""

安装后用 /fs:grep-code "pattern" 触发， 替换为你输入的参数，!{...} 块自动执行 Shell 命令。

添加 GEMINI.md 上下文

在扩展根目录创建 GEMINI.md，然后在清单中引用：

{
  "name": "my-extension",
  "contextFileName": "GEMINI.md",
  ...
}

扩展激活时，此文件内容会随每次会话发送给模型。

添加 Agent Skill

创建 skills/security-audit/SKILL.md：

---
name: security-audit
description: >
  安全代码审计专家。当用户要求"检查安全问题"或"代码审计"时激活。
---

# 安全审计员

你是一名资深安全研究员。审计时请：

1. 检查 OWASP Top 10 常见漏洞
2. 扫描硬编码密钥和 API Key
3. 对每个发现提供修复建议

Skill 只在模型判断任务与 description 相关时才激活，不会一直占用上下文窗口。

---

发布扩展

扩展发布通过 Git 仓库或 GitHub Releases 分发：

1. 在 GitHub 创建仓库，推送扩展代码
2. 创建 Release Tag，命名规范：v1.0.0
3. 按 Extensions Gallery 的提交规范提交，让社区用户能搜索到你的扩展

---

与直接配置 settings.json 的区别

场景	推荐方式
个人项目专用工具	直接写 settings.json 的 mcpServers
需要跨项目、跨机器复用	Extensions
需要分发给团队或社区	Extensions（可版本化、可分发）
临时调试工具	直接配置

常见问题

Q: 安装扩展后工具没有出现，怎么排查？

A: ① /extensions list 确认扩展已列出且状态为激活；② /mcp list 检查扩展的 MCP 服务器是否 Connected；③ 重启 Gemini CLI（新安装的扩展需要重启才能加载）；④ 检查扩展的 package.json 依赖是否已安装（npm install）。

Q: 如何更新已安装的扩展？

A: gemini extensions install <url> 重新安装即覆盖更新，或通过 gemini extensions update <name> 命令（如有提供）。链接的本地开发版本修改后立即生效，无需更新。

Q: Extensions 和直接在 settings.json 里配置 MCP 服务器有什么区别？

A: 功能上等价，区别是打包方式。Extensions 把多个配置（MCP + 命令 + 上下文 + Skills）打成一个可版本化的单元，一键安装、一键卸载，适合分发。直接写 settings.json 更灵活，适合个人临时配置。