管理推論掛鉤

設定 Inference hooks

Copy page



為您的 Claude Enterprise 組織允許 Inference hooks、連接您的 AI 安全伺服器，並控制強制執行、失敗處理與逐步推出。

Inference hooks（推論掛鉤）會將您組織的提示傳送至您選擇的 AI 安全伺服器，並在 Claude 處理每個請求之前，先等待允許或拒絕的裁決（verdict）。本頁將逐步說明如何開啟此功能、連接您的伺服器，以及控制強制執行。若要了解 Inference hooks 是什麼以及何時使用，請參閱 Inference hooks 概覽。若要建置 AI 安全伺服器本身，請參閱開發 Inference hooks 整合。

開始之前

您需要：

• claude.ai 中的 organization:manage 權限。內建的 Admin、Owner 與 Primary owner 角色擁有此權限，任何被授予此權限的自訂角色亦然。
• 一個可接受裁決請求的 AI 安全伺服器 HTTPS 端點：位於連接埠 443 的 https:// URL，架設於可公開路由的主機上，且無需重新導向即可連線。不支援反向通道主機（ngrok 及類似的通道服務）：Anthropic 的網路政策會封鎖它們。請勿透過通道進行測試；請將您的伺服器架設在您所控制的網域上。如需完整的託管需求，以及建置伺服器與驗證已簽署請求的方法，請參閱開發 Inference hooks 整合。

設定 Inference hooks

共有三種強制執行狀態：關閉（Enforce verdicts 為關閉：永遠不會聯繫您的 AI 安全伺服器，且不會檢查提示）、影子（Enforce verdicts 為開啟且 Mode 設為 Shadow mode：您的 AI 安全伺服器會收到提示並回傳裁決，但不會封鎖任何內容），以及強制執行中（Enforce verdicts 為開啟且 Mode 設為 Allow the request 或 Block the request：拒絕裁決會封鎖該請求）。以下步驟會將一個新設定從關閉帶到強制執行中。

1. 1

   為您的組織允許 Inference hooks

   前往 claude.ai > Organization settings > Data and privacy，找到 Inference hooks 區段。開啟 Allow for your organization。

   開啟此選項會解鎖 Inference hooks 設定頁面，並一律強制將 Enforce verdicts 設為關閉，因此允許此功能本身絕不會啟動檢查：即使是先前已開啟強制執行的設定，在您於最後一個步驟重新開啟 Enforce verdicts 之前，仍會維持不檢查的狀態。

2. 2

   開啟 Inference hooks 設定頁面

   仍在 Data and privacy 中，開啟 Inference hooks 區段以進入 Inference hooks 設定頁面。它位於 Data and privacy 之下，而非設定導覽列中的獨立項目，因此其麵包屑導覽顯示為 Data and privacy / Inference hooks。在您儲存端點之前，頁面會警告提示尚未受到檢查，且 Enforce verdicts 會維持關閉並顯示 Requires endpoint 標記。

3. 3

   設定您的端點

   點擊 Configure 以開啟 Configure endpoint 對話框，並填入：

   • **Endpoint URL：**接收裁決請求的 https:// URL。僅接受 https:// URL。
   • **Custom request headers：**最多 16 個靜態標頭，會隨每個裁決請求一併傳送，讓您的 AI 安全伺服器能夠驗證呼叫者身分。標頭值會以加密方式儲存，且永遠不會再次顯示；儲存後僅會顯示標頭名稱。由於值為唯寫，儲存對標頭的任何變更都需要重新輸入每一個值。變更端點 URL 會清除所有已儲存的標頭值，以確保您的憑證絕不會被傳送至新的目的地；請在變更 URL 後重新輸入。標頭名稱必須使用標準 HTTP token 字元，並使用 - 而非 _，且不得與保留名稱衝突（請求框架標頭如 Content-* 與 Host、代理與 cookie 標頭、用戶端位址標頭如 X-Forwarded-*、webhook-* 簽章標頭，以及 X-Anthropic-* 前綴）。值必須為可列印的 ASCII 字元。

   此對話框僅涵蓋這兩個欄位以及 Test connection；它不會詢問失敗處理方式，您將在步驟 6 中選擇。一旦儲存端點後，按鈕會顯示為 Edit。

4. 4

   測試連線

   點擊 Test connection。Claude 會將一個合成的測試提示傳送至表單中目前的 URL 與標頭，而非已儲存的值，因此請在測試前重新輸入任何已儲存的標頭值。成功時，結果會回報您的 AI 安全伺服器對測試提示回傳的是允許還是拒絕裁決，這能在您開始強制執行之前揭露「全部拒絕」的預設行為。

   常見的失敗結果：

   結果	檢查事項
   URL 被拒絕	URL 未通過結構檢查。請使用位於連接埠 443 的 https:// URL。
   私有或內部 IP	主機解析為私有或內部位址。請使用可公開路由的主機。
   逾時	AI 安全伺服器未在逾時時間內回傳裁決。
   傳輸錯誤	DNS 解析、TLS 交握或連線失敗。
   非 200 狀態	AI 安全伺服器回應了 200 以外的狀態。裁決必須以 HTTP 200 回傳；重新導向不會被追蹤，並視為失敗。
   無法解析的回應	AI 安全伺服器有回應，但主體不是有效的裁決。

5. 5

   儲存並保存您的簽署密鑰

   儲存端點設定。首次儲存會產生您的 webhook 簽署密鑰，並僅顯示一次。請在關閉對話框前複製並安全地保存它：此密鑰之後無法再取回，只能輪替。

   您的 AI 安全伺服器會使用此密鑰來驗證其收到的每個請求上的簽章。關於驗證程序，請參閱驗證簽章。

6. 6

   選擇失敗處理方式與逾時

   在 Failure handling 下，設定 Mode 以選擇當 AI 安全伺服器無法連線或裁決逾時時的處理方式：

   • **Block the request：**當您的 AI 安全伺服器無法提供裁決時停止推論（失敗即關閉，fail closed）。
   • **Allow the request：**讓請求在未經檢查的情況下繼續送往模型（失敗即開放，fail open）。

   下拉選單的第三個選項 Shadow mode 是一種逐步推出工具，而非失敗政策；請參閱影子模式。

   接著設定 Prompt verdict timeout (ms)：1 至 10,000 毫秒，預設為 5,000 毫秒。此預算涵蓋整個交換過程，較慢的裁決會被視為伺服器無法連線，因此請設定您的伺服器能夠穩定達成的最低值。

   此區段中的變更會在您進行時即時儲存。首次儲存時，預設值為 Allow the request 與 5,000 毫秒。

7. 7

   選擇逐步推出百分比

   在 Rollout 下，設定 Requests inspected (%)，以便在您讓 AI 安全伺服器上線的過程中，對一定百分比的請求執行檢查。此值範圍為 0 至 100：100 表示檢查所有請求，0 則關閉檢查。

   每個請求會針對其整個對話輪次擲骰一次，因此單一對話可能在不同輪次間被部分檢查。落在取樣百分比之外的請求會在未經檢查的情況下繼續進行，即使失敗處理設為 Block the request 亦然。

8. 8

   開啟 Enforce verdicts

   若要先針對即時流量評估裁決而不封鎖任何人，請在開啟強制執行之前將 Mode 設為 Shadow mode（步驟 6）；請參閱影子模式。

   開啟 Enforce verdicts，讓 Claude 對每個受管控的提示都依據您 AI 安全伺服器的裁決進行把關，然後在對話框中確認，該對話框會重述您的失敗處理選擇。請預留約一分鐘讓變更傳達至每一台 Anthropic 伺服器；已在處理中的請求會依舊設定完成。關閉它會停止將提示傳送至您的 AI 安全伺服器，同樣約在一分鐘內生效；您的設定會被保留。

影子模式

「Shadow mode」（影子模式）會針對即時流量執行您的掛鉤，而不封鎖任何內容。您的 AI 安全伺服器會收到受管控的提示並回傳裁決，與強制執行時完全相同，但不會封鎖任何內容：每個請求都會繼續送往模型，即使您的伺服器拒絕它或無法連線亦然，且終端使用者不會看到任何異狀。請在開始強制執行之前，使用它來針對您組織的真實流量調整您的政策。

若要使用影子模式，請在 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）管理誰擁有各個角色；變更排除項目需要身分管理權限。此清單預設為空，在未排除任何角色的情況下，每個受管控的請求都會受到檢查。

排除適用於使用者的互動式工作階段；以機器憑證驗證的流量一律會受到檢查。若 Claude 無法解析請求者的角色成員資格，該請求會以可重試的錯誤失敗即關閉，而非在未經檢查的情況下繼續進行。對排除清單的變更會記錄在稽核軌跡中。

自訂封鎖提示訊息

在 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：**每個項目會精簡為時間戳記、錯誤類型與一行原因。項目絕不包含請求內容或您的端點 URL。

此面板為盡力而為：若 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 活動記錄在您組織的活動摘要中，因此您的安全團隊或供應商可以透過他們已在運行的監控（例如擷取該摘要的 SIEM）對跳脫發出警示。每次跳脫記錄一個活動，而非每個受影響的請求記錄一個。記錄需要為您的組織啟用 Compliance API；請參閱設定 Compliance API。

若要復原，請修復伺服器，然後重新開啟 Enforce verdicts 以重設斷路器。

斷路器也可以自行重設。從跳脫後 10 分鐘開始，Anthropic 會測試您的伺服器是否已復原：最多約每分鐘一次，從您組織的正常流量中取一個請求傳送至您的伺服器進行檢查，且無論您的伺服器是否回應，該請求都會為其使用者繼續進行。若您的伺服器以有效的裁決（允許或拒絕）回應，斷路器便會重設並恢復強制執行。任何其他結果皆為 webhook 失敗：斷路器維持跳脫狀態，測試繼續進行。

自動復原僅在您的 Inference hooks 設定自跳脫以來未曾變更時才會執行。若您在跳脫後變更任何 Inference hooks 設定（包括輪替簽署密鑰），測試便會停止，斷路器也不再自行重設；請在您的伺服器修復後重新開啟 Enforce verdicts。自動復原僅適用於跳脫：若您自行關閉 Enforce verdicts，強制執行會維持關閉，直到您重新開啟為止。

輪替您的簽署密鑰

點擊 Request signing 下的 Rotate secret 以更換您的簽署密鑰。輪替是立即切換：新密鑰會被產生並僅顯示一次，舊密鑰無法再取回，且絕不會有任何請求同時以兩個密鑰簽署，因此沒有可依賴的重疊期間。

以先前密鑰簽署的請求在輪替後仍可能短暫抵達；驗證簽章說明了您的 AI 安全伺服器應如何處理切換。

稽核軌跡

Inference hooks 活動會記錄在您組織的活動摘要中：設定變更、拒絕、斷路器跳脫，以及依據您的失敗處理設定在未經檢查的情況下繼續進行的請求。當斷路器處於跳脫狀態時，不會記錄每個請求的 Inference hooks 活動；跳脫活動即為該摘要對該時段的記錄。拒絕記錄帶有識別碼，讓您能將每筆拒絕與您自己系統中的對應記錄進行關聯。

關閉 Inference hooks

關閉有兩個層級：

• 在 Inference hooks 設定頁面上關閉 Enforce verdicts：約在一分鐘內，您組織的提示會停止傳送至您的 AI 安全伺服器；已在處理中的請求會依舊設定完成。設定頁面仍可使用，因此請在您處理 AI 安全伺服器時使用此方式暫停強制執行。
• 在 Data and privacy 設定中關閉 Allow for your organization：提示不再受到檢查，且 Inference hooks 設定會變為無法使用，直到您重新開啟為止。無論哪種方式，您的端點設定、自訂標頭與簽署密鑰都會被保留；重新開啟會強制將 Enforce verdicts 設為關閉並清除已跳脫的斷路器，因此請在您準備好時再次開啟強制執行。

後續步驟