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：

• 使用您已經擁有的：Claude Code 的某些功能是 mods，例如 /diff。請參閱內建於 Claude Code 的 Mods。
• 建立一個：在 Claude Code 工作階段中描述您想要的內容，Claude 會編寫 mod。請參閱向 Claude 要求 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 啟動的程序則會在沙箱之外執行。

Mod 可以核准您的 deny 或 ask 規則或 PreToolUse hook 原本會阻止的許多工具呼叫，除非內建防護加以阻止。載入防護後，預設情況下，使用者的 mod 無法這樣做。在本機終端機工作階段中，若 /plugin 的 Installed 分頁上出現 cc-plugin-sec-default，即表示防護已載入。

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

• plugin.json：外掛程式的清單
• hooks.json：指向您的程式碼檔案
• register.js：您的程式碼，稱為 hook 模組。它告訴 Claude Code 在哪些事件上執行您的函式。

這是一個完整的 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…。