Agent

text

Copy

openclaw agent

Run an agent turn via the Gateway (use

for embedded). Use to target a configured agent directly.

Pass at least one session selector:

• text

  Copy

  --to <dest>
• text

  Copy

  --session-id <id>
• text

  Copy

  --agent <id>

Related:

• Agent send tool: Agent send

Options

• text

  Copy

  -m, --message <text>
  : required message body
• text

  Copy

  -t, --to <dest>
  : recipient used to derive the session key
• text

  Copy

  --session-id <id>
  : explicit session id
• text

  Copy

  --agent <id>
  : agent id; overrides routing bindings
• text

  Copy

  --model <id>
  : model override for this run (
  text

  Copy

  provider/model
  or model id)
• text

  Copy

  --thinking <level>
  : agent thinking level (
  text

  Copy

  off
  ,
  text

  Copy

  minimal
  ,
  text

  Copy

  low
  ,
  text

  Copy

  medium
  ,
  text

  Copy

  high
  , plus provider-supported custom levels such as
  text

  Copy

  xhigh
  ,
  text

  Copy

  adaptive
  , or
  text

  Copy

  max
  )
• text

  Copy

  --verbose <on|off>
  : persist verbose level for the session
• text

  Copy

  --channel <channel>
  : delivery channel; omit to use the main session channel
• text

  Copy

  --reply-to <target>
  : delivery target override
• text

  Copy

  --reply-channel <channel>
  : delivery channel override
• text

  Copy

  --reply-account <id>
  : delivery account override
• text

  Copy

  --local
  : run the embedded agent directly (after plugin registry preload)
• text

  Copy

  --deliver
  : send the reply back to the selected channel/target
• text

  Copy

  --timeout <seconds>
  : override agent timeout (default 600 or config value)
• text

  Copy

  --json
  : output JSON

Examples

bash
Copy
openclaw agent --to +15555550123 --message "status update" --deliver
openclaw agent --agent ops --message "Summarize logs"
openclaw agent --agent ops --model openai/gpt-5.4 --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
  text

  Copy

  --local
  to force embedded execution up front.
• text

  Copy

  --local
  still preloads the plugin registry first, so plugin-provided providers, tools, and channels stay available during embedded runs.
• text

  Copy

  --local
  and embedded fallback runs are treated as one-shot runs. Bundled MCP loopback resources and warm Claude stdio sessions opened for that local process are retired after the reply, so scripted invocations do not keep local child processes alive.
• Gateway-backed runs leave Gateway-owned MCP loopback resources under the running Gateway process; older clients may still send the historical cleanup flag, but the Gateway accepts it as a compatibility no-op.
• text

  Copy

  --channel
  ,
  text

  Copy

  --reply-channel
  , and
  text

  Copy

  --reply-account
  affect reply delivery, not session routing.
• text

  Copy

  --json
  keeps stdout reserved for the JSON response. Gateway, plugin, and embedded-fallback diagnostics are routed to stderr so scripts can parse stdout directly.
• Embedded fallback JSON includes
  text

  Copy

  meta.transport: "embedded"
  and
  text

  Copy

  meta.fallbackFrom: "gateway"
  so scripts can distinguish fallback runs from Gateway runs.
• If the Gateway accepts an agent run but the CLI times out waiting for the final reply, embedded fallback uses a fresh explicit
  text

  Copy

  gateway-fallback-*
  session/run id and reports
  text

  Copy

  meta.fallbackReason: "gateway_timeout"
  plus the fallback session fields. This avoids racing the Gateway-owned transcript lock or silently replacing the original routed conversation session.
• When this command triggers
  text

  Copy

  models.json
  regeneration, SecretRef-managed provider credentials are persisted as non-secret markers (for example env var names,
  text

  Copy

  secretref-env:ENV_VAR_NAME
  , or
  text

  Copy

  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