本页是 Gemini CLI 扩展系统的技术参考手册，覆盖所有 gemini extensions 子命令、gemini-extension.json manifest 每个字段的含义与示例、Settings 安全存储机制、变量替换规则，以及扩展如何贡献策略规则和自定义主题。开发者在发布扩展前应通读本页。

Extensions 完整参考

本页是 Gemini CLI 扩展系统的完整技术参考，适合扩展开发者阅读。如果你只是想安装使用扩展，参见扩展插件概览。

命令参考

注意：gemini extensions install 等管理命令不支持在 CLI 交互模式内运行。请在普通终端中使用。在交互模式中，可用 /extensions list 查看已安装扩展。所有管理操作（包括自定义命令更新）仅在重启 CLI 会话后生效。

安装扩展

bash

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

参数	说明
`<source>`	GitHub 仓库 URL 或本地路径
`--ref <ref>`	指定 git ref（分支、tag 或 commit）
`--auto-update`	启用自动更新
`--pre-release`	允许安装预发布版本
`--consent`	确认安全风险并跳过确认提示
`--skip-settings`	安装时跳过配置步骤

从 GitHub 安装需要本地已安装 git。Gemini CLI 会在安装时创建一份扩展副本，后续需运行 gemini extensions update 才能拉取源仓库的新变更。

卸载扩展

bash

gemini extensions uninstall <name...>

禁用扩展

扩展默认在全局范围启用。可以全局禁用，也可以只在某个工作区禁用：

bash

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

--scope 可选值：user（全局）或 workspace（当前工作区）。

启用扩展

bash

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

更新扩展

bash

gemini extensions update <name>   # 更新单个扩展
gemini extensions update --all     # 更新所有扩展

创建扩展模板

bash

gemini extensions new <path> [template]

内置模板：

mcp-server：包含 MCP 服务器示例的基础模板
context：提供 GEMINI.md 上下文的最小模板
custom-commands：包含自定义命令示例的模板

链接本地扩展（开发用）

bash

gemini extensions link <path>

link 命令在 Gemini CLI 扩展目录和你的开发目录之间创建符号链接，让你无需重新安装即可立即看到代码变更效果。重新构建项目后重启 CLI 会话即可测试。

配置扩展 Settings

bash

gemini extensions config <name> [setting] [--scope <scope>]

更新扩展的配置项（如 API Key），--scope 指定修改范围（user 或 workspace）。

`gemini-extension.json` 格式

每个扩展根目录下必须有一个 gemini-extension.json manifest 文件。

完整示例

json

{
  "name": "my-extension",
  "version": "1.0.0",
  "description": "My awesome extension",
  "contextFileName": "GEMINI.md",
  "excludeTools": ["run_shell_command(rm -rf)"],
  "migratedTo": "https://github.com/new-owner/new-extension-repo",
  "settings": [
    {
      "name": "API Key",
      "description": "Your API key for the service.",
      "envVar": "MY_API_KEY",
      "sensitive": true
    }
  ],
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["${extensionPath}/my-server.js"],
      "cwd": "${extensionPath}"
    }
  },
  "themes": [
    {
      "name": "my-theme",
      "type": "custom"
    }
  ],
  "plan": {
    "directory": ".gemini/plans"
  }
}

字段说明

字段	类型	必填	说明
`name`	string	是	扩展唯一标识，小写字母/数字/连字符，必须与扩展目录名一致
`version`	string	是	扩展版本号（建议遵循 SemVer）
`description`	string	否	简短描述，将显示在 geminicli.com/extensions 扩展库中
`contextFileName`	string	否	上下文文件名（默认 `GEMINI.md`）；若省略但目录存在 GEMINI.md，仍会自动加载
`excludeTools`	array	否	禁用的工具列表；支持命令级限制，如 `"run_shell_command(rm -rf *)"`
`migratedTo`	string	否	迁移目标仓库 URL；CLI 检测到后自动提示用户迁移安装源
`mcpServers`	object	否	MCP 服务器配置（格式与 settings.json 中的 `mcpServers` 相同，不支持 `trust` 字段）
`settings`	array	否	安装时向用户收集的配置项
`themes`	array	否	自定义主题定义
`plan`	object	否	Plan Mode 配置

`mcpServers` 注意事项

所有 settings.json 支持的 MCP 服务器配置均受支持，但不支持 trust 字段
当 extension 和 settings.json 定义了同名 MCP 服务器时，settings.json 优先
引用扩展目录内的文件时，使用 ${extensionPath} 变量确保可移植性
command 和 args 需分开填写，不要把可执行文件和参数混在 command 里

`plan` 对象

json

"plan": {
  "directory": ".gemini/plans"
}

directory：规划产物（Plan Mode 生成的文件）的存储目录。优先级低于用户自己在 settings 中指定的 plan 目录，高于 CLI 默认路径。

Extension Settings

Extension Settings 让扩展在安装时向用户收集 API Key、URL 等配置信息。

定义 Settings

在 manifest 的 settings 数组中添加：

json

"settings": [
  {
    "name": "API Key",
    "description": "Your API key for the service.",
    "envVar": "MY_API_KEY",
    "sensitive": true
  },
  {
    "name": "Service URL",
    "description": "Base URL of the target service.",
    "envVar": "MY_SERVICE_URL",
    "sensitive": false
  }
]

字段	类型	说明
`name`	string	设置项显示名
`description`	string	清晰解释该设置的用途
`envVar`	string	存储值的环境变量名，MCP 服务器进程启动时自动注入
`sensitive`	boolean	`true` 时值存入系统 Keychain 并在 UI 中脱敏显示

用户安装扩展时会被提示输入每个 Setting 的值。后续可用 gemini extensions config 更新。

扩展目录结构

一个功能完整的扩展可能包含以下目录：

text

my-extension/
├── gemini-extension.json      # manifest（必须）
├── GEMINI.md                  # 上下文文件（可选）
├── commands/                  # 自定义命令
│   ├── deploy.toml            # → /deploy
│   └── gcs/
│       └── sync.toml          # → /gcs:sync（命名空间）
├── skills/                    # Agent Skills
│   └── security-audit/
│       └── SKILL.md
├── agents/                    # Sub-agents（预览功能）
│   └── my-agent.md
├── hooks/                     # Hooks
│   └── hooks.json
├── policies/                  # Policy Engine 策略
│   └── policies.toml
├── src/                       # MCP 服务器源码
│   └── index.ts
└── dist/                      # 构建产物
    └── index.js

自定义命令命名规则

自定义命令 TOML 文件放在 commands/ 子目录，目录结构决定命令名：

commands/deploy.toml → /deploy
commands/gcs/sync.toml → /gcs:sync（冒号分隔命名空间）

命令优先级：用户命令 > 项目命令 > 扩展命令。若扩展命令与用户/项目命令冲突，扩展命令自动加扩展名前缀（如 /gcp.deploy，使用点号分隔）。

Hooks

在扩展根目录的 hooks/hooks.json 中定义 Hooks（注意：Hooks 不在 gemini-extension.json 中定义）。

详见 Hooks 系统。

Agent Skills

将 Skill 定义文件放在 skills/ 目录，例如 skills/security-audit/SKILL.md 暴露一个 security-audit Skill。

详见 Skills 工作流。

Policy Engine 集成

扩展可以为 Policy Engine 贡献策略规则和安全检查器。

在扩展根目录创建 policies/ 目录，将 .toml 策略文件放入其中，CLI 会自动加载该目录下所有 .toml 文件。

扩展贡献的规则运行在 tier 2（与工作区策略同级），优先级高于默认规则，低于用户和管理员策略。

toml

[[rule]]
mcpName = "my_server"
toolName = "dangerous_tool"
decision = "ask_user"
priority = 100

[[safety_checker]]
mcpName = "my_server"
toolName = "write_data"
priority = 200
[safety_checker.checker]
type = "in-process"
name = "allowed-path"
required_context = ["environment"]

安全限制：Gemini CLI 会忽略扩展策略中的 allow 决策和 yolo 模式配置。扩展无法自动批准工具调用或绕过安全确认机制。

自定义主题

在 gemini-extension.json 的 themes 数组中定义主题：

json

{
  "name": "my-green-extension",
  "version": "1.0.0",
  "themes": [
    {
      "name": "shades-of-green",
      "type": "custom",
      "background": {
        "primary": "#1a362a"
      },
      "text": {
        "primary": "#a6e3a1",
        "secondary": "#6e8e7a",
        "link": "#89e689"
      },
      "status": {
        "success": "#76c076",
        "warning": "#d9e689",
        "error": "#b34e4e"
      },
      "border": {
        "default": "#4a6c5a"
      },
      "ui": {
        "comment": "#6e8e7a"
      }
    }
  ]
}

主题激活方式：使用 /theme 命令，或在 settings.json 中设置 ui.theme。引用来自扩展的主题时，名称格式为 主题名 (扩展名)，例如 shades-of-green (my-green-extension)。

变量替换

gemini-extension.json 和 hooks/hooks.json 中支持以下变量：

变量	说明
`${extensionPath}`	扩展目录的绝对路径
`${workspacePath}`	当前工作区的绝对路径
`${/}`	平台专用路径分隔符（`/` 或 `\`）

跨平台路径示例：

json

"args": ["${extensionPath}${/}dist${/}index.js"]

配置加载优先级

Gemini CLI 启动时合并所有已加载扩展的配置。冲突时的优先级：

settings.json（用户/工作区）> 扩展配置

常见问题

Q: 修改了扩展文件，怎么让 CLI 生效？

A: 重启 Gemini CLI 会话。管理操作（安装、更新、自定义命令）都在会话启动时加载，运行中的会话不会动态热更新。

Q: 如何在本地调试扩展而不反复安装？

A: 运行 gemini extensions link <扩展目录路径>。Link 模式下，CLI 直接链接到你的开发目录，重新构建后重启会话即可看到变更。

Q: 扩展的 MCP 服务器能否共享用户已配置的 MCP 服务器？

A: 扩展和 settings.json 中可以定义同名 MCP 服务器，settings.json 中的定义优先级更高。两者同时存在时，只加载 settings.json 中的版本。

Extensions 完整参考 ​

命令参考 ​

安装扩展 ​

卸载扩展 ​

禁用扩展 ​

启用扩展 ​

更新扩展 ​

创建扩展模板 ​

链接本地扩展（开发用） ​

配置扩展 Settings ​

gemini-extension.json 格式 ​

完整示例 ​

字段说明 ​

mcpServers 注意事项 ​

plan 对象 ​

Extension Settings ​

定义 Settings ​

扩展目录结构 ​

自定义命令命名规则 ​

Hooks ​

Agent Skills ​

Policy Engine 集成 ​

自定义主题 ​

变量替换 ​

配置加载优先级 ​

常见问题 ​

Extensions 完整参考

命令参考

安装扩展

卸载扩展

禁用扩展

启用扩展

更新扩展

创建扩展模板

链接本地扩展（开发用）

配置扩展 Settings

`gemini-extension.json` 格式

完整示例

字段说明

`mcpServers` 注意事项

`plan` 对象

Extension Settings

定义 Settings

扩展目录结构

自定义命令命名规则

Hooks

Agent Skills

Policy Engine 集成

自定义主题

变量替换

配置加载优先级

常见问题