--- title: 配置推理钩子 url: https://platform.claude.com/docs/zh-CN/manage-claude/inference-hooks-configuration description: 为您的 Claude Enterprise 组织允许推理钩子，连接您的 AI 安全服务器，并控制强制执行、故障处理和逐步发布。 --- “Inference hooks”（推理钩子）仅面向 Claude Enterprise 组织提供。配置推理钩子需要 `organization:manage` 权限，只有所有者和主要所有者角色拥有该权限。 推理钩子会将您组织中的提示发送到您选择的 AI 安全服务器，并在 Claude 处理每个请求之前将其挂起，等待允许或拒绝的裁决（verdict）。本页将逐步介绍如何开启该功能、连接您的服务器以及控制强制执行。要了解推理钩子是什么以及何时使用它们，请参阅[推理钩子概述](https://platform.claude.com/docs/zh-CN/manage-claude/inference-hooks)。要构建 AI 安全服务器本身，请参阅[开发推理钩子集成](https://platform.claude.com/docs/zh-CN/manage-claude/inference-hooks-endpoint)。 ## 开始之前 您需要： * claude.ai 中的 `organization:manage` 权限，只有**所有者**和**主要所有者**角色拥有该权限。**管理员**角色不具备该权限。 * 一个接受裁决请求的 AI 安全服务器 HTTPS 端点：使用 443 端口的 `https://` URL，位于可公开路由的主机上，且无需重定向即可访问。不支持反向隧道主机（ngrok 及类似的隧道服务）：Anthropic 的网络策略会阻止它们。请勿通过隧道进行测试；请将您的服务器托管在您控制的域名上。有关完整的[托管要求](https://platform.claude.com/docs/zh-CN/manage-claude/inference-hooks-endpoint#receive-a-request)，以及如何构建服务器和验证签名请求，请参阅[开发推理钩子集成](https://platform.claude.com/docs/zh-CN/manage-claude/inference-hooks-endpoint)。 ## 设置推理钩子 强制执行有三种状态： * **关闭：**当**强制执行裁定**关闭时，永远不会联系您的 AI 安全服务器，也不会检查提示。 * **影子模式：**当**强制执行裁定**开启且**模式**设置为**影子模式**时，您的 AI 安全服务器会接收提示并返回裁决，但不会阻止任何内容。 * **强制执行：**当**强制执行裁定**开启且**模式**设置为**允许请求**或**阻止该请求**时，拒绝裁决会阻止请求。 以下步骤将一个新配置从关闭状态变为强制执行状态。 前往 claude.ai > **组织设置** > **数据与隐私**，找到**推理钩子**部分。开启**在您的组织中允许**。 开启此选项会解锁推理钩子设置页面，并始终强制将**强制执行裁定**置于关闭状态，因此允许该功能本身永远不会启动检查：即使是之前已开启强制执行的配置，在您于最后一步重新开启**强制执行裁定**之前也会保持不检查状态。 仍在**数据与隐私**中，打开**推理钩子**部分以进入推理钩子设置页面。该页面位于**数据与隐私**之下，而不是在设置导航中作为独立条目，因此其面包屑导航显示为**数据与隐私 / 推理钩子**。在您保存端点之前，页面会警告提示尚未被检查，并且**强制执行裁定**保持关闭，并带有**需要端点**标记。 点击**配置**打开**设置端点**对话框，并输入**终端节点 URL**：即接收裁决请求的 `https://` URL。仅接受 `https://` URL。 此时对话框不会要求填写其他内容：自定义请求标头在第 5 步中设置，故障处理在第 6 步中设置。点击**下一步**保存。保存端点后，该按钮将显示为**编辑**。 首次保存会生成您的 webhook 签名密钥，并仅显示一次。在点击**下一步**之前，请复制并安全地存储该密钥：该密钥之后无法再次获取，只能[轮换](https://platform.claude.com/docs/zh-CN/manage-claude/inference-hooks-configuration#rotate-your-signing-secret)。 您的 AI 安全服务器使用此密钥来验证其收到的每个请求上的签名，包括下一步中的连接测试。有关验证流程，请参阅[验证签名](https://platform.claude.com/docs/zh-CN/manage-claude/inference-hooks-endpoint#verify-the-signature)。 在签名密钥对话框上点击**下一步**会重新打开端点对话框，此时多了两个控件： * **自定义请求标头：** 最多 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 安全服务器已响应，但响应体不是有效的裁决。 | | 需要签名密钥 | 您的组织没有签名密钥，因此测试请求将以未签名的方式发送。请点击**请求签名**下的**生成密钥**，然后再次测试。 | 在**失败处理**下，设置**模式**以选择当 AI 安全服务器无法访问或裁决超时时的处理方式： * **阻止该请求：** 当您的 AI 安全服务器无法提供裁决时停止推理（故障关闭）。 * **允许请求：** 让请求在未经检查的情况下继续发送到模型（故障开放）。 下拉菜单的第三个选项**影子模式**是一种逐步推出工具，而不是故障策略；请参阅[影子模式](https://platform.claude.com/docs/zh-CN/manage-claude/inference-hooks-configuration#shadow-mode)。 然后设置**提示词裁定超时（毫秒）**：1 到 10,000 毫秒，默认为 5,000 毫秒。该预算涵盖整个交换过程，较慢的裁决会被视为服务器无法访问，因此请设置您的服务器能够可靠满足的最低值。 此部分中的更改会在您进行更改时即时保存。首次保存时，默认值为**允许请求**和 5,000 毫秒。 在**发布**下，设置**已检查请求（%）**，以便在您启动 AI 安全服务器期间对一定百分比的请求运行检查。该值范围为 0 到 100：100 表示检查所有请求，0 表示关闭检查。 每个请求针对其整个对话轮次只抽样一次，因此单个对话可能在不同轮次之间被部分检查。抽样百分比之外的请求会在未经检查的情况下继续进行，即使故障处理设置为**阻止该请求**也是如此。 若要先针对实时流量评估裁决而不阻止任何人，请在开启强制执行之前将**模式**设置为**影子模式**（第 6 步）；请参阅[影子模式](https://platform.claude.com/docs/zh-CN/manage-claude/inference-hooks-configuration#shadow-mode)。 开启**强制执行裁定**，使 Claude 对每个受管控的提示都以您的 AI 安全服务器的裁决为准，然后在对话框中确认，该对话框会重申您选择的故障处理方式。更改需要大约一分钟才能传达到每个 Anthropic 服务器；已在处理中的请求将按照旧设置完成。关闭它会停止将提示发送到您的 AI 安全服务器，同样在大约一分钟内生效；您的配置会被保留。 位于**强制执行裁定**下方的 **Validate tool calls（验证工具调用）** 还会将 Claude 每个响应中的工具调用发送到您的 AI 安全服务器，并在这些工具调用运行之前等待其裁决；请参阅[工具调用帧](https://platform.claude.com/docs/zh-CN/manage-claude/inference-hooks-endpoint#the-tool-call-frame)。在新配置中，该选项默认开启。当**强制执行裁定**关闭时，它不起作用；与**强制执行裁定**一样，对它的更改传播到每台 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`）记录在您组织的[活动源](https://platform.claude.com/docs/zh-CN/manage-claude/compliance-activity-feed)中。 ### 仅检查选定的角色 **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** 的更改以及对受检查角色的更改会记录在您组织的[活动源](https://platform.claude.com/docs/zh-CN/manage-claude/compliance-activity-feed)中。 ## 自定义提示词拦截消息 在**自定义提示词拦截消息**下，设置最多 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 次失败，并在最后一次失败一小时后清除。 **近期错误**中的错误类型含义如下： | 显示的错误 | 含义 | 是否计入断路器 | | ---------------------------------------------------- | ------------------------------------------------------------------------------------ | ------- | | `DlpWebhookTimeoutError` · `webhook_error` | 您的 AI 安全服务器未在您设置的**提示词裁定超时（毫秒）** 内返回裁决。 | 是 | | `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 安全服务器是健康的。**每分钟失败次数**统计每一次失败，包括永远不会触发断路器的网络和 DNS 错误，因此它可能很高而**熔断器已触发**仍为空。 ## 断路器 可归因于您的 AI 安全服务器的持续 webhook 失败会触发 circuit breaker（断路器）跳闸，从而停止强制执行：不再联系您的服务器，并且您的**失败处理**选择将应用于每个被检查的请求。如果选择了**阻止该请求**，您组织中的用户将被阻止，直到断路器重置。当断路器跳闸时，管理员也会在 claude.ai 通知中心收到通知。 每次触发还会作为 `inference_hooks_circuit_breaker_tripped` 活动记录在您组织的[活动源](https://platform.claude.com/docs/zh-CN/manage-claude/compliance-activity-feed)中，以便您的安全团队或供应商可以通过他们已有的监控（例如接入该动态的 SIEM）针对触发事件发出警报。每次触发只记录一条活动，而不是每个受影响的请求各记录一条。记录功能要求为您的组织启用 Compliance API；请参阅[设置 Compliance API](https://platform.claude.com/docs/zh-CN/manage-claude/compliance-api-access)。 要恢复，请修复服务器，然后重新开启**强制执行裁定**以重置断路器。 熔断器也可以自行重置。从触发后 10 分钟开始，Anthropic 会在后台向您的服务器发送测试请求，以检查其是否已恢复，频率最多约为每分钟一次；此过程不涉及任何用户请求。如果您的服务器返回有效的裁决（允许或拒绝均可），熔断器将重置，强制执行将恢复。否则，熔断器保持触发状态，检查将继续进行。 只有在触发后您的推理钩子设置未发生更改的情况下，自动恢复才会运行。如果您在触发后更改了任何推理钩子设置（包括轮换签名密钥），检查将停止，熔断器将不再自行重置；请在服务器修复后重新开启**强制执行裁定**。自动恢复仅适用于触发情况：如果您自己关闭了**强制执行裁定**，强制执行将保持关闭状态，直到您重新开启它。 ## 轮换您的签名密钥 点击**请求签名**下的**轮换密钥**以替换您的签名密钥。如果您的组织尚无密钥，该按钮会显示为**生成密钥**，并创建第一个密钥。轮换是即时切换的：新密钥会被生成并仅显示一次，旧密钥将无法再被获取，并且任何请求都不会同时使用两个密钥签名，因此不存在可依赖的重叠期。 使用先前密钥签名的请求在轮换后仍可能短暂到达；[验证签名](https://platform.claude.com/docs/zh-CN/manage-claude/inference-hooks-endpoint#verify-the-signature)介绍了您的 AI 安全服务器应如何处理切换。 ## 审计跟踪 推理钩子活动会记录在您组织的[活动源](https://platform.claude.com/docs/zh-CN/manage-claude/compliance-activity-feed)中：配置更改、拒绝、断路器跳闸，以及因无法获得裁决而在未经检查的情况下继续处理的请求。最后一类仅在**强制执行裁定**开启且**模式**为**允许请求**时记录。其原因为 `endpoint_timeout`、调用您的 AI 安全服务器时出现任何其他问题时的 `endpoint_error`，或 Anthropic 一侧故障时的 `internal_error`。在**阻止该请求**或**影子模式**下，失败的请求不会被单独记录。断路器的自动恢复在任何模式下都不会被记录。断路器处于跳闸状态期间，不会记录任何按请求的推理钩子活动；跳闸活动即是活动源对该时间段的记录。拒绝记录带有标识符，可让您将每次拒绝与您自己系统中的对应记录关联起来。 ## 关闭推理钩子 关闭有两个级别： * 在推理钩子设置页面上关闭**强制执行裁定**：在大约一分钟内，您组织的提示将停止发送到您的 AI 安全服务器；已在处理中的请求将按照旧设置完成。设置页面仍然可用，因此您可以在处理 AI 安全服务器期间使用此方式暂停强制执行。 * 在**数据与隐私**设置中关闭**在您的组织中允许**：提示不再被检查，并且推理钩子设置将变为不可用，直到您重新开启它。无论哪种方式，您的端点配置、自定义标头和签名密钥都会被保留；重新开启它会强制将**强制执行裁定**置于关闭状态并清除已跳闸的断路器，因此请在准备就绪时再次开启强制执行。 ## 后续步骤 构建 AI 安全服务器：请求和裁决模式、签名验证以及操作语义。 推理钩子是什么、裁决往返如何工作，以及哪些内容会被发送到您的 AI 安全服务器。