---
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 與格式化器](/zh-Hant/docs/opencode/understanding/07-tools-mcp-lsp)。

到這裡，OpenCode 的理解篇已經走完：定位、安裝、TUI、配置、擴充套件、模型、工具、安全。下一步不要繼續堆配置，應該回到真實專案裡驗證三件事：

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

如果這三件事穩定，再考慮接更復雜的 MCP、CI 整合、外掛或企業閘道器。

## 接下來去哪

<Cards>
  <Card title="許可權配置" description="把 allow、ask、deny、外部目錄和 Agent 級許可權落到專案配置裡。" href="/zh-Hant/docs/opencode/official/05-security/permissions" />
  <Card title="分享會話" description="單獨理解 `/share`、`/unshare`、公開連結和團隊預設策略。" href="/zh-Hant/docs/opencode/official/00-getting-started/share" />
  <Card title="工具、MCP、LSP" description="繼續收緊工具呼叫、外部系統、格式化和診斷工具的邊界。" href="/zh-Hant/docs/opencode/understanding/07-tools-mcp-lsp" />
  <Card title="GitHub 整合" description="把團隊自動化接入 CI 前，先從只讀評論觸發開始。" href="/zh-Hant/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)
