08 · 安全、分享与团队使用

OpenCode 能读写项目、执行命令、连接模型、调用工具、接入 GitHub/GitLab，也能分享会话。这些能力都很实用，但它们本质上也是安全边界。

这一篇解决收尾问题：把 OpenCode 从“我本机能跑”推进到“真实项目和团队能长期用”。读完以后，你应该能建立一条最小安全基线：权限怎么配，密钥放哪里，会话能不能分享，网络和 MCP 怎么控，团队公共配置哪些该版本化。

安全边界总图

OpenCode 的安全不是一个开关，而是一组边界同时成立。

flowchart TB
  Project["项目工作区"] --> Permission["permission<br/>读写 / bash / 外部目录"]
  Project --> Secrets["密钥边界<br/>auth store / env / CI secrets"]
  Project --> Provider["模型 provider<br/>数据发送到哪里"]
  Project --> Share["/share<br/>公开链接和留存"]
  Project --> MCP["MCP / web / CI<br/>外部系统上下文"]
  Project --> Team["团队配置<br/>Git 版本化和 review"]

  style Permission fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
  style Secrets fill:#fee2e2,stroke:#ef4444
  style Share fill:#fef3c7,stroke:#f59e0b
  style Team fill:#dcfce7,stroke:#22c55e

任何一条边界说不清，都不要把 OpenCode 放进敏感项目或自动化流程。

1. 先把权限当成产品功能

AI coding agent 的权限不是“阻碍效率”，而是让你敢把它放进真实项目。

使用 OpenCode 时，至少要明确：

• 哪些目录可以改。
• 哪些命令可以跑。
• 是否允许联网。
• 是否允许调用 MCP。
• 是否允许分享会话。
• 是否允许读取密钥文件。
• 是否允许发布或部署。

这些规则应该写进项目配置或团队文档，而不是靠每次口头提醒。

2. 权限基线从 ask 开始

OpenCode 的权限动作是三类：

官方 Permissions 文档说明，如果没有显式配置，大多数权限默认偏开放；doom_loop 和 external_directory 默认 ask，.env 文件默认拒绝读取。真实项目不要只依赖默认值。

一个保守的项目级起点：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    },
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "rm *": "deny",
      "git push*": "deny"
    },
    "webfetch": "ask",
    "websearch": "ask",
    "skill": "ask",
    "external_directory": "ask"
  }
}

这不是唯一正确配置，但体现了原则：只读可以更开放，写入和 shell 要确认，危险命令先拒绝。

3. 外部目录要单独治理

OpenCode 从项目工作目录启动。访问工作区外路径时，会触发 external_directory。这不是小事，因为工作区外可能有其他项目、个人文件、下载目录或凭据。

不要为了省事允许整个 home 目录。更稳的写法是允许少数可信路径，并单独限制 edit：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/shared-docs/**": "allow"
    },
    "edit": {
      "~/projects/shared-docs/**": "deny"
    }
  }
}

允许读取不代表允许修改。这个区分对团队知识库、公共素材目录和凭据目录尤其重要。

4. 分享功能的边界

OpenCode 支持分享会话，生成公开链接。这个能力适合协作和求助，但默认要按“公开泄露风险”处理。

官方 Share 文档说明：

• /share 会创建公开 URL，链接形式是 opncd.ai/s/<share-id>，自动复制到剪贴板。
• 拿到链接的人都可以访问共享会话——分享出去等于公开。
• shared conversation 会同步到 OpenCode 的服务器，包含完整对话历史 / 全部消息 / session metadata。
• 三种模式：manual（默认，按 /share 触发）/ auto（每次新会话自动分享，慎用）/ disabled（彻底关闭）。
• /unshare 会移除分享链接并删除服务器上相关会话数据。
• 企业部署可以选择整体禁用、限制 SSO 用户、或自托管。

敏感项目建议直接禁用：

{
  "$schema": "https://opencode.ai/config.json",
  "share": "disabled"
}

普通项目也建议显式保持手动：

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

分享前必须检查：

• 对话里是否包含源码片段。
• 是否包含文件路径、客户名、业务数据。
• 是否包含 API key、token、cookie、账号信息。
• 是否包含未公开产品策略。
• 是否包含内部报错日志。

如果不确定，就不要分享。需要协作时，先整理一份脱敏摘要，再分享。

5. 数据边界要分清

官方 Enterprise 文档说明，OpenCode 默认不存储代码或上下文数据，处理发生在本地或通过直接 API 调用发送到你的 AI provider。这里仍然有三条实际边界：

所以安全问题不能只问“OpenCode 是否开源”。你还要问：

• provider 是否可信？
• 是否走内部 AI gateway？
• 是否禁用了分享？
• MCP 是否会把本地内容带到外部系统？
• CI 日志是否会输出敏感内容？

6. 网络访问

网络能力会扩大 agent 的行动范围。它可能访问官方文档、下载依赖、调用外部 API，也可能把本地信息带到不该去的地方。

比较稳的策略：

默认本地优先
需要查官方资料时再临时放开
需要调用内部系统时走明确 MCP 或 API
生产服务写操作必须人工确认

不要让 agent 在没有说明的情况下自由联网排障。

企业代理环境还要处理 HTTPS_PROXY、HTTP_PROXY、NO_PROXY 和自定义 CA。尤其要把 localhost、127.0.0.1 放进 NO_PROXY，避免本地 TUI/server 通信被代理绕坏。

7. 密钥管理

模型 API key、GitHub token、Cloudflare token、数据库连接串都不应该写进仓库配置。

推荐方式：

• 使用环境变量。
• 使用系统 keychain 或 secret manager。
• .env 加入 .gitignore。
• 项目 README 只写变量名，不写真实值。
• 让 agent 修改配置模板，不直接接触真实密钥。

如果 agent 已经读到了真实密钥，不要继续把整段对话分享出去。

密钥相关的文件建议这样分工：

不要让 agent “顺手帮你整理凭据”。涉及密钥时，尽量让它改模板和说明，不直接读取真实值。

8. 团队公共配置怎么版本化

团队使用 OpenCode 时，最有价值的不是每个人都单独配置，而是把公共部分版本化：

opencode.json
.opencode/commands/
.opencode/agents/
.opencode/skills/
AGENTS.md
README

这些文件应该回答：

• 这个项目怎么跑测试。
• 常见任务用哪些命令。
• 哪些目录禁止自动改。
• 什么时候必须人工 review。
• 什么时候允许 agent 自主提交 patch。
• 哪些 MCP/skill/plugin 被允许。
• 分享功能是 manual 还是 disabled。

个人配置不要强行同步给团队。比如个人 provider、个人主题、个人 keybind、个人全局 skill，可以留在全局配置；项目级配置只写团队必须一致的部分。

9. GitHub/GitLab 集成先只读试跑

OpenCode 可以接入 GitHub issue / PR 和 GitLab issue / MR。官方文档说明，GitHub 集成通过 /opencode 或 /oc 评论触发，并运行在 GitHub Actions runner；GitLab 集成运行在 GitLab Runner 上。

接入前先确认：

• API key 放在 GitHub Actions Secrets 或 GitLab CI/CD Variables。
• workflow / pipeline 只给必要权限。
• 第一次任务只读，不直接提交代码。
• 公开仓库要检查日志和评论是否会暴露敏感信息。
• Runner 的网络、依赖、模型 provider 都可用。

第一次测试建议：

/opencode explain this issue. Do not change files.

或：

@opencode review this merge request. Do not change files.

确认能读上下文、能输出解释、不会误提交以后，再尝试小范围文档或 typo 修复。

10. 最小安全基线

把 OpenCode 用进真实项目，至少执行这条基线：

1. 第一次任务只读。
2. 第一次写操作限定单文件。
3. 所有大范围改动先看计划。
4. 涉及密钥、账号、支付、部署、数据删除必须人工确认。
5. 分享会话前默认脱敏；敏感项目直接 share: "disabled"。
6. 团队公共配置提交到 Git，个人密钥留在本机。
7. CI 集成先从只读 prompt 开始，不直接给写权限。
8. MCP 和 custom tool 先启用少数必要项，不把生产写操作自动放开。

做到这些，OpenCode 才能从“能跑”进入“能长期使用”。

11. 怎么验收

你可以用 8 个问题检查是否过关：

• 是否显式配置了项目权限，而不是依赖默认值？
• .env、token、数据库连接串是否不会被读取或分享？
• 外部目录是否没有放开整个 home？
• 分享模式是否符合项目敏感度？
• provider、MCP、CI 日志的数据边界是否说得清？
• 团队公共配置是否可 review、可回滚？
• GitHub/GitLab 集成是否先通过只读任务验证？
• 高风险动作是否必须人工确认？

12. 完成这一组后怎么继续

上一篇先确认工具边界：工具、MCP、LSP 与格式化器。

到这里，OpenCode 的理解篇已经走完：定位、安装、TUI、配置、扩展、模型、工具、安全。下一步不要继续堆配置，应该回到真实项目里验证三件事：

只读理解是否准确
小范围改动是否可控
团队配置是否可复用

如果这三件事稳定，再考虑接更复杂的 MCP、CI 集成、插件或企业网关。

接下来去哪

官方资料

• Permissions：https://opencode.ai/docs/permissions
• Share：https://opencode.ai/docs/share
• Enterprise：https://opencode.ai/docs/enterprise
• Network：https://opencode.ai/docs/network
• GitHub：https://opencode.ai/docs/github
• GitLab：https://opencode.ai/docs/gitlab