OpenClaw Reference Documentation
Complete technical reference for OpenClaw: configuration schema, all CLI commands, every environment variable, error code lookup, prompt variables, and the built-in tool catalog.
How to Use This Reference
This section is your quick-lookup companion for everything OpenClaw exposes: every config key, every CLI flag, every environment variable, and every built-in error code. Use the sections below to jump to the specific reference you need, or use your browser's find (Ctrl+F) within sub-pages for instant lookup.
All reference pages follow a consistent structure: a summary table at the top, detailed entries in alphabetical order, and annotated examples at the bottom. Where a config key, CLI flag, and environment variable overlap, the Config Schema page notes precedence rules.
At a Glance: Most-Used Config Keys
| Key | Type | Default | Description |
|---|---|---|---|
provider | string | openai | LLM provider: openai, anthropic, groq, ollama |
model | string | gpt-4o-mini | Model name passed to the provider |
max_iterations | integer | 20 | Hard cap on agent think/act cycles per run |
timeout | integer | 300 | Total run timeout in seconds |
tools | list | [] | Built-in tool names or paths to custom tools |
memory.backend | string | none | Memory backend: none, redis, sqlite, chroma |
log_level | string | WARNING | Logging verbosity: DEBUG, INFO, WARNING, ERROR |
Minimal Config Scaffold
# openclaw.yaml — minimal production config
provider: openai
model: gpt-4o-mini
max_iterations: 30
timeout: 600
tools:
- web_search
- read_file
- write_file
memory:
backend: redis
url: redis://localhost:6379/0
monitoring:
enabled: true
log_level: INFO
log_format: jsonSections
Config Schema
Full YAML/TOML/JSON config schema with all options, types, defaults, and examples.
Read →CLI Reference
All openclaw commands with flags, arguments, and usage examples.
Read →Environment Variables
Complete list of all supported env vars with types, defaults, and descriptions.
Read →Error Codes
All OCE-xxxxx error codes, meanings, causes, and resolution steps.
Read →Prompt Variables
Built-in prompt variables, custom variables, and template syntax reference.
Read →Tool Catalog
All built-in tools, inputs, outputs, permissions, and usage examples.
Read →Common Error Codes
All OpenClaw runtime errors follow the OCE-XXXXX format. The prefix indicates the subsystem: OCE-1xxxx = agent, OCE-2xxxx = tool, OCE-3xxxx = provider/LLM, OCE-4xxxx = config, OCE-5xxxx = memory.
| Code | Name | Probable Cause | Resolution |
|---|---|---|---|
OCE-10001 | MaxIterationsReached | Agent loop exceeded max_iterations | Increase max_iterations or simplify the task |
OCE-10002 | AgentTimeout | Run exceeded timeout seconds | Increase timeout or break task into subtasks |
OCE-20001 | ToolNotFound | Tool name not registered in the registry | Check spelling; ensure tool is listed under tools: |
OCE-20002 | ToolInputValidationError | Argument does not match the tool's schema | Review tool schema definition; check LLM output format |
OCE-20003 | ToolExecutionError | Tool raised an unhandled exception | Check tool logs; ensure external service is reachable |
OCE-30001 | ProviderAuthError | Invalid or missing API key | Verify OPENAI_API_KEY / provider key is set and valid |
OCE-30002 | ProviderRateLimited | Provider rate limit hit | Reduce concurrency; enable built-in retry with backoff |
OCE-30003 | ProviderContextLengthExceeded | Total tokens exceed model context window | Enable memory summarisation or reduce tool outputs |
OCE-40001 | ConfigValidationError | Required field missing or invalid value type | Run openclaw config validate and check the error details |
OCE-50001 | MemoryBackendUnreachable | Redis/Chroma/Pinecone connection failed | Check backend URL and credentials; verify network access |
Built-in Tool Catalog (Quick Reference)
These tools are available to all agents without any additional installation. Enable them by adding the tool name to the tools list in your config or CLI invocation.
| Tool Name | Category | Key Inputs | Returns |
|---|---|---|---|
web_search | Web | query, max_results | List of result objects (title, url, snippet) |
fetch_url | Web | url, extract_text | Page content as plain text or HTML |
read_file | Filesystem | path | File contents as string |
write_file | Filesystem | path, content | Confirmation with bytes written |
list_directory | Filesystem | path, recursive | Array of file/directory entries |
run_python | Code | code, timeout | stdout, stderr, return value |
run_bash | Code | command, cwd | stdout, stderr, exit code |
send_email | Communication | to, subject, body | Delivery confirmation + message ID |
sql_query | Database | query, connection | Result rows as list of dicts |
memory_store | Memory | key, value | Confirmation |
memory_recall | Memory | key or query | Stored value or top-k similar memories |
CLI Commands Quick Reference
| Command | Description | Common Flags |
|---|---|---|
openclaw run | Run an agent with a task prompt | --task, --provider, --model, --tools, --max-iterations |
openclaw start | Start the API server in the foreground | --port, --host, --reload |
openclaw config validate | Validate openclaw.yaml and print schema errors | --config |
openclaw config show | Print merged config (file + env vars) | --format json|yaml |
openclaw install | Install missing dependencies (LLM providers, etc.) | --provider, --all |
openclaw update | Update OpenClaw to the latest version | --pre (include pre-releases) |
openclaw stop | Gracefully stop a running API server instance | --timeout |
openclaw db migrate | Apply pending database schema migrations | --dry-run |