5.4 权限系统 - OpenCode深度教程

权限系统是OpenCode的安全核心，通过精细的权限控制，可以确保AI助手在安全的边界内工作。

三种权限状态

每个工具都可以配置为以下三种权限状态之一：

状态	说明	使用场景
`allow`	自动执行，无需确认	信任的操作，如读取文件、搜索代码
`ask`	每次执行前询问用户确认	需要审查的操作，如执行命令、修改文件
`deny`	禁止执行	危险操作或不需要的功能

默认权限

默认情况下，读取类工具（read、grep、glob、list）为 allow，写入类工具（edit、write、bash）为 ask。

配置结构

基本配置

在 opencode.json 中配置全局权限：

{
  "permission": {
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "list": "allow",
    "edit": "ask",
    "write": "ask",
    "bash": "ask",
    "patch": "ask",
    "webfetch": "ask",
    "lsp": "allow"
  }
}

细粒度配置

可以为特定工具配置更详细的规则：

{
  "permission": {
    "bash": {
      "default": "ask",
      "rules": [
        {
          "pattern": "npm *",
          "permission": "allow"
        },
        {
          "pattern": "git *",
          "permission": "allow"
        },
        {
          "pattern": "rm -rf *",
          "permission": "deny"
        }
      ]
    }
  }
}

通配符匹配

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

通配符	说明	示例
`*`	匹配任意字符（不含路径分隔符）	`*.js` 匹配所有JS文件
`**`	匹配任意路径	`src/*/.ts` 匹配src下所有TS文件
`?`	匹配单个字符	`file?.txt` 匹配file1.txt等
`[abc]`	匹配括号内任一字符	`[Rr]eadme` 匹配Readme或readme

路径规则示例

{
  "permission": {
    "edit": {
      "default": "ask",
      "rules": [
        {
          "pattern": "src/**/*.ts",
          "permission": "allow"
        },
        {
          "pattern": "test/**/*",
          "permission": "allow"
        },
        {
          "pattern": "*.config.js",
          "permission": "ask"
        },
        {
          "pattern": "node_modules/**/*",
          "permission": "deny"
        },
        {
          "pattern": ".env*",
          "permission": "deny"
        }
      ]
    }
  }
}

命令规则示例

{
  "permission": {
    "bash": {
      "default": "ask",
      "rules": [
        {
          "pattern": "npm run *",
          "permission": "allow"
        },
        {
          "pattern": "npm test",
          "permission": "allow"
        },
        {
          "pattern": "npm install *",
          "permission": "ask"
        },
        {
          "pattern": "git status",
          "permission": "allow"
        },
        {
          "pattern": "git diff *",
          "permission": "allow"
        },
        {
          "pattern": "git push *",
          "permission": "ask"
        },
        {
          "pattern": "rm *",
          "permission": "deny"
        },
        {
          "pattern": "sudo *",
          "permission": "deny"
        }
      ]
    }
  }
}

可用权限类型

以下是所有可配置权限的工具：

文件操作

工具	说明	建议权限
`read`	读取文件内容	allow
`edit`	编辑现有文件	ask
`write`	创建或覆盖文件	ask
`patch`	应用补丁	ask

搜索操作

工具	说明	建议权限
`grep`	搜索文件内容	allow
`glob`	按模式查找文件	allow
`list`	列出目录内容	allow

执行操作

工具	说明	建议权限
`bash`	执行shell命令	ask

扩展操作

工具	说明	建议权限
`webfetch`	获取网页内容	ask
`lsp`	语言服务器查询	allow
`mcp:*`	MCP服务器工具	ask

代理级别自定义

可以为不同代理配置不同的权限：

限制性代理

{
  "agent": {
    "reviewer": {
      "description": "代码审查代理",
      "mode": "primary",
      "permission": {
        "read": "allow",
        "grep": "allow",
        "glob": "allow",
        "list": "allow",
        "edit": "deny",
        "write": "deny",
        "bash": "deny"
      }
    }
  }
}

宽松代理

{
  "agent": {
    "developer": {
      "description": "开发代理",
      "mode": "primary",
      "permission": {
        "read": "allow",
        "grep": "allow",
        "glob": "allow",
        "list": "allow",
        "edit": "allow",
        "write": "allow",
        "bash": {
          "default": "allow",
          "rules": [
            {
              "pattern": "rm -rf *",
              "permission": "deny"
            },
            {
              "pattern": "sudo *",
              "permission": "deny"
            }
          ]
        }
      }
    }
  }
}

权限优先级

权限配置的优先级从高到低：

代理级别规则 - 特定代理的permission配置
细粒度规则 - 匹配的pattern规则
工具默认值 - 工具的default设置
全局默认值 - 系统默认权限

安全最佳实践

安全建议

始终禁止 rm -rf 和 sudo 命令
保护敏感文件（.env、credentials等）
对生产环境操作使用 ask 权限
定期审查权限配置

运行时权限管理

在TUI界面中可以临时调整权限：

# 临时允许所有bash命令
/permission bash allow

# 恢复默认设置
/permission bash ask

# 查看当前权限状态
/permission

临时权限

通过命令修改的权限只在当前会话有效，重启后恢复配置文件设置。

下一步

高级配置部分完成。接下来学习OpenCode的扩展功能，包括LSP语言服务器集成。