Claude Code: лимит фоновой команды 30 минут - когда он действует

С версии 2.1.285 у команд, которые Claude Code запускает в фоне, есть лимит времени жизни. Это относится, например, к npm run dev и сборке в режиме отслеживания изменений. По умолчанию это 30 минут, а потолок без настройки 2 часа, даже если Claude передал timeout длиннее. Когда лимит истекает, Claude Code останавливает команду и сообщает Claude причину. С версии 2.1.288 этот лимит действует только в автономных запусках - флаг -p, приложение на Agent SDK, задача CI или облачная сессия. В интерактивном терминале, настольном приложении и расширении для VS Code лимита нет: до 2.1.288 он действовал везде.

В Telegram-канале выходят новости вайб-кодинга: инструменты, находки, ошибки.

Что именно изменилось в 2.1.285

Запись о версии 2.1.285 есть в официальном журнале изменений Claude Code. Вот она в коммите репозитория anthropics/claude-code на GitHub, который добавил её в CHANGELOG.md:

Перевод: изменили так, что фоновые Bash- и PowerShell-команды останавливаются по истечении лимита времени (их timeout вместе с run_in_background, по умолчанию 30 минут, максимум 2 часа); при остановке Claude получает уведомление.

Где лимит действует, а где нет

Документация tools-reference.md прямо называет, где лимит действует:

Перевод: в сессии, которая работает без присмотра - запуск с флагом -p, приложение на Agent SDK, задача CI или облачная сессия - у фоновых Bash- и PowerShell-команд есть лимит времени. У локальной сессии, в которой ты сам работаешь из терминала, десктоп-приложения или расширения VS Code, лимита на фоновые команды нет.

Лимит требует Claude Code 2.1.285 или новее. До 2.1.288 он действовал в любой сессии.

Если ты работаешь в обычном интерактивном терминале Claude Code, дальнейшее про 30 минут и 2 часа тебя не касается напрямую - это про -p, SDK, CI и облако. Если ты запускаешь Claude Code автономно - по расписанию, из Agent SDK или в CI, лимит работает так:

Как работает лимит на практике

Официальная документация tools-reference.md разделяет два сценария запуска:

Перевод: отсчёт лимита времени идёт с момента, когда команда попадает в фон. Команда, которую Claude запускает в фоне, получает 30 минут или timeout, который Claude передаёт вместе с run_in_background, максимум до 2 часов. Команда, которая начинается на переднем плане и потом переходит в фон, например по своему таймауту, получает 30 минут с момента перехода.

Не путай этот лимит с обычным таймаутом команды на переднем плане. По умолчанию команда на переднем плане получает 2 минуты. Если за это время она не завершилась, Claude Code не останавливает её, а переводит в фон (кроме команд, которые начинаются с sleep). С этого момента и начинается отсчёт фоновых 30 минут.

Когда фоновая команда достигает лимита, Claude Code её останавливает и сообщает Claude причину. Уведомление звучит дословно так: Background command "<description>" was stopped after reaching its background time limit. Если работа ещё не закончена, Claude может запустить команду снова с бо́льшим timeout.

Лимит не единственная причина остановки. Фоновая команда заканчивается и раньше, если сама завершилась или её остановили, например через /tasks. Есть и ещё два случая. Команда, которую запустил субагент на переднем плане, останавливается, когда заканчивается запуск этого субагента. В неинтерактивном режиме с флагом -p фоновые команды завершаются вскоре после итогового результата запуска.

Если долгие фоновые процессы у тебя обычное дело, лучше один раз разобраться в настройках лимита, чем каждый раз выяснять, почему сервер остановился. Лимит фоновых команд при этом лишь одна из настроек рабочего процесса с ИИ-агентом. Если ты выстраиваешь такой процесс, посмотри практикум СмыслоКода.

Интенсив по Hermes-агентам

Собери свою компанию на ИИ-агентах

Три вечера: от метода одного агента до связки ролей в компании

Старт 6–8 октября  ·  2 000 ₽

Записаться на интенсив по Hermes-агентам →

Как поднять лимит

Первый способ обходится без настроек. Таймаут для конкретной команды выбирает сам Claude, документация говорит об этом прямо:

Перевод: каждая команда выполняется с таймаутом, и им управляет Claude: когда ему нужно больше времени, чем по умолчанию, он передаёт параметр timeout вместе с вызовом. Таймаут для отдельной команды ты никогда не задаёшь сам.

Поэтому ты можешь только написать Claude в задаче, сколько должна проработать фоновая команда. Это просьба, а не настройка: решение передать timeout остаётся за Claude, и без переменных окружения больше 2 часов не получится.

Второй способ: переменные окружения. Документация описывает их так:

Перевод: две переменные окружения поднимают эти лимиты, одинаково для Bash- и PowerShell-команд. Обе задаются в миллисекундах, и ни одна не может укоротить лимит: меньшее значение оставляет 30 минут по умолчанию и максимум 2 часа как есть. Задай BASH_DEFAULT_TIMEOUT_MS больше 1800000, чтобы заменить 30 минут по умолчанию этим значением, и для команд, которые Claude запускает без timeout, и для переведённых в фон. Задай BASH_MAX_TIMEOUT_MS больше 7200000, чтобы поднять максимум в 2 часа до этого значения. BASH_DEFAULT_TIMEOUT_MS больше 7200000 поднимает максимум точно так же.

Выбор переменной зависит от задачи:

• Команда без своего timeout должна жить дольше 30 минут. Нужна BASH_DEFAULT_TIMEOUT_MS больше 1800000. Только она меняет 30 минут по умолчанию. Например, BASH_DEFAULT_TIMEOUT_MS=10800000 даёт 3 часа по умолчанию, а поскольку это больше 7200000, потолок тоже становится 3 часа.
• Claude передаёт timeout длиннее 2 часов. Нужна BASH_MAX_TIMEOUT_MS больше 7200000, например 10800000 для потолка в 3 часа. Одна эта переменная 30 минут по умолчанию не меняет: команда, которую Claude запустил в фоне без своего timeout, всё равно остановится через 30 минут.

У BASH_DEFAULT_TIMEOUT_MS есть побочный эффект. Та же переменная задаёт таймаут команды на переднем плане, когда Claude не передал свой: из коробки это 2 минуты. Если поднять её до 3 часов, команда на переднем плане без своего timeout тоже получит 3 часа, прежде чем Claude Code переведёт её в фон.

Раздел о фоновых командах не говорит, где задавать эти переменные. Ответ есть на других страницах той же документации. Страница о данных и телеметрии говорит: «All environment variables can be checked into settings.json», то есть любую переменную окружения можно записать в settings.json. Страница о проверке настроек уточняет, какой это файл: блок env хранится в ~/.claude/settings.json, а не в похожем по имени ~/.claude.json, где лежит состояние приложения. Как выглядит блок env, показывает пример из tools-reference.md для другой переменной, CLAUDE_CODE_USE_POWERSHELL_TOOL.

По тому же образцу запись для фонового лимита в 1 час выглядит так:

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

Если в файле уже есть блок env, добавь строку в него, а не создавай второй. Значение 3600000 меньше 7200000, поэтому потолок остаётся 2 часа; побочный эффект для команд на переднем плане из абзаца выше здесь тоже действует.

Чтобы проверить, что файл настроек читается без ошибок, запусти в терминале claude doctor: по документации команда выводит диагностику установки и настроек, не открывая сессию. Внутри сессии команда /status показывает, какие источники настроек сейчас активны. Обе команды проверяют файл и источники настроек, а не то, сколько на самом деле проживёт фоновая команда.

Когда новое значение начинает действовать, документация для этих переменных отдельно не описывает. В разделе о хуках страница о проверке настроек пишет, что правка settings.json вступает в силу в уже запущенной сессии после короткой задержки и перезапуск не нужен. Распространяется ли это на блок env и фоновый лимит, страница не уточняет. Поэтому ниже порядок действий построен так, чтобы результат проверялся по факту, а не по предположению.

Отдельная переменная CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 не снимает лимит, а отключает фоновые задачи целиком: и автоматический перевод в фон, и остальную работу с фоновыми задачами.

Что делать, если процесс уже остановился

1. Спроси Claude, что произошло: Claude Code сообщает ему причину остановки.
2. Если это разовый долгий прогон до 2 часов, попроси Claude запустить команду снова с бо́льшим timeout. На этом можно остановиться.
3. Если фоновые команды без своего timeout регулярно нужны дольше 30 минут, сначала впиши BASH_DEFAULT_TIMEOUT_MS больше 1800000 в блок env файла ~/.claude/settings.json, как в примере выше. Одна BASH_MAX_TIMEOUT_MS для этого не подойдёт. Если нужно больше 2 часов, впиши туда же BASH_MAX_TIMEOUT_MS больше 7200000 или BASH_DEFAULT_TIMEOUT_MS больше 7200000.
4. Проверь файл командой claude doctor: она покажет ошибки в файле настроек, но не длительность фоновой команды.
5. Только после этого попроси Claude запустить остановленную команду заново. Влияет ли новое значение на команду, которая уже работала в фоне до правки, документация не говорит, поэтому рассчитывай на новый запуск.
6. Проверь результат по факту: когда пройдёт больше 30 минут с запуска, открой /tasks и посмотри, есть ли команда в списке фоновых задач. Если её нет, а Claude сообщил об остановке по лимиту, значит, новое значение к этой команде не применилось. Тогда начни новую сессию Claude Code и повтори шаги 5 и 6.

Той же командой /tasks можно остановить фоновую задачу раньше лимита.

Изменение описано в записи версии 2.1.285. Anthropic может уточнить лимиты в следующих релизах, поэтому перед изменением настроек в важном проекте сверяй значения с официальной документацией.

Другие материалы о Claude Code на СмыслоКоде: Как сделать сайт на Astro через Claude Code: от пустой папки до публикации, 11 советов Claude Code в 2026: шорткаты, флаги и команды и Ultracode в Claude Code: режим xhigh и dynamic workflows за 10 минут.

Интенсив по Hermes-агентам

Собери свою компанию на ИИ-агентах

Три вечера: от метода одного агента до связки ролей в компании

Старт 6–8 октября  ·  2 000 ₽

Записаться на интенсив по Hermes-агентам →

Новые материалы - дайджестом, без спама

Гайды выходят регулярно. Подпишись, чтобы не пропускать: пришлю подборку в Telegram или на email. Раз в неделю или каждый день - выбираешь сам.

Подписаться в Telegramили на email