Documentation — Spybara

agent-sdk/hooks.md +64 −64

Details

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

16 16

17<h2 id="how-hooks-work">17<h2 id="how-hooks-work">

~~18 Как работают hooks~~18 Как работают хуки

19</h2>19</h2>

20 20

21<Steps>21<Steps>

22 <Step title="Срабатывает событие">22 <Step title="Срабатывает событие">

23 Что-то происходит во время выполнения агента, и SDK срабатывает событие: инструмент вот-вот будет вызван (`PreToolUse`), инструмент вернул результат (`PostToolUse`), подагент запустился или остановился, агент неактивен или выполнение завершилось. См. [полный список событий](#available-hooks).23 Во время выполнения агента что-то происходит, и SDK генерирует событие: инструмент вот-вот будет вызван (`PreToolUse`), инструмент вернул результат (`PostToolUse`), субагент запустился или остановился, агент простаивает или выполнение завершилось. См. [полный список событий](#available-hooks).

24 </Step>24 </Step>

25 25

~~26 <Step title="SDK собирает зарегистрированные hooks">~~26 <Step title="SDK собирает зарегистрированные хуки">

27 SDK проверяет наличие hooks, зарегистрированных для этого типа события. Это включает callback hooks, которые вы передаете в `options.hooks`, и hooks команд shell из файлов настроек, когда соответствующая запись [`settingSources`](/docs/ru/agent-sdk/typescript#settingsource) или [`setting_sources`](/docs/ru/agent-sdk/python#settingsource) включена, что она есть для параметров `query()` по умолчанию.27 SDK проверяет наличие хуков, зарегистрированных для этого типа события. Сюда входят callback-хуки, которые вы передаете в `options.hooks`, и хуки shell-команд из файлов настроек, если включена соответствующая запись [`settingSources`](/docs/ru/agent-sdk/typescript#settingsource) или [`setting_sources`](/docs/ru/agent-sdk/python#settingsource), что по умолчанию так и есть для параметров `query()`.

28 </Step>28 </Step>

29 29

~~30 <Step title="Matchers фильтруют, какие hooks запускаются">~~30 <Step title="Фильтрация запускаемых хуков с помощью matcher">

31 Если hook имеет паттерн [`matcher`](#matchers) (например, `"Write|Edit"`), SDK проверяет его против цели события (например, имя инструмента). Hooks без matcher запускаются для каждого события этого типа.31 Если у хука есть паттерн [`matcher`](#matchers) (например, `"Write|Edit"`), SDK проверяет его на соответствие цели события (например, имени инструмента). Хуки без matcher запускаются для каждого события этого типа.

32 </Step>32 </Step>

33 33

34 <Step title="Выполняются функции обратного вызова">34 <Step title="Выполняются функции обратного вызова">

35 Каждая функция [обратного вызова](#callback-functions) matching hook получает информацию о том, что происходит: имя инструмента, его аргументы, ID сеанса и другие детали, специфичные для события.35 [Функция обратного вызова](#callback-functions) каждого подходящего хука получает информацию о том, что происходит: имя инструмента, его аргументы, ID сессии и другие детали, специфичные для события.

36 </Step>36 </Step>

37 37

38 <Step title="Ваш callback возвращает решение">38 <Step title="Ваш callback возвращает решение">

39 После выполнения любых операций (логирование, вызовы API, валидация), ваш callback возвращает [объект вывода](#outputs), который говорит агенту, что делать: разрешить операцию, заблокировать ее, изменить входные данные или внедрить контекст в разговор.39 После выполнения любых операций (логирование, вызовы API, валидация) ваш callback возвращает [объект вывода](#outputs), который сообщает агенту, что делать: разрешить операцию, заблокировать ее, изменить входные данные или внедрить контекст в диалог.

40 </Step>40 </Step>

41</Steps>41</Steps>

42 42

43Следующий пример объединяет эти шаги. Он регистрирует hook `PreToolUse` (шаг 1) с matcher `"Write|Edit"` (шаг 3), поэтому callback срабатывает только для инструментов записи файлов. При срабатывании callback получает входные данные инструмента (шаг 4), проверяет, нацелена ли путь файла на файл `.env`, и возвращает `permissionDecision: "deny"` для блокировки операции (шаг 5):43Следующий пример объединяет эти шаги. Он регистрирует хук `PreToolUse` (шаг 1) с matcher `"Write|Edit"` (шаг 3), поэтому callback срабатывает только для инструментов записи файлов. При срабатывании callback получает входные данные инструмента (шаг 4), проверяет, указывает ли путь файла на файл `.env`, и возвращает `permissionDecision: "deny"` для блокировки операции (шаг 5):

44 44

45<CodeGroup>45<CodeGroup>

46 ```python Python theme={null}46 ```python Python theme={null}

140 ```140 ```

141</CodeGroup>141</CodeGroup>

142 142

143Когда вы запустите любой из скриптов, Claude попытается создать файл `.env`, hook заблокирует вызов инструмента, и финальный ответ Claude объяснит, что он не может создавать файлы `.env`.143Когда вы запустите любой из скриптов, Claude попытается создать файл `.env`, и хук отклонит вызов инструмента.

144 144

145<h2 id="available-hooks">145<h2 id="available-hooks">

146 Доступные hooks146 Доступные hooks

179| `ConfigChange` | Нет | Да | Файл конфигурации изменился | Динамически перезагрузить настройки |179| `ConfigChange` | Нет | Да | Файл конфигурации изменился | Динамически перезагрузить настройки |

180| `InstructionsLoaded` | Нет | Да | Файл `CLAUDE.md` или файл правил загружается в контекст | Проверять, какие файлы инструкций загружаются |180| `InstructionsLoaded` | Нет | Да | Файл `CLAUDE.md` или файл правил загружается в контекст | Проверять, какие файлы инструкций загружаются |

181| `WorktreeCreate` | Нет | Да | Git worktree создан | Отслеживать изолированные рабочие пространства |181| `WorktreeCreate` | Нет | Да | Git worktree создан | Отслеживать изолированные рабочие пространства |

182| `WorktreeRemove` | Нет | Да | Git worktree удален | Очистить ресурсы рабочего пространства |182| `WorktreeRemove` | Нет | Да | Удаляется worktree, созданный хуком `WorktreeCreate` | Очистить ресурсы рабочего пространства |

183| `CwdChanged` | Нет | Да | Рабочий каталог изменяется во время сеанса | Перезагрузить переменные окружения для каждого каталога |183| `CwdChanged` | Нет | Да | Рабочий каталог изменяется во время сеанса | Перезагрузить переменные окружения для каждого каталога |

184| `FileChanged` | Нет | Да | Отслеживаемый файл изменяется, создаётся или удаляется | Перезагрузить конфигурацию при изменении файлов проекта |184| `FileChanged` | Нет | Да | Отслеживаемый файл изменяется, создаётся или удаляется | Перезагрузить конфигурацию при изменении файлов проекта |

185| `DirectoryAdded` | Нет | Да | Рабочий каталог добавляется во время сеанса | Установить зависимости для репозитория, добавленного во время сеанса |185| `DirectoryAdded` | Нет | Да | Рабочий каталог добавляется во время сеанса | Установить зависимости для репозитория, добавленного во время сеанса |

186 186

187<h2 id="configure-hooks">187<h2 id="configure-hooks">

188 Настройка hooks188 Настройка хуков

189</h2>189</h2>

190 190

191Чтобы настроить hook, передайте его в поле `hooks` ваших параметров агента (`ClaudeAgentOptions` в Python, объект `options` в TypeScript). Этот фрагмент предполагает, что вы уже определили callback hook, например `protect_env_files` в Python или `protectEnvFiles` в TypeScript из примера выше:191Чтобы настроить хук, передайте его в поле `hooks` ваших параметров агента (`ClaudeAgentOptions` в Python, объект `options` в TypeScript). Этот фрагмент предполагает, что вы уже определили callback хука, например `protect_env_files` в Python или `protectEnvFiles` в TypeScript из примера выше:

192 192

193<CodeGroup>193<CodeGroup>

194 ```python Python theme={null}194 ```python Python theme={null}

218 218

219Опция `hooks` — это словарь (Python) или объект (TypeScript), где:219Опция `hooks` — это словарь (Python) или объект (TypeScript), где:

220 220

221* **Ключи**: [имена событий hook](#available-hooks), такие как `'PreToolUse'`, `'PostToolUse'` и `'Stop'`221* **Ключи**: [имена событий хуков](#available-hooks), такие как `'PreToolUse'`, `'PostToolUse'` и `'Stop'`

222* **Значения**: массивы [matchers](#matchers), каждый содержащий необязательный паттерн фильтра и ваши [функции обратного вызова](#callback-functions)222* **Значения**: массивы [matchers](#matchers), каждый содержащий необязательный паттерн фильтра и ваши [функции обратного вызова](#callback-functions)

223 223

224<h3 id="matchers">224<h3 id="matchers">

225 Matchers225 Matchers

226</h3>226</h3>

227 227

228Используйте matchers для фильтрации, когда срабатывают ваши callbacks. Поле `matcher` соответствует другому значению в зависимости от типа события hook. Например, hooks на основе инструментов соответствуют имени инструмента, в то время как hooks `Notification` соответствуют типу уведомления.228Используйте matchers для фильтрации, когда срабатывают ваши callbacks. Поле `matcher` сопоставляется с разными значениями в зависимости от типа события хука. Например, хуки на основе инструментов сопоставляются с именем инструмента, в то время как хуки `Notification` сопоставляются с типом уведомления.

229 229

230SDK matchers следуют тем же правилам, что и [matchers в файлах настроек](/docs/ru/hooks#matcher-patterns). Этот раздел документирует пути оценки точной строки и регулярного выражения, требования к версиям и значения matcher для каждого типа события.230SDK matchers следуют тем же правилам, что и [matchers в файлах настроек](/docs/ru/hooks#matcher-patterns). Этот раздел документирует пути оценки точной строки и регулярного выражения, требования к версиям и значения matcher для каждого типа события.

231 231

232| Опция | Тип | По умолчанию | Описание |232| Опция | Тип | По умолчанию | Описание |

233| - | - | - | - |233| - | - | - | - |

234| `matcher` | `string` | `undefined` | Паттерн, сопоставляемый с полем фильтра события, следуя [правилам для matchers в файлах настроек](/docs/ru/hooks#matcher-patterns). Для hooks инструментов это имя инструмента. Встроенные инструменты включают `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `Agent` и другие (см. [Tool Input Types](/docs/ru/agent-sdk/typescript#tool-input-types) для полного списка). MCP инструменты используют паттерн `mcp__<server>__<action>`, где `<server>` — это ключ, который вы используете в конфигурации `mcpServers`. |234| `matcher` | `string` | `undefined` | Паттерн, сопоставляемый с полем фильтра события, следуя [правилам для matchers в файлах настроек](/docs/ru/hooks#matcher-patterns). Для хуков инструментов это имя инструмента. Встроенные инструменты включают `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `Agent` и другие (см. [Tool Input Types](/docs/ru/agent-sdk/typescript#tool-input-types) для полного списка). MCP инструменты используют паттерн `mcp__<server>__<action>`, где `<server>` — это ключ, который вы используете в конфигурации `mcpServers`. |

237 237

238Используйте паттерн `matcher` для нацеливания на конкретные инструменты, когда это возможно. Matcher с `'Bash'` запускается только для команд Bash, в то время как опущение паттерна запускает ваши callbacks для каждого возникновения события. Опустите его намеренно для логирования каждого вызова инструмента, который делает ваш сеанс.238Используйте паттерн `matcher` для нацеливания на конкретные инструменты, когда это возможно. Matcher с `'Bash'` запускается только для команд Bash, в то время как опущение паттерна запускает ваши callbacks для каждого возникновения события. Опустите его намеренно для логирования каждого вызова инструмента, который делает ваша сессия.

239 239

240<h3 id="callback-functions">240<h3 id="callback-functions">

241 Функции обратного вызова241 Функции обратного вызова

245 Входные данные245 Входные данные

246</h4>246</h4>

247 247

248Каждый callback hook получает три аргумента:248Каждый callback хука получает три аргумента:

249 249

250* **Входные данные:** типизированный объект, содержащий детали события. Каждый тип hook имеет свою форму входных данных. Например, `PreToolUseHookInput` включает `tool_name` и `tool_input`, в то время как `NotificationHookInput` включает `message`. См. полные определения типов в справочниках [TypeScript](/docs/ru/agent-sdk/typescript#hookinput) и [Python](/docs/ru/agent-sdk/python#hookinput) SDK.250* **Входные данные:** типизированный объект, содержащий детали события. Каждый тип хука имеет свою форму входных данных. Например, `PreToolUseHookInput` включает `tool_name` и `tool_input`, в то время как `NotificationHookInput` включает `message`. См. полные определения типов в справочниках [TypeScript](/docs/ru/agent-sdk/typescript#hookinput) и [Python](/docs/ru/agent-sdk/python#hookinput) SDK.

251 * Все входные данные hook содержат `session_id`, `cwd` и `hook_event_name`.251 * Все входные данные хуков содержат `session_id`, `cwd` и `hook_event_name`.

252 * `agent_id` и `agent_type` заполняются, когда hook срабатывает внутри подагента. В TypeScript они находятся на базовом входе hook и доступны для всех типов hook. В Python они являются необязательными полями на `PreToolUse`, `PostToolUse`, `PostToolUseFailure` и `PermissionRequest`, и обязательными полями на `SubagentStart` и `SubagentStop`.252 * `agent_id` и `agent_type` заполняются, когда хук срабатывает внутри субагента. В TypeScript они находятся на базовом входе хука и доступны для всех типов хуков. В Python они являются необязательными полями на `PreToolUse`, `PostToolUse`, `PostToolUseFailure` и `PermissionRequest`, и обязательными полями на `SubagentStart` и `SubagentStop`.

253* **ID использования инструмента** (`str | None` / `string | undefined`): коррелирует события `PreToolUse` и `PostToolUse` для одного и того же вызова инструмента.253* **ID использования инструмента** (`str | None` / `string | undefined`): коррелирует события `PreToolUse` и `PostToolUse` для одного и того же вызова инструмента.

254* **Контекст:** в TypeScript содержит свойство `signal` (`AbortSignal`) для отмены. В Python этот аргумент зарезервирован для будущего использования.254* **Контекст:** в TypeScript содержит свойство `signal` (`AbortSignal`) для отмены. В Python этот аргумент зарезервирован для будущего использования.

255 255

259 259

260Ваш callback возвращает объект с двумя категориями полей:260Ваш callback возвращает объект с двумя категориями полей:

261 261

262* **Поля верхнего уровня** принимаются для каждого события: `systemMessage` показывает сообщение пользователю, и `continue` (`continue_` в Python) определяет, продолжает ли агент работать после этого hook. Некоторые события отбрасывают их или доставляют их в другое место. Раздел каждого [события](/docs/ru/hooks#hook-events) на странице hooks говорит, где они попадают.262* **Поля верхнего уровня** принимаются для каждого события: `systemMessage` показывает сообщение пользователю, и `continue` (`continue_` в Python) определяет, продолжает ли агент работать после этого хука. Некоторые события отбрасывают их или доставляют их в другое место. Раздел каждого [события](/docs/ru/hooks#hook-events) на странице хуков говорит, где они попадают.

263* **`hookSpecificOutput`** контролирует текущую операцию. Поля, которые вы устанавливаете внутри, зависят от типа события хука:263* **`hookSpecificOutput`** контролирует текущую операцию. Поля, которые вы устанавливаете внутри, зависят от типа события хука:

264 * Для хуков `PreToolUse` здесь вы устанавливаете `permissionDecision` (`"allow"`, `"deny"`, `"ask"` или `"defer"`), `permissionDecisionReason` и `updatedInput`. Если вы вернете `"defer"`, ход завершается сообщением с результатом, у которого `stop_reason` равен `"tool_deferred"`, чтобы вы могли [возобновить вызов позже](/docs/ru/hooks#defer-a-tool-call-for-later).264 * Для хуков `PreToolUse` здесь вы устанавливаете `permissionDecision` (`"allow"`, `"deny"`, `"ask"` или `"defer"`), `permissionDecisionReason` и `updatedInput`. Если вы вернете `"defer"`, ход завершается сообщением с результатом, у которого `stop_reason` равен `"tool_deferred"`, чтобы вы могли [возобновить вызов позже](/docs/ru/hooks#defer-a-tool-call-for-later).

265 * Для хуков `PostToolUse` вы можете установить `additionalContext` для добавления информации к результату инструмента. Чтобы заменить выходные данные инструмента перед тем, как Claude их увидит, установите `updatedToolOutput`, который работает для любого инструмента в обоих SDK. Более старое поле `updatedMCPToolOutput` заменяет только выходные данные MCP инструмента и является устаревшим.265 * Для хуков `PostToolUse` вы можете установить `additionalContext` для добавления информации к результату инструмента. Чтобы заменить выходные данные инструмента перед тем, как Claude их увидит, установите `updatedToolOutput`, который работает для любого инструмента в обоих SDK. Более старое поле `updatedMCPToolOutput` заменяет только выходные данные MCP инструмента.

266 * В TypeScript SDK callback `PostToolUse` может также возвращать `classifierContext`, краткую заметку о результате вызова инструмента для классификатора разрешений [авторежима](/docs/ru/permission-modes#eliminate-prompts-with-auto-mode). Поскольку ваш callback работает в собственном процессе вашего приложения, классификатор может учитывать заявление пользователя, которое вы передаете в заметке, как намерение пользователя. Поле требует TypeScript Agent SDK версии 0.3.236 или позже. В разделе [Аннотирование результата для классификатора авторежима](/docs/ru/hooks#annotate-a-result-for-the-auto-mode-classifier) описаны ограничение по длине, правило только синхронного выполнения и то, что не следует помещать в заметку.266 * В TypeScript SDK callback `PostToolUse` может также возвращать `classifierContext`, краткую заметку о результате вызова инструмента для классификатора разрешений [авторежима](/docs/ru/permission-modes#eliminate-prompts-with-auto-mode). Поскольку ваш callback работает в собственном процессе вашего приложения, классификатор может учитывать заявление пользователя, которое вы передаете в заметке, как намерение пользователя. Поле требует TypeScript Agent SDK версии 0.3.236 или позже. В разделе [Аннотирование результата для классификатора авторежима](/docs/ru/hooks#annotate-a-result-for-the-auto-mode-classifier) описаны ограничение по длине, правило только синхронного выполнения и то, что не следует помещать в заметку.

267 267

268Возвращайте `{}` для разрешения операции без изменений. SDK callback hooks используют тот же формат вывода JSON, что и [hooks команд shell Claude Code](/docs/ru/hooks#json-output), который документирует каждое поле и опцию, специфичную для события. Для определений типов SDK см. справочники [TypeScript](/docs/ru/agent-sdk/typescript#synchookjsonoutput) и [Python](/docs/ru/agent-sdk/python#synchookjsonoutput) SDK.268Возвращайте `{}` для разрешения операции без изменений. SDK callback-хуки используют тот же формат вывода JSON, что и [хуки shell-команд Claude Code](/docs/ru/hooks#json-output), который документирует каждое поле и опцию, специфичную для события. Для определений типов SDK см. справочники [TypeScript](/docs/ru/agent-sdk/typescript#synchookjsonoutput) и [Python](/docs/ru/agent-sdk/python#synchookjsonoutput) SDK.

269 269

270<Note>270<Note>

271 Когда применяются несколько hooks или правил разрешений, `deny` имеет приоритет над `defer`, который имеет приоритет над `ask`, который имеет приоритет над `allow`. Если какой-либо hook возвращает `deny`, операция блокируется независимо от других hooks.271 Когда применяются несколько хуков или правил разрешений, `deny` имеет приоритет над `defer`, который имеет приоритет над `ask`, который имеет приоритет над `allow`. Если какой-либо хук возвращает `deny`, операция блокируется независимо от других хуков.

272</Note>272</Note>

273 273

274<h4 id="asynchronous-output">274<h4 id="asynchronous-output">

275 Асинхронный вывод275 Асинхронный вывод

276</h4>276</h4>

277 277

278По умолчанию агент ждет, пока ваш hook вернется, прежде чем продолжить. Если ваш hook выполняет побочный эффект, такой как логирование или отправка webhook, и не нужно влиять на поведение агента, вы можете вернуть асинхронный вывод вместо этого. Это говорит агенту продолжить немедленно без ожидания завершения hook. В этом фрагменте `send_to_logging_service` в Python и `sendToLoggingService` в TypeScript служат заменой для любой функции логирования, которую вы определяете:278По умолчанию агент ждет, пока ваш хук вернется, прежде чем продолжить. Если ваш хук выполняет побочный эффект, такой как логирование или отправка webhook, и ему не нужно влиять на поведение агента, вы можете вернуть асинхронный вывод вместо этого. Это говорит агенту продолжить немедленно без ожидания завершения хука. В этом фрагменте `send_to_logging_service` в Python и `sendToLoggingService` в TypeScript служат заменой для любой функции логирования, которую вы определяете:

279 279

280<CodeGroup>280<CodeGroup>

281 ```python Python theme={null}281 ```python Python theme={null}

297| Поле | Тип | Описание |297| Поле | Тип | Описание |

298| - | - | - |298| - | - | - |

301 301

302<Note>302<Note>

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

798</h2>798</h2>

799 799

800<h3 id="hook-not-firing">800<h3 id="hook-not-firing">

801 Hook не срабатывает801 Хук не срабатывает

802</h3>802</h3>

803 803

804* Проверьте, что имя события hook правильное и чувствительно к регистру (`PreToolUse`, а не `preToolUse`)804* Проверьте, что имя события хука правильное и чувствительно к регистру (`PreToolUse`, а не `preToolUse`)

805* Проверьте, что ваш паттерн matcher точно совпадает с именем инструмента805* Проверьте, что ваш паттерн matcher точно совпадает с именем инструмента

806* Убедитесь, что hook находится под правильным типом события в `options.hooks`806* Убедитесь, что хук находится под правильным типом события в `options.hooks`

807* Для non-tool hooks, которые поддерживают matchers, таких как `Notification` и `SubagentStop`, matchers соответствуют разным полям, и `Stop` полностью игнорирует matchers (см. [matcher patterns](/docs/ru/hooks#matcher-patterns))807* Для хуков, не связанных с инструментами, которые поддерживают matcher, таких как `Notification` и `SubagentStop`, matcher сопоставляется с другими полями, а `Stop` полностью игнорирует matcher (см. [паттерны matcher](/docs/ru/hooks#matcher-patterns))

808* Hooks могут не срабатывать, когда агент достигает лимита [`max_turns`](/docs/ru/agent-sdk/python#claudeagentoptions), потому что сеанс заканчивается перед тем, как hooks смогут выполниться808* Хуки могут не срабатывать, когда агент достигает лимита [`max_turns`](/docs/ru/agent-sdk/python#claudeagentoptions), потому что сессия заканчивается до того, как хуки смогут выполниться

809 809

810<h3 id="matcher-not-filtering-as-expected">810<h3 id="matcher-not-filtering-as-expected">

811 Matcher не фильтрует как ожидается811 Matcher не фильтрует как ожидается

812</h3>812</h3>

813 813

814Matchers соответствуют только имени инструмента, а не путям файлов или другим аргументам. Для фильтрации по пути файла проверьте `tool_input.file_path` внутри вашего hook:814Matcher сопоставляется только с именами инструментов, а не с путями файлов или другими аргументами. Для фильтрации по пути файла проверьте `tool_input.file_path` внутри вашего хука:

815 815

816```typescript theme={null}816```typescript theme={null}

817const myHook: HookCallback = async (input, toolUseID, { signal }) => {817const myHook: HookCallback = async (input, toolUseID, { signal }) => {

825```825```

826 826

827<h3 id="hook-timeout">827<h3 id="hook-timeout">

828 Hook timeout828 Таймаут хука

829</h3>829</h3>

830 830

831Claude Code запускает каждый callback с timeout, который вы устанавливаете в секундах с помощью поля `timeout` на его `HookMatcher`. Когда вы не устанавливаете его, Claude Code использует значение по умолчанию для события: 600 секунд для большинства событий, 30 секунд для `UserPromptSubmit`, `PreModelSwitch` и `PostModelSwitch`, и 10 секунд для `MessageDisplay`. Claude Code запускает callbacks `SessionEnd` во время завершения работы под более коротким [бюджетом timeout SessionEnd](/docs/ru/hooks#sessionend-input), 1,5 секунды по умолчанию.831Claude Code запускает каждый callback с таймаутом, который вы устанавливаете в секундах с помощью поля `timeout` в его `HookMatcher`. Если вы его не устанавливаете, Claude Code использует значение по умолчанию для события: 600 секунд для большинства событий, 30 секунд для `UserPromptSubmit`, `PreModelSwitch` и `PostModelSwitch` и 10 секунд для `MessageDisplay`. Claude Code запускает callbacks `SessionEnd` во время завершения работы в рамках более короткого [бюджета таймаута SessionEnd](/docs/ru/hooks#sessionend-input), по умолчанию 1,5 секунды.

832 832

833Когда callback превышает свой timeout, Claude Code отменяет его и отбрасывает его выходные данные, и сеанс продолжается, а не зависает. Что происходит дальше, зависит от события:833Когда callback превышает свой таймаут, Claude Code отменяет его и отбрасывает его выходные данные, и сессия продолжается, а не зависает. Что происходит дальше, зависит от события:

834 834

835* `PreToolUse`: Claude Code не запускает вызов инструмента, Claude получает результат инструмента, указывающий, что hook не ответил до истечения timeout, и ход продолжается. Если другой hook `PreToolUse` вернул явный отказ, Claude получает этот отказ вместо ошибки timeout. До версии 2.1.210 Claude Code сообщал timeout Claude как отклонение пользователем, что заставляло автоматические сеансы остановиться и ждать ввода.835* `PreToolUse`: Claude Code не выполняет вызов инструмента, Claude получает результат инструмента, указывающий, что хук не ответил до истечения таймаута, и ход продолжается. Если другой хук `PreToolUse` вернул явный отказ, Claude получает этот отказ вместо ошибки таймаута. До версии 2.1.210 Claude Code сообщал Claude о таймауте как об отклонении пользователем, из-за чего автоматические сессии останавливались и ждали ввода.

836* `PostToolUse` и `PostToolUseFailure`: Claude Code сохраняет результат инструмента и ход продолжается.836* `PostToolUse` и `PostToolUseFailure`: Claude Code сохраняет результат инструмента, и ход продолжается.

837* `UserPromptSubmit` и [`UserPromptExpansion`](/docs/ru/hooks#userpromptexpansion): Claude Code блокирует запрос с сообщением, указывающим hook и timeout, и сеанс продолжается. Поскольку callback на этих событиях может действовать как политический шлюз, Claude Code никогда не пропускает истекший по времени запрос без проверки. До версии 2.1.208 Claude Code завершал запрос с `error_during_execution`, когда callback на этих событиях истекал по времени.837* `UserPromptSubmit` и [`UserPromptExpansion`](/docs/ru/hooks#userpromptexpansion): Claude Code блокирует промпт с сообщением, указывающим хук и таймаут, и сессия продолжается. Поскольку callback на этих событиях может действовать как шлюз политики, Claude Code никогда не пропускает промпт с истекшим таймаутом без проверки. До версии 2.1.208 Claude Code завершал запрос с `error_during_execution`, когда у callback на этих событиях истекал таймаут.

838* `Stop` и `SubagentStop`: истекший по времени callback считается возвращающим отсутствие решения. Агент или подагент останавливается так, как если бы этот callback разрешил это, и решение из ваших других hooks на событие все еще применяется. До Claude Code версии 2.1.273 истекший по времени callback `Stop` или `SubagentStop` считался неудачным запуском hook, и Claude Code отбрасывал решения ваших других hooks на событие.838* `Stop` и `SubagentStop`: callback с истекшим таймаутом считается не вернувшим решения. Агент или субагент останавливается так, как если бы этот callback это разрешил, а решение ваших других хуков на этом событии по-прежнему применяется. До Claude Code версии 2.1.273 callback `Stop` или `SubagentStop` с истекшим таймаутом считался неудачным запуском хука, и Claude Code отбрасывал решения ваших других хуков на этом событии.

839* `SessionStart`: истекший по времени callback считается возвращающим отсутствие выходных данных, и сеанс продолжается с выходными данными ваших других hooks `SessionStart`.839* `SessionStart`: callback с истекшим таймаутом считается не вернувшим выходных данных, и сессия продолжается с выходными данными ваших других хуков `SessionStart`.

840* `PreModelSwitch`: Claude Code блокирует переключение модели. Hook, который не отвечает, не одобрил переключение.840* `PreModelSwitch`: Claude Code блокирует переключение модели. Хук, который не отвечает, не одобрил переключение.

841* Другие события, такие как `Notification`, `PreCompact` и `PostModelSwitch`: Claude Code логирует сбой и продолжает.841* Другие события, такие как `Notification`, `PreCompact` и `PostModelSwitch`: Claude Code записывает сбой в лог и продолжает работу.

842 842

843Первый раз, когда callback `Stop` или `SessionStart` истекает по времени в основном сеансе, Claude Code также добавляет [`SDKInformationalMessage`](/docs/ru/agent-sdk/typescript#sdkinformationalmessage) в поток сообщений, говоря, что приложение, управляющее сеансом, не ответило. Более поздние timeout не повторяют это сообщение, пока ваше приложение остается неответчивым.843Когда у callback `Stop` или `SessionStart` впервые истекает таймаут в основной сессии, Claude Code также добавляет в поток сообщений [`SDKInformationalMessage`](/docs/ru/agent-sdk/typescript#sdkinformationalmessage) о том, что приложение, управляющее сессией, не ответило. Последующие таймауты не повторяют это сообщение, пока ваше приложение остается неотвечающим.

844 844

845Если вы прерываете запрос во время ожидания callback, Claude Code отменяет ожидающий вызов инструмента. До версии 2.1.208 вызов инструмента мог все еще продолжиться, если вы прервали во время ожидания callback `PreToolUse`.845Если вы прерываете запрос во время ожидания callback, Claude Code отменяет ожидающий вызов инструмента. До версии 2.1.208 вызов инструмента мог все же выполниться, если вы прерывали запрос во время ожидания callback `PreToolUse`.

846 846

847Если вашему callback нужно больше времени, установите более высокий `timeout` на его `HookMatcher`. В TypeScript используйте `AbortSignal` из третьего аргумента callback для корректной обработки отмены, когда истекает timeout.847Если вашему callback нужно больше времени, установите более высокий `timeout` в его `HookMatcher`. В TypeScript используйте `AbortSignal` из третьего аргумента callback для корректной обработки отмены при срабатывании таймаута.

848 848

849<h3 id="tool-blocked-unexpectedly">849<h3 id="tool-blocked-unexpectedly">

850 Инструмент заблокирован неожиданно850 Инструмент заблокирован неожиданно

851</h3>851</h3>

852 852

853* Проверьте все hooks `PreToolUse` на возвращение `permissionDecision: 'deny'`853* Проверьте все хуки `PreToolUse` на возвращение `permissionDecision: 'deny'`

854* Добавьте логирование в ваши hooks, чтобы увидеть, какие `permissionDecisionReason` они возвращают854* Добавьте логирование в ваши хуки, чтобы увидеть, какие `permissionDecisionReason` они возвращают

855* Проверьте, что паттерны matcher не слишком широкие: пустой matcher соответствует всем инструментам855* Проверьте, что паттерны matcher не слишком широкие: пустой matcher соответствует всем инструментам

856 856

857<h3 id="modified-input-not-applied">857<h3 id="modified-input-not-applied">

858 Измененный входной сигнал не применяется858 Измененные входные данные не применяются

859</h3>859</h3>

860 860

861* Убедитесь, что `updatedInput` находится внутри `hookSpecificOutput`, а не на верхнем уровне:861* Убедитесь, что `updatedInput` находится внутри `hookSpecificOutput`, а не на верхнем уровне:

870 };870 };

871 ```871 ```

872 872

873* Не объединяйте `updatedInput` с `permissionDecision: 'defer'`, который отбрасывает измененный входной сигнал. Опущение `permissionDecision` допустимо: измененный входной сигнал все еще применяется через обычную оценку разрешений. Вы также можете вернуть `'allow'` для автоматического одобрения измененного входного сигнала или `'ask'` для отображения его пользователю на утверждение873* Не объединяйте `updatedInput` с `permissionDecision: 'defer'`, так как это отбрасывает измененные входные данные. Опускать `permissionDecision` допустимо: измененные входные данные все равно применяются через обычную оценку разрешений. Вы также можете вернуть `'allow'` для автоматического одобрения измененных входных данных или `'ask'`, чтобы показать их пользователю для подтверждения

874 874

875* Включите `hookEventName` в `hookSpecificOutput` для идентификации типа hook, для которого предназначен вывод875* Включите `hookEventName` в `hookSpecificOutput`, чтобы указать, к какому типу хука относится вывод

876 876

877<h3 id="session-hooks-not-available-in-python">877<h3 id="session-hooks-not-available-in-python">

878 Hooks сеанса недоступны в Python878 Хуки сессии недоступны в Python

879</h3>879</h3>

880 880

881`SessionStart` и `SessionEnd` могут быть зарегистрированы как SDK callback hooks в TypeScript, но недоступны в Python SDK, потому что его тип `HookEvent` их опускает. В Python они доступны только как [shell command hooks](/docs/ru/hooks#hook-events), определенные в файлах настроек, таких как `.claude/settings.json`. Для загрузки shell command hooks из вашего приложения SDK включите соответствующий источник настроек с [`setting_sources`](/docs/ru/agent-sdk/python#settingsource) или [`settingSources`](/docs/ru/agent-sdk/typescript#settingsource):881`SessionStart` и `SessionEnd` можно зарегистрировать как callback-хуки SDK в TypeScript, но они недоступны в Python SDK, потому что его тип `HookEvent` их не включает. В Python они доступны только как [хуки shell-команд](/docs/ru/hooks#hook-events), определенные в файлах настроек, таких как `.claude/settings.json`. То, какие файлы настроек загружает ваше приложение SDK, зависит от [`setting_sources`](/docs/ru/agent-sdk/python#settingsource) или [`settingSources`](/docs/ru/agent-sdk/typescript#settingsource). Если вы задаете этот параметр, включите источник, который содержит хуки:

882 882

883<CodeGroup>883<CodeGroup>

884 ```python Python theme={null}884 ```python Python theme={null}

894 ```894 ```

895</CodeGroup>895</CodeGroup>

896 896

897Для запуска логики инициализации как Python SDK callback вместо этого используйте первое сообщение из `client.receive_response()` как ваш триггер.897Чтобы вместо этого запускать логику инициализации как callback Python SDK, используйте первое сообщение из `client.receive_response()` в качестве триггера.

898 898

899<h3 id="subagent-permission-prompts-multiplying">899<h3 id="subagent-permission-prompts-multiplying">

900 Запросы разрешений подагента умножаются900 Запросы разрешений субагентов множатся

901</h3>901</h3>

902 902

903При порождении нескольких подагентов каждый может запросить разрешения отдельно для своих собственных вызовов инструментов. Чтобы избежать повторных запросов, используйте hooks `PreToolUse` для автоматического одобрения конкретных инструментов или настройте правила разрешений, которые подагенты [наследуют от родительского разговора](/docs/ru/sub-agents#permission-modes).903При порождении нескольких субагентов каждый из них может запрашивать разрешения отдельно для своих собственных вызовов инструментов. Чтобы избежать повторных запросов, используйте хуки `PreToolUse` для автоматического одобрения конкретных инструментов или настройте правила разрешений, которые субагенты [наследуют от родительского диалога](/docs/ru/sub-agents#permission-modes).

904 904

905<h3 id="recursive-hook-loops-with-subagents">905<h3 id="recursive-hook-loops-with-subagents">

906 Рекурсивные циклы hook с подагентами906 Рекурсивные циклы хуков с субагентами

907</h3>907</h3>

908 908

909Hook `UserPromptSubmit`, который порождает подагентов, может создать бесконечные циклы, если эти подагенты срабатывают тот же hook. Чтобы предотвратить это:909Хук `UserPromptSubmit`, который порождает субагентов, может создать бесконечные циклы, если эти субагенты вызывают срабатывание того же хука. Чтобы предотвратить это:

910 910

911* Используйте общую переменную или состояние сеанса для отслеживания, находитесь ли вы уже внутри подагента911* Используйте общую переменную или состояние сессии для отслеживания того, находитесь ли вы уже внутри субагента

912* Ограничьте область действия hooks, чтобы они запускались только для сеанса агента верхнего уровня912* Ограничьте хуки, чтобы они запускались только для сессии агента верхнего уровня

913 913

914<h3 id="systemmessage-not-appearing-in-output">914<h3 id="systemmessage-not-appearing-in-output">

915 systemMessage не появляется в выводе915 systemMessage не появляется в выводе

916</h3>916</h3>

917 917

918Поле `systemMessage` показывает сообщение пользователю, а не модели. На Claude Code версии 2.1.227 или позже, `systemMessage` hook может появиться в потоке сообщений как [`SDKInformationalMessage`](/docs/ru/agent-sdk/typescript#sdkinformationalmessage). Появляется ли оно, зависит от события. Каждый [раздел события](/docs/ru/hooks#hook-events) на странице hooks говорит, как выводится результат. Для передачи контекста модели вместо этого верните [`additionalContext`](/docs/ru/hooks#add-context-for-claude).918Поле `systemMessage` показывает сообщение пользователю, а не модели. В Claude Code версии 2.1.227 или новее `systemMessage` хука может появиться в потоке сообщений как [`SDKInformationalMessage`](/docs/ru/agent-sdk/typescript#sdkinformationalmessage). Появится ли оно, зависит от события. В [разделе каждого события](/docs/ru/hooks#hook-events) на странице хуков описано, как выводится результат. Чтобы вместо этого передать контекст модели, верните [`additionalContext`](/docs/ru/hooks#add-context-for-claude).

919 919

920До версии 2.1.227 SDK выводил выходные данные hook в поток сообщений только для hooks `SessionStart` и `Setup`. Для любого другого события выходные данные появлялись только в событиях жизненного цикла, которые добавляет [`includeHookEvents`](/docs/ru/agent-sdk/typescript#options) (`include_hook_events` в Python). Запись этого параметра охватывает, какие события жизненного цикла производит каждое событие hook.920До версии 2.1.227 SDK выводил выходные данные хука в поток сообщений только для хуков `SessionStart` и `Setup`. Для любого другого события выходные данные появлялись только в событиях жизненного цикла, которые добавляет [`includeHookEvents`](/docs/ru/agent-sdk/typescript#options) (`include_hook_events` в Python). В описании этого параметра указано, какие события жизненного цикла порождает каждое событие хука.

921 921

922Если вам нужно надежно вывести решения hook в ваше приложение, логируйте их отдельно или используйте выделенный канал вывода.922Если вам нужно надежно передавать решения хуков в ваше приложение, логируйте их отдельно или используйте выделенный канал вывода.

923 923

924<h2 id="related-resources">924<h2 id="related-resources">

925 Связанные ресурсы925 Связанные ресурсы

agent-sdk/python.md +7 −6

Details

194 `ToolAnnotations`194 `ToolAnnotations`

195</h4>195</h4>

196 196

197Подсказки поведения для инструмента, передаваемые как аргумент `annotations` функции [`tool()`](#tool). `ToolAnnotations` расширяет `mcp.types.ToolAnnotations` SDK MCP с полем `maxResultSizeChars`, и вы можете писать каждую подсказку в camelCase или snake\_case: `ToolAnnotations(readOnlyHint=True)` и `ToolAnnotations(read_only_hint=True)` эквивалентны. Вы также можете передать простой `mcp.types.ToolAnnotations` везде, где SDK принимает аннотации.197Подсказки поведения для инструмента, передаваемые как аргумент `annotations` функции [`tool()`](#tool). `ToolAnnotations` расширяет `mcp.types.ToolAnnotations` SDK MCP с полем `maxResultSizeChars`, и вы можете писать каждую подсказку в camelCase или snake\_case: `ToolAnnotations(readOnlyHint=True)` и `ToolAnnotations(read_only_hint=True)` эквивалентны. Чтобы прочитать подсказку обратно из объекта, используйте написание, объявленное в установленном у вас пакете `mcp`: `.readOnlyHint` в `mcp` 1.x и `.read_only_hint` в 2.x, тогда как `.maxResultSizeChars` работает в обоих. Вы также можете передать простой `mcp.types.ToolAnnotations` везде, где SDK принимает аннотации.

198 198

199Имена snake\_case и типизированное поле `maxResultSizeChars` требуют Python Agent SDK 0.2.140 или позже. Версии 0.1.31 по 0.2.139 переэкспортируют `mcp.types.ToolAnnotations` без изменений. В версиях 0.1.55 по 0.2.139 вы все еще можете передать `maxResultSizeChars` как аргумент ключевого слова: класс MCP принимает дополнительные поля, и SDK пересылает значение в Claude Code.199Имена snake\_case и типизированное поле `maxResultSizeChars` требуют Python Agent SDK 0.2.140 или позже. Версии 0.1.31 по 0.2.139 переэкспортируют `mcp.types.ToolAnnotations` без изменений. В версиях 0.1.55 по 0.2.139 вы все еще можете передать `maxResultSizeChars` как аргумент ключевого слова: класс MCP принимает дополнительные поля, и SDK пересылает значение в Claude Code.

200 200

1467 1467

1468Дополнительное поле `display` контролирует, возвращается ли текст thinking `"summarized"` или `"omitted"`. На Claude Opus 4.7 и позже, по умолчанию API — `"omitted"`, поэтому установите `"summarized"` для получения содержимого thinking в выходах [`ThinkingBlock`](#thinkingblock). Claude Code не отправляет `display` на Amazon Bedrock или Google Cloud's Agent Platform, поэтому на этих поставщиках Opus 4.7 и позже возвращают пустые выходы `ThinkingBlock` даже когда вы установили `display` на `"summarized"`.1468Необязательное поле `display` определяет, возвращается ли текст размышлений в виде `"summarized"` или `"omitted"`. В Claude Opus 4.7 и новее значение API по умолчанию — `"omitted"`, поэтому установите `"summarized"`, чтобы получать содержимое размышлений в выходных данных [`ThinkingBlock`](#thinkingblock). Claude Code не включает `display` в запросы к некоторым поставщикам, таким как Amazon Bedrock и Google Cloud's Agent Platform. У этих поставщиков Opus 4.7 и новее возвращают пустые выходные данные `ThinkingBlock`, даже если вы установили `display` в `"summarized"`.

1469 1469

1470Поскольку это классы `TypedDict`, они являются простыми dicts во время выполнения. Либо конструируйте их как dict-литералы, либо вызывайте класс как конструктор; оба создают `dict`. Получайте доступ к полям с `config["budget_tokens"]`, а не `config.budget_tokens`:1470Поскольку это классы `TypedDict`, они являются простыми dicts во время выполнения. Либо конструируйте их как dict-литералы, либо вызывайте класс как конструктор; оба создают `dict`. Получайте доступ к полям с `config["budget_tokens"]`, а не `config.budget_tokens`:

1471 1471

1875| `maxOutputTokens` | `int` | Максимальный лимит выходных токенов для этой модели. |1875| `maxOutputTokens` | `int` | Максимальный лимит выходных токенов для этой модели. |

1876| `canonicalModel` | `str` | Канонический ID модели, используемый для поиска цены. Может отличаться от необработанной строки модели, по которой индексируется запись, такой как ID или псевдоним, специфичный для поставщика. Не всегда присутствует. |1876| `canonicalModel` | `str` | Канонический ID модели, используемый для поиска цены. Может отличаться от необработанной строки модели, по которой индексируется запись, такой как ID или псевдоним, специфичный для поставщика. Не всегда присутствует. |

1877| `provider` | `str` | Поставщик API, который обслуживал эту модель, такой как `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle` или `gateway`. Не всегда присутствует. |1877| `provider` | `str` | Поставщик API, который обслуживал эту модель, такой как `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle` или `gateway`. Не всегда присутствует. |

1878| `costBasis` | `str` | Таблица цен, по которой была рассчитана стоимость последнего запроса этой модели: `list` для прейскурантной цены, `managed` для таблицы [`modelPricing`](/docs/ru/settings-reference#modelpricing) или `unknown`, если ни одна из них не соответствует ID модели. Не всегда присутствует и не объявлено в TypedDict, поэтому читайте его с помощью `.get()`. Требуется Claude Code v2.1.246 или позже. |

1878 1879

1879<h3 id="streamevent">1880<h3 id="streamevent">

1880 `StreamEvent`1881 `StreamEvent`

2166 """Base error for Claude SDK."""2167 """Base error for Claude SDK."""

2167```2168```

2168 2169

2169Когда одноразовый `query()` заканчивается результатом ошибки, например ошибкой превышения лимита ходов, SDK вызывает [`ResultError`](#resulterror) после выдачи финального сообщения результата. Версии Python Agent SDK до 0.2.140 вызывали простое `Exception`, которое не было подклассом `ClaudeSDKError`.2170Когда одноразовый `query()` заканчивается результатом ошибки, например ошибкой превышения лимита ходов, SDK вызывает [`ResultError`](#resulterror).

2170 2171

2171<h3 id="clinotfounderror">2172<h3 id="clinotfounderror">

2172 `CLINotFoundError`2173 `CLINotFoundError`

2216 `ResultError`2217 `ResultError`

2217</h3>2218</h3>

2218 2219

2219Вызывается после финального [`ResultMessage`](#resultmessage), когда процесс Claude Code завершается, потому что запуск закончился результатом ошибки, таким как ошибка превышения лимита ходов или ошибка API. `ResultError` является подклассом `ProcessError`, поэтому существующий обработчик `except ProcessError` также его перехватывает. Его атрибуты содержат поля этого сообщения результата, поэтому вы можете разветвляться в зависимости от причины сбоя запуска без анализа текста сообщения. Требуется Python Agent SDK версии 0.2.140 или позже.2220Вызывается, когда процесс Claude Code завершается, потому что запуск закончился [сообщением результата](#resultmessage) с ошибкой, таким как ошибка превышения лимита ходов или ошибка API. `ResultError` является подклассом `ProcessError`, поэтому существующий обработчик `except ProcessError` также его перехватывает. Его атрибуты содержат поля этого сообщения результата, поэтому вы можете разветвляться в зависимости от причины сбоя запуска без анализа текста сообщения. Требуется Python Agent SDK версии 0.2.140 или позже.

2220 2221

2221```python theme={null}2222```python theme={null}

2222class ResultError(ProcessError):2223class ResultError(ProcessError):

2649 hookEventName: Literal["PostToolUse"]2650 hookEventName: Literal["PostToolUse"]

2650 additionalContext: NotRequired[str]2651 additionalContext: NotRequired[str]

2651 updatedToolOutput: NotRequired[Any]2652 updatedToolOutput: NotRequired[Any]

2652 updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools2653 updatedMCPToolOutput: NotRequired[Any] # MCP tools only. Prefer updatedToolOutput, which works for all tools

2653 2654

2654 2655

2655class PostToolUseFailureHookSpecificOutput(TypedDict):2656class PostToolUseFailureHookSpecificOutput(TypedDict):

2767 Типы ввода/вывода инструментов2768 Типы ввода/вывода инструментов

2768</h2>2769</h2>

2769 2770

2770Документация схем ввода/вывода для всех встроенных инструментов Claude Code. Хотя Python SDK не экспортирует их как типы, они представляют структуру входов и выходов инструментов в сообщениях.2771Документация схем ввода/вывода для встроенных инструментов Claude Code. Хотя Python SDK не экспортирует их как типы, они представляют структуру входов и выходов инструментов в сообщениях.

2771 2772

2772Каждый показанный вывод — это значение, которое вы читаете из [`UserMessage.tool_use_result`](#usermessage) для этого инструмента. Названия ключей появляются точно так, как их выдает Claude Code. Ключ, аннотированный `| None` с комментарием "present when" или "optional", опускается, когда он не применяется.2773Каждый показанный вывод — это значение, которое вы читаете из [`UserMessage.tool_use_result`](#usermessage) для этого инструмента. Названия ключей появляются точно так, как их выдает Claude Code. Ключ, аннотированный `| None` с комментарием "present when" или "optional", опускается, когда он не применяется.

2773 2774

agent-sdk/structured-outputs.md +5 −5

Details

60 60

61Чтобы использовать структурированные выводы, определите [JSON Schema](https://json-schema.org/understanding-json-schema/about), описывающую форму данных, которые вы хотите, затем передайте его в `query()` через опцию `outputFormat` (TypeScript) или `output_format` (Python). Когда агент завершит работу, сообщение результата включает поле `structured_output` с валидированными данными, соответствующими вашей схеме.61Чтобы использовать структурированные выводы, определите [JSON Schema](https://json-schema.org/understanding-json-schema/about), описывающую форму данных, которые вы хотите, затем передайте его в `query()` через опцию `outputFormat` (TypeScript) или `output_format` (Python). Когда агент завершит работу, сообщение результата включает поле `structured_output` с валидированными данными, соответствующими вашей схеме.

62 62

63Пример ниже просит агента исследовать Anthropic и вернуть название компании, год основания и штаб-квартиру как структурированный вывод.63Прежде чем запускать примеры на этой странице, установите Claude Agent SDK, следуя руководству [быстрый старт](/docs/ru/agent-sdk/quickstart#setup). Пример ниже просит агента исследовать Anthropic и вернуть название компании, год основания и штаб-квартиру как структурированный вывод.

64 64

65<CodeGroup>65<CodeGroup>

66 ```typescript TypeScript theme={null}66 ```typescript TypeScript theme={null}

390 Обработка ошибок390 Обработка ошибок

391</h2>391</h2>

392 392

393Генерация структурированного вывода может не удаться, когда агент не может создать валидный JSON, соответствующий вашей схеме. Это обычно происходит, когда схема слишком сложна для задачи, сама задача неоднозначна или агент достигает лимита повторных попыток при попытке исправить ошибки валидации. Это также может произойти без каких-либо ошибок валидации: [откат модели](/docs/ru/model-config#automatic-model-fallback) может отменить уже завершённый вывод в середине потока, и если никакая повторная попытка его не заменит, выполнение завершится с той же ошибкой. Проверьте список `errors` в сообщении результата, чтобы различить две причины перед отладкой вашей схемы.393Генерация структурированного вывода может не удаться, когда агент не может создать валидный JSON, соответствующий вашей схеме. Это обычно происходит, когда схема слишком сложна для задачи, сама задача неоднозначна или агент достигает лимита повторных попыток при попытке исправить ошибки валидации. Это также может произойти без каких-либо ошибок валидации: [переключение на резервную модель](/docs/ru/model-config#automatic-model-fallback) может отменить уже завершённый вывод в середине потока, и если никакая повторная попытка его не заменит, выполнение завершится с той же ошибкой. Проверьте список `errors` в сообщении результата с ошибкой, чтобы различить две причины перед отладкой вашей схемы.

394 394

395Когда происходит ошибка, сообщение результата имеет `subtype`, указывающий, что пошло не так:395Когда происходит ошибка, сообщение результата имеет `subtype`, указывающий, что пошло не так:

396 396

397| Subtype | Значение |397| Subtype | Значение |

398| - | - |398| - | - |

400| `error_max_structured_output_retries` | Ни один валидный вывод не пережил несколько попыток (ошибки валидации или откат модели без успешной повторной попытки) |400| `error_max_structured_output_retries` | После нескольких попыток не осталось валидного вывода (ошибки валидации или отмена вывода при переключении на резервную модель без успешной повторной попытки) |

401 401

402Результат также может завершиться с subtype `success`, но без значения `structured_output`, например, когда выполнение завершается без того, чтобы агент создал структурированный вывод. Рассматривайте этот случай как ошибку. Запись по устранению неполадок [structured\_output is None but the result says success](/docs/ru/agent-sdk/troubleshooting#structured_output-is-none-but-the-result-says-success) охватывает этот случай. Пример ниже рассматривает результат как успешный только когда `subtype` равен `success` и `structured_output` присутствует, и обрабатывает все остальные результаты как ошибку:402Результат также может завершиться с subtype `success`, но без значения `structured_output`, например, когда выполнение завершается без того, чтобы агент создал структурированный вывод. Этот случай также рассматривайте как ошибку. Запись по устранению неполадок [structured\_output is None but the result says success](/docs/ru/agent-sdk/troubleshooting#structured_output-is-none-but-the-result-says-success) охватывает этот случай. Пример ниже рассматривает результат как успешный только когда `subtype` равен `success` и `structured_output` присутствует, и обрабатывает все остальные результаты как ошибку:

403 403

404<CodeGroup>404<CodeGroup>

405 ```typescript TypeScript theme={null}405 ```typescript TypeScript theme={null}

488 488

489* **Держите схемы сосредоточенными.** Глубоко вложенные схемы со многими обязательными полями сложнее удовлетворить. Начните с простого и добавляйте сложность по мере необходимости.489* **Держите схемы сосредоточенными.** Глубоко вложенные схемы со многими обязательными полями сложнее удовлетворить. Начните с простого и добавляйте сложность по мере необходимости.

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

491* **Используйте четкие приглашения.** Неоднозначные приглашения затрудняют для агента понимание того, какой вывод создавать.491* **Используйте четкие промпты.** Неоднозначные промпты затрудняют для агента понимание того, какой вывод создавать.

492 492

493<h2 id="related-resources">493<h2 id="related-resources">

494 Связанные ресурсы494 Связанные ресурсы

agent-sdk/typescript.md +13 −8

Details

186 console.error("Claim failed:", error.message);186 console.error("Claim failed:", error.message);

187});187});

188 188

189for await (const message of claimedQuery) {189try {

190 for await (const message of claimedQuery) {

190 console.log(message);191 console.log(message);

192 }

193} catch (error) {

194 // После отклонённого требования затребованный запрос выбрасывает исключение, как только выдаст результат с ошибкой

195 console.error(`Session ended with an error: ${error}`);

191}196}

192```197```

193 198

567| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Тайм-аут в миллисекундах для каждого вызова `sessionStore.load()` и `sessionStore.listSubkeys()` во время материализации возобновления. Если адаптер не разрешится в этом окне, запрос не удается вместо зависания. Игнорируется, когда `sessionStore` не установлен |572| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Тайм-аут в миллисекундах для каждого вызова `sessionStore.load()` и `sessionStore.listSubkeys()` во время материализации возобновления. Если адаптер не разрешится в этом окне, запрос не удается вместо зависания. Игнорируется, когда `sessionStore` не установлен |

568| `managedSettings` | `Settings` | `undefined` | Параметры уровня политики, которые ваш хост-процесс предоставляет порожденному сеансу. На машинах с развернутыми администратором управляемыми параметрами Claude Code игнорирует их, если только источник управляемых параметров администратора с наивысшим приоритетом не установит `parentSettingsBehavior: 'merge'`, и никогда не объединяет их, пока [`policyHelper`](/docs/ru/settings-reference#policyhelper) предоставляет управляемые параметры. Объединенные значения проходят через фильтр только для ограничений; [Ограничить параметры родителя](/docs/ru/claude-apps-gateway#restrict-parent-settings) охватывает то, что допускает фильтр и блокировки `allowManaged*Only`. Хост, который устанавливает [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ru/env-vars), имеет три ключа, прочитанные прямо из этого полезного груза: его [конфигурация модели](/docs/ru/model-config#restrict-model-selection) на Claude Code v2.1.222 или позже, [`modelPricing`](/docs/ru/settings-reference#modelpricing) когда ни один управляемый источник не устанавливает его на v2.1.246 или позже, и его запись `ENABLE_TOOL_SEARCH` env на v2.1.247 или позже |573| `managedSettings` | `Settings` | `undefined` | Параметры уровня политики, которые ваш хост-процесс предоставляет порожденному сеансу. На машинах с развернутыми администратором управляемыми параметрами Claude Code игнорирует их, если только источник управляемых параметров администратора с наивысшим приоритетом не установит `parentSettingsBehavior: 'merge'`, и никогда не объединяет их, пока [`policyHelper`](/docs/ru/settings-reference#policyhelper) предоставляет управляемые параметры. Объединенные значения проходят через фильтр только для ограничений; [Ограничить параметры родителя](/docs/ru/claude-apps-gateway#restrict-parent-settings) охватывает то, что допускает фильтр и блокировки `allowManaged*Only`. Хост, который устанавливает [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ru/env-vars), имеет три ключа, прочитанные прямо из этого полезного груза: его [конфигурация модели](/docs/ru/model-config#restrict-model-selection) на Claude Code v2.1.222 или позже, [`modelPricing`](/docs/ru/settings-reference#modelpricing) когда ни один управляемый источник не устанавливает его на v2.1.246 или позже, и его запись `ENABLE_TOOL_SEARCH` env на v2.1.247 или позже |

569| `maxBudgetUsd` | `number` | `undefined` | Остановить запрос, когда оценка стоимости на стороне клиента достигает этого значения в USD. Сравнивается с той же оценкой, что и `total_cost_usd`. Для предостережений точности и поведения сброса см. [Отслеживание стоимости и использования](/docs/ru/agent-sdk/cost-tracking) |574| `maxBudgetUsd` | `number` | `undefined` | Остановить запрос, когда оценка стоимости на стороне клиента достигает этого значения в USD. Учитывает только расходы самого вызова; итоги, восстановленные из возобновленного сеанса, не учитываются. Для предостережений точности и поведения сброса см. [Отслеживание стоимости и использования](/docs/ru/agent-sdk/cost-tracking) |

572| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Конфигурации MCP сервера |577| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Конфигурации MCP сервера |

718| `reconnectMcpServer(serverName)` | Переподключить MCP сервер по имени. Если имя также совпадает с записью в файле параметров, таком как `.mcp.json` или `~/.claude.json`, Claude Code переподключает сервер, который вы настроили через [`mcpServers`](#options) или `setMcpServers()`, а не запись файла параметров. Этот порядок разрешения требует Claude Code v2.1.257 или позже |723| `reconnectMcpServer(serverName)` | Переподключить MCP сервер по имени. Если имя также совпадает с записью в файле параметров, таком как `.mcp.json` или `~/.claude.json`, Claude Code переподключает сервер, который вы настроили через [`mcpServers`](#options) или `setMcpServers()`, а не запись файла параметров. Этот порядок разрешения требует Claude Code v2.1.257 или позже |

719| `toggleMcpServer(serverName, enabled)` | Включает или отключает MCP-сервер по имени с тем же разрешением имён, что и у `reconnectMcpServer()`. Отключение сервера разрывает соединение с ним и удаляет его инструменты. Необходимую версию Claude Code для каждого вида серверов см. в [`toggleMcpServer()`](#togglemcpserver) |724| `toggleMcpServer(serverName, enabled)` | Включает или отключает MCP-сервер по имени с тем же разрешением имён, что и у `reconnectMcpServer()`. Отключение сервера разрывает соединение с ним и удаляет его инструменты. Необходимую версию Claude Code для каждого вида серверов см. в [`toggleMcpServer()`](#togglemcpserver) |

720| `setMcpServers(servers)` | Динамически замените набор MCP серверов для этого сеанса. Разрешается с помощью [`McpSetServersResult`](#mcpsetserversresult), называющего, какие серверы были добавлены и удалены, и любые ошибки |725| `setMcpServers(servers)` | Заменяет MCP-серверы, которыми управляет этот метод: серверы, добавленные через него, и [внутрипроцессные SDK-серверы](#createsdkmcpserver). Возвращает [`McpSetServersResult`](#mcpsetserversresult) с указанием добавленных и удалённых серверов, а также ошибок; в том разделе указано, какие другие серверы остаются подключёнными |

721| `readMcpResource(serverName, uri)` | *Alpha.* Читает один MCP Apps `ui://` ресурс из подключенного MCP сервера, чтобы ваше приложение могло отобразить виджет инструмента. Разрешается с помощью [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Требует TypeScript Agent SDK v0.3.280 или позже |726| `readMcpResource(serverName, uri)` | *Alpha.* Читает один MCP Apps `ui://` ресурс из подключенного MCP сервера, чтобы ваше приложение могло отобразить виджет инструмента. Разрешается с помощью [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Требует TypeScript Agent SDK v0.3.280 или позже |

844 849

845`options.cwd` требуется. Заявка также может установить `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, наложение параметров флага в `settings`, `appendSystemPrompt`, `title`, `agents` и токены для каждого сеанса в `env`.850`options.cwd` требуется. Заявка также может установить `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, наложение параметров флага в `settings`, `appendSystemPrompt`, `title`, `agents` и токены для каждого сеанса в `env`.

846 851

847Claude Code может отказать в заявке, например, для папки, которая не существует, или той, чьи параметры проекта устанавливают `env`, `agent` или `model`. Когда `claimed` отклоняется с сообщением, которое начинается с `option_not_applied`, сеанс работает без `model` или `maxThinkingTokens`, которые вы запросили. После любого другого отказа ваша подсказка не запустилась, поэтому запустите сеанс с `query()` вместо этого.852Claude Code может отказать в занятии, например для несуществующей папки или папки, настройки проекта которой задают `env`, `agent` или `model`. После отказа промпт, уже отправленный `claim()`, получает результат с ошибкой, текст которого начинается с `not_claimed`, после чего возвращённый запрос выбрасывает исключение. Оберните цикл запроса в блок try, чтобы продолжить работу после исключения. Когда `claimed` отклоняется с сообщением, начинающимся с `option_not_applied`, сессия работает без запрошенных вами `model` или `maxThinkingTokens`. После любого другого отклонения ваш промпт не был выполнен, поэтому начните сессию через `query()`.

848 853

849<h3 id="sdkcontrolinitializeresponse">854<h3 id="sdkcontrolinitializeresponse">

850 `SDKControlInitializeResponse`855 `SDKControlInitializeResponse`

1337| `mcpServer` | `{ name: string; source: string }` | Для инструмента `mcp__*`, MCP сервер, который его обслуживает, и откуда определение этого сервера пришло, с полями [`McpServerProvenance`](#mcpserverprovenance). Отсутствует для других инструментов. Требует Agent SDK v0.3.274 или позже |1342| `mcpServer` | `{ name: string; source: string }` | Для инструмента `mcp__*`, MCP сервер, который его обслуживает, и откуда определение этого сервера пришло, с полями [`McpServerProvenance`](#mcpserverprovenance). Отсутствует для других инструментов. Требует Agent SDK v0.3.274 или позже |

1339| `defaultToNo` | `boolean` | Когда `true`, одиночный случайный нажатие клавиши не должно одобрить этот запрос: откройте вашу подсказку на его опции отклонения, не предварительно выбирайте одобрение и не предлагайте ярлык одобрения одной клавишей. Требует Agent SDK v0.3.268 или позже |1344| `defaultToNo` | `boolean` | Когда `true`, одиночный случайный нажатие клавиши не должно одобрить этот запрос: откройте вашу подсказку на его опции отклонения, не предварительно выбирайте одобрение и не предлагайте ярлык одобрения одной клавишей. Требует Agent SDK v0.3.268 или позже |

1340| `suppressAlwaysAllowRule` | `boolean` | Когда `true`, не предлагайте постоянный выбор всегда разрешить для этого запроса, потому что правило, которое он напишет, предоставляет больше, чем действие самого запроса. Требует Agent SDK v0.3.268 или позже |1345| `suppressAlwaysAllowRule` | `boolean` | Если `true`, не предлагайте для этого запроса постоянный вариант «всегда разрешать». Требуется Agent SDK v0.3.268 или новее |

1343| `requestId` | `string` | `request_id` оболочки `control_request`. `control_response`, которую ваше приложение отправляет вне SDK, такую как подписанный HTTP POST, должна повторить это значение, чтобы процесс Claude Code мог сопоставить ответ с запросом |1348| `requestId` | `string` | `request_id` оболочки `control_request`. `control_response`, которую ваше приложение отправляет вне SDK, такую как подписанный HTTP POST, должна повторить это значение, чтобы процесс Claude Code мог сопоставить ответ с запросом |

5459 | { type: "disabled" }; // Без расширенного мышления5464 | { type: "disabled" }; // Без расширенного мышления

5460```5465```

5461 5466

5462Необязательное поле `display` управляет тем, возвращается ли текст размышлений как `"summarized"` или `"omitted"`. На Claude Opus 4.7 и более поздних версиях значение API по умолчанию — `"omitted"`, поэтому установите `"summarized"`, чтобы получать содержимое размышлений в блоках `thinking`. Claude Code не отправляет `display` в Amazon Bedrock или Google Cloud's Agent Platform, поэтому у этих провайдеров Opus 4.7 и более поздние версии возвращают пустые блоки `thinking`, даже если вы установите `display` в `"summarized"`.5467Необязательное поле `display` управляет тем, возвращается ли текст размышлений как `"summarized"` или `"omitted"`. На Claude Opus 4.7 и более поздних версиях значение API по умолчанию — `"omitted"`, поэтому установите `"summarized"`, чтобы получать содержимое размышлений в блоках `thinking`. Claude Code не включает `display` в запросы к некоторым провайдерам, например Amazon Bedrock и Google Cloud's Agent Platform. У этих провайдеров Opus 4.7 и более поздние версии возвращают пустые блоки `thinking`, даже если вы установите `display` в `"summarized"`.

5463 5468

5464<h3 id="spawnedprocess">5469<h3 id="spawnedprocess">

5465 `SpawnedProcess`5470 `SpawnedProcess`

5530 5535

5531Когда вы вызываете `setMcpServers()`, Claude Code применяет следующие правила:5536Когда вы вызываете `setMcpServers()`, Claude Code применяет следующие правила:

5532 5537

5533* **Серверы, которые вызов не называет**: Claude Code оставляет серверы, предоставленные плагинами, работающими. Требует Agent SDK v0.3.210 или более поздней версии.5538* **Серверы, которые вызов не называет**: вне [облачной сессии](/docs/ru/claude-code-on-the-web) Claude Code отключает серверы, добавленные предыдущим вызовом `setMcpServers()`, и встроенные в процесс SDK-серверы, и перечисляет их в `removed`. Остальные серверы продолжают работать и не перечисляются в `removed`, в том числе stdio-, HTTP- и SSE-серверы из опции [`mcpServers`](#options), серверы из файлов настроек и серверы, предоставленные плагинами.

5534* **Серверы, которые вызов называет**: за исключением встроенных серверов, которые CLI запустил при старте, Claude Code заменяет работающий сервер, только если его конфигурация отличается от переданной вами.5539* **Серверы, которые вызов называет**: Claude Code заменяет stdio-, HTTP- или SSE-сервер, добавленный предыдущим вызовом `setMcpServers()`, только если его конфигурация отличается от переданной вами. Встроенный в процесс SDK-сервер, уже зарегистрированный под этим именем, остаётся без изменений, поэтому, чтобы заменить его, исключите его из одного вызова и добавьте в следующем.

5535* **Встроенные серверы, которые CLI запустил при старте**: если вызов называет такой сервер, Claude Code отбрасывает эту запись и сообщает о ней в `errors`.5540* **Встроенные серверы, которые CLI запустил при старте**: если вызов называет такой сервер, Claude Code отбрасывает эту запись и сообщает о ней в `errors`.

5536 5541

5537Промис разрешается после того, как вновь добавленные stdio-, HTTP- и SSE-серверы подключатся или не смогут подключиться, поэтому инструменты подключившихся серверов доступны на следующем ходу.5542Промис разрешается после того, как вновь добавленные stdio-, HTTP- и SSE-серверы подключатся или не смогут подключиться, поэтому инструменты подключившихся серверов доступны на следующем ходу.

agent-view.md +1 −0

Details

819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | Удалить сессию, удаление которой было отклонено из-за неотправленных коммитов, отбросив worktree вместе с его веткой и коммитами. Передайте точное значение, которое вывело отклонение; см. [Что удаляет удаление сессии](#what-deleting-a-session-removes). Требуется v2.1.260 или позже |819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | Удалить сессию, удаление которой было отклонено из-за неотправленных коммитов, отбросив worktree вместе с его веткой и коммитами. Передайте точное значение, которое вывело отклонение; см. [Что удаляет удаление сессии](#what-deleting-a-session-removes). Требуется v2.1.260 или позже |

820| `claude rm <id> --force-remove-worktree <worktree-id>` | Удалить сессию, удаление которой было отклонено, потому что git или хук `WorktreeRemove` не смогли удалить её worktree, удалив каталог worktree в любом случае и оставив его ветку в репозитории. Передайте точное значение, которое вывело отклонение; см. [Что удаляет удаление сессии](#what-deleting-a-session-removes). Требуется v2.1.268 или позже |820| `claude rm <id> --force-remove-worktree <worktree-id>` | Удалить сессию, удаление которой было отклонено, потому что git или хук `WorktreeRemove` не смогли удалить её worktree, удалив каталог worktree в любом случае и оставив его ветку в репозитории. Передайте точное значение, которое вывело отклонение; см. [Что удаляет удаление сессии](#what-deleting-a-session-removes). Требуется v2.1.268 или позже |

821| `claude daemon status` | Вывести состояние [supervisor](#the-supervisor-process), версию, каталог сокета и количество рабочих процессов |821| `claude daemon status` | Вывести состояние [supervisor](#the-supervisor-process), версию, каталог сокета и количество рабочих процессов |

822| `claude daemon logs` | Следить за файлом лога supervisor, [`~/.claude/daemon.log`](#where-state-is-stored), выводя новые строки по мере их появления, пока вы не нажмете `Ctrl+C` |

822| `claude daemon stop --any` | Остановить процесс supervisor и фоновые сессии, которые он размещает. Передайте `--keep-workers`, чтобы оставить фоновые сессии работающими, чтобы следующий supervisor переподключился к ним. Следующий `claude agents` или `claude --bg` запускает новый supervisor |823| `claude daemon stop --any` | Остановить процесс supervisor и фоновые сессии, которые он размещает. Передайте `--keep-workers`, чтобы оставить фоновые сессии работающими, чтобы следующий supervisor переподключился к ним. Следующий `claude agents` или `claude --bg` запускает новый supervisor |

823 824

824`claude attach` и `claude logs` могут принимать часть имени работающей сессии вместо ID, например `claude logs "auth refactor"`. Для передачи имени требуется Claude Code v2.1.290 или позже.825`claude attach` и `claude logs` могут принимать часть имени работающей сессии вместо ID, например `claude logs "auth refactor"`. Для передачи имени требуется Claude Code v2.1.290 или позже.

agents.md +1 −1

Details

20 20

21Три дополнительных инструмента поддерживают эту работу, не являясь способом запуска агентов:21Три дополнительных инструмента поддерживают эту работу, не являясь способом запуска агентов:

22 22

23* [Worktrees](/docs/ru/worktrees) дают каждому сеансу отдельный git checkout, поэтому параллельные сеансы никогда не редактируют одни и те же файлы. Используйте их для сеансов, которые вы запускаете сами. Сеанс, который вы отправляете из agent view, [переходит в свой собственный worktree перед редактированием файлов](/docs/ru/agent-view#how-file-edits-are-isolated), и подагенты, которых вы порождаете, могут получить свой собственный.23* [Worktrees](/docs/ru/worktrees) дают каждой сессии отдельный git checkout, поэтому параллельные сессии редактируют каждая свою копию файлов. Используйте их для сессий, которые вы запускаете сами. Сессия, которую вы отправляете из agent view, [переходит в свой собственный worktree перед редактированием файлов](/docs/ru/agent-view#how-file-edits-are-isolated), и субагенты, которых вы порождаете, тоже могут получить каждый свой.

24* [Cross-session messaging](/docs/ru/cross-session-messaging) позволяет Claude перечислять и отправлять сообщения вашим другим сеансам Claude Code на этой машине, на другой машине или [в облаке](/docs/ru/claude-code-on-the-web), поэтому сеансы, которые вы запускаете сами, могут передавать результаты и статус между собой.24* [Cross-session messaging](/docs/ru/cross-session-messaging) позволяет Claude перечислять и отправлять сообщения вашим другим сеансам Claude Code на этой машине, на другой машине или [в облаке](/docs/ru/claude-code-on-the-web), поэтому сеансы, которые вы запускаете сами, могут передавать результаты и статус между собой.

25* [`/batch`](/docs/ru/commands) — это [skill](/docs/ru/skills), который заставляет Claude разделить одно большое изменение на 5–30 worktree-изолированных подагентов. Это упакованное использование подагентов и worktrees, а не отдельный стиль координации.25* [`/batch`](/docs/ru/commands) — это [skill](/docs/ru/skills), который заставляет Claude разделить одно большое изменение на 5–30 worktree-изолированных подагентов. Это упакованное использование подагентов и worktrees, а не отдельный стиль координации.

26 26

amazon-bedrock.md +1 −1

Details

681 681

682Amazon Bedrock передает ответы `InvokeModelWithResponseStream` в двоичном формате event-stream с заголовком `Content-Type: application/vnd.amazon.eventstream`. Шлюз или прокси между Claude Code и Amazon Bedrock должны передавать тело ответа и его заголовки, включая `Content-Type`, так как их отправил Amazon Bedrock.682Amazon Bedrock передает ответы `InvokeModelWithResponseStream` в двоичном формате event-stream с заголовком `Content-Type: application/vnd.amazon.eventstream`. Шлюз или прокси между Claude Code и Amazon Bedrock должны передавать тело ответа и его заголовки, включая `Content-Type`, так как их отправил Amazon Bedrock.

683 683

684Если шлюз переписывает `Content-Type` на другое значение, Claude Code отклоняет ответ с ошибкой, которая начинается с `Bedrock streaming response has content-type`, указывая полученное значение. Обычная переписка — это `text/event-stream` из интеграции, которая повторно передает поток как события, отправляемые сервером.684Если шлюз переписывает `Content-Type` на другое значение, Claude Code отклоняет ответ с ошибкой, которая начинается с `Bedrock streaming response has content-type`, указывая полученное значение. Чаще всего значение переписывается на `text/event-stream` интеграцией, которая повторно передает поток как события, отправляемые сервером. О переменной `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD`, которую называет сообщение об ошибке, см. [Bedrock streaming response has an unexpected content-type](/docs/ru/errors#bedrock-streaming-response-has-an-unexpected-content-type).

685 685

686Если шлюз удаляет или очищает заголовок, Claude Code предполагает, что тело — это поток событий Amazon Bedrock и декодирует его, поэтому тело, которое шлюз передал без изменений, продолжает передаваться потоком.686Если шлюз удаляет или очищает заголовок, Claude Code предполагает, что тело — это поток событий Amazon Bedrock и декодирует его, поэтому тело, которое шлюз передал без изменений, продолжает передаваться потоком.

687 687

auto-mode-config.md +1 −1

Details

351}351}

352```352```

353 353

354Получите отзыв ИИ о ваших пользовательских правилах `allow`, `soft_deny` и `hard_deny`:354Получите отзыв ИИ о ваших пользовательских записях `allow`, `soft_deny`, `hard_deny` и `environment`:

355 355

356```bash theme={null}356```bash theme={null}

357claude auto-mode critique357claude auto-mode critique

chrome.md +1 −1

Details

343 343

345| - | - | - |345| - | - | - |

346| "Browser extension is not connected" | Хост собственного обмена сообщениями не может достичь расширения, или список разрешённых IP-адресов вашей организации отклоняет подключение к `bridge.claudeusercontent.com` | Перезагрузите Chrome и Claude Code, затем выполните `/chrome` для переподключения. Если ваша организация использует список разрешённых IP-адресов и ошибка сохраняется, см. [Списки разрешённых IP-адресов организации и исходящий трафик через прокси](/docs/ru/network-config#organization-ip-allowlists-and-proxy-egress) |346| "Browser extension is not connected" | Хост собственного обмена сообщениями не может достичь расширения, или список разрешённых IP-адресов вашей организации отклоняет подключение к `bridge.claudeusercontent.com` | Убедитесь, что в расширении выполнен вход в ту же учётную запись claude.ai, что и в Claude Code, перезагрузите Chrome и Claude Code, затем выполните `/chrome` для переподключения. Если ваша организация использует список разрешённых IP-адресов и ошибка сохраняется, см. [Списки разрешённых IP-адресов организации и исходящий трафик через прокси](/docs/ru/network-config#organization-ip-allowlists-and-proxy-egress) |

347| Расширение отображается как "Not detected" в `/chrome` | Расширение Chrome не установлено или отключено | Установите или включите расширение в `chrome://extensions` |347| Расширение отображается как "Not detected" в `/chrome` | Расширение Chrome не установлено или отключено | Установите или включите расширение в `chrome://extensions` |

claude-apps-gateway.md +2 −2

Details

75| - | - |75| - | - |

76| Claude Code v2.1.195 или позже | Подкоманда `claude gateway` и поток входа шлюза поставляются в v2.1.195. Более ранние общедоступные сборки их не включают. Как машина, запускающая сервер шлюза, так и машина каждого разработчика должны быть на v2.1.195 или позже; запустите `claude update`, чтобы получить последний выпуск. [Claude Platform on AWS upstream](/docs/ru/claude-apps-gateway-config#claude-platform-on-aws) требует Claude Code v2.1.198 или позже на сервере шлюза. |76| Claude Code v2.1.195 или позже | Подкоманда `claude gateway` и поток входа шлюза поставляются в v2.1.195. Более ранние общедоступные сборки их не включают. Как машина, запускающая сервер шлюза, так и машина каждого разработчика должны быть на v2.1.195 или позже; запустите `claude update`, чтобы получить последний выпуск. [Claude Platform on AWS upstream](/docs/ru/claude-apps-gateway-config#claude-platform-on-aws) требует Claude Code v2.1.198 или позже на сервере шлюза. |

77| Поставщик удостоверений OpenID Connect (OIDC) | Okta, Microsoft Entra ID, Google Workspace, Keycloak или Dex, или любой другой совместимый с OIDC IdP, такой как PingFederate. Шлюз запускает стандартное обнаружение OIDC и поток кода авторизации против него. SAML и LDAP не поддерживаются. |77| Поставщик удостоверений OpenID Connect (OIDC) | Okta, Microsoft Entra ID, Google Workspace, Keycloak или Dex, или любой другой совместимый с OIDC IdP, такой как PingFederate. Шлюз запускает стандартное обнаружение OIDC и поток кода авторизации против него. SAML и LDAP не поддерживаются. |

78| PostgreSQL 14 или позже | Поддерживает поток входа устройства, где обратный вызов браузера пишет, а опрашивающий CLI читает, плюс счётчики ограничения скорости. Любой управляемый Postgres работает, включая самый маленький уровень. Без настроенных ограничений расходов шлюз хранит несколько КБ краткосрочного состояния аутентификации; с [ограничениями расходов](/docs/ru/claude-apps-gateway-spend-limits) он также содержит долговечные таблицы расходов, аудита и идентификации, которые должны быть скопированы. TLS через `?sslmode=require` рекомендуется. |78| PostgreSQL 11 или позже | Обеспечивает работу потока входа устройства и счётчиков ограничения частоты запросов. Подойдёт управляемый сервис PostgreSQL, включая самый маленький уровень; см. [какие базы данных поддерживаются](/docs/ru/claude-apps-gateway-deploy#postgres). С [ограничениями расходов](/docs/ru/claude-apps-gateway-spend-limits) он также содержит долговечные таблицы расходов, аудита и идентификации, для которых следует создавать резервные копии. TLS через `?sslmode=require` рекомендуется. PostgreSQL 11, 12 и 13 требуют Claude Code v2.1.290 или позже на сервере шлюза. Проект PostgreSQL больше не поддерживает эти версии, поэтому по возможности используйте более новую. |

79| Вышестоящий уровень модели | Учётные данные Amazon Bedrock, учётные данные Claude Platform on AWS, учётные данные Google Cloud, ресурс Microsoft Foundry или ключ API Anthropic. Поддерживаются несколько вышестоящих уровней с отказоустойчивостью. |79| Вышестоящий уровень модели | Учётные данные Amazon Bedrock, учётные данные Claude Platform on AWS, учётные данные Google Cloud, ресурс Microsoft Foundry или ключ API Anthropic. Поддерживаются несколько вышестоящих уровней с отказоустойчивостью. |

80| HTTPS | Шлюз должен быть доступен по `https://` с ноутбуков разработчиков и из любого браузера, используемого для входа; шлюз служит страницей проверки устройства на том же слушателе. Либо предоставьте сертификат TLS через `listen.tls`, либо запустите позади завершающего TLS входа, и установите `listen.public_url` на внешнее происхождение в обоих случаях. При `/login` Claude Code принимает простое происхождение `http://` только когда хост шлюза является loopback: `localhost`, `127.0.0.1` или `::1`. |80| HTTPS | Шлюз должен быть доступен по `https://` с ноутбуков разработчиков и из любого браузера, используемого для входа; шлюз служит страницей проверки устройства на том же слушателе. Либо предоставьте сертификат TLS через `listen.tls`, либо запустите позади завершающего TLS входа, и установите `listen.public_url` на внешнее происхождение в обоих случаях. При `/login` Claude Code принимает простое происхождение `http://` только когда хост шлюза является loopback: `localhost`, `127.0.0.1` или `::1`. |

81| Адрес частной сети | При `/login` Claude Code требует, чтобы имя хоста или IP-адрес шлюза разрешались только в частные адреса: RFC 1918, link-local, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7` или loopback. Для шлюза, который вы размещаете, любой общедоступный адрес вне блока, который вы объявляете, отклоняется; см. [модель угроз](/docs/ru/claude-apps-gateway-deploy#threat-model-summary) в руководстве развёртывания. Если машины разработчиков маршрутизируют HTTPS через корпоративный прокси, вход также требует, чтобы хост прокси разрешался в частные адреса; если это не так, добавьте хост шлюза в `NO_PROXY`, чтобы CLI подключался напрямую. Если ваша внутренняя сеть пронумерована из общедоступного пространства IPv4, которым владеет ваша организация, [объявите эти блоки](#allow-a-gateway-on-public-address-space-you-own), чтобы `/login` принял шлюз там. |81| Адрес частной сети | При `/login` Claude Code требует, чтобы имя хоста или IP-адрес шлюза разрешались только в частные адреса: RFC 1918, link-local, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7` или loopback. Для шлюза, который вы размещаете, любой общедоступный адрес вне блока, который вы объявляете, отклоняется; см. [модель угроз](/docs/ru/claude-apps-gateway-deploy#threat-model-summary) в руководстве развёртывания. Если машины разработчиков маршрутизируют HTTPS через корпоративный прокси, вход также требует, чтобы хост прокси разрешался в частные адреса; если это не так, добавьте хост шлюза в `NO_PROXY`, чтобы CLI подключался напрямую. Если ваша внутренняя сеть пронумерована из общедоступного пространства IPv4, которым владеет ваша организация, [объявите эти блоки](#allow-a-gateway-on-public-address-space-you-own), чтобы `/login` принял шлюз там. |

91 </Step>91 </Step>

92 92

93 <Step title="Подготовьте базу данных PostgreSQL">93 <Step title="Подготовьте базу данных PostgreSQL">

94 Любой Postgres 14 или позже работает, включая самый маленький управляемый уровень. Шлюз запускает свои собственные миграции схемы при загрузке, поэтому пользователю базы данных нужны права для создания и изменения таблиц; см. [`store`](/docs/ru/claude-apps-gateway-config#store).94 Используйте PostgreSQL 11 или позже. Самого маленького управляемого уровня достаточно. Шлюз запускает свои собственные миграции схемы при загрузке, поэтому роли базы данных нужны права для создания и изменения таблиц; см. [`store`](/docs/ru/claude-apps-gateway-config#store).

95 </Step>95 </Step>

96 96

97 <Step title="Напишите gateway.yaml">97 <Step title="Напишите gateway.yaml">

claude-apps-gateway-config.md +3 −3

Details

158Шлюз читает ключ и сертификат один раз при загрузке, поэтому изменённый файл вступает в силу только после перезапуска. Выполняйте ротацию в таком порядке, чтобы ни один запрос токена не предъявлял сертификат, которого нет у IdP:158Шлюз читает ключ и сертификат один раз при загрузке, поэтому изменённый файл вступает в силу только после перезапуска. Выполняйте ротацию в таком порядке, чтобы ни один запрос токена не предъявлял сертификат, которого нет у IdP:

159 159

1601. Загрузите новый сертификат в IdP в дополнение к старому.1601. Загрузите новый сертификат в IdP в дополнение к старому.

1612. Замените файлы ключа и сертификата, которые загружает `gateway.yaml`, затем перезапустите шлюз.1612. Замените файлы ключа и сертификата, которые загружает `gateway.yaml`, затем перезапустите шлюз. Если вы запускаете несколько реплик, подойдёт [последовательный перезапуск](/docs/ru/claude-apps-gateway-deploy#upgrades), потому что у IdP есть оба сертификата, пока вы не удалите старый.

1623. Удалите старый сертификат из IdP.1623. После перезапуска всех реплик удалите старый сертификат из IdP.

163 163

164<h4 id="idp-requests-through-a-forward-proxy">164<h4 id="idp-requests-through-a-forward-proxy">

165 Запросы к IdP через прямой прокси165 Запросы к IdP через прямой прокси

227 227

229| - | - | - |229| - | - | - |

230| `postgres_url` | Да | URL `postgres://` или `postgresql://`. Обязателен: точке встречи грантов устройств, куда пишет обратный вызов браузера и откуда читает опрашивающий CLI, нужно состояние, общее для реплик. Шлюз сам выполняет миграции схемы при загрузке и при обновлении, поэтому роли нужны права на создание и изменение таблиц в целевой схеме. См. [Обновления](/docs/ru/claude-apps-gateway-deploy#upgrades) и [Postgres](/docs/ru/claude-apps-gateway-deploy#postgres). |230| `postgres_url` | Да | URL `postgres://` или `postgresql://` с одним хостом, а не списком хостов через запятую. Шлюз сам выполняет миграции схемы при загрузке и при обновлении, поэтому роли нужны права на создание и изменение таблиц в целевой схеме. См. [Обновления](/docs/ru/claude-apps-gateway-deploy#upgrades) и [Postgres](/docs/ru/claude-apps-gateway-deploy#postgres). |

231| `username` | Нет | Переопределяет пользователя в `postgres_url` |231| `username` | Нет | Переопределяет пользователя в `postgres_url` |

232| `password` | Нет | Учётные данные базы данных. Задавайте их здесь, а не в `postgres_url`, чтобы учётные данные не попадали в URL. Принимает любые символы и имеет приоритет над учётными данными из URL. |232| `password` | Нет | Учётные данные базы данных. Задавайте их здесь, а не в `postgres_url`, чтобы учётные данные не попадали в URL. Принимает любые символы и имеет приоритет над учётными данными из URL. |

233| `max_connections` | Нет | Размер пула соединений Postgres на реплику. По умолчанию `5` — консервативное значение, подходящее для общих баз данных. При включённых [лимитах расходов](#admin) горячий путь выполняет несколько операций на каждый запрос инференса, поэтому увеличьте значение для выделенной базы данных под нагрузкой и следите, чтобы число реплик × это значение было меньше `max_connections` базы данных. |233| `max_connections` | Нет | Размер пула соединений Postgres на реплику. По умолчанию `5` — консервативное значение, подходящее для общих баз данных. При включённых [лимитах расходов](#admin) горячий путь выполняет несколько операций на каждый запрос инференса, поэтому увеличьте значение для выделенной базы данных под нагрузкой и следите, чтобы число реплик × это значение было меньше `max_connections` базы данных. |

claude-apps-gateway-deploy.md +7 −1

Details

249 Postgres249 Postgres

250</h3>250</h3>

251 251

252Шлюз хранит своё состояние в базе данных PostgreSQL:

253

254* **База данных**: сам PostgreSQL, размещённый самостоятельно или управляемый, [минимальной версии](/docs/ru/claude-apps-gateway#prerequisites) или новее. Базы данных, которые лишь реализуют протокол Postgres, например распределённые SQL-базы данных, не поддерживаются.

255* **Адрес**: `store.postgres_url` принимает один хост. Если у базы данных несколько узлов, используйте адрес, стоящий перед ними, например эндпоинт вашего управляемого сервиса, балансировщик нагрузки или виртуальный IP. Установите [период благодати готовности](#readiness-grace-period) длиннее, чем занимает переключение при отказе.

256

252Шлюз содержит пять таблиц данных плюс таблицу `_migrations`, все созданные его миграциями при загрузке:257Шлюз содержит пять таблиц данных плюс таблицу `_migrations`, все созданные его миграциями при загрузке:

253 258

396| CLI `/login`: `Could not resolve the configured HTTP proxy` | Имя хоста в `HTTPS_PROXY` или `HTTP_PROXY` не разрешается с машины разработчика, обычно потому что она не подключена к корпоративной сети | Попросите разработчика подключиться к вашей сети или VPN и повторить попытку, или исправьте URL прокси |401| CLI `/login`: `Could not resolve the configured HTTP proxy` | Имя хоста в `HTTPS_PROXY` или `HTTP_PROXY` не разрешается с машины разработчика, обычно потому что она не подключена к корпоративной сети | Попросите разработчика подключиться к вашей сети или VPN и повторить попытку, или исправьте URL прокси |

397| CLI `/login`: `Could not resolve gateway host <host>` | Машина не может разрешить внутреннее DNS-имя шлюза, обычно потому что она не в корпоративной сети | Попросите разработчика подключиться к вашей сети или VPN, затем повторите попытку `/login` |402| CLI `/login`: `Could not resolve gateway host <host>` | Машина не может разрешить внутреннее DNS-имя шлюза, обычно потому что она не в корпоративной сети | Попросите разработчика подключиться к вашей сети или VPN, затем повторите попытку `/login` |

398| Загрузка выходит с ошибкой валидации конфигурации, называющей `store.postgres_url` | Postgres не настроен; шлюз требует Postgres | Установите `store.postgres_url`. Для локальной разработки используйте одноразовый контейнер: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |403| Загрузка выходит с ошибкой валидации конфигурации, называющей `store.postgres_url` | Postgres не настроен; шлюз требует Postgres | Установите `store.postgres_url`. Для локальной разработки используйте одноразовый контейнер: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |

404| Загрузка выходит: `store.postgres_url in <path> is not a URL the gateway can read` или, в версиях до v2.1.290, просто `Invalid URL` или `URI error` | URL не удаётся разобрать, например потому что в нём указано более одного хоста или пароль содержит незакодированные `/`, `?`, `#` или `%` | Укажите [один хост](#postgres) и перенесите пароль в [`store.password`](/docs/ru/claude-apps-gateway-config#store) |

399| Загрузка выходит: `requires the native binary` | Запуск под Node вместо нативного бинарного файла | Установите Claude Code одним из [методов автономной установки](/docs/ru/setup) |405| Загрузка выходит: `requires the native binary` | Запуск под Node вместо нативного бинарного файла | Установите Claude Code одним из [методов автономной установки](/docs/ru/setup) |

400| Загрузка выходит с ошибкой обнаружения OIDC после `config.load` | `oidc.issuer` недоступен или цепочке TLS нет доверия | Проверьте, что издатель доступен из pod и обслуживает `/.well-known/openid-configuration`. Установите `ca_cert_pem` для приватной PKI. Если pod достигает IdP только через forward proxy, установите [`oidc.use_proxy: true`](/docs/ru/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); на версиях до v2.1.227 вместо этого предоставьте pod прямой маршрут к каждому эндпоинту IdP. Если pod также не может разрешить имя хоста IdP или прокси отказывает в `CONNECT` на IP-адрес, см. [Proxy-only egress](/docs/ru/claude-apps-gateway-config#proxy-only-egress), что требует v2.1.277 или позже. |406| Загрузка выходит с ошибкой обнаружения OIDC после `config.load` | `oidc.issuer` недоступен или цепочке TLS нет доверия | Проверьте, что издатель доступен из pod и обслуживает `/.well-known/openid-configuration`. Установите `ca_cert_pem` для приватной PKI. Если pod достигает IdP только через forward proxy, установите [`oidc.use_proxy: true`](/docs/ru/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); на версиях до v2.1.227 вместо этого предоставьте pod прямой маршрут к каждому эндпоинту IdP. Если pod также не может разрешить имя хоста IdP или прокси отказывает в `CONNECT` на IP-адрес, см. [Proxy-only egress](/docs/ru/claude-apps-gateway-config#proxy-only-egress), что требует v2.1.277 или позже. |

401| Загрузка выходит с ошибкой прав доступа Postgres | Роль базы данных не имеет прав DDL на своей схеме | Предоставьте роли `CREATE` на схему шлюза, чтобы она могла создавать и изменять свои таблицы при загрузке |407| Загрузка выходит с ошибкой прав доступа Postgres | Роль базы данных не имеет прав DDL на своей схеме | Предоставьте роли `CREATE` на схему шлюза, чтобы она могла создавать и изменять свои таблицы при загрузке |

402| Лог: `could not connect to Postgres at boot, attempt 1 of 3` | База данных ещё не была доступна, когда шлюз запустился, например на холодном экземпляре, чья сеть всё ещё поднимается | Если шлюз затем завершает загрузку, никаких действий не требуется. Когда база данных недоступна, шлюз пытается подключиться три раза, с интервалом в две секунды, перед выходом. Если он выходит с `could not connect to Postgres`, проверьте `store.postgres_url` и сетевой путь к базе данных. Если попытки завершаются по таймауту, а не отклоняются, поднимите [`store.connect_timeout_seconds`](/docs/ru/claude-apps-gateway-config#store), чтобы дать каждой больше времени. |408| Лог: `could not connect to Postgres at boot, attempt 1 of 3` | База данных ещё не была доступна, когда шлюз запустился, например на холодном экземпляре, чья сеть всё ещё поднимается | Если шлюз затем завершает загрузку, никаких действий не требуется. Когда база данных недоступна, шлюз пытается подключиться три раза, с интервалом в две секунды, перед выходом. Если он выходит с `could not connect to Postgres`, проверьте `store.postgres_url`, в том числе что в нём указан один хост, и сетевой путь к базе данных. Если попытки завершаются по таймауту, а не отклоняются, поднимите [`store.connect_timeout_seconds`](/docs/ru/claude-apps-gateway-config#store), чтобы дать каждой больше времени. |

403| `/oauth/callback` показывает "Sign-in could not be completed" | Домен email отклонён, валидация id\_token не удалась или `email_verified` явно `false`, что шлюз всегда отклоняет без возможности переопределения | Проверьте `allowed_email_domains` и что IdP возвращает проверенное утверждение `email`. Для `email_verified: false` исправьте проверку на стороне IdP. Если ваш IdP выдаёт email под другим именем утверждения, установите `oidc.email_claim`. |409| `/oauth/callback` показывает "Sign-in could not be completed" | Домен email отклонён, валидация id\_token не удалась или `email_verified` явно `false`, что шлюз всегда отклоняет без возможности переопределения | Проверьте `allowed_email_domains` и что IdP возвращает проверенное утверждение `email`. Для `email_verified: false` исправьте проверку на стороне IdP. Если ваш IdP выдаёт email под другим именем утверждения, установите `oidc.email_claim`. |

404| Лог: `token exchange failed request_id=<id>: id_token missing email claim` | IdP не включает `email` в id\_token по умолчанию. Это отклонение срабатывает только когда установлен `allowed_email_domains`; без него отсутствующий email создаёт сессию без email | Настройте IdP для выдачи `email` в id\_token. Okta: добавьте `email` к утверждениям ID-токена пользовательского сервера авторизации. Entra: добавьте `email` как опциональное утверждение в регистрации приложения. PingFederate: включите политику OpenID Connect, которая выдаёт `email`. Если IdP обслуживает `email` из эндпоинта userinfo, но не включает его в id\_token, как, например, сервер авторизации организации Okta, установите `oidc.userinfo_fallback: true`. |410| Лог: `token exchange failed request_id=<id>: id_token missing email claim` | IdP не включает `email` в id\_token по умолчанию. Это отклонение срабатывает только когда установлен `allowed_email_domains`; без него отсутствующий email создаёт сессию без email | Настройте IdP для выдачи `email` в id\_token. Okta: добавьте `email` к утверждениям ID-токена пользовательского сервера авторизации. Entra: добавьте `email` как опциональное утверждение в регистрации приложения. PingFederate: включите политику OpenID Connect, которая выдаёт `email`. Если IdP обслуживает `email` из эндпоинта userinfo, но не включает его в id\_token, как, например, сервер авторизации организации Okta, установите `oidc.userinfo_fallback: true`. |

405| Лог: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, и разработчики видят `Cloud gateway session expired` каждые `session.ttl_hours` | IdP принял refresh token, но не вернул вместе с ним id\_token, поэтому шлюз запросил утверждения пользователя у эндпоинта userinfo IdP. IdP отклонил там обновлённый access token. Шлюз отвечает `temporarily_unavailable`, поэтому Claude Code сохраняет refresh token, но не может обновить сессию. Версии шлюза до v2.1.260 логируют ту же строку без деталей `(at …)`. | Установите [`oidc.scope_on_refresh: true`](/docs/ru/claude-apps-gateway-config#oidc), доступно в шлюзе v2.1.260 или позже, чтобы запрос refresh снова запрашивал `openid`. Некоторые IdP, такие как Okta, возвращают id\_token при refresh только при явном запросе. На PingFederate вместо этого включите **Return ID Token On Refresh Grant** в разделе **Applications > OAuth > OpenID Connect Policy Management**. Ключ не изменяет поведение PingFederate. Для других IdP, которые всё ещё его опускают, проверьте, принимает ли эндпоинт userinfo access tokens, выданные при refresh. В качестве временного решения поднимите [`session.ttl_hours`](/docs/ru/claude-apps-gateway-config#session). См. [Identity provider setup](#identity-provider-setup) о компромиссе при deprovisioning. |411| Лог: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, и разработчики видят `Cloud gateway session expired` каждые `session.ttl_hours` | IdP принял refresh token, но не вернул вместе с ним id\_token, поэтому шлюз запросил утверждения пользователя у эндпоинта userinfo IdP. IdP отклонил там обновлённый access token. Шлюз отвечает `temporarily_unavailable`, поэтому Claude Code сохраняет refresh token, но не может обновить сессию. Версии шлюза до v2.1.260 логируют ту же строку без деталей `(at …)`. | Установите [`oidc.scope_on_refresh: true`](/docs/ru/claude-apps-gateway-config#oidc), доступно в шлюзе v2.1.260 или позже, чтобы запрос refresh снова запрашивал `openid`. Некоторые IdP, такие как Okta, возвращают id\_token при refresh только при явном запросе. На PingFederate вместо этого включите **Return ID Token On Refresh Grant** в разделе **Applications > OAuth > OpenID Connect Policy Management**. Ключ не изменяет поведение PingFederate. Для других IdP, которые всё ещё его опускают, проверьте, принимает ли эндпоинт userinfo access tokens, выданные при refresh. В качестве временного решения поднимите [`session.ttl_hours`](/docs/ru/claude-apps-gateway-config#session). См. [Identity provider setup](#identity-provider-setup) о компромиссе при deprovisioning. |

claude-apps-gateway-on-aws.md +25 −23

Details

161 --policy-name read-gateway-secrets --policy-document file://secrets-read.json161 --policy-name read-gateway-secrets --policy-document file://secrets-read.json

162 ```162 ```

163 163

164 Политика называет один ARN на секрет, а не простой подстановочный знак `gateway-*`, который в общей учётной записи также совпадал бы с несвязанными секретами; конечный `-??????` совпадает ровно с случайным суффиксом из шести символов, который Secrets Manager добавляет к ARN каждого секрета. Конечный `-*` был бы простым глобусом префикса и также совпадал бы с более длинными именами, такими как `gateway-postgres-url-prod`.164 Политика называет один ARN на секрет, а не простой подстановочный знак `gateway-*`, который в общей учётной записи также совпадал бы с несвязанными секретами; конечный `-??????` совпадает ровно с случайным суффиксом из шести символов, который Secrets Manager добавляет к ARN каждого секрета. Конечный `-*` был бы простым глобом префикса и также совпадал бы с более длинными именами, такими как `gateway-postgres-url-prod`.

165 165

166 Политика IAM предоставляет gateway разрешение на вызов Bedrock, и Bedrock включает доступ к модели по умолчанию в коммерческих регионах. Оставшиеся ворота на уровне учётной записи — это одноразовая форма использования Anthropic: если никто в вашей учётной записи её не отправил, откройте [консоль Amazon Bedrock](https://console.aws.amazon.com/bedrock/), выберите модель Anthropic из каталога моделей и заполните форму. Доступ предоставляется сразу после отправки; см. [Claude Code на Amazon Bedrock](/docs/ru/amazon-bedrock#1-submit-use-case-details) для формы AWS Organizations и разрешений IAM, которые нужны отправителю.166 Политика IAM предоставляет gateway разрешение на вызов Bedrock, и Bedrock включает доступ к модели по умолчанию в коммерческих регионах. Оставшиеся ворота на уровне учётной записи — это одноразовая форма использования Anthropic: если никто в вашей учётной записи её не отправил, откройте [консоль Amazon Bedrock](https://console.aws.amazon.com/bedrock/), выберите модель Anthropic из каталога моделей и заполните форму. Доступ предоставляется сразу после отправки; см. [Claude Code на Amazon Bedrock](/docs/ru/amazon-bedrock#1-submit-use-case-details) для формы AWS Organizations и разрешений IAM, которые нужны отправителю.

167 167

169 </Step>169 </Step>

170 170

171 <Step title="Подготовьте Amazon RDS для PostgreSQL">171 <Step title="Подготовьте Amazon RDS для PostgreSQL">

172 Экземпляр работает в приватных подсетях без публичного адреса и с включённым шифрованием хранилища. Версия движка закреплена на Postgres 16, что удовлетворяет поддерживаемому минимуму gateway PostgreSQL 14 и гарантирует, что семейство группы параметров ниже совпадает с экземпляром.172 Экземпляр работает на Postgres 16 в приватных подсетях без публичного адреса и с включённым шифрованием хранилища.

173 173

174 Сначала создайте группу подсетей, которая размещает базу данных в приватных подсетях, и группу параметров с `rds.force_ssl=1`, чтобы сервер отклонял открытые соединения. Версия движка закреплена один раз, потому что семейство группы параметров должно совпадать с основной версией движка, которую запускает экземпляр:174 Сначала создайте группу подсетей, которая размещает базу данных в приватных подсетях, и группу параметров с `rds.force_ssl=1`, чтобы сервер отклонял открытые соединения. Версия движка закреплена один раз, потому что семейство группы параметров должно совпадать с основной версией движка, которую запускает экземпляр:

175 175

203 203

204 Буквальный аргумент `--master-user-password` виден в таблице процессов и в журналах аудита/EDR во время выполнения команды, то же самое воздействие, которое охватывает примечание шага секретов. На общем или контролируемом хосте передайте пароль через `--cli-input-json` из файла `0600` вместо этого, так же как это делает `setup.sh` пакета.204 Буквальный аргумент `--master-user-password` виден в таблице процессов и в журналах аудита/EDR во время выполнения команды, то же самое воздействие, которое охватывает примечание шага секретов. На общем или контролируемом хосте передайте пароль через `--cli-input-json` из файла `0600` вместо этого, так же как это делает `setup.sh` пакета.

205 205

206 Дождитесь, пока экземпляр запустится, что может занять несколько минут, затем прочитайте его приватную конечную точку и соберите строку подключения, которую будет использовать gateway:206 Дождитесь, пока экземпляр запустится, что может занять несколько минут, затем прочитайте его приватный эндпоинт и соберите строку подключения, которую будет использовать gateway:

207 207

208 ```bash theme={null}208 ```bash theme={null}

209 aws rds wait db-instance-available --db-instance-identifier claude-gateway-db209 aws rds wait db-instance-available --db-instance-identifier claude-gateway-db

214 214

215 `sslmode=verify-full` заставляет gateway проверять цепь сертификата сервера RDS и имя хоста, а не только шифровать. Якорь доверия — это [пакет сертификатов AWS RDS](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem), который шаг сборки образа ниже копирует в `/etc/claude/rds-global-bundle.pem` и доверяет через `NODE_EXTRA_CA_CERTS`. Не добавляйте параметр `sslrootcert=` в стиле libpq к URL: драйвер gateway читает только `sslmode` из строки запроса и передал бы `sslrootcert` Postgres как параметр запуска, который сервер отклоняет.215 `sslmode=verify-full` заставляет gateway проверять цепь сертификата сервера RDS и имя хоста, а не только шифровать. Якорь доверия — это [пакет сертификатов AWS RDS](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem), который шаг сборки образа ниже копирует в `/etc/claude/rds-global-bundle.pem` и доверяет через `NODE_EXTRA_CA_CERTS`. Не добавляйте параметр `sslrootcert=` в стиле libpq к URL: драйвер gateway читает только `sslmode` из строки запроса и передал бы `sslrootcert` Postgres как параметр запуска, который сервер отклоняет.

216 216

217 Сервис ECS или поды EKS должны работать в этом VPC, чтобы они могли достичь приватной конечной точки экземпляра, и группа безопасности `claude-gateway-db` допускает только группу безопасности gateway.217 Сервис ECS или поды EKS должны работать в этом VPC, чтобы они могли достичь приватного эндпоинта экземпляра, и группа безопасности `claude-gateway-db` допускает только группу безопасности gateway.

218 </Step>218 </Step>

219 219

220 <Step title="Напишите gateway.yaml">220 <Step title="Напишите gateway.yaml">

223 Два поля `listen` описывают, что находится перед gateway:223 Два поля `listen` описывают, что находится перед gateway:

224 224

225 * `public_url`: внешний источник `https://`, требуется для любого привязывания, отличного от loopback; см. [справочник `listen`](/docs/ru/claude-apps-gateway-config#listen). Gateway строит `redirect_uri` IdP и его документ обнаружения только из этого значения, никогда из заголовков `X-Forwarded-*`.225 * `public_url`: внешний источник `https://`, требуется для любого привязывания, отличного от loopback; см. [справочник `listen`](/docs/ru/claude-apps-gateway-config#listen). Gateway строит `redirect_uri` IdP и его документ обнаружения только из этого значения, никогда из заголовков `X-Forwarded-*`.

226 * `trusted_proxies`: диапазоны источников фронтенда. Gateway соблюдает `X-Forwarded-For` только когда TCP-пир находится в этом списке, затем проходит цепь мимо доверенных переходов, поэтому ограничения скорости входа на IP и события аудита записывают IP разработчиков вместо load balancer.226 * `trusted_proxies`: диапазоны источников фронтенда. Gateway соблюдает `X-Forwarded-For` только когда TCP-пир находится в этом списке, затем проходит цепь мимо доверенных переходов, поэтому ограничения частоты запросов на вход по IP и события аудита записывают IP разработчиков вместо load balancer.

227 227

228 На обоих треках фронтенд — это внутренний ALB, создан ли он напрямую или AWS Load Balancer Controller, и узлы ALB берут адреса из подсетей, к которым он присоединён, поэтому установите `trusted_proxies` на CIDR этих подсетей. Это доверяет каждому хосту в этих подсетях как прокси. Не допускайте, чтобы источник входа ALB, ваша корпоративная CIDR, перекрывался с ними, и не делитесь подсетями с ненадёжными рабочими нагрузками, которые могли бы подделать IP клиентов через `X-Forwarded-For`.228 На обоих треках фронтенд — это внутренний ALB, создан ли он напрямую или AWS Load Balancer Controller, и узлы ALB берут адреса из подсетей, к которым он присоединён, поэтому установите `trusted_proxies` на CIDR этих подсетей. Это доверяет каждому хосту в этих подсетях как прокси. Не допускайте, чтобы источник входа ALB, ваша корпоративная CIDR, перекрывался с ними, и не делитесь подсетями с ненадёжными рабочими нагрузками, которые могли бы подделать IP клиентов через `X-Forwarded-For`.

229 229

230 Атрибут сохранения клиентского порта ALB, `routing.http.xff_client_port.enabled`, может остаться в любом параметре: с ним включённым, ALB записывает клиента как `203.0.113.7:54321` или `[2001:db8::1]:54321`, и gateway читает оба с опущенным портом.230 Атрибут сохранения клиентского порта ALB, `routing.http.xff_client_port.enabled`, может остаться в любой настройке: с ним включённым, ALB записывает клиента как `203.0.113.7:54321` или `[2001:db8::1]:54321`, и gateway читает оба с опущенным портом.

231 231

232 ```yaml gateway.yaml theme={null}232 ```yaml gateway.yaml theme={null}

233 listen:233 listen:

244 # Сервер авторизации организации Okta возвращает тонкий id_token, который опускает244 # Сервер авторизации организации Okta возвращает тонкий id_token, который опускает

245 # email и groups; gateway заполняет их из /userinfo.245 # email и groups; gateway заполняет их из /userinfo.

246 userinfo_fallback: true246 userinfo_fallback: true

247 # Okta выдаёт groups только когда запрашивается область `groups` и247 # Okta выдаёт groups только когда запрашивается scope `groups` и

248 # фильтр утверждения groups приложения их позволяет.248 # фильтр утверждения groups приложения их позволяет.

249 scopes: [openid, profile, email, offline_access, groups]249 scopes: [openid, profile, email, offline_access, groups]

250 250

267 ```267 ```

268 268

269 <Note>269 <Note>

270 Только блок `oidc` специфичен для Okta. Чтобы использовать Microsoft Entra ID вместо этого, установите `issuer` на `https://login.microsoftonline.com/<tenant-id>/v2.0`, удалите `userinfo_fallback` и область `groups`, и обратите внимание, что Entra выдаёт Object ID группы, а не имена, поэтому [`managed.policies`](/docs/ru/claude-apps-gateway-config#managed) должны совпадать на GUID, или на App Roles с `oidc.groups_claim: roles`. См. [Настройка поставщика идентификации](/docs/ru/claude-apps-gateway-deploy#identity-provider-setup).270 Только блок `oidc` специфичен для Okta. Чтобы использовать Microsoft Entra ID вместо этого, установите `issuer` на `https://login.microsoftonline.com/<tenant-id>/v2.0`, удалите `userinfo_fallback` и scope `groups`, и обратите внимание, что Entra выдаёт Object ID группы, а не имена, поэтому [`managed.policies`](/docs/ru/claude-apps-gateway-config#managed) должны совпадать на GUID, или на App Roles с `oidc.groups_claim: roles`. См. [Настройка поставщика идентификации](/docs/ru/claude-apps-gateway-deploy#identity-provider-setup).

271 </Note>271 </Note>

272 </Step>272 </Step>

273 273

289 Буквальные аргументы `--secret-string` видны в таблице процессов и в журналах аудита/EDR во время выполнения каждой команды. На общем или контролируемом хосте поместите значение в файл `0600` и передайте `--secret-string file://<path>` вместо этого. `setup.sh` пакета держит значения секретов вне argv процесса так же, передавая временные файлы `0600` в `--cli-input-json`.289 Буквальные аргументы `--secret-string` видны в таблице процессов и в журналах аудита/EDR во время выполнения каждой команды. На общем или контролируемом хосте поместите значение в файл `0600` и передайте `--secret-string file://<path>` вместо этого. `setup.sh` пакета держит значения секретов вне argv процесса так же, передавая временные файлы `0600` в `--cli-input-json`.

290 </Note>290 </Note>

291 291

292 В отличие от секретов, сам `gateway.yaml` не содержит значений секретов, потому что каждое учётное данные разрешается при загрузке через [`${VAR}` или `${file:...}` расширение](/docs/ru/claude-apps-gateway-config#secret-expansion). Как всё достигает контейнера, отличается по треку:292 В отличие от секретов, сам `gateway.yaml` не содержит значений секретов, потому что все учётные данные разрешаются при загрузке через [`${VAR}` или `${file:...}` расширение](/docs/ru/claude-apps-gateway-config#secret-expansion). Как всё достигает контейнера, отличается по треку:

293 293

294 * На ECS, сборка следующего шага копирует `gateway.yaml` в образ в `/etc/claude/gateway.yaml`, и определение задачи внедряет три секрета как переменные окружения через его поле `secrets`, поэтому YAML ссылается на `${GATEWAY_JWT_SECRET}`, `${OIDC_CLIENT_SECRET}` и `${GATEWAY_POSTGRES_URL}`.294 * На ECS, сборка следующего шага копирует `gateway.yaml` в образ в `/etc/claude/gateway.yaml`, и определение задачи внедряет три секрета как переменные окружения через его поле `secrets`, поэтому YAML ссылается на `${GATEWAY_JWT_SECRET}`, `${OIDC_CLIENT_SECRET}` и `${GATEWAY_POSTGRES_URL}`.

295 * На EKS, смонтируйте `gateway.yaml` из ConfigMap и секреты как файлы в `/secrets`, на которые ссылаются как `${file:/secrets/...}`. Получите Kubernetes Secrets из Secrets Manager с External Secrets Operator или поставщиком AWS драйвера Secrets Store CSI, или создайте их напрямую с помощью `kubectl`.295 * На EKS, смонтируйте `gateway.yaml` из ConfigMap и секреты как файлы в `/secrets`, на которые ссылаются как `${file:/secrets/...}`. Получите Kubernetes Secrets из Secrets Manager с External Secrets Operator или поставщиком AWS драйвера Secrets Store CSI, или создайте их напрямую с помощью `kubectl`.

298 <Step title="Соберите и отправьте образ в Amazon ECR">298 <Step title="Соберите и отправьте образ в Amazon ECR">

299 Соберите образ согласно [требованиям образа контейнера](/docs/ru/claude-apps-gateway-deploy#container-image), разместив двоичный файл `linux-x64` glibc в `./claude` в контексте сборки. Напишите свой собственный Dockerfile согласно этим требованиям или начните с [`Dockerfile`](https://github.com/anthropics/claude-code/blob/main/examples/gateway/aws/Dockerfile) пакета, который копирует заполненный `gateway.yaml` из предыдущих шагов в образ в `/etc/claude/gateway.yaml`. На ECS эта встроенная копия — это то, как конфигурация достигает контейнера, поэтому сборка идёт после написания файла. Трек EKS вместо этого монтирует `gateway.yaml` из ConfigMap при развёртывании, поэтому встроенная копия там не используется.299 Соберите образ согласно [требованиям образа контейнера](/docs/ru/claude-apps-gateway-deploy#container-image), разместив двоичный файл `linux-x64` glibc в `./claude` в контексте сборки. Напишите свой собственный Dockerfile согласно этим требованиям или начните с [`Dockerfile`](https://github.com/anthropics/claude-code/blob/main/examples/gateway/aws/Dockerfile) пакета, который копирует заполненный `gateway.yaml` из предыдущих шагов в образ в `/etc/claude/gateway.yaml`. На ECS эта встроенная копия — это то, как конфигурация достигает контейнера, поэтому сборка идёт после написания файла. Трек EKS вместо этого монтирует `gateway.yaml` из ConfigMap при развёртывании, поэтому встроенная копия там не используется.

300 300

301 Образ также содержит пакет сертификатов AWS RDS как якорь доверия для `sslmode=verify-full` строки подключения, поэтому загрузите его в контекст сборки сначала. AWS ротирует пакет (новые региональные CA добавляются), поэтому загружайте его при каждой сборке, а не закрепляйте контрольную сумму или фиксируйте её:301 Образ также содержит пакет сертификатов AWS RDS как якорь доверия для `sslmode=verify-full` строки подключения, поэтому загрузите его в контекст сборки сначала. AWS ротирует пакет (новые региональные CA добавляются), поэтому загружайте его при каждой сборке, а не закрепляйте контрольную сумму или фиксируйте его:

302 302

303 ```bash theme={null}303 ```bash theme={null}

304 curl -fL --proto '=https' -o rds-global-bundle.pem \304 curl -fL --proto '=https' -o rds-global-bundle.pem \

305 https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem305 https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

306 ```306 ```

307 307

308 Требования образа контейнера не охватывают пакет, поэтому если вы напишете свой собственный Dockerfile, добавьте две строки, которые копируют и доверяют ему; `Dockerfile` пакета уже включает оба:308 Требования образа контейнера не охватывают пакет, поэтому если вы напишете свой собственный Dockerfile, добавьте две строки, которые копируют и доверяют ему; `Dockerfile` пакета уже включает обе:

309 309

310 ```dockerfile theme={null}310 ```dockerfile theme={null}

311 COPY rds-global-bundle.pem /etc/claude/rds-global-bundle.pem311 COPY rds-global-bundle.pem /etc/claude/rds-global-bundle.pem

312 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem312 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem

313 ```313 ```

314 314

315 Создайте репозиторий ECR и подпишите Docker в него. Неизменяемые теги означают, что тег `<version>`, который закрепляет шаг развёртывания, не может позже молча переуказываться на другой образ:315 Создайте репозиторий ECR и выполните вход Docker в него. Неизменяемые теги означают, что тег `<version>`, который закрепляет шаг развёртывания, не может позже молча переуказываться на другой образ:

316 316

317 ```bash theme={null}317 ```bash theme={null}

318 aws ecr create-repository --repository-name claude-gateway \318 aws ecr create-repository --repository-name claude-gateway \

401 401

402 Добавьте слушатель HTTPS. `--ssl-policy` закрепляет современный минимум TLS, так как его опущение возвращается к устаревшему значению по умолчанию `ELBSecurityPolicy-2016-08`, которое всё ещё принимает TLS 1.0/1.1.402 Добавьте слушатель HTTPS. `--ssl-policy` закрепляет современный минимум TLS, так как его опущение возвращается к устаревшему значению по умолчанию `ELBSecurityPolicy-2016-08`, которое всё ещё принимает TLS 1.0/1.1.

403 403

404 ALB закрывает соединение после 60 секунд без данных по умолчанию. Keepalive пинги gateway держат потоки внутри этого значения по умолчанию, поэтому повышение времени ожидания добавляет запас выше кадра пинга; строка [Troubleshooting](#troubleshooting) на разорванных потоках охватывает механизм и более старые gateway. Команды ниже добавляют слушатель и повышают время ожидания:404 ALB закрывает соединение после 60 секунд без данных по умолчанию. Keepalive пинги gateway держат потоки внутри этого значения по умолчанию, поэтому повышение таймаута добавляет запас выше частоты пингов; строка [Устранение неполадок](#troubleshooting) о разорванных потоках охватывает механизм и более старые gateway. Команды ниже добавляют слушатель и повышают таймаут:

405 405

406 ```bash theme={null}406 ```bash theme={null}

407 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \407 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \

414 --attributes Key=idle_timeout.timeout_seconds,Value=3600414 --attributes Key=idle_timeout.timeout_seconds,Value=3600

415 ```415 ```

416 416

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

418 418

419 ```bash theme={null}419 ```bash theme={null}

420 aws ecs create-service --cluster claude-gateway --service-name claude-gateway \420 aws ecs create-service --cluster claude-gateway --service-name claude-gateway \

425 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"425 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"

426 ```426 ```

427 427

428 Период благодати в 60 секунд даёт холодной задаче время на извлечение образа, подключение к хранилищу и ответ на первую проверку здоровья перед тем, как ECS начнёт считать отказы против развёртывания. Проверка здоровья целевой группы на `GET /readyz` проверяет, что хранилище доступно, поэтому задача, которая не может достичь Postgres, никогда не входит в ротацию. Чтобы держать задачи проходящими проверку через короткий сбой базы данных, такой как отказ RDS, установите `store.readiness_grace_seconds`, как описано в [Поведение при сбое](/docs/ru/claude-apps-gateway-deploy#outage-behavior), которое также охватывает альтернативу `/healthz`.428 Период благодати в 60 секунд даёт холодной задаче время на извлечение образа, подключение к хранилищу и ответ на первую проверку здоровья перед тем, как ECS начнёт считать отказы против развёртывания.

429 429

430 Задачи работают в приватных подсетях без публичного IP, поэтому весь исходящий трафик (в Bedrock, ваш IdP, Secrets Manager, ECR и CloudWatch Logs) проходит через NAT gateway. Чтобы держать трафик Bedrock вне публичного пути, создайте интерфейсную конечную точку VPC `bedrock-runtime` и укажите `base_url` upstream на неё, как показано в [справочнике upstream Bedrock](/docs/ru/claude-apps-gateway-config#amazon-bedrock); IdP всё ещё нуждается в исходящем доступе в интернет.430 Проверка здоровья целевой группы на `GET /readyz` проверяет, что хранилище доступно, поэтому задача, которая не может достичь Postgres, никогда не входит в ротацию. Чтобы держать задачи проходящими проверку через короткий сбой базы данных, такой как отказ RDS, установите `store.readiness_grace_seconds`, как описано в [Поведение при сбое](/docs/ru/claude-apps-gateway-deploy#outage-behavior), которое также охватывает альтернативу `/healthz`.

431

432 Задачи работают в приватных подсетях без публичного IP, поэтому весь исходящий трафик (в Bedrock, ваш IdP, Secrets Manager, ECR и CloudWatch Logs) проходит через NAT gateway. Чтобы держать трафик Bedrock вне публичного пути, создайте интерфейсный эндпоинт VPC `bedrock-runtime` и укажите `base_url` upstream на него, как показано в [справочнике upstream Bedrock](/docs/ru/claude-apps-gateway-config#amazon-bedrock); IdP всё ещё нуждается в исходящем доступе в интернет.

431 433

432 Завершите, дав разработчикам приватно разрешаемое имя хоста: в приватной зоне Route 53 создайте псевдоним внутреннего имени DNS gateway на ALB и установите `listen.public_url` на это имя хоста. Собственное имя `*.elb.amazonaws.com` ALB разрешается на приватные адреса на внутреннем ALB, но оно не может нести ваш сертификат ACM, поэтому используйте своё имя.434 Завершите, дав разработчикам приватно разрешаемое имя хоста: в приватной зоне Route 53 создайте псевдоним внутреннего имени DNS gateway на ALB и установите `listen.public_url` на это имя хоста. Собственное имя `*.elb.amazonaws.com` ALB разрешается на приватные адреса на внутреннем ALB, но оно не может нести ваш сертификат ACM, поэтому используйте своё имя.

433 435

434 Обновите URI перенаправления авторизованного клиента OAuth на `<public_url>/oauth/callback` перед первым входом. После изменения `public_url`, пересоберите и отправьте образ под новым тегом, зарегистрируйте новую редакцию определения задачи и переразвёртывайте. На ECS параметр живёт в встроенном `gateway.yaml` образа, и gateway строит свой публичный источник только из этого параметра, игнорируя `X-Forwarded-Host` и `X-Forwarded-Proto`. `X-Forwarded-For` соблюдается для IP клиентов только когда установлен `listen.trusted_proxies`.436 Обновите URI перенаправления авторизованного клиента OAuth на `<public_url>/oauth/callback` перед первым входом. После изменения `public_url`, пересоберите и отправьте образ под новым тегом, зарегистрируйте новую редакцию определения задачи и переразвёртывайте. На ECS настройка живёт во встроенном `gateway.yaml` образа, и gateway строит свой публичный источник только из этой настройки, игнорируя `X-Forwarded-Host` и `X-Forwarded-Proto`. `X-Forwarded-For` соблюдается для IP клиентов только когда установлен `listen.trusted_proxies`.

435 </Tab>437 </Tab>

436 438

437 <Tab title="EKS">439 <Tab title="EKS">

438 Этот трек нуждается в установленных `kubectl` и `eksctl` локально, и существующем кластере EKS с поставщиком IAM OIDC и установленным AWS Load Balancer Controller. Кластер должен быть на `$VPC_ID`, чтобы поды могли достичь приватной конечной точки RDS, и группа безопасности `claude-gateway-db` должна допускать группу безопасности пода или узла кластера вместо `$GW_SG`.440 Этот трек нуждается в установленных `kubectl` и `eksctl` локально, и существующем кластере EKS с поставщиком IAM OIDC и установленным AWS Load Balancer Controller. Кластер должен быть на `$VPC_ID`, чтобы поды могли достичь приватного эндпоинта RDS, и группа безопасности `claude-gateway-db` должна допускать группу безопасности пода или узла кластера вместо `$GW_SG`.

439 441

440 На EKS gateway получает свои учётные данные Bedrock через IRSA, а не роли ECS. Политика доверия `ecs-tasks.amazonaws.com` из шага IAM не применяется здесь; IRSA нуждается в роли, чья политика доверия федерирует на поставщика OIDC кластера, ограниченном `system:serviceaccount:claude-gateway:gateway`. `eksctl create iamserviceaccount` создаёт эту роль, присоединяет политики и аннотирует учётную запись сервиса Kubernetes с ARN роли в один шаг. Превратите два документа политики из шага IAM в управляемые политики, которые он может присоединить:442 На EKS gateway получает свои учётные данные Bedrock через IRSA, а не роли ECS. Политика доверия `ecs-tasks.amazonaws.com` из шага IAM не применяется здесь; IRSA нуждается в роли, чья политика доверия федерирует на поставщика OIDC кластера, ограниченной `system:serviceaccount:claude-gateway:gateway`. `eksctl create iamserviceaccount` создаёт эту роль, присоединяет политики и аннотирует учётную запись сервиса Kubernetes с ARN роли в один шаг. Превратите два документа политики из шага IAM в управляемые политики, которые он может присоединить:

441 443

442 ```bash theme={null}444 ```bash theme={null}

443 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \445 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \

464 Для фронтенда, Ingress, управляемый AWS Load Balancer Controller, предусматривает внутренний ALB. Аннотируйте его с:466 Для фронтенда, Ingress, управляемый AWS Load Balancer Controller, предусматривает внутренний ALB. Аннотируйте его с:

465 467

466 * `alb.ingress.kubernetes.io/scheme: internal` и `alb.ingress.kubernetes.io/target-type: ip`468 * `alb.ingress.kubernetes.io/scheme: internal` и `alb.ingress.kubernetes.io/target-type: ip`

467 * `alb.ingress.kubernetes.io/ip-address-type: ipv4`, поэтому записи AAAA общественного диапазона не публикуются для проверки приватной сети `/login` [private-network check](/docs/ru/claude-apps-gateway#prerequisites) отклонить469 * `alb.ingress.kubernetes.io/ip-address-type: ipv4`, чтобы не публиковались записи AAAA общественного диапазона, которые [проверка приватной сети](/docs/ru/claude-apps-gateway#prerequisites) `/login` отклонила бы

468 * `alb.ingress.kubernetes.io/inbound-cidrs: <your-corporate-cidr>`, поэтому контроллер-управляемая группа безопасности фронтенда допускает только вашу корпоративную сеть вместо значения по умолчанию `0.0.0.0/0`470 * `alb.ingress.kubernetes.io/inbound-cidrs: <your-corporate-cidr>`, поэтому контроллер-управляемая группа безопасности фронтенда допускает только вашу корпоративную сеть вместо значения по умолчанию `0.0.0.0/0`

469 * `alb.ingress.kubernetes.io/certificate-arn` с сертификатом ACM471 * `alb.ingress.kubernetes.io/certificate-arn` с сертификатом ACM

470 * `alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS13-1-2-2021-06`, поэтому слушатель не возвращается к устаревшей политике по умолчанию, которая принимает TLS 1.0 и 1.1472 * `alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS13-1-2-2021-06`, поэтому слушатель не возвращается к устаревшей политике по умолчанию, которая принимает TLS 1.0 и 1.1

471 * `alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=3600`, запас выше keepalive потоков gateway; см. [Troubleshooting](#troubleshooting)473 * `alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=3600`, запас выше keepalive потоковой передачи gateway; см. [Устранение неполадок](#troubleshooting)

472 474

473 С IRSA, AWS SDK читает спроецированный токен учётной записи сервиса и обменивает его с AWS STS, поэтому под никогда не нуждается в сервисе метаданных экземпляра EC2; NetworkPolicy исходящего трафика может блокировать `169.254.169.254` для подов gateway. Проблема с лимитом переходов узла в [Troubleshooting](#troubleshooting) ниже применяется только к кластерам, которые пропускают IRSA и полагаются на роли экземпляра узла.475 С IRSA, AWS SDK читает спроецированный токен учётной записи сервиса и обменивает его с AWS STS, поэтому под никогда не нуждается в сервисе метаданных экземпляра EC2; NetworkPolicy исходящего трафика может блокировать `169.254.169.254` для подов gateway. Проблема с лимитом переходов узла в разделе [Устранение неполадок](#troubleshooting) ниже применяется только к кластерам, которые пропускают IRSA и полагаются на роли экземпляра узла.

474 </Tab>476 </Tab>

475 </Tabs>477 </Tabs>

476 </Step>478 </Step>

477 479

478 <Step title="Отправьте URL gateway на машины разработчиков">480 <Step title="Отправьте URL gateway на машины разработчиков">

479 Gateway теперь работает, но разработчики не могут достичь его из `/login` до тех пор, пока URL gateway не будет на их машинах. Установите `forceLoginMethod` и `forceLoginGatewayUrl` в [файле управляемых параметров](/docs/ru/claude-apps-gateway#set-the-gateway-url), который вы развёртываете на каждом устройстве через MDM. Нет опции gateway в средстве выбора входа для разработчика, чтобы выбрать вручную.481 Gateway теперь работает, но разработчики не могут достичь его из `/login` до тех пор, пока URL gateway не будет на их машинах. Установите `forceLoginMethod` и `forceLoginGatewayUrl` в [файле управляемых настроек](/docs/ru/claude-apps-gateway#set-the-gateway-url), который вы развёртываете на каждом устройстве через MDM. Нет опции gateway в средстве выбора входа для разработчика, чтобы выбрать вручную.

480 </Step>482 </Step>

481</Steps>483</Steps>

482 484

claude-code-on-the-web.md +4 −2

Details

442`claude --cloud` и `claude --teleport` требуют входа с аккаунтом claude.ai. Если вы аутентифицируетесь с помощью API-ключа или ваши сохранённые данные аккаунта устарели, вы увидите одно из следующего:442`claude --cloud` и `claude --teleport` требуют входа с аккаунтом claude.ai. Если вы аутентифицируетесь с помощью API-ключа или ваши сохранённые данные аккаунта устарели, вы увидите одно из следующего:

443 443

444* `Unable to get organization UUID`444* `Unable to get organization UUID`

445* Сообщение о том, что аутентификации с помощью API-ключа недостаточно445* ``Cloud sessions need a claude.ai sign-in. Run `claude auth login` (or /login in a local session), then try again.``

446* `Error loading Claude Code sessions` в окне выбора сессии, если вы запускаете `claude --teleport` без ID сессии446* `Error loading Claude Code sessions` в окне выбора сессии, если вы запускаете `claude --teleport` без ID сессии

447 447

448Запустите `/login` для входа с вашим аккаунтом claude.ai, затем повторите команду. Если вместо этого в ошибке указан ваш поставщик, см. [таблицу ошибок](#errors-when-sending-to-a-cloud-session): облачные сессии недоступны через сторонних поставщиков.448Запустите [`claude auth login`](/docs/ru/cli-reference#cli-commands) в оболочке, чтобы войти с вашим аккаунтом claude.ai, затем повторите команду. Внутри запущенной сессии то же самое делает `/login`. Если вместо этого в ошибке указан ваш поставщик, см. [таблицу ошибок](#errors-when-sending-to-a-cloud-session): облачные сессии недоступны через сторонних поставщиков.

449

450В версиях с v2.1.274 по v2.1.289 сообщение о входе было таким: `Claude Code cloud sessions require authentication with a Claude.ai account. API key authentication is not sufficient. Please run /login to authenticate, or check your authentication status with /status.`

449 451

450<h3 id="remote-control-session-expired-or-access-denied">452<h3 id="remote-control-session-expired-or-access-denied">

451 Remote Control session expired or access denied453 Remote Control session expired or access denied

claude-directory.md +3 −3

Details

34 oneLiner: 'Project instructions Claude reads every session',34 oneLiner: 'Project instructions Claude reads every session',

35 when: 'Loaded into context at the start of every session',35 when: 'Loaded into context at the start of every session',

36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',

37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>, <>If your repo already has an <C>AGENTS.md</C> for other coding agents, Claude Code <A href="/docs/en/memory#agents-md">can read that</A> on its own or alongside CLAUDE.md</>],37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>, <>If your repo already has an <C>AGENTS.md</C> for other coding agents, Claude Code <A href="/docs/en/memory#agents-md">can read that</A> in place of a <C>CLAUDE.md</C></>],

38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',

39 example: `# Project conventions39 example: `# Project conventions

40 40

1434 1434

1435На Windows `~/.claude` разрешается в `%USERPROFILE%\.claude`. Если вы установите [`CLAUDE_CONFIG_DIR`](/docs/ru/env-vars), каждый путь `~/.claude` на этой странице будет находиться в этой директории вместо этого.1435На Windows `~/.claude` разрешается в `%USERPROFILE%\.claude`. Если вы установите [`CLAUDE_CONFIG_DIR`](/docs/ru/env-vars), каждый путь `~/.claude` на этой странице будет находиться в этой директории вместо этого.

1436 1436

1437Большинство пользователей редактируют только `CLAUDE.md` и `settings.json`. Если ваш репозиторий уже содержит `AGENTS.md` для других агентов кодирования, Claude Code [может читать это](/docs/ru/memory#agents-md) самостоятельно или вместе с `CLAUDE.md`. Остальная часть директории опциональна: добавляйте skills, rules или subagents по мере необходимости.1437Большинство пользователей редактируют только `CLAUDE.md` и `settings.json`. Если ваш репозиторий уже содержит `AGENTS.md` для других агентов кодирования, Claude Code [может читать его](/docs/ru/memory#agents-md) вместо `CLAUDE.md`. Остальная часть директории опциональна: добавляйте skills, rules или subagents по мере необходимости.

1438 1438

1439<h2 id="explore-the-directory">1439<h2 id="explore-the-directory">

1440 Изучите директорию1440 Изучите директорию

1454| - | - | - |1454| - | - | - |

1455| `managed-settings.json` | Уровень системы, варьируется в зависимости от ОС | Параметры, установленные предприятием, которые вы не можете переопределить, за исключением [узких исключений](/docs/ru/settings#security-keys-where-the-stricter-value-applies). См. [где сохранить файл](/docs/ru/managed-settings#deploy-a-managed-settings-file) и [какой управляемый источник использует Claude Code](/docs/ru/managed-settings#precedence-within-the-managed-tier). |1455| `managed-settings.json` | Уровень системы, варьируется в зависимости от ОС | Параметры, установленные предприятием, которые вы не можете переопределить, за исключением [узких исключений](/docs/ru/settings#security-keys-where-the-stricter-value-applies). См. [где сохранить файл](/docs/ru/managed-settings#deploy-a-managed-settings-file) и [какой управляемый источник использует Claude Code](/docs/ru/managed-settings#precedence-within-the-managed-tier). |

1457| `AGENTS.md` | Корень проекта, `.claude/` или любой каталог | Инструкции проекта, которые вы пишете для агентов AI кодирования. Claude Code может [загрузить его](/docs/ru/memory#agents-md) самостоятельно или вместе с `CLAUDE.md`. |1457| `AGENTS.md` | Корень проекта, `.claude/` или любой каталог | Инструкции проекта, которые вы пишете для агентов AI кодирования. Claude Code может [загрузить его](/docs/ru/memory#agents-md) вместо `CLAUDE.md`. |

1458| Установленные плагины | `~/.claude/plugins` | Клонированные маркетплейсы, установленные версии плагинов, запись установки `installed_plugins.json` и данные для каждого плагина, управляемые командами `claude plugin`. Плагины, [синхронизированные с вашей учётной записью claude.ai](/docs/ru/plugins/loading#synced-plugins), загружаются в `~/.claude/plugins/synced/`. Для плагина, установленного из маркетплейса с источником [`command`](/docs/ru/plugins/marketplace-reference#command-plugin-source) в режиме ссылки, Claude Code хранит здесь ссылки вместо копии, и файлы плагина остаются в каталоге, который выводит команда. Источник `command` требует Claude Code v2.1.229 или позже. Плагин, указанный относительным путём в маркетплейсе, который вы добавили из локального пути, также [загружается на месте](/docs/ru/plugins/loading#find-plugins-on-disk) из своего исходного каталога, а не из копии в кэше. См. [кэширование плагинов](/docs/ru/plugins/loading#find-plugins-on-disk), чтобы узнать, как очищаются заброшенные версии. |1458| Установленные плагины | `~/.claude/plugins` | Клонированные маркетплейсы, установленные версии плагинов, запись установки `installed_plugins.json` и данные для каждого плагина, управляемые командами `claude plugin`. Плагины, [синхронизированные с вашей учётной записью claude.ai](/docs/ru/plugins/loading#synced-plugins), загружаются в `~/.claude/plugins/synced/`. Для плагина, установленного из маркетплейса с источником [`command`](/docs/ru/plugins/marketplace-reference#command-plugin-source) в режиме ссылки, Claude Code хранит здесь ссылки вместо копии, и файлы плагина остаются в каталоге, который выводит команда. Источник `command` требует Claude Code v2.1.229 или позже. Плагин, указанный относительным путём в маркетплейсе, который вы добавили из локального пути, также [загружается на месте](/docs/ru/plugins/loading#find-plugins-on-disk) из своего исходного каталога, а не из копии в кэше. См. [кэширование плагинов](/docs/ru/plugins/loading#find-plugins-on-disk), чтобы узнать, как очищаются заброшенные версии. |

1459 1459

1460`~/.claude` также содержит данные, которые Claude Code записывает во время работы: стенограммы, историю подсказок, снимки файлов, кэши и журналы. См. [данные приложения](#application-data) ниже.1460`~/.claude` также содержит данные, которые Claude Code записывает во время работы: стенограммы, историю подсказок, снимки файлов, кэши и журналы. См. [данные приложения](#application-data) ниже.

cli-reference.md +2 −0

Details

31| `claude attach <id\|name>` | Подключиться к [фоновой сессии](/docs/ru/agent-view#manage-sessions-from-the-shell) в этом терминале. Передача части имени работающей сессии вместо ID требует Claude Code v2.1.290 или новее | `claude attach 7c5dcf5d` |31| `claude attach <id\|name>` | Подключиться к [фоновой сессии](/docs/ru/agent-view#manage-sessions-from-the-shell) в этом терминале. Передача части имени работающей сессии вместо ID требует Claude Code v2.1.290 или новее | `claude attach 7c5dcf5d` |

32| `claude auto-mode defaults` | Вывести встроенные правила классификатора [авторежима](/docs/ru/permission-modes#eliminate-prompts-with-auto-mode) в формате JSON. Используйте `claude auto-mode config`, чтобы увидеть вашу действующую конфигурацию с применёнными настройками. `--label <prefix>` выводит только правила, метка которых начинается с этого префикса, без учёта регистра. Требует Claude Code v2.1.208 или новее | `claude auto-mode defaults --label 'Git Destructive'` |32| `claude auto-mode defaults` | Вывести встроенные правила классификатора [авторежима](/docs/ru/permission-modes#eliminate-prompts-with-auto-mode) в формате JSON. Используйте `claude auto-mode config`, чтобы увидеть вашу действующую конфигурацию с применёнными настройками. `--label <prefix>` выводит только правила, метка которых начинается с этого префикса, без учёта регистра. Требует Claude Code v2.1.208 или новее | `claude auto-mode defaults --label 'Git Destructive'` |

33| `claude auto-mode reset` | Восстановить конфигурацию [авторежима](/docs/ru/permission-modes#eliminate-prompts-with-auto-mode) по умолчанию, удалив раздел `autoMode` из файла пользовательских настроек. Запрашивает подтверждение перед записью; передайте `-y`/`--yes`, чтобы пропустить запрос. Правила из [управляемых настроек](/docs/ru/server-managed-settings) или флага `--settings` по-прежнему применяются. Требует Claude Code v2.1.212 или новее. См. [Проверить значения по умолчанию и вашу действующую конфигурацию](/docs/ru/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |33| `claude auto-mode reset` | Восстановить конфигурацию [авторежима](/docs/ru/permission-modes#eliminate-prompts-with-auto-mode) по умолчанию, удалив раздел `autoMode` из файла пользовательских настроек. Запрашивает подтверждение перед записью; передайте `-y`/`--yes`, чтобы пропустить запрос. Правила из [управляемых настроек](/docs/ru/server-managed-settings) или флага `--settings` по-прежнему применяются. Требует Claude Code v2.1.212 или новее. См. [Проверить значения по умолчанию и вашу действующую конфигурацию](/docs/ru/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |

34| `claude daemon logs` | Отслеживать файл лога [супервизора](/docs/ru/agent-view#the-supervisor-process) фоновых сессий, `~/.claude/daemon.log`, выводя новые строки по мере их появления, пока вы не нажмёте `Ctrl+C` | `claude daemon logs` |

35| `claude daemon run` | Запустить [супервизор](/docs/ru/agent-view#the-supervisor-process) фоновых сессий на переднем плане этого терминала с выводом его лога | `claude daemon run` |

34| `claude daemon status` | Вывести состояние [супервизора](/docs/ru/agent-view#the-supervisor-process) фоновых сессий, версию, каталог сокетов и количество рабочих процессов для диагностики. Завершается с кодом 1, если супервизор не запущен | `claude daemon status` |36| `claude daemon status` | Вывести состояние [супервизора](/docs/ru/agent-view#the-supervisor-process) фоновых сессий, версию, каталог сокетов и количество рабочих процессов для диагностики. Завершается с кодом 1, если супервизор не запущен | `claude daemon status` |

35| `claude daemon stop --any` | Остановить [супервизор](/docs/ru/agent-view#the-supervisor-process) фоновых сессий и размещённые им сессии. Передайте `--keep-workers`, чтобы оставить фоновые сессии работающими, и следующий супервизор переподключится к ним. `--any` подтверждает остановку супервизора по требованию, который используется по умолчанию. Используйте это для восстановления после [неотвечающего супервизора](/docs/ru/agent-view#agent-view-says-the-background-service-did-not-respond) | `claude daemon stop --any --keep-workers` |37| `claude daemon stop --any` | Остановить [супервизор](/docs/ru/agent-view#the-supervisor-process) фоновых сессий и размещённые им сессии. Передайте `--keep-workers`, чтобы оставить фоновые сессии работающими, и следующий супервизор переподключится к ним. `--any` подтверждает остановку супервизора по требованию, который используется по умолчанию. Используйте это для восстановления после [неотвечающего супервизора](/docs/ru/agent-view#agent-view-says-the-background-service-did-not-respond) | `claude daemon stop --any --keep-workers` |

36| `claude doctor` | Вывести диагностику установки и настроек (только для чтения) из терминала без запуска сессии, включая состояние установки, ошибки валидации файлов настроек и доступность Remote Control. Для проверки настройки внутри сессии, которая также может применять исправления, запустите [`/doctor`](/docs/ru/commands#all-commands) | `claude doctor` |38| `claude doctor` | Вывести диагностику установки и настроек (только для чтения) из терминала без запуска сессии, включая состояние установки, ошибки валидации файлов настроек и доступность Remote Control. Для проверки настройки внутри сессии, которая также может применять исправления, запустите [`/doctor`](/docs/ru/commands#all-commands) | `claude doctor` |

context-window.md +1 −1

Details

1586 1586

1587Сеанс проходит через реалистичный поток с репрезентативными подсчётами токенов:1587Сеанс проходит через реалистичный поток с репрезентативными подсчётами токенов:

1588 1588

1589* **Перед тем, как вы что-либо введёте**: CLAUDE.md, автоматическая память, имена инструментов MCP и описания skills загружаются в контекст. [Файлы AGENTS.md](/docs/ru/memory#agents-md) также могут загружаться, самостоятельно или вместе с CLAUDE.md. Ваша собственная настройка может добавить больше здесь, например [стиль вывода](/docs/ru/output-styles) или текст из [`--append-system-prompt`](/docs/ru/cli-reference).1589* **Перед тем, как вы что-либо введёте**: CLAUDE.md, автоматическая память, имена инструментов MCP и описания скиллов загружаются в контекст. [Файлы AGENTS.md](/docs/ru/memory#agents-md) могут загружаться вместо CLAUDE.md. Ваша собственная настройка может добавить больше здесь, например [стиль вывода](/docs/ru/output-styles) или текст из [`--append-system-prompt`](/docs/ru/cli-reference).

1590* **Во время работы Claude**: каждое чтение файла добавляется в контекст, [правила с областью действия пути](/docs/ru/memory#path-specific-rules) загружаются автоматически вместе с соответствующими файлами, и [hook PostToolUse](/docs/ru/hooks-guide) срабатывает после каждого редактирования.1590* **Во время работы Claude**: каждое чтение файла добавляется в контекст, [правила с областью действия пути](/docs/ru/memory#path-specific-rules) загружаются автоматически вместе с соответствующими файлами, и [hook PostToolUse](/docs/ru/hooks-guide) срабатывает после каждого редактирования.

1591* **Последующий prompt**: [subagent](/docs/ru/sub-agents) обрабатывает исследование в своём собственном отдельном контекстном окне, поэтому большие чтения файлов остаются вне вашего. Только резюме и небольшой трейлер метаданных возвращаются.1591* **Последующий prompt**: [subagent](/docs/ru/sub-agents) обрабатывает исследование в своём собственном отдельном контекстном окне, поэтому большие чтения файлов остаются вне вашего. Только резюме и небольшой трейлер метаданных возвращаются.

1592* **В конце прохождения**: вы запускаете `/compact`, который заменяет историю разговора структурированным резюме. Большая часть содержимого при запуске перезагружается автоматически; таблица ниже показывает, что происходит с каждым механизмом.1592* **В конце прохождения**: вы запускаете `/compact`, который заменяет историю разговора структурированным резюме. Большая часть содержимого при запуске перезагружается автоматически; таблица ниже показывает, что происходит с каждым механизмом.

desktop.md +1 −1

Details

1092Чтобы увидеть, какую версию приложения desktop вы запускаете:1092Чтобы увидеть, какую версию приложения desktop вы запускаете:

1093 1093

1094* **macOS**: нажмите **Claude** в строке меню, затем **About Claude**1094* **macOS**: нажмите **Claude** в строке меню, затем **About Claude**

1095* **Windows**: нажмите **Help**, затем **About**1095* **Windows**: нажмите **Help**, затем **About Claude**

1096 1096

1097Нажмите на номер версии, чтобы скопировать его в буфер обмена.1097Нажмите на номер версии, чтобы скопировать его в буфер обмена.

1098 1098

desktop-ios-simulator.md +1 −1

Details

92* Сохранить снимок экрана с помощью **Cmd+S** или запись экрана с помощью **Cmd+R**, используя кнопки захвата панели или сочетания клавиш; файлы сохраняются на ваш Desktop92* Сохранить снимок экрана с помощью **Cmd+S** или запись экрана с помощью **Cmd+R**, используя кнопки захвата панели или сочетания клавиш; файлы сохраняются на ваш Desktop

93* Остановить трансляцию устройства без его выключения, нажав **Detach simulator**, что вернёт панель в состояние **Attach simulator**93* Остановить трансляцию устройства без его выключения, нажав **Detach simulator**, что вернёт панель в состояние **Attach simulator**

94 94

95Чтобы настроить видеопоток от симулятора, откройте меню **Display** панели. Снизьте **Frame rate** или **Resolution**, если панель перегружает ваш Mac. Обе настройки изменяют способ отображения устройства панелью, а не способ работы приложения.95Если на панели отображается меню **Display**, используйте его, чтобы настроить видеопоток от симулятора. Снизьте **Frame rate** или **Resolution**, если панель перегружает ваш Mac. Обе настройки изменяют способ отображения устройства панелью, а не способ работы приложения.

96 96

97Вы и Claude управляете одним и тем же устройством, поэтому ваши касания изменяют состояние приложения, которое видит Claude. Чтобы Claude проверил конкретный экран, перейдите к нему, касаясь, затем попросите. Пока Claude управляет устройством, панель показывает значок **Claude is using this device** над экраном; воздержитесь от касания до тех пор, пока значок не исчезнет, чтобы результат отражал приложение, а не ваш ввод.97Вы и Claude управляете одним и тем же устройством, поэтому ваши касания изменяют состояние приложения, которое видит Claude. Чтобы Claude проверил конкретный экран, перейдите к нему, касаясь, затем попросите. Пока Claude управляет устройством, панель показывает значок **Claude is using this device** над экраном; воздержитесь от касания до тех пор, пока значок не исчезнет, чтобы результат отражал приложение, а не ваш ввод.

98 98

env-vars.md +1 −0

Details

354| `CLAUDE_CODE_PERFORCE_MODE` | Установите `1`, чтобы включить защиту от записи с учётом Perforce. Если переменная задана, Edit, Write и NotebookEdit завершаются неудачей с подсказкой `p4 edit <file>`, когда у целевого файла отсутствует бит записи для владельца, который Perforce снимает у синхронизированных файлов, пока `p4 edit` не откроет их. Это не позволяет Claude Code обходить отслеживание изменений Perforce |354| `CLAUDE_CODE_PERFORCE_MODE` | Установите `1`, чтобы включить защиту от записи с учётом Perforce. Если переменная задана, Edit, Write и NotebookEdit завершаются неудачей с подсказкой `p4 edit <file>`, когда у целевого файла отсутствует бит записи для владельца, который Perforce снимает у синхронизированных файлов, пока `p4 edit` не откроет их. Это не позволяет Claude Code обходить отслеживание изменений Perforce |

355| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | Переопределяет корневой каталог плагинов. Несмотря на название, задаёт родительский каталог, а не сам кэш: маркетплейсы и кэш плагинов находятся в подкаталогах по этому пути. По умолчанию `~/.claude/plugins` |355| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | Переопределяет корневой каталог плагинов. Несмотря на название, задаёт родительский каталог, а не сам кэш: маркетплейсы и кэш плагинов находятся в подкаталогах по этому пути. По умолчанию `~/.claude/plugins` |

356| `CLAUDE_CODE_PLUGIN_DIRS` | Каталоги плагинов для загрузки в сессию; каждый загружается так же, как его загружает флаг [`--plugin-dir`](/docs/ru/plugins/cli-reference#flags-that-load-a-plugin-for-one-session). Разделяйте несколько путей символом `:` в Unix или `;` в Windows. Указывайте каждый путь как абсолютный или начинайте его с `~`, поскольку Claude Code пропускает относительные пути. Требуется Claude Code v2.1.280 или новее. См. [Загрузка плагина для одной сессии](/docs/ru/plugins/create#load-a-directory-or-archive-for-one-session) |356| `CLAUDE_CODE_PLUGIN_DIRS` | Каталоги плагинов для загрузки в сессию; каждый загружается так же, как его загружает флаг [`--plugin-dir`](/docs/ru/plugins/cli-reference#flags-that-load-a-plugin-for-one-session). Разделяйте несколько путей символом `:` в Unix или `;` в Windows. Указывайте каждый путь как абсолютный или начинайте его с `~`, поскольку Claude Code пропускает относительные пути. Требуется Claude Code v2.1.280 или новее. См. [Загрузка плагина для одной сессии](/docs/ru/plugins/create#load-a-directory-or-archive-for-one-session) |

357| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | Управляет тем, перезагружает ли Claude Code [мод](/docs/ru/plugins/mods/overview) при изменении файлов мода. Перезагрузка применяется к моду, который вы загружаете из каталога с помощью `--plugin-dir`, и по умолчанию включена в интерактивных сессиях. Установите `1`, чтобы включить её также в неинтерактивных сессиях, или `0`, чтобы отключить её во всех сессиях. Требуется Claude Code v2.1.287 или новее. См. [настройки и переменные окружения мода](/docs/ru/plugins/mods/reference#settings-and-environment-variables) |

357| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Таймаут в миллисекундах для клонирования или обновления маркетплейса плагинов (по умолчанию: 120000). Увеличьте это значение для больших репозиториев или медленных сетевых подключений. См. [Git clone timed out](/docs/ru/plugins/troubleshooting#git-clone-timed-out-after-120s) |358| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Таймаут в миллисекундах для клонирования или обновления маркетплейса плагинов (по умолчанию: 120000). Увеличьте это значение для больших репозиториев или медленных сетевых подключений. См. [Git clone timed out](/docs/ru/plugins/troubleshooting#git-clone-timed-out-after-120s) |

358| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | Установите `1`, чтобы пропустить попытку повторного клонирования и продолжить использовать существующую копию маркетплейса, когда при обновлении маркетплейса не удаётся связаться с удалённым репозиторием или пройти аутентификацию. Полезно в автономных или изолированных средах, где повторное клонирование завершилось бы такой же ошибкой. См. [Обновления маркетплейса не выполняются в автономных средах](/docs/ru/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |359| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | Установите `1`, чтобы пропустить попытку повторного клонирования и продолжить использовать существующую копию маркетплейса, когда при обновлении маркетплейса не удаётся связаться с удалённым репозиторием или пройти аутентификацию. Полезно в автономных или изолированных средах, где повторное клонирование завершилось бы такой же ошибкой. См. [Обновления маркетплейса не выполняются в автономных средах](/docs/ru/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |

359| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | Установите `1`, чтобы клонировать источники GitHub в сокращённой форме `owner/repo` по HTTPS вместо SSH. Применяется к установке и обновлению плагинов, а также к `/plugin marketplace add` и `update`. Полезно в CI-раннерах, контейнерах или любых средах без настроенного SSH-ключа для `github.com` |360| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | Установите `1`, чтобы клонировать источники GitHub в сокращённой форме `owner/repo` по HTTPS вместо SSH. Применяется к установке и обновлению плагинов, а также к `/plugin marketplace add` и `update`. Полезно в CI-раннерах, контейнерах или любых средах без настроенного SSH-ключа для `github.com` |

errors.md +2 −3

Details

197| `Cloud sessions cannot be created from a --restricted session` | [Command-line errors](#cloud-sessions-cannot-be-created-from-a-restricted-session) |197| `Cloud sessions cannot be created from a --restricted session` | [Command-line errors](#cloud-sessions-cannot-be-created-from-a-restricted-session) |

198| `Cloud sessions are disabled by your organization's policy` | [Command-line errors](#cloud-sessions-are-disabled-by-your-organizations-policy) |198| `Cloud sessions are disabled by your organization's policy` | [Command-line errors](#cloud-sessions-are-disabled-by-your-organizations-policy) |

199| `Couldn't verify your organization's policy for cloud sessions` | [Command-line errors](#cloud-sessions-are-disabled-by-your-organizations-policy) |199| `Couldn't verify your organization's policy for cloud sessions` | [Command-line errors](#cloud-sessions-are-disabled-by-your-organizations-policy) |

200| `Cloud sessions need a claude.ai sign-in` | [Unable to get organization UUID](/docs/ru/claude-code-on-the-web#unable-to-get-organization-uuid) |

200| `Error: --json-schema is not a valid JSON Schema` | [Command-line errors](#the-json-schema-value-is-not-a-valid-json-schema) |201| `Error: --json-schema is not a valid JSON Schema` | [Command-line errors](#the-json-schema-value-is-not-a-valid-json-schema) |

202| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [Command-line errors](#invalid-agents-configuration) |203| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [Command-line errors](#invalid-agents-configuration) |

387* Соединение, которое, как обнаружил Claude Code, было разорвано тем, что ваш компьютер перешёл в режим сна в середине запроса. Claude Code считает это разорванным соединением в соответствии с приведёнными выше правилами; как только метка повторной попытки назовёт конкретную причину, она будет читаться как `Connection lost while your computer was asleep`, и если ход завершается после того, как Claude завершил размышления, но до любого текста или вызова инструмента, сообщение читается как `Your computer went to sleep before a response was produced`.388* Соединение, которое, как обнаружил Claude Code, было разорвано тем, что ваш компьютер перешёл в режим сна в середине запроса. Claude Code считает это разорванным соединением в соответствии с приведёнными выше правилами; как только метка повторной попытки назовёт конкретную причину, она будет читаться как `Connection lost while your computer was asleep`, и если ход завершается после того, как Claude завершил размышления, но до любого текста или вызова инструмента, сообщение читается как `Your computer went to sleep before a response was produced`.

388* Застопорившийся поток ответа, когда заголовки ответа прибыли, но ни одна часть ответа Claude не прибыла, или когда Claude завершил размышления, но не начал какой-либо текст или вызов инструмента: Claude Code прерывает застопорившееся соединение и повторно отправляет запрос максимум один раз, вне бюджета из 10 попыток выше. Если ответ застопорится во второй раз после того, как Claude завершил размышления, но до любого текста или вызова инструмента, Claude Code завершает ход с `The response stalled before a response was produced`.389* Застопорившийся поток ответа, когда заголовки ответа прибыли, но ни одна часть ответа Claude не прибыла, или когда Claude завершил размышления, но не начал какой-либо текст или вызов инструмента: Claude Code прерывает застопорившееся соединение и повторно отправляет запрос максимум один раз, вне бюджета из 10 попыток выше. Если ответ застопорится во второй раз после того, как Claude завершил размышления, но до любого текста или вызова инструмента, Claude Code завершает ход с `The response stalled before a response was produced`.

389* Потоковый запрос, на который API никогда не отвечает заголовками ответа, на соединении, где [действует дедлайн первого байта](/docs/ru/network-config#streaming-idle-watchdogs): Claude Code прерывает его по истечении дедлайна и повторно отправляет его максимум один раз за запрос модели, в пределах бюджета повторных попыток, затем завершает ход с [No response from API](#no-response-from-api), если эта попытка также остаётся без ответа. На других соединениях запрос ждёт `API_TIMEOUT_MS`. Когда вы устанавливаете `CLAUDE_CODE_RETRY_WATCHDOG`, ограничение на одну повторную попытку не применяется.390* Потоковый запрос, на который API никогда не отвечает заголовками ответа, на соединении, где [действует дедлайн первого байта](/docs/ru/network-config#streaming-idle-watchdogs): Claude Code прерывает его по истечении дедлайна и повторно отправляет его максимум один раз за запрос модели, в пределах бюджета повторных попыток, затем завершает ход с [No response from API](#no-response-from-api), если эта попытка также остаётся без ответа. На других соединениях запрос ждёт `API_TIMEOUT_MS`. Когда вы устанавливаете `CLAUDE_CODE_RETRY_WATCHDOG`, ограничение на одну повторную попытку не применяется.

391* Потоковый ответ, который выходной фильтр содержимого API останавливает до того, как Claude либо завершил размышления, либо начал какой-либо текст или вызов инструмента. Claude Code повторно отправляет запрос один раз, в пределах бюджета повторных попыток, и показывает [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy), если фильтр останавливает и второй ответ.

390* Временные дроссели 429, но не `429` лимита расходов шлюза, который не является дросселем; см. [Spend limit reached](#spend-limit-reached).392* Временные дроссели 429, но не `429` лимита расходов шлюза, который не является дросселем; см. [Spend limit reached](#spend-limit-reached).

391 * Когда вы вошли с подпиской claude.ai, это включает дроссели 429, которые не содержат заголовков квоты вашего плана. До v2.1.199 Claude Code повторял эти дроссели только при входе с API-ключом и через Enterprise.393 * Когда вы вошли с подпиской claude.ai, это включает дроссели 429, которые не содержат заголовков квоты вашего плана. До v2.1.199 Claude Code повторял эти дроссели только при входе с API-ключом и через Enterprise.

392* Запрос отклонён, потому что входные данные плюс `max_tokens` превышают лимит контекста. Повторная отправка его без изменений приведёт к тому же результату, поэтому Claude Code повторяет с уменьшенным `max_tokens` и прекращает повторные попытки и вместо этого выполняет компактирование в двух случаях:394* Запрос отклонён, потому что входные данные плюс `max_tokens` превышают лимит контекста. Повторная отправка его без изменений приведёт к тому же результату, поэтому Claude Code повторяет с уменьшенным `max_tokens` и прекращает повторные попытки и вместо этого выполняет компактирование в двух случаях:

405* [Amazon Bedrock streaming response with an unexpected content-type](#bedrock-streaming-response-has-an-unexpected-content-type), потому что шлюз или прокси, переписывающие ответ, переписали бы повторную попытку таким же образом. Требуется Claude Code v2.1.208 или позже.407* [Amazon Bedrock streaming response with an unexpected content-type](#bedrock-streaming-response-has-an-unexpected-content-type), потому что шлюз или прокси, переписывающие ответ, переписали бы повторную попытку таким же образом. Требуется Claude Code v2.1.208 или позже.

406* Непотоковая повторная попытка неудавшегося потокового запроса, которая получает статус успеха, но [no Claude API message in the body](#api-returned-an-empty-or-malformed-response). Claude Code завершает ход с этой ошибкой.408* Непотоковая повторная попытка неудавшегося потокового запроса, которая получает статус успеха, но [no Claude API message in the body](#api-returned-an-empty-or-malformed-response). Claude Code завершает ход с этой ошибкой.

407* Запрос, который проверка политики вашей организации отклонила, который отображается как строка `API Error:`, содержащая сообщение об отказе. Администраторы вашей организации настроили проверку с помощью [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks), функции Claude Enterprise, и сообщение заканчивается инструкциями, которые они настроили, или по умолчанию говорит вам связаться с ними. Claude Code не отправляет отклонённый запрос повторно на ту же модель или на [резервную модель](/docs/ru/model-config#fallback-model-chains), потому что отказ касается содержимого запроса, а не модели. До v2.1.239 Claude Code мог повторно отправить отклонённый запрос без потоковой передачи или на настроенную резервную модель перед отображением отказа.409* Запрос, который проверка политики вашей организации отклонила, который отображается как строка `API Error:`, содержащая сообщение об отказе. Администраторы вашей организации настроили проверку с помощью [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks), функции Claude Enterprise, и сообщение заканчивается инструкциями, которые они настроили, или по умолчанию говорит вам связаться с ними. Claude Code не отправляет отклонённый запрос повторно на ту же модель или на [резервную модель](/docs/ru/model-config#fallback-model-chains), потому что отказ касается содержимого запроса, а не модели. До v2.1.239 Claude Code мог повторно отправить отклонённый запрос без потоковой передачи или на настроенную резервную модель перед отображением отказа.

408* Ответ, который заблокировал выходной фильтр содержимого API. Claude Code сразу показывает [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy) и не повторяет и не отправляет этот запрос повторно.

409 410

410<h3 id="what-you-see-while-claude-code-retries-or-waits">411<h3 id="what-you-see-while-claude-code-retries-or-waits">

411 Что вы видите, пока Claude Code повторяет или ждёт412 Что вы видите, пока Claude Code повторяет или ждёт

2905API Error: Output blocked by content filtering policy2906API Error: Output blocked by content filtering policy

2906```2907```

2907 2908

2908Claude Code показывает ошибку сразу после получения блокировки и на этом завершает запрос. Он не повторяет запрос, не отправляет его повторно без потоковой передачи и не переключается на [резервную модель](/docs/ru/model-config#fallback-model-chains). До версии 2.1.285 Claude Code мог повторно отправлять заблокированный запрос и повторять попытки, иногда в течение нескольких минут, прежде чем показать ошибку.

~~2909~~

2910**Что делать:**2909**Что делать:**

2911 2910

2912* Переформулируйте последнее сообщение или выберите другой подход2911* Переформулируйте последнее сообщение или выберите другой подход

glossary.md +1 −1

Details

130 130

131Файл markdown с постоянными инструкциями, которые вы пишете для Claude, загружаемый в начале каждого сеанса как пользовательское сообщение после системного prompt. Поместите сюда соглашения проекта, заметки об архитектуре и правила "всегда делай X". CLAUDE.md в корне проекта сохраняется при [compaction](#compaction) и перечитывается свежим с диска после этого.131Файл markdown с постоянными инструкциями, которые вы пишете для Claude, загружаемый в начале каждого сеанса как пользовательское сообщение после системного prompt. Поместите сюда соглашения проекта, заметки об архитектуре и правила "всегда делай X". CLAUDE.md в корне проекта сохраняется при [compaction](#compaction) и перечитывается свежим с диска после этого.

132 132

133Вы можете разместить CLAUDE.md в области проекта в `./CLAUDE.md` или `./.claude/CLAUDE.md`, в области пользователя в `~/.claude/CLAUDE.md` или как [managed policy](#managed-settings) для вашей организации. Все обнаруженные файлы объединяются в контекст, а не переопределяют друг друга, упорядочены от самой широкой области к наиболее специфичной. Claude Code также может загружать файлы [AGENTS.md](#agents-md) проекта, отдельно или вместе с CLAUDE.md.133Вы можете разместить CLAUDE.md на уровне проекта в `./CLAUDE.md` или `./.claude/CLAUDE.md`, на уровне пользователя в `~/.claude/CLAUDE.md` или как [управляемую политику](#managed-settings) для вашей организации. Все обнаруженные файлы объединяются в контексте, а не переопределяют друг друга, и упорядочиваются от самой широкой области действия к наиболее конкретной. Claude Code также может загружать файлы [AGENTS.md](#agents-md) проекта вместо CLAUDE.md.

134 134

135Подробнее: [CLAUDE.md files](/docs/ru/memory#claude-md-files)135Подробнее: [CLAUDE.md files](/docs/ru/memory#claude-md-files)

136 136

google-vertex-ai.md +3 −3

Details

210export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1210export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

211```211```

212 212

213Большинство версий моделей имеют соответствующую переменную `VERTEX_REGION_CLAUDE_*`. Полный список см. в [справочнике переменных окружения](/docs/ru/env-vars). Проверьте [Google Cloud's Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden), чтобы определить, какие модели поддерживают глобальные конечные точки в сравнении с региональными только.213Большинство версий моделей имеют соответствующую переменную `VERTEX_REGION_CLAUDE_*`. Полный список см. в [справочнике переменных окружения](/docs/ru/env-vars#variables). Проверьте [Google Cloud's Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden), чтобы определить, какие модели поддерживают глобальные эндпоинты, а какие только региональные.

214 214

215Если значение региона не похоже на имя региона или местоположения, Claude Code рассматривает его как неустановленное. Например, Claude Code рассматривает значение, содержащее косую черту, точку или пробел, как неустановленное. Claude Code откатывается на другой источник для каждой переменной:215Если значение региона не похоже на имя региона или местоположения, Claude Code рассматривает его как неустановленное. Например, Claude Code рассматривает значение, содержащее косую черту, точку или пробел, как неустановленное. Claude Code откатывается на другой источник для каждой переменной:

216 216

364 364

365* Подтвердите, что модель включена в [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)365* Подтвердите, что модель включена в [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)

366* Проверьте, что модель доступна в указанном вами местоположении. Некоторые модели предлагаются только на `global` или многорегиональных местоположениях, таких как `eu` и `us`, а не в конкретных регионах366* Проверьте, что модель доступна в указанном вами местоположении. Некоторые модели предлагаются только на `global` или многорегиональных местоположениях, таких как `eu` и `us`, а не в конкретных регионах

367* Если вы используете `CLOUD_ML_REGION=global`, проверьте, что ваши модели поддерживают глобальные конечные точки в [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) в разделе "Supported features". Для моделей, которые не поддерживают глобальные конечные точки, либо:367* Если вы используете `CLOUD_ML_REGION=global`, проверьте, что ваши модели поддерживают глобальные эндпоинты в [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) в разделе "Supported features". Для моделей, которые не поддерживают глобальные эндпоинты, либо:

368 * Укажите поддерживаемую модель через `ANTHROPIC_MODEL` или `ANTHROPIC_DEFAULT_HAIKU_MODEL`, либо368 * Укажите поддерживаемую модель через `ANTHROPIC_MODEL` или `ANTHROPIC_DEFAULT_HAIKU_MODEL`, либо

369 * Установите регион или многорегиональное местоположение, используя переменные окружения `VERTEX_REGION_<MODEL_NAME>`369 * Установите регион или многорегиональное местоположение с помощью переменной `VERTEX_REGION_CLAUDE_*` для соответствующей модели, указанной в [справочнике по переменным окружения](/docs/ru/env-vars#variables)

370 370

371Если вы столкнулись с ошибками 429:371Если вы столкнулись с ошибками 429:

372 372

hooks.md +4 −5

Details

63| `DirectoryAdded` | Когда рабочий каталог добавляется в середине сеанса через `/add-dir` или запрос управления SDK `register_repo_root` |63| `DirectoryAdded` | Когда рабочий каталог добавляется в середине сеанса через `/add-dir` или запрос управления SDK `register_repo_root` |

64| `FileChanged` | Когда наблюдаемый файл изменяется на диске. Поле `matcher` указывает, какие имена файлов отслеживать |64| `FileChanged` | Когда наблюдаемый файл изменяется на диске. Поле `matcher` указывает, какие имена файлов отслеживать |

65| `WorktreeCreate` | Когда worktree создаётся через `--worktree`, `isolation: "worktree"`, или для фонового сеанса. Заменяет поведение git по умолчанию |65| `WorktreeCreate` | Когда worktree создаётся через `--worktree`, `isolation: "worktree"`, или для фонового сеанса. Заменяет поведение git по умолчанию |

67| `PreCompact` | Перед компактизацией контекста |67| `PreCompact` | Перед компактизацией контекста |

68| `PostCompact` | После завершения компактизации контекста |68| `PostCompact` | После завершения компактизации контекста |

69| `PreModelSwitch` | Перед тем как Claude Code применяет переключение модели, которое вы или клиент запросили. Может заблокировать переключение |69| `PreModelSwitch` | Перед тем как Claude Code применяет переключение модели, которое вы или клиент запросили. Может заблокировать переключение |

3274 WorktreeRemove3274 WorktreeRemove

3275</h3>3275</h3>

3276 3276

3277Выполняется при удалении worktree. Это парный хук очистки для [WorktreeCreate](#worktreecreate). Событие срабатывает, когда:3277Выполняется, когда Claude Code удаляет worktree, созданный вашим хуком [`WorktreeCreate`](#worktreecreate). Событие срабатывает, когда:

3278 3278

3279* вы выходите из сессии `--worktree` и выбираете её удаление3279* Вы выходите из сессии `--worktree` и выбираете удаление worktree

3280* завершается субагент с `isolation: "worktree"`3280* Вы удаляете [фоновую сессию](/docs/ru/agent-view#what-deleting-a-session-removes), которая работает в этом worktree

3281* вы удаляете [фоновую сессию](/docs/ru/agent-view#what-deleting-a-session-removes), worktree которой создал хук

3282 3281

3283Для worktree на основе git Claude Code выполняет очистку автоматически с помощью `git worktree remove`. Если вы настроили хук WorktreeCreate, добавьте к нему хук WorktreeRemove, чтобы управлять очисткой создаваемых им worktree:3282Для worktree на основе git Claude Code выполняет очистку автоматически с помощью `git worktree remove`. Если вы настроили хук WorktreeCreate, добавьте к нему хук WorktreeRemove, чтобы управлять очисткой создаваемых им worktree:

3284 3283

hooks-guide.md +1 −1

Details

526| `DirectoryAdded` | Когда рабочий каталог добавляется в середине сеанса через `/add-dir` или запрос управления SDK `register_repo_root` |526| `DirectoryAdded` | Когда рабочий каталог добавляется в середине сеанса через `/add-dir` или запрос управления SDK `register_repo_root` |

528| `WorktreeCreate` | Когда worktree создаётся через `--worktree`, `isolation: "worktree"`, или для фонового сеанса. Заменяет поведение git по умолчанию |528| `WorktreeCreate` | Когда worktree создаётся через `--worktree`, `isolation: "worktree"`, или для фонового сеанса. Заменяет поведение git по умолчанию |

532| `PreModelSwitch` | Перед тем как Claude Code применяет переключение модели, которое вы или клиент запросили. Может заблокировать переключение |532| `PreModelSwitch` | Перед тем как Claude Code применяет переключение модели, которое вы или клиент запросили. Может заблокировать переключение |

how-claude-code-works.md +1 −1

Details

76* **Вашему проекту.** Файлы в вашем каталоге и подкаталогах, а также файлы в других местах с вашего разрешения.76* **Вашему проекту.** Файлы в вашем каталоге и подкаталогах, а также файлы в других местах с вашего разрешения.

77* **Вашему терминалу.** Любой команде, которую вы можете запустить: инструменты сборки, git, менеджеры пакетов, системные утилиты, скрипты. Если вы можете это сделать из командной строки, Claude тоже может.77* **Вашему терминалу.** Любой команде, которую вы можете запустить: инструменты сборки, git, менеджеры пакетов, системные утилиты, скрипты. Если вы можете это сделать из командной строки, Claude тоже может.

78* **Вашему состоянию git.** Текущей ветке, незафиксированным изменениям и истории недавних коммитов.78* **Вашему состоянию git.** Текущей ветке, незафиксированным изменениям и истории недавних коммитов.

79* **Вашему [CLAUDE.md](/docs/ru/memory).** Файл markdown, где вы храните инструкции, специфичные для проекта, соглашения и контекст, который Claude должен знать в каждом сеансе. Если ваш репозиторий содержит AGENTS.md для других агентов кодирования, Claude [может прочитать это](/docs/ru/memory#agents-md) самостоятельно или вместе с CLAUDE.md.79* **Вашему [CLAUDE.md](/docs/ru/memory).** Файл markdown, где вы храните инструкции, специфичные для проекта, соглашения и контекст, который Claude должен знать в каждой сессии. Если ваш репозиторий содержит AGENTS.md для других агентов кодирования, Claude [может прочитать его](/docs/ru/memory#agents-md) вместо CLAUDE.md.

80* **[Автоматической памяти](/docs/ru/memory#auto-memory).** Обучение, которое Claude сохраняет автоматически по мере работы, например ваши предпочтения. Первые 200 строк или 25 КБ MEMORY.md, в зависимости от того, что меньше, загружаются в начале каждого сеанса.80* **[Автоматической памяти](/docs/ru/memory#auto-memory).** Обучение, которое Claude сохраняет автоматически по мере работы, например ваши предпочтения. Первые 200 строк или 25 КБ MEMORY.md, в зависимости от того, что меньше, загружаются в начале каждого сеанса.

81* **Расширениям, которые вы настраиваете.** [MCP servers](/docs/ru/mcp) для внешних сервисов, [skills](/docs/ru/skills) для рабочих процессов, [subagents](/docs/ru/sub-agents) для делегированной работы и [Claude в Chrome](/docs/ru/chrome) для взаимодействия с браузером.81* **Расширениям, которые вы настраиваете.** [MCP servers](/docs/ru/mcp) для внешних сервисов, [skills](/docs/ru/skills) для рабочих процессов, [subagents](/docs/ru/sub-agents) для делегированной работы и [Claude в Chrome](/docs/ru/chrome) для взаимодействия с браузером.

82 82

memory.md +2 −2

Details

8 8

9Каждый сеанс Claude Code начинается со свежего context window. Два механизма переносят знания между сеансами:9Каждый сеанс Claude Code начинается со свежего context window. Два механизма переносят знания между сеансами:

10 10

11* **Файлы CLAUDE.md**: инструкции, которые вы пишете, чтобы дать Claude постоянный контекст. Claude также может читать файлы [`AGENTS.md`](#agents-md) репозитория отдельно или вместе с CLAUDE.md11* **Файлы CLAUDE.md**: инструкции, которые вы пишете, чтобы дать Claude постоянный контекст. Claude также может читать файлы [`AGENTS.md`](#agents-md) репозитория вместо CLAUDE.md

12* **Auto memory**: заметки, которые Claude пишет сам на основе ваших исправлений и предпочтений12* **Auto memory**: заметки, которые Claude пишет сам на основе ваших исправлений и предпочтений

13 13

14На этой странице рассматривается, как:14На этой странице рассматривается, как:

15 15

16* [Писать и организовывать файлы CLAUDE.md](#claude-md-files)16* [Писать и организовывать файлы CLAUDE.md](#claude-md-files)

~~17* [Использовать существующий AGENTS.md](#agents-md) как инструкции вашего проекта отдельно или вместе с CLAUDE.md~~17* [Использовать существующий AGENTS.md](#agents-md) как инструкции вашего проекта

18* [Ограничивать правила определёнными типами файлов](#organize-rules-with-claude/rules/) с помощью `.claude/rules/`18* [Ограничивать правила определёнными типами файлов](#organize-rules-with-claude/rules/) с помощью `.claude/rules/`

19* [Настраивать auto memory](#auto-memory) так, чтобы Claude автоматически делал заметки19* [Настраивать auto memory](#auto-memory) так, чтобы Claude автоматически делал заметки

20* [Устранять неполадки](#troubleshoot-memory-issues) когда инструкции не соблюдаются20* [Устранять неполадки](#troubleshoot-memory-issues) когда инструкции не соблюдаются

overview.md +4 −4

Details

163 claude "commit my changes with a descriptive message"163 claude "commit my changes with a descriptive message"

164 ```164 ```

165 165

166 В CI вы можете автоматизировать проверку кода и сортировку проблем с помощью [GitHub Actions](/docs/ru/github-actions) или [GitLab CI/CD](/docs/ru/gitlab-ci-cd).166 В CI вы можете автоматизировать код-ревью и сортировку проблем с помощью [GitHub Actions](/docs/ru/github-actions) или [GitLab CI/CD](/docs/ru/gitlab-ci-cd).

167 </Accordion>167 </Accordion>

168 168

169 <Accordion title="Подключите свои инструменты с помощью MCP" icon="plug">169 <Accordion title="Подключите свои инструменты с помощью MCP" icon="plug">

170 [Model Context Protocol (MCP)](/docs/ru/mcp) — это открытый стандарт для подключения инструментов AI к внешним источникам данных. С помощью MCP Claude Code может читать ваши документы дизайна в Google Drive, обновлять задачи в Jira, извлекать данные из Slack или использовать ваши собственные пользовательские инструменты. [MCP quickstart](/docs/ru/mcp-quickstart) подключает ваш первый сервер от начала до конца.170 [Model Context Protocol (MCP)](/docs/ru/mcp) — это открытый стандарт для подключения инструментов AI к внешним источникам данных. С помощью MCP Claude Code может читать ваши документы дизайна в Google Drive, обновлять задачи в Jira, извлекать данные из Slack или использовать ваши собственные пользовательские инструменты. [Быстрый старт MCP](/docs/ru/mcp-quickstart) подключает ваш первый сервер от начала до конца.

171 </Accordion>171 </Accordion>

172 172

173 <Accordion title="Настройте с помощью инструкций, skills и hooks" icon="sliders">173 <Accordion title="Настройте с помощью инструкций, скиллов и хуков" icon="sliders">

174 [`CLAUDE.md`](/docs/ru/memory) — это файл markdown, который вы добавляете в корень вашего проекта, и Claude Code читает его в начале каждого сеанса. Используйте его для установки стандартов кодирования, архитектурных решений, предпочитаемых библиотек и контрольных списков проверки. Если ваш репозиторий уже имеет `AGENTS.md` для других агентов кодирования, Claude Code [может читать это](/docs/ru/memory#agents-md) самостоятельно или вместе с `CLAUDE.md`. Claude также создает [auto memory](/docs/ru/memory#auto-memory) по мере работы, сохраняя знания в разных сеансах без необходимости что-либо писать.174 [`CLAUDE.md`](/docs/ru/memory) — это файл markdown, который вы добавляете в корень вашего проекта, и Claude Code читает его в начале каждой сессии. Используйте его для установки стандартов кодирования, архитектурных решений, предпочитаемых библиотек и контрольных списков проверки. Если в вашем репозитории уже есть `AGENTS.md` для других агентов кодирования, Claude Code [может читать его](/docs/ru/memory#agents-md) вместо `CLAUDE.md`. Claude также создает [автоматическую память](/docs/ru/memory#auto-memory) по мере работы, сохраняя знания между сессиями без необходимости что-либо писать.

175 175

176 Создавайте [skills](/docs/ru/skills) для упаковки повторяемых рабочих процессов, которые ваша команда может использовать, например `/review-pr` или `/deploy-staging`.176 Создавайте [skills](/docs/ru/skills) для упаковки повторяемых рабочих процессов, которые ваша команда может использовать, например `/review-pr` или `/deploy-staging`.

177 177

plugins/components.md +1 −1

Details

733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

734```734```

735 735

736Этот агент назван `my-plugin:security-reviewer`, и пользователь может [вызвать его явно](/docs/ru/sub-agents#invoke-subagents-explicitly) с помощью `@agent-my-plugin:security-reviewer`. Форма имени — `<plugin>:<name>`, где `<name>` берётся из frontmatter или из имени файла, когда его нет.736Этот агент называется `my-plugin:security-reviewer`, и пользователь может [вызвать его явно](/docs/ru/sub-agents#invoke-subagents-explicitly) с помощью `@agent-my-plugin:security-reviewer`. Форма имени — `<plugin>:<name>`, где `<name>` берётся из поля `name` во frontmatter или из имени файла, если это поле отсутствует.

737 737

738Ключ `agents` манифеста заменяет сканирование `agents/`.738Ключ `agents` манифеста заменяет сканирование `agents/`.

739 739

plugins/mods/interface.md +5 −3

Details

428 428

429| Элемент | Что он рисует | Где |429| Элемент | Что он рисует | Где |

430| :- | :- | :- |430| :- | :- | :- |

431| `Box` | Контейнер flex. Принимает свойства макета, такие как `flexDirection`, `columnGap`, `padding`, `borderStyle` и `width`. | Везде |431| `Box` | Контейнер flex. Принимает пропсы макета, такие как `flexDirection`, `columnGap`, `padding`, [`borderStyle`](/docs/ru/plugins/mods/reference#box-border-styles) и `width`. | Везде |

432| `Text` | Стилизованный текст. Принимает `color`, `bold`, `dimColor`, `italic` и `wrap`. `color` — это ключ темы или цвет, такой как `'red'`. `wrap` — это `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'` или `'truncate-end'`. | Везде |432| `Text` | Стилизованный текст. Принимает `color`, `bold`, `dimColor`, `italic` и `wrap`. `color` — это ключ темы или цвет, такой как `'red'`. `wrap` — это `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'` или `'truncate-end'`. | Везде |

434| `Link`, `Code`, `Markdown` | Ссылка с `href` и необязательной `label`, блок кода и текст, отформатированный так, как ответы Claude. `Markdown` принимает свое содержимое в свойстве `text`, а не в `children`, и нуждается в `key`, когда вы передаете `onLinkPress`. | Везде |434| `Link`, `Code`, `Markdown` | Ссылка с `href` и необязательной `label`, блок кода и текст, отформатированный так, как ответы Claude. `Markdown` принимает свое содержимое в свойстве `text`, а не в `children`, и нуждается в `key`, когда вы передаете `onLinkPress`. | Везде |

563Многие панели — это текстовое поле со списком под ним. Пример в этом разделе — панель заметок: вы вводите заметку и нажимаете Enter, чтобы добавить ее, и каждая заметка имеет кнопку `x`, которая удаляет ее. С двумя добавленными заметками терминал рисует панель таким образом:563Многие панели — это текстовое поле со списком под ним. Пример в этом разделе — панель заметок: вы вводите заметку и нажимаете Enter, чтобы добавить ее, и каждая заметка имеет кнопку `x`, которая удаляет ее. С двумя добавленными заметками терминал рисует панель таким образом:

564 564

565```text theme={null}565```text theme={null}

566╭──────────────────────────────────────────────────────────╮566╭────────────────────────────────────────────────────────✕─╮

567│ Note: Type a note and press Enter ⏎ add ✕ │567│ Note: Type a note and press Enter ⏎ add │

568│ x buy milk │568│ x buy milk │

569│ x call bob │569│ x call bob │

570╰──────────────────────────────────────────────────────────╯570╰──────────────────────────────────────────────────────────╯

571```571```

572 572

573`✕` на верхней границе — это собственная отметка Claude Code для закрытия панели.

574

573Пример использует следующие техники:575Пример использует следующие техники:

574 576

575* **Получение введенного текста**: `Input` вызывает `onSubmit(value)` с текстом поля, когда пользователь нажимает Enter, и `onInput(value)` при каждом изменении577* **Получение введенного текста**: `Input` вызывает `onSubmit(value)` с текстом поля, когда пользователь нажимает Enter, и `onInput(value)` при каждом изменении

plugins/mods/reference.md +23 −2

Details

242Чтобы подогнать дерево под точку отрисовки, читайте в хуке следующие пропсы:242Чтобы подогнать дерево под точку отрисовки, читайте в хуке следующие пропсы:

243 243

244* **Ширина `Pane` или полосы**: рисуйте по `e.props.bodyColumns`244* **Ширина `Pane` или полосы**: рисуйте по `e.props.bodyColumns`

245* **Высота `Pane` рядом с транскриптом**: когда `e.props.placement` равно `'dock'`, `e.props.scroll.bodyRows` — это число строк панели245* **Высота `Pane` рядом с транскриптом**: когда `e.props.placement` равно `'dock'`, `e.props.scroll.bodyRows` — это число строк, которые панель отводит под ваше дерево

246* **Высота `Pane` над промптом**: когда `e.props.placement` равно `'inline'`, панель растёт вместе с вашим деревом до предела, а `bodyRows` — это этот предел. [Поле `rows` в `$.ui.open`](/docs/ru/plugins/mods/interface#open-a-pane-at-the-right-time) запрашивает другой предел.246* **Высота `Pane` над промптом**: когда `e.props.placement` равно `'inline'`, панель растёт вместе с вашим деревом до предела, а `bodyRows` — это этот предел. [Поле `rows` в `$.ui.open`](/docs/ru/plugins/mods/interface#open-a-pane-at-the-right-time) запрашивает другой предел.

247 247

248Дерево, которое выше панели, прокручивается целиком.248Дерево, которое выше панели, прокручивается целиком.

255 255

257| :- | :- | :-: | :-: |257| :- | :- | :-: | :-: |

258| [`Box`](/docs/ru/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex-раскладка, `gap`, `padding`, `margin`, `width`, `height`, `borderStyle`, `backgroundColor`, `position`, `hover` | ✓ | ✓ |258| [`Box`](/docs/ru/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex-раскладка, `gap`, `padding`, `margin`, `width`, `height`, [`borderStyle`](#box-border-styles), `backgroundColor`, `position`, `hover` | ✓ | ✓ |

259| [`Text`](/docs/ru/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ |259| [`Text`](/docs/ru/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ |

260| [`Button`](/docs/ru/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ |260| [`Button`](/docs/ru/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ |

261| `Link` | `href`, `label` | ✓ | ✓ |261| `Link` | `href`, `label` | ✓ | ✓ |

270 270

271Дополнительные правила для `Button`: `action` указывает одно из собственных [действий сочетаний клавиш](/docs/ru/keybindings) Claude Code, и сочетание, назначенное пользователем для этого действия, нажимает кнопку, если это аккорд или клавиша с модификатором. Цифровой `hotkey` на кнопке в полосе также срабатывает, когда пользователь вводит только эту цифру в пустой промпт и делает паузу. Если две кнопки в одной отрисовке указывают один и тот же `hotkey`, он достаётся более поздней. `autoFocus` на любом элементе управления принимает только `true`, поэтому, чтобы отключить его, опустите этот проп.271Дополнительные правила для `Button`: `action` указывает одно из собственных [действий сочетаний клавиш](/docs/ru/keybindings) Claude Code, и сочетание, назначенное пользователем для этого действия, нажимает кнопку, если это аккорд или клавиша с модификатором. Цифровой `hotkey` на кнопке в полосе также срабатывает, когда пользователь вводит только эту цифру в пустой промпт и делает паузу. Если две кнопки в одной отрисовке указывают один и тот же `hotkey`, он достаётся более поздней. `autoFocus` на любом элементе управления принимает только `true`, поэтому, чтобы отключить его, опустите этот проп.

272 272

273<h3 id="box-border-styles">

274 Стили рамки `Box`

275</h3>

276

277Чтобы нарисовать рамку вокруг `Box`, задайте для его `borderStyle` одно из этих имён, например `borderStyle: 'round'`. В каждой строке указано, что терминал рисует для этого имени, и показан верхний край рамки.

278

279| `borderStyle` | Что рисует терминал | Верхний край |

280| :- | :- | :- |

281| `'single'` | Тонкие линии с прямыми углами | `┌──┐` |

282| `'double'` | Двойные линии | `╔══╗` |

283| `'round'` | Тонкие линии со скруглёнными углами | `╭──╮` |

284| `'bold'` | Толстые линии | `┏━━┓` |

285| `'singleDouble'` | Тонкие линии сверху и снизу, двойные линии по бокам | `╓──╖` |

286| `'doubleSingle'` | Двойные линии сверху и снизу, тонкие линии по бокам | `╒══╕` |

287| `'classic'` | ASCII-символы `+`, `-` и `\|` | `+--+` |

288| `'arrow'` | Стрелки, указывающие внутрь `Box` | `↘↓↓↙` |

289| `'dashed'` | Пунктирные линии с пустыми углами | `╌╌` |

290| `'quote'` | Полоса `▎` вдоль левой стороны и пустые ячейки на остальных трёх сторонах | Пусто |

291

292`Box`, у которого `borderStyle` указывает любое другое имя, например `'rounded'`, рисуется без рамки.

293

273<h2 id="limits">294<h2 id="limits">

274 Ограничения295 Ограничения

275</h2>296</h2>

plugins/troubleshooting.md +2 −1

Details

15<Note>15<Note>

16 Эти случаи рассматриваются на других страницах:16 Эти случаи рассматриваются на других страницах:

17 17

18 * **Почему области видимости, кэш и приоритет ведут себя так, как они себя ведут**: прочитайте [Справочник по загрузке плагинов](/docs/ru/plugins/loading)18 * **Почему области действия, кэш и приоритет ведут себя так, как они себя ведут**: прочитайте [Справочник по загрузке плагинов](/docs/ru/plugins/loading)

19 * **Поиск флага, поля или команды**: используйте [справочник команд плагинов](/docs/ru/plugins/cli-reference), [справочник манифеста](/docs/ru/plugins/manifest-reference) или [справочник маркетплейса](/docs/ru/plugins/marketplace-reference)19 * **Поиск флага, поля или команды**: используйте [справочник команд плагинов](/docs/ru/plugins/cli-reference), [справочник манифеста](/docs/ru/plugins/manifest-reference) или [справочник маркетплейса](/docs/ru/plugins/marketplace-reference)

20 * **Сообщение `hooks module not loaded` или `hooks module did not load`**: плагин является [модом](/docs/ru/plugins/mods/overview), поэтому прочитайте [Мод не загружается](/docs/ru/plugins/mods/troubleshoot#the-mod-doesn’t-load)

20</Note>21</Note>

21 22

22Найдите точное сообщение, которое вы видели. Каждое сообщение указано под этапом, который его создаёт, что не всегда совпадает с командой, которую вы запустили. Например, установка может завершиться ошибкой, потому что маркетплейс отсутствует, поэтому это сообщение находится в разделе [Добавить маркетплейс](#add-a-marketplace).23Найдите точное сообщение, которое вы видели. Каждое сообщение указано под этапом, который его создаёт, что не всегда совпадает с командой, которую вы запустили. Например, установка может завершиться ошибкой, потому что маркетплейс отсутствует, поэтому это сообщение находится в разделе [Добавить маркетплейс](#add-a-marketplace).

quickstart.md +5 −5

Details

33 <Tab title="Встроенная установка (рекомендуется)">33 <Tab title="Встроенная установка (рекомендуется)">

34 **macOS, Linux, WSL:**34 **macOS, Linux, WSL:**

35 35

~~36 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~36 ```bash theme={null}

37 curl -fsSL https://claude.ai/install.sh | bash37 curl -fsSL https://claude.ai/install.sh | bash

38 ```38 ```

39 39

40 **Windows PowerShell:**40 **Windows PowerShell:**

41 41

~~42 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~42 ```powershell theme={null}

43 irm https://claude.ai/install.ps1 | iex43 irm https://claude.ai/install.ps1 | iex

44 ```44 ```

45 45

46 **Windows CMD:**46 **Windows CMD:**

47 47

~~48 ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~48 ```batch theme={null}

49 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd49 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

50 ```50 ```

51 51

63 </Tab>63 </Tab>

64 64

65 <Tab title="Homebrew">65 <Tab title="Homebrew">

~~66 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~66 ```bash theme={null}

67 brew install --cask claude-code67 brew install --cask claude-code

68 ```68 ```

69 69

75 </Tab>75 </Tab>

76 76

77 <Tab title="WinGet">77 <Tab title="WinGet">

~~78 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~78 ```powershell theme={null}

79 winget install Anthropic.ClaudeCode79 winget install Anthropic.ClaudeCode

80 ```80 ```

81 81

self-hosted-environments-testing.md +1 −1

Details

104 Пример скрипта104 Пример скрипта

105</h2>105</h2>

106 106

107Скрипт ниже запускает полный цикл против `$CLAUDE_TEST_ENVIRONMENT_ID`, ID `ccpool_...` вашего тестового окружения, показанный в диалоговом окне деталей окружения на странице администратора или возвращённый вызовом [create-environment](#create-a-dedicated-test-environment), и проверяет наличие фразы-маркера в каждом ответе. Запустите его из git-репозитория, который вы хотите, чтобы сеанс работал, после запуска runner на этом хосте с установленным hook захвата и экспортированным `E2E_REPLY_DIR`.107Скрипт ниже запускает полный цикл против `$CLAUDE_TEST_ENVIRONMENT_ID`, ID `ccpool_...` вашего тестового окружения, показанный в диалоговом окне деталей окружения на странице администратора или возвращённый вызовом [create-environment](#create-a-dedicated-test-environment), и проверяет наличие фразы-маркера в каждом ответе. Запускайте его из git-клона репозитория, в котором должна работать сессия, после запуска runner на этом хосте с установленным хуком захвата и экспортированной переменной `E2E_REPLY_DIR`. Сначала войдите с учётной записью claude.ai на машине, на которой запускается скрипт, как описано в разделе [Аутентификация из CI](#authenticate-from-ci). Без этого входа первая отправка завершится ошибкой, например `Unable to get organization UUID for cloud session creation`.

108 108

109```bash theme={null}109```bash theme={null}

110#!/usr/bin/env bash110#!/usr/bin/env bash

server-managed-settings.md +1 −1

Details

43 <Step title="Откройте консоль администратора">43 <Step title="Откройте консоль администратора">

44 В консоли claude.ai перейдите в [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code).44 В консоли claude.ai перейдите в [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code).

45 45

46 Если ссылка перенаправляет вас на другую страницу Organization settings вместо страницы Claude Code, ваша учетная запись не имеет требуемой роли. Роль Admin и другие роли, отличные от Owner, не могут просматривать или редактировать управляемые настройки, поэтому попросите Owner или Primary Owner в вашей организации внести изменение. См. [Контроль доступа](#access-control).46 Если в организации Team или Enterprise на странице указано, что у вас нет доступа, попросите [Owner или Primary Owner](#access-control) внести изменение.

47 </Step>47 </Step>

48 48

49 <Step title="Определите ваши настройки">49 <Step title="Определите ваши настройки">

sessions.md +3 −3

Details

83* Терминал: `claude --continue`, `claude --resume <session-id>` или `claude --resume <name>`, когда имя соответствует одному сеансу, без `-p`. Claude Code восстанавливает режим разрешений, в котором находился сеанс, за исключением случаев в таблице. Передайте `--permission-mode` или `--dangerously-skip-permissions`, чтобы переопределить восстановленный режим.83* Терминал: `claude --continue`, `claude --resume <session-id>` или `claude --resume <name>`, когда имя соответствует одному сеансу, без `-p`. Claude Code восстанавливает режим разрешений, в котором находился сеанс, за исключением случаев в таблице. Передайте `--permission-mode` или `--dangerously-skip-permissions`, чтобы переопределить восстановленный режим.

84* Неинтерактивный: `claude -p --resume` или `claude -p --continue`. Claude Code запускает выполнение в режиме разрешений, в котором запустился бы новый запуск `claude -p`, за исключением того, что сеанс, который завершился в режиме Plan Mode, возобновляется в режиме Plan Mode при [условиях ниже](#resume-in-plan-mode-with-p).84* Неинтерактивный: `claude -p --resume` или `claude -p --continue`. Claude Code запускает выполнение в режиме разрешений, в котором запустился бы новый запуск `claude -p`, за исключением того, что сеанс, который завершился в режиме Plan Mode, возобновляется в режиме Plan Mode при [условиях ниже](#resume-in-plan-mode-with-p).

85* VS Code: панель диалога расширения. Таблица охватывает только диалог, который завершился в режиме Plan Mode; для остального см. [возобновление прошлых диалогов](/docs/ru/vs-code#resume-past-conversations).85* VS Code: панель диалога расширения. Таблица охватывает только диалог, который завершился в режиме Plan Mode; для остального см. [возобновление прошлых диалогов](/docs/ru/vs-code#resume-past-conversations).

86* Средство выбора сеансов при запуске: сеанс, который вы выбираете из [средства выбора сеансов](#use-the-session-picker), независимо от того, открыли ли вы его с помощью `claude --resume` отдельно, `claude --from-pr` или имени, которое соответствует более чем одному сеансу. Claude Code не восстанавливает сохранённый режим разрешений. Он запускает сеанс в режиме разрешений, в котором он запустил бы новый сеанс из той же командной строки.86* Средство выбора сессий при запуске: сессия, которую вы выбираете в [средстве выбора сессий](#use-the-session-picker), независимо от того, открыли ли вы его с помощью одного `claude --resume`, `claude --from-pr` или имени, соответствующего нескольким сессиям. Claude Code запускает сессию в том режиме разрешений, в котором запустил бы новую сессию из той же командной строки, за исключением того, что сессия, завершившаяся в режиме планирования, возобновляется в режиме планирования, если вы не передали `--permission-mode`, `--dangerously-skip-permissions` или `--fork-session`. Никакой другой сохранённый режим разрешений не восстанавливается.

87* `/resume` внутри сеанса, с аргументом или без: Claude Code не восстанавливает сохранённый режим разрешений. Диалог, на который вы переключаетесь, продолжается в режиме разрешений, в котором находится ваш текущий сеанс.87* `/resume` внутри сессии, с аргументом или без: диалог, на который вы переключаетесь, продолжается в режиме разрешений вашей текущей сессии, за исключением того, что диалог, завершившийся в режиме планирования, возобновляется в режиме планирования, даже если вы запустили Claude Code с `--permission-mode` или `--dangerously-skip-permissions`. Если этот диалог уже открывался ранее в текущем запуске Claude Code, например диалог, с которого вы начали, или диалог, который вы покинули с помощью `/clear` или `/resume`, он вместо этого продолжается в вашем текущем режиме разрешений.

88 88

89Восстановление режима Plan Mode на неинтерактивном пути и пути VS Code требует Claude Code v2.1.246 или более поздней версии. Каждая строка называет режим разрешений, в котором завершился сеанс, какой из путей терминала, неинтерактивного и VS Code вы его возобновляете, и режим разрешений, в котором Claude Code запускает возобновлённый сеанс.89Восстановление режима Plan Mode на неинтерактивном пути и пути VS Code требует Claude Code v2.1.246 или более поздней версии. Каждая строка называет режим разрешений, в котором завершился сеанс, какой из путей терминала, неинтерактивного и VS Code вы его возобновляете, и режим разрешений, в котором Claude Code запускает возобновлённый сеанс.

90 90

92| :- | :- | :- |92| :- | :- | :- |

93| `bypassPermissions` | Терминал | Режим разрешений, в котором запустился бы новый сеанс. Чтобы [пропустить разрешения](/docs/ru/permission-modes#skip-all-checks-with-bypasspermissions-mode) снова, включите его при запуске с одним из его флагов запуска или `permissions.defaultMode: "bypassPermissions"` в [пользовательских, `--settings` или управляемых параметрах](/docs/ru/settings-reference#permissions-defaultmode) |93| `bypassPermissions` | Терминал | Режим разрешений, в котором запустился бы новый сеанс. Чтобы [пропустить разрешения](/docs/ru/permission-modes#skip-all-checks-with-bypasspermissions-mode) снова, включите его при запуске с одним из его флагов запуска или `permissions.defaultMode: "bypassPermissions"` в [пользовательских, `--settings` или управляемых параметрах](/docs/ru/settings-reference#permissions-defaultmode) |

95| `auto` | Терминал | `auto`, только когда ваша учётная запись всё ещё соответствует [требованиям режима auto](/docs/ru/permission-modes#eliminate-prompts-with-auto-mode) |95| `auto` | Терминал | `auto`, только когда ваша учётная запись всё ещё соответствует [требованиям режима auto](/docs/ru/permission-modes#eliminate-prompts-with-auto-mode) |

96| Manual | Терминал | Manual, когда новый сеанс запустился бы в режиме auto из [встроенного значения по умолчанию](/docs/ru/permission-modes#which-mode-a-session-starts-in). Когда `defaultMode` из файла параметров [вступает в силу](/docs/ru/permission-modes#which-mode-a-session-starts-in), Claude Code запускает возобновлённый сеанс в этом режиме вместо этого |96| Manual | Терминал | Manual, когда новый сеанс запустился бы в режиме auto из [встроенного значения по умолчанию](/docs/ru/permission-modes#which-mode-a-session-starts-in). Когда `defaultMode` из файла параметров [вступает в силу](/docs/ru/permission-modes#which-mode-a-session-starts-in), Claude Code запускает возобновлённый сеанс в этом режиме вместо этого |

sub-agents.md +2 −2

Details

310 310

312| :- | :- | :- |312| :- | :- | :- |

313| `name` | Да | Уникальный идентификатор, такой как `code-reviewer` или `reviewer-v2`. [Hooks](/docs/ru/hooks#subagentstart) получают это значение как `agent_type`. Имя файла не должно совпадать. Имена не могут содержать `:`, который зарезервирован для [plugin-scoped identifiers](/docs/ru/plugins/overview) таких как `my-plugin:reviewer`. Claude Code не загружает файл, чьё имя содержит один, и регистрирует ошибку в журнал отладки. До версии 2.1.218 такие имена были приняты |313| `name` | Да | Уникальный идентификатор длиной не более 256 символов, например `code-reviewer` или `reviewer-v2`. [Хуки](/docs/ru/hooks#subagentstart) получают это значение как `agent_type`. Имя файла не обязано совпадать. Имена не могут содержать `:`, который зарезервирован для [идентификаторов с областью действия плагина](/docs/ru/plugins/overview), таких как `my-plugin:reviewer` |

314| `description` | Да | Когда Claude должен делегировать этому subagent |314| `description` | Да | Когда Claude должен делегировать этому subagent |

315| `tools` | Нет | [Инструменты](#available-tools), которые может использовать subagent, как строка, разделённая запятыми, такая как `Read, Grep, Bash` или список YAML. Наследует каждый инструмент, доступный для subagents, если опущено. Если ни один элемент в списке не разрешается в инструмент, subagent обычно [не запускается](/docs/ru/errors#agent-would-be-spawned-with-zero-tools) с ошибкой, называющей элементы. Чтобы предварительно загрузить Skills в контекст, используйте поле `skills` вместо перечисления `Skill` здесь |315| `tools` | Нет | [Инструменты](#available-tools), которые может использовать subagent, как строка, разделённая запятыми, такая как `Read, Grep, Bash` или список YAML. Наследует каждый инструмент, доступный для subagents, если опущено. Если ни один элемент в списке не разрешается в инструмент, subagent обычно [не запускается](/docs/ru/errors#agent-would-be-spawned-with-zero-tools) с ошибкой, называющей элементы. Чтобы предварительно загрузить Skills в контекст, используйте поле `skills` вместо перечисления `Skill` здесь |

316| `disallowedTools` | Нет | Инструменты для запрета, удалённые из унаследованного или указанного списка. Тот же формат, что и `tools`. Запись со спецификатором, такая как `Bash(git push *)`, по-прежнему [удаляет весь инструмент](#available-tools) |316| `disallowedTools` | Нет | Инструменты для запрета, удалённые из унаследованного или указанного списка. Тот же формат, что и `tools`. Запись со спецификатором, такая как `Bash(git push *)`, по-прежнему [удаляет весь инструмент](#available-tools) |

348 348

349* **Нет `name`**: Claude Code рассматривает файл как документацию, хранящуюся рядом с вашими агентами.349* **Нет `name`**: Claude Code рассматривает файл как документацию, хранящуюся рядом с вашими агентами.

350* **Открывающий `---`, который не является первой строкой файла**: Claude Code читает файл как не имеющий frontmatter и рассматривает его как документацию.350* **Открывающий `---`, который не является первой строкой файла**: Claude Code читает файл как не имеющий frontmatter и рассматривает его как документацию.

351* **`name`, который начинается с `-` или содержит `:`**: Claude Code пропускает файл и записывает ошибку в журнал отладки. См. строку `name` в таблице выше.351* **`name` начинается с `-`, содержит `:` или длиннее 256 символов**: Claude Code пропускает файл и записывает ошибку в лог отладки.

352* **`name`, но нет `description`**: Claude Code пропускает файл и записывает причину в журнал отладки.352* **`name`, но нет `description`**: Claude Code пропускает файл и записывает причину в журнал отладки.

353* **YAML, который не парсится**: Claude Code не читает никакие поля из файла, пропускает его и записывает ошибку парсинга в журнал отладки.353* **YAML, который не парсится**: Claude Code не читает никакие поля из файла, пропускает его и записывает ошибку парсинга в журнал отладки.

354 354

vs-code.md +1 −1

Details

606| `environmentVariables` | `[]` | Установить переменные окружения для процесса Claude. Используйте параметры Claude Code вместо этого для общей конфигурации. Запись [`CLAUDE_CONFIG_DIR`](/docs/ru/env-vars) применяется только в том случае, если её значение является абсолютным путём; расширение не раскрывает `~` и игнорирует относительное значение. |606| `environmentVariables` | `[]` | Установить переменные окружения для процесса Claude. Используйте параметры Claude Code вместо этого для общей конфигурации. Запись [`CLAUDE_CONFIG_DIR`](/docs/ru/env-vars) применяется только в том случае, если её значение является абсолютным путём; расширение не раскрывает `~` и игнорирует относительное значение. |

609| `claudeProcessWrapper` | - | Исполняемый файл, используемый для запуска процесса Claude. Путь к встроенному двоичному файлу передаётся в качестве аргумента при наличии. Установите это на отдельно установленный двоичный файл `claude`, если сборка расширения не включает его для вашей платформы. В обёрнутой установке беседы начинаются в режиме Manual, если вы не установили `initialPermissionMode` или не выбрали Manual, Edit automatically или Auto в более ранней беседе, потому что расширение пропускает параметры и встроенные шаги по умолчанию там; см. [Switch permission modes](/docs/ru/permission-modes#switch-permission-modes). Ошибка "Unsupported platform" при активации означает, что для вашей платформы не встроен двоичный файл; см. [какие платформы имеют предварительно собранные двоичные файлы](/docs/ru/troubleshoot-install#native-binary-not-found-after-npm-install). |609| `claudeProcessWrapper` | - | Исполняемый файл, используемый для запуска процесса Claude. Путь к встроенному двоичному файлу передаётся в качестве аргумента при наличии. Установите это на отдельно установленный двоичный файл `claude`, если сборка расширения не включает его для вашей платформы. |

610 610

611<h2 id="use-a-screen-reader">611<h2 id="use-a-screen-reader">

612 Использование программы чтения с экрана612 Использование программы чтения с экрана

worktrees.md +3 −1

Details

6 6

7> Изолируйте параллельные сеансы Claude Code в отдельных git worktrees, чтобы изменения не конфликтовали. Охватывает флаг `--worktree`, изоляцию subagent, `.worktreeinclude`, очистку и hooks для не-git VCS.7> Изолируйте параллельные сеансы Claude Code в отдельных git worktrees, чтобы изменения не конфликтовали. Охватывает флаг `--worktree`, изоляцию subagent, `.worktreeinclude`, очистку и hooks для не-git VCS.

8 8

9[git worktree](https://git-scm.com/docs/git-worktree) — это отдельный рабочий каталог с собственными файлами и веткой, использующий ту же историю репозитория и удалённый сервер, что и ваша основная копия. Запуск каждого сеанса Claude Code в собственном worktree означает, что правки в одном сеансе никогда не затрагивают файлы в другом, поэтому один сеанс может создавать функцию, а второй исправлять ошибку.9[git worktree](https://git-scm.com/docs/git-worktree) — это отдельный рабочий каталог с собственными файлами и веткой, использующий ту же историю репозитория и удалённый сервер, что и ваша основная копия. Запуск каждой сессии Claude Code в собственном worktree даёт ей отдельную копию файлов для редактирования, поэтому одна сессия может создавать функцию, а вторая исправлять ошибку.

10 10

11<Note>11<Note>

12 Worktrees требуют git-репозитория; для других систем контроля версий [настройте hooks для замены логики git](#non-git-version-control). В [десктопном приложении](/docs/ru/desktop#work-in-parallel-with-sessions) выберите опцию **worktree** при запуске сеанса, чтобы дать ему собственный worktree.12 Worktrees требуют git-репозитория; для других систем контроля версий [настройте hooks для замены логики git](#non-git-version-control). В [десктопном приложении](/docs/ru/desktop#work-in-parallel-with-sessions) выберите опцию **worktree** при запуске сеанса, чтобы дать ему собственный worktree.

104* **Перенаправления git**: Claude Code блокирует команду Bash или Monitor, которая перенаправляет git в основную копию. Перенаправление может поступать через `git -C`, `--git-dir`, переменную `GIT_DIR` или `GIT_WORK_TREE` или `cd` в основную копию перед запуском git.104* **Перенаправления git**: Claude Code блокирует команду Bash или Monitor, которая перенаправляет git в основную копию. Перенаправление может поступать через `git -C`, `--git-dir`, переменную `GIT_DIR` или `GIT_WORK_TREE` или `cd` в основную копию перед запуском git.

105* **Форма команды**: Claude Code блокирует команду Bash или Monitor, когда он не может проверить из текста команды, что любой git, который запускает команда, остаётся внутри worktree. Это происходит, например, когда имя команды вычисляется во время выполнения, когда синтаксис не может быть проанализирован, или когда расширение, такое как `${!name}` или `${ command; }`, может запустить команду, которую текст не указывает явно. Claude Code сообщает Claude, как переписать отказанную команду, например разделив её на простые отдельные команды. Вы не можете отключить эту проверку.105* **Форма команды**: Claude Code блокирует команду Bash или Monitor, когда он не может проверить из текста команды, что любой git, который запускает команда, остаётся внутри worktree. Это происходит, например, когда имя команды вычисляется во время выполнения, когда синтаксис не может быть проанализирован, или когда расширение, такое как `${!name}` или `${ command; }`, может запустить команду, которую текст не указывает явно. Claude Code сообщает Claude, как переписать отказанную команду, например разделив её на простые отдельные команды. Вы не можете отключить эту проверку.

106 106

107Эти проверки считывают путь, на который нацелена правка, каталог, в котором выполняется команда, и текст команды. Ни одна из них не отслеживает, какие файлы записывает shell-команда, поэтому команда, которая записывает в основную копию, не запуская там git, например `cp` или перенаправление оболочки, ими не отклоняется. Claude Code обрабатывает такую команду как любую другую shell-команду, поэтому будет ли она выполнена или запросит у вас подтверждение, зависит от вашего [режима разрешений](/docs/ru/permission-modes) и правил.

108

107Проверки применяются к репозиторию, из которого вы запустили Claude Code. Они также охватывают основную копию, на которую ссылается связанный worktree. Для команд PowerShell Claude Code применяет только проверку рабочего каталога.109Проверки применяются к репозиторию, из которого вы запустили Claude Code. Они также охватывают основную копию, на которую ссылается связанный worktree. Для команд PowerShell Claude Code применяет только проверку рабочего каталога.

108 110

109Claude видит каждый отказ как ошибку инструмента, которая называет worktree и говорит, как продолжить. Для отказанной команды см. [что означает сообщение об отказе и как его очистить](/docs/ru/errors#command-blocked-by-the-worktree-isolation-checks).111Claude видит каждый отказ как ошибку инструмента, которая называет worktree и говорит, как продолжить. Для отказанной команды см. [что означает сообщение об отказе и как его очистить](/docs/ru/errors#command-blocked-by-the-worktree-isolation-checks).

Documentation 2026-10-06 23:59 UTC to 2026-10-07 17:58 UTC