跳转到内容
OpenCode
HomeDocs

工具

管理 LLM 可以使用的工具。

Tools（工具）让 LLM 能够在你的代码仓库中执行实际操作。OpenCode 内置了一些工具，你也可以通过自定义工具或 MCP 服务器进行扩展。

默认情况下，所有工具都是启用的，并且运行时不需要额外确认。你可以通过权限系统来细化控制工具行为。

配置

使用 permission 字段可以控制工具行为：你可以为每个工具单独设置允许、拒绝或需要确认。

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

你也可以使用通配符一次控制一组工具，例如要求某个 MCP 服务器下的所有工具在执行前都需确认：

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

更多配置方式见权限文档。

内置工具

下面是 OpenCode 中可用的内置工具列表。

bash

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

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

允许 LLM 运行终端命令，例如 npm install、git status 等。

edit

通过精确字符串替换来修改已有文件。

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

这是 LLM 修改代码时的主要方式，会对文件中精确匹配的文本进行替换。

write

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

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

允许 LLM 创建新文件；如果文件已存在则会被覆盖。

read

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

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

可以读取文件并返回内容，对大文件也支持按行范围读取。

grep

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

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

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

glob

按模式匹配查找文件。

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

支持 **/*.js、src/**/*.ts 等 glob 模式，返回匹配到的文件路径，并按修改时间排序。

list

列出某个路径下的文件和目录。

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

可以列出目录内容，并支持使用 glob 模式进行过滤。

lsp（实验性）

与已配置的 LSP 服务器交互，获取跳转、引用、悬停信息、调用层级等代码智能能力。

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

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

关于如何为项目配置 LSP 服务器，参见 LSP 服务器。

patch

对文件应用补丁。

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

可以将 patch/diff 内容应用到代码中，适合从各种来源应用补丁。

skill

加载某个 skill（SKILL.md 文件），并把内容注入对话。

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

todowrite

在会话中管理待办任务列表。

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

用于创建和更新任务列表，方便在复杂操作中跟踪进度。LLM 会用它来整理多步骤任务。

todoread

读取已有的待办任务列表。

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

用于读取当前的 todo 状态，让 LLM 知道哪些任务尚未完成、哪些已经完成。

webfetch

抓取网页内容。

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

允许 LLM 访问并读取网页内容，适合查阅文档或进行在线检索。

question

在执行过程中向用户提问。

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

该工具允许 LLM 在执行任务期间主动向你提问，适用于：

  • 收集用户偏好或需求
  • 澄清不明确的指令
  • 在实现细节上让你做选择
  • 提供多个执行路径并让你决定

每个问题会包含标题、正文和选项列表。用户可以从选项中进行选择，也可以输入自定义回答；当有多个问题时，可以在提交前在问题之间切换查看。

自定义工具

自定义工具允许你定义由 LLM 调用的函数，这些函数在本地执行任意逻辑。它们通过配置文件声明。

了解如何创建自定义工具。

MCP 服务器

MCP（Model Context Protocol）服务器可以将外部系统作为工具接入，包括数据库、HTTP API 和各种第三方服务。

关于配置 MCP 服务器的细节，见 MCP 服务器。

实现细节

在内部，grep、glob、list 等工具使用 ripgrep 作为底层实现。ripgrep 默认会遵守 .gitignore 规则，因此 .gitignore 中列出的文件和目录会被排除在搜索和列表结果之外。

忽略规则

如果希望包含本来会被忽略的路径，可以在项目根目录创建 .ignore 文件，以显式“取消忽略”某些路径：

.ignore
!node_modules/
!dist/
!build/

例如，上面的 .ignore 会让 ripgrep 即便在 .gitignore 中忽略了这些目录的情况下，仍然搜索 node_modules/、dist/ 和 build/。