团队与企业

Grok Bot 推理钩子

推理钩子会把受管控的每个 Grok Bot 模型请求发送到组织自建或安全供应商提供的 AI 安全服务器。Cursor 为每个请求签名，等待服务器判定允许或拒绝，并在被拒绝时停止请求。这样，你的策略就能在模型看到提示词或 Grok Bot 收集的内容前对其进行检查。其他控制措施见 Grok Bot 安全。

Beta 推理钩子目前处于测试阶段，面向所有 Enterprise 团队开放。团队管理员可在仪表盘配置，仅覆盖 Grok Bot。参见覆盖范围（Coverage）。

工作原理

• 每个受管控的模型请求都会接受检查。Grok Bot 调用模型前，Cursor 会向你的端点发送已签名的 prompt 帧，其中包含截至当时的对话。请求会一直等待，直到收到判定结果或超时。如果一个回合多次调用模型，例如在多次工具调用之间调用模型，每次调用都会发送一帧。
• 由你的服务器作出判定。 allow 会将请求放行至模型；deny 会停止请求并结束当前回合，发出消息的成员会看到拦截提示。
• 失败处理取决于运行模式。当端点超时、返回错误或响应不含有效判定时，运行模式决定放行还是拦截请求。检查失败本身不会被记为拒绝判定。
• 只检查模型输入。端点判断的是即将发送给模型的内容。工具调用及其结果在工具执行后才会出现在帧中。Grok Bot 给成员发送回复也属于工具调用，因此成员会先收到回复，之后它才会出现在帧中。拒绝判定只能阻止下一次模型调用，无法撤销已经发生的操作。

设置推理钩子

你需要拥有 Enterprise 团队的管理员权限。

1. 准备安全服务器。在安全供应商的控制台创建推理钩子集成，或自行托管满足以下端点要求的服务器。设置对话框的 Security Vendor 列表提供供应商预设及配置清单。
2. 打开 Inference Hooks。在 Cursor 仪表盘中选中团队，打开 Inference Hooks。该入口位于 Grok Bot 页面的 Security & Compliance 区域。
3. 添加端点。点击 Set Up Endpoint，选择供应商或 Custom Endpoint，输入 Endpoint URL 及所需的 Custom Headers（例如服务器的 API 密钥）。Cursor 会在保存时检查 URL。
4. 复制签名密钥。首次保存端点时，系统会生成前缀为 whsec_ 的签名密钥，仅显示一次。将它粘贴到供应商的 webhook 密钥字段或服务器配置中，以便验证每个请求。
5. 测试连接。点击 Test Connection。Cursor 会发送模拟请求，并显示判定结果或检查失败的原因。如果此时收到拒绝判定，说明策略会拦截测试提示词，正式执行前应先调整。
6. 先使用影子模式。新配置默认使用 Shadow Mode。开启 Enforce Verdicts 即可开始发送请求。端点会收到所有覆盖范围内的请求，拒绝判定会写入审计日志，但不会实际拦截。确认判定符合预期后，可将 Mode（位于 Failure Handling 下）设为 Allow the Request 或 Block the Request。

设置变更会在约一分钟内生效，已在处理中的请求会按原设置完成。

只要已保存端点、开启 Enforce Verdicts 且覆盖 Grok Bot，无论使用哪种模式或设置何种抽检比例，Grok Bot 都会跳过原本可能在回合开始前进行的部分模型调用，因此开始回复的时间可能稍晚。

端点要求

• 使用 https:// URL 和 443 端口。主机必须能通过公网路由访问，并提供由公共证书颁发机构签发的证书。Cursor 拒绝私有地址、环回地址和运营商级 NAT 地址。
• 不支持重定向和隧道。Cursor 不会跟随重定向，遇到重定向会视为检查失败。也不接受反向隧道主机。
• 不要在 URL 中包含密钥。管理员可看到明文 URL，因此不能在其中放置凭据、查询字符串或片段。请将凭据放入加密存储的自定义请求头。URL 最长为 2,048 个字符。
• 每个请求都要返回判定结果。请返回 HTTP 200 和 JSON 格式的判定结果，Test Connection 请求也不例外。参见判定结果。

自定义请求头

• 最多可添加 16 个请求头。名称只允许字母、数字和连字符，不含下划线，最长 128 个字符。值仅限可打印 ASCII 字符，最长 8,192 个字符。
• 请求头的值只能写入。保存后，页面只显示请求头名称。修改任意一个请求头时，都需要重新输入所有值。
• 更改 URL 会清空已保存的值。请求头的值只会发送到最初保存这些值时指定的端点。更改 URL 后，请在 Edit 中重新输入这些值。在此之前，请求不会携带它们。
• 部分请求头由 Cursor 保留。你不能添加 Host、Cookie、User-Agent、Accept-Encoding 等请求头、连接相关请求头（例如 Transfer-Encoding）、客户端地址请求头（例如 X-Real-IP），也不能使用以下前缀：Content-、Proxy-、X-Forwarded-、Webhook- 或 X-Cursor-。

签名密钥

每个请求都带有 Standard Webhooks 请求头，让服务器能够拒绝并非由 Cursor 发送的请求：

每个请求恰好携带一个签名。轮换密钥时，点击 Rotate Secret，入口位于 Request Signing。新密钥仅显示一次，Cursor 会在约一分钟内改用新密钥签名。在此之前请继续接受旧密钥。轮换密钥属于设置变更，会影响熔断器。

Test Connection

Test Connection 会发送已签名的 prompt 帧，其中 source.application 设为 config-test，消息是固定测试内容，不含用户内容，也不关联成员、会话或模型。测试使用已保存的密钥签名，并等待到已保存的判定超时时限。从端点对话框运行时，它使用表单里的 URL 和请求头；从页面运行时，则使用已保存的值。

运行模式

Enforce Verdicts 控制是否发送。关闭时，Cursor 保留设置但不发送任何请求。开启时，由 Mode 决定检查无法完成时的处理方式：

在 Allow 和 Block 模式下，模型请求会等待判定。在 Shadow 模式下，Cursor 仍在相同时间发送相同的帧，但会在后台发送：请求不等待，成员看不到提示，拒绝和失败会写入审计日志。负载过高时，Cursor 可以跳过影子检查，跳过的检查不会生成审计记录。

以下情况会导致检查失败：服务器超时、返回非 200 状态码、响应体不是 JSON 判定结果或超过 64 KiB、返回的 action 未使用任何一种有效取值，即 allow 或 deny，或服务器不可达。大于 64 MiB 的帧也会被判为检查失败。

一旦 Cursor 取得设置，Block 模式会拦截所有未能完成检查的请求，即使原因在 Cursor 一侧。如果 Cursor 根本无法加载团队的推理钩子设置，就无法确定所选模式，此时会放行请求，并在审计日志中记为失败时放行，原因为 config_unavailable。

判定超时

Verdict Timeout (ms) 的范围为 1 至 10,000 毫秒，默认 5,000。时限涵盖连接、TLS 握手、请求和响应的整个过程。如果连接失败，Cursor 会在同一时限内重试一次，使用相同的 webhook-id 和签名，因此你可以按 webhook-id 去重。服务器一旦响应，Cursor 便不会重试。在超时时限之外，Cursor 自身的处理最多还需约半秒。

分阶段启用

Requests Inspected (%) 用于在启用端点的过程中仅将一定比例的受管控请求发送给端点。抽样以整个回合为单位：同一回合中的所有请求（包括子 Agent 的请求）要么全部检查，要么全部跳过。即使在 Block 模式下，未被抽中的请求也会未经检查直接放行。设为 0% 会关闭检查。

熔断器

由服务器引起的持续失败（如超时、错误状态码、TLS 错误和格式错误的判定结果）会触发熔断。DNS 和连接错误、被 Cursor 拒绝的 URL，以及大于 64 MiB 的帧会记为失败，但不会触发熔断。

• 熔断期间，Cursor 停止发送请求。此时运行模式对所有受管控请求生效：Block 模式全部拦截；Allow 和 Shadow 模式全部未经检查放行。审计日志会在每次熔断时记录一个 inference_hooks_circuit_breaker_tripped 事件，熔断期间不逐请求记录事件。
• 系统自动尝试恢复。从熔断发生 10 分钟后起，Cursor 会定期向服务器发送 Test Connection 请求。只要收到允许或拒绝判定，就会重置熔断器。
• 修改任何设置都会停止自动恢复。这也包括轮换密钥。修复端点后，点击 Reset，或将 Enforce Verdicts 关闭后重新开启。

Cursor 暂停服务

紧急情况下，Cursor 可暂停某个团队或所有团队的推理钩子。暂停期间不发送任何帧，受管控请求会放行，其中大多数在审计日志中记为失败时放行，原因为 kill_switch。Test Connection 会显示“Inference hooks are temporarily paused by Cursor.”。

成员会看到什么

当服务器拒绝某个请求时，Grok Bot 桌面和移动应用仅向发送被拦消息的成员显示拦截提示，位置在该成员与 Bot 的对话中。在移动端，提示位于消息框上方，内容包括：

• 标题 Blocked by your organization's policy。
• 服务器返回的 deny_reason，以及之后显示的 Blocked Message。
• 操作指引，包括 Edit 按钮和 Reset 按钮。Edit 会将被拦截的消息从对话中撤回。如果消息框中没有其他草稿，其文本会被放回消息框，让成员修改后重发。Reset 会清空对话。移动端和新版桌面端会先请成员确认。当 Cursor 无法将对话回滚到被拦消息之前时，只会显示 Reset 按钮。

Blocked Message 最多 500 个字符，默认文案为“Your organization's security policy blocked this request.”。关闭时仅显示服务器返回的 deny_reason。可用这段文字告诉成员下一步该做什么，例如联系谁。

重置后，Bot 不再看到该对话中之前的消息，并停止为该对话启动的后台辅助任务。其他已启动的工作（例如云端 Agent 和后台命令）仍会继续，也可以回报结果。Bot 的记忆、文件、例行任务和设置都会保留。Edit 会将对话回滚到被拦消息之前。两种操作都不会撤销 Bot 已完成的工作，例如已写入的文件。

如果重置后对话立即再次被拦截，提示中不会有按钮。提示会说明匹配到的内容可能在 Bot 的记忆或文件中，请成员前往移除或联系管理员协助。

在 Block 模式下检查失败时，桌面应用会显示 Your organization's policy check is unavailable，并说明组织要求在模型响应前完成策略检查，本次检查未完成，请稍后重试；若持续出现，请联系管理员。移动应用也会提示策略检查不可用，请稍后重试或联系管理员。此时不显示自定义的 Blocked Message，也没有 Edit 或 Reset 按钮。

其他位置显示的信息较少：

• 共享 Bot 仅通知发送者。在共享 Bot 中，只有发出被拦消息的队友能在自己的聊天中看到提示和按钮。Edit 或 Reset 也只影响该聊天。Bot 所有者看不到拒绝理由或自定义的 Blocked Message。聊天室和群聊中没有 Edit 或 Reset 按钮。
• Slack 会在对话中回复。Bot 会回复“组织的策略拦截了此对话，因此我无法回复”。在一对一私信中，它还会引用拒绝理由和自定义的 Blocked Message；频道消息串和多人私信中不会显示这两项。回复提供 Remove blocked message（作用同 Edit）和 Reset（先要求确认）。如果 Cursor 无法回滚对话，则只提供 Reset。任何有权使用该 Bot 并已关联 Cursor 账号的人都可点击。被撤回的消息在 Slack 中仍可见，但 Bot 不再能看到。如果重置后立即再次被拦截，则不显示按钮。在 Block 模式下检查失败时，Bot 会返回通用错误消息，不显示策略提示。
• 移动应用在其他位置只显示失败提示。在群聊及不属于该成员个人的对话中，应用显示“Bot failed to respond”，并说明组织的策略已拦截，请发送不同的消息，若问题持续则联系管理员。这里不会显示拒绝理由、自定义的 Blocked Message 或按钮。
• 其他 Cursor 应用仅显示标题。
• 旧版桌面应用不显示按钮。根据版本不同，提示可能显示拒绝理由、自定义的 Blocked Message，以及“发送不同的消息，若问题持续则开始新聊天”的指引；也可能仅提示组织策略已拦截，请发送其他消息或联系管理员。
• 后台辅助任务停止时不显示提示。当 Grok Bot 启动的辅助任务被拦截时，Bot 会获知组织策略终止了该任务，但不会收到拒绝理由。
• 例行任务会停止并记录此次拦截。Cursor 仪表盘的运行历史会显示 Blocked by your organization's policy 或 Your organization's policy check is unavailable（Block 模式下检查失败时）。提示附带固定的说明，不包含拒绝理由。Grok Bot 应用的例行任务列表只显示运行失败。
• 邮件、Linear 和其他已连接渠道不会收到回复。

被拦的消息会一直保留在对话中，直到有人将它撤回或重置对话。在此之前，Grok Bot 会在后续每个请求中再次发送这条消息，你的服务器也会重新判定。扫描完整对话记录的策略会持续拒绝该对话。仅判定最新用户消息的策略则会在成员发出不同内容后允许对话继续。

请求获准或处于 Shadow 模式时，成员不会看到提示。Shadow 模式同样会将对话发送到你的端点，请先告知成员组织将检查 Grok Bot 请求，再开启 Enforce Verdicts。

覆盖范围（Coverage）

覆盖：团队成员与 Grok Bot 对话时产生的模型请求，包括回合中的每一步、子 Agent、Grok Bot 为长对话撰写的摘要，以及例行任务。共享 Bot 或聊天室使用其所属团队的推理钩子，个人 Bot 则使用所有者选定的团队配置。每个请求会分别生成一帧，包含截至当时的对话。

不覆盖：

• 不检查模型响应。参见工作原理。
• 请求中不属于对话的部分不会发送。系统提示词、工具定义以及模型的隐藏推理不会发送到端点。Cursor 也会省略它为模型添加的大部分文本，例如提醒和时间戳。
• 不发送辅助性模型调用。这些调用为对话提供支持，例如撰写聊天标题、执行 Auto Review 或保存记忆，并不直接延续对话。
• 不覆盖其他 Cursor 功能。包括 Cloud Agents、编辑器中的 Agent、CLI、Agent SDK、Tab、embedding 和本地模型。
• 不在动作执行时检查该动作。工具执行、已连接应用的操作及成员 Grok Bot 电脑的网络流量，仅在其输出作为后续帧中的工具结果返回给模型时，才会到达端点。要管控操作，请使用网络策略和 Auto Review。

请求格式

Cursor 使用 HTTPS POST 请求发送每一帧，请求体为紧凑的 JSON。请求头名称均为小写。

标准请求头（如 host 和 content-length）也包含在每个请求中。

{
  "type": "prompt",
  "request_id": "req_6b1f0c2e-4d7a-4f1e-9a53-2c8d7e41b9a0",
  "tenant_id": "team_4mQvT8yLcN2pR6",
  "actor": {
    "type": "user",
    "id": "user_8hJw3KzP5sXq1V7nB2cF9mD4tR",
    "email_address": null
  },
  "source": { "application": "grok-bot" },
  "session_id": "3f2c9a71-58e4-4b0d-9c6a-0d1e7b25a4f8",
  "model": "<Cursor model identifier>",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Check the Q3 renewals sheet for accounts at risk and draft a note to the account team."
        },
        {
          "type": "attachment",
          "file_name": null,
          "media_type": "image/png",
          "size_bytes": 184320,
          "text": null
        }
      ]
    }
  ],
  "metadata": {}
}

帧字段

消息

• 角色为 user 和 assistant。工具结果归在 user。
• 块的类型包括 text、tool_use、tool_result 和 attachment。。其中，tool_use 块指明工具并保存其 input；对应的 tool_result 保存输出。Grok Bot 提供给模型的上下文（如规则、共享记忆及可用的已连接应用）通常位于 attachment 块的 text 中。图像表示为 attachment，只包含媒体类型和大小，不含图像字节或 URL。
• 每帧都包含截至当前的完整对话。帧不是增量数据，每帧都会再次携带之前的消息。对话较长时，Grok Bot 会用摘要取代较早的消息。
• 向成员发送回复属于工具调用。成员看到的内容由 Grok Bot 通过工具发送，因此回复位于 tool_use 的输入字段中，并不写入 assistant 消息的以下字段：text。
• Cursor 不会向帧添加密钥值。上下文可能列出 Bot 可用凭据的名称和说明，但不会包含实际值。

针对这些帧编写策略

• 验证签名。不要依赖 User-Agent 或源 IP。如果 Inference Hooks 页面列出 Source IP Ranges，入口位于 Request Signing，也可以把这些地址加入白名单。
• 将 ID 视为不透明字符串。不要解析 tenant_id 或 actor.id。请按 actor.id 映射成员，因为帧不包含邮箱。
• 将 source.application 视为开放取值集合。Cursor 会随覆盖范围扩展添加新值。此字段仅供参考，不应作为安全控制措施。
• 扫描所有块类型，不要只扫描 text。。上下文通常位于附件的 text 中；对成员的回复和对已连接应用的调用则位于 tool_use 的输入中。
• 不要依赖 tool_result.is_error。。其值为 false 时，工具调用也可能失败；大多数失败的工具调用都会返回该值。

判定结果

返回 HTTP 200 及一个 JSON 对象：

{
  "action": "deny",
  "deny_reason": "This message contains a customer account number. Remove it and try again.",
  "reference_id": "policy-7f3c21"
}

• action 可取 allow 或 deny。其他值均视为检查失败。
• deny_reason 会显示在发信成员看到的拦截提示中。Cursor 最多保留 500 个字符。
• reference_id 是你为判定指定的标识符，会写入 Cursor 审计日志。最多 50 个字符，可使用 A-Z、a-z、0-9 和 .、_、:、/、-。格式有误时，仅丢弃该字段，拒绝判定仍然生效。
• 忽略未知字段。Cursor 最多读取 64 KiB 未压缩内容，并忽略 Cookie。

请为 config-test 帧也返回判定结果。此类帧来自 Test Connection 和熔断恢复检查，不应计入成员流量报告。

审计日志

可在团队的审计日志中查看推理钩子活动。事件载荷仅包含标识符和代码，不会包含提示词内容、拒绝理由、签名密钥或请求头值。放行请求不会生成相应的允许事件。

在 inference_hooks_signing_secret_generated 事件中，设置字段显示变更后的状态。轮换密钥时会递增 config_version。首次生成密钥时，该值与同次保存产生的 inference_hooks_config_updated 事件相同。

Cursor 在所有模式下均记录请求检查失败：Allow 和 Shadow 记为失败时放行，Block 记为失败时关闭。系统也会记录熔断器自动恢复。失败时放行和失败时关闭事件的 reason 表示检查失败的具体原因（timeout、non_200_status、unparseable_response、oversized_response、invalid_action、transport_error、tls_error、endpoint_rejected、frame_too_large）、Cursor 一侧的原因（endpoint_not_allowlisted、config_unavailable），或仅在失败时放行时出现的暂停原因（kill_switch）。可使用这些事件名称和 reason 值构建 SIEM 规则。

拒绝或失败事件中的 request_id 与帧中的 request_id 和 webhook-id 相同，可用于将供应商记录与审计日志关联起来。

Inference Hooks 页面还会显示端点健康情况，包括状态、判定延迟、每分钟失败数、过去 24 小时的拦截率，以及近期错误的类型和状态码。这些指标未覆盖全部流量，因此可能低于供应商统计的数据。

隐私与 Privacy Mode

• Cursor 不保留发送到钩子的内容。Cursor 通过 HTTPS 将帧发送至端点，在收到判定后丢弃。帧内容不会写入 Cursor 的数据库、日志、指标或追踪记录。
• 端点数据由你决定如何保留。端点属于你的组织或安全供应商。存储什么、存储位置及保留时长取决于配置和与供应商的协议。Cursor 无法控制这些数据。
• Privacy Mode 继续生效。模型请求本身仍完全按照团队的 Privacy Mode 设置处理，与未配置钩子时相同，钩子也不会额外保存请求副本。无论成员采用哪种 Privacy Mode，受覆盖的请求均会运行推理钩子，因为管理员已指示 Cursor 向组织自己的端点发送请求。
• 帧字段仅通过不透明 ID 标识人员。 actor.email_address 始终为 null。

Cursor 仅保留运行此功能及展示运行结果所需的数据：

• 设置及加密保存的密钥。请求头值和签名密钥会加密存储。
• 仅含标识符和代码的审计日志事件。其中包括服务器返回的 reference_id，详见审计日志。
• 不含对话内容的健康指标。包括计数、延迟、近期错误的类型及状态码。
• 与被拦截回合一起加密存储的拦截提示。你的服务器返回的 deny_reason 和自定义 Blocked Message，都会与 Grok Bot 对被拦截回合的记录一同加密保存。

故障排除

为什么在 Grok Bot 页面找不到 Inference Hooks？

此页面面向 Enterprise 团队管理员，显示仪表盘当前选定团队的信息。请确认已选择正确的团队。如果页面显示“Inference hooks aren't available yet”，请联系客户经理。

为什么端点 URL 被拒绝？

检查端点要求。常见原因包括使用 443 以外的端口、URL 中包含查询字符串或凭据、使用隧道主机，或域名解析到私有地址。

为什么 Test Connection 提示需要签名密钥？

首次保存端点时，Cursor 才会生成签名密钥。请先保存端点，将密钥复制到供应商控制台，然后重新测试。

为什么我的服务器拒绝 Cursor 的请求？

多数拒绝是签名或凭据不匹配所致。请将当前签名密钥粘贴到服务器；如果验证器需要，请保留 whsec_ 前缀，并确认验证器使用标准 base64 解码密钥。检查 API 密钥请求头是否已保存。如果更改了端点 URL，请重新输入请求头值。轮换后，Cursor 会在约一分钟内切换到新密钥。

为什么 Test Connection 返回拒绝判定？

你的服务器策略拒绝了 Cursor 的模拟测试提示词。在 Allow 或 Block 模式下，此类策略也会拦截成员请求。请先调整策略或其默认动作，再启用强制执行。

为什么请求超时？

服务器的响应时间超过了判定时限。请在健康面板和供应商报告中检查判定延迟。较轻量的扫描配置可更快响应。可以将 Verdict Timeout (ms) 调高至 10,000。

为什么我的端点收不到请求？

确认已保存端点、Enforce Verdicts 已开启、覆盖范围（Coverage） 包含 Grok Bot、Requests Inspected (%) 大于 0，并且熔断器未触发。只有团队成员的 Grok Bot 对话受此设置管控。如果 Test Connection 报告推理钩子已暂停，表示 Cursor 暂停了此功能。

为什么成员会看到策略检查不可用？

当前使用 Block 模式且检查失败，或熔断器已触发。请查看 Recent Errors，入口位于 Inference Hooks 页面。如需在修复端点期间让成员继续工作，可切换到 Allow the Request。

熔断器已触发，如何恢复？

修复端点，运行 Test Connection，然后点击 Reset。修改任何设置都会停止自动恢复。如果在触发熔断后修改过设置，请手动重置。

为什么一次拦截后，对话中的每条消息都被拦截？

被拦截的消息会保留在对话中，随之后的每个请求发送到你的服务器。若策略扫描完整对话记录，这些请求就会逐一被拒绝。请选择 Edit（桌面或移动应用的拦截提示中），或选择 Remove blocked message（Slack 中 Bot 的回复里），即可撤回原消息并发送不同内容。Reset 则会清空对话。如果重置后立即再次被拦截，触发策略的内容可能在 Bot 的记忆或文件中，请前往移除。如果策略仅判断最新用户消息，成员发送不同内容后对话即可继续。

为什么在审计日志的筛选器中看不到推理钩子事件？

只有团队启用推理钩子时，筛选器才会显示这些事件类型。此前已记录的事件仍然可以在日志中看到。

相关页面

• Grok Bot 安全
• 面向团队和企业的 Grok Bot
• 合规与监控
• 隐私与数据治理