---
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="/docs/opencode/official/05-security/permissions">
    工具真正的安全边界在 permission 里。
  </Card>
  <Card title="创建自定义工具" href="/docs/opencode/official/04-tools-mcp/custom-tools">
    当内置工具不够、动作又是项目专有时，再封装 custom tool。
  </Card>
  <Card title="连接 MCP 服务器" href="/docs/opencode/official/04-tools-mcp/mcp-servers">
    需要外部系统上下文时，才把 MCP 接进来。
  </Card>
  <Card title="LSP 服务器" href="/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/)
