工具系统与权限

目标：理解 OpenCode 的工具机制，安全配置权限

概述

工具（Tools）是 AI 代理执行操作的能力。OpenCode 的工具系统让 AI 能：

📖 read — 读取文件内容
✏️ edit — 编辑文件
🖥️ bash — 运行终端命令
🌐 webfetch — 获取网页内容
🧩 skill — 加载代理技能
以及更多...

理解工具权限，是安全使用 AI 编程助手的关键。

工具权限架构图

内置工具列表

文件操作

工具	功能	风险	默认权限
`read`	读取文件	无	`allow`
`edit`	编辑文件	中	`allow`
`list`	列出目录	无	`allow`
`search`	搜索代码	无	`allow`

命令执行

工具	功能	风险	建议权限
`bash`	运行 shell 命令	高	`ask`
`python`	运行 Python 代码	高	`ask`

网络与知识

工具	功能	风险	建议权限
`webfetch`	获取网页	低	`allow`
`skill`	加载技能	低	`allow`

权限配置

默认所有工具都是启用的。你可以通过权限控制：

三种权限级别

级别	说明	效果	图标
`allow`	允许	AI 直接使用，不询问	🟢
`ask`	询问	AI 请求时显示确认提示	🟡
`deny`	拒绝	AI 无法使用该工具	🔴

基础配置文件

在 opencode.json 中：

{
  "permission": {
    "edit": "allow",      // 自动编辑文件
    "bash": "ask",        // 运行命令前确认
    "webfetch": "deny"    // 禁止访问网页
  }
}

使用通配符

控制一组工具：

{
  "permission": {
    "mymcp_*": "ask",     // mymcp 开头的所有工具都需确认
    "read": "allow",
    "github_*": "ask"     // GitHub MCP 的所有操作需确认
  }
}

权限矩阵表

场景	read	edit	bash	webfetch	MCP
新手学习	allow	ask	ask	allow	ask
日常开发	allow	allow	ask	allow	ask
代码审查	allow	deny	deny	allow	deny
自动化 CI	allow	deny	deny	allow	deny
完全信任	allow	allow	allow	allow	allow
企业安全	allow	ask	deny	ask	ask

权限配置策略

安全模式（推荐新手）

{
  "permission": {
    "edit": "ask",        // 编辑前确认
    "bash": "ask",        // 命令前确认
    "webfetch": "ask",    // 联网前确认
    "python": "ask"       // Python 执行前确认
  }
}

信任模式（熟练后）

{
  "permission": {
    "edit": "allow",
    "bash": "ask",
    "webfetch": "allow",
    "read": "allow"
  }
}

只读模式（审查代码）

{
  "permission": {
    "edit": "deny",
    "bash": "deny",
    "python": "deny",
    "read": "allow",
    "webfetch": "allow"
  }
}

企业级权限配置

{
  "permission": {
    // 文件操作：允许读取，编辑需确认
    "read": "allow",
    "list": "allow",
    "search": "allow",
    "edit": "ask",
 
    // 命令执行：严格管控
    "bash": "ask",
    "python": "ask",
 
    // 网络：按需控制
    "webfetch": "ask",
 
    // MCP 工具：统一确认策略
    "mcp_*": "ask",
    "github_*": "ask",
    "postgres_*": "deny",
 
    // 特定路径保护
    "edit_/etc/*": "deny",
    "edit_~/.ssh/*": "deny",
    "bash_rm*": "deny"
  }
}

真实场景案例 ①：金融企业安全策略

某银行技术团队配置 bash: deny 和 edit: ask，所有代码修改必须人工确认，AI 仅用于代码审查和文档生成，确保生产环境零风险。

命令执行确认

当权限设为 ask 时，AI 执行命令前会提示：

🤖 我要运行以下命令：
   npm test

是否允许？
[Y] 是  [N] 否  [A] 始终允许此命令

批量确认

长时间任务可临时切换到 allow：

/permission bash allow    （临时）

或使用环境变量：

OPENCODE_CONFIG_CONTENT='{"permission":{"bash":"allow"}}' opencode

安全策略模板

模板 A：个人开发者（平衡效率与安全）

{
  "permission": {
    "read": "allow",
    "edit": "allow",
    "bash": "ask",
    "webfetch": "allow",
    "python": "ask",
    "mcp_*": "ask"
  }
}

模板 B：团队协作（ conservative ）

{
  "permission": {
    "read": "allow",
    "edit": "ask",
    "bash": "ask",
    "webfetch": "allow",
    "python": "deny",
    "mcp_*": "ask",
    "github_*": "ask"
  },
  "rules": [
    "所有代码修改必须经过人工确认",
    "禁止执行删除命令",
    "禁止修改配置文件"
  ]
}

模板 C：自动化流水线（只读）

{
  "permission": {
    "read": "allow",
    "edit": "deny",
    "bash": "deny",
    "webfetch": "allow",
    "python": "deny",
    "mcp_*": "deny"
  }
}

工具执行日志

所有工具调用都会被记录：

~/.local/share/opencode/logs/

可以查看 AI 具体执行了哪些操作。

审计日志配置

启用详细审计：

{
  "logging": {
    "level": "debug",
    "tools": true,
    "commands": true,
    "fileChanges": true,
    "outputPath": "~/.local/share/opencode/logs/audit.log"
  }
}

日志分析示例

# 查看今天 AI 执行的所有 bash 命令
grep "bash" ~/.local/share/opencode/logs/*.log | grep $(date +%Y-%m-%d)
 
# 统计 AI 编辑了哪些文件
grep "edit" ~/.local/share/opencode/logs/*.log | awk '{print $3}' | sort | uniq -c
 
# 查看是否有被拒绝的操作
grep "denied\|rejected" ~/.local/share/opencode/logs/*.log

真实场景案例 ②：安全审计

某企业安全团队每周审查 OpenCode 审计日志，发现 AI 曾尝试执行 rm -rf 命令（被权限系统拦截）。基于此，团队更新了规则，明确禁止包含 rm -rf 的命令模式。

MCP 工具的权限

MCP 服务器添加的工具同样受权限控制：

{
  "mcp": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  },
  "permission": {
    "github_*": "ask",    // GitHub MCP 的所有工具都需确认
    "github_create_pr": "deny",  // 禁止自动创建 PR
    "github_read_issue": "allow" // 允许读取 Issue
  }
}

MCP 权限决策流程

真实场景案例 ③：MCP 分级管控

某团队配置 GitHub MCP 时：

github_read_*: allow（读取类操作自动通过）

github_create_*: ask（创建类操作需确认）

github_delete_*: deny（删除类操作完全禁止）

实现了细粒度的 MCP 权限控制。

最佳实践

DO ✅

生产环境使用 ask 模式
定期检查日志
为敏感操作设置 deny
使用通配符批量控制 MCP 工具
为不同项目配置不同权限
团队统一安全策略

DON'T ❌

不要随意 allow bash 工具
不要在公共机器上存储 API 密钥
不要忽略权限确认提示
不要对所有 MCP 使用统一权限
不要在生产环境启用 python 工具

FAQ

Q: ask 模式下，AI 会等待多久？

A: 默认等待用户无限期确认。在 CI/CD 等非交互环境中，应使用 allow 或 deny，避免卡住。

Q: 可以针对特定路径设置权限吗？

A: 部分支持。可以通过命名约定或 MCP 配置实现路径级别的控制，具体取决于工具实现。

Q: 权限被拒绝时，AI 会怎么处理？

A: AI 会收到权限拒绝的错误信息，通常会尝试替代方案（如用 read 代替 edit 查看文件），或向用户说明需要更高权限。

Q: 临时修改权限后如何恢复？

A: 通过 /config 查看当前配置，或重启 OpenCode 加载配置文件中的默认权限。

避坑清单 ⚠️

坑	后果	正确做法
全局 `bash: allow`	AI 可能执行 `rm -rf /` 等危险命令	始终 `ask` 或严格限制命令白名单
`edit: allow` + 无版本控制	代码被误改后无法恢复	确保项目已 Git 初始化且频繁提交
忽略 MCP 工具权限	MCP 可能执行越权操作	为每个 MCP 配置独立权限
多人共用一台机器	权限配置互相干扰	使用项目级 `opencode.json` 隔离
未启用审计日志	无法追溯 AI 操作	生产环境务必启用日志记录
`python` 工具 `allow`	AI 可执行任意 Python 代码	等同于 `bash: allow`，谨慎使用

练习

将 bash 权限设为 ask，体验确认流程
尝试 deny edit，看 AI 如何响应
为一个 MCP 工具配置特定权限
审查本周的 AI 操作日志

下一篇：11. 规则系统