status: complete audience: both chapter: 02 last_updated: 2026-04 contributors: [alexwill87, claude-cockpit] lang: en

2.12 -- OpenClaw Initial Configuration

Context

The file ~/.openclaw/config.json is the control center of OpenClaw. Each field affects system behavior. This section details a complete and annotated configuration file.

Complete configuration file

Create or edit ~/.openclaw/config.json :

{
  // --- Identification ---
  "instance_name": "oa-paris",
  "environment": "production",

  // --- IA Model ---
  "model": {
    "provider": "openrouter",
    "default_model": "anthropic/claude-sonnet-4",
    "fallback_model": "anthropic/claude-haiku-4-5",
    "temperature": 0.3,
    "max_tokens": 8192
  },

  // --- Vault Connection ---
  "vault": {
    "enabled": true,
    "address": "http://127.0.0.1:8200",
    "token_env": "VAULT_TOKEN",
    "secret_prefix": "secret"
  },

  // --- Database ---
  "database": {
    "type": "postgresql",
    "vault_path": "secret/database",
    "pool_size": 10,
    "ssl": false
  },

  // --- Gateway ---
  "gateway": {
    "host": "127.0.0.1",
    "port": 3000,
    "cors_origins": []
  },

  // --- Notifications ---
  "notifications": {
    "telegram": {
      "enabled": true,
      "vault_path": "secret/telegram"
    }
  },

  // --- Logging ---
  "logging": {
    "level": "info",
    "file": "~/.openclaw/logs/openclaw.log",
    "max_size_mb": 50,
    "max_files": 5
  },

  // --- Workspace ---
  "workspace": {
    "path": "~/.openclaw/workspace",
    "auto_save_memory": true,
    "session_retention_days": 30
  },

  // --- Security ---
  "security": {
    "allowed_commands": ["git", "npm", "node", "docker", "docker compose"],
    "blocked_paths": ["/etc/shadow", "/root"],
    "require_confirmation_for": ["rm", "drop", "delete", "truncate"]
  }
}

OpenRouter model names change regularly. Before configuring, verify the current names at openrouter.ai/models. The names above were valid in April 2026.

Note : JSON does not support comments. Remove the // lines in the final file, or use a JSON5 preprocessor. The comments above are for documentation only.

Field-by-field explanation

instance_name

Unique identifier for this instance. Useful if you have multiple VPS. Appears in logs and notifications.

model

vault

database

security

Connecting to Vault

For the configuration to work, the Vault token must be available as an environment variable :

$ export VAULT_TOKEN="your-application-token"

To make this permanent, add to ~/.bashrc :

export VAULT_TOKEN="your-application-token"

Or better : use the systemd file (section 15) to inject the variable.

Model selection

Recommendation : Claude Sonnet as default, Haiku as fallback.

Registering models in agents.defaults.models

In addition to configuring the primary model, OpenClaw needs models to be registered in the agents.defaults.models section so agents can use them. Add this section to ~/.openclaw/config.json :

"agents": {
  "defaults": {
    "models": [
      {
        "id": "anthropic/claude-sonnet-4",
        "provider": "openrouter",
        "role": "primary"
      },
      {
        "id": "anthropic/claude-haiku-4-5",
        "provider": "openrouter",
        "role": "fallback"
      }
    ]
  }
}

Or via the CLI :

$ openclaw config set agents.defaults.models --strict-json '[{"id":"anthropic/claude-sonnet-4","provider":"openrouter","role":"primary"},{"id":"anthropic/claude-haiku-4-5","provider":"openrouter","role":"fallback"}]'

Without this step, OpenClaw agents will not know which model to use and will fail with a "no model configured for agent" error.

Syntax for openclaw config set

If you prefer to configure via the CLI rather than editing JSON manually, here is the syntax for openclaw config set :

Strings (quotes required for values containing spaces or special characters) :

$ openclaw config set instance_name "oa-paris"
$ openclaw config set model.default_model "anthropic/claude-sonnet-4"

Booleans :

$ openclaw config set vault.enabled true
$ openclaw config set database.ssl false

Numbers :

$ openclaw config set model.temperature 0.3
$ openclaw config set model.max_tokens 8192

JSON objects (use --strict-json to pass a complete object) :

$ openclaw config set model --strict-json '{"provider":"openrouter","default_model":"anthropic/claude-sonnet-4","fallback_model":"anthropic/claude-haiku-4-5","temperature":0.3,"max_tokens":8192}'

List current configuration :

$ openclaw config get
$ openclaw config get model.default_model

Common pitfall : If you forget quotes around a string containing / (like anthropic/claude-sonnet-4), the shell may interpret it differently. Always wrap values in quotes.

Common errors

• Invalid JSON : Remove the // comments from the file. Validate with jq . ~/.openclaw/config.json.
• Missing Vault token : The error appears when OpenClaw starts. Check echo $VAULT_TOKEN.
• Model not found : Verify the exact model name at openrouter.ai/models.
• Pool size too large : PostgreSQL has a limited number of connections (100 by default). 10 is reasonable.

Verification

$ cat ~/.openclaw/config.json | python3 -m json.tool
$ openclaw doctor

Expected results : - Valid JSON (no parsing errors) - Doctor : valid configuration

Estimated time

15 minutes.