Configuration Schema Reference

Configuration File Format

The configuration file is YAML. All top-level keys are optional unless noted. Configuration values can be overridden by environment variables with the prefix OPENCLAW_ — for example, llm.model can be overridden by setting OPENCLAW_LLM_MODEL=gpt-4o. Environment variables use uppercase and underscores instead of dots for nesting.

openclaw config validate    # validate config file syntax and values
openclaw config show        # show effective config after env var overrides
openclaw config init        # generate a starter config interactively

agent Block

llm Block

memory Block

tools Block

tools:
  enabled:
    - web_search
    - read_url
    - write_file
  disabled:
    - execute_code   # disable dangerous tools explicitly
  plugins:
    - my_plugin.tools   # Python module path to tool package
  config:
    web_search:
      provider: duckduckgo   # or: google, bing
      max_results: 5
    write_file:
      allowed_dirs:
        - /tmp/agent-output
        - /data/reports

logging and server Blocks

logging:
  level: INFO           # DEBUG, INFO, WARNING, ERROR, CRITICAL
  format: json          # json or console
  file_path: null       # Write logs to file; null for stdout only

server:
  host: 0.0.0.0
  port: 8080
  workers: 4            # Uvicorn worker processes
  max_concurrent_tasks: 10
  api_key: null         # Require X-API-Key header; null disables auth

Complete Example

agent:
  name: research-assistant
  max_steps: 25
  max_tokens: 80000
  timeout_seconds: 240

llm:
  provider: openai
  model: gpt-4o
  max_retries: 3

memory:
  working:
    max_turns: 15
  semantic:
    enabled: true
    backend: chroma

tools:
  enabled: [web_search, read_url, write_file]
  config:
    web_search:
      max_results: 8

server:
  port: 8080
  max_concurrent_tasks: 5

Configuration Inheritance and Profiles

For teams that run OpenClaw in multiple environments (development, staging, production), configuration profiles eliminate duplication. Create a base config file with shared settings and environment-specific files that override only the values that differ:

# Set the profile with an environment variable
OPENCLAW_PROFILE=production openclaw start

# Or specify the profile config file directly
openclaw start --config openclaw.production.yaml

Typical dev vs. production differences: the development config uses a cheap fast model like gpt-4o-mini and sets OPENCLAW_LOG_LEVEL=DEBUG; the production config uses the production model, sets LOG_LEVEL=INFO, enables the full tool set, and requires an API key for the server. Keeping these as separate config profiles prevents accidentally running production settings locally and vice versa.

Validating Configuration Changes

Any change to the configuration file, no matter how small, should be validated before deployment. The openclaw config validate command checks the config against the full JSON Schema, verifying that all required keys are present, all values are of the correct type, all enum values are valid choices, and no unknown keys are present. A valid config doesn't guarantee the agent will work (the API key might be wrong, the model might not exist), but it eliminates an entire class of startup failures.

Consider adding openclaw config validate as a pre-commit hook in your repository using pre-commit — it catches config mistakes before they're even pushed, let alone deployed. The validation runs in under a second and fails loudly on any schema violation.

Hot Reload and Dynamic Config

When running in server mode, OpenClaw monitors the configuration file for changes and applies non-breaking changes without restarting. Log level, tool configuration, agent timeout, and similar runtime settings reload instantly. Changes to server bindings, worker counts, or LLM provider selection require a server restart. The openclaw status command shows the effective configuration and when it was last loaded — use it to confirm that a config change was picked up correctly after editing the file.

Advanced Configuration Patterns

For organizations running multiple agent configurations (a research agent, a coding agent, a customer service agent), consider using a shared base configuration with per-agent overrides. Store shared settings (LLM provider, logging format, server settings) in a base YAML file and agent-specific settings (system prompt, enabled tools, max_steps) in agent-specific YAML files. Load the agent config with openclaw run --config agent-configs/research.yaml. This prevents duplication and ensures that infrastructure changes (rotating API keys, changing log levels) only need to be made in one place.

Configuration Tips for Production

Set agent.temperature to a lower value (0.2–0.4) for production agents performing structured tasks like data extraction or code generation — this reduces output variance and makes behavior more predictable. Leave higher temperatures (0.7–0.9) for creative tasks like content writing. Always set server.api_key in production — leaving auth disabled exposes your instance to anyone who can reach the port.