本文最初發表於 Unattended。以下是 Claude Code AI 代理防護機制的一個實用範例。您可以使用 .claude/settings.json 中的拒絕規則來阻擋危險工具,並利用以結束代碼 2 結束的 PreToolUse 鉤子來捕捉這些規則可能遺漏的破壞性指令,同時透過 --max-turns 和 --max-budget-usd 參數來限制迴圈和花費。
每一層防護都涵蓋不同的失敗情境,它們共同作用,讓排程的任務無需人工監看也能順利執行。
本文介紹如何為 Claude Code AI 代理設定安全防護機制,以確保自動化任務安全執行。透過拒絕規則、PreToolUse 鉤子以及 CLI 參數(如 --max-turns 和 --max-budget-usd),可有效防範破壞性指令、無限迴圈和成本超支等問題。這些分層防護措施讓無人值守的代理運作更加可靠。

本文最初發表於 Unattended。以下是 Claude Code AI 代理防護機制的一個實用範例。您可以使用 .claude/settings.json 中的拒絕規則來阻擋危險工具,並利用以結束代碼 2 結束的 PreToolUse 鉤子來捕捉這些規則可能遺漏的破壞性指令,同時透過 --max-turns 和 --max-budget-usd 參數來限制迴圈和花費。
每一層防護都涵蓋不同的失敗情境,它們共同作用,讓排程的任務無需人工監看也能順利執行。
Anthropic 表示,Claude Code 的鉤子能提供「確定性控制:某些動作總是會發生,而不是依賴 LLM 選擇執行它們」。因此,以鉤子形式編寫的防護機制不依賴於模型記住指令。那麼,哪種選項適合您呢?
第一個正確的防護機制取決於您目前如何運行 Claude Code。從適合您的情況開始,然後再逐步添加其他防護。對於初學者、僅限互動式會話的使用者,應先設定 .claude/settings.json 中的拒絕規則;對於日常工作、cron 或 CI 任務,則應設定 --permission-mode dontAsk 和 --max-turns;如果您曾遇到破壞性指令洩漏,則需要 PreToolUse 阻擋鉤子;而預算緊張、使用 API 金鑰計費的使用者,則應設定 --max-budget-usd 和 Console 工作區花費上限。
這些選擇的原因是:拒絕規則無需成本,適用於每個會話。dontAsk 可防止無人值守的執行停滯。鉤子可以匹配規則無法匹配的模式。預算上限則能阻止您可能從帳單中發現的單一失敗。
在 Claude Code 中,AI 代理防護機制是什麼樣子?在 Claude Code 中,防護機制是限制代理動作、運行時間和花費的權限規則、鉤子腳本或 CLI 上限。您會發現,大多數關於此查詢的防護機制解釋器會將防護機制分為輸入、輸出和系統級別類型,然後使用聊天機器人範例,例如個人身份資訊(PII)的編輯或銀行轉帳批准。這種框架適用於面向客戶的機器人。
一個在凌晨 3 點運行的程式碼代理會以其他方式失敗,因此本指南圍繞其中三種失敗情境進行組織:破壞性指令(例如 rm -rf、git push --force、git reset --hard),可透過拒絕規則和 PreToolUse 鉤子防範;失控迴圈(代理不斷重試失敗的修復長達數小時),可透過 --max-turns 和工具呼叫計數器鉤子防範;以及成本飆升(一個隔夜任務燒掉一週的預算),可透過 --max-budget-usd 和花費上限防範。
還有一個「過早完成」的失敗情境,即代理在測試仍失敗時停止,這可透過 Stop 鉤子解決。
如果您之前沒有設定過鉤子,請先閱讀《Claude Code Hooks Lifecycle: Every Event, Explained》。它會說明 PreToolUse 和 Stop 鉤子何時觸發。
如何使用權限規則阻擋破壞性指令?Claude Code 的權限規則位於 .claude/settings.json 中的 permissions.allow、ask 和 deny 陣列中。拒絕規則會在匹配的工具呼叫運行之前將其阻擋。
步驟 1:建立專案設定檔。在您的儲存庫根目錄中,如果 .claude/settings.json 不存在,請建立它。貼上以下起始點並更改指令以匹配您的堆疊:
```json
{
"permissions" : {
"allow" : [
"Bash(npm run test *)",
"Bash(npm run lint *)",
"Bash(git status *)",
"Bash(git diff *)",
"Bash(git commit *)"
],
"ask" : [
"Bash(git push *)"
],
"deny" : [
"Bash(rm -rf *)",
"Bash(git push --force *)",
"Bash(git reset --hard *)",
"Read(./.env)",
"Read(./.env.*)",
"Edit(./.env)"
]
}
}
```
提交此檔案,以便每台機器和每個排程任務都使用相同的規則。權限文件指出,您可以「將權限設定提交到版本控制以共享它們」。
步驟 2:正確使用萬用字元。尾隨的 * 將規則變為前綴匹配。無頭模式文件警告說,「* 前面的空格很重要」:Bash(git diff*) 也會匹配 git diff-index。
常見錯誤:信任範圍限制的拒絕規則來捕捉所有變體。CLI 參考資料指出,像 Bash(rm *) 這樣的範圍限制規則「只拒絕按原樣匹配的呼叫」。例如,Bash(rm -rf *) 不會匹配 rm -r -f build/ 或 find . -delete。
解決方法是下一節中的鉤子,它會讀取實際的指令字串並可以匹配多個模式。另請注意 git push 的 ask 規則。在沒有權限主機的 -p 運行中,無頭模式文件指出,會提示的請求「無論如何都會被拒絕」。因此在無人值守的運行中,ask 實際上意味著「永不」。這通常是您對推送操作所希望的。
如何編寫一個阻止危險指令的鉤子?Claude Code 的 PreToolUse 鉤子會在每個匹配的工具呼叫之前運行。如果腳本以結束代碼 2 結束,則該呼叫將被阻擋。鉤子參考資料是這樣說的:「結束代碼 2 是鉤子發出『停止,不要執行此操作』信號的方式。」
步驟 1:儲存腳本。將此腳本儲存為 .claude/hooks/block-destructive.sh 並執行 chmod +x。它需要安裝 jq。
```bash
#!/bin/bash
cmd=$(jq -r '.tool_input.command // empty')
if echo "$cmd" | grep -Eiq \
'rm +-[a-z]r[a-z] -?[a-z]f|rm +-r +-f|find .* -delete|git +push .(--force|-f)|git +reset +--hard|git +clean +-[a-z]f|drop +(table|database)|terraform +destroy'; then
echo "Blocked by guardrail: '$cmd' matches a destructive pattern. Use a safer alternative or leave a note for a human." >&2
exit 2
fi
exit 0
```
步驟 2:註冊它。在與 permissions 相同的設定檔中添加一個 hooks 區塊。這遵循鉤子參考資料中的結構:
```json
{
"hooks" : {
"PreToolUse" : [
{
"matcher" : "Bash",
"hooks" : [
{
"type" : "command",
"command" : "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh"
}
]
}
]
}
}
```
步驟 3:驗證。在儲存庫中啟動 claude 並輸入 /hooks。檢查您的腳本是否出現在 PreToolUse 下。成本文件描述了其範例鉤子的相同檢查。要求 Claude 在一個臨時資料夾上運行 rm -r -f tmp/。該呼叫應該會被阻擋。
常見錯誤:腳本不可執行(chmod +x 可修復)、cron 主機上缺少 jq,或者匹配器是小寫的 bash。匹配器會作為 JavaScript 正規表達式進行測試,因此大小寫很重要(鉤子參考資料)。有關相同風格的另外六個腳本,請參閱《Claude Code Hooks Examples: 7 Copy-Paste Scripts》。
如何在無人值守的運行中阻止失控迴圈?Claude Code 的 --max-turns 參數會限制列印模式下的代理回合數。CLI 參考資料明確指出「預設沒有限制」。請在每個排程任務上設定它。
cron 指令。這是一個結合了上限的 cron 安全調用:
```bash
claude -p "Run the test suite, fix failing tests in src/, and commit the fix" \
--permission-mode dontAsk \
--permission-prompts none \
--max-turns 30 \
--max-budget-usd 3.00 \
--output-format json
```
根據官方文件,每個參數的作用如下:--permission-mode dontAsk:「Claude Code 拒絕所有會提示的呼叫,這對於鎖定的 CI 運行很有用」(無頭模式文件)。您的允許規則仍然適用。--permission-prompts none:告知 Claude 沒有人可以批准請求,並且不要重試,這樣它就不會浪費回合數再次詢問。
這需要 v2.1.259 或更高版本(無頭模式文件)。--max-turns 30:當達到限制時,運行「會以錯誤結束」(CLI 參考資料)。您的腳本可以根據非零結束代碼進行分支。數字 30 是一個範例。您可以透過查看正常成功運行所需的回合數並增加一個餘裕來選擇它。
第二層:計算工具呼叫。回合數和工具呼叫是不同的東西,因此一個計算每個會話工具呼叫數的鉤子可以作為您的後備。此範例使用 session_id,每個鉤子都會在其輸入中收到它:
```bash
#!/bin/bash
input=$(cat)
sid=$(echo "$input" | jq -r '.session_id')
f="/tmp/claude-toolcalls-$sid"
n=$(( $(cat "$f" 2>/dev/null || echo 0) + 1 ))
echo "$n" > "$f"
if [ "$n" -gt 150 ] ; then
echo "Tool-call limit reached. Stop, summarize progress, and list what is unresolved." >&2
exit 2
fi
exit 0
```
將其註冊在 PreToolUse 下,匹配器為 .*,以便計算每個工具。如果運行比您預期的更早停止,請查閱《Why Claude Code Stops Mid-Automation (and How to Fix It)》。您自己的防護機制可能是原因。
Stop 鉤子:不要讓它在測試失敗時退出。Stop 鉤子可以透過返回 {"decision": "block", "reason": "..."} 將 Claude 送回工作(鉤子參考資料)。請務必先檢查 stop_hook_active,否則鉤子可能會無限期地將 Claude 彈回:
```bash
#!/bin/bash
input=$(cat)
[ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ] && exit 0
if ! npm test --silent > /dev/null 2>&1 ; then
echo '{"decision":"block","reason":"Tests still fail. Fix them, or explain why they cannot be fixed, before stopping."}'
fi
exit 0
```
如何限制每次運行的 Claude Code 成本?Claude Code 的 --max-budget-usd 參數會在估計的 API 花費達到您的上限時停止列印模式運行。將其視為軟性上限,而非精確上限。CLI 參考資料給出了兩個注意事項。上限是根據客戶端估計值檢查的,該估計值「可能與您的帳單不同」,並且「花費可能會超過上限,因此請預留緩衝空間」。子代理的花費也計入其中(CLI 參考資料)。
就規模而言,Anthropic 報告稱,在企業部署中,平均「每個活躍開發者每天約 13 美元」。這是互動式使用的平均值,不是自動化的數字,但它是一個有用的健全性檢查。一個隔夜任務如果花費超過人類一整天的工作量,很可能正在無限迴圈。實用的分層防護,從最便宜到最強:添加 --output-format json 並從每次運行中記錄 total_cost_usd(無頭模式文件)。
每週閱讀日誌。將 --max-budget-usd 設定為您典型運行成本的約兩倍。在 API 計費方面,在 Claude Console 中設定工作區花費上限。成本文件將「工作區花費上限」列為 Console 使用者的上限。要了解代幣最初去了哪裡,請參閱《Claude Code: How to See Token Usage (and Reduce It)》。
哪個防護層捕捉哪種失敗?Claude Code 的防護層有意重疊。沒有單一的層可以涵蓋所有情況,因此請根據失敗模式進行選擇:
| 層級 | 捕捉 | 遺漏 | 設定成本 |
| :------------- | :--------------------------------- | :------------------------------------ | :--------- |
| 拒絕規則 | 精確的已知指令、秘密檔案 | 重新措辭的變體 | 5 分鐘 |
| PreToolUse 鉤子 | 模式變體、自訂邏輯 | 您的正規表達式未涵蓋的任何內容 | 15–30 分鐘 |
| --max-turns / 工具呼叫計數器 | 迴圈 | 在少數回合中花費大量資金的運行 | 1 分鐘 |
| --max-budget-usd | 成本飆升 | 超過上限的超支 | 1 分鐘 |
| Stop 鉤子 | 在測試失敗時退出 | 仍然通過測試的錯誤程式碼 | 10 分鐘 |
所有這些都適用一個限制。即使在您從未信任過的資料夾中,-p 會話也會運行專案的 .claude/settings.json 中的鉤子。僅將無人值守的任務指向您控制的儲存庫,或使用 --bare 搭配明確的 --settings 檔案。同時保留復原路徑,因為防護機制可以減少損害但無法撤銷損害。
《Claude Code Checkpoints: How Rollback Works in Automations》涵蓋了您可以回滾的內容。
下一步行動。立即執行(DIY):將權限區塊貼到 .claude/settings.json 中並提交。添加 block-destructive.sh,註冊它,並確認它出現在 /hooks 下。將 --max-turns 和 --max-budget-usd 添加到每個排程的 claude -p 行中。cron 設定指南顯示了這些行所在的位置。
如果您不想自己建構:Claude 訂閱不會為您設定防護機制,但它確實對使用量設定了硬性上限。Pro 每月 20 美元,Max 起價每月 100 美元,Claude Code 包含在付費方案中(截至 2026 年 10 月;請查看 claude.com/pricing)。
訂閱適合希望每月花費可預測的個人開發者。如果您需要按次運行的美元計費,則不適合:成本文件指出,對於 Pro 和 Max 訂閱者,/usage 會話成本數字「與計費目的無關」。對於按代幣控制,透過 Claude Console 進行 API 計費並設定工作區花費上限是更好的選擇。
本網站上的相關指南:《Claude Code Hooks Examples: 7 Copy-Paste Scripts》、《Claude Code Hooks Lifecycle: Every Event, Explained》、《Why Claude Code Stops Mid-Automation (and How to Fix It)》。
常見問題。AI 代理的範例是什麼?Claude Code 就是一個 AI 代理的範例。它讀取檔案、運行 shell 指令、編輯程式碼並根據結果決定下一步,所有這些都在一個迴圈中進行。
覺得值得一看?分享給朋友。
以上為 AI 自動翻譯導讀。原文版權歸 DEV Community (Claude Code) 所有, 建議透過「閱讀原文」前往原始網站,以取得最完整資訊並支持原作者。
43 個來源、每 2 小時更新,太多看不完。電子報每週挑最值得看的幾則,附上 Max 的看法。