---
summary: "CLI reference for `openclaw agent` (send one agent turn via the Gateway)"
read_when:
- You want to run one agent turn from scripts (optionally deliver reply)
title: "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 ](/tools/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
```bash
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.