---
read_when:
    - Ви хочете запустити один хід агента зі скриптів (необов’язково доставити відповідь)
summary: Довідка CLI для `openclaw agent` (надсилання одного ходу агента через Gateway)
title: Агент
x-i18n:
    generated_at: "2026-05-11T20:26:20Z"
    model: gpt-5.5
    provider: openai
    source_hash: ae5c2f895cadf70a6253e49a3c7c698a04840a24231076cf8ef5bab340162f52
    source_path: cli/agent.md
    workflow: 16
---

# `openclaw agent`

Запустіть хід агента через Gateway (використовуйте `--local` для вбудованого режиму).
Використовуйте `--agent <id>`, щоб напряму вибрати налаштованого агента.

Передайте принаймні один селектор сеансу:

- `--to <dest>`
- `--session-id <id>`
- `--agent <id>`

Пов’язано:

- Інструмент надсилання агента: [Надсилання агента](/uk/tools/agent-send)

## Параметри

- `-m, --message <text>`: обов’язковий текст повідомлення
- `-t, --to <dest>`: одержувач, який використовується для формування ключа сеансу
- `--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`: запустити вбудованого агента напряму (після попереднього завантаження реєстру Plugin)
- `--deliver`: надіслати відповідь назад у вибраний канал/ціль
- `--timeout <seconds>`: перевизначити тайм-аут агента (типово 600 або значення з конфігурації)
- `--json`: вивести JSON

## Приклади

```bash
openclaw agent --to +15555550123 --message "status update" --deliver
openclaw agent --agent ops --message "Summarize logs"
openclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
openclaw agent --agent ops --message "Run locally" --local
```

## Примітки

- Режим Gateway повертається до вбудованого агента, коли запит до Gateway не вдається. Використовуйте `--local`, щоб примусово запустити вбудоване виконання із самого початку.
- `--local` усе одно спочатку попередньо завантажує реєстр Plugin, тому провайдери, інструменти й канали, надані Plugin, залишаються доступними під час вбудованих запусків.
- `--local` і вбудовані резервні запуски вважаються одноразовими. Пакетні ресурси local loopback MCP і теплі stdio-сеанси Claude, відкриті для цього локального процесу, завершуються після відповіді, тому скриптові виклики не залишають локальні дочірні процеси активними.
- Запуски на базі Gateway залишають ресурси MCP loopback, якими володіє Gateway, у запущеному процесі Gateway; старіші клієнти все ще можуть надсилати історичний прапорець очищення, але Gateway приймає його як сумісну операцію без дії.
- `--channel`, `--reply-channel` і `--reply-account` впливають на доставку відповіді, а не на маршрутизацію сеансу.
- `--json` залишає stdout зарезервованим для JSON-відповіді. Діагностика Gateway, Plugin і вбудованого резервного режиму спрямовується в stderr, щоб скрипти могли напряму розбирати stdout.
- JSON вбудованого резервного режиму містить `meta.transport: "embedded"` і `meta.fallbackFrom: "gateway"`, щоб скрипти могли відрізняти резервні запуски від запусків Gateway.
- Якщо Gateway приймає запуск агента, але CLI вичерпує час очікування фінальної відповіді, вбудований резервний режим використовує свіжий явний ідентифікатор сеансу/запуску `gateway-fallback-*` і повідомляє `meta.fallbackReason: "gateway_timeout"` разом із полями резервного сеансу. Це дає змогу уникнути змагання за блокування транскрипту, яким володіє Gateway, або тихої заміни початкового маршрутизованого сеансу розмови.
- Коли ця команда запускає повторне створення `models.json`, облікові дані провайдера, керовані SecretRef, зберігаються як несекретні маркери (наприклад, назви змінних середовища, `secretref-env:ENV_VAR_NAME` або `secretref-managed`), а не як розкритий секретний відкритий текст.
- Записи маркерів є авторитетними щодо джерела: OpenClaw зберігає маркери з активного знімка конфігурації джерела, а не з розкритих секретних значень runtime.

## Стан доставки JSON

Коли використовується `--json --deliver`, JSON-відповідь CLI може містити верхньорівневий `deliveryStatus`, щоб скрипти могли розрізняти доставлені, пригнічені, часткові й невдалі надсилання:

```json
{
  "payloads": [{ "text": "Report ready", "mediaUrl": null }],
  "meta": { "durationMs": 1200 },
  "deliveryStatus": {
    "requested": true,
    "attempted": true,
    "status": "sent",
    "succeeded": true,
    "resultCount": 1
  }
}
```

`deliveryStatus.status` має одне зі значень: `sent`, `suppressed`, `partial_failed` або `failed`. `suppressed` означає, що доставку навмисно не було надіслано, наприклад, її скасував hook надсилання повідомлення або не було видимого результату; це все одно кінцевий результат без повторних спроб. `partial_failed` означає, що принаймні одне корисне навантаження було надіслано до того, як пізніше корисне навантаження завершилося помилкою. `failed` означає, що жодне стале надсилання не завершилося або передперевірка доставки не вдалася.

CLI-відповіді на базі Gateway також зберігають початкову форму результату Gateway, де той самий об’єкт доступний у `result.deliveryStatus`.

Спільні поля:

- `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` або метаданими hook, якщо доступно.

## Пов’язано

- [Довідник CLI](/uk/cli)
- [Runtime агента](/uk/concepts/agent)