openclaw/docs/tools/agent-send.md

summary, read_when, title

summary	read_when	title
Run agent turns from the CLI and optionally deliver replies to channels	You want to trigger agent runs from scripts or the command line You need to deliver agent replies to a chat channel programmatically	Agent send

openclaw agent runs a single agent turn from the command line without an inbound chat message. Use it for scripted workflows, testing, and programmatic delivery. Full flag and behavior reference: Agent CLI reference.

Quick start

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

Sends the message through the Gateway and prints the reply.

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

Reads a valid UTF-8 file as the agent message body.

```bash # 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"
```

```bash # 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>	Inline message to send
--message-file <path>	Read the message from a valid UTF-8 file (max 4 MiB)
--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
--model <id>	Model override for this run (provider/model or model id)
--local	Force local embedded runtime (skip Gateway)
--deliver	Send the reply to a chat channel
--channel <name>	Delivery channel; with --agent + --to, also applies DM scope
--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>	Persist verbose level for the session (full also logs tool output)
--timeout <seconds>	Override agent timeout (default 600, or config value)
--json	Output structured JSON

Behavior

• By default, the CLI goes through the Gateway. Add --local to force the embedded runtime on the current machine.
• Pass exactly one of --message or --message-file. File messages preserve multiline content after removing an optional UTF-8 BOM. Files larger than 4 MiB are rejected before dispatch.
• After transient handshake retries, a Gateway timeout or closed connection fails the command with a stderr hint; the CLI never silently reruns the turn embedded. The Gateway may still finish an accepted turn, so verify Gateway and session state before retrying or rerunning with --local.
• Session selection: --to derives the session key (group/channel targets preserve 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 isolated from the agent's main session.
• --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.
• --reply-channel and --reply-account affect delivery only.
• Thinking and verbose flags persist into the session store.
• Output: plain text by default, or --json for structured payload + metadata.
• With --json --deliver, the JSON includes delivery status for sent, suppressed, partial, and failed sends. 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"

Related

Full `openclaw agent` flag and option reference. Background sub-agent spawning. How session keys work and how `--to`, `--agent`, and `--session-id` resolve them. Native command catalog used inside agent sessions.