OpenCode 安全配置与团队协作实战教程

📚 分类: OpenCode 安全与团队管理 ⏱️ 预计耗时: 30 分钟 🎯 难度: 中级 🔧 环境要求: 已安装并运行过 OpenCode

你将学到什么

完成本教程后，你将能够：

[ ] 配置 OpenCode 的权限模型，从“默认开放”变为“按需授权”
[ ] 安全地管理 API 密钥和敏感文件，避免泄露风险
[ ] 掌握会话分享的三种模式，并能为敏感项目禁用分享功能
[ ] 制定团队级的公共配置规范，并将其版本化
[ ] 安全地接入 GitHub/GitLab 集成，从只读任务开始验证

最终效果

你将拥有一个配置好的 OpenCode 项目。该项目具备明确的安全边界：高危操作需要人工审批，敏感文件不会被意外读取，分享功能被严格管控，所有团队公共配置都存储在 Git 仓库中并可追溯。

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求版本	验证命令
OpenCode	最新稳定版	`opencode --version`
Git	≥ 2.30	`git --version`

1. 准备一个测试项目

我们将在测试项目中应用所有安全配置。

bash

# 创建一个测试项目目录
$ mkdir secure-opencode-project && cd secure-opencode-project

# 初始化一个 Git 仓库（用于模拟团队协作）
$ git init

✅ 验证：你应该看到 Initialized empty Git repository in /your/path/secure-opencode-project/.git/。

第 1 步：配置权限基线，从 `ask` 开始

🎯 目标：创建一个项目级的 opencode.json 配置文件，将 OpenCode 的默认权限从“相对开放”调整为“询问优先”，确保关键操作必须经过你的人工确认。

📝 操作：

在项目根目录下创建 opencode.json 文件，并写入以下配置：

json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    // 全局默认：所有未明确指定的操作，执行前都需要询问
    "*": "ask",
    "read": {
      // 读取操作相对开放，但 .env 文件除外
      "*": "allow",
      "*.env": "deny",          // 新增：禁止读取 .env 文件
      "*.env.*": "deny",        // 新增：禁止读取 .env.local 等
      "*.env.example": "allow", // 新增：但允许读取示例文件
      "grep": "allow",
      "glob": "allow"
    },
    "edit": {
      // 写入/修改文件，执行前需要询问
      "*": "ask"
    },
    "bash": {
      // Shell 命令，执行前需要询问，但安全的 git 命令除外
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "rm *": "deny",            // 新增：直接拒绝 rm 命令
      "git push*": "deny"       // 新增：直接拒绝 git push
    },
    "webfetch": "ask",
    "websearch": "ask",
    "skill": "ask",
    "external_directory": "ask"
  }
}

🤔 为什么要这样做？"*": "ask" 就像一道安全门，让 OpenCode 在每次执行写文件、运行命令或联网操作前，都会弹窗询问你。这给了你理解 agent 行为的机会，而不是让它“悄悄”做事。对于 rm 和 git push 这种高风险命令，直接 "deny" 可以避免灾难性操作。

✅ 验证：

在终端运行 opencode 启动 TUI。
尝试输入一个简单的写文件命令，例如：“在当前目录创建一个名为 test.txt 的文件，内容为 'hello'”。
你会看到 OpenCode 在执行前会弹出一个审批弹窗，询问你是否允许 edit 操作。

第 2 步：管控外部目录访问

🎯 目标：限制 OpenCode 只能访问项目工作区内的文件，并对需要访问的外部目录进行精确授权，避免它“窥探”你的个人文件。

📝 操作：

编辑 opencode.json 文件，在 permission 对象中增加 external_directory 配置：

json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    // ... 上一步的配置保持不变 ...
    "external_directory": {
      // 新增：只允许读取共享文档目录，禁止修改
      "~/projects/shared-docs/**": "allow",
      "edit": {
        // 新增：对共享文档目录的编辑权限设为禁止
        "~/projects/shared-docs/**": "deny"
      }
    }
  }
}

⚠️ 常见错误： ❌ 错误做法："external_directory": "allow" —— 这等于允许 OpenCode 访问你电脑上的任何目录，包括桌面、下载文件夹等，非常危险。 ✅ 正确做法：像上面示例一样，只允许访问少数几个你明确授权的路径，并且可以单独设置这些路径的读写权限。

💡 提示：~/projects/shared-docs/** 中的 ** 表示匹配该目录下的所有子目录和文件。

✅ 验证：

在 TUI 中尝试让 OpenCode 读取 ~/Downloads 目录下的文件。它应该会触发 external_directory 的 ask 权限询问，而不是直接执行。

第 3 步：配置会话分享模式

🎯 目标：根据项目敏感度，配置 OpenCode 的分享模式。对于敏感项目，彻底禁用分享功能。

📝 操作：

编辑 opencode.json 文件，在最外层（与 $schema 同级）添加 share 配置：

json

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual", // 新增：设置为手动分享模式
  "permission": {
    // ... 之前的配置 ...
  }
}

🤔 分享模式选择：

模式	配置值	行为	适用场景
手动 (推荐)	`"manual"`	只有在 TUI 中输入 `/share` 命令时，才会创建分享链接。	大多数普通项目。
自动 (慎用)	`"auto"`	每次新会话都会自动创建一个公开分享链接。	仅限公开教程、演示等绝对不包含敏感信息的项目。
禁用 (安全)	`"disabled"`	彻底关闭分享功能，输入 `/share` 命令无效。	商业、金融、个人隐私等敏感项目。

✅ 验证：

在 TUI 中输入 /share 命令。
你会看到 OpenCode 询问你是否确认创建分享链接，因为模式是 manual。
如果你设置了 "share": "disabled"，输入 /share 后，OpenCode 会提示“分享功能已被禁用”。

第 4 步：管理密钥与敏感文件

🎯 目标：建立一套密钥管理规范，确保 API 密钥、Token 等敏感信息永远不会被写入 Git 仓库或被 OpenCode 意外读取。

📝 操作：

创建 .env.example 文件：在项目根目录创建一个名为 .env.example 的文件，只包含变量名，不包含真实值。
bash
```
# .env.example
OPENAI_API_KEY=YOUR_API_KEY_HERE
GITHUB_TOKEN=YOUR_GITHUB_TOKEN_HERE
DATABASE_URL=YOUR_DATABASE_URL_HERE
```

创建 .gitignore 文件：确保 .env 文件被 Git 忽略。

bash

# .gitignore
.env
.env.local
.env.production
node_modules/

配置 OpenCode 禁止读取 .env：我们在第 1 步的配置中已经设置了 "*.env": "deny"，现在再次确认这条规则生效。

✅ 验证：

在 TUI 中对 OpenCode 说：“读取项目根目录下的 .env 文件内容”。
OpenCode 应该会拒绝执行，并提示你没有权限读取该文件。

💡 提示：对于更高级的密钥管理，可以考虑使用系统的钥匙串访问（Keychain）或专门的密钥管理服务（如 HashiCorp Vault），并通过环境变量注入到 OpenCode 中。

第 5 步：配置团队级公共规则

🎯 目标：将团队必须遵守的公共配置（如权限规则、自定义命令）提交到 Git 仓库，实现版本控制和团队同步，而将个人配置（如 API Key、主题）留在本地。

📝 操作：

确定哪些文件需要版本化：
- opencode.json：项目核心权限和配置。
- .opencode/commands/：自定义命令。
- .opencode/agents/：自定义 Agent。
- AGENTS.md：Agent 使用说明。
- README.md：项目说明，包括如何使用 OpenCode。

将上述文件添加到 Git 并提交：

bash

$ git add opencode.json .opencode/ AGENTS.md README.md .gitignore
$ git commit -m "feat: 添加 OpenCode 团队公共配置"

个人配置留在本地：告诉团队成员，他们的个人 API Key 和主题配置应该放在全局的 opencode.json 中（通常在 ~/.config/opencode/），而不是项目配置里。
🤔 为什么要这样做？ 将公共配置版本化，可以确保团队所有成员使用相同的规则和命令，避免“在我机器上能跑”的尴尬。同时，个人密钥不进入 Git，是基本的安全底线。

✅ 验证：

运行 git log，你应该能看到刚才的提交记录。运行 git status，你应该看到工作区是干净的，没有未跟踪的 .env 文件。

第 6 步：安全接入 GitHub/GitLab 集成

🎯 目标：安全地配置 OpenCode 的 GitHub/GitLab 集成，并从一个只读任务开始测试，确保它不会意外修改代码。

📝 操作：

配置 API Key：将你的 GitHub Token 或 GitLab Token 存储在 CI/CD 的 Secrets 中（例如 GitHub Actions Secrets），而不是写在代码里。
发起只读任务：在 GitHub Issue 或 PR 中，使用 /opencode 或 /oc 命令触发 OpenCode，并明确要求它不要修改文件。
markdown
```
/opencode explain this issue. Do not change files.
```
或者：
markdown
```
@opencode review this merge request. Do not change files.
```

✅ 验证：

等待 OpenCode 执行完毕。你应该看到它输出了对 Issue 或 PR 的解释或审查意见，但不会在仓库中创建任何新的提交或文件修改。

⚠️ 常见错误： ❌ 错误做法：在第一次集成时就允许 OpenCode 提交代码。 ✅ 正确做法：先从只读任务开始，确认它能正确理解上下文、不会误操作后，再逐步开放小范围的写权限（如修复文档中的拼写错误）。

进阶技巧（可选）

网络代理配置：如果你的团队使用企业代理，可以在 OpenCode 的配置或环境变量中设置 HTTPS_PROXY、HTTP_PROXY 和 NO_PROXY。务必确保 localhost 和 127.0.0.1 在 NO_PROXY 中，以避免内部通信出错。
MCP 工具的权限控制：对于 MCP 服务器，可以像控制文件系统一样，在 opencode.json 中明确哪些 MCP 工具是 allow、ask 或 deny 的。

常见问题 (FAQ)

Q1: 配置了 "*": "ask" 后，每次操作都弹窗，太烦了怎么办？A: 这是最安全的起点。当你熟悉了 OpenCode 的行为后，可以逐步将一些你完全信任的低风险操作（如运行 npm install）从 ask 改为 allow。安全是一个渐进的过程，不是一次性的开关。

Q2: 如果不小心把包含密钥的会话分享出去了怎么办？A: 立即在 TUI 中输入 /unshare 命令。这会移除分享链接并删除服务器上的会话数据。同时，你应该立即轮换（Rotate）泄露的密钥。

Q3: 团队中有人不遵守 opencode.json 的配置怎么办？A: 将 opencode.json 设为 Git 仓库的一部分，并通过 Code Review 来确保任何修改都经过团队同意。如果有人使用自己本地的配置覆盖了项目配置，这属于流程问题，需要团队内部沟通解决。

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

权限配置：通过 opencode.json 将默认权限从开放改为 ask，并对敏感文件和危险命令设置 deny，实现了最小权限原则。
外部目录管控：精确授权 OpenCode 可以访问的外部目录，并区分读写权限。
分享管理：理解了 manual、auto、disabled 三种分享模式，并能根据项目需求进行选择。
密钥安全：掌握了 .env + .gitignore 的标准密钥管理流程，并配置 OpenCode 禁止读取敏感文件。
团队协作：学会了将公共配置版本化，实现团队规则的一致性和可追溯性。
安全集成：了解了 GitHub/GitLab 集成应从只读任务开始的安全接入方法。

下一步

如果你想继续深入，建议学习：

📖 工具、MCP、LSP 与格式化器：学习如何进一步收紧工具调用的安全边界。
📖 GitHub 集成官方文档：深入了解 GitHub 集成的所有配置选项。

💡 练习任务：尝试为你的一个真实项目（非敏感）配置本教程中的所有安全设置，并让 OpenCode 执行一次只读的代码审查任务。这是巩固知识的最佳方式。

yaml


## 相关文档

- [OpenCode 企业版部署与配置实战教程](/docs/tuan-dui-xie-zuo/opencode-qi-ye-ban-bu-shu-yu-pei-zhi-shi-zhan-jiao-cheng.html)

OpenCode 安全配置与团队协作实战教程 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

1. 准备一个测试项目 ​

第 1 步：配置权限基线，从 ask 开始 ​

第 2 步：管控外部目录访问 ​

第 3 步：配置会话分享模式 ​

第 4 步：管理密钥与敏感文件 ​

第 5 步：配置团队级公共规则 ​

第 6 步：安全接入 GitHub/GitLab 集成 ​

进阶技巧（可选） ​

常见问题 (FAQ) ​

总结 ​

下一步 ​

OpenCode 安全配置与团队协作实战教程

你将学到什么

最终效果

前置准备

1. 准备一个测试项目

第 1 步：配置权限基线，从 `ask` 开始

第 2 步：管控外部目录访问

第 3 步：配置会话分享模式

第 4 步：管理密钥与敏感文件

第 5 步：配置团队级公共规则

第 6 步：安全接入 GitHub/GitLab 集成

进阶技巧（可选）

常见问题 (FAQ)

总结

下一步