OpenClaw Configuration Complete Guide: From openclaw.json to Core Model Management

I. openclaw.json: Your Agent Control Panel

OpenClaw's design philosophy is "one config file to manage everything." Whether you need to adjust models, add communication channels, modify Gateway behavior, or configure security permissions, all settings converge in a single file.^[1]

1.1 File Location

The default path is ~/.openclaw/openclaw.json. You can also specify a custom path via the OPENCLAW_CONFIG_PATH environment variable, but this is rarely needed in practice.^[2]

When you run openclaw onboard for the first time, the system automatically creates this file and writes the initial settings. If you have a fresh installation, you don't need to create it manually.

1.2 JSON5 Format

openclaw.json uses the JSON5 format, which is a superset of standard JSON that allows:^[8]

• Inline comments: Use // to add explanations for each setting
• Trailing commas: The last item can have a trailing comma, reducing copy-paste errors
• Unquoted keys: Simplified writing, less visual clutter

This means you can open it directly with a text editor and add comments so team members understand the purpose of each setting. However, the official recommendation is to use CLI commands to modify settings, to avoid syntax errors from manual editing.^[3]

II. Model Settings: Primary and Fallback

Model settings are the most frequently adjusted part of OpenClaw. They determine which large language model your AI agent uses to "think."^[4]

2.1 Setting the Primary Model

Use the following command to set your primary model:

openclaw config set agents.defaults.model.primary claude-opus-4-6

OpenClaw supports multiple model providers, including Anthropic (Claude series), OpenAI (GPT series), Google (Gemini series), and more. When setting the model name, refer to each provider's model identifier.

2.2 Setting Fallback Models

Fallback models automatically activate when the primary model is unavailable (e.g., API rate limiting, service outage):

openclaw config set agents.defaults.model.fallbacks '["claude-sonnet-4-6", "gpt-4o"]'

The fallback list is tried in order: the first available model is selected. In production environments, it is strongly recommended to configure at least one fallback model to ensure continuous agent operation.

2.3 Model Authentication

Each model provider requires independent API key or OAuth authentication. Use the following commands to manage authentication:

// Using API key
openclaw models auth setup-token --provider anthropic

// Using OAuth (interactive authorization)
openclaw models auth login --provider openai

Authentication information is stored in ~/.openclaw/auth-profiles.json, separated from the main configuration file to reduce the risk of accidental exposure.^[6]

III. Gateway Mode Settings

The Gateway is OpenClaw's central hub, routing all messages through it.^[5] The Gateway mode determines who can access your agent.

3.1 Local Mode (Default)

The default local mode only allows connections from localhost (127.0.0.1), suitable for personal development and testing:

openclaw config set gateway.mode local

In this mode, the Web UI is at http://127.0.0.1:18789, accessible only from your own computer.

3.2 Remote Mode

When you need to access OpenClaw from a phone, another device, or an external network, switch to remote mode:

openclaw config set gateway.mode remote

After switching, you need to set up a Gateway Token to prevent unauthorized access:

openclaw doctor --generate-gateway-token

Security reminder: In remote mode, be sure to use TLS (HTTPS) and a strong password Token; otherwise your entire computer will be exposed on the network.^[6]

3.3 Port Configuration

The default port is 18789. If it conflicts with other services, you can customize it:

openclaw config set gateway.port 28789

IV. Workspace and Agent Settings

Workspaces are OpenClaw's logical units for managing agent memory and state. Each Workspace can have independent agent settings.

4.1 Default Workspace Path

openclaw config set agents.defaults.workspace ~/my-workspace

The Workspace directory contains the agent's context memory, conversation history, and tool call records. Different projects can use different Workspaces, allowing the agent to maintain independent knowledge contexts across projects.

4.2 Timeout Settings

The agent's execution time limit is controlled by timeoutSeconds:

openclaw config set agents.defaults.timeoutSeconds 300

The default value is usually sufficient for most tasks. However, if your agent needs to perform long-running operations (such as scanning large codebases or complex browser automation workflows), you may need to increase this value.

V. Common Configuration Commands Quick Reference

All config set commands immediately write to openclaw.json, but some settings (such as Gateway mode) require restarting the Gateway to take effect.^[3]

VI. Security Best Practices

OpenClaw is an agent with access to your entire computer. Improper configuration can lead to serious security risks.^[6][7]

1. Never push openclaw.json to Git: The config file may contain sensitive Tokens and path information
2. Use CLI instead of manual editing: openclaw config set automatically validates format and value legality
3. Remote mode must use a Token: A remote Gateway without a Token is effectively handing over computer control to the public internet
4. Rotate API keys regularly: Update model provider API keys every 90 days
5. Principle of least privilege: Only enable the Skills and Hooks that the agent actually needs, reducing the attack surface

Conclusion

OpenClaw's configuration system is built around the core philosophy of "one file to manage everything," simplifying a complex distributed agent architecture into intuitive key-value pairs.^[1] Master the structure of openclaw.json and the config set command, and you master control over the entire agent system.

If you encounter issues during configuration, refer to our "OpenClaw Troubleshooting Guide", or use openclaw doctor --fix to let the system automatically repair common configuration errors.