How to Use the openclaw agent CLI Command

openclaw agent is the CLI bridge between scripts and a real OpenClaw session. It sends a message into the agent runtime, waits for the result, and can optionally deliver the answer back to a channel. That makes it useful for one-shot reports, local automations, smoke tests, and operator workflows where a cron or shell script needs the agent without opening Slack or the dashboard.

When this is the right move

Use it when you want an agent turn, not just a raw outbound message. If you need to send a literal message to Slack or Telegram, use openclaw message. If you need the model to think, call tools, summarize logs, or generate a report, use openclaw agent with an explicit session target.

The practical workflow

1. Choose the session selector first. The command requires at least --to, --session-id, or --agent, and --agent targets a configured agent directly.
2. Pass the message body with --message. Keep scripted prompts specific because this is a one-shot run, not a long back-and-forth planning surface.
3. Set --thinking only when the job needs it. The docs list off, minimal, low, medium, high, plus provider-supported custom levels such as xhigh, adaptive, or max.
4. Use --deliver only when the answer should go back to a selected channel or target. Delivery flags affect reply delivery, not session routing.
5. Use --json for automation so stdout stays parseable and diagnostics route to stderr.

Grounded command or config pattern

These examples mirror the documented command shape: selector, message, optional thinking, optional delivery.

openclaw agent --agent ops --message "Summarize logs"
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
openclaw agent --to +15555550123 --message "status update" --deliver
openclaw agent --agent ops --message "Run locally" --local --json

Gateway mode can fall back to embedded agent when the Gateway request fails, while --local forces embedded execution up front. The docs note that --local still preloads the plugin registry so configured providers, tools, and channels can be available during embedded runs.

Operator notes

One subtle implementation detail is good for automation hygiene: each openclaw agent invocation is a one-shot run, and bundled or configured MCP servers opened for that run are retired afterward. That means scripted calls should not leak stdio MCP child processes between invocations.

Rollout approach

For use the openclaw agent cli command, I would make the first pass deliberately small: one owner, one machine or channel, one visible test, and one rollback path. OpenClaw features become powerful when they connect to real tools and real messages, so the safest rollout is not a giant configuration day. It is a short rehearsal that proves the docs-grounded path works in your exact workspace before you depend on it while busy.

Common mistake

The common mistake is treating the command as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and a tiny verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A small note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or machine changes.

Safety checks

If you use --deliver, be explicit about where the output goes. --channel, --reply-channel, and --reply-account affect delivery, not routing, so a sloppy command can produce an answer in the wrong place. For long jobs, raise --timeout intentionally instead of letting automation die mid-run.

How to verify it worked

For human use, a normal text answer is enough. For scripts, verify the JSON shape from --json and check the command exit code. If delivery was requested, confirm the target channel received exactly one final answer and not an interim status line.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.