Подключение Claude Code (кооперативный путь)

Claude Code — это канонический кооперативный источник для Olivares AI. Он эмитит телеметрию OpenTelemetry (OTLP) об инструментах, которые он запускает, а MCP-серверы, с которыми он общается, раскрывают подсказки интроспекции (readOnlyHint / destructiveHint) о том, читает ли инструмент или пишет. Вместе они питают модуль III — карту доступа R/RW рёбрами высокой точности, атрибутированными агенту, — кооперативной половиной картины permitted-vs-observed.

Эта страница подключает этот путь: направляет экспортёр OTLP Claude Code на приёмник движка, затем объявляет источник, чтобы его телеметрия стала рёбрами доступа. Об общем механизме подключения источников и о том, как это вписывается, см. Подключение источника и обзор архитектуры. О форме нормализованных событий, которые это производит, см. справочник событий.

Кооперативный, не авторитетный

Кооперативный путь — высокоточный, но с уровнями доверия. Телеметрия инструментов OTLP атрибутируется конкретной сессии агента; аннотации MCP — это полезный сигнал R/RW, но они недоверены по спецификации MCP и подтверждаются, никогда не доверяются в одиночку (см. Честность и ограничения). Для активности вне кооперации агента — или чтобы поймать агента, переставшего эмитить — сочетайте это с некооперативным резервным механизмом (kernel/eBPF) и нативным аудитом хранилища (pgAudit, CloudTrail). Эта страница — только о кооперативном источнике.

Что вы получаете от этого источника

После подключения телеметрия Claude Code нормализуется в модель данных движка и передаётся в модуль III:

Выход	Происхождение	Примечания
Ребро доступа сессия агента → ресурс (чтение/запись)	сигнальный источник otel	достоверность attributed — инициатором является конкретная сессия, а не общая сервисная учётная запись
Ребро MCP-сервера сессия → MCP-сервер	сигнальный источник otel	режим unknown (соединение само по себе не является доступом; это топология/инвентаризация)
Подсказка R/RW из интроспекции MCP	сигнальный источник mcp_annotation	недоверенная — подтверждающий сигнал, никогда не ребро сам по себе
Образец затрат (использование модели по запросу)	телеметрия api-request	питает FinOps, не карту доступа
Finding (антиуклонение)	пробелы в телеметрии / запрещённые инструменты	сессия, переставшая эмитить, оставаясь активной, помечается

Коннектор read-first и с минимумом данных: он записывает отношение (какая сессия обратилась к какому ресурсу, чтение или запись), никогда не полезную нагрузку. Сырой ввод инструмента или shell-команда — которые могут нести секрет или PII — сводятся к маскированной ссылке на ресурс прежде, чем когда-либо станут наблюдением. Эта установка — по умолчанию; удержание любого содержимого — явное согласие в рамках конкретной категории.

Как работает обвязка

Есть две половины, и они встречаются на loopback-сокете на хосте, где работает Claude Code.

1. Движок раскрывает приёмник OTLP как core ingest. Кооперативный коннектор запускает приёмник OTLP (gRPC и HTTP) для собственного вывода OpenTelemetry Claude Code плюс эндпоинт для его хуков инструментов. Он привязывается к loopback по умолчанию — кооперативный приём неаутентифицирован, поэтому он не должен быть доступен вне хоста. Держите его на loopback; внехостовой резервный механизм — это коллектор ядра, а не публичный порт OTLP.
2. Вы направляете экспортёр OTLP Claude Code на этот приёмник и объявляете источник, чтобы движок знал, что нужно запустить его для вашего тенанта.

  Claude Code (agent host)                 Olivares AI engine
  ┌──────────────────────────┐             ┌─────────────────────────────┐
  │ OTLP exporter            │── loopback ─▶│ cooperative OTLP receiver   │
  │ (OTEL_* env on the CLI)  │   (4317/4318)│ → normalize → access edges  │
  │ MCP servers (R/RW hints) │             │ → module III (R/RW map)     │
  └──────────────────────────┘             └─────────────────────────────┘

Приёмник неаутентифицирован и только на loopback по умолчанию

Поскольку кооперативный приём принимает телеметрию без аутентификации отправителя, любой, кто может достучаться до сокета, может подделать рёбра. Приёмник по умолчанию привязывается к loopback именно по этой причине. Привязка его к не-loopback адресу — это опасное, явное согласие; не выставляйте его в общей сети. Внехостовые агенты должны наблюдаться вместо этого через некооперативный резервный механизм.

Шаг 1 — направьте Claude Code на приёмник

Claude Code конфигурируется через собственные переменные окружения OpenTelemetry. На хосте агента включите его экспорт OTLP и направьте его на loopback-приёмник движка. Приёмник движка следует стандартным портам OpenTelemetry (gRPC и HTTP); задайте эндпоинт экспортёра Claude Code на соответствующий loopback-адрес и протокол.

Точные имена переменных OTEL принадлежат Claude Code, не этому продукту

Экспортёр конфигурируется собственными настройками Claude Code / OpenTelemetry (включить телеметрию, выбрать протокол OTLP, задать эндпоинт). Эти имена определены Claude Code и OTel SDK — обращайтесь к документации Claude Code по телеметрии за актуальными именами переменных, а не копируйте список сюда. Этому продукту принадлежит приёмник, на который они указывают, и объявление источника ниже.

По умолчанию коннектор удерживает только структурную телеметрию — атрибуты сессии и идентичности, имена инструментов, режим R/RW, тайминг — и никогда не текст промпта, тела инструментов или сырые тела API, даже если Claude Code сконфигурирован их эмитить. Оставьте это так, если у вас нет конкретной, проаудированной причины удерживать категорию содержимого.

Шаг 2 — объявите источник

Реальные (не демонстрационные) источники подключаются из единого операторского конфигурационного файла, заданного переменной окружения OLIVARES_SOURCES_CONFIG, который движок читает до своего старта. Секреты живут по значению в этом операторском файле, никогда в хранилище. Каждая запись называет источник, его kind, тенанта, которому он принадлежит, и блок config для конкретного источника:

{
  "sources": [
    {
      "name": "claude",
      "kind": "claude",
      "tenant": "<tenant-ref>",
      "config": {
        "grpc_addr": "127.0.0.1:4317"
      }
    }
  ]
}

• name — ваша метка для этого экземпляра источника.
• kind выбирает кооперативный коннектор Claude Code.
• tenant ограничивает каждое произведённое им ребро одним тенантом (чтения модуля III ограничены тенантом и привилегированы).
• config содержит собственные настройки коннектора — например, loopback- адрес, к которому привязывается приёмник OTLP. Коннектор привязывает свой приёмник сам, а не заимствует его у агента, так что отключение переменной OTEL Claude Code не может молча выключить коллектор.

Подтвердите ключи config коннектора по поставляемому дескриптору

Коннектор публикует собственную схему конфигурации (его дескриптор перечисляет каждый ключ, тип, значение по умолчанию и описание). Блок config выше показывает репрезентативный ключ адреса приёмника; не выдумывайте дополнительные ключи с этой страницы. Читайте дескриптор, который сообщает коннектор — или справочник по конфигурации — за авторитетным, версионированным списком (адреса приёмников, путь хуков, окна корреляции/тишины, allowlist захвата содержимого и опциональные поля управления). По одному значению за раз, проверенному по тому, что действительно поставляет ваша сборка.

Ненастроенный или пустой источник честно предупреждает, а не отказывает: kind, который неизвестен, не встроен или не загружается, сообщается при старте, никогда не сбрасывается молча в no-op. После редактирования файла перезапустите движок, чтобы корень композиции перечитал его.

Шаг 3 — проверьте, что рёбра приходят

С экспортирующим Claude Code и объявленным источником запустите сессию Claude Code, которая обращается к ресурсу (читает файл, выполняет команду, вызывает MCP-инструмент), затем посмотрите на карту доступа. Просмотр графа доступа — это привилегированное, ограниченное тенантом, проаудированное действие (роль editor и выше — никогда не самый низкий viewer), поэтому используйте токен с правильной ролью:

• Граф доступа обслуживается по маршруту модуля /v1/m/accessmap/graph.
• Результат permitted-vs-observed — дрейф наименьших привилегий — находится по /v1/m/accessmap/drift.

Эти маршруты модуля достижимы, но намеренно не включены в обслуживаемый документ OpenAPI; их контракты живут в типизированных интерфейсах Go/TS продукта. О сквозном прохождении от свежего движка до заполненного графа следуйте туториалу «От нуля до графа».

Вы должны увидеть рёбра, чей сигнальный источник — otel, атрибутированные сессии Claude Code. Если интроспекция MCP внесла подсказку R/RW, она приходит как отдельный сигнал mcp_annotation, который подтверждает — но сам по себе не устанавливает — режим ребра.

Честные ограничения этого пути

• Аннотации MCP недоверены. readOnlyHint / destructiveHint — это рекомендательные подсказки, которые сервер заявляет о себе; спецификация MCP гласит, что клиенты должны считать их недоверенными. Продукт раскрывает их как подтверждающий сигнал и честно показывает достоверность — он никогда не повышает ребро до «только чтение» по одной лишь подсказке.
• Атрибуция зависит от идентичности отдельного агента. Рёбра атрибутируются идентичности сессии. Пул агентов, разделяющих одну сервисную учётную запись, сворачивает атрибуцию; разрешение этого — забота управления (выдача и обеспечение идентичности отдельного агента), а не то, что этот коннектор может изготовить.
• Он кооперативный. Он видит то, о чём сообщает агент. Агент, который никогда не эмитит, или активность, происходящая вне пути агента, невидимы для этого источника по построению — именно поэтому некооперативный резервный механизм ядра и нативный аудит хранилища существуют рядом с ним.
• Глубина на стадии проектирования. Большая часть платформы — pre-1.0. Относитесь к возможностям здесь как к проверенному кооперативному пути приёма; там, где нижележащий модуль или поле ещё не построены, продукт так и говорит, а не подразумевает покрытие.

Дальнейшие шаги

• Подключение источника — общая модель подключения источников (кооперативная и некооперативная).
• Управление и согласование — превратите наблюдённый дрейф в решение о наименьших привилегиях.
• Справочник событий — нормализованные наблюдения, которые эмитит этот источник.
• Обзор архитектуры — где кооперативный путь находится в платформе.