2025-12-09 17:51:05 +00:00
|
|
|
---
|
2026-01-30 03:15:10 +01:00
|
|
|
summary: "Direct `openclaw agent` CLI runs (with optional delivery)"
|
2025-12-09 17:51:05 +00:00
|
|
|
read_when:
|
|
|
|
|
- Adding or modifying the agent CLI entrypoint
|
2026-01-31 16:04:03 -05:00
|
|
|
title: "Agent Send"
|
2025-12-09 17:51:05 +00:00
|
|
|
---
|
2026-01-31 21:13:13 +09:00
|
|
|
|
2026-01-30 03:15:10 +01:00
|
|
|
# `openclaw agent` (direct agent runs)
|
2025-12-04 17:53:37 +00:00
|
|
|
|
2026-01-30 03:15:10 +01:00
|
|
|
`openclaw agent` runs a single agent turn without needing an inbound chat message.
|
2026-01-08 23:06:56 +01:00
|
|
|
By default it goes **through the Gateway**; add `--local` to force the embedded
|
|
|
|
|
runtime on the current machine.
|
2025-12-04 17:53:37 +00:00
|
|
|
|
|
|
|
|
## Behavior
|
2026-01-08 23:06:56 +01:00
|
|
|
|
2025-12-04 17:53:37 +00:00
|
|
|
- Required: `--message <text>`
|
|
|
|
|
- Session selection:
|
2026-01-11 02:57:42 +00:00
|
|
|
- `--to <dest>` derives the session key (group/channel targets preserve isolation; direct chats collapse to `main`), **or**
|
2026-01-18 22:49:55 +00:00
|
|
|
- `--session-id <id>` reuses an existing session by id, **or**
|
|
|
|
|
- `--agent <id>` targets a configured agent directly (uses that agent's `main` session key)
|
2026-01-08 23:06:56 +01:00
|
|
|
- Runs the same embedded agent runtime as normal inbound replies.
|
|
|
|
|
- Thinking/verbose flags persist into the session store.
|
2025-12-04 17:53:37 +00:00
|
|
|
- Output:
|
2026-01-08 23:06:56 +01:00
|
|
|
- default: prints reply text (plus `MEDIA:<url>` lines)
|
|
|
|
|
- `--json`: prints structured payload + metadata
|
2026-01-30 03:15:10 +01:00
|
|
|
- Optional delivery back to a channel with `--deliver` + `--channel` (target formats match `openclaw message --target`).
|
2026-01-18 22:49:55 +00:00
|
|
|
- Use `--reply-channel`/`--reply-to`/`--reply-account` to override delivery without changing the session.
|
2026-01-08 23:06:56 +01:00
|
|
|
|
|
|
|
|
If the Gateway is unreachable, the CLI **falls back** to the embedded local run.
|
|
|
|
|
|
|
|
|
|
## Examples
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-01-30 03:15:10 +01:00
|
|
|
openclaw agent --to +15555550123 --message "status update"
|
|
|
|
|
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 --to +15555550123 --message "Summon reply" --deliver
|
|
|
|
|
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
|
2026-01-08 23:06:56 +01:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Flags
|
|
|
|
|
|
2026-01-13 06:51:20 +00:00
|
|
|
- `--local`: run locally (requires model provider API keys in your shell)
|
2026-01-18 22:49:55 +00:00
|
|
|
- `--deliver`: send the reply to the chosen channel
|
2026-01-23 16:45:37 -06:00
|
|
|
- `--channel`: delivery channel (`whatsapp|telegram|discord|googlechat|slack|signal|imessage`, default: `whatsapp`)
|
2026-01-18 22:49:55 +00:00
|
|
|
- `--reply-to`: delivery target override
|
|
|
|
|
- `--reply-channel`: delivery channel override
|
|
|
|
|
- `--reply-account`: delivery account id override
|
2026-01-07 17:17:38 -08:00
|
|
|
- `--thinking <off|minimal|low|medium|high|xhigh>`: persist thinking level (GPT-5.2 + Codex models only)
|
2026-01-17 05:33:27 +00:00
|
|
|
- `--verbose <on|full|off>`: persist verbose level
|
2026-01-08 23:06:56 +01:00
|
|
|
- `--timeout <seconds>`: override agent timeout
|
|
|
|
|
- `--json`: output structured JSON
|
