跳至正文

机器翻译。英文版本为权威来源，母语审校尚未完成。

指南

连接 Claude Code

从 OpenTelemetry gen_ai 遥测数据中摄取 Claude Code 会话，并在默认拒绝的执行点治理其工具调用，治理数据保留在本地

最近更新:

Claude Code 是 Olivares AI 的典型协作数据源。平台对它做两件不同的事情，在两个具有相反姿态的界面上：保持它们清晰，因为一个是读优先的，另一个故意处于路径中。

关于通用数据源模型，参见连接数据源；关于执行工作流，参见治理与审批。

观测的内容 vs. 执行的内容

  • 观测（读优先）。 Claude Code 导出 OpenTelemetry；连接器运行一个 OTLP 接收器，将该遥测数据转换为访问映射边、成本样本和身份。此路径绝不处于代理的请求路径中——它在带外摄取。参见访问映射。
  • 执行（默认拒绝）。 Claude Code 的原生 PreToolUse / PostToolUse 钩子可以调用策略执行点（PEP），在工具运行之前返回允许/拒绝/询问。这是你在控制平面必须治理代理而非仅观察时开启的有意介入路径。

你可以只运行观测。执行是可选的和增量的。

观测：OTel 遥测摄取

连接器暴露一个标准的 OTLP 接收器（gRPC 和 HTTP，在常规的 OpenTelemetry 端口上）。它将两种词汇映射到同一管道：

  • Claude Code 自己的 claude_code.* 遥测——工具调用、会话、每请求模型使用，以及（在跟踪 beta 下）子代理层次结构。
  • 供应商中立的 OpenTelemetry GenAI 语义约定（gen_ai.*），因此任何 OTel 检测的代理都能馈送同一访问映射和 FinOps，不仅限于 Claude Code。

从该遥测数据中，连接器推导出会话归因的访问边（哪个会话触及了哪个资源，读还是写）、每个会话连接的 MCP 服务器的拓扑边，以及每请求的成本样本。MCP 服务器暴露 readOnlyHint / destructiveHint 内省；这些是 MCP 规范标记为不可信的 R/RW 信号，因此连接器将它们视为佐证证据，绝不仅凭提示升级边。

OLIVARES_SOURCES_CONFIG 是一个 JSON 文档（在引擎启动前读取）；kind: "claude" 选择此连接器。http_addr 默认绑定回环地址——参见下面的警告。

{
  "sources": [
    {
      "name": "claude",
      "kind": "claude",
      "tenant": "<tenant-ref>",
      "config": {
        "enable_http": "true",
        "http_addr": "127.0.0.1:4318"
      }
    }
  ]
}

GenAI 配置文件是可选启用的

gen_ai.* 语义约定仍处于开发状态，因此将它们映射到成本和边是显式的可选启用。将连接器的 semconv_opt_in 设置为规范自己的令牌（镜像 OTEL_SEMCONV_STABILITY_OPT_IN）；关闭时，gen_ai.* 记录仍然馈送存活性看门狗但不进行成本核算。该配置文件读取当前和已弃用的属性名称（真实框架仍在发出），接受跟踪或日志上的数据，并对同时通过两者到达的操作进行去重，以避免 FinOps 双重计费。消息内容从不读取——内容键仅用于检测发射器使用的方言。

默认最小数据

连接器仅保留结构性遥测——会话、身份、工具名称、R/RW 模式、时间——即使客户端配置为发出提示文本或工具正文。原始工具输入在成为观测结果之前被缩减为脱敏的资源引用。保留任何内容类别是一个单独的、受审计的可选启用。参见允许与观测和保真度了解覆盖范围和归因如何分层。

:::caution 协作接收器未经认证且默认绑定回环地址。任何能到达套接字的人都可以伪造遥测数据，因此不要在共享网络上暴露它。离线主机代理应使用非协作的内核后备，而非公共 OTLP 端口。 :::

执行：钩子 PEP

要治理——而非仅观测——将 Claude Code 的钩子连接到 PEP。代理的 PreToolUse 钩子将每个工具调用通过管道传给一个受管钩子命令，该命令将其转发到 PEP 并中继裁决。连接器只拥有钩子线协议和默认拒绝的默认值；实际决策通过控制平面实现的接口委托给实时 PDP（Cedar/ABAC）、确定身份平面、人在环审批和防篡改账本。

Claude Code ──PreToolUse hook──▶ managed hook command ──HTTP──▶ governed PEP
   (agent)        (stdin JSON)                                  (loopback)
                                                                    │
              allow │ deny │ ask  ◀──── governed decision ──────────┘
            (+ updatedInput rewrite)   deny-closed on any failure

PEP 可以返回的内容，已针对 Claude Code 的钩子合约验证：

  • PreToolUse ——allow、deny 或 ask，带有可选的受治理 updatedInput 重写（缩小路径、添加 --dry-run、重定向获取）。优先级为 deny 高于 ask 高于 allow。
  • PostToolUse ——Claude Code 没有输出重写字段，因此 PostToolUse 钩子只能在策略标记的结果上阻止进一步处理。连接器不假装重写模型已经看到的结果；它脱敏的是它保留和审计的内容。

默认拒绝是全面的

在数据路径中介入是不对称风险，因此每个失败模式都视为拒绝，绝不开放：缺失的决策者、决策错误（PDP 不可达、身份未解析、无法打开的审批）或格式错误的钩子载荷都返回清晰的拒绝。裁决的零值本身就是拒绝。ask 路由到受治理的审批；审批绑定到精确工具调用的计划哈希，因此不能被重用来授权不同的调用（反 TOCTOU）。

在生产中，钩子在 Claude Code 的企业受管设置层级中发布，启用了仅受管钩子，因此开发者无法从较低优先级的设置文件中禁用或替换它。请求上标记的身份提示细化归因；权威主体是决策者解析的持有者，要求确定身份的策略会拒绝只能近似归因的任何内容。

更轻量的本地模式

连接器还支持在钩子的热路径上评估的本地进程内执行策略，无需引擎往返——因此慢速或不可达的控制平面永远不会卡住开发者的工具调用。它是可选启用的：没有配置规则时，钩子被观测但绝不被把关。这是默认协作的姿态；上面的受治理 PEP 是你在控制平面必须作为决策者时切换到的相反姿态。

反规避

因为观测路径是协作的，连接器监视一个停止发出 OTel 但其钩子仍在触发的会话——这是一个代理在继续操作的同时禁用了其导出器的特征。注意它不做什么：一个完成的代理会安静下来，仅安静本身绝不会被标记。真正非协作活动的基础事实是内核/eBPF 后备，而非这个启发式。

气隙：什么留在本地，什么不留

控制平面在你自己的基础设施内运行，可以气隙运行——治理和观测数据（访问边、决策、审计、成本样本）永远不会离开你的边界。OTLP 接收器和钩子 PEP 是本地套接字；引擎不会拨号回家。

一个诚实的注意事项：Claude 推理永远不是气隙的。 Claude Code 仍然将其提示发送到 Anthropic 的 API（直接或通过 Bedrock、Vertex 或 Foundry）以获取响应。控制平面的气隙保持你资产的治理数据在本地；它不将模型移到本地。只有真正可自托管的模型（例如通过 vLLM/Ollama）才能完全离线运行。参见什么是 Olivares AI 和诚实与局限。

下一步

搜索文档