---
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="/zh-Hant/docs/gemini-cli/official/04-agents-skills" />
  <Card title="MCP 設定" description="Extension 裡打包 MCP 時，仍要遵守 MCP 最小許可權。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
  <Card title="Security controls" description="安裝第三方 extension 前，繼續核對安全和企業控制。" href="/zh-Hant/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)
