工具

管理 LLM 可以使用的工具。

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

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

# 配置#

你可以全局或按代理配置工具。代理特定的配置会覆盖全局设置。

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

## 全局#

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "write": false,
5    "bash": false,
6    "webfetch": true
7  }
8}

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "mymcp_*": false
5  }
6}

## 按代理#

使用代理定义中的 tools 配置为特定代理覆盖全局工具设置。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "write": true,
5    "bash": true
6  },
7  "agent": {
8    "plan": {
9      "tools": {
10        "write": false,
11        "bash": false
12      }
13    }
14  }
15}

例如，这里 plan 代理覆盖全局配置以禁用 write 和 bash 工具。

你也可以在 Markdown 中为代理配置工具。

markdown
1<!-- ~/.config/opencode/agent/readonly.md -->
2---
3description: 只读分析代理
4mode: subagent
5tools:
6  write: false
7  edit: false
8  bash: false
9---
10
11分析代码而不进行任何修改。

了解更多关于按代理配置工具。

# 内置工具#

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

## bash#

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "bash": true
5  }
6}

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

## edit#

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "edit": true
5  }
6}

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

## write#

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "write": true
5  }
6}

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

## read#

从代码库读取文件内容。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "read": true
5  }
6}

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

## grep#

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "grep": true
5  }
6}

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

## glob#

通过模式匹配查找文件。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "glob": true
5  }
6}

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

## list#

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "list": true
5  }
6}

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

## lsp（实验性）#

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

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "lsp": true
5  }
6}

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

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

## patch#

将补丁应用到文件。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "patch": true
5  }
6}

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

## skill#

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "skill": true
5  }
6}

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

## todowrite#

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "todowrite": true
5  }
6}

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

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

## todoread#

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "todoread": true
5  }
6}

读取当前待办事项列表状态。LLM 使用此工具来跟踪待处理或已完成的任务。

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

## webfetch#

获取网页内容。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "webfetch": true
5  }
6}

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

# 自定义工具#

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

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

# MCP 服务器#

MCP（模型上下文协议）服务器允许你集成外部工具和服务。这包括数据库访问、API 集成和第三方服务。

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

# 内部机制#

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

## 忽略模式#

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

# .ignore
!node_modules/
!dist/
!build/

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

工具

相关文档