FAQ: Common Issues

Why does OpenClaw stop before finishing my task?

The default max_iterations is 10. Increase it for complex tasks:

openclaw run "complex task" --max-iterations 30

# config.yaml
max_iterations: 30

Why is it so slow?

• Use a faster model: --model gpt-4o-mini
• Enable streaming: stream: true in config
• Use a local model: Ollama
• Check your internet/API latency: ping api.openai.com

The AI is making things up (hallucinating)

• Provide more context: use --file to attach relevant documents
• Use a stronger model (gpt-4o instead of mini)
• Use the --rag flag to ground in your own knowledge base
• Add "Do not make up information. If you don't know, say so." to your prompt

ContextWindowError: my input is too large

# Use chunking
openclaw run "summarise this" --file big-file.txt --chunk-size 50000

# Or switch to a model with a larger context
openclaw run "summarise this" --model claude-3-5-sonnet-20241022 --file big-file.txt

No output is produced

# Check if task ran at all
openclaw run "echo hello" --debug

# Verify output file path is writable
openclaw run "write summary" --output /tmp/test.md && cat /tmp/test.md

I get different results every time

LLMs are non-deterministic by default. For reproducibility:

# config.yaml
temperature: 0.0    # 0.0 = deterministic (greedy decoding)
seed: 42            # supported by some providers

API key not found even after setting it

# Check env var is exported (not just set)
export OPENCLAW_API_KEY="sk-..."

# On Windows PowerShell:
$env:OPENCLAW_API_KEY = "sk-..."

# To persist permanently, use:
openclaw config set api_key "sk-..."
# This writes to ~/.openclaw/config.yaml

Performance FAQs

Why is openclaw run so slow on my machine?

Most latency comes from the LLM API round-trips. Typical response times:

• gpt-4o-mini: 1-3 seconds for a short response
• gpt-4o: 3-8 seconds
• claude-3-5-sonnet: 2-6 seconds
• llama3.2 via Ollama (M2 Mac): 1-4 seconds; CPU-only: 10-30 seconds

If responses are slower than these baselines, check your network or switch to a faster model for the task.

How do I reduce token usage / API costs?

# Use cheaper model for simple tasks
openclaw run "classify as bug/feature/question: {text}" --model gpt-4o-mini

# Cap response length
openclaw config set max_tokens 512

# Use streaming to see output sooner (doesn't reduce total tokens)
openclaw config set stream true

Why does openclaw use so many API calls for one task?

Each step in an autonomous workflow makes one or more API calls. If your task requires 5 reasoning steps + 3 tool calls, that's 5-8 API calls total. Reduce by:

• Limiting max_steps: 5 in config
• Breaking the task into smaller, explicit sub-commands
• Using --no-tools for pure text tasks that don't need tool calls

Configuration FAQs

How do I use different providers for different tasks?

# Override provider per command without changing config
openclaw run "Summarise this 100-page doc" \
  --model claude-3-5-sonnet    # Claude for long context
openclaw run "Quick: fix this typo" \
  --model gpt-4o-mini          # Fast + cheap for simple tasks

Can I run openclaw without internet?

Yes — use Ollama with a locally-downloaded model. Download the model while online:

ollama pull llama3.2         # download while online
openclaw config set provider ollama
openclaw config set model llama3.2
# Now works 100% offline

How do I prevent openclaw from modifying files outside my project?

# config.yaml — restrict allowed paths
allowed_paths:
  - ./src/
  - ./tests/
  - /home/user/project/docs/
# OpenClaw will refuse to read/write files outside these paths

Multi-Model & Offline FAQ

Can I use multiple models in the same workflow?

Yes. Use --provider and --model flags per task invocation, or define per-profile configs:

# Use cheap model for first pass, powerful model for final review
openclaw run "Draft email" --model gpt-4o-mini --output draft.txt
openclaw run "Review and polish" --model gpt-4o --context draft.txt

Can OpenClaw work completely offline?

Yes, with Ollama or another local LLM. Set provider: ollama in config. Note: some tools (web search, GitHub integration) require internet regardless of LLM choice — disable them with --no-tools web-search.

What's the cheapest way to run OpenClaw?

Use gpt-4o-mini (OpenAI, ~$0.15/1M tokens) or a local Ollama model (zero cost after setup). Avoid --verbose in production — it increases token usage by including debug traces in the prompt.

More troubleshooting: Common Errors | Log Analysis | Debugging