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 <level>: agent thinking level (off, minimal, low, medium, high, plus provider-supported custom levels such as xhigh, adaptive, or max)
• --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.
• Each openclaw agent invocation is treated as a one-shot run. Bundled or user-configured MCP servers opened for that run are retired after the reply, even when the command uses the Gateway path, so stdio MCP child processes do not stay alive between scripted invocations.
• --channel, --reply-channel, and --reply-account affect reply delivery, not session routing.
• --json keeps stdout reserved for the JSON response. Gateway, plugin, and embedded-fallback diagnostics are routed to stderr so scripts can parse stdout directly.
• 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.

Related

• CLI reference
• Agent runtime