docs/tools/agent-send.md
openclaw agent runs a single agent turn from the command line without needing
an inbound chat message. Use it for scripted workflows, testing, and
programmatic delivery.
This sends the message through the Gateway and prints the reply.
This reads a valid UTF-8 file as the agent message body.
# 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 to Slack
openclaw agent --agent ops --message "Generate report" \
--deliver --reply-channel slack --reply-to "#reports"
```
| Flag | Description |
|---|---|
--message \<text\> | Inline message to send |
--message-file \<path\> | Read the message from a valid UTF-8 file |
--to \<dest\> | Derive session key from a target (phone, chat id) |
--session-key \<key\> | Use an explicit session key |
--agent \<id\> | Target a configured agent (uses its main session) |
--session-id \<id\> | Reuse an existing session by id |
--local | Force local embedded runtime (skip Gateway) |
--deliver | Send the reply to a chat channel |
--channel \<name\> | Delivery channel (whatsapp, telegram, discord, slack, etc.) |
--reply-to \<target\> | Delivery target override |
--reply-channel \<name\> | Delivery channel override |
--reply-account \<id\> | Delivery account id override |
--thinking \<level\> | Set thinking level for the selected model profile |
--verbose \<on|full|off\> | Set verbose level |
--timeout \<seconds\> | Override agent timeout |
--json | Output structured JSON |
--local to force the
embedded runtime on the current machine.--message or --message-file. File messages preserve
multiline content after removing an optional UTF-8 BOM.--to derives the session key (group/channel targets
preserve isolation; direct chats collapse to main).--session-key selects an explicit key. Agent-prefixed keys must use
agent:<agent-id>:<session-key>, and --agent must match that agent id when
both are supplied. Bare non-sentinel keys are scoped to --agent when
supplied; for example, --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 remain
unscoped only when no --agent is supplied; in that case, embedded fallback
and store ownership use the configured default agent.--json for structured payload + metadata.--json --deliver, the JSON includes delivery status for sent,
suppressed, partial, and failed sends. See
JSON delivery status.# Simple turn with JSON output
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
# 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"