Перейти к содержимому

Машинный перевод. Авторитетным источником является английская версия; проверка носителем языка ещё не выполнена.

Руководства

Подключение Claude Code

Приём сессий Claude Code из телеметрии OpenTelemetry gen_ai и управление вызовами инструментов в точке применения с запретом по умолчанию.

Обновлено:

Claude Code — каноничный кооперативный источник для Olivares AI. Платформа делает две различные вещи с ним, на двух поверхностях с противоположными позициями: различайте их, потому что одна работает с приоритетом чтения, а другая намеренно находится на пути.

Для общей модели источников см. Подключение источника; для рабочего процесса применения см. Управление и согласование.

Что наблюдается vs. что применяется

  • Наблюдение (приоритет чтения). Claude Code экспортирует OpenTelemetry; коннектор запускает OTLP-приёмник, который преобразует телеметрию в рёбра карты доступа, примеры затрат и идентичность. Этот путь никогда не находится на пути запросов агента — он принимает данные вне основного канала. См. карта доступа.
  • Применение (запрет по умолчанию). Нативные хуки Claude Code PreToolUse / PostToolUse могут вызывать точку применения политики (PEP), которая возвращает allow / deny / ask до запуска инструмента. Это намеренно встроенный путь, который вы включаете, когда плоскость управления должна управлять агентом, а не просто наблюдать.

Вы можете запустить только наблюдение. Применение опционально и аддитивно.

Наблюдение: приём телеметрии OTel

Коннектор предоставляет стандартный OTLP-приёмник (gRPC и HTTP, на обычных портах OpenTelemetry). Он маппирует два словаря в один конвейер:

  • Собственная телеметрия Claude Code claude_code.* — вызовы инструментов, сессии, использование модели по запросу и (в бета-версии трассировки) иерархия субагентов.
  • Вендор-нейтральные семантические соглашения OpenTelemetry GenAI (gen_ai.*), поэтому любой OTel-инструментированный агент питает ту же карту доступа и FinOps, не только Claude Code.

Из этой телеметрии коннектор создаёт рёбра доступа, атрибутированные сессиям (какая сессия обратилась к какому ресурсу, чтение или запись), ребро топологии для каждого MCP-сервера, к которому подключается сессия, и пример затрат по запросу. MCP-серверы предоставляют интроспекцию readOnlyHint / destructiveHint; это сигнал R/RW, который спецификация MCP помечает как ненадёжный, поэтому коннектор рассматривает их как подтверждающее свидетельство и никогда не повышает ребро только на основе подсказки.

OLIVARES_SOURCES_CONFIG — JSON-документ (читается перед запуском движка); kind: "claude" выбирает этот коннектор. http_addr привязан к loopback по умолчанию — см. предупреждение ниже.

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

Профиль GenAI опционален

Семантические соглашения gen_ai.* всё ещё имеют статус Development, поэтому маппирование их на затраты и рёбра — явный opt-in. Установите semconv_opt_in коннектора на собственный токен спецификации (зеркалируя OTEL_SEMCONV_STABILITY_OPT_IN); без него запись gen_ai.* всё ещё питает сторожевой таймер активности, но не учитывается в затратах. Профиль читает и текущие, и устаревшие имена атрибутов, которые реальные фреймворки всё ещё генерируют, принимает данные на трассировках или логах и дедуплицирует операцию, которая приходит по обоим каналам, чтобы FinOps не считал дважды. Контент сообщений никогда не читается — ключи контента используются только для определения, на каком диалекте говорит эмиттер.

Минимальные данные по умолчанию

Коннектор сохраняет только структурную телеметрию — сессии, идентичности, имена инструментов, режим R/RW, тайминги — даже если клиент настроен генерировать текст промптов или тела инструментов. Сырой ввод инструмента сводится к отредактированной ссылке на ресурс перед тем, как стать наблюдением. Сохранение любой категории контента — это отдельный, аудируемый opt-in. См. разрешённый и наблюдаемый и точность для того, как уровни покрытия и атрибуции определяются.

:::caution Кооперативный приёмник неаутентифицирован и привязан к loopback по умолчанию. Любой, кто может достичь сокета, может подделать телеметрию, поэтому не открывайте его в общей сети. Внехостовые агенты принадлежат некооперативному ядерному бэкстопу, а не публичному 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, перенаправить fetch). Приоритет: deny над ask над allow.
  • PostToolUse — Claude Code не имеет поля перезаписи вывода, поэтому хук PostToolUse может только заблокировать дальнейшую обработку по результату, помеченному политикой. Коннектор не претендует на перезапись результата, который модель уже видела; то, что он редактирует — это то, что он сохраняет и аудирует.

Запрет по умолчанию тотален

Встраивание в путь данных — асимметричный риск, поэтому каждый режим отказа завершается отказом, никогда открытым: отсутствующий решатель, ошибка решения (PDP недоступен, идентичность не разрешена, согласование не удалось открыть) или некорректная полезная нагрузка хука — всё возвращает чистый отказ. Нулевое значение вердикта само по себе является отказом. ask маршрутизирует к управляемому согласованию; согласование привязано к хешу плана точного вызова инструмента, поэтому не может быть использовано повторно для авторизации другого вызова (анти-TOCTOU).

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

Облегчённый, локальный режим

Коннектор также поддерживает локальную, внутрипроцессную политику применения, вычисляемую на горячем пути хука без обращения к движку — так что медленная или недоступная плоскость управления никогда не блокирует вызов инструмента разработчика. Это opt-in: без настроенных правил хуки наблюдаются и никогда не ограничиваются. Это кооперативная по умолчанию позиция; управляемый PEP выше — противоположная позиция, на которую вы переключаетесь, когда плоскость управления должна быть принимающим решения.

Защита от обхода

Поскольку путь наблюдения кооперативен, коннектор отслеживает сессию, которая перестаёт генерировать OTel пока её хуки продолжают срабатывать — сигнатура агента, который отключил свой экспортёр в середине сессии, продолжая действовать. Обратите внимание, что он не делает: завершённый агент замолкает, и тишина сама по себе никогда не помечается. Наземная истина для действительно некооперативной активности — это ядерный/eBPF бэкстоп, а не эта эвристика.

Изолированная сеть: что остаётся дома, а что нет

Плоскость управления работает внутри вашей собственной инфраструктуры и может работать в изолированной сети — данные управления и наблюдения (рёбра доступа, решения, аудит, примеры затрат) никогда не покидают ваш периметр. OTLP-приёмник и хук PEP — локальные сокеты; движок не отправляет данные домой.

Одна честная оговорка: инференс Claude никогда не изолирован от сети. Claude Code по-прежнему отправляет промпты в API Anthropic (напрямую или через Bedrock, Vertex или Foundry) для получения ответа. Изоляция плоскости управления от сети сохраняет данные управления вашим окружением дома; это не перемещает модель on-prem. Только действительно самостоятельно размещаемые модели (например через vLLM/Ollama) работают полностью офлайн. См. что такое Olivares AI и честность и ограничения.

Следующие шаги

Поиск в документации