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 "status update" --deliveropenclaw agent --agent ops --message "Summarize logs"openclaw agent --agent ops --message-file ./task.mdopenclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"openclaw agent --agent ops --session-key incident-42 --message "Summarize status"openclaw agent --session-id 1234 --message "Summarize inbox" --thinking mediumopenclaw agent --to +15555550123 --message "Trace logs" --verbose on --jsonopenclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"openclaw agent --agent ops --message "Run locally" --local

Примітки

• Передавайте рівно один із параметрів --message або --message-file. --message-file видаляє початкову позначку BOM UTF-8 і зберігає багаторядковий вміст; файли з некоректним кодуванням UTF-8 відхиляються.
• Команди з косою рискою (наприклад, /compact) не можна запускати через --message. CLI відхиляє їх і натомість указує на спеціалізовану команду (openclaw sessions compact <key> для ущільнення).
• Запуски з --local і вбудованим резервним виконанням є одноразовими: вбудовані ресурси зворотного підключення MCP і прогріті stdio-сеанси Claude, відкриті для запуску, завершуються після відповіді, тому сценарні виклики не залишають локальні дочірні процеси запущеними. Натомість під час запусків через 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 відповідь CLI у форматі JSON містить поле верхнього рівня deliveryStatus, щоб сценарії могли розрізняти успішну, пригнічену, часткову та невдалу доставку:

{  "payloads": [{ "text": "Report ready", "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: причина в нижньому регістрі зі словами, розділеними підкресленнями, отримана від надійної доставки або перевірки перед доставкою. Відомі значення: 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
• Середовище виконання агента