權限與工具管理

學習目標

• 認識 14+ 種內建工具的功能與用途
• 理解 allow / ask / deny 三種權限模式
• 學會全域權限與細粒度規則設定
• 掌握代理級覆寫與安全防護機制

內建工具總覽

opencode 提供一系列內建工具，讓代理能夠執行各種操作。這些工具可分別啟用或停用，也可以指定不同的權限行為。

工具	用途	說明
bash	Shell 指令執行	在專案環境中執行 Bash/PowerShell 指令
edit	檔案編輯	對已讀取的檔案進行精確的區塊取代
write	檔案寫入	建立新檔案或完整覆寫既有檔案
patch	修補檔案	以 diff 格式對檔案進行小幅修改
read	檔案讀取	讀取檔案內容（支援行數偏移與限制）
grep	內容搜尋	使用正規表達式搜尋檔案內容
glob	檔名搜尋	以 glob 模式匹配檔案路徑
lsp	語言伺服器	透過 LSP 取得語法分析與診斷資訊
skill	技能載入	載入 SKILL.md 定義的代理技能
todowrite	任務追蹤	寫入待辦事項清單供代理參考
webfetch	網頁擷取	從 URL 取得網頁內容並轉為 Markdown
websearch	網路搜尋	執行網路搜尋查詢（需對應提供商支援）
question	提問用戶	向使用者提問以釐清需求
task	子代理調度	啟動子代理平行處理獨立任務

三種權限行為

每個工具可以指派以下權限行為之一，決定代理何時需要徵求你的許可：

權限	行為	適用場景
allow	自動允許，不詢問	信任的唯讀工具如 read、glob
ask	執行前先提問用戶	可能有副作用的工具如 bash、write
deny	完全禁止使用	高風險或不需要的工具如 websearch

全域權限設定

在 opencode.json 中可設定全域工具權限，所有工具預設繼承這些規則：

{
  "permissions": {
    "allow": [
      "read",
      "glob",
      "grep",
      "lsp",
      "question"
    ],
    "ask": [
      "bash",
      "edit",
      "write",
      "patch",
      "webfetch",
      "skill",
      "todowrite",
      "task"
    ],
    "deny": [
      "websearch"
    ]
  }
}

未在清單中的工具將使用預設權限（通常是 ask）。

細粒度規則（物件語法）

除了簡單的陣列清單，你還可以使用物件語法對特定工具設定更精細的規則。這在 bash 工具的指令層級權限控制上尤其有用：

{
  "permissions": {
    "bash": {
      "allow": [
        "npm test",
        "npm run build",
        "git status",
        "git diff",
        "ls",
        "node --version"
      ],
      "ask": [
        "npm install",
        "git add",
        "git commit",
        "mkdir",
        "rm"
      ],
      "deny": [
        "rm -rf /",
        "sudo",
        "curl"
      ]
    },
    "write": "ask",
    "edit": "ask"
  }
}

當你對 bash 使用物件語法時，代理執行的指令會與規則進行前綴匹配。例如以 npm 開頭的指令會自動允許，而以 sudo 開頭的則完全禁止。

全域 vs 代理級覆寫

權限可以設定在兩個層級，下層會繼承並可覆寫上層：

1. 全域層級 — 在 opencode.json 的 permissions 區塊中設定，所有代理共用
2. 代理層級 — 在自訂代理定義中設定，僅影響該代理

範例：全域允許所有唯讀工具，但在自訂的 deploy-agent 中將 bash 設為 ask：

{
  "agents": {
    "deploy-agent": {
      "permissions": {
        "bash": "ask",
        "write": "ask",
        "edit": "ask",
        "read": "allow",
        "glob": "allow"
      }
    }
  }
}

安全防護機制

external_directory

預設情況下，opencode 限制代理只能操作專案目錄內的檔案。若需要允許代理存取專案外部的特定目錄（例如共享設定檔或暫存區），可使用 external_directory 設定：

{
  "permissions": {
    "external_directory": [
      "C:\\Users\\YourName\\.shared-config",
      "D:\\temp"
    ]
  }
}

doom_loop 防護

為防止代理陷入無限循環（例如不斷執行失敗的指令並重試），opencode 內建了 doom_loop 防護機制。當代理在短時間內重複執行相同操作且持續失敗時，系統會自動介入並終止循環。這個機制預設啟用，不需要額外設定。

實戰練習