Tools - OpenCode Docs | OpenCode Tutorial

工具允许 LLM 在您的代码库中执行操作。OpenCode 提供了一组内置工具，但您可以使用自定义工具或 MCP 服务器对其进行扩展。

默认情况下，所有工具都启用，并且不需要运行权限。您可以通过权限控制工具行为。

##配置

使用 permission 字段来控制工具行为。您可以允许、拒绝或要求批准每个工具。

bash

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

您还可以使用通配符一次控制多个工具。例如，要要求批准来自 MCP 服务器的所有工具：

bash

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

了解更多关于配置权限的信息。

##内置

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

###bash

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

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": "allow"
  }
}

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

###edit

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

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "allow"
  }
}

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

###write

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

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "allow"
  }
}

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

Note

📝 注意

write 工具由 edit 权限控制，该权限涵盖所有文件修改（edit、write、patch、multiedit）。

###read

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

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "allow"
  }
}

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

###grep

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

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "grep": "allow"
  }
}

跨代码库的快速内容搜索。支持完整的 regex 语法和文件模式过滤。

###glob

通过模式匹配查找文件。

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "glob": "allow"
  }
}

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

###list

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

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "list": "allow"
  }
}

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

###lsp (实验性)

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

Note

📝 注意

只有当 OPENCODE_EXPERIMENTAL_LSP_TOOL=true (或 OPENCODE_EXPERIMENTAL=true) 时，此工具才可用。

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "lsp": "allow"
  }
}

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

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

###patch

将补丁应用于文件。

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "allow"
  }
}

此工具将补丁文件应用于您的代码库。对于应用来自各种来源的差异和补丁很有用。

Note

📝 注意

patch 工具由 edit 权限控制，该权限涵盖所有文件修改（edit、write、patch、multiedit）。

###skill

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

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "skill": "allow"
  }
}

###todowrite

在编码会话期间管理待办事项列表。

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "todowrite": "allow"
  }
}

创建和更新任务列表，以跟踪复杂操作期间的进度。LLM 使用此功能来组织多步骤任务。

Note

📝 注意

默认情况下，此工具对于子代理是禁用的，但您可以手动启用它。了解更多

###todoread

读取现有的待办事项列表。

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "todoread": "allow"
  }
}

读取当前的待办事项列表状态。LLM 使用它来跟踪哪些任务正在等待或已完成。

Note

📝 注意

默认情况下，此工具对于子代理是禁用的，但您可以手动启用它。了解更多

###webfetch

获取 Web 内容。

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "webfetch": "allow"
  }
}

允许 LLM 获取和读取网页。对于查找文档或研究在线资源很有用。

###question

在执行期间向用户提问。

bash

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "question": "allow"
  }
}

此工具允许 LLM 在任务期间向用户提问。它对于以下情况很有用：

收集用户偏好或要求
澄清不明确的说明
获取关于实现选择的决策
提供关于采取什么方向的选择

每个问题都包括一个标题、问题文本和一个选项列表。用户可以从提供的选项中进行选择，或者键入自定义答案。当有多个问题时，用户可以在提交所有答案之前在它们之间导航。

##自定义工具

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

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

##MCP 服务器

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

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

##内部

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

###忽略模式

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

bash

!node_modules/
!dist/
!build/

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