SpyBara
Go Premium

plugins/mods/overview.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 56 additions and 56 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Tue 6 23:59 Thu 8 22:58 Wed 14 22:58 Thu 15 23:58 Mon 19 23:58 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59

Mods 概覽

透過 mod 為 Claude Code 新增窗格、命令與工具呼叫規則。了解 mod 能做什麼、如何製作或安裝 mod，以及 mod 在何處執行。

mod 是一種會改變 Claude Code 外觀與行為的外掛。它由 JavaScript 或 TypeScript 事件處理常式組成：當事件發生時（例如工具呼叫、提交提示詞，或繪製介面的某個部分），Claude Code 會呼叫對應的處理常式，而處理常式可以監看該事件、變更它，或完全接管它。您可以使用 mod 為 Claude Code 新增自己的功能，例如一個在每次請求後以圖表呈現 context 使用量的窗格。如需了解 mod 中包含的檔案以及完整範例，請參閱 mod 的運作方式。

[!NOTE]

Claude Code 既有的 hooks 也會在事件發生時執行，其形式是您在設定檔中設定的 shell 命令、HTTP 請求或提示詞。相對地，mod 的處理常式則是在 Claude Code 內部執行的函式，而非上述形式。Claude Code 將這兩種都稱為 hook：在這些頁面中，「hook」指的是 mod 的處理常式，而設定檔中的那種則稱為「設定 hook」。

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 可以計算工具呼叫，而另一個在微調器旁邊顯示計數，或一個可以讀取每個請求的權杖使用量，而另一個在窗格中繪製它。請參閱對事件做出反應。

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

取得 mod

若要開始使用 mod：

安裝或更新 mod

[!WARNING]

Mod 是使用您的權限執行的程式碼。它可以讀取和寫入您的檔案、啟動程序和發出網路請求。僅從您信任的作者和市集安裝 mods。請參閱決定是否信任 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 啟動的程序則會在沙箱之外執行。

當工作階段使用受管設定，或以 Team 或 Enterprise /login 作為工作階段的憑證時，預設情況下，mod 的核准無法讓呼叫繞過您的 ask 規則或 PreToolUse hook。若兩者皆無，mod 可以核准 ask 規則會提示的呼叫，或您的 PreToolUse hook 阻止的呼叫。若要確認 mod 何時也能核准 deny 規則拒絕的呼叫，請參閱使用 hook 擴展權限。

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

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

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

claude plugin validate ./some-mod

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

開啟或關閉 mods

mod 預設為開啟。在終端機中，請使用 Claude Code v2.1.287 或更新版本。Desktop 應用程式內含自己的 Claude Code 副本，mod 從 v2.1.286 起即可在其中運作。請在您使用 mod 的地方檢查版本：

  • 終端機：在您的 shell 中執行 claude --version。如果您的版本較舊，請更新 Claude Code。
  • Desktop 應用程式：在 Code 標籤的本機工作階段中，輸入 /status 並查看 Claude Code 列，其中會顯示版本，例如 2.1.286。如果您的版本較舊，請更新 Desktop 應用程式。

若要關閉 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 是否可以載入。

[!NOTE]

如果您在早期存取期間設定了 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS，請移除它。Claude Code v2.1.287 及更新版本會忽略它，因此將其設定為 0 不會保持 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…。