OpenCode 工具权限配置与管理实战教程

📚 分类: 开发工具配置 ⏱️ 预计耗时: 20 分钟 🎯 难度: 入门 🔧 环境要求: 已安装并配置好 OpenCode 编辑器

---

你将学到什么

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

• [ ] 理解 OpenCode 中“工具”和“权限”的核心概念
• [ ] 通过 opencode.json 配置文件，精确控制每个工具的权限
• [ ] 为内置工具、MCP 服务器工具设置不同的权限策略（允许、拒绝、需审批）
• [ ] 使用 .ignore 文件解决搜索工具忽略 .gitignore 中文件的问题

最终效果

你将能够根据自己的工作流，创建一份个性化的 opencode.json 配置文件。例如，你可以让 AI 助手只能读取代码，不能执行任何 shell 命令，或者在每次执行高风险操作前都向你请求批准。

---

前置准备

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

检查项	要求版本	验证命令
OpenCode	最新稳定版	opencode --version

1. 确认项目根目录存在 opencode.json

OpenCode 的配置是基于项目的。请确保你的项目根目录下有一个 opencode.json 文件。如果没有，创建一个空的即可。

# 进入你的项目目录
$ cd /path/to/your/project

# 如果文件不存在，创建一个空的 JSON 文件
$ touch opencode.json

✅ 验证：在项目根目录下执行 ls -la | grep opencode.json，应该能看到该文件。

---

第 1 步：理解核心概念——权限（Permission）

🎯 目标：理解 permission 字段如何控制工具的行为。

在 OpenCode 中，permission 是控制 AI 助手能做什么的核心机制。你可以为每个工具（或工具组）设置三种权限状态：

1. allow (允许)：AI 可以自由使用该工具，无需经过你同意。
2. deny (拒绝)：AI 无法使用该工具。任何尝试都会失败。
3. ask (需审批)：AI 每次使用该工具前，都会弹出提示框询问你是否允许。

🤔 为什么要这样做？ 这就像给你的 AI 助手设置不同的“安全等级”。例如，你希望它能自由地读取文件（read: allow），但执行删除文件的命令（bash: ask）必须经过你确认，以防止意外操作。

---

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

🎯 目标：学会在 opencode.json 中为特定内置工具设置权限。

OpenCode 自带了许多内置工具，如 bash（执行命令）、edit（编辑文件）、read（读取文件）等。我们以 edit 工具为例，将其设置为“拒绝”，即禁止 AI 自动修改你的代码。

📝 操作：

1. 打开你的 opencode.json 文件。
2. 将以下内容粘贴进去。

// opencode.json
{
  "$schema": "https://opencode.ai/config.json", 
  "permission": {                // 权限配置的根对象
    "edit": "deny"               // 禁止 AI 使用 edit 工具修改文件
  }
}

3. 保存文件。

✅ 验证： 在 OpenCode 中向 AI 助手提出一个修改代码的请求，例如“将 index.js 中的 console.log('hello') 改为 console.log('world')”。AI 应该会回复它没有权限执行此操作，或者直接报错。

💡 提示：

• 配置中的 $schema 字段是可选的，但它能让你在编辑 opencode.json 时获得代码补全和校验提示，强烈建议保留。
• 其他内置工具（如 bash, read, grep）都可以用同样的方式配置。

---

第 3 步：配置多个工具的不同权限

🎯 目标：学会在一个配置文件中为多个工具设置不同的权限策略。

在实际工作中，你通常需要对不同工具设置不同的权限。例如：允许 AI 读取文件、搜索代码，但拒绝它自动执行命令或修改文件，并在需要联网获取信息时询问你。

📝 操作：

1. 修改你的 opencode.json 文件，内容如下：

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "allow",          // 允许读取文件
    "grep": "allow",          // 允许搜索代码内容
    "edit": "deny",           // 拒绝修改文件
    "bash": "deny",           // 拒绝执行 shell 命令
    "webfetch": "ask"         // 获取网页内容前需要我批准
  }
}

2. 保存文件。

✅ 验证：

• 尝试让 AI 读取一个文件（如“帮我看看 package.json 的内容”），它应该能成功执行。
• 尝试让 AI 执行一个命令（如“帮我运行 npm install”），它应该会拒绝。
• 尝试让 AI 去获取一个网页（如“帮我看看 https://example.com 的内容”），它应该会弹出一个确认框。

⚠️ 常见错误：

• 权限冲突：如果你对同一个工具设置了两次，后一个会覆盖前一个。所以请确保每个工具名只出现一次。
• 拼写错误：工具名必须与官方文档完全一致，例如 webfetch 不是 web_fetch 或 webFetch。

---

第 4 步：使用通配符批量控制 MCP 服务器工具

🎯 目标：学会使用通配符 * 来批量管理来自同一 MCP 服务器的所有工具。

当你集成了 MCP 服务器（如一个数据库 MCP 服务器），它可能会提供多个工具（如 db_query、db_insert、db_delete）。手动为每个工具配置权限很麻烦。这时，你可以使用通配符。

📝 操作：

假设你注册了一个名为 my-db-server 的 MCP 服务器，它提供了 query、insert、delete 三个工具。我们希望所有来自这个服务器的工具在使用前都需要审批。

1. 修改你的 opencode.json 文件，添加如下配置：

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "allow",
    "grep": "allow",
    // 控制所有以 "my-db-server_" 开头的工具
    "my-db-server_*": "ask"
  }
}

🤔 为什么要这样做？ MCP 服务器的工具命名规则通常是 [服务器名]_[工具名]。使用 * 通配符可以匹配 my-db-server_query、my-db-server_insert 和 my-db-server_delete 这三个工具，一举三得。

✅ 验证： 在 OpenCode 中，让 AI 执行一个涉及数据库的操作，例如“查询用户数量”。AI 应该会弹出一个提示框，询问你是否允许 my-db-server_query 工具执行。

---

进阶技巧：使用 .ignore 文件包含被忽略的目录

🎯 目标：解决 grep 或 glob 工具无法搜索 node_modules 等被 .gitignore 忽略的目录的问题。

OpenCode 的搜索工具（如 grep）底层使用 ripgrep，它会默认遵循 .gitignore 的规则。这意味着 node_modules、dist 等目录中的内容不会被搜索到。如果你想临时搜索这些目录，可以创建一个 .ignore 文件来覆盖此行为。

📝 操作：

1. 在项目根目录下创建一个名为 .ignore 的文件。
2. 在其中添加你想包含的目录，并在前面加上 ! 符号。

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

这个配置的意思是：“忽略 .gitignore 的规则，允许搜索 node_modules/， dist/ 和 build/ 目录”。

✅ 验证： 在 OpenCode 中，向 AI 提问：“在 node_modules 中搜索所有包含 express 的 package.json 文件”。如果没有 .ignore 文件，AI 可能找不到。有了它，AI 就能成功执行搜索。

⚠️ 注意：搜索 node_modules 等大目录会显著降低性能，请仅在必要时使用此技巧。

---

常见问题 (FAQ)

Q1: 我修改了 opencode.json，但 AI 的行为没有变化？A: 请确保：

1. opencode.json 文件位于项目根目录下。
2. 文件是合法的 JSON 格式（没有多余的逗号，键名使用双引号）。你可以用 JSONLint 等工具校验。
3. 重启 OpenCode 或重新加载窗口（通常是 Ctrl+Shift+P -> Developer: Reload Window）。

Q2: 如何查看当前 OpenCode 支持的所有内置工具列表？A: 你可以在 OpenCode 的官方文档或直接在编辑器中查看。在对话中向 AI 提问“列出所有可用的内置工具”，它通常能告诉你。

Q3: edit 和 write 工具有什么区别？为什么它们的权限是同一个？A: edit 用于修改已存在的文件（通过精确的文本替换），而 write 用于创建新文件或完全覆盖现有文件。在权限层面，它们被归为同一类文件修改操作，都由 "edit" 这个键控制。所以当你设置 "edit": "allow" 时，write 和 patch 工具也会被允许。

---

总结

恭喜你完成了本教程！🎉

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

1. 权限模型：理解了 allow、deny、ask 三种权限状态，这是控制 AI 行为的基础。
2. 精确配置：学会了如何在 opencode.json 的 permission 字段中为单个内置工具配置权限。
3. 批量管理：学会了使用通配符 * 来高效管理来自 MCP 服务器的多个工具。
4. 解决搜索盲区：学会了使用 .ignore 文件来临时覆盖 .gitignore 规则，搜索被忽略的目录。

---

下一步

如果你想继续深入，建议学习：

• 📖 OpenCode 自定义工具教程：学习如何创建你自己的工具，让 AI 能调用你编写的脚本或 API。
• 📖 OpenCode MCP 服务器配置指南：学习如何集成外部服务（如数据库、云平台），极大地扩展 OpenCode 的能力。

💡 练习任务：尝试创建一个新的 opencode.json 配置，要求：

1. 允许 AI 读取文件和搜索代码。
2. 拒绝 AI 执行任何 shell 命令。
3. 对于编辑文件的 edit 工具，设置为“每次都需要审批”。 这是巩固知识的最佳方式。