Claude Code 연결 — Olivares AI

OpenTelemetry gen_ai 텔레메트리에서 Claude Code 세션을 수집하고 기본 거부 시행 포인트에서 도구 호출을 거버넌스, 거버넌스 데이터는 온프레미스 유지

Claude Code는 Olivares AI의 정식 협력적 소스입니다. 플랫폼은 두 가지 서로 다른 작업을 수행하며, 두 표면에서 반대의 자세를 가집니다: 하나는 읽기 우선이고 다른 하나는 의도적으로 경로에 위치하므로 구분하세요.

일반적인 소스 모델은 소스 연결을 참조하세요; 시행 워크플로우는 거버넌스 및 승인을 참조하세요.

관찰되는 것 vs 시행되는 것

관찰 (읽기 우선). Claude Code는 OpenTelemetry를 내보냅니다; 커넥터는 해당 텔레메트리를 접근 맵 에지, 비용 샘플 및 신원으로 변환하는 OTLP 수신기를 실행합니다. 이 경로는 에이전트의 요청 경로에 절대 위치하지 않습니다 — 대역 외에서 수집합니다. 접근 맵을 참조하세요.
시행 (기본 거부). Claude Code의 네이티브 PreToolUse / PostToolUse 후크는 도구가 실행되기 전에 allow / deny / ask를 반환하는 정책 시행 포인트(PEP)를 호출할 수 있습니다. 이것은 제어 평면이 에이전트를 관찰만 하는 것이 아니라 거버넌스해야 할 때 켜는 의도적으로 삽입된 경로입니다.

관찰만 실행할 수 있습니다. 시행은 옵트인이며 추가적입니다.

관찰: OTel 텔레메트리 수집

커넥터는 표준 OTLP 수신기(gRPC 및 HTTP, 기존 OpenTelemetry 포트)를 노출합니다. 두 어휘를 동일한 파이프라인에 매핑합니다:

Claude Code의 자체 claude_code.* 텔레메트리 — 도구 호출, 세션, 요청별 모델 사용, (트레이싱 베타에서) 서브에이전트 계층.
벤더 중립 OpenTelemetry GenAI 시맨틱 규약(gen_ai.*), Claude Code만이 아니라 OTel 계측된 모든 에이전트가 동일한 접근 맵과 FinOps를 공급합니다.

이 텔레메트리에서 커넥터는 세션 귀속 접근 에지(어떤 세션이 어떤 리소스에 접근했는지, 읽기 또는 쓰기), 세션이 연결하는 각 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 모드, 타이밍. 원시 도구 입력은 관찰이 되기 전에 수정된 리소스 참조로 축소됩니다. 콘텐츠 카테고리 유지는 별도의 감사된 옵트인입니다. 커버리지와 귀속이 어떻게 계층화되는지는 허용됨 vs 관찰됨과 충실도를 참조하세요.

:::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 후크는 정책 플래그된 결과에 대해 추가 처리를 차단만 할 수 있습니다. 커넥터는 모델이 이미 본 결과를 재작성하는 척하지 않습니다; 수정하는 것은 자체가 유지하고 감사하는 것입니다.

기본 거부는 전면적

데이터 경로에 삽입하는 것은 비대칭 위험이므로, 모든 실패 모드는 **기본 거부(closed)**입니다, 절대 열리지 않습니다: 누락된 결정자, 결정 오류(PDP 도달 불가, 신원 미해결, 열 수 없는 승인), 잘못된 형식의 후크 페이로드 모두 깨끗한 deny를 반환합니다. 판정의 제로 값 자체가 deny입니다. ask는 거버넌스된 승인으로 라우팅됩니다; 승인은 정확한 도구 호출의 플랜 해시에 바인딩되므로, 다른 호출을 인가하는 데 재사용할 수 없습니다 (TOCTOU 방지).

프로덕션에서 후크는 Claude Code의 엔터프라이즈 관리형 설정 계층에서 managed-hooks-only가 활성화된 상태로 제공되므로, 개발자가 낮은 우선순위 설정 파일에서 비활성화하거나 교체할 수 없습니다. 요청에 찍힌 신원 힌트가 귀속을 정제합니다; 권위적 주체는 결정자가 해결하는 베어러이며, 확고한 신원을 요구하는 정책은 approximate로만 귀속할 수 있는 것을 거부합니다.

더 가벼운 로컬 모드

커넥터는 엔진 왕복 없이 후크의 핫 경로에서 평가되는 로컬 인프로세스 시행 정책도 지원합니다 — 따라서 느리거나 도달할 수 없는 제어 평면이 개발자의 도구 호출을 멈추지 않습니다. 옵트인입니다: 규칙이 구성되지 않으면 후크는 관찰되며 절대 게이트되지 않습니다. 이것이 기본 협력적 자세입니다; 위의 거버넌스된 PEP는 제어 평면이 의사 결정자여야 할 때 전환하는 반대 자세입니다.

회피 방지

관찰 경로는 협력적이므로, 커넥터는 후크가 여전히 발동하는 동안 OTel 출력을 중단하는 세션을 감시합니다 — 계속 행동하면서 내보내기를 비활성화한 에이전트의 서명입니다. 하지 않는 것에 주목하세요: 종료된 에이전트는 조용해지며, 조용함만으로는 절대 플래그되지 않습니다. 진정으로 비협력적인 활동에 대한 기반 진실은 이 휴리스틱이 아닌 커널/eBPF 백스톱입니다.

에어갭: 집에 남는 것과 남지 않는 것

제어 평면은 자체 인프라 내에서 실행되며 에어갭할 수 있습니다 — 거버넌스 및 관찰 데이터(접근 에지, 결정, 감사, 비용 샘플)는 경계를 절대 벗어나지 않습니다. OTLP 수신기와 후크 PEP는 로컬 소켓입니다; 엔진은 전화하지 않습니다.

정직한 주의사항: Claude 추론은 절대 에어갭되지 않습니다. Claude Code는 여전히 응답을 받기 위해 Anthropic의 API(직접 또는 Bedrock, Vertex, Foundry를 통해)에 프롬프트를 보냅니다. 제어 평면을 에어갭하면 환경의 거버넌스 데이터가 집에 유지됩니다; 모델을 온프레미스로 이동하지 않습니다. 진정으로 자체 호스팅 가능한 모델(예: vLLM/Ollama)만 완전히 오프라인으로 실행됩니다. Olivares AI란 무엇인가와 정직함과 한계를 참조하세요.

다음 단계

거버넌스 및 승인 — PEP가 시행하는 정책과 ask → 사람 승인 루프 작성.
접근 맵 — 관찰된 에지가 공급하는 것.
Claude Code 거버넌스 — 이 경로의 제품 개요.