openclaw agent

Выполняет один ход агента через Gateway. Если запрос к Gateway завершается ошибкой, используется встроенный агент; передайте --local, чтобы сразу принудительно использовать встроенное выполнение.

Передайте хотя бы один селектор сеанса: --to, --session-key, --session-id или --agent.

См. также: Инструмент отправки агенту

Параметры

• -m, --message <text>: текст сообщения
• --message-file <path>: прочитать текст сообщения из файла UTF-8
• -t, --to <dest>: получатель, используемый для формирования ключа сеанса
• --session-key <key>: явный ключ сеанса для маршрутизации
• --session-id <id>: явный идентификатор сеанса
• --agent <id>: идентификатор агента; переопределяет привязки маршрутизации
• --model <id>: переопределение модели для этого запуска (provider/model или идентификатор модели)
• --thinking <level>: уровень рассуждений агента (off, minimal, low, medium, high, а также поддерживаемые провайдером пользовательские уровни, например xhigh, adaptive или max)
• --verbose <on|off>: сохранить уровень подробности для сеанса
• --channel <channel>: канал доставки; не указывайте, чтобы использовать основной канал сеанса
• --reply-to <target>: переопределение цели доставки
• --reply-channel <channel>: переопределение канала доставки
• --reply-account <id>: переопределение учётной записи доставки
• --local: запустить встроенного агента напрямую (после предварительной загрузки реестра плагинов)
• --deliver: отправить ответ обратно в выбранный канал или выбранной цели
• --timeout <seconds>: переопределить время ожидания агента (по умолчанию 600 или agents.defaults.timeoutSeconds); 0 отключает время ожидания
• --json: вывести JSON

Примеры

openclaw agent --to +15555550123 --message "обновление статуса" --deliveropenclaw agent --agent ops --message "Суммируй журналы"openclaw agent --agent ops --message-file ./task.mdopenclaw 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 mediumopenclaw agent --to +15555550123 --message "Проследи журналы" --verbose on --jsonopenclaw 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 <key> для Compaction).
• --local и запуски с резервным переходом на встроенного агента являются одноразовыми: встроенные ресурсы обратной связи MCP и активные сеансы Claude stdio, открытые для запуска, завершаются после ответа, поэтому вызовы из скриптов не оставляют локальные дочерние процессы запущенными. При запусках через Gateway ресурсы обратной связи MCP, принадлежащие Gateway, остаются в работающем процессе Gateway.
• При совместном использовании --agent, --channel и --to маршрутизация сеанса следует каноническому получателю канала и session.dmScope. Каналы со стабильной идентичностью получателя, используемой только для исходящих сообщений, применяют принадлежащий провайдеру сеанс, изолированный от основного сеанса агента. --reply-channel и --reply-account влияют только на доставку.
• --session-key выбирает явный ключ сеанса. Ключи с префиксом агента должны использовать agent:<agent-id>:<session-key>, а --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, чтобы скрипты могли различать выполненную, подавленную, частично выполненную и неудачную отправку:

{  "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 принимает одно из следующих значений:

Общие поля:

• 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
• Среда выполнения агента