Complete flag reference for openclaw agent, covering session selection, message delivery, local execution, and output control.
What does Openclaw Agent do?
It’s the primary CLI entry point for dispatching a prompt to a configured agent runtime and getting a reply. Under the hood it resolves a Gateway session, forwards your message to the agent, and either prints the response in your terminal or routes it back out to a chat channel, depending on how you wire it up. The same command works whether your runtime is local (embedded model with API keys) or remote (via the OpenClaw Gateway).
Where to Look for the Right Flags
Start with Session Selection, you need at least one of –to, –session-id, or –agent to tell the command which context to run against. If the output should go back to a chat channel rather than your terminal, add –deliver and the relevant delivery flags. Everything else, thinking level, verbosity, JSON output, is optional and additive. The Examples section at the bottom shows four working combinations that cover the most common cases.
Command Syntax
shell
openclaw agent --message "<text>" [session-selection] [delivery-options] [exec-flags]
Flag Reference
Required Parameter
| Flag | Description |
|---|---|
--message <text> | The prompt or task you want to send to the agent. This is the only flag that is always required. |
Session Selection
These flags determine which session context the agent uses. You need at least one of the three.
| Flag | Description |
|---|---|
--to <dest> | Derives the session key based on the destination. Direct chats collapse to the main session; group/channel targets preserve their isolation. |
--session-id <id> | Reuses a specific, existing session by its ID. Useful when you want to continue a prior conversation thread rather than start fresh. |
--agent <id> | Targets a configured agent directly, using that agent’s main session key. The simplest selector when you just want to hit a named agent. |
–to and –session-id are about routing to an existing context. –agent is about targeting a named configuration. When in doubt and you have a named agent set up, –agent is the most explicit choice.
Delivery Options
If you want the agent’s reply sent out to a chat channel instead of just printing in your terminal, use these flags.
| Flag | Description |
|---|---|
| –deliver | Instructs OpenClaw to send the final reply to the chosen channel. Acts as the master switch, the flags below only take effect when this is present. |
--channel <name> | Specifies the delivery channel. Accepts: whatsapp, telegram, discord, slack, mattermost, signal, imessage, msteams. Defaults to whatsapp. |
--reply-to <dest> | Overrides the delivery target without changing the session context. Send to a different recipient than the session owner. |
--reply-channel <name> | Overrides the delivery channel without changing the session context. Lets you route output to Slack while keeping a WhatsApp session active, for example. |
--reply-account <id> | Overrides the delivery account ID. Use when you have multiple accounts configured for the same channel. |
–deliver must be present for –channel, –reply-to, –reply-channel, and –reply-account to have any effect. Without it, output goes to stdout regardless of the other delivery flags.
Execution & Output Flags
| Flag | Description |
|---|---|
| –local | Forces the embedded agent runtime to run locally on your current machine rather than via the Gateway. Requires your model provider API keys to be present in your shell environment. |
--thinking <level> | Persists a thinking level override into the session store. Levels: off minimal low medium high xhigh. |
--verbose <on|full|off> | Controls the verbosity of the output. full includes intermediate steps and tool calls; on shows progress without full trace; off is silent except for the final reply. |
| –json | Prints the structured payload and metadata as JSON instead of the default plain text reply. Useful for piping output into other CLI tools. |
--timeout <seconds> | Sets a timeout for the agent run. The command exits with an error if the agent doesn’t complete within the specified duration. |
When using –local, make sure environment variables like ANTHROPIC_API_KEY or OPENAI_API_KEY are exported in the same shell session. The runtime won’t pull them from a .env file automatically.
Examples
Four working patterns from the most common use cases. Copy, adjust the values in angle brackets, and run.
01 Standard local run, prints to terminal
openclaw agent --agent ops --message "Summarize logs"
02 Targeting an existing session with thinking enabled
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
03 Running an agent and delivering the reply to WhatsApp
openclaw agent --to +15555550123 --message "status update" --deliver
04 Running an agent and overriding delivery to a Slack channel
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slac
- Openclaw Agents Commands Guide
Complete subcommand reference for openclaw agents, covering agent lifecycle, channel routing bindings, and identity configuration. What is Openclaw Agents? It’s the management..
- Openclaw Channels Command List
Complete reference for openclaw channels, inspecting channel health, managing auth accounts, and resolving platform-specific IDs across WhatsApp, Slack, Discord, Telegram, and..
