Skip to content
OpenClaw Docs

Agent Send

Agent Send

Section titled “Agent Send”

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.

Quick start

Section titled “Quick start”

  1. Run a simple agent turn

    Terminal window
    openclaw agent --message "What is the weather today?"

    This sends the message through the Gateway and prints the reply.

  2. Target a specific agent or session

    Terminal window
    # 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"

  3. Deliver the reply to a channel

    Terminal window
    # 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

Section titled “Flags”
FlagDescription
--message \<text\>Message to send (required)
--to \<dest\>Derive session key from a target (phone, chat id)
--agent \<id\>Target a configured agent (uses its main session)
--session-id \<id\>Reuse an existing session by id
--localForce local embedded runtime (skip Gateway)
--deliverSend 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 (off, minimal, low, medium, high, xhigh)
--verbose \<on|full|off\>Set verbose level
--timeout \<seconds\>Override agent timeout
--jsonOutput structured JSON

Behavior

Section titled “Behavior”
  • By default, the CLI goes through the Gateway. Add --local to force the embedded runtime on the current machine.
  • If the Gateway is unreachable, the CLI falls back to the local embedded run.
  • Session selection: --to derives the session key (group/channel targets preserve isolation; direct chats collapse to main).
  • Thinking and verbose flags persist into the session store.
  • Output: plain text by default, or --json for structured payload + metadata.

Examples

Section titled “Examples”
Terminal window
# 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


# Deliver to a different channel than the session
openclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin"
Section titled “Related”