Claude Mod 是什麼？Claude Code Mods 完整教學：安裝、寫法、安全風險與和 hooks 的差別

Claude Mod（官方稱 Claude Code mods）是 Anthropic 在 2026 年 10 月 1 日隨 Claude Code v2.1.287 推出的客製化機制：用 JavaScript 或 TypeScript 寫事件處理器，直接載入 Claude Code 的執行程序。

它能畫自己的介面、重繪 Claude Code 原本的介面、攔下或改寫工具呼叫與提示，以及加入不發起模型回合的自訂指令。Claude Code 的 /diff 與 AGENTS.md 載入也已用 mod 實作。

mod 以你的使用者權限執行，不在沙箱裡，能讀寫檔案、讀取環境變數裡的金鑰、核准工具呼叫，以及使用你的模型額度。安裝第三方 mod 前，先用 claude plugin validate 查看它的事件與 API 呼叫，再審查來源與程式碼；通過驗證不代表安全。

Claude Code 是 Anthropic 的程式碼代理，會讀 codebase、改檔、跑指令與測試；基本操作可參考站上的 Claude Code 完整實測教學。2026 年 10 月 1 日，Anthropic 的開發者帳號 @ClaudeDevs 在 X 宣布 Mods，Claude Code v2.1.287 的版本說明也加入了這項功能；官方 npm 套件紀錄顯示該版本在同日（UTC）發布。Mods 在 v2.1.287 以上預設開啟，能否載入仍受啟動旗標與組織政策控制。

Mods 讓開發者能改動 Claude Code 的行為與畫面。過去常見的客製化方式是寫規則檔、提供提示或接入工具；現在也能用程式碼處理工具呼叫、模型請求與介面繪製。以下依 2026 年 10 月 5 日的官方文件整理，參考文件目前對應 v2.1.289。

先試官方範例：用 token-weather 顯示 context window

已經能執行 Claude Code 的讀者，可先用官方範例看懂 mod 的效果。以下指令在終端機執行；先確認版本不低於 v2.1.287，再取得範例、查看事件與 API 清單，最後載入單次 session：

claude --version
git clone https://github.com/anthropics/claude-code-playground.git
cd claude-code-playground/claude-code/mods
claude plugin validate ./token-weather
claude --plugin-dir ./token-weather

token-weather 會在輸入框上方顯示 context window 的概況。在 Claude Code 裡執行 /plugin，分頁下方的「mods active」列可確認是否載入；它不包含內建 mod。這個流程依 官方範例 README，只載入本次 session。若組織禁止 --plugin-dir，需改用組織允許的安裝方式。

Claude Mod 是什麼：跑在 Claude Code 內部的客製化程式碼

官方文件使用 Claude Code mods；本文簡稱 Claude Mod。依 官方定義，mod 是一種 plugin（外掛），本體是一或多個 JavaScript 或 TypeScript 事件處理器：Claude Code 在事件發生時呼叫你的函式，例如 Claude 要使用工具、使用者送出提示，或介面元件準備繪製時。函式可以觀察事件、改寫內容，也可以直接回傳結果，接手原本的行為。

要理解 mod 改變了什麼，得先看 Claude Code 這類工具的結構。AI 代理的外層是一個所謂的 harness：負責送提示給模型、執行模型要求的工具、把結果貼回對話、畫出終端機介面。harness 決定了代理「長什麼樣、怎麼做事」。在 Mods 出現之前，你對 harness 的客製化全都發生在外面：settings 裡的 hooks 是把事件丟給外部腳本處理，CLAUDE.md 是塞文字給模型讀，MCP 是從外面遞工具進來。mod 則是把你的程式碼載入 Claude Code 的執行程序裡，站在事件與 harness 行為之間，官方文件用了一個很精確的比喻：這些處理器形成一條中介層（middleware）鏈。

名詞上有一個容易混淆的地方要先講：Claude Code 原本就有 hooks 機制（在 settings.json 裡設定的 shell 指令、HTTP 請求或提示）。官方文件現在把兩種都叫 hook，mod 裡的叫函式 hook，settings 檔裡的叫 settings hook。本文為了清楚，講到 hook 時指 mod 的處理器，講傳統機制時會明寫 settings hook。

官方的宣布本身就是最好的摘要，三行講完能力範圍：改變行為、自訂介面、換上你自己的功能。

官方提供兩種建立方式：依教學手寫免建置的 mod，或在 Claude Code 裡描述需求，讓內建的 plugin-authoring 技能協助產生。

一個 mod 能做到的五件事，連內建功能都改用 mod 實作

官方文件將 mod 的能力歸納成五個面向。

第一，畫出你自己的介面。mod 可以在對話記錄旁邊開一個 pane，或在輸入框上方加一條橫幅，裡面放分頁、按鈕、文字輸入框。官方的例子是一個圖表 pane，每次請求結束就畫出 context 還剩多少空間。第二，重繪 Claude Code 本來的介面：工具呼叫那一行、轉圈的 spinner、Claude 問問題的對話框，mod 都可以換掉或重新上樣式。這是「從外面圍繞」的機制永遠碰不到的一層。

第三，處理工具呼叫與模型請求。mod 可以把工具呼叫暫停、先詢問使用者再放行，可以不執行工具直接回傳結果，也可以把模型請求改送到另一個模型。第四，自訂指令：/command 可以直接執行函式，不發起 Claude 回合；註冊時加上 immediate: true，才能在 Claude 忙碌時執行。第五，共享狀態：同一個 mod 的處理器可以使用檔案裡的共同變數，讓一個 hook 計數、另一個 hook 把數字畫在 spinner 旁邊。

官方在 claude-code-playground 儲存庫放了三個完整範例，很適合拿來理解這五件事的落地長相：token-weather 在輸入框上方畫 context window 的「天氣預報」；blast-radius 會攔下 rm -rf 或強制 push 這類危險指令，先展示它會改到哪些檔案，再給你執行或取消的按鈕；replay-theater 加一個 /replay 指令，逐步重播 Claude 上一回合改過的檔案。倉庫明說這些範例依現狀提供、不附支援，但它們是免費可讀的完整實作。

Claude Code 自己的功能也用 mod 實作。在 /plugin 的 Installed 分頁可找到 Built-in 清單：cc-plugin-diff 接管 /diff 並繪製差異 pane，cc-plugin-agents-md 負責 AGENTS.md 的載入，cc-plugin-you-should-know 則是背景代理，會在較長任務中提醒可能漏看的資訊。You should know 預設關閉，是否列出也取決於組織可用性。內建 mod 不能更新或解除安裝，各有停用方式；停用 diff mod 後，/diff 仍由 Claude Code 自己的版本回答。部分完整源碼與測試公開在 官方 mods 目錄。

Claude Code 負責人 Boris Cherny 在發布當天的說法，把這個設計意圖講得很白：每個人的工作方式不同，沒有理由每個人用到的 Claude 長得一樣。

跟 hooks、skills、MCP、CLAUDE.md 怎麼分工

Mods 不是憑空出現的第五種機制，它是 Claude Code 既有客製化版圖上的一塊新拼圖，而且官方文件明說：如果 settings hook、skill 或 MCP server 已經能做你要的事，先比一比再決定要不要寫 mod。四者的分工可以用一張表看清楚。

	Mod	Settings hook	Skill	MCP server
本質	跑在 Claude Code 程式內的事件處理函式	settings 檔裡設定的 shell 指令、HTTP 請求或提示	一份給 Claude 讀的 SKILL.md 指令文件	把工具遞給 Claude 的外部程序
能改變什麼	工具呼叫、提示、指令、回合與介面繪製	工具呼叫或提示的放行與否、參數與結果、附加 context	Claude 知道與做到的事	Claude 手上有哪些工具
能不能畫介面	可以	不能	不能	不能
用什麼寫	JavaScript 或 TypeScript	一支腳本加一條設定	Markdown	任何語言的伺服器
適用時機	想要面板、橫幅、自訂指令，或想改寫事件本身	想用現成腳本擋下、放行或記錄事件	常常重複貼同一段指示給 Claude	要讓 Claude 連上外部系統

幾個界線值得單獨點出。傳統的 hooks 在事件發生時把資料丟給你指定的 shell 指令或 HTTP 端點，本質是外部程序，所以拿不到介面，也難做需要持續狀態的東西；mod 的處理器就住在 Claude Code 裡，天然共享記憶體與繪圖能力。Skills 和 CLAUDE.md 這份規則檔改變的是「Claude 讀到什麼」，成本最低，但管不到 Claude Code 自己的行為與畫面；MCP 給 Claude 新工具，工具要不要被核准、結果怎麼顯示，仍然由 harness 決定。mod 是四者中唯一能三者同時碰的：讀到的提示、執行的工具、畫出來的介面。

反過來說，大多數需求其實不需要 mod。要 Claude 遵守團隊規範，規則檔就夠；要接資料庫或內部 API，MCP 是正解；要在送出前擋一下危險指令，一支 settings hook 腳本十分鐘搞定。mod 的合理出場時機是：你想改的東西涉及 Claude Code 本身的行為或介面，而且願意承擔維護一支小程式的成本。兩者也可以共存，官方明言一個 plugin 可以同時裝著 mod、skill 與 MCP server。

開發者 Thariq 在發布當天補了一個更縱觀的註腳：軟體正在變得可塑，Claude Code 把可擴充性當成一級公民來支援。

取得與安裝：marketplace、官方目錄與單次載入

mod 以 plugin 形式發布。從 marketplace（市集）安裝前，要先加入該市集，例如在 shell 執行 claude plugin marketplace add your-org/your-marketplace；這裡的 owner/repo 與外掛名稱都是示意值，需換成作者提供的來源。加入後，在 Claude Code session 跑 /plugin install token-chart@your-org，或在 shell 跑 claude plugin install token-chart@your-org。如果 session 已開著，從 shell 安裝或更新後，還要在 session 裡跑 /reload-plugins；否則下次啟動才載入。

市集本身是 JSON 目錄檔，放在 git 儲存庫裡就能使用，團隊也可以用成員能存取的私有 repo。Anthropic 另維護收錄 plugins 與 connectors 的目錄，在 claude.ai 或 Cowork 加入後，Claude Code 可透過帳號同步載入，名稱會是外掛名加 @synced；公開的 Claude Marketplace 也可瀏覽收錄項目。想送進目錄，依 官方發布說明，需從 claude.ai/directory/manage 提交。提交者須有付費的 claude.ai 方案：Pro、Max 可由本人送出，Team、Enterprise 由 Owner 送出，Enterprise 也可授予其他成員 Directory 權限。Anthropic 的 claude-plugins-official marketplace 是另一個發布管道，不透過這個目錄入口送件。

不經市集也能載入：claude --plugin-dir ./some-mod 載入一個目錄供單次 session 使用，改檔會熱重載；claude --plugin-url 可指向 zip。要長期使用官方樣本，在 clone 的 claude-code/mods 目錄執行 claude plugin marketplace add ./，再執行 claude plugin install token-weather@claude-code-playground-mods --scope user。這個市集指向本機 clone，移動或刪除該目錄會使 mod 無法載入。

自己寫一個 mod：三個檔案就能跑，不必裝 Node.js

官方 建立 mod 的教學開宗明義：不需要 Node.js、不需要打包器、不需要建置步驟，Claude Code 直接載入 .js 與 .ts 檔。最小的 mod 只有三個檔案：

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

先建立 first-mod/.claude-plugin/plugin.json，提供名稱與版本：

{
  "name": "first-mod",
  "version": "0.1.0",
  "description": "Counts tool calls and adds a tally command"
}

接著建立 first-mod/hooks/hooks.json。modules 陣列指向的路徑相對於 hooks.json；這個欄位讓 Claude Code 將外掛當成 mod 載入：

{
  "description": "The first-mod hooks module",
  "modules": ["./register.js"]
}

register.js 是本體，官方教學的完整範例做四件事：session 開始時註冊一個 /tally 指令、每次工具呼叫加一、spinner 重畫時把計數畫在後面、使用者打 /tally 時印出總數。程式碼依官方範例精簡如下：

let calls = 0

export function register(on) {
  on('session.start', async ($, e, next) => {
    await $.command.register({
      name: 'tally',
      description: 'Show how many tool calls Claude has made',
    })
    return next(e)
  })

  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.invalidate('ui.render')
    return next(e)
  })

  on('command.run', { command: 'tally' }, async () => {
    return { text: 'Claude has made ' + calls + ' tool calls' }
  })

  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls } })
  })
}

用 claude --plugin-dir ./first-mod 啟動就生效，改檔存檔會自動重載。不寫程式也有一條等價路徑：在 session 裡用自然語言描述「幫我做一個在輸入框上方顯示目前 git branch 的 mod」，Claude 會透過內建的 plugin-authoring 技能（也可用 /plugin-authoring 手動載入）把 mod 寫進 ~/.claude/dev-mods/ 下面屬於該 session 的資料夾，第一個檔案存下時 Claude Code 會問你要不要為這個 session 開啟熱重載，核准後才載入。這條路有明確的邊界：Claude 寫的 mod 只在寫它的 session 裡載入，資料夾過了清理期會被刪掉；要留下來就把目錄搬到自己的位置，用 --plugin-dir 載入或送進市集。

開發時可先跑 claude plugin validate ./first-mod。它會檢查 manifest 並靜態分析 mod，不執行程式碼就列出處理的事件與 API 呼叫（hooks: 與 calls: 行）；事件名拼錯會報錯。claude plugin test 則執行你另外建立的 .test.ts 測試檔，不需要 session、登入或網路；上面的三檔範例還沒有測試檔，可依官方測試教學加入。每次用 --plugin-dir 載入或重載時，Claude Code 會在 .claude-plugin/types/ 寫出對應版本的 TypeScript 宣告檔。事件與 API 可能隨版本變動，文件與型別衝突時，以本機版本產生的型別為準。

事件模型：觀察、改寫、接手，與中介層的順序

mod 的一切圍繞事件。每個 hook 收到三個參數：$ 是 mods API（畫圖、下指令、呼叫模型、讀寫檔案的唯一通道），e 是事件資料（深度凍結，改不了，只能傳副本），next 則把事件交給鏈上的下一個處理器，鏈的終點是 Claude Code 自己的行為。對 next 的用法決定了你的 hook 是哪一種：呼叫 next(e) 原樣放行是觀察；帶著改過的副本呼叫 next 是改寫；不呼叫 next、直接回傳結果是接手，後面的 mod 與官方行為都不會發生。

第二個參數可以放 matcher 過濾器，值可以是單一值、陣列或正規表示式：{ tool: ‘Bash’ } 只攔 Bash，{ tool: [‘Edit’, ‘Write’] } 攔兩種，{ tool: /^mcp__github__/ } 攔某個 MCP server 的全部工具。事件家族依 官方事件文件大致分六組：工具組（tool.call、tool.check、tool.describe）、提示組（prompt.submit 到系統提示的每個 section）、回合組（turn.start、turn.step、turn.complete）、session 組（start、end、compact、跨 session 訊息）、介面組（ui.render 到按鈕按下）與其他 mod 的載入事件；傳統 settings hook 的事件也以 classic. 前綴映射進來，例如 classic.Stop。

hook 想做任何超出自身程式碼的事，都必須透過 $ 上的 mods API，沒有第二條路，這是官方文件明載的設計。API 依命名空間組織：$.ui 管畫圖與互動，$.command 與 $.tool 註冊指令和工具，$.model 呼叫模型，$.fs 讀寫檔案，$.store 是跨 session 共用的鍵值儲存，$.http 與 $.process 負責網路與程序，$.mcp 連 MCP server，$.clock 提供計時器。這個約束帶來一個容易被忽略的漂亮性質：每一個 API 呼叫本身也是事件。掛在 fs.read 上的 hook 可以攔到後面其他 mod 的檔案讀取，掛在 model.complete 上的可以審核別的 mod 呼叫了哪個模型。

tool.call 可以暫停工具呼叫，再用 $.ui.ask 詢問使用者。以下依官方事件教學示範，以正規表示式比對 rm -r、rm -rf、git reset --hard 與 git push --force，命中時提供「執行或拒絕」的選項；問題被關閉或無法顯示時，預設拒絕。這個 pattern 會漏掉 git push -f 等其他寫法，用來理解事件處理，不是完整的指令安全檢查：

const RISKY = /\brm\s+-rf?\b|\bgit\s+reset\s+--hard\b|\bgit\s+push\b.*--force/

export function register(on) {
  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
    if (!RISKY.test(e.command)) return next(e)
    let answer = 'Refuse'
    try {
      answer = await $.ui.ask('Run this command? ' + e.command, ['Run it', 'Refuse'])
    } catch {
      // nobody answered the question
    }
    if (answer !== 'Run it') {
      return { deny: 'The user declined this command.' }
    }
    return next(e)
  })
}

tool.check 更靠底層：它在權限規則與 settings hook 做完決定之後觸發，你的 hook 可以讀到決定並改寫成 allow、ask 或 deny，官方例子是「目前分支是 main 就拒絕 git push」。turn.step 是串流事件，寫成產生器可以邊串流邊轉發，也能 next({ …e, model }) 把請求改送別的模型，或讀出每次請求的 token 用量與快取命中數。prompt.submit 能改寫你送出的提示原文、附加只有 Claude 讀得到的 context，或整個擋下不送。

繪圖這一側同樣有清楚的解剖圖。ui.render 事件在每個「繪圖點位」要畫的時候觸發，點位清單裡除了 mod 自己開的 Pane 與輸入框上方的 AbovePrompt，也包括 Claude Code 本來就在畫的東西：使用者訊息列、助理訊息、工具呼叫與結果的每一行、spinner、問答對話框、提示輸入框下的暗色提示。hook 拿到 $ 後用元素組出畫面樹，元素從 Box、Text、Button、Input、Select、Markdown、程式碼區塊，到桌面應用程式才支援的 Svg 向量圖，以及終端機才支援的 Raster 點陣格與 Image 圖片。同一份 mod 程式碼可以判斷自己跑在哪個應用裡，在畫不了圖的環境退回文字輸出，這是為什麼「處理器到處都跑、繪圖限縮」不會讓 mod 壞掉。

多個 mod 的順序依來源決定：有載入的 sec-default 守衛與組織 prependPlugins 先執行，接著是使用者安裝的 mod、組織 appendPlugins，最後才是其他內建 mod。管理者在 managed settings 設定的 PreToolUse hook 更早執行，被它阻擋的呼叫不會進入 mod；mod 若改寫呼叫，managed hook 也會重新檢查。失敗處理需另外設計：hook 在呼叫 next 之前拋錯或逾時、又沒有 .catch 時，Claude Code 會跳過它並交給下一個處理器；若 next 已完成，則保留原結果。用來阻擋指令的 hook 可依官方失敗處理範例加上 .catch，失敗時回傳 deny，避免檢查失效後繼續執行。

執行上也有硬限制，依 v2.1.289 參考文件：單一 hook 自身執行上限通常為 10 秒，不計 next 與大部分 mods API 呼叫的等待時間，但 $.clock.sleep 仍計入；prompt.edit hook 則只有 50 毫秒。$.process.run 預設 30 秒、最多 10 分鐘；$.model.complete 預設最多輸出 1024 token，可設至 64,000 或模型本身的輸出上限。檔案讀寫單檔 4 MiB，$.store 總量 4 MiB。介面重繪一般每秒節流 10 次，終端機特定可見區域可到 30 次。

執行環境與方案：版本門檻、各入口支援度、怎麼關掉

mods 需要 Claude Code v2.1.287 以上，且預設開啟，claude --version 一查就知道。曾在早期存取期間設過 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS 環境變數的人要注意：2.1.287 之後這個變數被忽略，設成 0 擋不住 mods，該從設定裡移除。

「能不能用」要拆成兩個問題：事件處理器跑不跑，以及畫出來的介面顯不顯示。處理器在所有會載入外掛的 session 都會跑；繪圖只在終端機與桌面應用程式顯示。依官方文件整理成對照表：

執行環境	事件處理器會跑	畫的介面會出現
終端機的 claude（含編輯器內建終端機、JetBrains 外掛）	會	會
Claude 桌面應用程式的 Code 分頁	會	會，終端機專屬元素除外
桌面應用程式的 WSL session	不會（外掛不載入）	不會
VS Code 擴充功能的聊天面板	會	不會
claude -p 與 Agent SDK	會	不會
Remote Control（從 claude.ai 或手機連回本機）	會，在本機 session	本機終端機上
雲端 session	有觸及的 plugin 會	不會

單一 mod 可在 /plugin 的 Installed 分頁停用或解除安裝。排查某次 session 時可用 claude --safe-mode 啟動，停用已安裝的 mod，包含組織管理的 mod。若在自己的 ~/.claude/settings.json 設 "disableAllHooks": true，會停掉自己的 mod、settings hook、自訂狀態列與 /goal，但組織管理的 mod 仍會執行；相同設定若由 managed settings 下達，範圍更大。這些開關不停止內建 mod，內建項目各有停用方式，sec-default 守衛不能由使用者關閉。

官方文件未另列 Mods 的加價項目或獨立方案資格，仍需具備可使用 Claude Code 的帳號，並符合版本與載入政策。Pro、Max 與 API 的費用依原有方式計算；mod 若呼叫模型，使用的是你的方案額度或 API key。提交 Anthropic 目錄所需的付費 claude.ai 帳號是作者的送件條件，與使用者載入 mod 是兩件事。

安全模型：mod 以你的權限執行，安裝前要看的清單

官方文件在安裝段落的開頭放了整份文件裡語氣最重的一段警告，值得逐條展開。mod 載入之後能做的事包括：以你的身分讀寫你帳號碰得到的任何檔案、啟動程序、發網路請求；讀走環境變數與設定檔，包括放在裡面的 API 金鑰；看到你送出的每個提示與 Claude 的每個工具呼叫；改寫提示或工具呼叫、以你的名義送出提示、傳訊息給你的其他 session；在你被詢問之前先核准工具呼叫；用你的方案或 API key 呼叫模型。mods 不在沙箱裡，就算開了 Claude Code 的 sandboxing，它隔離的也只是 Claude 跑的 Bash 指令，mod 自己起的程序在沙箱外。

tool.check 的 mod 可以把 ask 規則要求詢問的呼叫改成 allow，也能放行使用者自己的 PreToolUse hook 所阻擋的呼叫，因此權限模式與 settings.json 規則不等於 mod 的沙箱。deny 的保護有條件：官方管理文件指出，sec-default 守衛有載入時，使用者 mod 預設不能核准 deny 規則拒絕的工具呼叫；管理者仍可透過 allowModsToOverrideDenyRules 放寬。這個守衛會在有 managed settings 的機器，或登入 Team、Enterprise 的 session 載入。mod 不能改繪權限提示，但可以在提示出現前直接核准呼叫，所以使用者不一定會看到詢問框。

deny 規則與 managed PreToolUse 的保護針對 Claude 的工具呼叫，不會套用到 mod 自己的 $.fs 或 $.process API。即使規則拒絕 Read(.env)，mod 仍可能用 $.fs.read 或自己啟動的程序讀取檔案；要限制這些行為，需要拒絕載入該 mod，或由組織政策 mod 檢查它的 API 呼叫。

安裝第三方 mod 前，先選擇可信任的作者與市集，再取得外掛目錄，執行 claude plugin validate ./some-mod。hooks: 行列出事件，calls: 行列出 API 呼叫，例如 $.http.fetch 表示可發出網路請求，$.env.get 表示可讀取環境變數；env reads:、env writes:、state reads:、state writes: 則列出相關項目。這個檢查不執行 mod，能幫你決定哪些程式碼要詳讀，尤其是 tool.call、tool.check、檔案、程序與網路呼叫。它檢查的是結構與能力，不能判定作者是否可信或保證行為無害。

靜態分析要求特定寫法：事件名需用字串字面量，不能把 $ 或它的命名空間存入其他變數；import 只能指向 plugin 目錄內的相對路徑，唯一允許的裸 import 是 claude-code；檔案需使用 ES module，register 裡也不能重新宣告名為 on 的變數。動態 import 等分析器無法接受的寫法會驗證失敗。這些限制讓 Claude Code 能列出已知事件與 API 呼叫；即使清單很短，一個 $.process.run 仍可啟動權限很大的程序，不能只靠清單長短判斷安全。

團隊可透過 managed settings 管理載入來源與順序。allowManagedModsOnly 是 sec-default 守衛的 option，需放在 pluginConfigs 的 cc-plugin-sec-default@builtin 之下，不能只在 settings 頂層加同名欄位。prependPlugins 排在使用者 mod 之前，appendPlugins 排在之後；管理者自訂 prependPlugins 時，需要把 sec-default@builtin 保留在清單裡，才會繼續載入守衛。官方也提供公開的 sec-default 源碼，組織可參考它，用 plugin.register 審查其他 mod 的事件與 API 能力。

截至 2026 年 10 月 5 日的版本與社群範例

npm 紀錄顯示 v2.1.287、v2.1.288、v2.1.289 分別在 10 月 1、2、3 日（UTC）發布；截至 10 月 5 日，latest 為 v2.1.289，stable 標籤仍為 v2.1.285。因此只更新到 stable 的使用者，仍應執行 claude --version 確認是否達到 Mods 門檻。版本說明列出多項 Mods 修正，包括 ui.render 值不合法造成的介面錯誤、按鈕動作不一致，以及升級後首次 session 未載入 mod。事件與 API 可能持續調整，作者應在 README 註明測試版本，並以本機產生的型別宣告檔為準。

官方樣本之外，也已有開發者分享自己的實作。Anshu 在發布當天展示自訂 spinner：觀察主代理的工作，再以 Sonnet 5.5 畫出即時小卡通。這是開發者分享的案例，並非內建功能或官方效能測試。

實作時可先試本文開頭的 token-weather，再讀 blast-radius 的攔截與按鈕程式碼，最後寫自己的計數器 mod。先跑 validate，加入測試檔後再跑 test，逐步確認事件與回傳結果；第三方 mod 則從來源可追溯、程式碼可讀的開始。如果團隊正在比較 Claude Code 與 Codex 的工作流程，也可將介面與行為的客製化需求列入評估。

要分享自己的 mod，除了確認功能，也要記錄適用版本與需要的 API 權限。更新到新版本後，重新檢查型別宣告與測試結果，尤其是會核准工具呼叫的 mod。

常見問題

Claude Mod 和 Claude Code 的 hooks 有什麼不同？

兩者都在事件發生時被呼叫，差別在程式碼住在哪裡。Settings hook 是你在 settings.json 設定的 shell 指令、HTTP 請求或提示，事件發生時把資料丟給外部程序處理；mod 的處理器是 JavaScript 或 TypeScript 函式，直接載入 Claude Code 的執行程序裡。所以 mod 能畫介面、共享記憶體狀態、攔下事件後代答，settings hook 做不到這些，但比較輕量、適合用現成腳本擋或記錄事件。

Claude Mod 需要額外付費嗎？哪些方案可以用？

官方文件未另列 Mods 額外費用或獨立方案資格。需要可使用 Claude Code 的帳號、v2.1.287 以上版本，以及允許載入 mod 的設定。mod 呼叫模型會使用你的方案額度或 API key；付費 claude.ai 方案則是作者提交 Anthropic 目錄的條件。

不會寫 TypeScript，也能用或寫 mod 嗎？

可以。官方的設計路徑是「用自然語言描述、叫 Claude 幫你寫」：在 session 裡說出你要的功能，Claude 會用內建的 plugin-authoring 技能把 mod 寫好，放在該 session 專屬的資料夾，經你核准熱重載後生效。不過 Claude 寫的 mod 只在那個 session 載入，過了清理期會被刪掉，想長期用要把目錄搬出來自己收好。

第三方的 Claude Mod 安全嗎？安裝前可以怎麼檢查？

mod 以你的權限執行，不在沙箱裡，能讀寫檔案、讀取環境變數、發出網路請求與核准工具呼叫。取得外掛檔案後，先跑 claude plugin validate ./some-mod，查看 hooks:、calls: 與環境變數讀寫清單，再閱讀相關程式碼。驗證不執行 mod，也不保證它安全，仍需確認作者與來源可信。

Claude Mod 在 VS Code、雲端或手機上也能用嗎？

事件處理器與繪圖要分開看。VS Code 聊天面板、claude -p 與 Agent SDK 會執行已載入 plugin 的 mod 處理器；雲端 session 則需該 plugin 已同步或以支援方式載入，但這些入口不顯示 mod 的介面。終端機與桌面應用程式的 Code 分頁支援繪圖，桌面 WSL session 除外，部分元素也只限終端機。Remote Control 的處理器在本機 session 執行，畫面出現在本機終端機。

怎麼把 Claude Mod 關掉或解除安裝？

單一 mod 可在 /plugin 的 Installed 分頁停用或解除安裝。claude --safe-mode 可在單次 session 停用已安裝的 mod，包括組織管理的 mod；在自己的 ~/.claude/settings.json 設 "disableAllHooks": true 則停用自己的 mod、settings hook、自訂狀態列與 /goal，組織管理的 mod 仍執行。內建 mod 各有停用方式，sec-default 守衛不能由使用者關閉。

Mod 和 MCP server 差在哪？什麼時候該用哪個？

MCP server 是外部程序，功能是給 Claude 新工具（連資料庫、查內部 API 這類），工具要不要核准、結果怎麼顯示仍由 Claude Code 決定；mod 跑在 Claude Code 內部，能改的是行為與介面本身，包括攔工具呼叫、改提示、畫面板。要接外部系統選 MCP，要改 Claude Code 自己的樣子與規則才選 mod，兩者可以裝在同一個 plugin 裡共存。

Mod 可以改變 Claude 讀到的提示或換模型嗎？

可以。prompt.submit 能改寫使用者提示、加上只有 Claude 讀取的 context，或阻擋送出；turn.step 能改送另一個模型並讀取 token 用量與快取資訊；prompt.section 則處理系統提示的各個 section。有組織 sec-default 守衛時，使用者 mod 不能改動受保護的系統提示與管理者指令。

寫 Claude Mod 需要 Node.js 或打包工具嗎？

都不用。官方文件明說 Claude Code 直接載入 .js 與 .ts 檔，不需要 Node.js、打包器或建置步驟，最小的 mod 只有 plugin.json、hooks.json 與一支 register.js 三個檔案。用 claude --plugin-dir ./first-mod 載入後存檔還會自動重載，開發迴圈很短。

Mod 可以繞過 Claude Code 的權限規則嗎？

部分可以。tool.check 能核准 ask 規則要求詢問的呼叫，也能放行使用者自己的 PreToolUse hook 阻擋的呼叫。sec-default 守衛有載入時，deny 規則預設優先，除非管理者明確放寬；managed PreToolUse 的阻擋是最終決定。但這些限制針對 Claude 的工具呼叫，不是 mod 自己的 $.fs 或 $.process。mod 也可在權限提示出現前核准呼叫。

現在投入 Claude Mod 值得嗎？API 會不會一直變？

可以先用官方樣本理解事件與介面，再寫小工具自用。Mods 在 2026 年 10 月 1 日推出，官方明說事件與 API 可能隨版本變動；應以本機版本產生的型別宣告檔為準，並在 README 註明測試版本。若 mod 會核准工具呼叫，升級後尤其需要重新驗證行為。

Claude Mod 和 CLAUDE.md、skills 有什麼不一樣？

層級不同。CLAUDE.md 與 skills 改變的是 Claude 讀到什麼：一份是自動載入的專案規則檔，一份是按需展開的指令文件，成本最低但不能碰 Claude Code 的行為與畫面。mod 是程式碼，直接改工具呼叫、提示、指令與介面繪製。要 Claude 遵守規範用前者就夠，要改變 Claude Code 本身的做事方式與長相，才輪到 mod。