openclaw agent: One-Shot AI Call Command Guide

Command Overview

The openclaw agent command lets you send a single request to the AI directly from the command line and get a response, without going through a channel. It is ideal for quick testing, script integration, and automation workflows.

Basic Usage

openclaw agent "Hello, please introduce yourself"

Output:

Hello! I'm the OpenClaw AI assistant. I can help you answer questions,
write code, translate text, and more. How can I help?

Specify a Model

# Use a model alias defined in your config
openclaw agent --model gpt-4o "Explain the basics of quantum computing"

# Use a provider and model name
openclaw agent --provider openai --model gpt-4o-mini "Write a sorting algorithm"

Pass a System Prompt

openclaw agent \
  --system "You are a professional Python programmer. Only answer in Python." \
  "Implement an in-order traversal of a binary tree"

Read from Standard Input

# Pipe input
echo "Translate to English: The weather is great today" | openclaw agent

# Read from a file
cat error.log | openclaw agent "Analyze the errors in this log"

# Here document
openclaw agent <<EOF
Please review the following code:
def add(a, b):
    return a - b
EOF

Streaming Output

# Enable streaming (display content as it is generated)
openclaw agent --stream "Write a short essay about artificial intelligence"

Output Format

# Plain text (default)
openclaw agent "Hello"

# JSON format
openclaw agent --format json "Hello"

JSON output:

{
  "content": "Hello! How can I help you?",
  "model": "gpt-4o-mini",
  "usage": {
    "promptTokens": 12,
    "completionTokens": 15,
    "totalTokens": 27
  },
  "latency": 850
}

Adjust Model Parameters

openclaw agent \
  --temperature 0.2 \
  --max-tokens 1000 \
  --top-p 0.9 \
  "Give me 5 project name suggestions"

Use Tools

Allow the AI to invoke tools:

openclaw agent --tools web_search "What's the weather like in Beijing today?"

openclaw agent --tools code_exec "Calculate the value of fibonacci(30)"

# Multiple tools
openclaw agent --tools web_search,code_exec "Search for the latest Python version and run test code"

Multi-Turn Conversation

While agent is primarily designed for one-shot calls, it also supports simple multi-turn conversations:

# Use a session ID to maintain context
openclaw agent --session my-test "My name is John"
openclaw agent --session my-test "What's my name?"
# Output: Your name is John.

Script Integration Examples

Using in Shell Scripts

#!/bin/bash
# Automatically generate a Git commit message
DIFF=$(git diff --cached)
MESSAGE=$(echo "$DIFF" | openclaw agent --model gpt-4o-mini \
  --system "Generate a concise commit message based on this git diff. Output only the message, nothing else." \
  --format text)

git commit -m "$MESSAGE"

Batch Processing

#!/bin/bash
# Batch translate files
for file in docs/*.md; do
  openclaw agent --model gpt-4o-mini \
    --system "Translate the following Markdown content to English, preserving formatting" \
    < "$file" > "translated/$(basename $file)"
done

Working with jq

# Extract specific fields from JSON
openclaw agent --format json "Generate 3 random user profiles" | jq '.content'

Exit Codes

0: Success
1: General error
2: Authentication error
3: Model unavailable
4: Rate limited

openclaw agent "test" || echo "Call failed with exit code: $?"

Timeout Settings

openclaw agent --timeout 30 "A complex question..."

Debug Mode

openclaw agent --debug "Hello"

Output includes detailed request and response information:

[DEBUG] Provider: openai
[DEBUG] Model: gpt-4o-mini
[DEBUG] Request tokens: 12
[DEBUG] Response time: 850ms
[DEBUG] Response tokens: 15

Hello! How can I help you?

Summary

openclaw agent is one of the most flexible commands in the OpenClaw CLI, bringing AI capabilities directly into the command line. It lets you compose AI calls with pipes, scripts, and automation workflows just like any other Unix tool.