openclaw-agent-run
Direct agent CLI invocations in OpenClaw. Use when running the `openclaw agent` command to trigger agent turns, targeting sessions or agents programmatically, delivering replies to channels, using --json output for automation, overriding thinking/verbose levels, or understanding session selection logic. Triggers for: "openclaw agent", "direct agent run", "send a message to agent", "--deliver", "--session-id", "agent turn", "CLI agent", "thinking level", "verbose mode", "--json output".
Best use case
openclaw-agent-run is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Direct agent CLI invocations in OpenClaw. Use when running the `openclaw agent` command to trigger agent turns, targeting sessions or agents programmatically, delivering replies to channels, using --json output for automation, overriding thinking/verbose levels, or understanding session selection logic. Triggers for: "openclaw agent", "direct agent run", "send a message to agent", "--deliver", "--session-id", "agent turn", "CLI agent", "thinking level", "verbose mode", "--json output".
Teams using openclaw-agent-run should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/openclaw-agent-run/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How openclaw-agent-run Compares
| Feature / Agent | openclaw-agent-run | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Direct agent CLI invocations in OpenClaw. Use when running the `openclaw agent` command to trigger agent turns, targeting sessions or agents programmatically, delivering replies to channels, using --json output for automation, overriding thinking/verbose levels, or understanding session selection logic. Triggers for: "openclaw agent", "direct agent run", "send a message to agent", "--deliver", "--session-id", "agent turn", "CLI agent", "thinking level", "verbose mode", "--json output".
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Direct Agent Runs (`openclaw agent`)
## Basic Usage
```bash
# Target by agent ID
openclaw agent --agent main --message "Summarize the latest logs"
# Target by phone/channel destination (session key derived)
openclaw agent --to +15555550123 --message "Status update please"
# Reuse an existing session
openclaw agent --session-id {sessionId} --message "Continue from where we left off"
```
## Session Selection Rules
1. `--agent {id}` → targets that agent's `main` session key
2. `--to {dest}` → derives session from destination (group chats keep isolation; direct → `main`)
3. `--session-id {id}` → reuses exact session by ID (stable, OpenClaw-chosen IDs)
4. No flags → defaults to `main` agent on default session
## Output Modes
```bash
# Default: prints reply text (+ MEDIA:<url> lines for media)
openclaw agent --agent main --message "Hello"
# JSON: structured payload + metadata
openclaw agent --agent main --message "Hello" --json
```
JSON output shape:
```json
{
"text": "...",
"media": [],
"sessionId": "...",
"runId": "...",
"agentId": "main",
"model": "anthropic/claude-sonnet-4-5"
}
```
## Delivery to Channel
```bash
# Deliver reply to WhatsApp (default channel)
openclaw agent --to +15555550123 --message "Check the server" --deliver
# Deliver to specific channel and target
openclaw agent --agent ops --message "Generate report" \
--deliver \
--reply-channel slack \
--reply-to "#reports"
```
## Thinking & Verbose Flags
Both **persist into the session store** (affect future turns too):
```bash
# Thinking levels: off | minimal | low | medium | high | xhigh
openclaw agent --agent main --message "Debug this" --thinking high
# Verbose levels: off | on | full
openclaw agent --agent main --message "Trace logs" --verbose full
```
Note: `--thinking` levels only work with models that support extended thinking (GPT-5.2, Codex, Claude 3.7+).
## Timeout Override
```bash
openclaw agent --agent main --message "Long analysis" --timeout 900
```
Default: 600s (10 min). Override for tasks known to be slow.
## Local vs Gateway
```bash
# Force local run (bypasses gateway, uses shell env API keys)
openclaw agent --local --agent main --message "Hello"
# Default: goes through gateway (http://localhost:18789)
# Falls back to local if gateway unreachable
```
See [references/automation-recipes.md](references/automation-recipes.md) for common automation patterns using `openclaw agent` in scripts.Related Skills
openclaw-medicine
Diagnose and fix OpenClaw gateway issues — broken configs, missing tokens, dead channels, auth failures, merge bugs, and multi-instance management. Use when openclaw is unresponsive, channels aren't starting, config is corrupted, or when managing remote openclaw instances (e.g. via SSH). Also covers migrating between config strategies (Nix-managed vs local).
openclaw-json-editing
Advanced JSON editing for OpenClaw configuration files, tools, and data structures. Handles JSON5 configs, schema validation, merge patching, env var substitution, and type-safe modifications.
openclaw-config-validator
Validate, analyze, and explain OpenClaw configuration files. Use when users need to check config.json for errors, understand what a config field does, compare configs, or safely modify OpenClaw configuration. Triggers on config validation requests, schema questions, or config editing tasks.
openclaw-tescmd
Installation and setup guide for Tesla vehicle control and telemetry via the tescmd node.
aura-openclaw
No description provided.
openclaw-starter-kit
Replace 100+ API keys with one. Instant access to LLMs, Twitter, YouTube, LinkedIn, Finance, Tavily & Scholar data. Enterprise stability for your local agent.
moltbot, openclaw-best-practices
Best practices for AI agents to avoid common mistakes. Learn from real failures - confirms before executing, shows drafts before publishing. Works with Claude, Cursor, GPT, Copilot.
bgo
Automates the complete Blender build-go workflow, from building and packaging your extension/add-on to removing old versions, installing, enabling, and launching Blender for quick testing and iteration.
self-subagent
Orchestrate parallel sub-tasks by spawning non-interactive instances of your own CLI as subagents. Use when you need to parallelize work across multiple files, run independent investigations simultaneously, or delegate heavy multi-step tasks. Works with ANY AI coding CLI agent (Amp, Claude Code, Codex, Cursor, OpenCode, aider, Cline, Roo, goose, Windsurf, Copilot CLI, pi, etc.). Triggers on "run in parallel", "subagent", "delegate", "fan out", "concurrent tasks", or any complex task that benefits from parallel execution.
self-improving-ai
Understanding and using StickerNest's self-improving AI system. Use when the user asks about AI self-improvement, prompt versioning, reflection loops, AI evaluation, auto-tuning prompts, or the AI judge system. Covers AIReflectionService, stores, and the improvement loop.
second-brain
Personal intelligence system for capturing thoughts, managing knowledge, and surfacing insights. Use when user wants to capture an idea, task, or note during conversation; query their knowledge base; check their inbox; review digests; or update task status. Triggers include "remember this," "add a task," "what did I say about," "show my inbox," or "mark complete."
searching-message-history
Search Telegram conversation history and stored links. Use when finding past messages, what someone said, or links shared in chats.