---
title: "Extensions"
description: "Gemini CLI extensions：安装、启用、禁用、更新、link、本地开发、验证和与 MCP/Skills 的边界。"
verifiedAt: "2026-05-09"
---

Extensions 是 Gemini CLI 的扩展打包机制。官方 CLI cheatsheet 中列出 `gemini extensions` 的安装、卸载、列表、启用、禁用、更新、link、new、validate 等命令。

> [!WARNING]
> Extension 是分发容器，不是单纯 UI 插件。它可能带来 MCP server、hooks、commands、skills 和工具权限，安装前必须审查 manifest 和实际新增能力。

Extension 可以打包 prompts、MCP servers、custom commands、themes、hooks、sub-agents 和 agent skills。它不是单一功能，而是 Gemini CLI 侧的分发容器。

## 常用命令

常见动作包括安装、列表、启用、禁用、更新、link、本地新建和验证。对应命令是 `gemini extensions install <source>`、`gemini extensions list`、`gemini extensions enable <name>`、`gemini extensions disable <name>`、`gemini extensions update <name>`、`gemini extensions link <path>`、`gemini extensions new ./my-extension`、`gemini extensions validate ./my-extension`。

交互会话里也可以用 `/extensions list` 检查已安装 extension 和状态。开发本地 extension 时，用 `gemini extensions link .` 比反复安装更适合迭代。

## 和 MCP / Skills 的边界

| 能力 | 更像什么 |
| --- | --- |
| MCP | 接外部服务和工具 |
| Skills | 专门任务能力包 |
| Extensions | Gemini CLI 侧扩展分发和集成 |

## 安装建议

- 先确认来源可信。
- 先看它会启用哪些工具和权限。
- 团队环境统一版本。
- 不要为了“功能多”安装一堆不用的 extension。

| 检查项 | 要看什么 | 风险 |
| --- | --- | --- |
| 来源 | 官方、团队仓库、可信 Git ref | 供应链污染 |
| manifest | MCP、hooks、commands、skills | 隐藏能力 |
| 凭据 | 是否使用 sensitive / keychain | 密钥泄露 |
| 工具权限 | 是否 trusted 或自动批准 | 越权写入 |
| 版本 | 是否锁定版本或 commit | 更新后行为漂移 |

## 开发建议

复杂 extension 推荐 TypeScript，源码放 `src/`，构建产物放 `dist/`，根目录保留 `gemini-extension.json`。如果包含 MCP server，要给工具参数做输入校验，避免任意命令执行或越权访问文件系统。

需要 API key 的 extension，应使用 manifest 里的 `sensitive: true` 设置，让密钥进入系统 keychain，并在 CLI 输出中脱敏。不要把 key 写进 `GEMINI.md`、示例配置或 README。

## install 和 link 的分工

开发本地 extension 时用 `link`，发布给别人或团队固定版本时用 `install`。`link` 适合快速迭代，但它指向本地工作目录，容易带入未提交文件；`install` 更适合可复现环境，但要锁定来源和版本。

团队教程里应写清楚使用哪一种：开发者贡献 extension 用 `link`，普通用户安装稳定版用 `install`。不要让新手直接 link 一个未知目录。

## 安全边界

Extension 能打包很多能力，所以安装前要看 manifest、MCP server、hooks、commands 和 skills。特别关注这些点：

- 是否引入 `run_shell_command` 或本地 MCP server。
- 是否把高风险工具设置成 trusted。
- 是否包含 hooks，可能影响 CLI 行为。
- 是否要求宽泛文件系统或网络权限。
- 是否使用未锁定版本或未知 Git ref。

## 验收方式

安装后先运行 `gemini extensions list` 和 `/extensions list`，确认名称、版本、启用状态。再看 `/tools`、`/commands list`、`/skills list`，确认它实际带来的能力符合预期。卸载或禁用后再检查这些能力是否消失。

## 接下来去哪

<Cards>
  <Card title="Agents & Skills" description="工具与 MCP 完成后，继续看 agent skills、subagents 和远程 agent。" href="/docs/gemini-cli/official/04-agents-skills" />
  <Card title="MCP 设置" description="Extension 里打包 MCP 时，仍要遵守 MCP 最小权限。" href="/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
  <Card title="Security controls" description="安装第三方 extension 前，继续核对安全和企业控制。" href="/docs/gemini-cli/official/06-security-enterprise/63-enterprise-controls" />
</Cards>

## 官方来源

- [Gemini CLI extensions](https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/index.md)
- [Gemini CLI extension best practices](https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/best-practices.md)
