How to Set Up OpenClaw Environment Variables

OpenClaw is powerful because it can keep running, connect to channels, call tools, and act from a machine you control. That also means its environment variables deserve more care than a one-off local .env file.

The goal is not to make setup complicated. The goal is to make startup repeatable, keep secrets out of Git, and avoid the quiet drift that happens when every developer and host has a slightly different set of values. If you are evaluating the broader workflow, Ghostable’s OpenClaw integration page is the right product-level starting point.

Start with the runtime boundary

OpenClaw’s current environment documentation explains a non-overriding precedence model: process environment first, then local .env, then the global state .env, then config-level env, with optional shell import after that. That order matters because the value present at process startup usually wins.

For teams, the clean pattern is to treat the process environment as the final runtime boundary. Local files can help development, but the host, service manager, or container runtime should receive the final values explicitly. When OpenClaw runs as a daemon, do not assume your interactive shell profile is part of the startup path.

This is also why setup should be written down before the first shared deployment. A developer can make OpenClaw work by exporting one key in a terminal. A team needs to know which values are required, where they come from, who can change them, and how a restart receives them.

Use .env.openclaw for local development

A local .env.openclaw file is useful as a developer-facing convention even though OpenClaw itself documents .env and global state paths. It gives teams a named place for OpenClaw-specific values without mixing them into unrelated app configuration.

The important detail is how you load it. If you use a wrapper script, Docker Compose, or a process manager, point that startup flow at .env.openclaw and keep the file ignored by Git. The committed file should be .env.openclaw.example, with variable names and safe placeholder values only.

For a local host workflow, the pattern is simple:

cp .env.openclaw.example .env.openclaw
set -a
. ./.env.openclaw
set +a
openclaw gateway run

That shell flow is intentionally boring. It makes the runtime environment visible before OpenClaw starts and avoids hiding credential loading inside a config file that later gets copied around.

Keep host startup explicit

The local shell is not the production model. Once OpenClaw is installed as a service, the service definition owns the environment. On Linux, that usually means a systemd environment file or service-level environment entries. On macOS, LaunchAgent or LaunchDaemon configuration needs the same explicit treatment.

The risk is subtle: OpenClaw may work during onboarding and then fail after reboot because the daemon did not inherit the same variables. That failure often gets patched by pasting secrets into whatever file is nearby. A better fix is to make the service startup read from the same source every time.

If you use Ghostable, that source should be the environment-specific secret set. Developers receive only what they are allowed to use, the host receives the values needed to boot, and the values are still decrypted locally rather than exposed to Ghostable servers.

Docker and container startup

Containerized OpenClaw should follow the same rule: inject values at runtime, not in the image. Dockerfiles should not contain model provider keys, channel tokens, gateway tokens, or OAuth client secrets. Compose files can reference an env file for local development, but the real values should stay outside the committed file.

A development Compose service might use an env file:

services:
  openclaw:
    image: openclaw/openclaw:latest
    env_file:
      - .env.openclaw
    volumes:
      - openclaw-state:/home/openclaw/.openclaw

That is a startup convenience, not a secret governance model. For shared environments, use your deployment platform’s secret injection mechanism or a controlled export from Ghostable into the host runtime. Keep the state directory persistent, but keep credentials independently rotatable.

What belongs in the first setup pass

The first pass should include only values needed to boot and verify OpenClaw. Model provider credentials, channel tokens, gateway authentication, and path overrides are common. Optional debugging flags and experimental provider keys can wait until they are actually needed.

Overloading the initial env file creates two problems. First, nobody knows which variables are still used. Second, stale values survive because removing them feels risky. A small setup surface is easier to audit and easier to rotate.

OpenClaw’s own environment variable reference is the current source for precedence and path behavior. Its getting started guide is useful for confirming the install and gateway startup flow.

Where Ghostable fits

Ghostable should be the team source of truth for OpenClaw runtime secrets, not a replacement for OpenClaw configuration. Keep behavior, channels, and model routing in OpenClaw config. Keep sensitive values in Ghostable and inject them into the runtime environment when the gateway starts.

That gives you a cleaner boundary: OpenClaw receives the variables it needs, while Ghostable handles access, versioning, and rotation. Because Ghostable uses zero-knowledge encryption, plaintext secrets are encrypted and decrypted locally and are not readable by Ghostable.

The setup is successful when a new developer or host can start OpenClaw without asking someone to paste a token into chat. That is the practical bar. Everything else is cleanup.