OpenCode 内置工具系统完全指南：掌握 13 个核心工具精准操控 AI 编程助手

OpenCode 内置工具系统完全指南：掌握 13 个核心工具精准操控 AI 编程助手

OpenCode 作为一款开源的 AI 编程终端，其强大之处不仅在于接入顶尖的大语言模型，更在于它拥有一个完整的内置工具系统。这些工具是 AI 助手与你的代码库、终端环境、乃至整个互联网交互的桥梁。理解每个工具的能力边界和配置方式，是充分发挥 OpenCode 潜力的关键。本文将深入剖析 OpenCode 的 13 个内置工具，涵盖文件操作、搜索导航、代码智能、网络获取、任务管理等多个维度，帮助你像高手一样精准操控 AI 编程助手。

文件操作三剑客：Read、Write、Edit

在 AI 辅助编程中，文件读写是最基础也是最频繁的操作。OpenCode 为此设计了三个核心工具，各司其职。

Read 工具用于读取文件内容，支持指定行号范围，方便 AI 高效定位代码片段。当你让 AI「查看某个函数」时，背后调用的正是 Read 工具。它按行返回内容，对大文件采用分段读取策略，避免一次加载过多 Token。

Write 工具用于创建新文件或覆盖已有文件。当 AI 需要生成一个新组件、配置文件或脚本时，Write 工具会全量写入——这意味着如果文件已存在，它会被完全替换。因此在实际使用中，AI 通常优先使用 Edit 工具做增量修改，而非用 Write 全量覆盖。

Edit 工具是 AI 修改代码的主力工具。它基于精确的字符串替换机制工作：AI 指定要替换的旧文本和新文本，工具在文件中找到唯一匹配后执行替换。这种设计看似简单，但在实践中非常可靠——它要求 AI 精确理解文件内容，无法像正则替换那样模糊匹配，从而减少了意外修改的风险。

{
  "permission": {
    "read": "allow",
    "edit": "allow"
  }
}

值得注意的是，Write 和 Edit 工具共享 edit 权限控制。如果你希望 AI 能精细修改但禁止全量覆写，仅靠权限系统还无法实现这种区分，需要通过自定义配置或工具钩子来增强控制。

代码搜索双雄：Grep 与 Glob

在大型项目中快速定位代码，是 AI 编程助手必须掌握的能力。OpenCode 提供了两个搜索工具：Grep 和 Glob，它们各有侧重。

Grep 工具基于 ripgrep 引擎，在整个项目中搜索匹配特定正则表达式的内容。它支持文件类型过滤（如 *.ts）、路径过滤，并且默认遵循 .gitignore 规则。当 AI 需要查找「所有使用了某个函数的地方」或「找到包含特定关键字的配置项」时，Grep 是首选工具。

Glob 工具则专注于按文件名模式查找文件。它支持 **/*.tsx、src/**/*.css 等 glob 模式，返回匹配的文件路径列表，并按修改时间排序。当 AI 需要「找到所有组件文件」或「列出测试文件」时，Glob 比 Grep 更高效。

{
  "permission": {
    "grep": "allow",
    "glob": "allow"
  }
}

一个实用的技巧是：如果你需要搜索被 .gitignore 排除的文件（如 node_modules），可以在项目根目录创建 .ignore 文件，显式允许搜索这些路径：

!node_modules/
!dist/

这样 ripgrep 就会在 Grep 和 Glob 操作中纳入这些目录，使 AI 能够查阅第三方依赖源码或构建产物。

Shell 执行：Bash 工具的实战智慧

Bash 工具赋予 AI 执行终端命令的能力，是 OpenCode 中最强大也最需要谨慎使用的工具之一。通过 Bash 工具，AI 可以运行 npm install、git status、docker ps、python test.py 等各种命令。

Bash 工具的设计有几个值得注意的特性：

• 它运行在持久化的 Shell 会话中，这意味着 cd 切换目录、设置环境变量等操作会影响后续命令的执行环境
• 支持超时设置，防止长时间运行的命令阻塞工作流
• 输出内容过大时会被自动截断并写入文件，AI 可以通过后续的 Read 操作继续读取

{
  "permission": {
    "bash": {
      "*": "ask",
      "git status": "allow",
      "grep *": "allow"
    }
  }
}

权限配置上，Bash 工具支持最细粒度的控制——你可以为具体的命令模式设置不同策略。上述配置中，所有命令默认需要询问，但 git status 和 grep 命令可以直接执行。这种精细化配置在「读允许、写确认」的工作流中非常实用。

需要特别注意的是：Bash 工具遵循工作目录约束。AI 应当通过 workdir 参数指定执行目录，而非使用 cd && command 的模式，这在 OpenCode 的命令行规范中被明确推荐。

代码智能：LSP 工具

LSP（Language Server Protocol）工具是 OpenCode 实验性的进阶功能，需要通过 OPENCODE_EXPERIMENTAL_LSP_TOOL=true 环境变量开启。一旦启用，AI 就能够利用配置好的语言服务器获得代码智能能力：

• goToDefinition：跳转到定义
• findReferences：查找所有引用
• hover：获取悬停信息（类型签名、文档等）
• documentSymbol：获取文档符号
• workspaceSymbol：全局搜索符号
• goToImplementation：查找实现
• prepareCallHierarchy、incomingCalls、outgoingCalls：调用层级分析

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

LSP 工具的价值在于让 AI 不再仅仅依赖字符串匹配来理解代码，而是获得了语言级别的语义理解能力。例如，当 AI 需要理解某个复杂类型时，它可以调用 hover 获取完整的类型签名；当重构一个接口时，可以调用 findReferences 确保所有实现都被更新。这种语义级的能力远超简单的文本搜索。

补丁应用：Apply Patch

Apply Patch 工具允许 AI 以补丁（diff）的方式应用修改，而非逐行编辑。这在处理跨文件的复杂变更时尤其有用。

补丁格式使用标准的统一 diff 格式，并在标记行中嵌入文件路径：

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

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

Apply Patch 同样受 edit 权限控制。在实际使用中，AI 通常会优先使用单个文件的 Edit 工具做精确修改，而在需要批量操作或文件重命名时才使用 Apply Patch。

知识管理：Skill 与 Todowrite

OpenCode 提供了两个辅助工具来管理知识和任务。

Skill 工具用于加载 SKILL.md 文件——这是一种可复用的专业技能定义文件。当 AI 检测到当前任务匹配某个 Skill 的定义时，它会自动调用 Skill 工具加载对应的指导说明。例如，一个「博客发布」Skill 会包含发布流程、API 调用方式等专业信息，AI 加载后就获得了执行该任务所需的领域知识。

Todowrite 工具用于在多步骤任务中创建和管理待办列表。当 AI 处理复杂任务（如「实现用户注册功能」）时，它会将任务分解为多个步骤，通过 Todowrite 工具创建任务列表，并随着进度推进更新状态（待处理、进行中、已完成、已取消）。这不仅帮助 AI 自己保持任务跟踪，也让你能清晰地看到当前的进展。

{
  "permission": {
    "skill": "allow",
    "todowrite": "allow"
  }
}

需要注意的是，Todowrite 工具默认对子代理（SubAgent）是禁用的，因为子代理通常处理单一具体任务，不需要管理复杂的任务列表。如果你需要子代理也具备此项能力，可以在其权限配置中手动启用。

网络能力：Webfetch 与 Websearch

让 AI 具备联网能力，是现代编程助手的必备特性。

Webfetch 工具可以获取指定 URL 的内容，并自动将其转换为 Markdown 或其他格式。当 AI 需要查看某个 npm 包的文档、读取 GitHub Issue 详情或查阅 API 文档时，WebFetch 是最直接的途径。它支持超时设置，并且会自动将 HTTP 升级为 HTTPS。

Websearch 工具则提供了更广泛的搜索能力。它基于 Exa AI 搜索引擎，允许 AI 发现未知的在线资源。与 WebFetch 的「精确获取」不同，WebSearch 更适用于「探索发现」场景——例如查找最新的技术趋势、搜索某个问题的解决方案等。WebSearch 工具需要 OpenCode 提供商或设置 OPENCODE_ENABLE_EXA 环境变量来启用。

{
  "permission": {
    "webfetch": "allow",
    "websearch": "allow"
  }
}

使用建议：当你知道具体要访问哪个 URL 时使用 WebFetch；当你不确定去哪里找信息时使用 WebSearch。两者配合使用，覆盖了从发现到获取的完整网络信息需求链。

人机交互：Question 工具

Question 工具是 AI 与用户之间最直接的交互通道。当 AI 在任务执行中遇到需要你决策的情况时，它会调用 Question 工具向你提问。

每个 Question 包含：标题、问题文本和选项列表。你可以从预设选项中选择，也可以输入自定义答案。当有多个问题需要确认时，你可以在它们之间导航，确认后一次性提交所有回答。

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

实际场景中，Question 工具在以下场景特别有用：

• 选择设计方案：AI 提供几种方案让你决定
• 确认关键操作：删除文件、修改重要配置前征得同意
• 获取偏好信息：你想要的代码风格、命名规范等
• 提供更多上下文：当信息不充分时请求补充

工具权限管理实战：构建安全的 AI 协作环境

理解了每个工具的用途后，最关键的实战技巧就是合理配置权限。OpenCode 的权限系统支持三种策略：allow（允许）、ask（询问）、deny（禁止）。并且权限可以作用于不同层级：全局、代理级、甚至 Bash 命令级。

一个推荐的团队开发配置示例：

{
  "permission": {
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "npm test": "allow",
      "npm run lint": "allow",
      "git status": "allow",
      "git diff": "allow"
    },
    "webfetch": "allow",
    "websearch": "allow",
    "question": "allow",
    "skill": "allow",
    "todowrite": "allow"
  },
  "agent": {
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

上述配置的核心思路：

• 读操作全放开：Read、Grep、Glob 等只读操作设置为 allow，让 AI 可以自由探索代码库
• 写操作需确认：Edit 设置为 ask，每次修改前征求你的同意
• 安全命令自动放行：测试、lint、查看状态等安全命令直接执行，其他命令需确认
• Plan 模式双重保险：Plan 代理模式下，编辑和执行权限全部禁止，确保分析阶段不会意外修改代码

权限评估遵循一个关键原则：最后匹配的规则生效。这意味着你可以在通用规则后添加特例规则来实现精细化控制。

总结

OpenCode 的 13 个内置工具构成了一个完整而强大的 AI 编程辅助工具箱。从文件读写到代码搜索，从 Shell 执行到网络获取，从知识管理到人机交互，每个工具都针对特定场景做了精心设计。掌握这些工具的能力边界和配置方式，你可以像指挥家一样精准地引导 AI 完成各种编程任务。

实际操作中，建议从默认配置开始，逐步根据项目需求调整权限策略。先让 AI 在 Plan 模式下分析代码、生成计划，确认无误后再切换到 Build 模式执行修改。这种「先计划、再执行」的工作流，结合精细化的权限控制，能够最大化 AI 编程助手的效能，同时将风险降至最低。

OpenCode 的工具系统还在不断进化——LSP 工具正在从实验性走向成熟，新的工具也在持续加入。保持关注官方文档和社区动态，让你的 AI 编程助手始终处于最佳状态。