Triggering Agent Runs Directly from Your Terminal

I often find myself stuck in a loop where I need to test an agent’s logic but don’t want to pick up my phone to send a message. It is frustrating to wait for a webhook to trigger just to see if a prompt change worked or if a tool is fetching the right data.

The openclaw agent command solves this. It lets you run a single agent turn directly from your terminal. You get to skip the inbound message and see exactly how the agent responds.

What You’ll Need

• Model provider API keys in your shell (if you plan to use the --local flag).
• A running Gateway or a local environment configured with your agents.

Quick Start

The fastest way to use this is by sending a message to a specific destination. By default, this goes through the Gateway, but the CLI will fall back to a local run if the Gateway is down.

I recommend using the --agent flag when you want to test a specific configuration without worrying about session IDs.

# Basic message to a phone number
openclaw agent --to +15555550123 --message "status update"

# Target a specific configured agent
openclaw agent --agent ops --message "Summarize logs"

# Use a specific session and set thinking depth
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium

# Get structured JSON output for your scripts
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json

# Run a message and deliver the reply to the channel
openclaw agent --to +15555550123 --message "Summon reply" --deliver

# Override the delivery target and channel
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"

If you need to bypass the Gateway entirely, add the --local flag. This forces the embedded runtime on your current machine. You can also use --timeout to change how long the CLI waits for the agent to finish its work.

Troubleshooting

The Gateway is unreachable

If the CLI cannot connect to the Gateway, it automatically falls back to the embedded local run. Ensure your model provider API keys are set in your environment variables if this happens.

Thinking levels are not persisting

The --thinking flag only works with GPT-5.2 and Codex models. If you are using other models, this setting will not apply to the session store.

If you have more questions about setting up your environment, check out the AI Setup Assistant.

What’s Next

• Message Command Docs
• Agent Configuration Guide
• Session Management
• Gateway Setup