工具系統與權限

你將學到什麼

工具是 Claude Code 與你的系統互動的方式。沒有工具，它只能生成文字。有了工具，它可以讀取檔案、編輯程式碼、執行命令、搜尋網頁等等。

完成後，你將了解：

工具如何定義和註冊
工具調度模式
權限模式和審批閘門
如何安全地添加自定義工具

問題是什麼

給 AI 不受限制地存取你的檔案系統和終端是危險的。它可能刪除檔案、執行惡意命令或暴露敏感資料。

但過度限制會讓 AI 變得無用 — 如果它不能讀取檔案，就無法幫你寫程式。

解決方案：一個權限系統，作為 AI 意圖和實際執行之間的守門人。

如何運作

工具分類

Claude Code 將工具分為具有不同信任等級的類別：

┌──────────────────────────────────────────────┐
│              工具分類                         │
│                                               │
│  ┌─────────────────────────────────────────┐  │
│  │  始終允許（不需提示）                    │  │
│  │  • Read（讀取檔案）                     │  │
│  │  • Glob（檔案搜尋）                     │  │
│  │  • Grep（內容搜尋）                     │  │
│  └─────────────────────────────────────────┘  │
│                                               │
│  ┌─────────────────────────────────────────┐  │
│  │  需要批准（使用者確認）                  │  │
│  │  • Write（建立檔案）                    │  │
│  │  • Edit（修改檔案）                     │  │
│  │  • Bash（執行命令）                     │  │
│  └─────────────────────────────────────────┘  │
│                                               │
│  ┌─────────────────────────────────────────┐  │
│  │  特殊（依上下文決定）                    │  │
│  │  • Agent（產生子代理）                  │  │
│  │  • WebFetch（存取 URL）                 │  │
│  │  • MCP 工具（外部伺服器）               │  │
│  └─────────────────────────────────────────┘  │
└──────────────────────────────────────────────┘

權限回呼

當 AI 請求工具呼叫時，系統在執行前檢查權限：

AI 請求 tool_use
       │
       ▼
┌──────────────┐
│ 檢查          │
│ 權限規則      │
└──────┬───────┘
       │
       ├─── 允許 ──────► 執行工具
       │
       ├─── 拒絕 ──────► 回傳錯誤給 AI
       │
       └─── 詢問使用者 ─► 顯示提示
                           │
                   ┌───────┴───────┐
                   │               │
                 允許             拒絕
                   │               │
                執行工具        回傳錯誤

權限模式

模式	行為
Default	讀取工具自動允許，寫入/執行工具提示使用者
Plan	所有工具都需要批准，強制逐步審查
Auto	所有工具自動允許，沒有提示

關鍵洞見

工具是 AI 的雙手，權限是安全網。 這個設計的精妙之處在於：

AI 看到所有工具 — 它知道有什麼可用，可以據此規劃。
執行被閘門把關 — 權限系統位於意圖和行動之間。
使用者控制信任等級 — 從偏執（plan 模式）到完全自主（auto 模式）。

這與隱藏工具的系統根本不同。當 Claude Code 知道一個工具存在但被拒絕時，它可以解釋它想做什麼並請求許可 — 比默默失敗好得多。

實作範例

# 權限檢查
def check_permission(tool_name: str, input: dict) -> bool:
    """簡單的權限閘門"""
    # 唯讀工具始終允許
    if tool_name in ["read_file", "search_codebase", "list_files"]:
        return True

    # 寫入工具需要確認
    print(f"工具 '{tool_name}' 想要執行: {input}")
    response = input("允許？[y/N]: ")
    return response.lower() == 'y'

前後對比

沒有權限	有權限系統
所有工具立即執行	根據信任等級閘門式執行
沒有使用者監督	使用者可以審查每個動作
靠限制保安全（隱藏工具）	靠權限保安全（暴露所有，閘門執行）
全有或全無的信任	每個工具類別細粒度信任

下一堂課

在第 3 堂課中，我們將探索使用 TodoWrite 進行規劃 — Claude Code 如何在執行前建立任務計劃，以及為什麼「先思考再行動」的模式能大幅改善結果。