openclaw agent

Run one agent turn via the Gateway

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 xhigh

Controls 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 [phone]

# Deliver via channel
openclaw agent --message "Hello" --to [phone] --deliver

Examples

Basic

# Send a simple message
openclaw agent --message "What is the weather today?" --to [phone]

# Send with high thinking level
openclaw agent --message "Solve this complex problem" --thinking high --to [phone]

# Send and deliver response
openclaw agent --message "Generate a report" --to [phone] --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 [phone]; 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)

Related Commands

• agents - Manage isolated agents and workspaces
• sessions - List stored conversation sessions
• models - Manage model configurations