OpenClaw Config Set: The Command That Changes Everything

Teams that edit openclaw.yaml by hand are one typo away from a broken gateway. The config set command eliminates that risk — it validates your input before writing, tells you if a restart is needed, and keeps a history of every change. Ninety percent of teams only use three or four keys. The other ten percent — the ones building production-grade deployments — know the full set. Here it is.

Command Basics

The syntax is consistent across every config key: openclaw config set --key [key] --value [value]. No positional arguments. Flags only. This makes it safe to use in scripts without worrying about argument order.

# Basic usage
openclaw config set --key gateway.token --value my-secret-token

# Set a value for a specific agent
openclaw config set --agent researcher-001 --key max_context_tokens --value 100000

# Read the current value of a key
openclaw config get --key gateway.token

# List all keys with current values
openclaw config list

# List only keys you've changed from defaults
openclaw config list --modified

# Remove a custom value (revert to default)
openclaw config unset --key gateway.rate_limit

# Export entire config to YAML
openclaw config export > openclaw-backup.yaml

Gateway Configuration Keys

These keys control how the gateway itself operates — networking, authentication, and request handling.

# Common gateway config commands
openclaw config set --key gateway.token --value $(openssl rand -hex 32)
openclaw config set --key gateway.log_level --value debug
openclaw config set --key gateway.rate_limit --value 60
openclaw config set --key gateway.trusted_proxies --value "10.0.0.0/8,172.16.0.0/12"

Agent Configuration Keys

Agent keys control default behavior for all agents or, with --agent [id], for a specific one. These are the settings that most directly affect what your agents can do and how they behave.

# Set global agent defaults
openclaw config set --key agents.default_model --value gpt-4o
openclaw config set --key agents.max_context_tokens --value 128000
openclaw config set --key agents.session_timeout --value 3600
openclaw config set --key agents.max_retries --value 3
openclaw config set --key agents.response_timeout --value 120

# Override for a specific agent
openclaw config set --agent researcher-001 --key max_context_tokens --value 200000
openclaw config set --agent router-001 --key response_timeout --value 30

The session_timeout key controls how long an idle session stays open in seconds. Default is 3600 (one hour). For agents handling long-running tasks, increase this to avoid sessions expiring mid-task. For high-volume consumer-facing agents, decrease it to free memory faster.

The response_timeout key is the maximum time in seconds the gateway waits for an agent to respond before returning an error. Set this based on your slowest expected task completion time. Research agents that process large documents may need 300 seconds or more.

Provider and Model Keys

Provider keys are where you store API credentials and configure provider-specific behavior. These are the first keys you should set on any new installation.

# OpenAI
openclaw config set --key providers.openai.api_key --value sk-...
openclaw config set --key providers.openai.organization --value org-...

# Anthropic
openclaw config set --key providers.anthropic.api_key --value sk-ant-...

# Groq
openclaw config set --key providers.groq.api_key --value gsk_...

# Local Ollama
openclaw config set --key providers.ollama.base_url --value http://localhost:11434

# Per-provider timeout (seconds)
openclaw config set --key providers.openai.timeout --value 90

The provider timeout setting controls how long OpenClaw waits for the provider's API to respond before returning an error. Default is 60 seconds. For models with slow response times (large context processing), increase this to avoid false timeout errors.

Config Precedence: What Wins When Values Conflict

Understanding precedence saves debugging time. OpenClaw evaluates config from multiple sources and the order matters.

1. Agent-scoped CLI config — highest priority. Set with --agent [id]. Overrides everything below.
2. Global CLI config — set via openclaw config set without --agent. Overrides file-based config.
3. openclaw.yaml file values — your config file. Overrides built-in defaults.
4. Environment variables — OPENCLAW_GATEWAY_TOKEN, etc. Override built-in defaults but not CLI or file config.
5. Built-in defaults — lowest priority. Applied when no other source sets a value.

Here's the mistake most people make: they set a value in openclaw.yaml and then wonder why a CLI-set value doesn't take effect after restarting the gateway. It always does — CLI config is always higher priority than the file. The confusion happens when people think editing the file will override a CLI value. It won't.

# If you want to see exactly where a key's current value comes from
openclaw config get --key gateway.token --show-source

Common Config Set Mistakes

• Setting secrets as positional arguments in shell history — use --value $(cat secret-file) or read from environment variables to keep API keys out of your shell history. Every key you type in plaintext is stored in your terminal's history file.
• Changing gateway.port without planning for a restart — port changes require a full gateway restart, which drops all active agent sessions. Plan this during a maintenance window and notify any teams with active agents.
• Not exporting config before version upgrades — upgrades can reset CLI-set config in rare cases involving config schema migrations. Run openclaw config export > config-backup.yaml before every major version upgrade.
• Setting per-agent config without verifying the agent ID — if you mistype an agent ID, config set creates a config entry for a non-existent agent without error. The correct agent gets none of the settings you intended. Verify agent IDs with openclaw status first.
• Forgetting that unset reverts to default, not to YAML values — running openclaw config unset removes the CLI-level override but does not revert to your YAML file value. It reverts to the built-in default. If your YAML has a custom value, the YAML file value still applies after unset.

Frequently Asked Questions

What does openclaw config set do?

openclaw config set writes a key-value pair to the OpenClaw configuration database, immediately changing the behavior it controls. It covers gateway settings, agent defaults, provider API keys, memory limits, and plugin config. CLI-set values take precedence over config files.

How do I see all available config keys?

Run openclaw config list to see every configurable key with its current value and description. Add --section gateway or --section agents to filter by section. Use --modified to see only keys you've changed from their defaults.

Does openclaw config set require a gateway restart?

Most settings apply immediately. Exceptions include gateway port changes, TLS certificate paths, and new channel connector types — these require a gateway restart. The CLI tells you if a restart is required after you run the set command.

Can I set config values for a specific agent rather than globally?

Yes. Add --agent [agent-id] to scope the change to one agent: openclaw config set --agent researcher-001 --key max_context_tokens --value 200000. Agent-scoped settings override global defaults for that agent only.

How do I reset a config value to its default?

Run openclaw config unset --key [key-name] to remove a custom value and revert to the built-in default. For agent-scoped settings, add --agent [id]. Note that unset reverts to built-in defaults, not to values set in your YAML config file.

Where does openclaw config set store its values?

Values are written to the OpenClaw config database, which takes precedence over the openclaw.yaml file. CLI-set values survive config file replacements during upgrades. Export current config to YAML with openclaw config export > openclaw.yaml.