OpenClaw .env File Guide | Ghostable Article [ Blog ](https://ghostable.dev/blog) [ Articles ](https://ghostable.dev/blog/articles) [ Best Practices ](https://ghostable.dev/blog/category/best-practices) Friday, April 24, 2026 OpenClaw .env File Guide: Structure, Paths, and Examples ========================================================== A practical guide to OpenClaw env file structure, example templates, local paths, and what should never be committed. ![OpenClaw .env File Guide: Structure, Paths, and Examples](https://fls-9fca3102-944c-48ac-a3cc-22f1b47a39c7.laravel.cloud/blog/019dbfb1-eab7-7358-b07d-431489179511/open-claw-env-file.jpg) An OpenClaw `.env` file looks simple until it becomes the unofficial source of truth for a team. Then every copy is slightly different, nobody knows which value is current, and secrets start living in places that were only meant for local setup. A good env file is boring. It names the required runtime values, separates real secrets from examples, and makes it clear which process is responsible for loading it. The file should support OpenClaw startup, not become a second configuration system. The file should describe runtime inputs --------------------------------------- OpenClaw configuration belongs in `openclaw.json`. Runtime secrets and environment-dependent values belong in the process environment. A local env file is just one way to populate that environment before the gateway starts. For local development, a project-level `.env.openclaw` convention is easy to reason about. It keeps OpenClaw values separate from application `.env` files and lets a wrapper script or Compose service load the right values intentionally. OpenClaw’s documented loading behavior also includes current working directory `.env`, global `~/.openclaw/.env`, and config-level `env` entries, all with non-overriding semantics. That precedence is useful, but it can surprise teams that are not explicit about ownership. If two files contain the same variable, the earlier source wins. The safer habit is to avoid duplicates and make the startup path obvious. A practical `.env.openclaw.example` ----------------------------------- The example file should be committed. The real file should not. The example should show names, safe placeholders, and short comments about intent. It should never contain real tokens, personal phone numbers, production gateway passwords, OAuth secrets, or copied values from someone’s machine. ```bash # .env.openclaw.example # Model provider credentials OPENAI_API_KEY= ANTHROPIC_API_KEY= OPENROUTER_API_KEY= # Gateway and runtime behavior OPENCLAW_HOME= OPENCLAW_STATE_DIR= OPENCLAW_CONFIG_PATH= OPENCLAW_LOG_LEVEL=info # Channel credentials TELEGRAM_BOT_TOKEN= DISCORD_BOT_TOKEN= SLACK_BOT_TOKEN= # Optional service startup helpers NODE_EXTRA_CA_CERTS= ``` This is intentionally not exhaustive. It is a template for your team’s active surfaces. If you do not use Slack, do not keep a Slack token slot around forever. Empty placeholders are only useful when they reflect real setup choices. What belongs in the real file ----------------------------- The real `.env.openclaw` file should contain values for one environment only. Local development, staging, and production should not share a single file with commented blocks. That pattern feels convenient, but it leads to accidental promotion and makes review harder. Use names that match the runtime surface. A local developer file can include sandboxed model provider keys and a Telegram test bot token. A production host file should include only the credentials needed by that host and channel set. If a value is not required to boot that environment, leave it out. OpenClaw’s current [environment variable reference](https://docs.openclaw.ai/help/environment) documents path-related variables such as `OPENCLAW_HOME`, `OPENCLAW_STATE_DIR`, and `OPENCLAW_CONFIG_PATH`. Those are operational controls, not generic secrets. They should be set deliberately because they change where OpenClaw reads state, config, sessions, and credentials. Paths and precedence -------------------- The main path decision is whether values live near the project, under OpenClaw’s state directory, or in the parent process environment. For one developer, any of those can work. For a team, the parent process environment is the cleanest runtime boundary because it matches how services and containers actually start. The local file should feed that boundary. A wrapper script can read `.env.openclaw`, export values, and start the gateway. Docker Compose can use `env_file` for development. A service manager can read an environment file on the host. The key is that OpenClaw receives the values at startup, and the team knows which layer provided them. If you need SecretRefs inside OpenClaw config, use OpenClaw’s [secrets management guide](https://docs.openclaw.ai/gateway/secrets) as the source of truth. SecretRefs are useful for supported credential fields, but they do not remove the need to manage source values responsibly. Keep examples safe and useful ----------------------------- The most common mistake is letting `.env.openclaw.example` become a half-redacted copy of someone’s real file. That is worse than no example because it teaches the wrong boundary. The example should help a developer know what to request, not give them working credentials. For Ghostable teams, the example file can point developers toward the shared secret set without exposing values. The real secrets live in Ghostable, access is tied to the user and device, and the local file becomes an output of an approved workflow rather than an artifact passed around manually. The [device-linking guide](https://ghostable.dev/learn/linking-devices) explains that access model in more detail. If you already have old `.env` files floating around, clean them up before adding more automation. OpenClaw can only be as reliable as the startup inputs you give it. A clear file structure is the cheapest place to start. [ Back to blog ](https://ghostable.dev/blog) [All articles](https://ghostable.dev/blog/articles) Want product news and updates? -------------------------------- Sign up for our newsletter. Email Address Subscribe → Subscribing... We care about your data. Read our [privacy policy](https://ghostable.dev/privacy).