Claude Code 自動跑任務前：Auto 權限模式、白名單與回合上限

v2.1.309：驗收設定檔與 sandbox 的實際邊界#

2026 年 10 月 22 日 UTC 發布的 v2.1.309修正 sandbox Bash 在每次命令前於隔離外執行 shell startup files、macOS denyWrite glob 經 symlink 未套用到真實位置，以及 sandbox 命令／自動接受的編輯可修改 --mcp-config 指定檔案等問題。另修正 print／SDK session 已停用的 MCP 被後續權限提示重新連上的路徑。

這些修正對依賴既有排程設定的讀者有直接影響：應核對真正啟動的 claude --version 與參數，重新啟動排程程序後再驗收，不能只看互動終端機更新成功。下面是尚未執行的驗收設計，適用於不含真實憑證、可拋棄的測試工作區：

• MCP 設定保護：準備只含測試內容的 MCP 設定，記錄原始雜湊。透過實際的 --mcp-config 入口啟動，分別要求受 sandbox 限制的 Bash 寫入及自動接受的編輯修改該檔。核對工具結果與檔案雜湊，測試後仍應與原檔一致；不要拿 production 設定測試。
• macOS symlink 路徑：以假檔案及 symlink 建立 denyWrite glob 的測試目標，分別要求經連結路徑與真實路徑寫入。兩次都要對照拒絕結果與內容；只測一般路徑不足以涵蓋本次修正。測試設定與 symlink 限定於 fixture，不改個人 dotfiles。
• 停用 MCP 的持續性：在 print／SDK 測試 session 停用測試 MCP，再觸發既定的無害權限詢問；確認之後的可用工具與測試服務連線紀錄沒有重新啟用。沒有服務端觀測資料時，應保留「未驗證連線」而非只靠模型口頭回答。

官方 sandbox 文件說明 sandbox 包覆 shell 命令，並提供 /sandbox Config 檢查解析後的限制。自己在一般 shell 執行測試、或從通常在 sandbox 外執行的 ! 入口輸入命令，都不能證明模型的 sandbox Bash 路徑受限。失敗後若改成隔離外重試，必須另記為不同入口。

v2.1.309 也將 sed -i 改為一般 Bash 詢問並按原命令執行；這類 Bash 編輯不由 /rewind 還原。驗收工作區應先留 Git checkpoint，再比較檔案差異；不要把 rewind 清單當成所有 shell 副作用的備份。

如果只有 Edit(path) deny，還要對照 permissions 的 redirect 檢查；v2.1.309 包含帶 subshell 的特定 redirect 修正。每項結果都應記下入口、規則來源、是否真正寫入與檔案前後差異，通過一個案例不能概括為全部 shell 語法都已驗證。

v2.1.284 之後先確認互動模式#

從 v2.1.284 起，互動式終端機和 VS Code session 若沒有指定權限模式，會以 Auto 啟動；明確設定的 permissions.defaultMode 仍然優先。這項 release note 指的是互動 session，不應直接推論到所有腳本或非互動呼叫。

Auto 不是 bypassPermissions。後者會略過 permission prompt，官方建議只在無法造成損害的隔離環境使用。若某個自動化依賴固定的 Plan 行為，像本文後面的 claude -p --permission-mode plan 範例一樣，請在該次執行明確指定 --permission-mode plan，不要仰賴安裝版本的互動預設。

若要檢查互動預設，先看團隊或個人的 settings 是否有 permissions.defaultMode，再用一個不含敏感資料的測試 repository 啟動互動 session，確認實際顯示的模式。需要統一管理 Auto 或 bypass 預設時，也要留意官方 settings precedence：project/local settings 不能設定這兩個模式，應在 user 或 managed settings 控制。

v2.1.302 的腳本預設不能從互動視窗推論#

v2.1.302 release notes指出，沒有指定權限模式的 claude -p 與 Agent SDK session，在第三方 provider、停用 telemetry 或全新安裝的情況，會以 default 啟動；明確指定 --permission-mode auto 仍維持 auto。這是帶條件的變更，不能簡化成所有腳本都改用 default，也不能從互動式視窗顯示 Auto 推論排程的模式。

因此，升級後若背景工作開始等待權限或停止，先記錄版本、provider、設定來源與實際啟動參數，確認是否依賴未指定的預設。不要直接補上 bypass。本文最後的 plan 範例已明確指定模式；既有要自動修改的腳本也應依核准的任務能力明確選擇模式。

可以在不含敏感資料的 fixture repository 做兩輪驗收：第一輪從真正的排程入口執行既有命令，保留工具決策與結束狀態；第二輪只加入已選定的 --permission-mode，保持 provider、任務與設定不變，再比較。prompt 可要求讀取指定測試檔，再執行一個事先設有 ask／deny 的無害命令，確認詢問或拒絕路徑符合預期。此流程尚未執行；模型自己說「我在 Auto」也不能取代工具決策紀錄。

Agent SDK 要另外核對呼叫端傳入的權限設定，不能以 terminal wrapper 的參數當證據。若排程無人可以回覆詢問，將等待或權限拒絕列為可辨識的未完成狀態，由排程外層設定逾時；--max-turns 限制的是回合，不能代替整個程序的牆鐘時間上限。不要因為沒有看到錯誤就直接重跑可能已有外部副作用的任務。

升到 v2.1.289，還要驗收拒絕規則的入口#

2026 年 10 月 3 日的 v2.1.289 release notes列出幾個與自動化直接相關的修正：受管理機器上的複合 shell 命令，局部 deny／ask 不應被使用者安裝 mod 的核准蓋過；sandbox auto-allow 下，帶展開值的環境變數前綴或前置變數賦值不應跳過 Bash deny／ask；IDE 中經 symlink 提及、修改或選取的檔案也應套用 Read deny。

這些是特定路徑的修正，不能解讀成所有外掛、shell 或 IDE 情境都已驗證。已有自動任務應先確認 claude --version，再在不含敏感資料的測試 repository 驗收實際使用的入口。以下是待執行的測試設計，本文沒有執行 Claude Code：

• 建立只含 permission-fixture 字樣的 blocked.txt，設定精確的 Read deny；分別要求直接讀取及透過 IDE 的 symlink 入口讀取，確認工具被擋下。不要用真實金鑰測試。
• 用 Bash(printf *) 作為測試 deny，要求執行單純的 printf、帶環境變數前綴的版本與前置賦值版本；若 production 開了 sandbox auto-allow，測試也應採相同條件。這些指令只能印出測試字串。
• 使用 ask 規則時，確認需要人工回覆的入口確實提出詢問；不要把它當成 deny。對 managed／mod 複合命令的情境，另記錄實際政策與 mod 版本，沒有該環境就標記未驗證。

前述 Bash 測試可要求 Claude 在 fixture 中嘗試以下無害命令，逐筆記錄是否被拒絕；不要自己在 shell 執行後，把字串輸出當成 Claude 權限已生效的證據：

1
printf '%s\n' 'permission-fixture'
2
TZ="$PWD" printf '%s\n' 'permission-fixture'
3
marker=fixture; printf '%s\n' 'permission-fixture'

Bash pattern 比對命令文字，不是整個程式的存取邊界。即使 Bash(printf *) 的上述測試通過，也不能推論絕對路徑、其他 shell wrapper 或另一個工具入口全被擋住。需要檔案與網路隔離時，仍要驗收 sandbox；拒絕清單不能取代隔離機制。

驗收紀錄應包含版本、命令原文、規則來源及工具是否執行。官方 permissions 文件說明規則依 deny、ask、allow 順序判定；可在 /permissions 查看來源。prompt 裡寫「不要讀」不能代替工具權限。

若某項拒絕規則沒有生效，先停用該自動流程並保留結果；不要以放寬 allow 或 bypass 來讓測試通過。較完整的唯讀診斷範圍可參考 Claude Code 本機日誌診斷。

先決定這次任務應有哪種能力#

先把任務切成三類，才不會一開始就給過大的權限。

這個分類不是產品保證，而是實務上的權限設計：先從最小集合開始，缺什麼再補，而不是讓 agent 先拿到完整終端機再希望它永遠不會誤用。

用白名單允許可預期的讀取工作#

Anthropic 文件說明，--allowedTools 可讓指定工具在不另外詢問的情況下執行；規則可對 Bash 指令使用 pattern。對只讀的工作，我會讓允許清單保持小而明確。

1
claude -p \
2
  --allowedTools "Read" "Bash(git status *)" "Bash(git diff *)" "Bash(git log *)" \
3
  "請檢查這個 PR 的變更，只列出風險，不要修改檔案。"

注意 pattern 是權限規則，不是安全審查的替代品。若命令需要網路、憑證或會改寫資料，就不應因為「看起來常用」而放進白名單。

用拒絕規則封住不能碰的操作#

--disallowedTools 可以移除整個工具，或拒絕特定 pattern。官方文件舉例指出，裸工具名稱會從模型可用工具中移除，而像 Bash(rm *) 的 scoped rule 只會拒絕符合的呼叫。

1
claude -p \
2
  --disallowedTools "Bash(rm *)" "Bash(git push *)" "Bash(curl *)" \
3
  "修正型別錯誤；只修改 src/，完成後執行 pnpm check。"

這裡的重點不是列出所有危險命令，而是先列出此任務不需要卻可能造成外部影響的類別，例如刪除、推送、下載或部署。真正需要這些動作時，改成單獨一步並交由人確認。

不要把跳過確認當作預設值#

--dangerously-skip-permissions 等同以 bypassPermissions 權限模式啟動。官方文件明確把它標成跳過 permission prompt 的選項；它適合隔離環境中的受控任務，不適合作為日常本機開發的預設。

如果只是要先釐清方案，可從 plan mode 開始：

1
claude --permission-mode plan \
2
  "先分析目前測試為何失敗，列出根因與預計修改檔案；不要修改。"

先拿到計畫，再以較窄的允許工具重新啟動實作，通常比在同一個 session 內逐步放寬權限更容易稽核。

非互動任務要限制 agent 回合數#

自動化最怕的不是一次失敗，而是無限制重試。Claude Code 的 --max-turns 可限制非互動模式的 agentic turns；為每種任務設定合理上限，並把到達上限視為「需要檢查」而非「再跑一次」。

1
claude -p \
2
  --max-turns 8 \
3
  --allowedTools "Read" "Edit" "Bash(pnpm check)" \
4
  "修正這個型別錯誤。完成標準：pnpm check 成功；若第 8 回合前無法完成，回報阻礙與目前 diff。"

回合上限要搭配完成條件才有意義。沒有驗證標準時，agent 可能很快停下卻沒有解決問題；沒有上限時，失敗的方向又可能被反覆嘗試。

額外資料夾要當成新的存取面#

--add-dir 會讓 Claude Code 能讀寫額外資料夾。官方文件也提醒，這些資料夾多數 .claude/ 設定不會被自動發現。實務上應把每個額外路徑當作一次新的權限審查：它是否包含 secrets、production 設定檔、客戶資料或其他 repository？

不確定時，先不要用 --add-dir。把需要的檔案複製到明確的工作區，或先以只讀報告確認必要性，再最小化新增路徑。

一個可拿來改的安全起點#

1
claude -p \
2
  --permission-mode plan \
3
  --max-turns 4 \
4
  --allowedTools "Read" "Bash(git status *)" "Bash(git diff *)" \
5
  --disallowedTools "Bash(rm *)" "Bash(git push *)" "Bash(curl *)" \
6
  "分析登入測試失敗的根因。不要修改檔案。輸出：
7
  1. 涉及檔案；2. 根因證據；3. 最小修正方案；4. 需要的人為決策。"

它的目標不是一次解完問題，而是先取得足以授權下一步的證據。確定修正範圍後，再另開一個只允許必要編輯與測試指令的 session。

這次要記住的事#

自動化的安全性不在於某一個神奇旗標，而在於任務是否分段、每段是否只取得必要權限，以及是否能在回合耗盡時留下可讀的失敗證據。把讀取、修改與外部動作拆開，日後回頭查問題也會容易得多。

常見問題#