openclaw/docs/cli/agent.md

summary, read_when, title

summary	read_when	title
CLI reference for `openclaw agent` (send one agent turn via the Gateway)	You want to run one agent turn from scripts (optionally deliver reply)	agent

openclaw agent

Run an agent turn via the Gateway (use --local for embedded). Use --agent <id> to target a configured agent directly.

Pass at least one session selector:

• --to <dest>
• --session-id <id>
• --agent <id>

Related:

• Agent send tool: Agent send

Options

• -m, --message <text>: required message body
• -t, --to <dest>: recipient used to derive the session key
• --session-id <id>: explicit session id
• --agent <id>: agent id; overrides routing bindings
• --thinking <off|minimal|low|medium|high|xhigh>: agent thinking level
• --verbose <on|off>: persist verbose level for the session
• --channel <channel>: delivery channel; omit to use the main session channel
• --reply-to <target>: delivery target override
• --reply-channel <channel>: delivery channel override
• --reply-account <id>: delivery account override
• --local: run the embedded agent directly (after plugin registry preload)
• --deliver: send the reply back to the selected channel/target
• --timeout <seconds>: override agent timeout (default 600 or config value)
• --json: output JSON

Examples

openclaw agent --to +15555550123 --message "status update" --deliver
openclaw agent --agent ops --message "Summarize logs"
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
openclaw agent --agent ops --message "Run locally" --local

Notes

• Gateway mode falls back to the embedded agent when the Gateway request fails. Use --local to force embedded execution up front.
• --local still preloads the plugin registry first, so plugin-provided providers, tools, and channels stay available during embedded runs.
• --channel, --reply-channel, and --reply-account affect reply delivery, not session routing.
• When this command triggers models.json regeneration, SecretRef-managed provider credentials are persisted as non-secret markers (for example env var names, secretref-env:ENV_VAR_NAME, or secretref-managed), not resolved secret plaintext.
• Marker writes are source-authoritative: OpenClaw persists markers from the active source config snapshot, not from resolved runtime secret values.