Claude Code: почему фоновая команда останавливается через 30 минут

В автономном запуске Claude Code может остановить фоновую команду через 30 минут. Это относится к вызовам с флагом -p, приложениям на Agent SDK, заданиям CI и облачным сессиям. Если Claude назначил команде собственный срок, она может работать до 2 часов. В интерактивной сессии из терминала, настольного приложения или VS Code начиная с версии 2.1.288 ограничения нет.

Когда-то я проводил у экрана весь день: выдавал агенту очередной шаг, проверял результат, вносил поправки и отправлял его дальше. Машина писала код, а я непрерывно ею управлял. Теперь я составляю план, разбиваю работу на этапы и поручаю субагентам выполнять их ночью. Через 8 часов Claude может пройти весь план: исследовать задачу, реализовать решение и доработать его. Утром остаётся больше принимать готовое, чем переписывать.

Однако ночной процесс, запущенный через -p, по расписанию на сервере, в CI или в облаке, может потерять фоновый сервер разработки или сборку уже через 30 минут. Claude Code остановит команду, и работа прервётся. Ниже разберём, на какие запуски распространяется ограничение, как его увеличить и как поступить после остановки.

Подробнее о сервисе — в документации Ailoot.

На какие запуски распространяется ограничение#

Фоновая команда — это процесс, который Claude запускает и оставляет работать, пока занимается другой задачей. Например, это может быть сервер разработки npm run dev или сборка, отслеживающая изменения файлов.

В справочнике Anthropic описано следующее:

Иными словами, предел установлен для работы, которая выполняется без вашего участия: запусков с -p, приложений Agent SDK, заданий CI и облачных сессий. Если вы сами работаете в терминале, настольном приложении или VS Code, ограничения нет начиная с версии 2.1.288. Оно появилось в 2.1.285, а до 2.1.288 действовало во всех сессиях.

Определить, относится ли это к вашей ситуации, можно так:

• Вы запустили Claude Code в терминале или VS Code, поручили задачу и ушли спать. В версии 2.1.288 и выше временного предела нет. В версиях 2.1.285–2.1.287 он применялся и к такому запуску. Инструкцию по обновлению я приводил в отдельной статье.
• Claude Code запускается командой claude -p "задача" по расписанию, из приложения на Agent SDK или в CI. Для такого запуска предел есть.
• Задача выполняется в облачной сессии. Предел также действует.

Поручая агентам работать самостоятельно, я добавляю в запрос требование записать в план условия и причины остановки, а также проверить, зависит ли процесс от окна, которое я могу закрыть, или от моего компьютера. Ограничение фоновой работы в 30 минут — один из факторов, который следует учесть.

Сколько может работать фоновая команда Claude Code?#

Время начинают отсчитывать, когда команда переходит в фоновый режим. Возможны два сценария.

Claude сразу запускает команду в фоне. Ей отводится 30 минут. Если при запуске Claude указал для неё собственное время через параметр timeout, используется это значение, но не более 2 часов.

Команда не завершилась, пока Claude её ожидал. Обычно Claude ждёт результат команды 2 минуты. Если она всё ещё выполняется, Claude Code оставляет её работать в фоне. С этого момента начинается её 30-минутный срок.

По истечении срока Claude Code прекращает команду и передаёт Claude такое сообщение:

Background command "<description>" was stopped after reaching its background time limit

Если задача ещё не завершена, Claude может повторно запустить команду, назначив ей больше времени.

Для запуска с -p есть отдельное условие: фоновые команды завершаются примерно через 5 секунд после окончательного ответа Claude. Поэтому сервер, поднятый ночным запуском с -p, будет работать примерно столько же, сколько длится сам запуск. Ограничение в 30 минут становится существенным, если запуск продолжается дольше: например, Claude поднимает сервер в начале, а затем час выполняет на нём проверки.

Как организовать ночную работу Claude Code#

Мне надоело постоянно контролировать агента, поэтому я заменил отдельные ручные поручения одним управляющим запросом. Вечером запускаю работу, и Claude проходит этапы по порядку: пишет код, проверяет его, исправляет ошибки и создаёт коммиты.

Группы субагентов выполняют работу в отдельных файлах, чтобы не мешать друг другу. Свежая группа проверяет результаты: проводит ревью кода, проверяет безопасность и запускает программу. Найденные ошибки исправляются, после чего проверки выполняются снова. В запросе также указывается: если закончится контекст, нужно сохранить состояние, чтобы продолжить при следующем запуске.

В описанном случае за 3 дня удалось пройти 8 из 14 этапов.

Есть два условия. Управляющий запрос не заменяет продуманный план: сначала нужно подробно описать этапы, а затем запускать ночную работу. Кроме того, такая задача может заметно расходовать лимит подписки, поэтому подход не всегда оправдан для небольшой работы. Задайте предел числа попыток, чтобы агент не израсходовал весь лимит за ночь. О настройках ограничения расходов я писал в отдельной статье.

Как увеличить временной предел#

Способ 1: попросить Claude. Время для конкретной команды определяет сам Claude. В запросе можно указать, например: «Оставь сервер разработки в фоне на 2 часа». Этот способ не позволяет превысить двухчасовой предел.

Способ 2: настроить переменные окружения. Значения указываются в миллисекундах. Уменьшить базовые 30 минут или предел в 2 часа нельзя, но их можно увеличить.

• BASH_DEFAULT_TIMEOUT_MS: значение больше 1800000 (30 минут) увеличивает срок по умолчанию. Оно применяется и к командам, для которых Claude не задал отдельное время, и к командам, перешедшим в фон после тайм-аута ожидания. Если задать больше 7200000 (2 часа), увеличится также верхний предел.
• BASH_MAX_TIMEOUT_MS: значение больше 7200000 поднимает верхнюю границу в 2 часа. Стандартные 30 минут эта переменная не меняет: команда без собственного срока всё равно остановится через 30 минут.

У BASH_DEFAULT_TIMEOUT_MS есть дополнительный эффект: эта же переменная определяет, как долго Claude будет ждать обычную команду, прежде чем перевести её в фон. При значении в 1 час ожидание вместо стандартных 2 минут тоже составит час. Для ночной работы это обычно несущественно, но днём ответы на долгие команды будут приходить позже.

Если требуется установить 3 часа и для стандартного времени, и для верхнего предела, достаточно задать BASH_DEFAULT_TIMEOUT_MS со значением 10800000. Добавлять вторую переменную не нужно.

Настройки хранятся в ~/.claude/settings.json в домашней папке на macOS и Linux, а в Windows — в %USERPROFILE%\.claude\settings.json. Если файла ещё нет, создайте его. Пример настройки на 1 час:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "3600000"
  }
}

Если в файле уже есть раздел env, внесите переменную в него. Сохранённые изменения применяются к запущенной сессии после сохранения файла. Удалённая переменная окончательно перестанет действовать при следующем запуске claude.

Файл настроек должен находиться на той машине, где запущен агент. Для ночной работы компьютер должен оставаться включённым и не переходить в спящий режим. Другой вариант — запустить Claude Code на удалённом сервере и хранить настройки там.

Что делать, если команда уже остановилась#

Сначала спросите Claude, что произошло: Claude Code передаёт ему причину остановки.

Затем выполните следующие действия:

1. Нужен один долгий запуск продолжительностью до 2 часов. Попросите Claude запустить команду ещё раз и назначить ей больше времени.
2. Команды регулярно работают дольше 30 минут. Добавьте в файл настроек BASH_DEFAULT_TIMEOUT_MS со значением больше 1800000, как в примере выше. Если нужно более 2 часов, добавьте туда же BASH_MAX_TIMEOUT_MS со значением больше 7200000.
3. Запустите команду повторно. Документация не гарантирует, что новая настройка изменит время уже работающей фоновой команды.
4. Проверьте результат следующего запуска. Если в отчёте Claude опять появится сообщение «stopped after reaching its background time limit», заданное значение не применилось к этой команде.

Субагенты и рутины помогают организовать работу агента, когда вы не можете следить за ним постоянно.

О циклическом ночном запуске агента я рассказывал в отдельной статье. Настройка Claude Code для ночной работы над проектом описана здесь.

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

Познакомьтесь с Ailoot.