Настройка сессий в самостоятельно размещаемых окружениях

​

Скрипты-обёртки

claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret --exec-path /etc/claude/session-wrapper.sh

​

Задавайте значение по умолчанию для переменных, которые могут быть не установлены

​

Заключайте в кавычки аргументы и переменные, которые раскрывает ваш скрипт

• Аргументы: передавайте их дальше как "$@"
• Переменные: заключайте каждую в кавычки, как в "${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}". Ссылка на ветку Slack, например, может содержать ? и &.
• Строки eval и sh -c: не подставляйте значение в строку, которую выполняет eval или sh -c, даже внутри кавычек. Вместо этого пусть такая строка ссылается на саму переменную.

​

Сохраняйте stdin и дескриптор файла 3 подключёнными

exec 9<&0   # the runner uses 3, and from v2.1.309 reserves 4 and 5
"$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&9 9<&- &
CHILD=$!
trap 'teardown' EXIT
wait "$CHILD"

• Дескриптор файла 3: передаёт сигналы активности дочернего процесса средству выполнения. Не закрывайте и не переиспользуйте его в обёртке.
• Дескрипторы файлов 4 и 5: средства выполнения на Claude Code v2.1.309 или новее резервируют их для дочернего процесса. Не закрывайте и не переиспользуйте их в обёртке. Если ваша обёртка использует какой-либо из них, например для сохранения stdin, перенесите это использование на дескриптор с 6 по 9 — более ранние версии также оставляют их свободными.
• stderr: когда обёртка или дочерний процесс завершается с ненулевым кодом выхода, средство выполнения публикует последние строки stderr в сессию и выводит их в свой собственный лог. Пользователь сессии видит эти строки, поэтому не выводите секреты в stderr и удалите set -x перед развёртыванием обёртки. Если вы перенаправите stderr, сессии по-прежнему будут работать, но средство выполнения будет сообщать о сбое только с кодом выхода.

​

Передавайте флаги системного промпта дальше

• Передавайте их дальше: завершайте обёртку командой exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@", которая передаёт файловые флаги вместе со всеми остальными аргументами. Не удаляйте и не переписывайте их. Если сессия теряет файловый флаг промпта, она работает без инструкций, которые для неё отправила плоскость управления.
• На средстве выполнения версии v2.1.281 или новее добавленный вами файловый флаг заменяет серверный, а не дополняет его: каждый файловый флаг промпта принимает одно значение, и Claude Code использует последнее вхождение, поэтому если вы добавите --append-system-prompt-file <path> после "$@", содержимое вашего файла заменит дополнительные инструкции сервера. Чтобы добавить инструкции поверх серверных, поместите их в CLAUDE.md образа средства выполнения, который средство выполнения добавляет в пользовательскую конфигурацию каждой сессии.

​

Исправление Argument list too long при запуске сессии

Session <id> finished: failed — reason: child exited 126: /opt/wrapper.sh: line 9: /usr/local/bin/claude: Argument list too long

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --append-system-prompt "$(cat /opt/team-instructions.md)"

​

Подготовка учётных данных, ограниченных создателем сессии

#!/bin/bash
# Key on the stable Anthropic user ID and require a human creator.
CREATOR_SUB=$("$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token \
  | jq -re '.act.sub // "" | select(startswith("user:"))') \
  || { echo "decode-token: verification failed or no human creator" >&2; exit 1; }

creds=$(your-sts-helper assume-role --subject "$CREATOR_SUB") \
  || { echo "credential exchange failed" >&2; exit 1; }
eval "$creds"

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"

​

Lifecycle hooks

​

checkout

​

Получение учётных данных git в хуке

• Учётные данные клонирования для каждой сессии: проверьте CLAUDE_CODE_SESSION_ACCESS_TOKEN с помощью стандартной библиотеки JWT по эндпоинту JWKS под CLAUDE_RUNNER_API_BASE_URL, как описано в разделе Verify the token from your service. Затем попросите вашу службу учётных данных выдать краткосрочные учётные данные клонирования для идентичности из утверждения act токена. Привязывайте эти учётные данные к act.sub и не требуйте act.email.
• Аутентификация git хоста: используйте любую аутентификацию git, которая уже есть на хосте, например SSH-агент, помощник учётных данных или .netrc.

​

Когда хук завершается ошибкой

• Репозиторий, в который сессия отправляет результаты: runner отмечает сессию как неудачную, и при ненулевом выходе выводит пользователю конец stderr скрипта. Запишите причину в stderr одной короткой строкой, сделайте это последним действием, а затем завершите работу с ненулевым кодом. Не выводите секреты в stderr и удалите set -x перед развёртыванием хука. Если сообщение git couldn't find remote ref встречается примерно в последних 4 КБ stderr хука, runner вместо этого сообщает об удалении ветки. Тогда в сообщении об ошибке сессии говорится, что ветка больше не существует в удалённом репозитории, и пользователю предлагается восстановить её. Если эта ветка существует, см. Сессия завершается ошибкой no longer exists on the remote или couldn't find remote ref.
• Репозиторий, из которого сессия только читает, например репозиторий, добавленный к запущенной сессии: runner пропускает его и продолжает работу с оставшимися репозиториями. Runner отправляет в сессию шаг Skipped и удаляет всё, что хук оставил по пути checkout. Если шаг Skipped упоминает хук checkout, подробности ошибки ищите в строке [runner:warn] checkout hook failed в логе runner’а. Если в шаге сказано, что исходная ссылка no longer exists on remote, см. Сессия завершается ошибкой no longer exists on the remote или couldn't find remote ref. Если после пропуска у сессии не остаётся ни одного репозитория, runner всё равно отмечает сессию как неудачную.

​

post-session

• completed: сессия завершилась чисто. Процесс Claude Code завершился нормально или завершился сам после того, как сессия была архивирована или удалена.
• failed: процесс Claude Code упал, или настройка не удалась после его запуска.
• interrupted: runner остановил сессию в одном из следующих случаев:
  • Runner освободил сессию, чтобы освободить слот.
  • Истекло время ожидания сессии при запуске.
  • Сервер переместил сессию с этого runner’а.
  • Опрос runner’а обнаружил архивирование или удаление до завершения процесса.
  • Runner был в режиме дренирования.
  • Сессия превысила свой лимит --kill-session-after-min.
• abandoned: зарезервировано для сессии, которую заявил другой runner. Hook в настоящее время не срабатывает в этом случае.

#!/usr/bin/env bash
set -u
export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}
IFS=':'
# -c overrides beat repo-local settings, blocking session-written fsmonitor,
# hook-path, and gpg-program config from executing code with the hook's
# privileges. -c commit.gpgsign=false also leaves these rescue commits
# unsigned under --configure-git.
# Repo-local credential.helper and pushurl still apply, and on a runner
# before v2.1.280 so does core.sshCommand; see the note below the script
# before you give this push a credential.
g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \
        -c commit.gpgsign=false "$@"; }
for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do
  cd "$ws" 2>/dev/null || continue
  [ -z "$(g status --porcelain 2>/dev/null)" ] && continue
  g add -A
  g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue
  g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true
done

​

Hook timing when the runner releases a session

• Неактивна после хода или истекла при запуске: runner останавливает дочерний процесс и запускает этот hook до завершения. Только после этого он освобождает сессию. Сообщение пользователя, отправленное во время выполнения hook’а, не может возобновить сессию на другом runner’е до завершения hook’а.
• Ожидание ответа пользователя на подсказку, такую как подсказка разрешения: runner сначала освобождает сессию, затем запускает этот hook. Сообщение пользователя, отправленное во время выполнения hook’а, может возобновить сессию на другом runner’е до завершения hook’а.

​

Git configuration inside lifecycle hooks

• Хуки git: если вы не укажете значение, core.hooksPath равен /dev/null, поэтому git пропускает хуки в .git/hooks репозитория и любую директорию хуков, указанную в ~/.gitconfig. Чтобы указать своё значение, экспортируйте core.hooksPath как пару GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n в окружении runner’а. Runner также читает core.hooksPath из системной конфигурации git и использует его, только если пользователь runner’а не может записывать в этот файл, в указанную в нём директорию или в файлы хуков в ней. Когда runner игнорирует значение, строка [runner:warn] при запуске называет это значение и причину.
• Монитор файловой системы: core.fsmonitor пуст, поэтому git в вашем хуке не запускает программу-монитор, указанную в файле конфигурации.
• Удалённые протоколы: GIT_ALLOW_PROTOCOL равна https:http:ssh. Clone, fetch или push с локальным путём, URL file:// или URL git:// завершается ошибкой fatal: transport 'file' not allowed или fatal: transport 'git' not allowed.
• Команда SSH и запрос учётных данных: git в вашем хуке игнорирует core.sshCommand и core.askPass из файлов конфигурации. Чтобы использовать собственную команду SSH, установите GIT_SSH_COMMAND в окружении runner’а. Чтобы использовать программу запроса учётных данных, установите там GIT_ASKPASS. Сессии наследуют окружение runner’а, поэтому обе переменные также попадают в собственный git сессии. Не помещайте учётные данные ни в одну из них.
• Программы gpg: gpg.program, gpg.openpgp.program, gpg.x509.program и gpg.ssh.program — это пути, которые устанавливает runner, а не значения из файла конфигурации.
• Подпись коммитов: с --configure-git коммиты, которые вы делаете из хука, подписываются от имени сессии. Без этого флага commit.gpgsign и tag.gpgsign равны false.

• Пары конфигурации: пара GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n, которую вы экспортируете в окружении runner’а, заменяет значение runner’а для того же ключа. Нумеруйте свои пары с 0 и установите GIT_CONFIG_COUNT равной их количеству. Если последняя пара, заявленная этим количеством, отсутствует, runner игнорирует все ваши пары и при запуске записывает в лог строку [runner:warn].
• Переменные окружения git: runner оставляет GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND и GIT_ASKPASS такими, какими вы их установили в его окружении.
• Опции git -c: опция git -c внутри хука переопределяет пару GIT_CONFIG_KEY_n — как runner’а, так и вашу. Она не изменяет GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND или GIT_ASKPASS, которые git читает раньше любой конфигурации.

​

command

​

Средства выполнения по требованию

claude self-hosted-runner orchestrator \
  --environment-secret-file /etc/claude/environment-secret \
  --hooks-dir /etc/claude/hooks

​

Хук spawn-runner

• Запустите его с нарядом на работу: укажите --environment-secret-file на файл, содержащий JWT наряда на работу, или установите SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET на значение JWT.
• Скопируйте JWT перед выходом хука: оркестратор удаляет файл наряда на работу после выхода хука, поэтому скопируйте JWT в рабочую нагрузку, которую вы отправляете, такую как Kubernetes Secret на порожденном Job, вместо передачи пути файла.
• Используйте --capacity 1 на порожденных средствах выполнения: наряд на работу, привязанный к сеансу, регистрирует ровно одно средство выполнения, привязанное к этому сеансу, поэтому более высокая емкость добавляет слоты, которые никогда не получают работу, и средство выполнения логирует предупреждение при запуске.
• Нарядные работы предварительного прогрева регистрируют без привязки: резервное средство выполнения не привязано к сеансу и заявляет поставленную в очередь работу, как средство выполнения фиксированного флота.

1. Будьте идемпотентны по CLAUDE_RUNNER_ORDER_ID. Повторная доставка одного и того же запроса должна порождать не более одного средства выполнения. Выведите детерминированное имя ресурса из ID заказа и позвольте вашей платформе отклонить дубликат. Не используйте вместо этого CLAUDE_RUNNER_SESSION_ID в качестве ключа. Каждый повторный запрос для сессии несёт тот же ID сессии с новым ID заказа. Рабочая нагрузка, названная или дедуплицированная по ID сессии, не создаётся снова, пока существует первая.
2. Не повторяйте рабочую нагрузку. Один ID заказа означает не более одной созданной рабочей нагрузки. Если средство выполнения никогда не регистрируется, Anthropic повторно запрашивает с новым ID заказа после --expected-spawn-seconds.
3. Соблюдайте контракт кода выхода. Завершайтесь со статусом, соответствующим результату:
   • Выход 0: отправлено.
   • Выход 1 или хук всё ещё выполняется по истечении --hook-timeout: сбой, допускающий повторную попытку. Сессия выжидает и предлагается снова. После 10 неудачных запросов подряд она блокируется так же, как после выхода 2 или выше.
   • Выход 2 или выше: сбой, не допускающий повторной попытки. Сессия блокируется от повторного порождения до тех пор, пока пользователь не отправит ей новое сообщение или Owner не выберет для неё Retry на вкладке Activity окружения.
   Пока сессия выжидает, она отображается на вкладке Activity как Queued без ошибки порождения, поэтому читайте вывод хука в логе оркестратора. После блокировки сессия отображается как Failed. Разверните её, чтобы прочитать ошибку порождения, взятую из последних 512 символов stderr хука. Пишите в stderr понятную ошибку, указывающую, что делать, и никаких секретов. В shell-хуке сохраняйте временные сбои повторяемыми. У запроса предварительного прогрева нет сессии, которая могла бы завершиться сбоем: оркестратор записывает ненулевой выход только в локальный лог, а сервер повторно запрашивает порождение после истечения аренды --expected-spawn-seconds.
4. Установите --expected-spawn-seconds не меньше вашего времени p99 от запроса на порождение до регистрации средства выполнения. Отсчитывайте от момента, когда оркестратор получает запрос на порождение, и учитывайте как ожидание ресурсов на вашей платформе, так и время загрузки. Это значение является арендой на стороне сервера, и наряд на работу истекает вместе с ней, поэтому средство выполнения, рабочая нагрузка которого запускается дольше, не сможет зарегистрироваться. Все реплики оркестратора должны использовать одно и то же значение.

​

Исправьте повторно открытые сессии, которые остаются в статусе Queued или отображаются как Failed

name="runner-${CLAUDE_RUNNER_SESSION_ID}"

1. При первом запросе на порождение для сессии хук создаёт рабочую нагрузку с этим именем, и средство выполнения запускается
2. Средство выполнения завершается, например после --release-idle-session-min, а позже пользователь повторно открывает сессию
3. Следующий запрос на порождение для сессии содержит тот же ID сессии и новый ID заказа, поэтому хук формирует то же имя
4. Если на вашей платформе всё ещё есть рабочая нагрузка от первого запроса, потому что ничто её не удалило при завершении её средства выполнения, хук не создаёт новую рабочую нагрузку, и средство выполнения не запускается
5. Каждый последующий запрос на порождение для сессии заканчивается так же

name="runner-${CLAUDE_RUNNER_ORDER_ID}"

• Queued: сессия получит следующий запрос на порождение самостоятельно
• Failed: выберите для неё Retry как Owner или попросите её пользователя отправить ей новое сообщение

​

Настройте завершение средств выполнения по требованию при простое

​

Направляйте вывод фонового процесса в файл

your-background-command >> "$HOME/claude-runner.log" 2>&1 &

• Примерно через секунду после выхода хука оркестратор записывает в лог exited, but a process it started still has the hook's stdout or stderr open. Начиная с этой строки, он записывает в лог до 64 КБ последующего вывода под [runner:hook:spawn-runner:after-exit jti=<order id>], а остальное отбрасывает.
• После завершения оркестратора запись процесса туда завершается сбоем.

• Вкладка Activity, в ошибке порождения неудачной сессии: spawn-runner hook timed out after 60000ms или последние строки stderr хука.
• Лог оркестратора: timed out after 60000ms, sending SIGTERM to process tree.

​

Завершайте хук, не дожидаясь средства выполнения

• Чтобы убедиться, что ваши средства выполнения останавливает именно таймаут: найдите в логе оркестратора timed out after 60000ms, sending SIGTERM to process tree для каждого запроса на порождение. 60000 — это ваш --hook-timeout в миллисекундах.
• Чтобы исправить это: пусть хук отправляет средство выполнения на вашу платформу и завершается с кодом 0. Если вместо этого увеличить --hook-timeout, средство выполнения просто остановится позже.

​

Сохраняйте временные сбои повторяемыми в shell-хуке

set -e
PERMANENT=; permanent() { printf '%s\n' "$*" >&2; PERMANENT=1; exit 2; }
trap 'rc=$?; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT

• Просто exit 2 или выше: при установленной ловушке он превращается в выход 1. Для ошибки, которую не исправит никакая повторная попытка, вместо этого вызовите permanent с указанием причины, например permanent "namespace claude-runners does not exist". Вызывайте её в основной оболочке, а не внутри $( ), ( ) или конвейера.
• exec: не начинайте последнюю команду хука с exec, потому что exec заменяет оболочку, и ловушка не выполняется.
• Вторая ловушка EXIT: второй trap ... EXIT заменяет первый, поэтому объедините их в одну ловушку. Поместите команды очистки сразу после rc=$?; и завершите каждую || true;. Тогда очистка выполняется как при сбое, так и при успехе, а сбойная команда очистки не влияет на статус выхода хука. Эта объединённая ловушка показывает структуру, где your-cleanup-command заменяет вашу собственную команду:
  trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
  
• Команды, которым разрешено завершаться сбоем: если хук раньше не использовал set -e, теперь он останавливается на первой команде, вернувшей ненулевой статус, например на поиске, который ничего не нашёл. Если хук использует результат, сделайте эту команду условием if. Если он игнорирует результат, добавьте после команды || true.
• Команда, которая отправляет рабочую нагрузку: не добавляйте после неё || true. С || true хук завершается с кодом 0, даже когда ваша платформа отклоняет отправку, например из-за превышения квоты, и сессия ждёт средство выполнения, которое так и не было запущено. Называйте рабочую нагрузку по CLAUDE_RUNNER_ORDER_ID, как требует первое правило хука. Тогда ответ «уже существует» означает повторную доставку того же запроса, поэтому считайте успехом только этот ответ. Во всех остальных случаях выведите ответ в stderr и завершитесь с кодом 1 или вызовите permanent, если никакая повторная попытка не поможет. Этот пример делает это для kubectl create с файлом job.yaml, который содержит только рабочую нагрузку:
  if ! out=$(kubectl create -f job.yaml 2>&1); then
    case "$out" in
      *AlreadyExists*) ;;
      *) printf '%s\n' "${out:-kubectl create failed}" >&2; exit 1 ;;
    esac
  fi
  
  Тогда в логе оркестратора отображается это сообщение. Если хук создаёт другие объекты, называйте каждый по ID заказа, создавайте его отдельной командой и так же считайте успехом его ответ «уже существует». Для объекта, содержащего секрет, выводите фиксированное сообщение вместо вывода команды.

​

Отправка запросов к модели в Bedrock или Agent Platform

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

env | grep -E 'CLAUDE_CODE_USE_(BEDROCK|VERTEX)'

​

Чем отличаются сессии от сессий в Anthropic API

• Политики из claude.ai: настройки, управляемые сервером, не доходят до этих сессий. Не доходят и политики организации, которые Owner задаёт в настройках администратора Claude Code, поэтому Claude Code не применяет их внутри сессии. Поместите правила, на которые вы полагаетесь, в файл управляемых настроек образа runner.
• Скиллы аккаунта: эти сессии не загружают скиллы, включённые для аккаунта claude.ai пользователя. См. Как собирается конфигурация каждой сессии.
• Файлы: файлы, которые пользователи прикрепляют к сессии в claude.ai, мобильном или десктопном приложении, до неё не доходят, и Claude не может отправлять файлы обратно с помощью инструмента SendUserFile. Вместо этого размещайте входные файлы в репозитории или на runner.
• Выбор модели: управляющий уровень Anthropic передаёт модель для каждой сессии, а если сессия запускается без неё, Claude Code использует модель по умолчанию для провайдера. Вы не можете выбрать модель с помощью ANTHROPIC_MODEL или ANTHROPIC_DEFAULT_MODEL в окружении runner, но можете закрепить, во что разрешается псевдоним:
  • ANTHROPIC_MODEL и ANTHROPIC_DEFAULT_MODEL: runner удаляет их из окружения, которое он передаёт сессиям, хотя в примерах на страницах провайдеров задаётся ANTHROPIC_MODEL.
  • Переменные закрепления для отдельных семейств: переменные из раздела «Закрепление версий моделей» для Amazon Bedrock и Agent Platform до сессий доходят. Они определяют, во что разрешается псевдоним, например opus, но не полный идентификатор модели.
• Модели, которые ваш аккаунт не обслуживает: сессия может завершиться ошибкой на сообщении с указанием модели. Включите модели, которые могут выбирать ваши разработчики, фоновую модель, описанную в разделе «Закрепление версий моделей», и модель классификатора, которую использует авторежим. В Amazon Bedrock разрешите каждую из них в своей политике.
• Веб-поиск и быстрый режим: веб-поиск недоступен в Amazon Bedrock, а быстрый режим недоступен ни у одного из этих провайдеров. О других возможностях, различающихся в зависимости от провайдера, см. Возможности CLI, зависящие от провайдера.

​

MCP-серверы

RUN claude mcp add --scope user sidecar -- /usr/local/bin/mcp-sidecar
RUN claude mcp add --scope user --transport http internal http://mcp-gateway.svc.cluster.local:8080

• Управляемый файл MCP корпоративного уровня по стандартному системному пути: /etc/claude-code/managed-mcp.json на хостах раннеров под Linux, /Library/Application Support/ClaudeCode/managed-mcp.json на хостах под macOS. Используйте его для строго контролируемых парков машин, где могут загружаться только серверы из списка администратора. Правила приоритета описаны в разделе эксклюзивный контроль с помощью managed-mcp.json. Если этот файл находится на хосте раннера, Claude Code пропускает MCP-серверы, которые плоскость управления Anthropic передаёт в сессию, включая коннекторы claude.ai, и перечисляет их в предупреждении в stderr дочернего процесса сессии, которое раннер записывает в лог на уровне debug. До версии v2.1.229 такие сессии завершались при запуске с ошибкой You cannot dynamically configure MCP servers when an enterprise MCP config is present.
• Ключ managedMcpServers в управляемых настройках на хосте раннера: предоставляет серверы HTTP и SSE без эксклюзивного контроля, поэтому серверы из других источников по-прежнему загружаются. Требуется Claude Code v2.1.259 или новее.
• <repo>/.mcp.json: область действия проекта. Вне треда проекта сделайте коммит этого файла в репозиторий, и его серверы будут автоматически подтверждаться в облачных сессиях. В сессии с несколькими репозиториями загружается файл не более чем из одного репозитория.
• Файл --mcp-config из вашего скрипта-обёртки: добавьте флаг после "$@", например exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --mcp-config /etc/claude/mcp.json. Чтобы серверы из этого файла продолжали работать, когда переданные в сессию серверы обновляются посреди сессии, ваша обёртка должна передавать дочернему процессу полное окружение, как это делает exec. До версии v2.1.299 серверы stdio, HTTP и SSE из этого файла завершали работу при первом таком обновлении, в котором они не были указаны.

​

Ожидание MCP-серверов перед первым ходом

• Запуск сессии: до того как список инструментов будет получен в первый раз, сессия по умолчанию ждёт до 5 секунд сервер HTTP или SSE, в записи которого задано alwaysLoad: true, или все серверы, если в окружении раннера задано MCP_CONNECTION_NONBLOCKING=0. В остальных случаях серверы HTTP и SSE подключаются в фоновом режиме. Пока сессия ждёт на этом этапе, она инициализируется медленнее. MCP_CONNECT_TIMEOUT_MS изменяет значение по умолчанию в 5 секунд.
• Первый ход: после поступления сообщения первый ход ждёт до 2 секунд stdio-серверы, которые ещё подключаются. Пока сессия ждёт на этом этапе, первый ответ приходит медленнее. Чтобы изменить длительность этого ожидания, задайте CLAUDE_CODE_MCP_STARTUP_WAIT_MS в окружении раннера. Эта переменная не меняет, какие серверы охватывает ожидание. Требуется Claude Code v2.1.274 или новее.

RUN claude mcp add-json core '{"type":"http","url":"https://mcp.example.com/mcp","alwaysLoad":true}' --scope user

​

Отключение встроенных инструментов сессии

{
  "permissions": {
    "deny": [
      "mcp__Claude_Code_Remote",
      "mcp__claude-code-remote",
      "mcp__bf7c680d-5fdc-5ef4-b4a0-abadb619bf0a"
    ]
  }
}

​

Подсказка сеансов для отправки их работы

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "timeout": 10,
            "command": "\"$CLAUDE_CONFIG_DIR/hooks/stop-hook-nudge.sh\""
          }
        ]
      }
    ]
  }
}

#!/bin/sh
# Stop-hook reference implementation for self-hosted runners.
#
# Nudges Claude once per turn if the project directory has uncommitted
# changes OR unpushed commits, so work isn't lost when an idle session
# is released and so the "Create PR" button on claude.ai/code lights up.
#
# Runner-level (no repo changes): drop this file at ~/.claude/hooks/ on
# the runner host and merge the accompanying Stop-hook settings block
# into ~/.claude/settings.json — the runner seeds both into every session.
# Repo-level alternative: commit to <repo>/.claude/hooks/ and change the
# settings.json command path to $CLAUDE_PROJECT_DIR/.claude/hooks/.
#
# stdin: hook JSON payload (see https://code.claude.com/docs/en/hooks)
# stdout: {"decision":"block","reason":"..."} to nudge, or nothing to allow stop.

# Re-entry guard: the harness sets stop_hook_active=true when re-invoking
# the Stop hook after a block. Bail so we only nudge once per turn. The
# harness emits compact JSON (no space after the colon), which this
# pattern relies on; use jq if you need a whitespace-tolerant check.
in=$(cat)
case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

d="$CLAUDE_PROJECT_DIR"

# Hardening: this script runs outside Claude Code's Bash sandbox, so its git
# calls skip some features that can start a program named in the checkout's
# git settings. They don't skip them all, so don't count on the sandbox alone.
GIT_OPTIONAL_LOCKS=0
export GIT_OPTIONAL_LOCKS
git() { command git -c core.fsmonitor= -c core.hooksPath=/dev/null "$@"; }

# Not a git repo → nothing to nudge.
git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

# No remote → "push to the remote" is unsatisfiable; bail.
[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

# Uncommitted changes (staged, unstaged, or untracked). Exclude .claude/
# entirely — operator-seeded settings and CLI-written runtime state
# (scheduler lock, worktrees, routine state) live there and neither is
# "uncommitted work" the model needs to push.
s=$(git -C "$d" status --porcelain --ignore-submodules=dirty -- . ':(exclude).claude/' 2>/dev/null)
if [ -n "$s" ]; then
  printf '{"decision":"block","reason":"There are uncommitted changes in the repository. Please commit and push these changes to the remote branch."}'
  exit 0
fi

# Unpushed commits. Count commits on HEAD not reachable from any
# remote-tracking ref or FETCH_HEAD. This works uniformly for:
#   - init+fetch checkouts (runner default: only FETCH_HEAD exists)
#   - clone-based checkouts (origin/* exist)
#   - the runner default: the child starts on the session's outcome
#     branch, which the runner creates after checkout
#   - detached HEAD, when a custom setup skips that branch creation
# With no reference point at all (never fetched), stay silent rather
# than false-positive on a read-only turn.
base=""
git -C "$d" rev-parse --verify -q FETCH_HEAD >/dev/null && base="FETCH_HEAD"
if [ -z "$base" ] && [ -z "$(git -C "$d" for-each-ref --count=1 refs/remotes/origin 2>/dev/null)" ]; then
  exit 0
fi
# shellcheck disable=SC2086  # $base is either "" or "FETCH_HEAD", intentional word-split
unpushed=$(git -C "$d" rev-list HEAD --not $base --remotes=origin --count 2>/dev/null) || unpushed=0
if [ "$unpushed" -gt 0 ]; then
  branch=$(git -C "$d" symbolic-ref --short -q HEAD)
  if [ -n "$branch" ]; then
    # $branch is attacker-influenced — git-check-ref-format(1) allows `"`
    # in ref names. `\` is forbidden (rule 10) but escaped anyway as cheap
    # defense-in-depth.
    # Escape JSON metacharacters before interpolating into the hand-built
    # payload so a branch like x","continue":false can't inject keys into
    # the hook-output JSON the harness parses. $unpushed is safe — the
    # -gt guard above rejects anything that isn't a plain integer.
    branch_esc=$(printf '%s' "$branch" | sed 's/\\/\\\\/g; s/"/\\"/g')
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on branch '\''%s'\''. Please push these changes to the remote repository."}' "$unpushed" "$branch_esc"
  else
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on a detached HEAD. Please create a branch and push it to the remote repository."}' "$unpushed"
  fi
  exit 0
fi

exit 0

• Идентификацию git: задайте user.name и user.email в образе средства выполнения или запустите средство выполнения с флагом --configure-git
• Учётные данные для отправки: используйте git под управлением Anthropic или предоставьте учётные данные, как описано в разделе Включение конфигурации git в образ
• Для возобновлённых сессий: задайте флаг --push-outcome-on-release на каждом средстве выполнения в окружении. Тогда возобновлённая сессия начинается с коммитов, которые Claude отправил в ветку сессии. Об ограничениях флага см. Возобновлённые сессии теряют неотправленную работу.

​

Подмодули и хук Stop

• Новый коммит в подмодуле: Claude получает промпт, пока родительский репозиторий не зафиксирует его, даже если .gitmodules задаёт ignore = all для этого подмодуля
• Незафиксированные файлы в подмодуле: Claude не получает промпт, поэтому эта работа остаётся только на диске средства выполнения
• Неотправленные коммиты в подмодуле: хук Stop не проверяет, отправлены ли они, поэтому родительский репозиторий может указывать на коммит, который больше никто не может получить

​

Замена более ранней копии скрипта хука Stop

• Когда: если ваши сессии работают с включённой песочницей Bash, замените скрипт сейчас. В противном случае замените его при следующей сборке образа или перезапуске средства выполнения.
• Что меняется: незафиксированные файлы в подмодуле больше не вызывают промпт для Claude. Новый коммит в подмодуле, который .gitmodules помечает как ignore = all, теперь вызывает.

​

Разрешения и подтверждение инструментов

#!/bin/bash
exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --permission-mode auto

​

Как собирается конфигурация каждой сессии

• Настройки проекта: вне треда проекта закоммиченный в репозиторий .claude/settings.json накладывается поверх базового пользовательского уровня. В сессии с несколькими репозиториями действует файл не более чем одного репозитория.
• Управляемые настройки: сессии читают managed-settings.json из стандартного системного пути в образе раннера. О том, применяются ли его ключи наряду с настройками, управляемыми сервером, см. как Claude Code объединяет управляемые источники.

• Куда они попадают: раннер записывает каждый переданный скрипт хука в зарезервированный подкаталог hooks/.ccr-launcher/ каталога конфигурации сессии и регистрирует скрипты в отдельном файле настроек, который передаёт сессии через --settings, не затрагивая заполненный settings.json и ваши собственные скрипты в hooks/<name>. Раннер пересоздаёт зарезервированный подкаталог для каждой сессии и не переносит в сессии содержимое хоста из ~/.claude/hooks/.ccr-launcher/.
• Кто их создаёт: управляющий уровень заполняет скрипты из фиксированных констант собственного развёртывания, никогда — из данных конкретной сессии или сторонних данных.
• Что по-прежнему ими управляет: хуки, переданные через --settings, входят в обычную объединённую конфигурацию хуков, а не в управляемый уровень, поэтому ваши управляемые настройки продолжают действовать. disableAllHooks отключает их, и они не входят в категории, которые allowManagedHooksOnly оставляет загруженными.

​

Остановка сессий, которым не удалось получить настройки, управляемые сервером

• Сессии каналов Claude Tag: не задавайте ключ на раннерах в окружении, на которое Owner направляет каналы Claude Tag. API Anthropic отклоняет запрос этих сессий на получение настроек, управляемых сервером, поэтому при заданном ключе они не запускаются. Поместите их правила в managed-settings.json образа раннера, который они по-прежнему читают. Чтобы использовать ключ для других сессий, запускайте их в отдельном окружении.
• Bedrock или Agent Platform: сессии у этих провайдеров не получают настройки, управляемые сервером, поэтому они запускаются независимо от того, задан ли ключ. Вместо этого применяйте свои правила через тот же managed-settings.json.

{
  "forceRemoteSettingsRefresh": true
}

​

Настройки репозиториев в сессиях с несколькими репозиториями

• --capacity 1 (по умолчанию) со встроенным checkout: сессия начинается в первом репозитории из своего списка репозиториев. .claude/settings.json этого репозитория действует как настройки проекта, и его .mcp.json загружается, а у остальных репозиториев — нет.
• --capacity больше единицы или хук checkout: сессия начинается в отдельном каталоге сессии, содержащем checkout-копии. .claude/settings.json ни одного репозитория не действует как настройки проекта, .mcp.json ни одного репозитория не загружается, а $CLAUDE_PROJECT_DIR в команде хука указывает на этот каталог, а не на checkout-копию.

​

Правила разрешений, закоммиченные в репозиторий

​

Что дальше

• Reference: каждый флаг CLI, переменная окружения и метрика
• Verify session identity: проверьте токен сеанса из служб вне средства выполнения