Agent Send: Run Agent Turns from CLI and Deliver Replies

openclaw agent executes a single agent turn from the command line without requiring an incoming chat message. Use it for automated scripts, testing, and programmatic output. Complete flag details and usage guidance: Agent CLI reference.

Quick start

Run a simple agent turn

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

Transmits the message through the Gateway and outputs the response.

Send a multiline prompt from a file

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

Loads a valid UTF-8 file to use 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 text to send inline
`--message-file <path>`	Load the message from a UTF-8 file (max 4 MiB)
`--to <dest>`	Obtain session key from a target (phone number, chat ID)
`--session-key <key>`	Provide a specific session key
`--agent <id>`	Direct to a configured agent (uses its `main` session)
`--session-id <id>`	Attach to an existing session by ID
`--model <id>`	Override the model for this execution (`provider/model` or model ID)
`--local`	Enforce local embedded runtime (bypass Gateway)
`--deliver`	Forward the reply to a chat channel
`--channel <name>`	Delivery channel; when used with `--agent` + `--to`, also sets DM scope
`--reply-to <target>`	Override the delivery target
`--reply-channel <name>`	Override the delivery channel
`--reply-account <id>`	Override the delivery account ID
`--thinking <level>`	Configure thinking level for the chosen model profile
`--verbose <on\|full\|off>`	Set verbose level for the session (`full` also logs tool output)
`--timeout <seconds>`	Override agent timeout (default 600, or value from config)
`--json`	Emit structured JSON output

Behavior

By default, the CLI routes through the Gateway. Add --local to use the embedded runtime on the local machine instead.
Supply exactly one of --message or --message-file. File messages keep multiline content after stripping an optional UTF-8 BOM. Files exceeding 4 MiB are refused before sending.
After transient handshake retries, a Gateway timeout or dropped connection fails the command with a stderr hint; the CLI never silently re-executes the turn locally. The Gateway may still complete an accepted turn, so check Gateway and session state before retrying or re-running with --local.
Session selection: --to derives the session key (group/channel targets maintain isolation; direct chats collapse to main). With --agent, --channel, and --to together, routing follows the channel's canonical recipient and session.dmScope. Stable outbound-only identities use a provider-owned session that is isolated from the agent's main session.
--session-key picks an explicit key. Agent-prefixed keys must use agent:<agent-id>:<session-key>, and --agent must match that agent ID when both are provided. Bare non-sentinel keys are scoped to --agent when supplied; for instance, --agent ops --session-key incident-42 routes to agent:ops:incident-42. Without --agent, bare non-sentinel keys are scoped to the configured default agent. Literal global and unknown stay unscoped only when no --agent is provided.
--reply-channel and --reply-account affect only delivery behavior.
Thinking and verbose flags are persisted in the session store.
Output: plain text by default, or --json for structured payload and metadata.
With --json --deliver, the JSON includes delivery status for sent, suppressed, partial, and failed sends. Refer to 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"

The Agent CLI reference provides a complete guide to every openclaw agent flag and option.
For spawning sub-agents that run in the background, see Sub-agents.
Sessions explains session key mechanics and how --to, --agent, and --session-id resolve them.
Inside agent sessions, use the built-in command list described in Slash commands.