--- read_when: - Вы хотите запустить один цикл агента из скриптов (при необходимости доставив ответ) summary: Справочник CLI для `openclaw agent` (отправка одного хода агента через Gateway) title: Агент x-i18n: generated_at: "2026-07-13T19:36:15Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 2e137c037a2fa58ac6534adbf1603218fc695e4c61e6c3118ce2c4ec6f1f2143 source_path: cli/agent.md workflow: 16 --- # `openclaw agent` Выполняет один ход агента через Gateway. Если запрос к Gateway завершается ошибкой, используется встроенный агент; передайте `--local`, чтобы сразу принудительно использовать встроенное выполнение. Передайте хотя бы один селектор сеанса: `--to`, `--session-key`, `--session-id` или `--agent`. См. также: [Инструмент отправки агенту](/ru/tools/agent-send) ## Параметры - `-m, --message `: текст сообщения - `--message-file `: прочитать текст сообщения из файла UTF-8 - `-t, --to `: получатель, используемый для формирования ключа сеанса - `--session-key `: явный ключ сеанса для маршрутизации - `--session-id `: явный идентификатор сеанса - `--agent `: идентификатор агента; переопределяет привязки маршрутизации - `--model `: переопределение модели для этого запуска (`provider/model` или идентификатор модели) - `--thinking `: уровень рассуждений агента (`off`, `minimal`, `low`, `medium`, `high`, а также поддерживаемые провайдером пользовательские уровни, например `xhigh`, `adaptive` или `max`) - `--verbose `: сохранить уровень подробности для сеанса - `--channel `: канал доставки; не указывайте, чтобы использовать основной канал сеанса - `--reply-to `: переопределение цели доставки - `--reply-channel `: переопределение канала доставки - `--reply-account `: переопределение учётной записи доставки - `--local`: запустить встроенного агента напрямую (после предварительной загрузки реестра плагинов) - `--deliver`: отправить ответ обратно в выбранный канал или выбранной цели - `--timeout `: переопределить время ожидания агента (по умолчанию 600 или `agents.defaults.timeoutSeconds`); `0` отключает время ожидания - `--json`: вывести JSON ## Примеры ```bash openclaw agent --to +15555550123 --message "обновление статуса" --deliver openclaw agent --agent ops --message "Суммируй журналы" openclaw agent --agent ops --message-file ./task.md openclaw agent --agent ops --model openai/gpt-5.4 --message "Суммируй журналы" openclaw agent --session-key agent:ops:incident-42 --message "Суммируй статус" openclaw agent --agent ops --session-key incident-42 --message "Суммируй статус" openclaw agent --session-id 1234 --message "Суммируй входящие сообщения" --thinking medium openclaw agent --to +15555550123 --message "Проследи журналы" --verbose on --json openclaw agent --agent ops --message "Создай отчёт" --deliver --reply-channel slack --reply-to "#reports" openclaw agent --agent ops --message "Запусти локально" --local ``` ## Примечания - Передайте ровно один из параметров: `--message` или `--message-file`. `--message-file` удаляет начальную метку BOM UTF-8 и сохраняет многострочное содержимое; файлы с недопустимой кодировкой UTF-8 отклоняются. - Команды с косой чертой (например, `/compact`) нельзя запускать через `--message`. CLI отклоняет их и вместо этого указывает соответствующую полноценную команду (`openclaw sessions compact ` для Compaction). - `--local` и запуски с резервным переходом на встроенного агента являются одноразовыми: встроенные ресурсы обратной связи MCP и активные сеансы Claude stdio, открытые для запуска, завершаются после ответа, поэтому вызовы из скриптов не оставляют локальные дочерние процессы запущенными. При запусках через Gateway ресурсы обратной связи MCP, принадлежащие Gateway, остаются в работающем процессе Gateway. - При совместном использовании `--agent`, `--channel` и `--to` маршрутизация сеанса следует каноническому получателю канала и `session.dmScope`. Каналы со стабильной идентичностью получателя, используемой только для исходящих сообщений, применяют принадлежащий провайдеру сеанс, изолированный от основного сеанса агента. `--reply-channel` и `--reply-account` влияют только на доставку. - `--session-key` выбирает явный ключ сеанса. Ключи с префиксом агента должны использовать `agent::`, а `--agent` должен соответствовать идентификатору агента в ключе, если указаны оба значения. Простые ключи, не являющиеся сигнальными, ограничиваются областью `--agent`, если он указан, или областью настроенного агента по умолчанию в противном случае; например, `--agent ops --session-key incident-42` направляется в `agent:ops:incident-42`. Литеральные ключи `global` и `unknown` остаются без области только тогда, когда `--agent` не указан. - `--json` резервирует stdout для ответа JSON; диагностические сообщения Gateway, плагинов и резервного перехода на встроенного агента выводятся в stderr, чтобы скрипты могли напрямую разбирать stdout. - JSON резервного перехода на встроенного агента содержит `meta.transport: "embedded"` и `meta.fallbackFrom: "gateway"`, чтобы скрипты могли обнаружить такой запуск. - Если Gateway принимает запуск, но время ожидания CLI истекает до получения окончательного ответа, резервный переход на встроенного агента использует новый идентификатор сеанса или запуска `gateway-fallback-*` и сообщает `meta.fallbackReason: "gateway_timeout"` вместе с полями резервного сеанса вместо конкуренции с принадлежащей Gateway расшифровкой или незаметной замены исходного сеанса. - `SIGTERM`/`SIGINT` прерывают ожидающий запрос через Gateway; если Gateway уже принял запуск, CLI перед завершением также отправляет `chat.abort` для идентификатора этого запуска. `--local` и запуски с резервным переходом на встроенного агента получают тот же сигнал, но не отправляют `chat.abort`. Если для внутреннего ключа дедупликации запусков уже существует активный запуск этого сеанса, ответ сообщает `status: "in_flight"`, а CLI без JSON выводит диагностическое сообщение в stderr вместо пустого ответа. Для внешних обёрток cron/systemd оставляйте резервное принудительное завершение, например `timeout -k 60 600 openclaw agent ...`, чтобы супервизор мог завершить процесс, если при остановке не удаётся дождаться завершения операций. - Когда эта команда запускает повторное создание `models.json`, управляемые SecretRef учётные данные провайдера сохраняются как несекретные маркеры (например, имена переменных окружения, `secretref-env:ENV_VAR_NAME` или `secretref-managed`), а не как открытый текст разрешённых секретов. Маркеры записываются из активного снимка исходной конфигурации, а не из разрешённых значений секретов среды выполнения. ## Статус доставки JSON При использовании `--json --deliver` ответ JSON от CLI содержит поле верхнего уровня `deliveryStatus`, чтобы скрипты могли различать выполненную, подавленную, частично выполненную и неудачную отправку: ```json { "payloads": [{ "text": "Отчёт готов", "mediaUrl": null }], "meta": { "durationMs": 1200 }, "deliveryStatus": { "requested": true, "attempted": true, "status": "sent", "succeeded": true, "resultCount": 1 } } ``` Ответы CLI через Gateway также сохраняют исходную структуру результата Gateway в `result.deliveryStatus`. `deliveryStatus.status` принимает одно из следующих значений: | Статус | Значение | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `sent` | Доставка завершена. | | `suppressed` | Доставка намеренно не выполнена (например, её отменил хук отправки сообщений или видимый результат отсутствовал). Конечное состояние, повторная попытка не выполняется. | | `partial_failed` | До сбоя при отправке последующей полезной нагрузки была отправлена хотя бы одна полезная нагрузка. | | `failed` | Ни одна надёжная отправка не завершена или предварительная проверка доставки завершилась ошибкой. | Общие поля: - `requested`: всегда `true`, если объект присутствует. - `attempted`: `true` после выполнения пути надёжной отправки; `false` при ошибках предварительной проверки или отсутствии видимых полезных нагрузок. - `succeeded`: `true`, `false` или `"partial"`; `"partial"` используется вместе с `status: "partial_failed"`. - `reason`: причина в нижнем регистре и формате snake_case, полученная при надёжной доставке или предварительной проверке. Известные значения: `cancelled_by_message_sending_hook`, `no_visible_payload`, `no_visible_result`, `channel_resolved_to_internal`, `unknown_channel`, `invalid_delivery_target` и `no_delivery_target`; при неудачных надёжных отправках также может указываться этап, завершившийся ошибкой. Рассматривайте неизвестные значения как непрозрачные, поскольку набор может расширяться. - `resultCount`: количество результатов отправки в канал, если доступно. - `sentBeforeError`: `true`, если при частичном сбое до возникновения ошибки была отправлена хотя бы одна полезная нагрузка. - `error`: `true` для неудачных или частично неудачных отправок. - `errorMessage`: присутствует только в том случае, если удалось получить сообщение о базовой ошибке доставки. Ошибки предварительной проверки содержат `error`/`reason`, но не `errorMessage`. - `payloadOutcomes`: необязательные результаты для отдельных полезных нагрузок с `index`, `status`, `reason`, `resultCount`, `error`, `stage`, `sentBeforeError` или метаданными хука, если они доступны. ## См. также - [Справочник CLI](/ru/cli) - [Среда выполнения агента](/ru/concepts/agent)