OpenCode 权限与安全完全指南

当 AI 编程助手拥有读写文件、执行命令和访问网络的能力时，安全就成了不可回避的话题。OpenCode 提供了一套精细化的权限控制系统，让你可以对 AI 的每一步操作进行规则化的管控。本文覆盖权限模型、安全策略、Policies 系统和最佳安全实践。

权限模型概述

OpenCode 的权限系统是一个基于模式匹配的白名单/黑名单模型，支持三个层级：

全局默认权限
    ↓ 覆盖
Agent 级权限
    ↓ 覆盖
规则模式匹配 (allow / deny / ask)

权限最终生效时：规则匹配 > Agent 默认权限 > 全局默认权限。

三大权限类型

1. 编辑权限 (edit)

控制 AI 是否可以创建、修改或删除文件：

{
  "permissions": {
    "edit": true
  }
}

2. 命令执行权限 (bash)

控制 AI 是否可以执行 Shell 命令：

{
  "permissions": {
    "bash": true
  }
}

3. 网络权限 (network)

控制 AI 是否可以发起网络请求（访问 API、下载资源等）：

{
  "permissions": {
    "network": true
  }
}

权限值说明

每个权限可以设置为：

| 值 | 行为 | 适用场景 |
|----|------|----------|
| true | 始终允许，无需确认 | 信任的本地开发环境 |
| false | 始终拒绝 | 敏感环境或代码审查模式 |
| "ask" | 每次操作前弹出确认提示 | 生产环境、关键操作 |

路径级别的权限控制

通过 allow、deny 和 ask 规则，可以对文件路径进行精细化控制：

allow — 白名单

明确允许操作的路径。一旦配置了 allow，只有在白名单中的路径才允许：

{
  "permissions": {
    "allow": [
      "src/**/*.ts",
      "src/**/*.tsx",
      "tests/**",
      "package.json",
      "tsconfig.json"
    ]
  }
}

deny — 黑名单

明确禁止操作的路径（优先级高于 allow）：

{
  "permissions": {
    "deny": [
      ".env",
      ".env.*",
      "**/secrets/**",
      "**/credentials.*",
      "**/*.key",
      "**/*.pem",
      "production/**",
      ".git/**"
    ]
  }
}

ask — 确认列表

需要每次确认的路径：

{
  "permissions": {
    "ask": [
      "config/**",
      "database/**",
      "deploy/**",
      "Makefile",
      "Dockerfile"
    ]
  }
}

路径模式语法

精确匹配：.env
通配符：   src/**/*.ts     (匹配 src 下所有 .ts 文件)
目录匹配： tests/            (匹配整个 tests 目录)
否定模式： !src/secrets/    (排除特定路径)
全局匹配： **/*.key         (匹配所有 .key 文件)

命令级别的安全控制

Shell 命令白名单

{
  "permissions": {
    "bash": "ask",
    "allowedCommands": [
      "npm test",
      "npm run lint",
      "npm run build",
      "npx tsc --noEmit",
      "git diff",
      "git status",
      "git log",
      "ls",
      "cat"
    ],
    "deniedCommands": [
      "rm -rf",
      "git push --force",
      "git reset --hard",
      "DROP",
      "DELETE FROM"
    ]
  }
}

网络域名白名单

{
  "permissions": {
    "network": "ask",
    "allowedDomains": [
      "api.github.com",
      "registry.npmjs.org",
      "*.npmjs.org"
    ],
    "deniedDomains": [
      "*"
    ]
  }
}

安全策略系统 (Policies)

Policies 提供比权限更高级的策略控制，可以为不同的场景设置不同的安全级别：

{
  "policies": {
    "default": {
      "permissions": {
        "edit": true,
        "bash": "ask",
        "network": true
      }
    },
    "strict": {
      "permissions": {
        "edit": false,
        "bash": false,
        "network": false
      }
    },
    "sandbox": {
      "permissions": {
        "edit": true,
        "bash": true,
        "network": false,
        "allow": ["/tmp/sandbox/**"]
      }
    }
  }
}

策略切换

在对话中切换策略：

/policy strict
/policy default

或者在启动时指定：

opencode --policy sandbox

敏感信息保护

环境变量保护

OpenCode 支持通过 ${} 语法引用环境变量，避免敏感信息写入配置文件：

{
  "provider": {
    "apiKey": "${ANTHROPIC_API_KEY}"
  },
  "mcp": {
    "github": {
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

自动检测与警告

OpenCode 内置了敏感信息检测，当生成的代码中包含可能是密钥、Token 或密码的内容时会发出警告。可以在配置中开启严格模式：

{
  "security": {
    "secretDetection": "strict",
    "blockOnSecrets": true,
    "auditLog": true
  }
}

文件内容过滤

{
  "security": {
    "filterPatterns": [
      "-----BEGIN.*PRIVATE KEY-----",
      "ghp_[A-Za-z0-9_]{36}",
      "sk-[A-Za-z0-9]{32}",
      "AKIA[0-9A-Z]{16}"
    ]
  }
}

OpenCode 在读取文件时会跳过匹配这些模式的敏感内容，不会将其发送到 LLM 提供商。

不同环境的安全配置

本地开发（宽松）

{
  "permissions": {
    "edit": true,
    "bash": true,
    "network": true,
    "deny": [
      ".env",
      ".env.local",
      "**/*.key",
      "**/*.pem"
    ]
  }
}

团队共享项目（中等）

{
  "permissions": {
    "edit": true,
    "bash": "ask",
    "network": true,
    "allow": ["src/**", "tests/**", "config/**"],
    "deny": [
      ".env",
      "**/secrets/**",
      ".git/**",
      "node_modules/**"
    ],
    "ask": [
      "package.json",
      "tsconfig.json",
      "docker-compose.yml"
    ]
  }
}

生产/敏感项目（严格）

{
  "permissions": {
    "edit": false,
    "bash": false,
    "network": false,
    "allow": ["src/**"],
    "deny": [
      "**/*.env*",
      "config/**",
      "infra/**",
      "**/credentials.*",
      "**/*.key",
      "**/*.pem"
    ]
  }
}

CI/CD 环境

{
  "permissions": {
    "edit": true,
    "bash": true,
    "network": false,
    "allow": ["src/**", "tests/**"],
    "deny": [".env", ".git/**"],
    "allowedCommands": [
      "npm test",
      "npm run lint",
      "npm run build",
      "npx tsc*"
    ]
  }
}

审计日志

启用操作审计，记录 AI 的所有行为：

{
  "logging": {
    "audit": true,
    "auditPath": "~/.config/opencode/audit.log",
    "logCommands": true,
    "logFileChanges": true,
    "logNetworkRequests": true
  }
}

审计日志示例：

[2026-07-29 15:30:22] EDIT    src/auth.ts       (lines 42-58)
[2026-07-29 15:30:25] BASH    npm test           (exit: 0)
[2026-07-29 15:30:30] NETWORK GET https://api.github.com/repos/org/repo
[2026-07-29 15:30:32] READ    src/database.ts    (200 lines)
[2026-07-29 15:30:35] BASH    git diff           (exit: 0)

安全最佳实践

1. 永远不要让 AI 看到密钥

{
  "permissions": {
    "deny": [".env", "**/.env*", "**/secrets/**"]
  }
}

2. 对危险命令设置 ask

{
  "permissions": {
    "allowedCommands": [
      "npm *", "git status", "git diff", "git log",
      "ls", "cat", "npx tsc*", "npx eslint*"
    ],
    "deniedCommands": [
      "rm *", "git push*", "git reset*",
      "DROP*", "TRUNCATE*", "ALTER*"
    ]
  }
}

3. 生产环境使用严格权限

生产环境只授予必要的最小权限，禁止网络访问以防止数据泄露。

4. 启用审计日志

随时可以回溯 AI 的操作记录，特别是在多人使用 OpenCode 的团队中。

5. 定期轮换 API Key

# 使用环境变量管理 API Key，方便随时更换
export ANTHROPIC_API_KEY="sk-ant-xxx"

6. 团队配置规范

将安全配置放在项目 .opencode/opencode.json 中并提交到 Git，确保所有团队成员遵守相同的安全策略：

{
  "permissions": {
    "deny": [
      ".env",
      "**/.env*",
      "**/secrets/**",
      "**/credentials.*",
      "**/*.key",
      "**/*.pem"
    ],
    "ask": [
      "package.json",
      "docker-compose.yml",
      "Makefile"
    ]
  },
  "security": {
    "secretDetection": "strict",
    "blockOnSecrets": true,
    "auditLog": true
  }
}

小结

权限和安全系统让 OpenCode 在「智能高效」和「安全可控」之间找到了平衡点。通过精细化的权限控制、命令白名单、网络过滤和审计日志，你可以放心地将 AI 编程助手引入从个人项目到企业级生产环境的任何场景。

下一篇我们将深入 OpenCode 的工具、插件与扩展系统，学习如何通过自定义工具、插件、Hooks 和 SDK 来无限扩展 OpenCode 的能力边界。