安裝外掛

Plugin 是 OpenCode 的執行時擴充套件。它不是提示詞，也不是 Agent 角色，而是在 OpenCode 執行過程中監聽事件、注入環境、修改工具呼叫、傳送通知、寫日誌，或者新增自定義工具。

先給結論：大多數新手暫時不需要外掛

Plugin 站得很底層。它能改變 OpenCode 的執行過程，所以不要把它當成“高階提示詞”使用。

先按這個順序判斷：

Plugin 在擴充套件層裡的位置

OpenCode 的擴充套件不是一層東西。把層級分清，後面才不會越配越亂。

flowchart TB
  Rules[Rules / AGENTS.md<br/>專案長期約束]
  Agent[Agents<br/>角色和許可權邊界]
  Skill[Skills<br/>可複用流程說明]
  Tool[Custom tools / MCP<br/>模型可呼叫能力]
  Plugin[Plugins<br/>執行時事件和行為擴充套件]

  Rules --> Agent
  Agent --> Skill
  Agent --> Tool
  Plugin -.監聽和改變.-> Tool
  Plugin -.注入或記錄.-> Agent

一句話判斷：如果你只是想讓模型“知道怎麼做”，不要寫外掛；如果你要在 OpenCode 執行時“發生某事時自動做某事”，才考慮外掛。

外掛放在哪裡

OpenCode 支援本地外掛和 npm 外掛。

專案級外掛隻影響當前儲存庫，更適合試錯。全域性外掛會影響所有 OpenCode 會話，除非它已經很穩定，否則不要預設放全域性。

npm 外掛什麼時候用

如果社群已有成熟外掛，可以在配置裡引用 npm 包：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-wakatime"]
}

OpenCode 會在啟動時用 Bun（一個比 Node.js 快得多的 JavaScript 執行時和包管理器，OpenCode 內部用它跑外掛程式碼）自動安裝 npm 外掛，並把依賴快取到本機。使用前至少檢查三件事：

• 外掛原始碼做了什麼，有沒有讀寫檔案、執行 shell、上傳資料。
• 外掛是否仍在維護，是否和當前 OpenCode 版本匹配。
• 是否真的需要全域性啟用，還是隻在某個專案啟用。

載入順序怎麼理解

OpenCode 會從多個來源載入外掛，並按順序執行 hooks。官方載入順序是：

如果同名同版本的 npm 包重複出現，只會載入一次；本地外掛和 npm 外掛即使名字相近，也會分別載入。

先寫一個只記錄日誌的最小外掛

第一個外掛不要攔截工具，也不要改 shell 環境。先驗證它能被載入，並能寫結構化日誌。

檔案：.opencode/plugins/audit-events.ts

export const AuditEventsPlugin = async ({ client }) => {
  await client.app.log({
    body: {
      service: "audit-events",
      level: "info",
      message: "Plugin loaded",
    },
  })

  return {}
}

這類外掛失敗時影響面小，適合作為“外掛鏈路是否正常”的第一步。

事件怎麼選

你不需要背完整事件表。先按風險選擇：

選事件前先問一句：我是觀察發生了什麼，還是要改變它？觀察型外掛風險低；攔截和修改型外掛要有測試儲存庫和停用方案。

依賴怎麼管理

本地外掛需要第三方 npm 包時，在配置目錄放 package.json。OpenCode 啟動時會執行 bun install。

{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

依賴越多，啟動、快取和排障成本越高。外掛依賴只放真正必要的包；如果只是幾行字串處理，不要引入新依賴。

外掛和 Custom Tool 的關係

Plugin 也可以新增 custom tool。這個能力很強，但也更容易誤用。

適合：

• 工具需要和外掛上下文繫結。
• 工具要配合事件監聽、日誌或許可權邏輯。
• 團隊希望用外掛包統一分發工具。

不適合：

• 只是封裝一個簡單專案命令。
• 只是讓模型多一個 API 呼叫入口。
• 沒有測試引數 schema 和錯誤輸出。

安全寫法

外掛可以影響 OpenCode 行為，所以預設按高風險擴充套件處理：

• 不在外掛裡硬編碼 API Key。
• 不把完整環境變數寫進日誌。
• 攔截 bash 時，不拼接未經校驗的命令。
• 只在確實必要時修改工具引數。
• 外掛出錯時返回清楚錯誤，不靜默吞掉。
• 給每個外掛保留停用路徑，例如移出目錄或清空配置裡的 plugin 陣列。

如果你的目標只是阻止模型讀 .env，優先用許可權或內建敏感檔案保護；只有需要更細粒度邏輯時才寫外掛。

怎麼判斷外掛寫對了

驗證外掛不要直接上真實任務。按這個順序驗收：

1. 外掛能被載入，沒有啟動錯誤。
2. 只讀日誌或通知能正常觸發。
3. 如果攔截工具呼叫，先在測試儲存庫驗證。
4. 外掛失敗時，錯誤資訊能定位到原因。
5. 停用外掛後，OpenCode 能恢復預設行為。

一個好外掛應該可關閉、可解釋、可定位問題。否則它會讓排障變得更難。

新手常見坑

• 把外掛當成提示詞增強器。提示詞規則應放 Rules、Agent、Command 或 Skill。
• 在全域性目錄放專案專屬外掛，導致其他專案出現異常。
• 外掛裡直接執行危險 shell。
• 日誌裡列印完整環境變數。
• 本來只需要 custom tool，卻寫了一個會修改 OpenCode 生命週期的外掛。
• 沒有停用方案，一齣問題只能猜是不是外掛導致。

接下來去哪

官方資料

• OpenCode plugins
• OpenCode configuration
• OpenCode custom tools