---
title: "08 · 安全、分享与团队使用"
description: "使用 OpenCode 时如何控制权限、网络、会话分享和团队配置边界。"
verifiedAt: "2026-05-09"
---

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

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

> [!NOTE]
> **先给结论**：真实项目里不要默认全开权限；敏感项目建议 `share: "disabled"`；密钥只放本机凭据、环境变量或 CI secrets；团队共享规则进 Git，个人 token 不进 Git；GitHub/GitLab 集成先从只读任务试跑。

## 安全边界总图

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

```mermaid
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 的权限动作是三类：

| 动作 | 含义 | 适合场景 |
| --- | --- | --- |
| `allow` | 直接执行 | 低风险、高频、你完全理解的动作 |
| `ask` | 执行前询问 | 写文件、跑命令、联网、外部工具 |
| `deny` | 直接拒绝 | 密钥、生产、删除、危险外部目录 |

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

一个保守的项目级起点：

```jsonc
{
  "$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 要确认，危险命令先拒绝。

> [!TIP]
> **Ask 不等于麻烦**：审批弹窗是你理解 agent 行为的机会。第一次看到陌生命令，先让 OpenCode 解释它要做什么、影响哪些文件，再决定是否批准。

## 3. 外部目录要单独治理

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

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

```jsonc
{
  "$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 用户、或自托管。

敏感项目建议直接禁用：

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

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

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

分享前必须检查：

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

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

## 5. 数据边界要分清

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

| 边界 | 风险 |
| --- | --- |
| AI provider | 你的代码和上下文会发送给你选择的模型供应商 |
| `/share` | 共享会话会发送到 OpenCode 用于托管分享页面的服务 |
| MCP / web / CI | 外部工具、网络、Runner 可能看到额外上下文 |

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

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

## 6. 网络访问

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

比较稳的策略：

```text
默认本地优先
需要查官方资料时再临时放开
需要调用内部系统时走明确 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 已经读到了真实密钥，不要继续把整段对话分享出去。

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

| 内容 | 放哪里 |
| --- | --- |
| 真实 API key | 本机 auth store、环境变量、Keychain、secret manager |
| GitHub/GitLab CI token | Actions Secrets / CI/CD Variables |
| 变量名和示例 | `.env.example`、README、部署文档 |
| provider 选择和非敏感策略 | `opencode.json` |
| 内部服务 URL | 视敏感程度决定是否进项目配置 |

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

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

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

```text
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 都可用。

第一次测试建议：

```text
/opencode explain this issue. Do not change files.
```

或：

```text
@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 集成是否先通过只读任务验证？
- 高风险动作是否必须人工确认？

> [!TIP]
> **过关标准**：团队里任何人打开这个项目，都能知道 OpenCode 可以做什么、不能做什么，以及什么时候必须停下来让人审核。

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

上一篇先确认工具边界：[工具、MCP、LSP 与格式化器](/docs/opencode/understanding/07-tools-mcp-lsp)。

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

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

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

## 接下来去哪

<Cards>
  <Card title="权限配置" description="把 allow、ask、deny、外部目录和 Agent 级权限落到项目配置里。" href="/docs/opencode/official/05-security/permissions" />
  <Card title="分享会话" description="单独理解 `/share`、`/unshare`、公开链接和团队默认策略。" href="/docs/opencode/official/00-getting-started/share" />
  <Card title="工具、MCP、LSP" description="继续收紧工具调用、外部系统、格式化和诊断工具的边界。" href="/docs/opencode/understanding/07-tools-mcp-lsp" />
  <Card title="GitHub 集成" description="把团队自动化接入 CI 前，先从只读评论触发开始。" href="/docs/opencode/official/06-integrations/github" />
</Cards>

## 官方资料

- Permissions：[https://opencode.ai/docs/permissions](https://opencode.ai/docs/permissions)
- Share：[https://opencode.ai/docs/share](https://opencode.ai/docs/share)
- Enterprise：[https://opencode.ai/docs/enterprise](https://opencode.ai/docs/enterprise)
- Network：[https://opencode.ai/docs/network](https://opencode.ai/docs/network)
- GitHub：[https://opencode.ai/docs/github](https://opencode.ai/docs/github)
- GitLab：[https://opencode.ai/docs/gitlab](https://opencode.ai/docs/gitlab)
