SpyBara
Go Premium

plugins/mods/overview.md 2026-10-01 23:59 UTC to 2026-10-02 15:01 UTC

This page contains 55 additions and 35 deletions.

2026
Thu 1 23:59 Fri 2 16:01

Mods 概述

使用 mod 為 Claude Code 新增窗格、命令和工具呼叫規則。了解 mod 的功能、如何建立或安裝 mod，以及 mod 的執行位置。

Mod 是一個外掛程式，可改變 Claude Code 的外觀和行為。它由 JavaScript 或 TypeScript 事件處理程式組成：Claude Code 在事件發生時呼叫一個，例如工具呼叫、已提交的提示或介面的一部分被繪製，處理程式可以監視事件、變更事件或接管事件。使用 mod 為 Claude Code 新增您自己的功能，例如在每個請求後繪製您的內容有多滿的窗格。如需 mod 中的檔案和完整範例，請參閱Mod 的運作方式。

Mod 可以做什麼

設定 hooks、skills、狀態行和 MCP 伺服器從 Claude Code 外部運作：每一個都執行指令碼，或為 Claude 提供文字或工具。Mod 在 Claude Code 內執行，因此它可以做他們無法做的事情：

  • 繪製您可以使用的介面：文字記錄旁邊的窗格或提示上方的帶狀區域，具有標籤、按鈕和文字欄位。請參閱在介面中繪製。
  • 重新繪製 Claude Code 自己的介面：取代或重新設定 Claude Code 自己繪製的部分，例如工具呼叫的列、微調器或 Claude 提出問題的對話框。請參閱變更 Claude Code 已繪製的內容。
  • 進入工具呼叫或請求：例如，在您詢問使用者問題時保留工具呼叫、在不執行工具的情況下回答，或將一個請求傳送到不同的模型。請參閱保護或變更工具呼叫和跟隨一個回合。
  • 在命令上執行您自己的程式碼：一個 /command，立即執行您的函式，沒有 Claude 回合，即使 Claude 正在工作。請參閱新增命令或工具。
  • 在 hooks 之間共享資料：mod 的 hooks 共享其檔案中的變數，因此一個 hook 記錄的內容，另一個可以顯示。例如，一個 hook 可以計算工具呼叫，而另一個在微調器旁邊顯示計數，或一個可以讀取每個請求的權杖使用量，而另一個在窗格中繪製它。請參閱對事件做出反應。

Mods 在 Claude Code CLI 和 Claude Desktop 應用程式的 Code 標籤中運作。請參閱Mods 執行的位置以了解它們在其他地方的行為，例如在 VS Code 擴充功能、claude -p 和雲端工作階段中。如果設定 hook、skill 或 MCP 伺服器已經做了您需要的事情，在您編寫 mod 之前比較它們。若要為組織管理 mods，請參閱為您的組織管理 mods。

取得 mod

若要開始使用 mod：

安裝或更新 mod

Mod 作為外掛程式從市集安裝。提供外掛程式的名稱、@ 和市集的名稱。這些範例從名為 your-org 的市集安裝名為 token-chart 的外掛程式：

  • 在 Claude Code 工作階段中，執行 /plugin install token-chart@your-org。
  • 在您的 shell 中，執行 claude plugin install token-chart@your-org。

安裝外掛程式涵蓋市集、範圍、VS Code 擴充功能和 Desktop 應用程式，以及保持外掛程式更新，所有這些都適用於包含 mod 的外掛程式，無需變更。

如果您在工作階段開啟時從 shell 安裝或更新 mod，請在該工作階段中執行 /reload-plugins 以載入它。否則，它會在您下次啟動 Claude Code 時載入。

試用範例 mod

Anthropic 在 claude-code-playground 儲存庫的 claude-code/mods 目錄中分享範例 mods。每一個都是完整的外掛程式，其 README 說明了它的建構方式。該儲存庫按原樣分享這些範例，不提供支援。

  • token-weather：在提示詞上方繪製您上下文視窗的預報
  • blast-radius：暫停有風險的 shell 命令（例如 rm -rf 或強制推送），並顯示它會變更的內容，附有繼續或取消的按鈕
  • replay-theater：新增 /replay 命令，逐步檢視 Claude 在上一個回合中所做的檔案編輯

範例 mod 會使用您的權限執行。若要在載入之前了解它的作用，請列出它的 hook 和呼叫。

若要試用，請複製該儲存庫，並使用 --plugin-dir 在單一工作階段中載入 mod 的目錄。若要確認 mod 已載入，請檢查工作階段載入了哪些 mods。

若要保留它，請將複製的 claude-code/mods 目錄新增為市集，然後從 claude-code-playground-mods 安裝該 mod。該市集指向您的複製，因此如果您移動或刪除它，mod 就會停止載入。

決定是否信任 mod

Mod 是使用您的權限在 Claude Code 內執行的程式碼。僅從您信任的作者和市集安裝 mods。

Mod 可以存取什麼

Mod 使用您的權限執行，因此在您安裝一個之前，請了解它可以存取什麼。載入後，mod 可以：

  • 在您的機器上以您的身份行動：讀取和寫入您的使用者帳戶可以存取的任何地方的檔案、啟動程式和發出網路請求
  • 讀取您的機密：環境變數和設定檔，包括您保留在任一個中的 API 金鑰
  • 查看您的工作階段：您傳送的每個提示詞和 Claude 進行的每個工具呼叫
  • 變更您的工作階段：重寫提示詞或工具呼叫、提交提示詞，就像您輸入的一樣，或傳送訊息到您的另一個工作階段
  • 在不詢問您的情況下行動：在詢問您之前核准工具呼叫
  • 花費您的使用量：在您的計畫或 API 金鑰上呼叫模型

Mods 不在沙箱中執行。如果您開啟沙箱機制，沙箱會隔離 Claude 執行的 Bash 命令，而 mod 啟動的程序則會在沙箱之外執行。

核准工具呼叫的 mod 可以核准 ask 規則會提示的呼叫，或您自己的 PreToolUse hook 阻止的呼叫。使用 hook 擴展權限列出此類 mod 可以核准的內容，包括何時可以核准 deny 規則拒絕的呼叫。

Mod 可以重新設定 Claude Code 介面的大部分，但不能重新設定權限提示。它無法變更提示顯示給您的內容。

在安裝 mod 之前列出它的功能

在您安裝 mod 之前，您可以列出它處理的事件以及它要求 Claude Code 執行的操作，例如讀取檔案或發出網路請求，而無需執行它。首先取得外掛程式的檔案，例如透過複製其儲存庫。然後，在您的 shell 中，在外掛程式的目錄上執行 claude plugin validate：

claude plugin validate ./some-mod

輸出中的 hooks: 和 calls: 行列出 mod 處理的事件以及它要求 Claude Code 執行的操作。檢查 mod 可以做什麼顯示輸出以及要查找的呼叫。

開啟或關閉 mods

Mods 需要 Claude Code v2.1.287 或更新版本，預設情況下它們是開啟的。在您的 shell 中，執行 claude --version 以檢查，如果您的版本較舊，請更新 Claude Code。

若要關閉 mods，請選擇要停止多少個，以及停止多長時間。若要將它們重新開啟，請撤銷相同的變更：

  • 一個 mod：從/plugin 中的已安裝標籤停用或解除安裝其外掛程式
  • 每個已安裝的 mod，一個工作階段：使用 --safe-mode 啟動 Claude Code，這也會停用您的其他自訂
  • 您安裝的每個 mod，在每個工作階段中：在 ~/.claude/settings.json 中設定 "disableAllHooks": true。您的設定 hook 和自訂狀態列也會停止。您的組織管理的內容會繼續執行。

如果您透過組織使用 Claude Code，管理員也可以限制哪些 mods 載入。管理員從停止使用者安裝的 mods 載入開始。

disableAllHooks 和您組織的 allowManagedModsOnly 會停止 mod，並保留其外掛的其餘部分：外掛會維持安裝狀態，其 skill、命令、agent 和 MCP 伺服器都會載入。其他設定和旗標的影響範圍更廣。disableAllHooks 和在 allowManagedHooksOnly 下執行的內容列出了每一項對外掛及其設定 hook 的影響。

若要了解 mods 是否可以為您載入，請參閱檢查 mods 是否可以載入。

查看工作階段載入了哪些 mods

若要查看終端機工作階段載入了哪些 mods，請在 Claude Code 提示處執行 /plugin。標籤下的暗行提供計數和名稱，例如 1 mod active · first-mod。如果您安裝的 mod 未在那裡命名，請參閱找出為什麼 mod 不執行任何操作。

Mod 的運作方式

Mod 是一個外掛程式，其程式碼註冊事件處理程式，稱為 hook。Claude Code 在其事件發生時執行 hook，例如當 Claude 呼叫工具或繪製微調器時。一個小 mod 有三個檔案：

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

這是一個完整的 register.js。它計算 Claude 進行的工具呼叫，並在 Claude 工作時在微調器旁邊顯示計數，如 Thinking · tool calls: 3…。

// The count, shared by the two hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs each time Claude is about to use a tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Ask Claude Code to draw the interface again, so the new count shows
    $.ui.invalidate('ui.render')
    // Let the tool run as usual
    return next(e)
  })

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

該檔案註冊了兩個 hook，兩者都使用頂部的 calls 變數：

  • tool.call hook 在 Claude 即將使用工具時執行。它將 calls 加一，要求 Claude Code 再次繪製介面，並讓工具照常執行。
  • ui.render hook 在 Claude Code 繪製微調器時執行。它保留 Claude Code 自己的微調器，並在單詞後面新增計數。

此錄影顯示 mod 的運作。觀看提示詞輸入框上方的微調器行：當 Claude 列出目錄並讀取兩個檔案時，它顯示 Thinking · tool calls: 1…，然後 2…，然後 3…。