OpenCode 为 AI 提供了一套内置工具，涵盖文件读写（read/edit/write）、代码搜索（grep/glob）、Shell 命令（bash）、网络抓取（webfetch/websearch）、任务管理（todowrite）等。所有工具默认开启，通过 permission 字段控制是否需要确认。内部 grep/glob 使用 ripgrep 实现，默认遵循 .gitignore 规则。

OpenCode 内置工具

OpenCode 为 AI 提供一套内置工具，让它可以在你的代码库中执行操作。所有工具默认全部启用，无需额外配置即可使用。

通过 permission 字段控制工具的执行权限。更多内容见权限管理。

---

工具权限配置

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

用 glob 一次控制多个工具（如某个 MCP 服务器的所有工具）：

{
  "permission": {
    "mymcp_*": "ask"
  }
}

---

内置工具列表

bash

执行 shell 命令。

{ "permission": { "bash": "allow" } }

允许 AI 运行 npm install、git status、测试命令等终端操作。

---

edit

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

{ "permission": { "edit": "allow" } }

精确编辑，通过匹配文本片段进行替换，是 AI 修改代码的主要方式。

---

write

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

{ "permission": { "edit": "allow" } }

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

---

read

读取文件内容。

{ "permission": { "read": "allow" } }

支持读取指定行范围（适合大文件）。默认允许，但 .env 文件默认被拒绝。

---

grep

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

{ "permission": { "grep": "allow" } }

快速全代码库内容搜索，支持完整正则语法和文件模式过滤。内部使用 ripgrep，自动遵循 .gitignore。

---

glob

按模式匹配查找文件。

{ "permission": { "glob": "allow" } }

支持 **/*.js、src/**/*.ts 等 glob 语法，返回按修改时间排序的文件路径列表。

---

lsp（实验性）

连接 LSP 服务器，获取代码智能功能。

{ "permission": { "lsp": "allow" } }

需要设置 OPENCODE_EXPERIMENTAL_LSP_TOOL=true（或 OPENCODE_EXPERIMENTAL=true）才能启用。

支持的操作：

操作	说明
goToDefinition	跳转到定义
findReferences	查找所有引用
hover	悬停信息
documentSymbol	文档符号列表
workspaceSymbol	工作区符号搜索
goToImplementation	跳转到实现
prepareCallHierarchy	准备调用层级
incomingCalls	查找调用方
outgoingCalls	查找被调方

LSP 服务器配置参见 LSP 配置文档。

---

apply_patch

应用 patch 文件到代码库。

{ "permission": { "edit": "allow" } }

受 edit 权限控制。Patch 文本中通过标记行指定操作和路径（相对于项目根目录）：

• *** Add File: src/new-file.ts — 新增文件
• *** Update File: src/existing.ts — 更新文件
• *** Move to: src/renamed.ts — 重命名文件
• *** Delete File: src/obsolete.ts — 删除文件

Hook 中处理此工具时，使用 input.tool === "apply_patch"（不是 "patch"），路径从 output.args.patchText 中读取。

---

skill

加载一个 skill（SKILL.md 文件），将其内容添加到对话中。

{ "permission": { "skill": "allow" } }

---

todowrite

在编码会话中管理任务列表。

{ "permission": { "todowrite": "allow" } }

AI 用此工具在处理复杂多步任务时记录和追踪进度。

注意：subagent 默认禁用此工具，可手动开启。

---

webfetch

抓取网页内容。

{ "permission": { "webfetch": "allow" } }

让 AI 能读取网页，适合查找文档或研究特定 URL 的内容。

---

websearch

搜索网络信息。

{ "permission": { "websearch": "allow" } }

仅在使用 OpenCode provider 或设置 OPENCODE_ENABLE_EXA=true 时可用：

OPENCODE_ENABLE_EXA=1 opencode

基于 Exa AI 的网络搜索，无需 API Key。

区别：websearch 用于发现信息（不知道具体 URL），webfetch 用于抓取已知 URL 的内容。

---

question

向用户提问。

{ "permission": { "question": "allow" } }

允许 AI 在执行任务中途向你提问：

• 收集用户偏好或需求
• 澄清模糊的指令
• 在实现选择上征求意见
• 提供方向选项

每个问题包含标题、问题文本和选项列表。用户可以选择选项或输入自定义答案。

---

扩展工具

除内置工具外，还可以通过以下方式添加更多工具：

• MCP 服务器：接入外部服务（数据库、API、第三方服务）
• 自定义工具：在配置文件中定义可执行任意代码的函数（参见官方文档）

---

搜索忽略规则

grep 和 glob 内部使用 ripgrep，默认遵循 .gitignore 规则，忽略其中列出的文件和目录。

如需搜索通常被忽略的目录，在项目根目录创建 .ignore 文件：

!node_modules/
!dist/
!build/

! 前缀表示"不忽略"，允许 ripgrep 搜索这些目录。

---

常见问题

Q: AI 总是拒绝执行 bash 命令，怎么回事？

A: 检查 permission.bash 配置。如果设为 "deny" 则完全禁止。如果设为 "ask" 则每次会弹确认框。对于信任的命令可以配置精细规则允许，例如 "git *": "allow"。

Q: AI 读不到某个文件怎么办？

A: 可能的原因：① 文件是 .env 类型（默认禁止读取）；② permission.read 有限制；③ 文件在 .gitignore 里（但 read 不受此影响，只有 grep/glob 受影响）。

Q: websearch 和 webfetch 什么时候用哪个？

A: 不知道去哪找信息时用 websearch（"最新的 React 文档在哪"）；有明确 URL 时用 webfetch（"读取 https://... 的内容"）。