OpenClaw reads its runtime configuration from a JSON5 file, normally ~/.openclaw/openclaw.json. Configuration connects your model provider, Gateway, channels, and tool policies. Workspace instruction files describe how the assistant should work; they serve a different purpose.

Independent guide. Schema and command references checked on October 2, 2026 against the official configuration documentation. Examples have been reviewed against those references, not tested on your installation.

Find the active configuration

openclaw config file
openclaw config get agents.defaults.workspace
openclaw config validate

Use the path reported by the CLI. A profile or OPENCLAW_CONFIG_PATH can select a different file, so editing the default path blindly may change the wrong assistant. The active path should be a regular file; the official docs describe atomic writes and why symlink-based arrangements need care.

The previous YAML examples on this page were incorrect for the OpenClaw Gateway. A config.yaml with agents.default, a generic memory.storage, or a made-up server.workers block should not be copied into a current installation.

Let onboarding establish the baseline

openclaw onboard

Choose and verify model access before adding advanced settings. For later guided edits:

openclaw configure

A working baseline gives you a useful comparison if a later change breaks replies. Preserve the credentials and authentication that onboarding created.

Understand the main sections

Section or path Purpose What to check before changing it
gateway Listener, authentication, remote access Whether access remains private and authenticated
agents.defaults Default agent behavior and workspace Exact supported key and desired scope
agents.entries Per-agent overrides Which agent is affected
channels Messaging accounts and access Pairing, allowlists, and provider-specific options
tools Tool availability and policy Permissions required by the task
models Provider and model configuration Provider credentials and supported model IDs

The configuration reference is the field map. For the version installed on your machine, inspect the CLI schema before pasting a setting:

openclaw config schema

A small JSON5 patch

This example changes a workspace path and keeps the Gateway listener on loopback. It is a partial configuration, not a replacement for the credentials and other settings in your existing file:

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
  gateway: {
    mode: "local",
    bind: "loopback",
    port: 18789,
  },
}

JSON5 permits comments, unquoted keys, and trailing commas. A normal .json parser may reject those features even though OpenClaw's config reader accepts them.

Keep the example in a separate file named openclaw.patch.json5 and preview it before applying:

openclaw config patch --file ./openclaw.patch.json5 --dry-run

Review which paths the patch would change. If they match your intent, apply it and validate:

openclaw config patch --file ./openclaw.patch.json5
openclaw config validate

See config patch semantics for merging, replacement, and version-specific flags. Never overwrite your whole config with a partial example.

Change one value with the CLI

openclaw config get agents.defaults.heartbeat.every
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config validate

Record the original value before changing it. If you are diagnosing unexpected model spending, also review the task frequency, model choice, and provider usage. A valid config confirms schema compatibility; it does not confirm that your account can call a selected model or afford every scheduled task.

Keep credentials separate from examples

Model provider keys, channel tokens, and the Gateway secret grant different types of access. Store them using the provider setup and secret mechanisms documented for your release. Do not put real values into screenshots, public Git repositories, or example snippets.

Use the official secrets guide and our API key security guide when replacing plain-text settings with secret references. Confirm the installed schema supports the reference at that particular path.

Configure sandboxing using its actual scope

Tool sandbox settings are under agents.defaults.sandbox or supported per-agent overrides. They are not enabled by a generic top-level security.sandbox_enabled flag. Follow the official sandbox guide for modes, backends, images, and workspace access.

A Gateway running inside Docker and an agent tool running inside a sandbox are separate choices. Decide which files and commands the task needs, then test that access using disposable data before relying on it for private files.

Validate, observe, and keep a rollback path

Before editing, make a private backup of the active configuration and state using the official backup workflow. After each change:

openclaw config validate
openclaw gateway status
openclaw doctor

Consult the docs for whether the particular setting reloads or requires a restart. If a restart is needed, stop active work first and use openclaw gateway restart. Then send the same small test message you used before editing. Keep the prior working settings until the test passes.

FAQ

Does OpenClaw use YAML?

The Gateway's current runtime config is JSON5 in openclaw.json. Some third-party tools may use YAML for their own data, but that does not change the Gateway schema.

Where do prompts and instructions belong?

Use the files and conventions described in the agent workspace documentation. A prompt file and a runtime listener setting should not be treated as interchangeable.

What should I do with an unknown field error?

Read the exact field in the validation output, compare it with openclaw config schema, and remove or migrate the unsupported setting. See the CLI guide and troubleshooting guide for the next checks.