OpenClaw's Configuration System - openclaw.json Explained

Mastering OpenClaw Configuration: A Practical Guide

Every serious OpenClaw deployment lives or dies by its configuration. The configuration file is where you define how your agents behave, which models they use, what tools and resources they can reach, how the system communicates, and the boundaries it must respect. Get it right and OpenClaw is flexible, predictable, and safe. Get it wrong and you end up with agents that are too cautious to be useful, too permissive to be safe, or that simply fail to start. This guide walks through the concepts that matter, how the major sections fit together, and the trade-offs to weigh, without pretending there is one magic setting that solves everything.

A quick note before the details: OpenClaw moves fast, and exact field names, defaults, and file formats can change between releases. Treat the specifics below as concepts to map onto whatever your installed version actually uses, and always confirm against the configuration reference for your release rather than copying values blindly.

What is the OpenClaw configuration file?

The OpenClaw configuration file is the single source of truth that tells your installation how to run, from which models your agents use to which tools they are allowed to call. Rather than hard-coding behavior, OpenClaw reads its setup from configuration, which means you can change how the whole system behaves without touching code. Swap a model, tighten a permission, enable a channel, or dial an agent's creativity up or down, all by editing settings and restarting.

Conceptually the configuration breaks into a few responsibilities: defining the agents themselves, controlling the service that orchestrates and exposes them, declaring the tools agents can use, deciding how much the system logs, and setting the security posture. Understanding those responsibilities, and how they interact, is what separates a copy-pasted setup from one you actually control.

Defining your agents

The agents portion of the configuration is where you describe each agent's identity and behavior. This is the most important part to get right because it directly shapes output quality and cost. For each agent you typically decide a handful of things.

• Which model it uses. This is the single biggest lever on both quality and price. A heavier model reasons better and costs more; a lighter one is cheaper and faster for routine work. Many deployments mix models, using a capable one for hard tasks and a cheaper one for high-volume, low-stakes work.
• How creative it is. A lower randomness setting produces consistent, predictable output, which is what you want for routing, classification, or anything you will parse downstream. A higher setting suits brainstorming and drafting where variety helps.
• Its instructions. The system instructions define the agent's role, tone, and rules. This is where most of your real "programming" happens, in plain language. Be specific about what the agent should and should not do.
• Which tools it can reach. Grant only the tools an agent actually needs. An agent that only summarizes does not need write access to your filesystem.
• Operational limits. Response length caps, execution timeouts, and whether the agent remembers context across sessions all belong here. These protect you from runaway cost and stuck processes.

The trade-off running through all of these is capability versus control. Every bit of freedom you grant an agent makes it more useful and slightly riskier. Start conservative and loosen deliberately.

Configuring the orchestrating service

The service that runs and exposes your agents is configured separately from the agents themselves, and this is where networking, access, and persistence are decided. The key questions to answer here are about exposure and limits.

• What it binds to. Binding to localhost keeps the service reachable only from the same machine, which is the safe default for anything experimental. Binding to a public interface exposes it to the network and must be paired with authentication and HTTPS.
• Rate limiting. Cap how many requests the service will accept in a window so a bug or abuse cannot run up your bill or overwhelm the box. Development can be loose; production should be deliberately tight.
• Sessions and state. How long sessions live and where state is stored both belong here. Lightweight setups can use a simple embedded store; higher-volume deployments usually point at a more robust database.
• Verbosity. How much the service reports about its own operation is a knob you will move depending on whether you are debugging or running steady-state.

The recurring trade-off is convenience versus exposure. Anything that makes the service easier to reach also makes it easier to attack, so every loosening should be a conscious decision rather than a default you forgot to change.

Declaring tools safely

Tools are what let agents do more than talk, and declaring them is the part of configuration with the most security weight. A tool might let an agent search the web, read or write files, call an external API, or send messages. That power is the whole point, and also the main risk surface. A few principles keep it sane.

• Never put secrets directly in the configuration. API keys, passwords, and tokens should come from environment variables or a secrets mechanism, so the configuration file itself can be shared and version-controlled without leaking credentials.
• Constrain file access. If an agent can touch the filesystem, restrict it to specific directories. An unbounded path is an invitation for an agent to read or overwrite something it should not.
• Disable what you do not use. Every enabled tool is attack surface and potential cost. Turn off anything an agent does not genuinely need.
• Rate-limit expensive operations. Tools that hit paid APIs should have their own guardrails so a loop cannot quietly drain a budget.

The mental model to hold is least privilege. Ask, for each agent, the smallest set of tools and the narrowest scope that still gets the job done, and grant exactly that.

Logging and observability

Logging configuration controls how much visibility you have into what your agents are doing, and the right level depends entirely on what you are trying to accomplish. During development you want detailed logs that show you decisions and errors as they happen. In production you usually pull verbosity back to warnings and errors to keep volume manageable, while still capturing enough to investigate problems.

Two cautions matter regardless of level. First, be deliberate about sensitive data; you rarely want full message contents or credentials sitting in plaintext logs, so prefer settings that exclude them. Second, plan for rotation and retention, because logs grow and an unbounded log file will eventually fill a disk and take your instance down with it. Structured output, where supported, makes logs far easier to search and analyze later, which is worth the small upfront effort.

Securing the deployment

The security portion of the configuration is where you decide who can reach your agents and how your data is protected, and it is the part most often neglected until something goes wrong. The essentials come down to a few decisions.

• Authentication. If the service is reachable by anyone but you, require authentication. An open, network-exposed agent endpoint is a liability.
• Transport security. Force HTTPS for anything beyond local experimentation so credentials and content are not sent in the clear.
• Origin restrictions. If a web client talks to your service, restrict which origins are allowed rather than accepting requests from anywhere.
• Encryption at rest. Sensitive stored data should be encrypted where supported, so a compromised disk does not hand over everything.

The honest summary is that security settings are the ones most tempting to skip during setup and most painful to skip in production. Decide them before you expose anything, not after.

Environment-specific configurations

A practical pattern is to keep separate configurations for development, staging, and production rather than toggling one file back and forth, because the right settings genuinely differ by environment. Development wants verbose logging, loose limits, and higher model creativity for experimentation. Production wants quiet logging, tight rate limits, enforced authentication and HTTPS, and conservative, predictable agent behavior. Maintaining distinct configurations means you never accidentally ship debug verbosity or a wide-open rate limit to a live system, and you never cripple your local iteration with production-grade restrictions.

Validating changes before you ship them

The safest way to change OpenClaw configuration is to validate it in a non-production environment before it ever touches a live system. A reliable routine looks like this:

1. Check the syntax. Malformed configuration is the most common reason an instance refuses to start. Validate the file before anything else.
2. Start it locally. Bring the configuration up in a development environment first and confirm it boots cleanly.
3. Read the startup logs. Warnings and errors at boot are early signals that something is misconfigured.
4. Test one agent end to end. Verify a single agent behaves correctly before enabling the whole fleet.
5. Watch resources. Keep an eye on CPU, memory, and API usage so a new setting does not quietly blow past your limits.
6. Roll out gradually. Move changes to production incrementally rather than flipping everything at once, so a mistake is contained.

Common configuration pitfalls

The most common configuration pitfall is committing secrets into the file, which turns version control into a leak. Beyond that, a handful of mistakes recur often enough to call out:

• Granting agents more tools than they need, which widens both your cost exposure and your risk surface.
• Exposing the service publicly without authentication, the configuration equivalent of leaving the front door open.
• Leaving development verbosity on in production, which floods logs and can capture sensitive data.
• Ignoring log rotation, which works fine right up until a disk fills.
• Editing live configuration without a tested rollback, so a bad change has no clean way back.

A managed platform takes several of these off your plate. On a myHermy OpenClaw VPS you get secrets handled securely, daily backups so a bad configuration change has a guaranteed restore point, and full root SSH when you do want to inspect and tune things directly.

Frequently asked questions

Where do I put API keys and passwords?

Never in the configuration file itself. Use environment variables or a secrets mechanism so credentials stay out of version control and out of any file you might share. The configuration should reference secrets, not contain them.

How do I keep different settings for development and production?

Maintain separate configurations per environment rather than editing one file repeatedly. Development favors verbose logging and loose limits; production favors quiet logging, tight rate limits, and enforced security. Separate files prevent accidental cross-contamination.

What is the safest way to test a configuration change?

Validate the syntax, bring it up in a non-production environment, read the startup logs, exercise a single agent, watch resource usage, and only then roll out gradually. Always have a known-good configuration to revert to.

Do the exact field names in this guide match my version?

Treat the specifics here as concepts rather than a literal schema. OpenClaw evolves, and field names and defaults can change between releases, so confirm the details against the configuration reference for your installed version.

Configuration is your lever, not your obstacle

The real power of OpenClaw configuration is that it lets you reshape behavior without writing code: change models, adjust how agents reason, add or remove tools, and tune security and limits, all from settings. Mastering that means thinking in trade-offs, capability versus control, convenience versus exposure, verbosity versus volume, and making each decision on purpose.

If you would rather spend that effort on what your agents do than on the plumbing underneath them, myHermy runs OpenClaw on a dedicated Hetzner VPS with root SSH, secure secret handling, daily backups, and OAuth subscription bridging so you can reuse plans like ChatGPT Plus, Claude Max, GitHub Copilot, or SuperGrok instead of paying API rates. Plans start at $19/mo. See how it compares on the OpenClaw alternative page, or deploy from the myHermy home page.