--- title: 設定 Inference hooks url: https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks-configuration description: 為您的 Claude Enterprise 組織允許 Inference hooks、連接您的 AI 安全伺服器，並控制強制執行、失敗處理與逐步推出。 --- Inference hooks 目前為 beta 版，適用於 Claude Enterprise 組織。設定此功能需要 `organization:manage` 權限，只有 Owner 和 Primary owner 角色擁有此權限。 Inference hooks（推論掛鉤）會將您組織的提示傳送至您選擇的 AI 安全伺服器，並在 Claude 處理每個請求之前，先等待允許或拒絕的裁決（verdict）。本頁將逐步說明如何開啟此功能、連接您的伺服器，以及控制強制執行。若要了解 Inference hooks 是什麼以及何時使用，請參閱 [Inference hooks 概覽](https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks)。若要建置 AI 安全伺服器本身，請參閱[開發 Inference hooks 整合](https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks-endpoint)。 ## 開始之前 您需要： * claude.ai 中的 `organization:manage` 權限，只有 **Owner** 和 **Primary owner** 角色擁有此權限。**Admin** 角色沒有此權限。 * 一個接受判定請求的 AI 安全伺服器 HTTPS 端點：使用連接埠 443 的 `https://` URL，位於可公開路由的主機上，且無需重新導向即可連線。不支援反向通道主機（ngrok 及類似的通道服務）：Anthropic 的網路政策會封鎖它們。請勿透過通道進行測試；請將您的伺服器託管在您控制的網域上。如需完整的[託管需求](https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks-endpoint#receive-a-request)，以及建置伺服器和驗證已簽署請求的方式，請參閱[開發 Inference hooks 整合](https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks-endpoint)。 ## 設定 Inference hooks 共有三種強制執行狀態：**關閉**（**Enforce verdicts** 為關閉：永遠不會聯繫您的 AI 安全伺服器，且不會檢查提示）、**影子**（**Enforce verdicts** 為開啟且 **Mode** 設為 **Shadow mode**：您的 AI 安全伺服器會收到提示並回傳裁決，但不會封鎖任何內容），以及**強制執行中**（**Enforce verdicts** 為開啟且 **Mode** 設為 **Allow the request** 或 **Block the request**：拒絕裁決會封鎖該請求）。以下步驟會將一個新設定從關閉帶到強制執行中。 前往 claude.ai > **Organization settings** > **Data and privacy**，找到 **Inference hooks** 區段。開啟 **Allow for your organization**。 開啟此選項會解鎖 Inference hooks 設定頁面，並一律強制將 **Enforce verdicts** 設為關閉，因此允許此功能本身絕不會啟動檢查：即使是先前已開啟強制執行的設定，在您於最後一個步驟重新開啟 **Enforce verdicts** 之前，仍會維持不檢查的狀態。 仍在 **Data and privacy** 中，開啟 **Inference hooks** 區段以進入 Inference hooks 設定頁面。它位於 Data and privacy 之下，而非設定導覽列中的獨立項目，因此其麵包屑導覽顯示為 **Data and privacy / Inference hooks**。在您儲存端點之前，頁面會警告提示尚未受到檢查，且 **Enforce verdicts** 會維持關閉並顯示 **Requires endpoint** 標記。 按一下 **Configure** 以開啟 **Set up endpoint** 對話方塊，並輸入 **Endpoint URL**：接收判定請求的 `https://` URL。僅接受 `https://` URL。 此時對話方塊不會要求其他資訊：自訂請求標頭在步驟 5 設定，失敗處理則在步驟 6 設定。按一下 **Next** 以儲存。儲存端點後，按鈕會顯示為 **Edit**。 第一次儲存時會產生您的 webhook「signing secret」（簽署密鑰），並僅顯示一次。在按一下 **Next** 之前，請複製並安全地儲存它：此密鑰之後無法再取得，只能[輪替](https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks-configuration#rotate-your-signing-secret)。 您的 AI 安全伺服器會使用此密鑰來驗證其收到的每個請求上的簽章，包括下一個步驟中的連線測試。如需驗證程序，請參閱[驗證簽章](https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks-endpoint#verify-the-signature)。 在簽署密鑰對話方塊上按一下 **Next** 會重新開啟端點對話方塊，此時會多出兩個控制項： * **Custom request headers：** 最多 16 個靜態標頭，會隨每個判定請求一起傳送，讓您的 AI 安全伺服器能夠驗證呼叫者。標頭值會以加密方式儲存，且不會再次顯示；儲存後只會顯示標頭名稱。由於這些值為唯寫，儲存對標頭的任何變更都需要重新輸入每個值。變更端點 URL 會清除所有已儲存的標頭值，以確保您的憑證永遠不會被傳送到新的目的地；變更 URL 後請重新輸入這些值。標頭名稱必須使用標準 HTTP token 字元，並使用 `-` 而非 `_`，且不得與保留名稱衝突（請求框架標頭，例如 `Content-*` 和 `Host`；代理與 cookie 標頭；用戶端位址標頭，例如 `X-Forwarded-*`；`webhook-*` 簽章標頭；以及 `X-Anthropic-*` 前綴）。值必須是可列印的 ASCII 字元。 * **Test connection：** Claude 會將一個合成的測試提示傳送到表單中目前填寫的 URL 和標頭，而非已儲存的值，因此請在測試前重新輸入任何已儲存的標頭值。成功時，結果會回報您的 AI 安全伺服器針對測試提示回傳的是允許還是拒絕判定，這能讓您在開始強制執行之前發現「全部拒絕」的預設行為。 按一下 **Save** 以儲存您輸入的任何標頭。 常見的失敗結果： | 結果 | 檢查事項 | | -------- | --------------------------------------------------------------------------------- | | URL 遭拒 | URL 未通過結構檢查。請使用連接埠 443 的 `https://` URL。 | | 私人或內部 IP | URL 的主機是私人或內部 IP 位址、IPv6 位址或 `localhost`。請使用可公開路由的主機。 | | 逾時 | AI 安全伺服器未在逾時時間內回傳判定。 | | 傳輸錯誤 | DNS 解析、TLS 交握或連線失敗，或主機名稱解析為私人位址。 | | 非 200 狀態 | AI 安全伺服器回應的狀態碼不是 200。判定必須以 HTTP 200 回傳；不會跟隨重新導向，且重新導向會被視為失敗。 | | 無法解析的回應 | AI 安全伺服器有回應，但內容不是有效的判定。 | | 需要簽署密鑰 | 您的組織沒有簽署密鑰，因此測試會以未簽署的方式傳送。請按一下 **Request signing** 下的 **Generate secret**，然後再次測試。 | 在 **Failure handling** 下，設定 **Mode** 以選擇當 AI 安全伺服器無法連線或裁決逾時時的處理方式： * **Block the request：**當您的 AI 安全伺服器無法提供裁決時停止推論（失敗即關閉，fail closed）。 * **Allow the request：**讓請求在未經檢查的情況下繼續送往模型（失敗即開放，fail open）。 下拉選單的第三個選項 **Shadow mode** 是一種逐步推出工具，而非失敗政策；請參閱[影子模式](https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks-configuration#shadow-mode)。 接著設定 **Prompt verdict timeout (ms)**：1 至 10,000 毫秒，預設為 5,000 毫秒。此預算涵蓋整個交換過程，較慢的裁決會被視為伺服器無法連線，因此請設定您的伺服器能夠穩定達成的最低值。 此區段中的變更會在您進行時即時儲存。首次儲存時，預設值為 **Allow the request** 與 5,000 毫秒。 在 **Rollout** 下，設定 **Requests inspected (%)**，以便在您讓 AI 安全伺服器上線的過程中，對一定百分比的請求執行檢查。此值範圍為 0 至 100：100 表示檢查所有請求，0 則關閉檢查。 每個請求會針對其整個對話輪次擲骰一次，因此單一對話可能在不同輪次間被部分檢查。落在取樣百分比之外的請求會在未經檢查的情況下繼續進行，即使失敗處理設為 **Block the request** 亦然。 若要先針對即時流量評估裁決而不封鎖任何人，請在開啟強制執行之前將 **Mode** 設為 **Shadow mode**（步驟 6）；請參閱[影子模式](https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks-configuration#shadow-mode)。 開啟 **Enforce verdicts**，讓 Claude 對每個受管控的提示都依據您 AI 安全伺服器的判定進行把關，然後在對話方塊中確認，該對話方塊會重述您的失敗處理選擇。變更大約需要一分鐘才能傳達到每個 Anthropic 伺服器；已在處理中的請求會依舊設定完成。關閉它會停止將提示傳送到您的 AI 安全伺服器，同樣約在一分鐘內生效；您的設定會被保留。 位於 **Enforce verdicts** 下方的 **Validate tool calls** 也會將 Claude 每個回應中的工具呼叫傳送到您的 AI 安全伺服器，並在執行前等待其判定；請參閱[工具呼叫訊框](https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks-endpoint#the-tool-call-frame)。在新設定中它預設為開啟。當 **Enforce verdicts** 關閉時它不會有任何作用，且對它的變更與 **Enforce verdicts** 一樣，大約需要一分鐘才能傳達到每個 Anthropic 伺服器。 ## 影子模式 「Shadow mode」（影子模式）會針對即時流量執行您的掛鉤，而不封鎖任何內容。您的 AI 安全伺服器會接收受管控的提示並傳回判定，方式與強制執行時完全相同，但不會封鎖任何內容：每個請求都會繼續傳送至模型，即使您的伺服器拒絕它或無法連線也是如此，且終端使用者不會察覺任何異狀。請使用它在開始強制執行之前，依據您組織的真實流量調整您的政策。開啟 **Validate tool calls** 時，您的伺服器在影子模式下也會接收工具呼叫訊框，且不會封鎖任何工具呼叫。 若要使用影子模式，請在 **Failure handling** 下將 **Mode** 設為 **Shadow mode**，然後開啟 **Enforce verdicts**，讓提示流向您的 AI 安全伺服器。當它處於啟用狀態時，設定頁面會顯示 **Shadow mode — not blocking** 標記。若要離開影子模式，請將 **Mode** 設回 **Allow the request** 或 **Block the request**；一旦強制執行開啟，裁決便會再次被強制執行。 ## 排除項目 在 **Exclusions** 下，選擇其成員不受 Inference hooks 涵蓋的角色：他們的提示永遠不會被傳送至您的 AI 安全伺服器。只有您組織建立的自訂角色可以被排除；不提供內建角色。請在角色選擇器中挑選它們，其預留文字顯示為 **Select roles to exclude**，並從角色管理頁面（**Manage roles**）管理誰擁有各個角色；變更排除項目需要身分管理權限。此清單預設為空，在未排除任何角色的情況下，每個受管控的請求都會受到檢查。 排除適用於使用者的互動式工作階段。對排除清單的變更會以角色權限變更（`rbac_role_permission_added` 和 `rbac_role_permission_removed`）的形式記錄在您組織的[活動摘要](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-activity-feed)中。 ## 自訂封鎖提示訊息 在 **Custom blocked prompt message** 下，設定最多 500 個字元的自訂文字，當您的 AI 安全伺服器拒絕請求時，此文字會附加在終端使用者看到的錯誤之後（通常是應聯繫誰或在何處申請例外）。最終訊息為您 AI 安全伺服器針對每個請求的 `deny_reason`（若有）、一個空行，然後是此文字。若未設定自訂文字，內建的預設訊息會引導使用者聯繫其管理員；您也可以完全關閉附加訊息，讓使用者只看到 `deny_reason`。 ## 監控您的 AI 安全伺服器 Inference hooks 設定頁面的端點健康狀態區域會顯示： * **Endpoint status：** Healthy、Tripped、Not enforcing，或在儲存端點之前顯示 Not configured。 * **Failures per minute：** 過去兩分鐘內 webhook 失敗次數的平均值。 * **Block rate：** 拒絕判定佔您 AI 安全伺服器判定的比例，在推出百分比低於 100 時顯示。 * **Circuit breaker tripped：** 斷路器上次跳脫的時間（若曾跳脫）。 * **Recent errors：** 每個項目會顯示失敗發生的時間、錯誤類型和類別。類別為 `webhook_error` 表示您的端點或與其連線有問題，為 `relay_error` 則表示 Anthropic 系統內部發生失敗。項目永遠不會包含請求內容或您的端點 URL。此清單會保留最近 10 次失敗，並在最後一次失敗的一小時後清除。 **Recent errors** 中的錯誤類型意義如下： | 顯示的錯誤 | 意義 | 是否計入斷路器 | | ---------------------------------------------------- | --------------------------------------------------------------------------------- | ------- | | `DlpWebhookTimeoutError` · `webhook_error` | 您的 AI 安全伺服器未在您設定的 **Prompt verdict timeout (ms)** 內傳回判定。 | 是 | | `DlpWebhookStatusError` · `webhook_error` | 您的 AI 安全伺服器以 200 以外的 HTTP 狀態回應，例如重新導向。 | 是 | | `DlpWebhookResponseError` · `webhook_error` | 您的 AI 安全伺服器回應 200，但內容不是有效的判定，或大於 64 KiB。 | 是 | | `DlpWebhookTransportError` · `webhook_error` | 在收到完整回應之前連線失敗或中斷：例如主機名稱無法解析或解析為私人位址、連線遭拒或重設，或 TLS 交握失敗。Anthropic 端的網路問題也可能以此方式呈現。 | 否 | | `DlpWebhookDisallowedAddressError` · `webhook_error` | 端點 URL 的主機是私人或內部 IP 位址、IPv6 位址或 `localhost`。解析為此類位址的主機名稱則會顯示為傳輸錯誤。 | 是 | | `DlpWebhookBlockedError` · `webhook_error` | 端點 URL 不是連接埠 443 上的 `https://` URL，或無法解析，因此未傳送任何請求。 | 否 | | `DlpWebhookRelayError` · `relay_error` | 失敗發生在 Anthropic 系統內部，通常未聯繫您的 AI 安全伺服器。 | 否 | 在影子模式下，任何錯誤都不會計入斷路器。 此面板為盡力而為：若 Anthropic 無法讀取計數器，它會顯示零次失敗且無錯誤，而非顯示其自身的錯誤，因此看起來健康的面板本身並不能證明您的 AI 安全伺服器是健康的。**Failures per minute** 會計算每一次失敗，包括永遠不會使斷路器跳脫的網路與 DNS 錯誤，因此它可能很高，而 **Circuit breaker tripped** 仍維持空白。 ## 斷路器 可歸因於您 AI 安全伺服器的持續 webhook 失敗會使「circuit breaker」（斷路器）跳脫，進而停止強制執行：不再聯繫您的伺服器，且您的 **Failure handling** 選擇會套用至每個受檢查的請求。若選擇 **Block the request**，您組織中的使用者會被封鎖，直到斷路器重設為止。當斷路器跳脫時，管理員也會在 claude.ai 通知中心收到通知。 每次跳脫也會以 `inference_hooks_circuit_breaker_tripped` 活動記錄在您組織的[活動摘要](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-activity-feed)中，因此您的安全團隊或供應商可以透過他們已在運行的監控（例如擷取該摘要的 SIEM）對跳脫發出警示。每次跳脫記錄一個活動，而非每個受影響的請求記錄一個。記錄需要為您的組織啟用 Compliance API；請參閱[設定 Compliance API](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access)。 若要復原，請修復伺服器，然後重新開啟 **Enforce verdicts** 以重設斷路器。 斷路器也可以自行重設。從跳脫後 10 分鐘開始，Anthropic 會在背景向您的伺服器傳送測試請求，以檢查伺服器是否已復原，頻率最多約每分鐘一次；此過程不涉及任何使用者請求。如果您的伺服器回應有效的判定（允許或拒絕皆可），斷路器就會重設，強制執行也會恢復。否則斷路器會維持跳脫狀態，檢查也會持續進行。 自動復原僅在您的 Inference hooks 設定自跳脫後未曾變更的情況下執行。如果您在跳脫後變更任何 Inference hooks 設定（包括輪替簽署密鑰），檢查就會停止，斷路器也不再自行重設；請在伺服器修復後重新開啟 **Enforce verdicts**。自動復原僅適用於跳脫：如果您自行關閉 **Enforce verdicts**，強制執行會維持關閉，直到您重新開啟為止。 ## 輪替您的簽署密鑰 按一下 **Request signing** 下的 **Rotate secret** 以更換您的簽署密鑰。如果您的組織尚未有密鑰，同一個按鈕會顯示為 **Generate secret**，並建立第一個密鑰。輪替是立即切換：新密鑰會被產生並僅顯示一次，舊密鑰將無法再取得，且任何請求都不會同時以兩個密鑰簽署，因此沒有可依賴的重疊期間。 以先前密鑰簽署的請求在輪替後仍可能短暫抵達；[驗證簽章](https://platform.claude.com/docs/zh-TW/manage-claude/inference-hooks-endpoint#verify-the-signature)說明了您的 AI 安全伺服器應如何處理切換。 ## 稽核軌跡 Inference hooks 活動會記錄在您組織的[活動摘要](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-activity-feed)中：設定變更、拒絕、斷路器跳脫，以及因無法取得判定而在未經檢查的情況下繼續進行的請求。最後一種只有在 **Enforce verdicts** 開啟且 **Mode** 為 **Allow the request** 時才會記錄。其原因為 `endpoint_timeout`、呼叫您 AI 安全伺服器時發生任何其他問題的 `endpoint_error`，或 Anthropic 端失敗的 `internal_error`。在 **Block the request** 或 **Shadow mode** 下，失敗的請求不會個別記錄。斷路器的自動復原在任何模式下都不會被記錄。斷路器跳脫期間，不會記錄任何個別請求的 Inference hooks 活動；跳脫活動即為活動摘要中該期間的記錄。拒絕記錄帶有識別碼，讓您能將每個拒絕與您自己系統中的對應記錄進行關聯。 ## 關閉 Inference hooks 關閉有兩個層級： * 在 Inference hooks 設定頁面上關閉 **Enforce verdicts**：約在一分鐘內，您組織的提示會停止傳送至您的 AI 安全伺服器；已在處理中的請求會依舊設定完成。設定頁面仍可使用，因此請在您處理 AI 安全伺服器時使用此方式暫停強制執行。 * 在 **Data and privacy** 設定中關閉 **Allow for your organization**：提示不再受到檢查，且 Inference hooks 設定會變為無法使用，直到您重新開啟為止。無論哪種方式，您的端點設定、自訂標頭與簽署密鑰都會被保留；重新開啟會強制將 **Enforce verdicts** 設為關閉並清除已跳脫的斷路器，因此請在您準備好時再次開啟強制執行。 ## 後續步驟 建置 AI 安全伺服器：請求與裁決結構描述、簽章驗證，以及運作語意。 Inference hooks 是什麼、裁決往返如何運作，以及哪些內容會被傳送至您的 AI 安全伺服器。