工具

管理 LLM 可以使用的工具。

工具允许 LLM 在你的代码库中执行操作。OpenCode 自带了一系列内置工具，但你可以通过自定义工具或 MCP 服务器来扩展它。

默认情况下，所有工具都是启用的，且无需权限即可运行。但你可以通过配置文件进行配置并控制权限。

配置

你可以全局配置工具，也可以为每个智能体单独配置。特定于智能体的配置会覆盖全局设置。

默认情况下，所有工具都设置为 true。要禁用某个工具，请将其设置为 false。

全局

使用 tools 选项全局禁用或启用工具。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false,
    "webfetch": true
  }
}

你也可以使用通配符同时控制多个工具。例如，禁用来自某个 MCP 服务器的所有工具：

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "mymcp_*": false
  }
}

按智能体

在智能体定义中使用 tools 配置来为特定智能体覆盖全局工具设置。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

例如，这里的 plan 智能体覆盖了全局配置，禁用了 write 和 bash 工具。

你也可以在 Markdown 中为智能体配置工具。

---
description: 只读分析智能体
mode: subagent
tools:
  write: false
  edit: false
  bash: false
---

在不进行任何修改的情况下分析代码。

了解更多关于为每个智能体配置工具的信息。

内置

以下是 OpenCode 中所有可用的内置工具。

bash

在你的项目环境中执行 shell 命令。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "bash": true
  }
}

此工具允许 LLM 运行终端命令，如 npm install、git status 或任何其他 shell 命令。

edit

使用精确的字符串替换来修改现有文件。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "edit": true
  }
}

此工具通过替换精确匹配的文本对文件进行精确编辑。这是 LLM 修改代码的主要方式。

write

创建新文件或覆盖现有文件。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true
  }
}

使用此工具允许 LLM 创建新文件。如果文件已存在，它将覆盖现有文件。

read

从你的代码库中读取文件内容。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "read": true
  }
}

此工具读取文件并返回其内容。对于大型文件，它支持读取特定的行范围。

grep

使用正则表达式搜索文件内容。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "grep": true
  }
}

在你的代码库中进行快速内容搜索。支持完整的正则表达式语法和文件模式过滤。

glob

通过模式匹配查找文件。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "glob": true
  }
}

使用 glob 模式（如 **/*.js 或 src/**/*.ts）搜索文件。返回按修改时间排序的匹配文件路径。

list

列出给定路径中的文件和目录。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "list": true
  }
}

此工具列出目录内容。它接受 glob 模式来过滤结果。

LSP (实验性)

与你配置的 LSP 服务器进行交互，以获取代码智能功能，如定义、引用、悬停信息和调用层次结构。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "lsp": true
  }
}

支持的操作包括 goToDefinition、findReferences、hover、documentSymbol、workspaceSymbol、goToImplementation、prepareCallHierarchy、incomingCalls 和 outgoingCalls。

要配置哪些 LSP 服务器可用于你的项目，请参阅 LSP 服务器。

patch

向文件应用补丁。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "patch": true
  }
}

此工具将补丁文件应用到你的代码库中。对于应用来自各种来源的差异 (diffs) 和补丁非常有用。

skill

加载一个技能 (skill) (SKILL.md 文件) 并在对话中返回其内容。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "skill": true
  }
}

你可以使用 permission.skill 通过权限 (permissions) 来控制加载技能时的批准提示。

todowrite

在编码会话期间管理任务列表 (todo lists)。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "todowrite": true
  }
}

创建并更新任务列表，以在复杂操作期间跟踪进度。LLM 使用它来组织多步骤任务。

todoread

读取现有的任务列表。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "todoread": true
  }
}

读取当前任务列表状态。由 LLM 用于跟踪哪些任务处于待处理或已完成状态。

webfetch

获取网页内容。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "webfetch": true
  }
}

允许 LLM 获取并读取网页。对于查阅文档或研究在线资源非常有用。

自定义工具

自定义工具允许你定义 LLM 可以调用的自有函数。这些工具在你的配置文件中定义，可以执行任意代码。

了解更多关于创建自定义工具的信息。

MCP 服务器

MCP (Model Context Protocol) 服务器允许你集成外部工具和服务。这包括数据库访问、API 集成和第三方服务。

了解更多关于配置 MCP 服务器的信息。

内部原理

在内部，grep、glob 和 list 等工具底层使用的是 ripgrep。默认情况下，ripgrep 会遵循 .gitignore 模式，这意味着 .gitignore 中列出的文件和目录将被排除在搜索和列表之外。

忽略模式

要包含通常会被忽略的文件，请在项目根目录下创建一个 .ignore 文件。此文件可以显式允许某些路径。

!node_modules/
!dist/
!build/

例如，即使 node_modules/、dist/ 和 build/ 目录列在 .gitignore 中，此 .ignore 文件也会允许 ripgrep 在这些目录中进行搜索。