Gemini CLI 扩展

本文档与 v0.4.0 版本同步更新。

Gemini CLI 扩展将提示、MCP 服务器和自定义命令打包成熟悉且用户友好的格式。通过扩展，你可以扩展 Gemini CLI 的功能并与他人共享这些功能。它们被设计为易于安装和共享。

要查看扩展示例，你可以浏览 Gemini CLI 扩展库。

参见入门文档获取创建第一个扩展的指南。

参见发布文档获取设置 GitHub 发布的高级指南。

扩展管理

我们提供一套使用 gemini extensions 命令的扩展管理工具。

请注意，这些命令不支持在 CLI 内部使用，但你可以使用 /extensions list 子命令列出已安装的扩展。

请注意，所有这些命令只会在重启后反映在活动的 CLI 会话中。

安装扩展

你可以使用 gemini extensions install 通过 GitHub URL 或本地路径安装扩展。

请注意，我们会创建已安装扩展的副本，因此你需要运行 gemini extensions update 来从本地定义的扩展和 GitHub 上的扩展拉取更改。

注意：如果你从 GitHub 安装扩展，你需要在机器上安装 git。参见 git 安装说明获取帮助。

gemini extensions install <source> [--ref <ref>] [--auto-update] [--pre-release] [--consent]

<source>：要安装的扩展的 GitHub URL 或本地路径。
--ref：要安装的 git ref。
--auto-update：为此扩展启用自动更新。
--pre-release：为此扩展启用预发布版本。
--consent：确认安装扩展的安全风险并跳过确认提示。

卸载扩展

要卸载一个或多个扩展，运行 gemini extensions uninstall <name...>：

gemini extensions uninstall gemini-cli-security gemini-cli-another-extension

禁用扩展

扩展默认在所有工作区启用。你可以完全禁用扩展或针对特定工作区禁用。

gemini extensions disable <name> [--scope <scope>]

<name>：要禁用的扩展名称。
--scope：禁用扩展的范围（user 或 workspace）。

启用扩展

你可以使用 gemini extensions enable <name> 启用扩展。你也可以在该工作区内使用 gemini extensions enable <name> --scope=workspace 为特定工作区启用扩展。

gemini extensions enable <name> [--scope <scope>]

<name>：要启用的扩展名称。
--scope：启用扩展的范围（user 或 workspace）。

更新扩展

对于从本地路径或 git 仓库安装的扩展，你可以使用 gemini extensions update <name> 显式更新到最新版本（如 gemini-extension.json 的 version 字段所示）。

你可以使用以下命令更新所有扩展：

gemini extensions update --all

创建样板扩展

我们提供几个示例扩展：context、custom-commands、exclude-tools 和 mcp-server。你可以在这里查看这些示例。

要使用你选择的类型将这些示例之一复制到开发目录，运行：

gemini extensions new <path> [template]

<path>：创建扩展的路径。
[template]：要使用的样板模板。

链接本地扩展

gemini extensions link 命令将从扩展安装目录创建到开发路径的符号链接。

这很有用，这样你就不必每次想要测试更改时都运行 gemini extensions update。

gemini extensions link <path>

<path>：要链接的扩展路径。

工作原理

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

扩展作为包含 gemini-extension.json 文件的目录存在。例如：

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

`gemini-extension.json`

gemini-extension.json 文件包含扩展的配置。文件具有以下结构：

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 服务器到设置的映射。键是服务器的名称，值是服务器配置。这些服务器将在启动时加载，就像在 settings.json 文件中设置的 MCP 服务器一样。如果扩展和 settings.json 文件都设置了同名的 MCP 服务器，则 settings.json 文件中定义的服务器优先。
- 请注意，除了 trust 之外，所有 MCP 服务器配置选项都受支持。
contextFileName：包含扩展上下文的文件名。这将用于从扩展目录加载上下文。如果未使用此属性但扩展目录中存在 GEMINI.md 文件，则将加载该文件。
excludeTools：要从模型中排除的工具名称数组。你还可以为支持它的工具指定命令特定的限制，如 run_shell_command 工具。例如，"excludeTools": ["run_shell_command(rm -rf)"] 将阻止 rm -rf 命令。请注意，这与 MCP 服务器的 excludeTools 功能不同，后者可以在 MCP 服务器配置中列出。

当 Gemini CLI 启动时，它会加载所有扩展并合并它们的配置。如果有任何冲突，工作区配置优先。

设置

注意：这是一个实验性功能。我们目前不建议扩展作者将设置作为其核心流程的一部分引入。

扩展可以定义用户在安装时会被提示提供的设置。这对于 API 密钥、URL 或扩展运行所需的其他配置很有用。

要定义设置，在你的 gemini-extension.json 文件中添加一个 settings 数组。数组中的每个对象应具有以下属性：

name：设置的用户友好名称。
description：设置的描述及其用途。
envVar：设置将存储为的环境变量名称。
sensitive：可选布尔值。如果为 true，则混淆用户提供的输入并将密钥存储在钥匙串存储中。

示例

json

{
  "name": "my-api-extension",
  "version": "1.0.0",
  "settings": [
    {
      "name": "API Key",
      "description": "你的服务 API 密钥。",
      "envVar": "MY_API_KEY"
    }
  ]
}

当用户安装此扩展时，他们将被提示输入 API 密钥。该值将保存到扩展目录中的 .env 文件（例如 <home>/.gemini/extensions/my-api-extension/.env）。

你可以通过运行以下命令查看扩展设置列表：

gemini extensions settings list <extension name>

你可以使用以下命令更新给定设置：

gemini extensions settings set <extension name> <setting name> [--scope <scope>]

--scope：设置设置的范围（user 或 workspace）。这是可选的，默认为 user。

自定义命令

扩展可以通过在扩展目录内的 commands/ 子目录中放置 TOML 文件来提供自定义命令。这些命令遵循与用户和项目自定义命令相同的格式，并使用标准命名约定。

示例

名为 gcp 的扩展具有以下结构：

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

将提供这些命令：

/deploy - 在帮助中显示为 [gcp] 来自 deploy.toml 的自定义命令
/gcs:sync - 在帮助中显示为 [gcp] 来自 sync.toml 的自定义命令

冲突解决

扩展命令具有最低优先级。当与用户或项目命令发生冲突时：

无冲突：扩展命令使用其自然名称（例如 /deploy）
有冲突：扩展命令使用扩展前缀重命名（例如 /gcp.deploy）

例如，如果用户和 gcp 扩展都定义了 deploy 命令：

/deploy - 执行用户的 deploy 命令
/gcp.deploy - 执行扩展的 deploy 命令（标记为 [gcp] 标签）

变量

Gemini CLI 扩展允许在 gemini-extension.json 中进行变量替换。如果你需要当前目录来使用 "cwd": "${extensionPath}${/}run.ts" 运行 MCP 服务器，这会很有用。

支持的变量：

变量	描述
`${extensionPath}`	用户文件系统中扩展的完全限定路径，例如 '/Users/username/.gemini/extensions/example-extension'。这不会解包符号链接。
`${workspacePath}`	当前工作区的完全限定路径。
`${/}` 或 `${pathSeparator}`	路径分隔符（因操作系统而异）。

Gemini CLI 扩展 ​

扩展管理 ​

安装扩展 ​

卸载扩展 ​

禁用扩展 ​

启用扩展 ​

更新扩展 ​

创建样板扩展 ​

链接本地扩展 ​

工作原理 ​

gemini-extension.json ​

设置 ​

自定义命令 ​

冲突解决 ​

变量 ​