OpenCode 工具权限配置实战教程 | 控制 AI 助手行为

📚 分类: OpenCode 文档 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 已安装并配置好 OpenCode 环境

---

你将学到什么

完成本教程后，你将能够：

• [ ] 理解 OpenCode 中“工具”和“权限”的核心概念
• [ ] 区分 OpenCode 内置的 12 种工具及其用途
• [ ] 独立配置 permission 字段，控制 LLM 对每个工具的使用权限
• [ ] 使用通配符批量管理多个工具的权限

最终效果

你将能够创建或修改 OpenCode 的配置文件 (opencode.json)，精准控制 AI 助手在你的代码库中能执行哪些操作（如：运行命令、修改文件、搜索网页等），从而在安全性与效率之间找到最佳平衡。

---

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求	验证方法
OpenCode 配置文件	在你的项目根目录下已有 opencode.json 文件	使用 ls opencode.json 命令检查是否存在

💡 提示：如果你还没有 opencode.json 文件，可以创建一个空文件，或者使用 OpenCode 的初始化命令（如果支持）来生成。

---

第 1 步：理解核心概念——工具与权限

🎯 目标：理解“工具”是 AI 助手执行操作的“双手”，而“权限”是你控制这双手的“缰绳”。

📝 操作：

1. 认识“工具”：在 OpenCode 中，工具（Tools） 是 AI 助手（LLM）用来与你的代码库和外部世界交互的功能模块。例如：

   • bash 工具允许 AI 运行终端命令。
   • edit 工具允许 AI 修改你的代码文件。
   • webfetch 工具允许 AI 抓取网页内容。

2. 认识“权限”：权限（Permission） 是你用来控制 AI 助手何时、以及是否可以调用某个工具的规则。你可以为每个工具设置三种权限状态：

   • allow（允许）：AI 可以无条件、直接使用该工具，无需你的确认。
   • deny（拒绝）：AI 完全不能使用该工具。
   • ask（需要审批）：AI 在尝试使用该工具前，会先向你发送请求，获得你的明确批准后才能执行。

🤔 为什么要这样做？ 这就像给你的 AI 助手配了一把“智能钥匙”。对于 read（读取文件）这类安全且常用的操作，你可以设为 allow，让它自由使用。但对于 bash（执行命令）或 edit（修改文件）这类有潜在风险的操作，你可以设为 ask，在它执行前先过目一下，确保安全。

✅ 验证： 你已经理解了“工具”和“权限”这两个核心概念。现在，我们可以进入下一步，学习如何实际配置它们。

---

第 2 步：配置单个工具的权限

🎯 目标：学会在 opencode.json 文件中，为指定的单个工具设置权限。

📝 操作：

1. 打开你项目根目录下的 opencode.json 文件。

2. 在文件的最外层，找到 "$schema" 字段，或者直接在其后添加一个 "permission" 字段。

3. 在 "permission" 字段内，以 "工具名称": "权限状态" 的格式添加配置。

   // opencode.json
   {
     "$schema": "https://opencode.ai/config.json", // 配置文件规范地址（可选）
     "permission": {                               // 权限配置开始
       "bash": "deny",                             // 禁止 AI 运行任何终端命令
       "edit": "ask",                              // 修改文件需要你审批
       "webfetch": "allow"                         // 允许 AI 自由抓取网页
     }                                             // 权限配置结束
   }

   💡 提示：如果文件里已经有其他配置，只需在 permission 对象内添加或修改工具权限即可。

✅ 验证： 保存文件后，你可以尝试让 AI 执行一个 bash 命令（例如，让它列出当前目录文件）。如果配置生效，AI 应该会提示你没有权限执行，或者直接拒绝。

⚠️ 常见错误：

• 拼写错误：确保工具名称（如 webfetch）和权限状态（如 allow）的拼写完全正确。
• JSON 格式错误：确保在 "permission" 对象内的每行配置末尾都有逗号（最后一行除外），并且所有键值对都用双引号包裹。

---

第 3 步：使用通配符批量管理工具权限

🎯 目标：学会使用通配符 *，一次性控制多个工具（尤其是来自同一个来源的，如 MCP 服务器）的权限。

📝 操作： 假设你连接了一个名为 my-mcp-server 的 MCP 服务器，它提供了 search-db、send-email 等多个工具。你希望这些工具在使用前都必须经过你的审批。

1. 打开 opencode.json 文件。

2. 在 "permission" 字段内，使用 "来源名称_*" 的格式来匹配该来源下的所有工具。

   // opencode.json
   {
     "$schema": "https://opencode.ai/config.json",
     "permission": {
       "bash": "deny",
       "edit": "ask",
       "webfetch": "allow",
       "mymcp_*": "ask"                // 要求 mymcp 服务器下的所有工具都需审批
     }
   }

🤔 为什么要这样做？ 当 MCP 服务器提供了很多工具时，逐个配置非常繁琐。通过 mymcp_* 这个通配符模式，你只需一行配置，就能控制该服务器下的所有工具。这极大地简化了管理工作。

✅ 验证： 配置保存后，尝试让 AI 调用 my-mcp-server 下的任何一个工具（例如 search-db）。你应该会看到 AI 向你发送一个权限审批请求，而不是直接执行。

---

内置工具一览

以下是 OpenCode 中所有可用的内置工具及其简要说明。你可以根据需要，参考上面的步骤来配置它们的权限。

工具名	用途	权限控制字段	默认行为
bash	在项目中执行 Shell 命令（如 npm install、git status）	bash	allow
edit	通过精确的字符串替换修改现有文件	edit	allow
write	创建新文件或覆盖现有文件	edit (注意：与 edit 共用)	allow
patch	对文件应用补丁 (diff)	edit (注意：与 edit 共用)	allow
read	读取文件内容，支持指定行范围	read	allow
grep	使用正则表达式在文件内容中搜索	grep	allow
glob	使用 Glob 模式（如 src/**/*.js）搜索文件名	glob	allow
lsp (实验性)	与 LSP 服务器交互，获取代码智能（跳转定义、查找引用等）	lsp	allow (需设置环境变量)
skill	执行预定义的 Agent Skills	skill	allow
todo	创建和管理任务清单，跟踪进度	todo	allow
webfetch	抓取并返回指定网页的内容	webfetch	allow
websearch	搜索网页内容，获取最新信息	websearch	allow
question	向用户提问，获取确认或补充信息	question	allow

💡 提示：write 和 patch 工具由 edit 权限控制，这意味着如果你拒绝了 edit 权限，AI 将无法使用 edit、write 和 patch 这三个工具。

⚠️ 关于 lsp 工具：这是一个实验性功能。你需要在启动 OpenCode 时设置环境变量 OPENCODE_EXPERIMENTAL_LSP_TOOL=true 或 OPENCODE_EXPERIMENTAL=true 才能启用它。

---

进阶技巧（可选）

1. 组合使用：将不常用的危险工具（如 bash）设为 deny，将常用的安全工具（如 read、grep）设为 allow，将需要确认的工具（如 edit）设为 ask，可以实现最佳的安全与效率平衡。
2. .gitignore 的尊重：OpenCode 会尊重你项目中的 .gitignore 文件。这意味着，被 .gitignore 忽略的文件（如 node_modules 文件夹）通常不会被 glob 或 grep 等工具搜索到，这本身就是一种内置的安全保护。

---

常见问题 (FAQ)

Q1: 我配置了 "bash": "deny"，但 AI 还是可以运行命令？A: 请检查你的 opencode.json 文件格式是否正确。一个常见错误是 JSON 格式错误（例如缺少逗号或引号）。你可以使用在线 JSON 校验工具检查文件有效性。另外，请确保修改后保存了文件，并重新启动了 OpenCode 会话。

Q2: 我设置了 "mymcp_*": "ask"，但为什么 AI 调用 mymcp_search-db 时直接执行了？A: 请确认 MCP 服务器的工具名称前缀是否与你的通配符完全匹配。例如，如果工具的实际名称是 my-mcp-server_search-db，那么你的通配符应该写成 "my-mcp-server_*": "ask"。

Q3: 如何撤销对所有工具的权限设置？A: 你可以在 opencode.json 中删除整个 "permission" 字段，或者将其值设为空对象 {}。这将使所有工具恢复为默认的 allow 状态。

---

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

1. 工具与权限：理解了工具是 AI 助手执行特定操作的能力，而权限是你控制这些能力的规则。
2. 配置方法：学会了在 opencode.json 文件的 "permission" 字段中，为单个工具设置 allow、deny 或 ask 权限。
3. 批量管理：掌握了使用通配符 * 来批量管理来自同一来源（如 MCP 服务器）的多个工具权限。
4. 内置工具：熟悉了 OpenCode 中 12 种内置工具的用途和对应的权限控制字段。

---