Config Files, Environment Variables, and Provider Secret Management

Once OpenClaw runs, configuration becomes the next source of confusion.

Model providers, Gateway tokens, channels, plugins, workspaces, and tool policy all touch the config system.

If API keys are scattered across files, debugging and migration become painful.

The Key Idea: Config Describes Structure, Env Injects Values, SecretRefs Protect Long-Lived Credentials

Think in three layers:

openclaw.json
  system structure and policy

environment variables
  runtime value injection

SecretRef
  supported credentials without plaintext config

Do not treat them as interchangeable.

openclaw.json Is the Main Config

Default path:

~/.openclaw/openclaw.json

Custom path:

OPENCLAW_CONFIG_PATH=/path/to/openclaw.json openclaw gateway

The docs warn that symlinked openclaw.json layouts are not supported for OpenClaw-owned writes, because atomic writes may replace the path.

Four Ways to Edit Config

openclaw onboard
  first-run interactive setup

openclaw configure
  configuration wizard

openclaw config get/set/unset
  command-line edits

Control UI Config tab
  schema-driven form plus Raw JSON

Direct file edits are allowed, but schema validation is strict.

Unknown keys, wrong types, or invalid values can stop the Gateway from starting.

Provider Configuration

Models are referenced as provider/model, for example:

openai/gpt-5.4
anthropic/claude-sonnet-4-6

A config can define a primary model and fallbacks:

{
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-5.4",
        fallbacks: ["anthropic/claude-sonnet-4-6"],
      },
    },
  },
}

Real deployments should answer:

What is the default model?
What is the fallback?
Which models are user-selectable?
Should images be downscaled?
Is long context actually needed?

Where Environment Variables Fit

Environment variables are good for:

container injection
CI/CD temporary values
Gateway tokens
provider API keys
local testing

Example:

export OPENCLAW_GATEWAY_TOKEN="..."
export OPENAI_API_KEY="..."

They are simple, but service environments differ. Your terminal may have a variable that launchd, systemd, or Docker does not.

SecretRef for Long-Lived Secrets

OpenClaw supports SecretRefs:

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

It also supports file and exec providers:

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }
{ source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }

The goal is to avoid plaintext credentials in openclaw.json, auth-profiles.json, .env, and generated model files.

But SecretRef is not process isolation. If plaintext keys remain in files the agent can read, file or shell tools may still expose them.

A Safer Secret Migration Flow

Use:

1. locate plaintext credentials
2. configure secrets.providers
3. replace supported fields with SecretRefs
4. reload secrets
5. audit for plaintext residue
6. encrypt or redact old backups

Useful commands:

openclaw secrets reload
openclaw secrets audit --check

Common Misunderstandings

Anything can go in config

No. The schema is strict.

Environment variables are automatically safer

Not always. They can leak through service managers, debug output, logs, or local processes.

SecretRef solves everything

Only if old plaintext files and generated residues are cleaned up.

A provider only needs an API key

Production provider setup also needs fallback, allowlists, context choices, cost awareness, and rate-limit planning.

Final Summary

Configuration is a runtime boundary, not a bag of fields.

openclaw.json defines structure, environment variables inject runtime values, SecretRefs protect supported long-lived credentials, and doctor/audit detect drift.

Exercises

1. Read the current workspace with openclaw config get agents.defaults.workspace.
2. Identify whether your provider key is plaintext, env-based, or SecretRef-based.
3. Inspect the config schema through CLI or Control UI.
4. Draft a migration plan from plaintext keys to SecretRefs.

Next Lesson Preview

Next we cover ports, reverse proxies, HTTPS, and LAN access.

References

• OpenClaw Docs: Configuration
• OpenClaw Docs: Configuration reference
• OpenClaw Docs: Secrets management
• OpenClaw Docs: Models
• OpenClaw Docs: Model failover