Gemini CLI 扩展

本文档与 v0.4.0 版本保持一致。

Gemini CLI 扩展会将 Prompts、MCP servers 与自定义命令打包为熟悉且易于使用的形式。借助扩展，你可以拓展 Gemini CLI 的能力，并将这些能力分享给他人。扩展旨在做到易于安装与分享。

想要编写你的第一个扩展，请参阅快速入门文档。

若需要了解如何设置 GitHub Releases，请查看发布指南。

扩展管理

我们通过 gemini extensions 命令提供了一套扩展管理工具。

需要注意的是，这些命令无法在 CLI 会话内部执行，但你可以在 CLI 中通过 /extensions list 子命令查看已安装的扩展。

同时请留意，所有命令的效果都会在重新启动当前 CLI 会话后才真正生效。

安装扩展

使用 gemini extensions install 配合 GitHub URL 或本地路径即可安装扩展。

安装后我们会复制一份扩展，因此无论是本地扩展还是 GitHub 扩展，若有更新都需要运行 gemini extensions update 才会生效。

注意：若从 GitHub 安装扩展，你需要在机器上预先安装 git。安装方法可参考 git 安装说明。

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

上面命令会安装 Gemini CLI Security 扩展，该扩展提供 /security:analyze 命令。

卸载扩展

若需卸载，可运行 gemini extensions uninstall extension-name。例如，上面的安装示例对应：

gemini extensions uninstall gemini-cli-security

禁用扩展

扩展默认在所有工作区启用。你可以在用户级或指定工作区禁用扩展。

例如，gemini extensions disable extension-name 会在用户级禁用该扩展，使其在任何地方都不可用。 gemini extensions disable extension-name --scope=workspace 则仅在当前工作区禁用。

启用扩展

使用 gemini extensions enable extension-name 可以重新启用扩展；若只想在特定工作区启用，可在该工作区执行 gemini extensions enable extension-name --scope=workspace。

当你在顶层禁用了扩展，但只想在部分位置使用时，这个命令会很实用。

更新扩展

对于本地路径或 git 仓库安装的扩展，可以通过 gemini extensions update extension-name 显式更新到最新版本（以 gemini-extension.json 中的 version 字段为准）。

若想一次性更新所有扩展，可执行：

gemini extensions update --all

扩展开发

我们也提供命令帮助扩展开发。

创建扩展样板

我们提供了若干示例扩展：context、custom-commands、exclude-tools、mcp-server。可以在 此处 查看源码。

要将其中某个示例复制到指定开发目录，可执行：

gemini extensions new path/to/directory custom-commands

链接本地扩展

gemini extensions link 会将扩展的安装目录与开发目录创建符号链接。

这样在修改扩展时无需每次运行 gemini extensions update 即可测试。

gemini extensions link path/to/directory

工作原理

启动时，Gemini CLI 会在 <home>/.gemini/extensions 中查找扩展。

扩展以目录形式存在，并包含一个 gemini-extension.json 文件。例如：

<home>/.gemini/extensions/my-extension/gemini-extension.json

gemini-extension.json

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"]
}

• name：扩展名称，用于唯一标识以及在命令冲突时的判定。建议使用小写或数字，并用短横线代替下划线或空格。CLI 中用户将通过该名称引用扩展。目录名应与之匹配。
• version：扩展版本号。
• mcpServers：要配置的 MCP server 映射。键为 server 名称，值为 server 配置。启动时会像读取 settings.json 中定义的 server 一样加载。 若扩展与 settings.json 配置了同名 server，以 settings.json 为准。
  • 注意除 trust 外，所有 MCP server 配置项都受支持。
• contextFileName：扩展上下文文件的文件名。CLI 会根据该名称在扩展目录中加载上下文；如果未设置但目录下存在 GEMINI.md，则会默认加载该文件。
• excludeTools：需要从模型中排除的工具名称数组。对于支持命令级限制的工具（如 run_shell_command），可以指定具体命令，例如 "excludeTools": ["run_shell_command(rm -rf)"] 会阻止执行 rm -rf。注意这与 MCP server 中的 excludeTools 配置方式不同。

Gemini CLI 启动时，会加载所有扩展并合并配置。如发生冲突，会以工作区配置为最高优先级。

自定义命令

扩展可在目录下的 commands/ 子目录放置 TOML 文件，引入自定义命令。格式与用户或项目自定义命令一致，命名规范相同。

示例

名为 gcp 的扩展目录结构：

.gemini/extensions/gcp/
├── gemini-extension.json
└── commands/
    ├── deploy.toml
    └── gcs/
        └── sync.toml

将提供以下命令：

• /deploy —— 在帮助信息中显示为 [gcp] Custom command from deploy.toml
• /gcs:sync —— 在帮助信息中显示为 [gcp] Custom command from sync.toml

冲突解决

当扩展命令与用户或项目命令冲突时，扩展命令的优先级最低：

1. 无冲突时：扩展命令沿用原名（如 /deploy）。
2. 发生冲突时：扩展命令会加上扩展前缀（如 /gcp.deploy）。

例如，当用户与 gcp 扩展都定义了 deploy：

• /deploy —— 执行用户的 deploy 命令。
• /gcp.deploy —— 执行扩展的 deploy 命令（帮助信息中带 [gcp] 标记）。

变量

Gemini CLI 扩展支持在 gemini-extension.json 中进行变量替换。例如当你需要当前目录来运行 MCP server 时，可使用 "cwd": "${extensionPath}${/}run.ts"。

支持的变量：