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