Skip to main content

​
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:

​
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.