---
title: "管理工具"
description: "說明 OpenCode 工具管理、LLM 可用工具範圍、許可權控制和排障思路。"
verifiedAt: "2026-05-09"
---

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

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

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

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

先記住這條線：

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

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

## 工具系統分層

```mermaid
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` 治理。

## 許可權怎麼寫

專案級起點可以這樣寫：

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

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

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

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

## `apply_patch` 的細節

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

```ts
input.tool === "apply_patch"
```

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

```text
*** 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` 時可用：

```bash
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`：

```text
!node_modules/
!dist/
!build/
```

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

## 怎麼驗收工具配置

檢查 6 件事：

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

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

## 接下來去哪

<Cards>
  <Card title="許可權配置" href="/zh-Hant/docs/opencode/official/05-security/permissions">
    工具真正的安全邊界在 permission 裡。
  </Card>
  <Card title="建立自定義工具" href="/zh-Hant/docs/opencode/official/04-tools-mcp/custom-tools">
    當內建工具不夠、動作又是專案專有時，再封裝 custom tool。
  </Card>
  <Card title="連線 MCP 伺服器" href="/zh-Hant/docs/opencode/official/04-tools-mcp/mcp-servers">
    需要外部系統上下文時，才把 MCP 接進來。
  </Card>
  <Card title="LSP 伺服器" href="/zh-Hant/docs/opencode/official/04-tools-mcp/lsp">
    需要定義、引用、診斷和型別訊號時，再看 LSP。
  </Card>
</Cards>

## 官方資料

- [OpenCode tools](https://opencode.ai/docs/tools/)
- [OpenCode permissions](https://opencode.ai/docs/permissions/)
- [OpenCode custom tools](https://opencode.ai/docs/custom-tools/)
- [OpenCode MCP servers](https://opencode.ai/docs/mcp-servers/)
