Agent Send: CLI Agent Turns

openclaw agent executes a single agent turn directly from the command line, with no incoming chat message required. It suits scripted workflows, testing, and automated delivery. For the complete set of flags and behavior details, see the Agent CLI reference.

When you need strict, short-lived CI or coding automation that manages its own setup, cleanup, output projection, and process exit status, turn to openclaw agent exec.

Quick start

Run a simple agent turn

openclaw agent --agent main --message "What is the weather today?"

The message is transmitted via the Gateway, and the response is displayed.

Send a multiline prompt from a file

openclaw agent --agent ops --message-file ./task.md

A valid UTF-8 file is loaded and used as the agent message body.

Target a specific agent or session

# Target a specific agent
openclaw agent --agent ops --message "Summarize logs"

# Target a phone number (derives session key)
openclaw agent --to +15555550123 --message "Status update"

# Reuse an existing session
openclaw agent --session-id abc123 --message "Continue the task"

# Target an exact session key
openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"

Deliver the reply to a channel

# Deliver to WhatsApp (default channel)
openclaw agent --to +15555550123 --message "Report ready" --deliver

# Deliver to Slack
openclaw agent --agent ops --message "Generate report" \
  --deliver --reply-channel slack --reply-to "#reports"

Flags

Flag	Description
`--message <text>`	Message supplied inline for sending
`--message-file <path>`	Message content pulled from a valid UTF-8 file (capped at 4 MiB)
`--to <dest>`	Session key generated from a target such as phone or chat id
`--session-key <key>`	A specific session key is applied
`--agent <id>`	Point to a configured agent, using its `main` session
`--session-id <id>`	An existing session is reused via its id
`--model <id>`	Model override for this execution (`provider/model` or a model id)
`--local`	Embedded local runtime forced, bypassing the Gateway
`--deliver`	Reply gets delivered to a chat channel
`--channel <name>`	Delivery channel; combined with `--agent` and `--to`, it sets DM scope
`--reply-to <target>`	Override for the delivery target
`--reply-channel <name>`	Override for the delivery channel
`--reply-account <id>`	Override for the delivery account id
`--thinking <level>`	Thinking level assigned to the chosen model profile
`--verbose <on\|full\|off>`	Verbose level saved for the session (`full` also captures tool output)
`--timeout <seconds>`	Agent timeout overridden (default 600, or the config value)
`--json`	Structured JSON produced as output

Behavior

The CLI normally routes traffic through the Gateway. To run the embedded runtime on this machine instead, include --local.
You must pass either --message or --message-file, but not both. File messages keep multiline content intact after any optional UTF-8 BOM is stripped. Any file exceeding 4 MiB is refused before it gets dispatched.
When handshake retries fail temporarily, a Gateway timeout or a closed connection aborts the command with a stderr note; the CLI never quietly executes the turn again in embedded mode. The Gateway might still complete a turn it already accepted, so check both Gateway and session state before you retry or use --local to rerun.
Picking a session: --to computes the session key (group and channel targets keep isolation, while direct chats reduce to main). When --agent, --channel, and --to are all present, routing follows the channel's canonical recipient plus session.dmScope. Stable outbound-only identities rely on a provider-owned session that stays separate from the agent's main one.
An explicit key is chosen with --session-key. Keys prefixed with an agent must go through agent:<agent-id>:<session-key>, and if both are given, --agent has to match that agent id. Bare non-sentinel keys, when provided, are limited to --agent; as an example, --agent ops --session-key incident-42 sends to agent:ops:incident-42. In the absence of --agent, bare non-sentinel keys are limited to the default agent that is configured. Literal global and unknown stay unscoped only when no --agent is supplied.
--reply-channel and --reply-account only influence how delivery happens.
Thinking and verbose settings are stored in the session store.
Output defaults to plain text; use --json to get structured payload plus metadata instead.
With --json --deliver, the JSON adds delivery status for sent, suppressed, partial, and failed sends. For details, see JSON delivery status.

Examples

# Simple turn with JSON output
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json

# Turn with a model override
openclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"

# Turn with thinking level
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium

# Multiline prompt from a file
openclaw agent --agent ops --message-file ./task.md

# Exact session key
openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"

# Legacy key scoped to an agent
openclaw agent --agent ops --session-key incident-42 --message "Summarize status"

# Deliver to a different channel than the session
openclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin"

Agent CLI reference, Complete openclaw agent flag and option documentation.
Sub-agents, Launching background sub-agents.
Sessions, How session keys function and how --to, --agent, and --session-id resolve them.
Slash commands, Built-in command list usable inside agent sessions.