Config Reference

config.yaml — The Human-Friendly Config File

config.yaml does everything openclaw.json does, but it's easier to read, supports comments, and is friendlier to hand-edit. This guide explains what it is, when to use it, and how every setting works.

What is config.yaml?

config.yaml is an alternative configuration file for OpenClaw that uses the YAML format instead of JSON. It contains the exact same settings as openclaw.json — just written in a different syntax.

Think of it like choosing between filling out a form in a cramped box (JSON) versus writing things out line by line in a notebook (YAML). The information is the same — but YAML gives you more room to breathe, and you can leave yourself notes (comments) in the margins.

📋 What is YAML?

YAML (YAML Ain't Markup Language) is a text format that uses indentation and colons instead of curly braces and quotes. It's widely used for config files because it's very clean to read. One important rule: indentation matters — use spaces, not tabs.

JSON vs YAML — Same Thing, Different Look

Here's the exact same config written in both formats, so you can see the difference:

📄 openclaw.json

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "apiKey": "$ANTHROPIC_API_KEY"
  },
  "gateway": {
    "port": 8080
  }
}

📋 config.yaml

# config.yaml — you can write comments!
llm:
  provider: anthropic
  model: claude-sonnet-4-6
  apiKey: $ANTHROPIC_API_KEY

gateway:
  port: 8080


Feature	openclaw.json	config.yaml
Comments allowed?	❌ No	✅ Yes — use `#`
Quotes needed on keys?	✅ Always	❌ Not usually
Curly braces?	✅ Required for objects	❌ Just use indentation
Good for beginners?	Medium	✅ Usually easier to read
Indentation matters?	❌ (cosmetic only)	✅ Critical — use spaces
Supported by OpenClaw?	✅ Default format	✅ Fully supported

Where Does config.yaml Live?

Same place as openclaw.json

Put config.yaml in your project's root folder — the same directory where you run openclaw start.

Don't use both at once

If both openclaw.json and config.yaml exist in the same folder, OpenClaw will use openclaw.json and ignore the YAML file. Pick one format per project.

Global fallback works here too

You can place a config.yaml at ~/.openclaw/config.yaml as a global default, just like with JSON.

Minimal Starter Config

Here's the smallest valid config.yaml to get your agent running — only the essentials:

# The only required section is llm
llm:
  provider: anthropic
  model: claude-haiku-4-5-20251001
  apiKey: $ANTHROPIC_API_KEY

⚠️ Never hardcode your API key

Use $ANTHROPIC_API_KEY instead of the actual key value — OpenClaw will read it from your environment. Add config.yaml to your .gitignore as a safety net too.

Full Annotated Example

Here's a complete config.yaml with every common section and comments explaining each field:

# ────────────────────────────────────────────────
# OpenClaw config.yaml
# All values with $ prefix are read from env vars
# ────────────────────────────────────────────────

llm:
  provider: anthropic         # anthropic | openai | ollama | groq
  model: claude-sonnet-4-6   # model name from your provider
  apiKey: $ANTHROPIC_API_KEY  # reads from environment variable
  maxTokens: 4096            # max response length
  temperature: 0.7           # 0 = precise, 1 = creative
  # systemPrompt: "You are a helpful assistant."  # optional persona

gateway:
  port: 8080                  # port OpenClaw listens on
  host: 127.0.0.1            # use 0.0.0.0 to allow LAN access
  timeout: 30000             # request timeout in ms
  cors: false                # set true for browser clients

memory:
  type: sqlite               # memory | sqlite | postgres
  path: ./agent.db           # path to SQLite file
  maxEntries: 10000          # max items stored
  # ttlSeconds: 86400           # auto-expire after 24h (optional)

tools:
  enabled:                   # list of tools to activate
    - web_search
    - file_read
    - code_run
  webSearch:
    provider: brave
    apiKey: $BRAVE_API_KEY
  maxConcurrent: 3           # max parallel tool calls

heartbeat:
  enabled: true              # keep agent alive between requests
  intervalMs: 60000          # ping every 60 seconds
  onIdle: keep               # keep | suspend | shutdown

voice:
  enabled: false             # set true to enable voice mode
  provider: elevenlabs       # elevenlabs | openai | piper
  apiKey: $ELEVENLABS_KEY
  # voiceId: "Rachel"           # specific voice (provider-specific)
  # sttProvider: whisper        # speech-to-text provider

mcpServers:
  filesystem:
    command: npx
    args:
      - -y
      - @modelcontextprotocol/server-filesystem
      - /Users/you/docs
  github:
    command: npx
    args:
      - -y
      - @modelcontextprotocol/server-github
    env:
      GITHUB_TOKEN: $GITHUB_TOKEN

YAML Tips for Beginners

💡 Indentation rules — most important thing

In YAML, indentation defines structure. Child settings must be indented under their parent with consistent spaces. OpenClaw expects 2 spaces per level.

# ✅ Correct — 2 spaces per level
llm:
  provider: anthropic
  model: claude-sonnet-4-6

# ❌ Wrong — tab character used
llm:
	provider: anthropic   # tab = error!

💬 How to write comments

Use # to write comments. Everything after # on a line is ignored by OpenClaw. Use comments to explain settings or temporarily disable a line.

llm:
  provider: anthropic      # inline comment — works great
  # model: claude-opus-4-6     # commented out = disabled
  model: claude-haiku-4-5-20251001

📝 Strings — when do you need quotes?

Most string values don't need quotes in YAML. But use quotes when your value contains special characters like :, #, or {, or when you want to be safe with values that look like numbers or booleans.

llm:
  model: claude-sonnet-4-6     # no quotes needed
  systemPrompt: "You are helpful: always."  # colon = use quotes
  version: "1.0"                  # prevent YAML treating as number

📋 Lists — how to write arrays

Lists use a dash - for each item. You can also write short lists on one line with square brackets.

# Multi-line list (preferred — easier to read)
tools:
  enabled:
    - web_search
    - file_read
    - code_run

# Inline list (works too)
tools:
  enabled: [web_search, file_read]

Field Reference

All fields are identical to openclaw.json. Click any section to see what each field does.

🤖 llm — Language Model Settings

Controls which AI model powers your agent.


Field	Type	Default	Description
`provider`	string	—	required AI provider: `anthropic`, `openai`, `ollama`, `groq`
`model`	string	—	required Model name, e.g. `claude-sonnet-4-6` or `gpt-4o`
`apiKey`	string	—	required Your API key or an env var reference like `$ANTHROPIC_API_KEY`
`maxTokens`	number	4096	optional Max tokens per response
`temperature`	number	0.7	optional 0 = deterministic, 1 = creative
`systemPrompt`	string	—	optional Custom system prompt — quote if it contains colons or special chars
`baseUrl`	string	—	optional Override the API endpoint URL

🌐 gateway — Server & Port Settings

Controls how OpenClaw exposes its HTTP gateway.


Field	Type	Default	Description
`port`	number	8080	optional Port to listen on
`host`	string	127.0.0.1	optional Host to bind to — use `0.0.0.0` for LAN access
`timeout`	number	30000	optional Request timeout in milliseconds
`cors`	boolean	false	optional Enable CORS headers for browser clients

🧠 memory — Storage & Persistence

Controls how your agent remembers things between conversations.


Field	Type	Default	Description
`type`	string	memory	optional Storage backend: `memory`, `sqlite`, `postgres`
`path`	string	./agent.db	optional File path for SQLite database
`connectionString`	string	—	optional Database URL for Postgres
`maxEntries`	number	10000	optional Max items stored in memory
`ttlSeconds`	number	—	optional Auto-expire memories after N seconds

🔧 tools — Capabilities & Integrations

Controls which tools your agent can use.


Field	Type	Default	Description
`enabled`	list	[]	optional Tool names to activate: `web_search`, `file_read`, `file_write`, `code_run`, `browser`
`webSearch`	object	—	optional Web search config — needs `provider` and `apiKey`
`codeRun`	object	—	optional Code execution sandbox settings
`maxConcurrent`	number	3	optional Max parallel tool calls

💓 heartbeat — Keep-Alive Settings

Keeps your agent active between requests.


Field	Type	Default	Description
`enabled`	boolean	false	optional Turn keep-alive on or off
`intervalMs`	number	60000	optional How often to ping in milliseconds
`onIdle`	string	keep	optional Idle behavior: `keep`, `suspend`, `shutdown`

🎙️ voice — Voice Mode Settings

Enables spoken interaction. See the Voice Mode guide.


Field	Type	Default	Description
`enabled`	boolean	false	optional Enable voice input/output
`provider`	string	—	optional TTS provider: `elevenlabs`, `openai`, `piper`
`apiKey`	string	—	optional API key for cloud TTS provider
`voiceId`	string	—	optional Voice name or ID (provider-specific)
`sttProvider`	string	—	optional Speech-to-text: `whisper`, `deepgram`

🔌 mcpServers — MCP Tool Connections

Connect your agent to external tools via Model Context Protocol. See the MCP guide.

mcpServers:
  myServer:              # give it any name
    command: npx
    args:
      - -y
      - @modelcontextprotocol/server-filesystem
      - /Users/you/docs
    env:
      MY_TOKEN: $MY_TOKEN


Field	Description
`command`	Executable to launch the server (e.g. `npx`, `python`)
`args`	List of arguments passed to the command
`env`	Environment variables to inject into the server process

📄

openclaw.json

Same settings in JSON format — the default config file

🔌

MCP Servers

Connect external tools via Model Context Protocol

🎙️

Voice Mode

Set up spoken interaction with your agent

🚀

Getting Started

New to OpenClaw? Start here