Skip to main content

​
openclaw agent

Execute a single agent interaction through the OpenClaw Gateway.

​
Usage

openclaw agent [options]

​
Options

​
--message <text>
string
required
The message or prompt to send to the agent
​
--to <identifier>
string
Recipient identifier (E.164 phone number, user ID, etc.)
​
--session-id <id>
string
Explicit session ID to use or create
​
--session-key <key>
string
Session key for routing (format: agent:sessionId)
​
--agent <id>
string
Agent ID to use for this interaction
​
--thinking <level>
string
Thinking level: off, low, medium, high, or xhighControls how much reasoning the agent performs before responding.
​
--thinking-once <level>
string
One-time thinking level override (same values as —thinking)
​
--verbose <level>
string
Verbose output level: on, full, or off
​
--timeout <seconds>
number
Timeout in seconds (0 means no timeout)
​
--deliver
boolean
Deliver the response to the recipient via their channel
​
--reply-to <id>
string
Message ID to reply to
​
--thread-id <id>
string
Thread ID for threaded conversations
​
--channel <name>
string
Message channel (telegram, discord, slack, etc.)
​
--reply-channel <name>
string
Override channel for reply delivery
​
--lane <lane>
string
Agent lane identifier for routing
​
--run-id <id>
string
Custom run ID for tracking (defaults to session ID)
​
--extra-system-prompt <text>
string
Additional system prompt to inject
​
--images <paths>
string
Comma-separated list of image file paths to include

​
Thinking Levels

The --thinking flag controls the agent’s reasoning process:
  • off: No explicit reasoning, direct responses
  • low: Minimal reasoning for simple queries
  • medium: Moderate reasoning for typical tasks
  • high: Deep reasoning for complex problems
  • xhigh: Extended reasoning (only for supported models)
The xhigh thinking level is only available for specific models like o1-preview and o1-mini.

​
Delivery Options

By default, agent responses are printed to stdout. Use --deliver to send responses through the configured channel: 
# Print response to terminal
openclaw agent --message "Hello" --to +1234567890

# Deliver via channel
openclaw agent --message "Hello" --to +1234567890 --deliver

​
Examples

# Send a simple message
openclaw agent --message "What is the weather today?" --to +1234567890

# Send with high thinking level
openclaw agent --message "Solve this complex problem" --thinking high --to +1234567890

# Send and deliver response
openclaw agent --message "Generate a report" --to +1234567890 --deliver
You must specify at least one of --to, --session-id, --session-key, or --agent to identify the target session.

​
Session Persistence

Agent conversations are automatically persisted to session files. Each session maintains:
  • Conversation history
  • Model preferences
  • Thinking level settings
  • Skills snapshot
  • Authentication profile
Sessions are stored in ~/.openclaw/sessions/ by default.

​
Model Selection

The agent uses the configured default model unless overridden in the session. To change models: 
# Configure default model
openclaw config set agents.defaults.model.primary anthropic:claude-4.5-sonnet

# Or use the models command
openclaw models set anthropic:claude-4.5-sonnet

​
Error Handling

If an agent turn fails, the CLI returns a non-zero exit code: 
if openclaw agent --message "Task" --to +1234567890; then
  echo "Success"
else
  echo "Agent failed"
fi

​
Environment Variables

​
OPENCLAW_AGENT_TIMEOUT
number
Default timeout in seconds for agent operations
​
OPENCLAW_THINKING_DEFAULT
string
Default thinking level (off, low, medium, high, xhigh)
  • agents - Manage isolated agents and workspaces
  • sessions - List stored conversation sessions
  • models - Manage model configurations