Debugging OpenClaw AI

⚡

Quick Debug Steps

Add --debug flag: openclaw run "your task" --debug
Check exit code: non-zero means the task failed
Read the last 20 lines of the log: tail -20 ~/.openclaw/logs/openclaw.log
Isolate the failing step by running a minimal task first
If the issue is reproducible, collect logs and open a GitHub issue

The `--debug` Flag

The simplest first step. Adds verbose output including every tool call and its result:

openclaw run "your task here" --debug

# Also useful: combine with log output
openclaw run "your task here" --debug 2>&1 | tee debug.log

Debug output includes:

Resolved config values
Prompt sent to the model (truncated)
Each tool call: name, input, output
Token counts per request
Final response

Log Levels

# Set log level via env var
OPENCLAW_LOG_LEVEL=debug openclaw run "task"

# Or in config.yaml
log_level: debug   # error | warning | info | debug | trace

Level	Shows
`error`	Only critical failures
`warning`	Warnings + errors
`info`	Normal operation (default)
`debug`	Tool calls, prompts, responses
`trace`	HTTP request/response bodies

Inspect API Requests

# Use trace level to see raw HTTP
OPENCLAW_LOG_LEVEL=trace openclaw run "hello" 2>&1 | grep -A5 "POST /v1/chat"

# Or print the resolved prompt without sending
openclaw run "task here" --dry-run --show-prompt

# Save the full request payload to file
OPENCLAW_LOG_LEVEL=trace openclaw run "task" 2>&1 | \
  grep -A100 "Request body:" > request-body.json

Tracing Tool Calls

# See each tool call as it happens
openclaw run "search for news and summarise" --debug 2>&1 | \
  grep -E "TOOL_CALL|TOOL_RESULT"

# Example output:
# [DEBUG] TOOL_CALL: web_search({"query": "AI news today"})
# [DEBUG] TOOL_RESULT: web_search -> {"results": [...]}
# [DEBUG] TOOL_CALL: summarise({"text": "..."})
# [DEBUG] TOOL_RESULT: summarise -> "Summary: ..."

Isolation Techniques

# Test with a minimal prompt first
openclaw run "Say hello" --debug

# Test connection to API
openclaw config test-connection

# Test specific tool
openclaw run "Use the calculator tool to compute 2+2" --debug

# Check your config is loading correctly
openclaw config show

Reporting a Bug

# Gather diagnostic info
openclaw --version
python --version
pip show openclaw

# Collect full debug log (sanitise the API key before sharing!)
openclaw run "reproduce the issue" --debug 2>&1 | \
  sed 's/sk-[a-zA-Z0-9]*/sk-REDACTED/g' > bug-report.log

Open a GitHub issue at github.com/openclaw-ai/openclaw/issues and attach bug-report.log.

💡

See Also

Debug Output Examples

When running with --debug, OpenClaw prints each step with timing and context:

$ openclaw run "Summarise the README" --file README.md --debug

[DEBUG] Config loaded: provider=openai, model=gpt-4o-mini
[DEBUG] Input: 1 file, 842 tokens
[STEP 1] Planning: identify task type and required tools
[DEBUG] API call: POST /v1/chat/completions (gpt-4o-mini, 892 tokens, 1.2s)
[STEP 2] Executing: summarise document content
[DEBUG] API call: POST /v1/chat/completions (gpt-4o-mini, 1043 tokens, 1.8s)
[DEBUG] Total steps: 2, Total tokens: 1935, Total time: 3.0s, Cost: ~$0.0003

Result:
OpenClaw AI is an open-source autonomous agent framework...

What Each Debug Field Means

Field	Meaning
`[STEP N]`	The Nth reasoning or execution step taken by the agent
`tokens`	Total tokens sent in the prompt (input tokens = cost)
`Ns`	Latency of that single API call in seconds
`Total tokens`	Sum of all input + output tokens for the entire run
`Cost`	Estimated cost based on the model's per-token pricing

Debugging Automated Scripts

When a cron job or automated script fails silently, use these techniques:

#!/usr/bin/env bash
# Wrap any openclaw call with debug output and error logging
set -euo pipefail   # Exit on error, undefined var, pipe failures

DEBUG_LOG="/var/log/openclaw-debug-$(date +%Y%m%d-%H%M%S).log"

echo "=== Run started: $(date) ===" >> "$DEBUG_LOG"
echo "Task: $TASK_DESC" >> "$DEBUG_LOG"

openclaw run "$TASK_DESC" \
  --debug \
  --log-level debug \
  2>&1 | tee -a "$DEBUG_LOG"

EXIT_CODE=$?
echo "=== Exit: $EXIT_CODE, Duration: ${SECONDS}s ===" >> "$DEBUG_LOG"
exit $EXIT_CODE

Common Causes of Silent Failures

Missing environment variables in cron: cron doesn't inherit shell env vars. Add source ~/.bashrc or define vars explicitly in the cron job
Wrong working directory: cron starts from /, not your home. Use absolute paths or cd /your/project first
Python venv not activated: cron won't know about your venv. Use the full path: /home/user/.venv/openclaw/bin/openclaw

# crontab entry — annotated for reliability
0 8 * * 1-5 \
  source /home/user/.bashrc; \
  cd /home/user/projects/main; \
  /home/user/.venv/openclaw/bin/openclaw \
    run "Morning standup summary" \
    >> /var/log/standup.log 2>&1

← Common Errors Logs →