管理工具
说明 OpenCode 工具管理、LLM 可用工具范围、权限控制和排障思路。
Tools 决定 LLM 能在你的项目里做什么。OpenCode 自带读文件、搜代码、改文件、运行命令、加载 Skill、访问网页等内置工具，也可以通过 custom tools 和 MCP servers 扩展。
这一篇用 10 分钟换什么：你会知道内置工具怎么分组、为什么权限比提示词可靠、apply_patch 受哪个权限控制，以及什么时候才需要 custom tool 或 MCP。
先给结论：工具越多，权限越要清楚
官方 Tools 文档说明，工具默认启用。真实项目里不要长期依赖默认开放状态，尤其是 bash、edit、apply_patch、MCP 写操作和外部网络。
先记住这条线：
只读工具可以更开放
写文件和 shell 默认 ask
外部系统写入默认 ask 或 deny
生产、发布、删除永远不要自动允许提示词是意图，permission 是执行边界。不要只在提示词里写“谨慎操作”，涉及写文件、shell、外部服务时必须配置权限。
工具系统分层
flowchart TB
Builtin[内置工具<br/>read / grep / glob / edit / bash]
Skill[Skill<br/>按需加载 SKILL.md]
Web[Web<br/>webfetch / websearch]
LSP[LSP experimental<br/>定义 / 引用 / 诊断]
Custom[Custom tools<br/>项目专有动作]
MCP[MCP servers<br/>外部系统工具]
Permission[permission<br/>allow / ask / deny]
Permission --> Builtin
Permission --> Skill
Permission --> Web
Permission --> LSP
Permission --> Custom
Permission --> MCP不要把所有扩展都叫“工具增强”。内置工具先够用；项目专有重复动作才做 custom tool；外部系统才接 MCP；需要运行时事件时才写 plugin。
内置工具怎么理解
| 工具组 | 代表工具 | 权限建议 |
|---|---|---|
| 读取和搜索 | read、grep、glob | 通常 allow |
| 文件修改 | edit、write、apply_patch | 默认 ask，审查 Agent deny |
| 命令执行 | bash | 默认 ask，危险命令 deny |
| 任务管理 | todowrite | 主 Agent 可用，子 Agent 按需开启 |
| Skill 加载 | skill | 内部 Skill 默认 ask |
| Web | webfetch、websearch | 研究类可放开，敏感项目 ask |
| 用户确认 | question | 关键决策点可用 |
| LSP 实验工具 | lsp | 只在启用实验变量后使用 |
write 和 apply_patch 都由 edit 权限控制。也就是说，只控制 write 这个名字不够，文件修改能力要统一按 edit 治理。
权限怎么写
项目级起点可以这样写：
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"read": "allow",
"grep": "allow",
"glob": "allow",
"edit": "ask",
"bash": "ask",
"webfetch": "ask",
"skill": "ask"
}
}如果某个 MCP server 暴露了一组工具，用通配符控制：
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"github_*": "ask",
"sentry_*": "ask"
}
}bash: allow 不适合作为默认配置。安装依赖、删除文件、发布、数据库操作都可能从 shell 触发。
apply_patch 的细节
官方当前工具名是 apply_patch。如果你在 plugin hook 里处理工具调用，要检查：
input.tool === "apply_patch"它使用 output.args.patchText，路径嵌在 patch marker 里，例如：
*** Add File: src/new-file.ts
*** Update File: src/existing.ts
*** Move to: src/renamed.ts
*** Delete File: src/obsolete.ts这也是为什么它必须由 edit 权限统一治理。
Web 工具怎么分
webfetch 适合读取指定 URL。websearch 适合发现信息。
websearch 只有在使用 OpenCode provider，或设置 OPENCODE_ENABLE_EXA 时可用：
OPENCODE_ENABLE_EXA=1 opencode如果任务涉及当前事实、版本、价格、法律、模型列表、API 变更，应该用搜索或官方文档核对；如果信息已经在本地仓库里，先用 read、grep、glob。
custom tool 和 MCP 怎么选
Custom tool 适合项目专有、反复出现、输入输出稳定的动作。例如内部诊断、读取项目配置、生成固定报告。
MCP 适合外部系统上下文。例如 GitHub、Sentry、数据库、文档搜索、浏览器自动化、项目管理系统。
不要用 custom tool 包一次性 shell 命令，也不要用 MCP 解决本地 grep 能解决的问题。工具一旦进入 OpenCode，就会成为模型可能调用的能力，需要长期维护和权限治理。
grep / glob 和 .ignore
OpenCode 的 grep、glob 等搜索能力底层使用 ripgrep（一款高速正则文件搜索工具，比 grep 快几十倍且默认会自动跳过 .gitignore 里的文件）。ripgrep 默认尊重 .gitignore，因此 .gitignore 排除的目录通常不会出现在搜索结果里。
如果你确实要让搜索包含某些被忽略目录，可以在项目根目录创建 .ignore：
!node_modules/
!dist/
!build/不要为了“搜得全”就把大型依赖、构建产物、缓存目录全部放开。上下文会变噪，搜索也会变慢。
怎么验收工具配置
检查 6 件事：
- 只读工具是否能正常读文件、搜代码、找路径。
edit是否控制了所有文件修改能力。bash是否默认需要确认。- Web 和 MCP 是否只在需要时启用。
- 子 Agent 是否不默认获得过宽工具。
- 出问题时是否能用 permission 或
--pure快速缩小范围。
工具配置的目标不是禁用所有能力，而是让每个能力都能解释清楚：谁能用、什么时候用、会影响什么。
接下来去哪
权限配置
工具真正的安全边界在 permission 里。
创建自定义工具
当内置工具不够、动作又是项目专有时，再封装 custom tool。
连接 MCP 服务器
需要外部系统上下文时，才把 MCP 接进来。
LSP 服务器
需要定义、引用、诊断和类型信号时，再看 LSP。