管理推理钩子

配置推理钩子

Copy page



为您的 Claude Enterprise 组织允许推理钩子，连接您的 AI 安全服务器，并控制强制执行、故障处理和逐步发布。

推理钩子会将您组织中的提示发送到您选择的 AI 安全服务器，并在 Claude 处理每个请求之前将其挂起，等待允许或拒绝的裁决（verdict）。本页将逐步介绍如何开启该功能、连接您的服务器以及控制强制执行。要了解推理钩子是什么以及何时使用它们，请参阅推理钩子概述。要构建 AI 安全服务器本身，请参阅开发推理钩子集成。

开始之前

您需要：

• claude.ai 中的 organization:manage 权限，只有所有者和主要所有者角色拥有该权限。管理员角色不具备该权限。
• 一个接受裁决请求的 AI 安全服务器 HTTPS 端点：使用 443 端口的 https:// URL，位于可公开路由的主机上，且无需重定向即可访问。不支持反向隧道主机（ngrok 及类似的隧道服务）：Anthropic 的网络策略会阻止它们。请勿通过隧道进行测试；请将您的服务器托管在您控制的域名上。有关完整的托管要求，以及如何构建服务器和验证签名请求，请参阅开发推理钩子集成。

设置推理钩子

强制执行有三种状态：

• 关闭：当强制执行裁定关闭时，永远不会联系您的 AI 安全服务器，也不会检查提示。
• 影子模式：当强制执行裁定开启且模式设置为影子模式时，您的 AI 安全服务器会接收提示并返回裁决，但不会阻止任何内容。
• 强制执行：当强制执行裁定开启且模式设置为允许请求或阻止该请求时，拒绝裁决会阻止请求。

以下步骤将一个新配置从关闭状态变为强制执行状态。

1. 1

   为您的组织允许推理钩子

   前往 claude.ai > 组织设置 > 数据与隐私，找到推理钩子部分。开启在您的组织中允许。

   开启此选项会解锁推理钩子设置页面，并始终强制将强制执行裁定置于关闭状态，因此允许该功能本身永远不会启动检查：即使是之前已开启强制执行的配置，在您于最后一步重新开启强制执行裁定之前也会保持不检查状态。

2. 2

   打开推理钩子设置页面

   仍在数据与隐私中，打开推理钩子部分以进入推理钩子设置页面。该页面位于数据与隐私之下，而不是在设置导航中作为独立条目，因此其面包屑导航显示为数据与隐私 / 推理钩子。在您保存端点之前，页面会警告提示尚未被检查，并且强制执行裁定保持关闭，并带有需要端点标记。

3. 3

   配置您的端点

   点击配置打开设置端点对话框，并输入终端节点 URL：即接收裁决请求的 https:// URL。仅接受 https:// URL。

   此时对话框不会要求填写其他内容：自定义请求标头在第 5 步中设置，故障处理在第 6 步中设置。点击下一步保存。保存端点后，该按钮将显示为编辑。

4. 4

   存储您的签名密钥

   首次保存会生成您的 webhook 签名密钥，并仅显示一次。在点击下一步之前，请复制并安全地存储该密钥：该密钥之后无法再次获取，只能轮换。

   您的 AI 安全服务器使用此密钥来验证其收到的每个请求上的签名，包括下一步中的连接测试。有关验证流程，请参阅验证签名。

5. 5

   添加请求头并测试连接

   在签名密钥对话框上点击下一步会重新打开端点对话框，此时多了两个控件：

   • 自定义请求标头： 最多 16 个静态请求头，随每个裁决请求一起发送，以便您的 AI 安全服务器对调用方进行身份验证。请求头的值以加密方式存储，且不会再次显示；保存后，仅显示请求头名称。由于这些值是只写的，保存对请求头的任何更改都需要重新输入每个值。更改端点 URL 会清除所有已存储的请求头值，以确保您的凭据永远不会被发送到新的目标地址；更改 URL 后请重新输入这些值。请求头名称必须使用标准 HTTP 令牌字符，并使用 - 而非 _，且不得与保留名称冲突（请求帧相关的请求头，例如 Content-* 和 Host；代理和 cookie 请求头；客户端地址请求头，例如 X-Forwarded-*；webhook-* 签名请求头；以及 X-Anthropic-* 前缀）。值必须是可打印的 ASCII 字符。
   • 测试连接： Claude 会将一个合成的测试提示发送到表单中当前填写的 URL 和请求头，而不是已保存的值，因此在测试之前请重新输入所有已存储的请求头值。测试成功时，结果会报告您的 AI 安全服务器针对该测试提示返回的是允许还是拒绝裁决，这样可以在您开始强制执行之前发现"默认拒绝一切"的情况。结果还会显示 Anthropic 为这一次测试请求测得的往返时间，该时间是在新连接上测得的，包含连接握手。

   点击保存以存储您输入的所有请求头。

   常见的失败结果：

   结果	检查内容
   URL 被拒绝	URL 未通过结构检查。请使用 443 端口上的 https:// URL。
   私有或内部 IP	URL 的主机是私有或内部 IP 地址、IPv6 地址或 localhost。请使用可公开路由的主机。
   超时	AI 安全服务器未在超时时间内返回裁决。
   传输错误	DNS 解析、TLS 握手或连接失败，或者主机名解析为私有地址。
   非 200 状态	AI 安全服务器返回了 200 以外的状态码。裁决必须以 HTTP 200 返回；重定向不会被跟随，并计为失败。
   无法解析的响应	AI 安全服务器已响应，但响应体不是有效的裁决。
   需要签名密钥	您的组织没有签名密钥，因此测试请求将以未签名的方式发送。请点击请求签名下的生成密钥，然后再次测试。

6. 6

   选择故障处理和超时

   在失败处理下，设置模式以选择当 AI 安全服务器无法访问或裁决超时时的处理方式：

   • 阻止该请求： 当您的 AI 安全服务器无法提供裁决时停止推理（故障关闭）。
   • 允许请求： 让请求在未经检查的情况下继续发送到模型（故障开放）。

   下拉菜单的第三个选项影子模式是一种逐步推出工具，而不是故障策略；请参阅影子模式。

   然后设置提示词裁定超时（毫秒）：1 到 10,000 毫秒，默认为 5,000 毫秒。该预算涵盖整个交换过程，较慢的裁决会被视为服务器无法访问，因此请设置您的服务器能够可靠满足的最低值。

   此部分中的更改会在您进行更改时即时保存。首次保存时，默认值为允许请求和 5,000 毫秒。

7. 7

   选择逐步发布百分比

   在发布下，设置已检查请求（%），以便在您启动 AI 安全服务器期间对一定百分比的请求运行检查。该值范围为 0 到 100：100 表示检查所有请求，0 表示关闭检查。

   每个请求针对其整个对话轮次只抽样一次，因此单个对话可能在不同轮次之间被部分检查。抽样百分比之外的请求会在未经检查的情况下继续进行，即使故障处理设置为阻止该请求也是如此。

8. 8

   开启“强制执行裁定”

   若要先针对实时流量评估裁决而不阻止任何人，请在开启强制执行之前将模式设置为影子模式（第 6 步）；请参阅影子模式。

   开启强制执行裁定，使 Claude 对每个受管控的提示都以您的 AI 安全服务器的裁决为准，然后在对话框中确认，该对话框会重申您选择的故障处理方式。更改需要大约一分钟才能传达到每个 Anthropic 服务器；已在处理中的请求将按照旧设置完成。关闭它会停止将提示发送到您的 AI 安全服务器，同样在大约一分钟内生效；您的配置会被保留。

   位于强制执行裁定下方的 Validate tool calls（验证工具调用） 还会将 Claude 每个响应中的工具调用发送到您的 AI 安全服务器，并在这些工具调用运行之前等待其裁决；请参阅工具调用帧。在新配置中，该选项默认开启。当强制执行裁定关闭时，它不起作用；与强制执行裁定一样，对它的更改传播到每台 Anthropic 服务器大约需要一分钟。

影子模式

Shadow mode（影子模式）会针对实时流量运行您的钩子，但不会阻止任何内容。您的 AI 安全服务器接收受管控的提示并返回裁决，与强制执行时完全相同，但不会阻止任何内容：每个请求都会继续发送到模型，即使您的服务器拒绝了它或无法访问，最终用户也不会察觉任何变化。在开始强制执行之前，可以使用它根据您组织的真实流量调整策略。开启 Validate tool calls 后，您的服务器在影子模式下也会接收工具调用帧，且不会阻止任何工具调用。

要使用影子模式，请在失败处理下将模式设置为影子模式，然后开启强制执行裁定，以便提示流向您的 AI 安全服务器。当它处于活动状态时，设置页面会显示影子模式——不拦截徽章。要退出影子模式，请将模式设置回允许请求或阻止该请求；一旦强制执行开启，裁决将再次被强制执行。

排除项

在 Who is inspected（检查对象） 下，开启 Limit by role（按角色限制） 后，选择其成员不受推理钩子覆盖的角色：这些成员的提示永远不会被发送到您的 AI 安全服务器。只有您组织创建的自定义角色可以被排除；内置角色不在可选范围内。在角色选择器中选择这些角色（其占位文本为选择要排除的角色），并在角色管理页面（管理角色）中管理每个角色的持有者；更改排除项需要身份管理权限。该列表默认为空，在没有排除任何角色的情况下，每个受管控的请求都会被检查，除非 Inspect（检查） 设置为 Only selected roles（仅限选定角色）。

排除项适用于用户的交互式会话。对排除列表的更改会作为角色权限更改（rbac_role_permission_added 和 rbac_role_permission_removed）记录在您组织的活动源中。

仅检查选定的角色

Who is inspected 部分中的所有内容都受一个开关 Limit by role 控制。当您开启该开关时，Inspect 的初始值为 Everyone except excluded roles（除被排除角色外的所有人），并按上述方式在其下方选择要排除的角色。

若要先在组织的一部分中试用推理钩子，请开启 Limit by role，将 Inspect 设置为 Only selected roles，并在打开的对话框中选择角色。此后，只有设置为自定义角色且被分配了选定角色的成员才会被检查。设置为任何其他角色（例如用户或所有者）的成员不会被检查，即使他们被分配了选定角色。如果您被设置为所有者或主要所有者，这也包括您本人。在切换之前请移除所有排除的角色：一个组织只能使用排除项或选定角色之一，不能同时使用两者。切换后，请在 Inspect 下的角色选择器中添加或移除角色。若要恢复检查所有人，请关闭 Limit by role：确认后，这将移除所有排除的角色并关闭 Only selected roles。

当设置为 Only selected roles 时：

• 功能访问权限为所有功能或全部已正式发布的自定义角色，与其他任何角色一样，只有在您选择它时才会计入。
• 如果没有任何设置为自定义角色的成员被分配了选定角色，则不会检查任何成员。
• 背后没有成员的请求不会被检查，例如使用 API 密钥发出的请求，以及 Slack 中的 Claude Tag 对话。

对 Inspect 的更改以及对受检查角色的更改会记录在您组织的活动源中。

自定义提示词拦截消息

在自定义提示词拦截消息下，设置最多 500 个字符的自定义文本，当您的 AI 安全服务器拒绝请求时，该文本会附加到最终用户看到的错误之后（通常是联系谁或在哪里申请例外）。最终消息由您的 AI 安全服务器针对每个请求的 deny_reason（如果存在）、一个空行，然后是此文本组成。在未配置自定义文本的情况下，内置默认消息会引导用户联系其管理员；您也可以完全关闭附加消息，使用户只看到 deny_reason。

监控您的 AI 安全服务器

推理钩子设置页面的端点健康区域显示：

• 端点状态： 正常、已熔断、未强制执行，或在保存端点之前显示未配置。
• 每分钟失败次数：过去 2 分钟内 webhook 失败次数的平均值。
• 拦截率： 拒绝裁决在您的 AI 安全服务器裁决中所占的比例，在逐步发布百分比低于 100 时显示。
• 熔断器已触发： 断路器上次跳闸的时间（如果曾跳闸）。
• 近期错误： 每个条目显示失败发生的时间、错误类型和类别。对于您的端点或与端点连接的问题，类别为 webhook_error；对于 Anthropic 系统内部的故障，类别为 relay_error。DlpWebhookStatusError 条目还可以显示您的 AI 安全服务器返回的 HTTP 状态以及 Anthropic 发送的请求体大小，例如 HTTP 413 · 1.3 MB。条目永远不会包含请求内容或您的端点 URL。该列表保留最近的 10 次失败，并在最后一次失败一小时后清除。

近期错误中的错误类型含义如下：

在影子模式下，任何错误都不会计入断路器。

该面板是尽力而为的：如果 Anthropic 无法读取计数器，它会显示零失败和无错误，而不是显示其自身的错误，因此看起来健康的面板本身并不能证明您的 AI 安全服务器是健康的。每分钟失败次数统计每一次失败，包括永远不会触发断路器的网络和 DNS 错误，因此它可能很高而熔断器已触发仍为空。

断路器

可归因于您的 AI 安全服务器的持续 webhook 失败会触发 circuit breaker（断路器）跳闸，从而停止强制执行：不再联系您的服务器，并且您的失败处理选择将应用于每个被检查的请求。如果选择了阻止该请求，您组织中的用户将被阻止，直到断路器重置。当断路器跳闸时，管理员也会在 claude.ai 通知中心收到通知。

每次触发还会作为 inference_hooks_circuit_breaker_tripped 活动记录在您组织的活动源中，以便您的安全团队或供应商可以通过他们已有的监控（例如接入该动态的 SIEM）针对触发事件发出警报。每次触发只记录一条活动，而不是每个受影响的请求各记录一条。记录功能要求为您的组织启用 Compliance API；请参阅设置 Compliance API。

要恢复，请修复服务器，然后重新开启强制执行裁定以重置断路器。

熔断器也可以自行重置。从触发后 10 分钟开始，Anthropic 会在后台向您的服务器发送测试请求，以检查其是否已恢复，频率最多约为每分钟一次；此过程不涉及任何用户请求。如果您的服务器返回有效的裁决（允许或拒绝均可），熔断器将重置，强制执行将恢复。否则，熔断器保持触发状态，检查将继续进行。

只有在触发后您的推理钩子设置未发生更改的情况下，自动恢复才会运行。如果您在触发后更改了任何推理钩子设置（包括轮换签名密钥），检查将停止，熔断器将不再自行重置；请在服务器修复后重新开启强制执行裁定。自动恢复仅适用于触发情况：如果您自己关闭了强制执行裁定，强制执行将保持关闭状态，直到您重新开启它。

轮换您的签名密钥

点击请求签名下的轮换密钥以替换您的签名密钥。如果您的组织尚无密钥，该按钮会显示为生成密钥，并创建第一个密钥。轮换是即时切换的：新密钥会被生成并仅显示一次，旧密钥将无法再被获取，并且任何请求都不会同时使用两个密钥签名，因此不存在可依赖的重叠期。

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

审计跟踪

推理钩子活动会记录在您组织的活动源中：配置更改、拒绝、断路器跳闸，以及因无法获得裁决而在未经检查的情况下继续处理的请求。最后一类仅在强制执行裁定开启且模式为允许请求时记录。其原因为 endpoint_timeout、调用您的 AI 安全服务器时出现任何其他问题时的 endpoint_error，或 Anthropic 一侧故障时的 internal_error。在阻止该请求或影子模式下，失败的请求不会被单独记录。断路器的自动恢复在任何模式下都不会被记录。断路器处于跳闸状态期间，不会记录任何按请求的推理钩子活动；跳闸活动即是活动源对该时间段的记录。拒绝记录带有标识符，可让您将每次拒绝与您自己系统中的对应记录关联起来。

关闭推理钩子

关闭有两个级别：

• 在推理钩子设置页面上关闭强制执行裁定：在大约一分钟内，您组织的提示将停止发送到您的 AI 安全服务器；已在处理中的请求将按照旧设置完成。设置页面仍然可用，因此您可以在处理 AI 安全服务器期间使用此方式暂停强制执行。
• 在数据与隐私设置中关闭在您的组织中允许：提示不再被检查，并且推理钩子设置将变为不可用，直到您重新开启它。无论哪种方式，您的端点配置、自定义标头和签名密钥都会被保留；重新开启它会强制将强制执行裁定置于关闭状态并清除已跳闸的断路器，因此请在准备就绪时再次开启强制执行。

后续步骤