Canonical: https://seo.whoops.com.tw/claude-mod/
Author: Sliven 褚崇名
Source robots: follow, index, max-snippet:-1, max-video-preview:-1, max-image-preview:large
Content modified (WordPress): 2026-11-09T04:14:13+00:00
Representation modified (content/template/converter): 2026-11-12T06:48:56+00:00

# 最佳 Claude Mod 完整教學：安裝、寫法與 hooks 差異

 

圖片：Claude Mod 完整教學精選圖，展示外掛安裝、事件中介層、自訂介面與程式碼審查（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/claude-mod-code-customization-featured.webp）

 

撰文作者 

[Sliven 褚崇名](<https://seo.whoops.com.tw/about/#founder-title>)

 

Whoops SEO 創辦人

 

SEO 與 AI SEO 專家，專長涵蓋技術 SEO、內容策略與 GEO 優化。從搜尋排名到 AI 答案中的品牌呈現，協助企業找出優化機會、排定執行順序，並追蹤實際成效。

 

圖片：Sliven 褚崇名肖像（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/sliven-portrait-navy.webp）

 

[作者背景與專業領域](<https://seo.whoops.com.tw/about/#founder-title>) 更新 2026-11-09 約 22 分鐘閱讀

 

本篇內容

 

### 本篇內容

 

## 先看重點

摘自本文

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

[跟 hooks、skills、MCP、CLAUDE.md 怎麼分工](<https://seo.whoops.com.tw/claude-mod/#%E8%B7%9F-hooks%E3%80%81skills%E3%80%81MCP%E3%80%81CLAUDE.md-%E6%80%8E%E9%BA%BC%E5%88%86%E5%B7%A5>)
- 傳統的 hooks 在事件發生時把資料丟給你指定的 shell 指令或 HTTP 端點，本質是外部程序，所以拿不到介面，也難做需要持續狀態的東西；mod 的處理器就住在 Claude Code 裡，天然共享記憶體與繪圖能力。

[跟 hooks、skills、MCP、CLAUDE.md 怎麼分工](<https://seo.whoops.com.tw/claude-mod/#%E8%B7%9F-hooks%E3%80%81skills%E3%80%81MCP%E3%80%81CLAUDE.md-%E6%80%8E%E9%BA%BC%E5%88%86%E5%B7%A5>)
- deny 的保護有條件：官方管理文件指出，sec-default 守衛有載入時，使用者 mod 預設不能核准 deny 規則拒絕的工具呼叫；管理者仍可透過 allowModsToOverrideDenyRules 放寬。

[安全模型：mod 以你的權限執行，安裝前要看的清單](<https://seo.whoops.com.tw/claude-mod/#%E5%AE%89%E5%85%A8%E6%A8%A1%E5%9E%8B%EF%BC%9Amod-%E4%BB%A5%E4%BD%A0%E7%9A%84%E6%AC%8A%E9%99%90%E5%9F%B7%E8%A1%8C%EF%BC%8C%E5%AE%89%E8%A3%9D%E5%89%8D%E8%A6%81%E7%9C%8B%E7%9A%84%E6%B8%85%E5%96%AE>)

 

### 檢查網站的 SEO 基礎

從網站網址開始，檢視可讀性與頁面基礎訊號。

- 檢查標題與搜尋摘要標記
- 核對 canonical 與索引指令
- 整理公開 HTML 的待改善項目

[免費檢查網站](<https://seo.whoops.com.tw/free-seo-audit/>)

 

[將 Whoops 設為 Google 偏好來源（另開 Google 設定頁）](<https://www.google.com/preferences/source?q=seo.whoops.com.tw>)

 

> 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 Mod 是什麼？Claude Code 改裝介面、工具流程與權限限制｜3 分鐘看懂](<https://seo.whoops.com.tw/videos/youtube-krjr_xg4lho-5ee625dfe5/>)

 

Claude Code 是 Anthropic 的程式碼代理，會讀 codebase、改檔、跑指令與測試；基本操作可參考站上的 [Claude Code 完整實測教學](<https://seo.whoops.com.tw/claude-code/>)。2026 年 10 月 1 日，Anthropic 的開發者帳號 @ClaudeDevs 在 X 宣布 Mods，Claude Code [v2.1.287 的版本說明](<https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md>)也加入了這項功能；[官方 npm 套件紀錄](<https://registry.npmjs.org/@anthropic-ai/claude-code>)顯示該版本在同日（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](<https://github.com/anthropics/claude-code-playground/blob/main/claude-code/mods/README.md>)，只載入本次 session。若組織禁止 `` --plugin-dir ``，需改用組織允許的安裝方式。

 

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

 

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

 

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

 

圖片：Claude Code 容器內的事件經過 JavaScript／TypeScript Mod，再交給工具執行與介面繪製（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/claude-mod-harness-event-middleware.webp）

Mod 直接載入 Claude Code 的執行程序，站在事件與 harness 行為之間，能觀察、改寫或接手事件。

 

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

 

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

 

> You can now mod Claude Code:
> 
> – Change how it behaves
> – Customize the UI
> – Swap in your own features
> 
> Write one with a few lines of TypeScript, or have Claude build it for you. Mods ship inside plugins, so you install them with /plugin in the CLI or desktop app.
> 
> A few examples: [pic.twitter.com/qMtzV8AeId](<https://t.co/qMtzV8AeId>)
> 
> — ClaudeDevs (@ClaudeDevs) [October 1, 2026](<https://x.com/ClaudeDevs/status/2105721434807083061?ref_src=twsrc%5Etfw>)

 

官方提供兩種建立方式：依教學手寫免建置的 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 Mod 的五種能力：自訂介面、重繪介面、攔改請求、自訂指令與共享狀態（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/claude-mod-five-capabilities.webp）

Mods 的範圍涵蓋介面、工具與模型請求、指令和記憶體內狀態，可依客製化需求撰寫對應的事件處理器。

 

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

 

圖片：Anthropic 官方 claude-code-playground 的 mods 目錄，顯示 blast-radius、replay-theater 與 token-weather 三個範例（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/claude-mod-official-playground-examples.webp）

Anthropic 官方 playground 收錄 blast-radius、replay-theater、token-weather 三個 mod 範例（擷取於 2026 年 10 月 5 日）。

 

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

 

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

 

> Mods are absolutely insane. You can now customize Claude to work and look the way you want by just prompting it.
> 
> Each person works differently, so there's no reason why everyone should have an identical Claude experience. Make Claude your own, and share mods as plugins so others… [https://t.co/FxQ8ggZ0uK](<https://t.co/FxQ8ggZ0uK>)
> 
> — Boris Cherny (@bcherny) [October 1, 2026](<https://x.com/bcherny/status/2105756563302723721?ref_src=twsrc%5Etfw>)

 

## 跟 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](<https://code.claude.com/docs/en/hooks>) 在事件發生時把資料丟給你指定的 shell 指令或 HTTP 端點，本質是外部程序，所以拿不到介面，也難做需要持續狀態的東西；mod 的處理器就住在 Claude Code 裡，天然共享記憶體與繪圖能力。[Skills](<https://code.claude.com/docs/en/skills>) 和 [CLAUDE.md 這份規則檔](<https://seo.whoops.com.tw/claude-md/>)改變的是「Claude 讀到什麼」，成本最低，但管不到 Claude Code 自己的行為與畫面；MCP 給 Claude 新工具，工具要不要被核准、結果怎麼顯示，仍然由 harness 決定。mod 是四者中唯一能三者同時碰的：讀到的提示、執行的工具、畫出來的介面。

 

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

 

圖片：Claude Code 四類客製化入口的分工：CLAUDE.md 與 Skills 提供指示，Settings hook 處理外部事件腳本，MCP 連工具，Mod 改行為與介面（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/claude-mod-hooks-skills-mcp-comparison.webp）

CLAUDE.md 與 skills 提供指示，MCP 接入工具，settings hook 交給外部處理；需要改 Claude Code 本身的行為或介面時，再考慮 mod。

 

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

 

> all software is becoming malleable, so it was important for us to support this as a first class citizen in Claude Code, I hope more and more software becomes extensible like this! 
> 
> here are some of what I'm most excited about with mods: [https://t.co/WuyqpGvIn8](<https://t.co/WuyqpGvIn8>)
> 
> — Thariq (@trq212) [October 1, 2026](<https://x.com/trq212/status/2105734197801562264?ref_src=twsrc%5Etfw>)

 

## 取得與安裝：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 的目錄](<https://claude.ai/directory/>)，在 claude.ai 或 [Cowork](<https://seo.whoops.com.tw/claude-cowork/>) 加入後，Claude Code 可透過帳號同步載入，名稱會是外掛名加 @synced；公開的 [Claude Marketplace](<https://claude.com/marketplace>) 也可瀏覽收錄項目。想送進目錄，依 [官方發布說明](<https://code.claude.com/docs/en/plugins/publish>)，需從 claude.ai/directory/manage 提交。提交者須有付費的 claude.ai 方案：Pro、Max 可由本人送出，Team、Enterprise 由 Owner 送出，Enterprise 也可授予其他成員 Directory 權限。Anthropic 的 claude-plugins-official marketplace 是另一個發布管道，不透過這個目錄入口送件。

 

圖片：Claude Code Docs 的 Publish and distribute a plugin 頁面，顯示官方發布途徑說明（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/claude-mod-official-plugin-publishing.webp）

Claude Code 官方文件說明直接分享外掛、自架 marketplace 與提交 Anthropic 目錄三種發布途徑（擷取於 2026 年 10 月 5 日）。

 

不經市集也能載入：`` 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 無法載入。

 

圖片：Claude Mod 安裝流程：選擇外掛來源、安裝、重新載入，最後在 plugin 清單確認（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/claude-mod-plugin-install-reload.webp）

從 shell 安裝外掛後，已開啟的 session 要重新載入；最後回到 /plugin 確認 mod 是否已啟用。

 

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

 

官方 [建立 mod 的教學](<https://code.claude.com/docs/en/plugins/mods/create>)開宗明義：不需要 Node.js、不需要打包器、不需要建置步驟，Claude Code 直接載入 .js 與 .ts 檔。最小的 mod 只有三個檔案：

 

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

 

圖片：最小 Claude Mod 的三個檔案：plugin.json、hooks.json 與 register.js（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/claude-mod-three-files-development-loop.webp）

plugin.json 描述外掛，hooks.json 指向事件模組，register.js 實作處理器；Claude Code 可直接載入 JS／TS，不需建置。

 

先建立 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、登入或網路；上面的三檔範例還沒有測試檔，可依[官方測試教學](<https://code.claude.com/docs/en/plugins/mods/test>)加入。每次用 `` --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 的全部工具。事件家族依 [官方事件文件](<https://code.claude.com/docs/en/plugins/mods/events>)大致分六組：工具組（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 可依[官方失敗處理範例](<https://code.claude.com/docs/en/plugins/mods/events#handle-a-hook-that-fails>)加上 .catch，失敗時回傳 deny，避免檢查失效後繼續執行。

 

執行上也有硬限制，依 [v2.1.289 參考文件](<https://code.claude.com/docs/en/plugins/mods/reference>)：單一 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 桌面應用程式](<https://seo.whoops.com.tw/claude-desktop/>)的 Code 分頁 | 會 | 會，終端機專屬元素除外 |
| 桌面應用程式的 WSL session | 不會（外掛不載入） | 不會 |
| VS Code 擴充功能的聊天面板 | 會 | 不會 |
| `` claude -p `` 與 Agent SDK | 會 | 不會 |
| Remote Control（從 claude.ai 或手機連回本機） | 會，在本機 session | 本機終端機上 |
| 雲端 session | 有觸及的 plugin 會 | 不會 |

 

圖片：終端機與桌面 Code 可執行 Mod 並顯示介面，其他部分入口僅執行事件處理器（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/claude-mod-runtime-ui-support.webp）

事件處理器會跑，不代表 mod 的面板會出現。入口的載入條件仍以官方文件與你的版本為準。

 

單一 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 的費用](<https://seo.whoops.com.tw/claude-code-pricing/>)依原有方式計算；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 規則](<https://seo.whoops.com.tw/claude-code-permissions-plan-mode/>)不等於 mod 的沙箱。deny 的保護有條件：[官方管理文件](<https://code.claude.com/docs/en/plugins/mods/admin>)指出，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、檔案、程序與網路呼叫。它檢查的是結構與能力，不能判定作者是否可信或保證行為無害。

 

圖片：Claude Mod 以使用者權限存取檔案與金鑰、工具核准和模型額度，安裝前需要審查（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/claude-mod-security-review-user-permissions.webp）

mod 不在沙箱裡。先確認來源、執行靜態驗證並閱讀源碼；通過 validate 只能幫助檢查能力，不能保證安全。

 

靜態分析要求特定寫法：事件名需用字串字面量，不能把 $ 或它的命名空間存入其他變數；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 門檻。[版本說明](<https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md>)列出多項 Mods 修正，包括 ui.render 值不合法造成的介面錯誤、按鈕動作不一致，以及升級後首次 session 未載入 mod。事件與 API 可能持續調整，作者應在 README 註明測試版本，並以本機產生的型別宣告檔為準。

 

官方樣本之外，也已有開發者分享自己的實作。Anshu 在發布當天展示自訂 spinner：觀察主代理的工作，再以 [Sonnet 5.5](<https://seo.whoops.com.tw/claude-sonnet-5-5/>) 畫出即時小卡通。這是開發者分享的案例，並非內建功能或官方效能測試。

 

> wait actually Claude Code mods are sick. I vibe-coded my own spinner that watches what the main agent is doing and uses Sonnet 5.5 to turn it into little cartoons in real time [https://t.co/AlTwTpX0Y1](<https://t.co/AlTwTpX0Y1>) [pic.twitter.com/pJy6udAYPa](<https://t.co/pJy6udAYPa>)
> 
> — Anshu (@anshuc) [October 1, 2026](<https://x.com/anshuc/status/2105773281936650247?ref_src=twsrc%5Etfw>)

 

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

 

要分享自己的 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。

 

[AI 寫程式](<https://seo.whoops.com.tw/tag/ai-coding/>)[AI 工具](<https://seo.whoops.com.tw/tag/ai-%e5%b7%a5%e5%85%b7/>)[Anthropic](<https://seo.whoops.com.tw/tag/anthropic/>)[Claude](<https://seo.whoops.com.tw/tag/claude/>)[Claude Code](<https://seo.whoops.com.tw/tag/claude-code/>)[Claude Mod](<https://seo.whoops.com.tw/tag/claude-mod/>)

 

喜歡這篇內容？讓下次搜尋，更容易遇見 Whoops。

[將 Whoops 設為 Google 偏好來源（另開 Google 設定頁）](<https://www.google.com/preferences/source?q=seo.whoops.com.tw>)前往 Google 選取並確認，即可完成設定。

 

[## Sliven 褚崇名](<https://seo.whoops.com.tw/about/#founder-title>)

Sliven 褚崇名是 Whoops SEO 創辦人，負責技術 SEO、內容與關鍵字策略、WordPress 網站重建，以及 AI SEO、AEO、GEO 的量測與內容優化。作者頁可查閱由他署名的〈SEO 是什麼〉與〈AI SEO 是什麼〉等教學；內容中的自有量測、模型觀測與第三方來源應分開判讀，並以各頁標示的方法與限制為準。是否適合特定專案，仍需依網站現況、目標、執行範圍與可驗證成果判斷。

[查看作者文章 →](<https://seo.whoops.com.tw/about/#founder-title>)

 

## 討論與提問

 

### 發佈留言

 

WHOOPS / JOURNAL

## 更多值得一讀的文章

[探索知識庫 ↗](<https://seo.whoops.com.tw/blog/>)

[AI 工具與應用約 23 分鐘閱讀

### 最佳 CLAUDE.md 完整教學：位置、寫法與規則排查

CLAUDE.md 是 Claude Code 保存專案規則的 Markdown 檔案。整理檔案位置與載入順序、CLAUDE.local.md、AGENTS.md 支援、auto memory、@ 匯入與路徑規則，附三個可修改範例及規則未生效的排查方式。

閱讀文章](<https://seo.whoops.com.tw/what-is-claude-md/>) [AI 工具與應用約 39 分鐘閱讀

### 最佳 DeepSeek Harness 完整教學：安裝、插件與比較

DeepSeek Harness（dsh）把模型、工具、工作階段與沙箱組成可執行任務的 AI 代理。本文以桌面版與本機 Web UI 畫面，說明安裝、API key、CSV 報告、排程、插件與費用，並解析和 Claude Code、Codex 的整合方式。

閱讀文章](<https://seo.whoops.com.tw/deepseek-harness/>) [AI 工具與應用約 46 分鐘閱讀

### 最佳 Claude 完整教學：怎麼用、費用與 ChatGPT 比較

Claude 是 Anthropic 的 AI 助理。這篇中文教學整理官方登入、Claude 怎麼用、Free／Pro／Max／Team／Enterprise 費用、模型、Projects、Artifacts、Cowork、Claude Code，以及和 ChatGPT 的差異。

閱讀文章](<https://seo.whoops.com.tw/claude-ai-tutorial/>)
