Tools

管理 LLM 可以使用的工具。

工具让 LLM 能够在你的代码库中执行操作。OpenCode 自带一组内置工具，但你可以用自定义工具或 MCP 服务器来扩展它。

默认情况下，所有工具都是启用的，且无需权限即可运行。你可以通过权限来控制工具行为。

配置

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

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

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

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

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

内置工具

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

bash

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

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

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

edit

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

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

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

write

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

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

用它来允许 LLM 创建新文件。如果文件已存在，它会覆盖现有文件。

注意： write 工具由 edit 权限控制，该权限涵盖所有文件修改操作（edit、write、apply_patch）。

read

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

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

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

grep

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

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

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

glob

通过模式匹配查找文件。

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

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

lsp（实验性）

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

注意： 此工具仅在 OPENCODE_EXPERIMENTAL_LSP_TOOL=true（或 OPENCODE_EXPERIMENTAL=true）时可用。

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

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

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

apply_patch

将补丁应用到文件。

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

此工具将补丁文件应用到你的代码库。适用于应用来自各种来源的 diff 和补丁。

在处理 tool.execute.before 或 tool.execute.after 钩子时，请检查 input.tool === "apply_patch"（而不是 "patch"）。

apply_patch 使用 output.args.patchText 而非 output.args.filePath。路径嵌入在 patchText 内的标记行中，并且相对于项目根目录（例如：*** Add File: src/new-file.ts、*** Update File: src/existing.ts、*** Move to: src/renamed.ts、*** Delete File: src/obsolete.ts）。

注意： apply_patch 工具由 edit 权限控制，该权限涵盖所有文件修改操作（edit、write、apply_patch）。

skill

加载一个技能（即一个 SKILL.md 文件）并将其内容返回到对话中。

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

todowrite

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

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

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

注意： 此工具默认对子代理禁用，但你可以手动启用它。了解更多

webfetch

获取网页内容。

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

允许 LLM 获取并读取网页。适用于查阅文档或在线检索资料。

websearch

在网上搜索信息。

注意： 此工具仅在使用 OpenCode provider 时，或当 OPENCODE_ENABLE_EXA 环境变量设为任意真值（例如 true 或 1）时可用。

在启动 OpenCode 时启用：

OPENCODE_ENABLE_EXA=1 opencode

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

使用 Exa AI 执行网页搜索，以在线查找相关信息。适用于研究主题、查找时事，或获取超出训练数据截止时间的信息。

无需 API key——该工具直接连接到 Exa AI 托管的 MCP 服务，无需身份验证。

提示： 当你需要查找信息（发现）时使用 websearch，当你需要从特定 URL 检索内容（检索）时使用 webfetch。

question

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

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

此工具允许 LLM 在任务期间向用户提问。它适用于：

• 收集用户偏好或需求
• 澄清含糊不清的指令
• 就实现选择做出决定
• 提供关于走向的选项

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

自定义工具

自定义工具让你能定义自己的、可供 LLM 调用的函数。它们在你的配置文件中定义，并可以执行任意代码。

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

MCP 服务器

MCP（Model Context Protocol）服务器让你能够集成外部工具和服务。这包括数据库访问、API 集成和第三方服务。

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

内部机制

在内部，grep 和 glob 等工具底层使用 ripgrep (opens in a new tab)。默认情况下，ripgrep 会遵循 .gitignore 模式，这意味着你 .gitignore 中列出的文件和目录会被排除在搜索和列举之外。

忽略模式

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

!node_modules/
!dist/
!build/

例如，这个 .ignore 文件允许 ripgrep 在 node_modules/、dist/ 和 build/ 目录中搜索，即使它们已列在 .gitignore 中。