权限与安全配置

AI 编程工具的强大能力也带来了安全风险。本文将教你如何配置 Opencode 的权限系统，让 AI 能高效工作，但不会误操作或泄露敏感信息。

为什么需要权限配置？

生产环境最怕两件事：

  1. 读取敏感信息：.env 文件、私钥、API Token
  2. 执行危险命令：rm -rf、批量替换、错误的数据库操作

通过合理的权限配置，你可以：

  • 防止 AI 读取敏感文件
  • 控制 AI 的文件修改权限
  • 限制 AI 执行的命令范围
  • 为不同的 Agent 设置不同的权限

权限配置基础

Opencode 的权限系统包含三个层级：

  1. read - 文件读取权限
  2. edit - 文件修改权限
  3. bash - 命令执行权限

每个权限可以设置为：

  • "allow" - 直接放行，不询问
  • "ask" - 每次询问用户确认
  • "deny" - 直接拒绝

推荐的安全配置

基础安全配置

适合个人开发者：

{
  "permission": {
    // 文件读取权限
    "read": {
      "*": "allow",                    // 默认允许读取
      "*.env": "deny",                 // 禁止读取 .env
      "*.env.*": "deny",               // 禁止读取 .env.local 等
      "*.env.example": "allow",        // 允许读取示例文件
      "*.key": "deny",                 // 禁止读取密钥文件
      "*.pem": "deny",                 // 禁止读取证书
      "id_rsa*": "deny"                // 禁止读取 SSH 密钥
    },
    
    // 文件修改权限
    "edit": "ask",                     // 修改前询问
    
    // 命令执行权限
    "bash": {
      "*": "ask",                      // 默认询问
      "git status": "allow",           // 安全命令直接放行
      "git diff": "allow",
      "git log": "allow",
      "npm test": "allow",
      "npm run lint": "allow"
    }
  }
}

严格安全配置

适合团队协作或生产环境：

{
  "permission": {
    "read": {
      "*": "allow",
      // 敏感文件
      "*.env": "deny",
      "*.env.*": "deny",
      "*.key": "deny",
      "*.pem": "deny",
      "*.p12": "deny",
      "*.pfx": "deny",
      // SSH 和 GPG
      "id_rsa*": "deny",
      "id_ed25519*": "deny",
      "*.gpg": "deny",
      // 云服务凭证
      ".aws/credentials": "deny",
      ".gcloud/credentials": "deny",
      ".azure/credentials": "deny",
      // 数据库配置
      "database.yml": "ask",
      "config/database.yml": "ask",
      // 允许示例文件
      "*.example": "allow",
      "*.sample": "allow"
    },
    
    "edit": "ask",
    
    "bash": {
      "*": "ask",
      // 安全的只读命令
      "git status": "allow",
      "git diff": "allow",
      "git log": "allow",
      "ls": "allow",
      "pwd": "allow",
      "cat": "allow",
      // 安全的测试命令
      "npm test": "allow",
      "npm run lint": "allow",
      "pytest": "allow",
      // 危险命令明确禁止
      "rm -rf": "deny",
      "rm -fr": "deny",
      "sudo": "deny",
      "chmod 777": "deny",
      "dd": "deny"
    }
  }
}

文件权限详解

通配符规则

Opencode 支持 glob 模式匹配：

{
  "permission": {
    "read": {
      // 精确匹配
      ".env": "deny",
      
      // 通配符匹配
      "*.env": "deny",              // 匹配所有 .env 结尾的文件
      "*.env.*": "deny",            // 匹配 .env.local, .env.production 等
      
      // 目录匹配
      "secrets/*": "deny",          // 匹配 secrets 目录下的所有文件
      "secrets/**": "deny",         // 匹配 secrets 目录及其子目录
      
      // 多级路径
      "config/secrets/*.key": "deny"
    }
  }
}

优先级规则

当多个规则匹配时，更具体的规则优先级更高：

{
  "permission": {
    "read": {
      "*": "allow",                 // 优先级 1（最低）
      "*.env": "deny",              // 优先级 2
      "*.env.example": "allow"      // 优先级 3（最高）
    }
  }
}

结果：

  • config.js → allow（匹配 *）
  • .env → deny（匹配 *.env）
  • .env.example → allow（匹配 *.env.example，优先级最高）

常见敏感文件清单

{
  "permission": {
    "read": {
      // 环境变量
      "*.env": "deny",
      "*.env.*": "deny",
      
      // 密钥和证书
      "*.key": "deny",
      "*.pem": "deny",
      "*.p12": "deny",
      "*.pfx": "deny",
      "*.crt": "ask",
      
      // SSH 密钥
      "id_rsa": "deny",
      "id_rsa.pub": "ask",
      "id_ed25519": "deny",
      "id_ed25519.pub": "ask",
      
      // 云服务凭证
      ".aws/credentials": "deny",
      ".aws/config": "ask",
      ".gcloud/**": "deny",
      ".azure/**": "deny",
      
      // 数据库
      "database.yml": "ask",
      "*.sql": "ask",
      
      // 密码文件
      "passwords.txt": "deny",
      "secrets.json": "deny",
      
      // 允许示例和模板
      "*.example": "allow",
      "*.sample": "allow",
      "*.template": "allow"
    }
  }
}

命令权限详解

安全命令白名单

{
  "permission": {
    "bash": {
      "*": "ask",  // 默认询问
      
      // Git 只读命令
      "git status": "allow",
      "git diff": "allow",
      "git log": "allow",
      "git show": "allow",
      "git branch": "allow",
      
      // 文件查看
      "ls": "allow",
      "cat": "allow",
      "head": "allow",
      "tail": "allow",
      "pwd": "allow",
      
      // 测试和检查
      "npm test": "allow",
      "npm run lint": "allow",
      "npm run type-check": "allow",
      "pytest": "allow",
      "cargo test": "allow",
      
      // 构建（谨慎）
      "npm run build": "ask",
      "cargo build": "ask"
    }
  }
}

危险命令黑名单

{
  "permission": {
    "bash": {
      // 文件删除
      "rm -rf": "deny",
      "rm -fr": "deny",
      "rm -r": "ask",
      
      // 权限修改
      "chmod 777": "deny",
      "chmod -R 777": "deny",
      "chown": "ask",
      
      // 系统级操作
      "sudo": "deny",
      "su": "deny",
      
      // 磁盘操作
      "dd": "deny",
      "mkfs": "deny",
      
      // 网络操作
      "curl | bash": "deny",
      "wget | sh": "deny",
      
      // 数据库操作
      "DROP DATABASE": "deny",
      "TRUNCATE": "ask",
      "DELETE FROM": "ask"
    }
  }
}

命令参数匹配

Opencode 支持匹配命令的参数：

{
  "permission": {
    "bash": {
      // 精确匹配
      "git push": "ask",
      "git push --force": "deny",
      
      // 部分匹配
      "npm install": "ask",
      "npm install -g": "deny",  // 禁止全局安装
      
      // 正则匹配（高级）
      "git push.*--force": "deny"
    }
  }
}

Agent 级别权限

为不同的 Agent 设置不同的权限：

只读 Agent

适合代码审查、文档生成等场景：

{
  "agent": {
    "code-reviewer": {
      "description": "代码审查专家",
      "model": "anthropic/claude-sonnet-4-5",
      "permission": {
        "read": {
          "*": "allow"
        },
        "edit": "deny",      // 禁止修改
        "bash": "deny"       // 禁止执行命令
      }
    }
  }
}

受限 Agent

允许读写，但命令需要确认：

{
  "agent": {
    "junior-dev": {
      "description": "初级开发者",
      "model": "deepseek/deepseek-coder",
      "permission": {
        "read": {
          "*": "allow",
          "*.env": "deny"
        },
        "edit": "ask",       // 修改前询问
        "bash": {
          "*": "ask",        // 所有命令都询问
          "git status": "allow"
        }
      }
    }
  }
}

高权限 Agent

适合可信任的复杂任务：

{
  "agent": {
    "senior-dev": {
      "description": "资深开发者",
      "model": "anthropic/claude-opus-4-5",
      "permission": {
        "read": {
          "*": "allow",
          "*.env": "deny"    // 仍然保护敏感文件
        },
        "edit": "allow",     // 允许直接修改
        "bash": {
          "*": "ask",
          "git status": "allow",
          "git diff": "allow",
          "npm test": "allow",
          "rm -rf": "deny"   // 危险命令仍然禁止
        }
      }
    }
  }
}

项目级权限配置

开源项目配置

{
  "permission": {
    "read": {
      "*": "allow"  // 开源项目，所有文件都可读
    },
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status": "allow",
      "npm test": "allow"
    }
  }
}

企业项目配置

{
  "permission": {
    "read": {
      "*": "allow",
      // 严格保护敏感文件
      "*.env": "deny",
      "*.env.*": "deny",
      "secrets/**": "deny",
      ".aws/**": "deny",
      "config/production.yml": "deny"
    },
    "edit": "ask",
    "bash": {
      "*": "ask",
      // 只允许安全的只读命令
      "git status": "allow",
      "git diff": "allow",
      // 禁止所有写操作
      "git push": "deny",
      "npm publish": "deny",
      "docker push": "deny"
    }
  }
}

安全最佳实践

1. 最小权限原则

默认拒绝，按需开放：

{
  "permission": {
    "read": {
      "*": "ask",  // 默认询问
      "src/**": "allow",  // 只允许读取源代码
      "docs/**": "allow"
    },
    "edit": "ask",
    "bash": "deny"  // 默认禁止命令
  }
}

2. 分层防护

全局配置 + 项目配置 + Agent 配置：

// 全局配置（~/.config/opencode/opencode.json）
{
  "permission": {
    "read": {
      "*.env": "deny",  // 全局禁止
      "*.key": "deny"
    }
  }
}

// 项目配置（./opencode.json）
{
  "permission": {
    "edit": "ask",  // 项目级别要求确认
    "bash": {
      "*": "ask"
    }
  }
}

3. 定期审计

检查 AI 的操作日志：

# 查看最近的文件操作
cat ~/.config/opencode/logs/operations.log

# 查看执行的命令
cat ~/.config/opencode/logs/bash.log

4. 使用 .gitignore

确保敏感文件不会被提交：

# 环境变量
.env
.env.*
!.env.example

# 密钥
*.key
*.pem
*.p12

# 云服务凭证
.aws/
.gcloud/
.azure/

# 数据库
database.yml

验证权限配置

测试文件权限

# 测试 1：尝试读取 .env
请读取 .env 文件的内容
→ 应该被拒绝

# 测试 2：尝试读取 .env.example
请读取 .env.example 文件的内容
→ 应该成功

# 测试 3：尝试修改文件
请修改 README.md
→ 应该询问确认

测试命令权限

# 测试 1：安全命令
请执行 git status
→ 应该直接执行

# 测试 2：危险命令
请执行 rm -rf node_modules
→ 应该被拒绝或询问

# 测试 3：未知命令
请执行 custom-script.sh
→ 应该询问确认

常见问题

Q: 权限配置会影响性能吗？

不会。权限检查是在操作执行前进行的，不会影响 AI 的响应速度。

Q: 如何临时提升权限？

可以在对话中明确说明：

我确认要执行这个操作，请忽略权限限制

或者临时修改配置文件。

Q: Agent 权限会覆盖全局权限吗？

是的。Agent 级别的权限优先级最高。

Q: 如何恢复默认权限？

删除配置文件中的 permission 部分，Opencode 会使用默认的安全配置。

下一步

本文由 OpenCodex 社区整理，安全无小事，欢迎分享你的安全配置经验。

最近更新: