Securing openclaw.json: Configuration File Best Practices

Your openclaw.json is the central configuration file for your OpenClaw instance. It may reference API keys, service credentials, and agent instructions. Securing it properly is essential.

What's in openclaw.json

A typical openclaw.json includes:

• LLM provider configuration (potentially API keys)
• Channel configurations (bot tokens, webhook URLs)
• Skill configurations (service credentials)
• Agent instructions and system prompts
• Security settings

If any of this is misconfigured or exposed, your entire agent setup is compromised.

File System Permissions (Self-Hosted)

# Set appropriate ownership
sudo chown openclaw:openclaw /etc/openclaw/openclaw.json

# Restrict permissions — owner read/write only
sudo chmod 600 /etc/openclaw/openclaw.json

Only the openclaw system user should be able to read this file. No group read, no other read.

Never Store Secrets Directly

// BAD — never do this
{
  "llm": {
    "api_key": "sk-ant-api03-actual-key-here"
  }
}

// GOOD — reference secrets by name
{
  "llm": {
    "api_key": "${ANTHROPIC_API_KEY}"
  }
}

Use openclaw secrets set to store the actual value encrypted.

Never Commit to Version Control

If you use git to manage your configuration:

Add to .gitignore:

openclaw.json
.openclaw/
*.secrets
.env

If you've accidentally committed credentials, rotate them immediately and clean history with BFG Repo-Cleaner.

Configuration Encryption at Rest

For particularly sensitive deployments, encrypt the configuration directory:

# Using gocryptfs
gocryptfs -init /opt/openclaw-config-encrypted
gocryptfs /opt/openclaw-config-encrypted /opt/openclaw-config
# Place openclaw.json in /opt/openclaw-config
# Unmount when not running

This adds a layer of protection if the host is compromised.

Backup Security

If you back up your OpenClaw configuration:

• Encrypt backups before storing remotely
• Use dedicated backup credentials, not the same keys as active deployment
• Store backup encryption keys separately from backups

nacre.sh Configuration Security

On nacre.sh, your configuration is:

• Stored encrypted in nacre.sh's secure configuration store
• Never accessible to nacre.sh employees in plaintext
• Automatically backed up and versioned
• Accessible only via your authenticated nacre.sh account

Frequently Asked Questions

Can I use an .env file instead of the secrets system?

Yes, with caution. An .env file with proper permissions (600) is acceptable. The advantage of OpenClaw's native secrets system is that secrets are encrypted at rest, unlike a plaintext .env file.

Should I version-control my openclaw.json at all?

Version control is valuable for configuration management, but strip all secrets first. Use secret references (${VAR_NAME}) in the committed config. Keep a separate, secure store for the actual values.

What format does the secrets store use?

OpenClaw's secrets store encrypts values using AES-256-GCM with a key derived from a master password (or system hardware key on supported platforms). Run openclaw secrets info to see details.