配置 Inference hooks

"Inference hooks"（推理钩子）会将您组织的提示发送到您选择的 AI 安全服务器，并在 Claude 处理每个请求之前等待允许或拒绝的裁定结果。本页将引导您完成启用该功能、连接服务器以及控制执行策略的过程。如需了解 Inference hooks 是什么以及何时使用，请参阅 Inference hooks 概述。如需构建 AI 安全服务器本身，请参阅开发 Inference hooks 集成。



开始之前

您需要：

• 在 claude.ai 中拥有 organization:manage 权限。内置的 Admin、Owner 和 Primary owner 角色拥有此权限，任何被授予该权限的自定义角色也同样拥有。
• 一个接受裁定请求的 AI 安全服务器 HTTPS 端点：一个使用 443 端口的 https:// URL，位于可公开路由的主机上，且无需重定向即可访问。有关完整的托管要求，以及如何构建服务器和验证签名请求，请参阅开发 Inference hooks 集成。



设置 Inference hooks

共有三种执行状态：关闭（Enforce verdicts 处于关闭状态：永远不会联系您的 AI 安全服务器，也不会检查提示）、影子模式（Enforce verdicts 处于开启状态且 Mode 设置为 Shadow mode：您的 AI 安全服务器会接收提示并返回裁定结果，但不会阻止任何内容）以及执行中（Enforce verdicts 处于开启状态且 Mode 设置为 Allow the request 或 Block the request：拒绝裁定会阻止请求）。以下步骤将引导您将新配置从关闭状态切换到执行状态。



影子模式

"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 通知中心收到通知。

要恢复，请修复服务器，然后重新开启 Enforce verdicts 以重置熔断器。



轮换您的签名密钥

点击 Request signing 下的 Rotate secret 以替换您的签名密钥。轮换是即时切换：新密钥会生成并仅显示一次，旧密钥无法再被获取，且不会有任何请求同时使用两个密钥签名，因此不存在可依赖的重叠期。

轮换后，使用先前密钥签名的请求可能仍会短暂到达；验证签名介绍了您的 AI 安全服务器应如何处理这一切换过程。



审计跟踪

Inference hooks 活动会记录在您组织的 Activity Feed 中：配置更改、拒绝记录，以及在您的故障处理设置下未经检查而继续处理的请求。拒绝记录带有标识符，可让您将每次拒绝与您自己系统中的匹配记录进行关联。



关闭 Inference hooks

有两个级别的关闭：

• 在 Inference hooks 设置页面上关闭 Enforce verdicts：约一分钟内，您组织的提示将停止发送到您的 AI 安全服务器；已在处理中的请求将按旧设置完成。设置页面仍然可用，因此在您调试 AI 安全服务器时可使用此方式暂停执行。
• 在 Data and privacy 设置中关闭 Allow for your organization：提示不再被检查，且 Inference hooks 设置将不可用，直到您重新开启。无论哪种方式，您的端点配置、自定义请求头和签名密钥都会被保留；重新开启会强制将 Enforce verdicts 设为关闭，因此请在准备就绪后再次开启执行。



后续步骤