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.
# 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\> | Message to send (required) |
--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.--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
# 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"