管理工具

Tools 決定 LLM 能在你的專案裡做什麼。OpenCode 自帶讀檔案、搜程式碼、改檔案、執行命令、載入 Skill、訪問網頁等內建工具，也可以透過 custom tools 和 MCP servers 擴充套件。

這一篇用 10 分鐘換什麼：你會知道內建工具怎麼分組、為什麼許可權比提示詞可靠、apply_patch 受哪個許可權控制，以及什麼時候才需要 custom tool 或 MCP。

先給結論：工具越多，許可權越要清楚

官方 Tools 文件說明，工具預設啟用。真實專案裡不要長期依賴預設開放狀態，尤其是 bash、edit、apply_patch、MCP 寫操作和外部網路。

先記住這條線：

只读工具可以更开放
写文件和 shell 默认 ask
外部系统写入默认 ask 或 deny
生产、发布、删除永远不要自动允许

提示詞是意圖，permission 是執行邊界。不要只在提示詞裡寫“謹慎操作”，涉及寫檔案、shell、外部服務時必須配置許可權。

工具系統分層

flowchart TB
  Builtin[內建工具<br/>read / grep / glob / edit / bash]
  Skill[Skill<br/>按需載入 SKILL.md]
  Web[Web<br/>webfetch / websearch]
  LSP[LSP experimental<br/>定義 / 引用 / 診斷]
  Custom[Custom tools<br/>專案專有動作]
  MCP[MCP servers<br/>外部系統工具]
  Permission[permission<br/>allow / ask / deny]

  Permission --> Builtin
  Permission --> Skill
  Permission --> Web
  Permission --> LSP
  Permission --> Custom
  Permission --> MCP

不要把所有擴充套件都叫“工具增強”。內建工具先夠用；專案專有重複動作才做 custom tool；外部系統才接 MCP；需要執行時事件時才寫 plugin。

內建工具怎麼理解

工具組	代表工具	許可權建議
讀取和搜尋	`read`、`grep`、`glob`	通常 `allow`
檔案修改	`edit`、`write`、`apply_patch`	預設 `ask`，審查 Agent `deny`
命令執行	`bash`	預設 `ask`，危險命令 `deny`
任務管理	`todowrite`	主 Agent 可用，子 Agent 按需開啟
Skill 載入	`skill`	內部 Skill 預設 `ask`
Web	`webfetch`、`websearch`	研究類可放開，敏感專案 `ask`
使用者確認	`question`	關鍵決策點可用
LSP 實驗工具	`lsp`	只在啟用實驗變數後使用

write 和 apply_patch 都由 edit 許可權控制。也就是說，只控制 write 這個名字不夠，檔案修改能力要統一按 edit 治理。

許可權怎麼寫

專案級起點可以這樣寫：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "bash": "ask",
    "webfetch": "ask",
    "skill": "ask"
  }
}

如果某個 MCP server 暴露了一組工具，用萬用字元控制：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "github_*": "ask",
    "sentry_*": "ask"
  }
}

bash: allow 不適合作為預設配置。安裝依賴、刪除檔案、釋出、資料庫操作都可能從 shell 觸發。

`apply_patch` 的細節

官方當前工具名是 apply_patch。如果你在 plugin hook 裡處理工具呼叫，要檢查：

input.tool === "apply_patch"

它使用 output.args.patchText，路徑嵌在 patch marker 裡，例如：

*** Add File: src/new-file.ts
*** Update File: src/existing.ts
*** Move to: src/renamed.ts
*** Delete File: src/obsolete.ts

這也是為什麼它必須由 edit 許可權統一治理。

Web 工具怎麼分

webfetch 適合讀取指定 URL。websearch 適合發現資訊。

websearch 只有在使用 OpenCode provider，或設定 OPENCODE_ENABLE_EXA 時可用：

OPENCODE_ENABLE_EXA=1 opencode

如果任務涉及當前事實、版本、價格、法律、模型列表、API 變更，應該用搜尋或官方文件核對；如果資訊已經在本地儲存庫裡，先用 read、grep、glob。

custom tool 和 MCP 怎麼選

Custom tool 適合專案專有、反覆出現、輸入輸出穩定的動作。例如內部診斷、讀取專案配置、生成固定報告。

MCP 適合外部系統上下文。例如 GitHub、Sentry、資料庫、文件搜尋、瀏覽器自動化、專案管理系統。

不要用 custom tool 包一次性 shell 命令，也不要用 MCP 解決本地 grep 能解決的問題。工具一旦進入 OpenCode，就會成為模型可能呼叫的能力，需要長期維護和許可權治理。

grep / glob 和 `.ignore`

OpenCode 的 grep、glob 等搜尋能力底層使用 ripgrep（一款高速正則檔案搜尋工具，比 grep 快幾十倍且預設會自動跳過 .gitignore 裡的檔案）。ripgrep 預設尊重 .gitignore，因此 .gitignore 排除的目錄通常不會出現在搜尋結果裡。

如果你確實要讓搜尋包含某些被忽略目錄，可以在專案根目錄建立 .ignore：

!node_modules/
!dist/
!build/

不要為了“搜得全”就把大型依賴、構建產物、快取目錄全部放開。上下文會變噪，搜尋也會變慢。

怎麼驗收工具配置

檢查 6 件事：

只讀工具是否能正常讀檔案、搜程式碼、找路徑。
edit 是否控制了所有檔案修改能力。
bash 是否預設需要確認。
Web 和 MCP 是否只在需要時啟用。
子 Agent 是否不預設獲得過寬工具。
出問題時是否能用 permission 或 --pure 快速縮小範圍。

工具配置的目標不是停用所有能力，而是讓每個能力都能解釋清楚：誰能用、什麼時候用、會影響什麼。

先給結論：工具越多，許可權越要清楚

工具系統分層

內建工具怎麼理解

許可權怎麼寫

`apply_patch` 的細節

Web 工具怎麼分

custom tool 和 MCP 怎麼選

grep / glob 和 `.ignore`

怎麼驗收工具配置

接下來去哪

許可權配置

建立自定義工具

連線 MCP 伺服器

LSP 伺服器

官方資料

本頁目錄