OpenCode怎麼用？Build、Plan、Permissions與安全工作流

OpenCode是一套開源、終端機優先的AI Coding Agent。它能讀取Repository、搜尋程式、建立Todo、修改檔案、執行Shell、使用LSP、Skills、MCP與自訂Tools，並透過Build、Plan與Subagents建立不同權限和工作方式。

OpenCode的主要優勢是多Provider、開放設定和細粒度Permission。可靠使用仍要把Task Scope、工作樹、Tests、Sandbox和人工Review放在模型之外；allow、ask、deny只是Tool層決策，不是完整OS隔離。

重點快讀

OpenCode內建Build與Plan兩個主要Agent。
Build適合實作；Plan預設更偏向讀取、分析和規劃。
可建立Primary Agent與Subagent，分別設定Prompt、Model和Permission。
Permission採allow、ask和deny三種結果。
從v1.1.1起，舊版tools布林設定已整合進permission。
Auto Mode只自動批准原本需要Ask的操作，明確Deny仍會生效。
支援75家以上Provider、OpenAI相容Endpoint與本地模型。
Plugins可註冊Hooks、Tools與整合，具完整程式執行風險。
Project Instructions、Skills、MCP和Plugins都要版本化與審查。

安裝與初始化

安裝方式依官方當前套件和作業系統選擇。啟動後先連接Provider，再進入Repository初始化專案設定：

如果尚未完成環境準備，可先參考OpenCode安裝指南（macOS、Linux、Windows、Node.js與Bun），確認安裝路徑後，再回到/connect與/init。

cd /path/to/project
opencode

# In the TUI
/connect
/init

/connect加入Provider Credential，/init協助建立專案指令。Credential不應寫進Repository、Prompt或Plugin原始碼。

Build和Plan怎麼分工？

Agent	主要用途	建議Permission
Plan	理解程式、建立方案、Review和風險分析	Edit deny、Bash ask或窄Allow
Build	寫檔、Patch、測試與實作	Edit ask／allow、危險Bash deny
Custom Primary	特定團隊工作模式	依Task設定
Subagent	研究、測試、文件或Code Review	比主Agent更窄

Agent名稱不形成安全邊界。Plan如果仍被允許執行高權限Custom Tool，就可能改變外部狀態；真正限制由Permission、Tool實作、Sandbox和身份共同形成。

建立自訂Agent

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Read-only security and maintainability review",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "permission": {
        "edit": "deny",
        "webfetch": "deny",
        "bash": {
          "*": "ask",
          "git diff*": "allow",
          "git log*": "allow"
        }
      }
    }
  }
}

Agent也可以使用Markdown檔案定義，放在全域或專案Agent目錄。Description要清楚，主Agent才能選擇正確Subagent；Prompt則應列出Task、輸出、禁止事項和驗收。

Permission系統

結果	行為
allow	不需核准直接執行
ask	執行前要求使用者批准
deny	阻擋Tool或符合Pattern的操作

Permission可以控制read、edit、glob、grep、list、bash、task、external_directory、todowrite、webfetch、websearch、lsp、skill與MCP Custom Tool等。使用Object Syntax可以按檔案、命令與Tool名稱建立細粒度規則。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "external_directory": "deny",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "git push*": "deny",
      "rm *": "deny"
    },
    "mymcp_*": "ask"
  }
}

規則按Pattern匹配，文件目前說明最後一條匹配規則生效，因此一般Wildcard放前面，具體例外放後面。設定後要用實際命令測試，避免Pattern和參數不一致。

Auto Mode的邊界

opencode --auto

opencode run --auto "Refactor this module"

Auto Mode會自動批准原本為Ask的Permission，明確Deny仍然生效。正式自動化應先把不可接受行為寫成確定性Deny，而不是期待模型自行避開。

允許Read、Search和局部Tests。
拒絕Git Push、Deployment和外部目錄。
正式資料、付款和刪除永遠Deny或人工。
在Container或可丟棄Worktree執行。
設定最大時間、Token和Tool次數。

Provider與模型

OpenCode使用AI SDK與Models.dev支援大量Provider，也能接OpenAI相容服務和本地模型。Provider Credential可透過/connect建立，模型使用provider/model-id格式。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Local Gateway",
      "options": {
        "baseURL": "http://localhost:1234/v1",
        "apiKey": "{env:LOCAL_MODEL_KEY}"
      },
      "models": {
        "coder": {
          "name": "Local Coder",
          "limit": {
            "context": 131072,
            "output": 16384
          }
        }
      }
    }
  },
  "model": "local/coder"
}

確認Endpoint使用Chat Completions或Responses。
設定正確Context和Output Limit。
測Tool Calling、Streaming和錯誤碼。
Provider使用Enabled／Disabled Allowlist。
模型更新後重跑Repository Eval。

Project Instructions

opencode.json可以透過instructions載入CONTRIBUTING、Guidelines或其他規則。指令檔適合保存Repository架構、命令、Coding Convention與驗收，不放動態Secrets和大量知識。

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/architecture.md",
    ".opencode/rules/*.md"
  ]
}

Skills與MCP

Skill Tool可以按需載入SKILL.md；MCP則連接外部Tools與Resources。兩者都受Permission控制，並應限制名稱、來源和權限。

Skill保存程序，不保存動態Credential。
MCP Tool使用Wildcard或精確名稱設定Ask／Deny。
未知Server預設不啟用。
外部內容不能改變System Policy。
寫入Tool使用Plan、Apply與Verify。
每次外部副作用保存Resource ID。

Plugins

OpenCode Plugin是JavaScript或TypeScript模組，可以從專案、全域目錄或npm載入。Plugin可使用Hook修改Tool參數、加入整合、處理Session事件或建立自訂行為。

專案Plugin：.opencode/plugins/。
全域Plugin：~/.config/opencode/plugins/。
npm Plugin透過Config載入。
Plugin可以使用Bun Shell和外部依賴。
Hook包含Tool Before／After、Permission、Session、File與Todo事件。

npm Plugin會在啟動時由Bun安裝，代表Package和Dependency具有供應鏈風險。正式環境固定版本、審查原始碼、限制Network並測試Hook故障。

Session與分享

每個Task使用獨立Session。
Session保存Prompt、Tool、Diff和狀態。
Compaction前把重要決策寫入檔案。
分享預設使用Manual，不自動公開。
分享前檢查程式碼、Secrets和內部URL。
敏感Session設定Retention和Delete。

Plugin也能接收Session Created、Compacted、Deleted、Error、Idle與Updated等事件，用於Audit和Lifecycle控制。

一條安全工作流

確認乾淨工作樹、Base Commit和測試基線。
使用Plan Agent理解程式和提出範圍。
人工確認Task Contract和Changed Files。
切換Build Agent進行Small Patch。
每批執行局部Tests和Diff Review。
完成後執行完整CI和Security Scan。
由Code Owner決定Commit、Push和Merge。
保存Session、結果和Rollback。

Small Patch與Failing Test方法可閱讀AI Coding怎麼用Small Patch降低失控？。

適合哪些人？

需要開源Terminal Coding Agent。
希望使用多家Provider和本地模型。
需要按Agent設定不同Model和Permission。
要以Plugin、MCP與Skill擴充。
希望在CLI、Desktop、GitHub Action中使用同一設定。
已有Container、Tests和Secret治理能力。

需要成熟Cloud Task、集中企業管理與開箱即用環境時，Codex、Cursor或Oz可能更直接。完整比較可閱讀AI Coding Agent怎麼選？。

常見問題

Build和Plan是安全邊界嗎？

不是。安全邊界由Permission、Tool、Sandbox、身份和人工Gate共同形成。

Auto Mode會忽略Deny嗎？

不會。Auto Mode只自動批准原本需要Ask的操作，明確Deny仍會阻擋。

OpenCode可以使用本地模型嗎？

可以，透過Provider和OpenAI相容Endpoint設定。模型需要穩定Tool Calling和足夠Context。

官方資料與延伸閱讀

OpenCode把多Provider、專用Agent、細粒度Permission、Plugins與Terminal工作流放進開源產品。真正可靠的使用方式，是用Plan縮小範圍、用Build完成Small Patch，再以Tests、Sandbox和人工Review決定是否進入主線。

OpenCode怎麼用？Build／Plan Agents、Permissions、Skills與MCP安全工作流