mirror of
https://github.com/openclaw/openclaw.git
synced 2026-04-04 16:36:42 +02:00
58 lines
2.5 KiB
Markdown
58 lines
2.5 KiB
Markdown
---
|
|
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.
|