OpenCode 权限系统完全指南：精细管控 AI 编程助手的每一次操作

OpenCode 权限系统完全指南：精细管控 AI 编程助手的每一次操作

AI 编程助手的能力越强大，安全管控的需求就越迫切。OpenCode 内置了一套完善的权限系统，让开发者可以在享受 AI 自动化的同时，精确控制哪些操作可以自动执行、哪些需要人工确认、哪些必须禁止。本文将深入剖析 OpenCode 的权限模型、配置方法以及最佳实践，帮助你构建既高效又安全的 AI 编程工作流。

权限模型：三种动作，一个核心概念

OpenCode 的权限系统围绕一个简洁而强大的模型展开——每个权限规则会解析为三种动作之一：

• allow：允许执行，无需确认
• ask：执行前征求用户批准
• deny：直接阻止操作

这三种动作覆盖了所有可能的权限策略。你既可以将所有操作完全放开以追求效率，也可以严格限制高风险操作来保障安全，还可以让 OpenCode 在执行关键操作时向你发起确认请求。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

上面这个配置的含义是：所有工具默认需要询问，但 bash 命令可以自动执行，而文件编辑操作则被完全禁止。这种分层配置让权限管理既灵活又直观。

全局权限：一键控制所有工具

最简单的方式是直接对所有工具设置统一的权限策略。如果你刚刚开始使用 OpenCode，或者你对它完全信任，可以直接放行所有操作：

{
  "permission": "allow"
}

这个配置让 OpenCode 拥有完全的自主权，不用每次操作都停下来问你。如果你希望更加谨慎，也可以设置全部需要确认：

{
  "permission": "ask"
}

但实际使用中，更常见的做法是「基本信任 + 重点管控」：大多数操作放行，只有少数高风险操作需要确认或禁止。

精细规则：对象语法实现差异化管控

OpenCode 的权限系统真正强大的地方在于精细规则（Granular Rules）。你可以为每个工具定义不同的策略，并且可以根据工具的具体输入参数来匹配规则。

{
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

这个配置展示了精细规则的典型用法：

• 大多数 bash 命令需要确认
• git 和 npm 命令可以自动执行
• rm 命令被完全禁止，防止误删除
• grep 搜索可以自动执行
• edit 编辑操作默认禁止，但允许修改 docs 目录下的 MDX 文件

这里是权限系统的核心价值所在——你可以根据项目的实际需求，构建出一套精细到命令级别的权限策略。

规则匹配机制

OpenCode 的权限规则按顺序匹配，最后匹配的规则生效。这意味着你应该把通用的通配规则放在前面，把更具体的例外规则放在后面：

{
  "permission": {
    "bash": {
      "*": "deny",
      "git *": "allow",
      "git commit *": "ask",
      "git push *": "deny"
    }
  }
}

在这个例子中，所有 bash 命令默认被禁止，git 相关命令放行，但 git commit 需要确认，git push 则被完全禁止。这就像一个「默认拒绝 + 逐步开放」的安全策略。

通配符匹配

权限规则支持通配符模式：

• * 匹配零个或多个任意字符
• ? 匹配恰好一个字符
• 其他字符匹配字面值

"bash": "git *" 可以匹配 git status、git log --oneline 等，而 "bash": "git commit *" 则更加具体，只匹配以 git commit 开头的命令。

自动模式：信任时的效率提升

如果你的项目有安全的配置和环境，可以使用 --auto 参数启动 OpenCode，自动批准所有未被明确禁止的权限请求：

opencode --auto

在 CLI 模式下也同样适用：

opencode run --auto "Refactor this module"

即使处于自动模式，显式设为 deny 的规则仍然会生效。自动模式只是将原本需要询问（ask）的操作自动批准，而不是覆盖 deny 规则。

你也可以在 TUI 中随时切换自动模式：打开命令面板，选择 Enable auto-approve permissions 或 Disable auto-approve permissions。当自动模式激活时，提示栏会显示一个 auto 标识。

外部目录访问：安全工作在多项目之间

OpenCode 默认只允许访问启动时所在的工作目录下的文件。如果需要访问其他目录（比如家目录下的配置文件、共享库等），需要使用 external_directory 权限来明确授权。

{
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

被授权的外部目录会继承当前工作区的默认权限。如果你想在允许读的同时禁止写，可以叠加其他规则：

{
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    },
    "edit": {
      "~/projects/personal/**": "deny"
    }
  }
}

这样，OpenCode 可以读取 ~/projects/personal/ 下的文件，但无法修改它们。

家目录展开

权限模式中可以使用 ~ 或 $HOME 来引用用户家目录：

• ~/projects/* 展开为 /Users/username/projects/*
• $HOME/projects/* 同样展开为 /Users/username/projects/*

注意：家目录展开只影响模式的书写方式，并不会自动将路径纳入工作区。外部目录仍然需要通过 external_directory 明确授权。

可用权限清单

OpenCode 的权限配置以工具名为键，覆盖了 AI 编程助手的全部操作能力：

| 权限键 | 控制对象 | 匹配依据 |
|--------|----------|----------|
| read | 读取文件 | 文件路径 |
| edit | 修改文件（edit/write/patch） | 文件路径 |
| glob | 文件搜索 | 搜索模式 |
| grep | 内容搜索 | 正则表达式 |
| bash | 执行 shell 命令 | 解析后的命令 |
| task | 启动子代理 | 子代理类型 |
| skill | 加载技能模块 | 技能名称 |
| lsp | LSP 查询 | 当前不支持精细匹配 |
| question | 向用户提问 | — |
| webfetch | 获取 URL | URL |
| websearch | 网页搜索 | 搜索查询 |
| external_directory | 访问工作区外路径 | 触发时的路径 |
| doom_loop | 重复相同操作 | 连续 3 次相同输入 |

每一个权限都可以独立配置，形成高度定制化的安全策略。

默认值：开箱即用的安全底线

如果不做任何配置，OpenCode 使用以下默认权限策略：

• 大多数操作默认 allow
• doom_loop 和 external_directory 默认 ask
• .env 文件默认禁止读取

具体来说，读取权限的默认配置相当于：

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

这意味着 .env 和 .env.local 等环境变量文件被自动保护起来，防止 AI 无意中读取敏感信息。而 .env.example 通常只包含占位符，因此可以正常访问。这个设计体现了「安全优先」的理念。

Ask 确认流程：人工审核的最后一关

当权限规则匹配到 ask 时，OpenCode 会暂停操作并发起确认请求。TUI 界面会提供三个选项：

• once：仅批准本次请求
• always：批准本次及后续匹配相同模式的请求（仅限当前会话）
• reject：拒绝请求

选择 always 后，OpenCode 会根据工具的提示生成一个通配模式。例如，批准 git status --porcelain 后，后续的 git status* 命令都会自动放行。

这个设计让权限管理在使用中逐步优化：你不需要一开始就配置所有规则，而是在实际操作中通过确认来「教会」OpenCode 哪些操作是安全的。

代理级权限：为不同角色定制规则

OpenCode 支持多 Agent 架构，不同 Agent 可以有独立的权限配置。Agent 权限会与全局配置合并，且 Agent 规则优先级更高。

{
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny",
      "grep *": "allow"
    }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
          "git commit *": "ask",
          "git push *": "deny",
          "grep *": "allow"
        }
      }
    }
  }
}

在这个配置中，Build 模式下的 Agent 可以执行 git commit（但需要确认），而全局规则中 git commit 是被禁止的。这样，不同角色的 Agent 拥有不同的权限边界。

你还可以在 Markdown 格式的 Agent 配置中定义权限：

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---
Only analyze code and suggest changes.

这个 Code Review Agent 只能读取代码、执行有限的命令，无法修改文件也不能访问网络——非常适合代码审查场景。

企业策略：Provider 级别的管控

除了操作级别的权限，OpenCode 还提供了实验性的策略（Policies）功能，用于控制 AI 编程助手可以使用哪些 LLM 提供商。这在企业环境中尤其重要，可以确保只有经过批准的 AI 模型被用于处理公司代码。

策略系统与权限系统相互独立——权限控制「工具能不能用」，策略控制「模型能不能用」。

{
  "experimental": {
    "policies": [
      {
        "effect": "deny",
        "action": "provider.use",
        "resource": "openai"
      }
    ]
  }
}

每条策略包含三个字段：effect（allow/deny）、action（操作类型）、resource（资源标识符或通配模式）。

如果想只允许使用特定提供商，可以先全部拒绝再逐个放行：

{
  "experimental": {
    "policies": [
      { "effect": "deny", "action": "provider.use", "resource": "*" },
      { "effect": "allow", "action": "provider.use", "resource": "anthropic" },
      { "effect": "allow", "action": "provider.use", "resource": "openai" }
    ]
  }
}

策略支持全局配置和项目配置的叠加，当两者冲突时，全局策略优先于项目策略。这防止了某个仓库在项目配置中重新启用已被全局禁止的提供商。

最佳实践

1. 渐进式收紧

不要一开始就把所有权限都锁死。先使用宽松的配置让团队适应 OpenCode 的使用方式，然后在实践中逐步收紧高风险操作。

2. 保护敏感文件

确保 .env、*.pem、credentials.json 等敏感文件被明确禁止读取。虽然 OpenCode 默认已经保护了 .env 文件，但你应根据项目实际情况补充更多规则。

3. 锁定危险命令

rm -rf、sudo、chmod -R 等危险命令应该被明确拒绝，或者在执行前必须经过人工确认。

4. 为不同 Agent 设置不同权限

审查型 Agent 不需要编辑权限，部署型 Agent 需要更广泛的脚本执行权限。根据 Agent 的职责范围精确配置。

5. 利用外部目录隔离项目

如果你同时处理多个项目，利用 external_directory 明确授权跨项目访问，而不是直接放行所有路径。

6. 定期审查权限配置

将 opencode.json 纳入版本控制，定期审查权限配置是否仍然符合团队的安全策略和安全需求。

总结

OpenCode 的权限系统是一个设计精巧、层次分明的安全框架。从全局的三动作模型（allow/ask/deny），到工具级别的精细规则，再到 Agent 级别的权限覆盖，最后到企业级的 Provider 策略——每一层都在不同的维度上保障着 AI 编程的安全性。

对于个人开发者，合理配置权限可以在「AI 的自动化效率」和「操作的安全性」之间找到最佳平衡点。对于团队和企业，完善的权限策略是实现 AI 编程助手规范化落地的基石。

掌握了 OpenCode 的权限系统，你才能放心地把更多工作交给 AI，真正做到「让 AI 干活，你来决策」。