docs/tools/agent-send.md
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.
Sends the message through the Gateway and prints the reply.
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 |
--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 |
--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). 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; the embedded fallback path
resolves those sentinel sessions to the configured default agent.--reply-channel and --reply-account affect delivery only.--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 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"