Claude Code 2.1.238: динамическая авторизация proxy и graceful shutdown для self-hosted runner

В Claude Code 2.1.238 три изменения напрямую касаются развёртывания self-hosted runner в корпоративной среде: динамическая авторизация proxy на каждое соединение, корректное завершение работы по SIGTERM и расширение модели доверия headersHelper на запросы к каталогу plugin marketplace.

Каждое из них — одна строка в changelog, но последствия для production-операций заслуживают отдельного разбора.

Проблема аутентификации корпоративного proxy

В корпоративных сетях исходящий HTTP-трафик Claude Code нередко проходит через аутентифицированный egress proxy. До 2.1.238 передать заголовок Proxy-Authorization этому proxy можно было только одним способом: записать значение в переменную окружения перед запуском runner.

Это работало, пока proxy раздавал статические учётные данные. Но если proxy использует краткосрочные токены — OAuth 2.0 bearer token из PAM-системы, ротируемые секреты из Vault или AWS Secrets Manager, Kerberos service ticket через SPNEGO — статическая env-переменная устаревает через несколько минут после запуска процесса. Runner продолжает работать, но каждый исходящий запрос получает отказ авторизации от proxy, при этом в логах — только сетевая ошибка без явного указания на истёкший токен.

2.1.238 добавляет два новых флага для claude self-hosted-runner:

--proxy-authorization-command "<shell-команда>"
--proxy-authorization-file "<путь к файлу>"

--proxy-authorization-command выполняет указанную команду при каждом новом исходящем соединении и использует её stdout как значение заголовка Proxy-Authorization. Команда может быть любой: вызов Vault, AWS STS, скрипт обращения к внутреннему token endpoint. Runner выполняет её на каждое соединение, поэтому TTL токена в 5 минут на стороне proxy больше не требует перезапуска runner.

--proxy-authorization-file читает значение из файла. Это удобно, когда внешний агент — sidecar или скрипт ротации учётных данных — периодически записывает свежие данные в фиксированный путь: runner при каждом соединении перечитывает файл, не зная ничего о том, как именно обновляются данные.

До 2.1.238 типичный обходной путь — wrapper-скрипт, который перезапускает runner по расписанию ротации учётных данных. Перезапуск обрывал все активные сессии, не дошедшие до точки естественной паузы. В Claude Code сессии не всегда корректно checkpoint-уются при внезапном завершении процесса, поэтому такой подход создавал устойчивую потерю контекста у разработчиков.

Graceful shutdown по SIGTERM

--defer-shutdown-max-min <минуты> меняет поведение runner при получении SIGTERM. Раньше сигнал завершения от контейнерного оркестратора (Kubernetes drain, ECS task drain, systemd stop) вызывал немедленный выход — все подключённые сессии обрывались.

С флагом --defer-shutdown-max-min 5 runner:

1. Перестаёт принимать новые сессии с сервера.
2. Продолжает обслуживать уже подключённые сессии.
3. После истечения заданного времени паркует оставшиеся сессии.
4. Завершает работу корректно.

Теперь terminationGracePeriodSeconds в Kubernetes, drain-хуки ECS и таймаут systemd stop реально работают с Claude Code runner. Раньше runner завершался до их истечения. Достаточно выставить эти параметры равными значению --defer-shutdown-max-min, и активные сессии успевают завершить текущий цикл работы.

Больше всего это ощущается в autoscaled-кластерах с плановой ротацией узлов. Узел, который раньше терял все сессии при деинициализации, теперь может корректно завершить текущий цикл работы перед тем, как отдать ресурсы. Стоит учитывать: если активная сессия не завершается сама в течение заданного времени, runner всё равно завершает работу принудительно по истечении --defer-shutdown-max-min. Это нижняя граница, а не гарантия завершения конкретной задачи.

headersHelper распространился на запросы к каталогу marketplace

headersHelper присутствовал в Claude Code несколько месяцев как механизм передачи динамически генерируемых HTTP-заголовков при подключении MCP server. В 2.1.238 он охватывает два новых сценария.

Запросы к каталогу plugin marketplace: если url-тип marketplace или отдельный catalog-entry определяет headersHelper, runner выполняет его для запросов листинга каталога и скачивания архивов плагинов. Раньше headersHelper срабатывал только при установке и обновлении — просмотр каталога был неаутентифицированным.

Ужесточение доверия для project-уровневых helper: headersHelper в project .mcp.json, inline MCP server в project или --add-dir agent файлах теперь требует, чтобы диалог доверия к директории был подтверждён. Это предотвращает выполнение скрипта сбора учётных данных из вредоносного репозитория без ведома пользователя. В режиме claude -p (неинтерактивный) скрипт headersHelper запускается из директории конфигурации Claude без наследования credential env vars из запускающей оболочки.

Первое изменение важно для команд, которые поддерживают приватный plugin marketplace. До 2.1.238 claude plugin list обращался к endpoint каталога без аутентификации — установка и обновление плагинов проходили через headersHelper, а просмотр каталога нет. Это означало, что внутренний marketplace либо должен был быть публично доступным для операций листинга, либо команда сталкивалась с ошибками при просмотре каталога. Теперь headersHelper из определения marketplace покрывает и этот запрос.

На что обратить внимание после обновления

Если runner работает за корпоративным proxy с краткосрочными токенами, после обновления до 2.1.238 стоит перейти на --proxy-authorization-command и убрать wrapper-скрипты с перезапуском по расписанию. Скрипт, передаваемый в --proxy-authorization-command, должен вывести в stdout полное значение заголовка Proxy-Authorization, включая схему — например Bearer <token> или Basic <base64>. Пустой stdout или ненулевой код возврата воспринимается как ошибка получения токена.

Для развёртываний в Kubernetes или ECS рекомендуется выставить --defer-shutdown-max-min равным terminationGracePeriodSeconds или аналогичному параметру оркестратора. При несовпадении значений в меньшую сторону сессии по-прежнему будут обрываться, при несовпадении в большую — оркестратор убьёт процесс до истечения grace period runner.

Командам с приватным plugin marketplace стоит проверить, распространяется ли headersHelper в определении marketplace на запросы claude plugin list после обновления. Для этого достаточно запустить claude plugin list под учётными данными, которые ранее были доступны только на шаге установки.

Если в automation-пайплайнах с claude -p использовался project-уровневый headersHelper, нужно убедиться, что скрипты не зависят от credential переменных из окружения запускающей оболочки. В 2.1.238 это наследование заблокировано: headersHelper из project .mcp.json теперь запускается из директории конфигурации Claude с очищенным окружением.

Документация Claude Code →