Environment variables not being read | Friends of the Crustacean 🦞🤝 | Page 1

frigid canyon Apr 19, 2026, 2:42 PM

#

I have copied my tokens into a file located at ~/.openclaw/.env but OpenClaw is not reading them. I get the following message:

missing env var "OPENCLAW_GATEWAY_TOKEN" at gateway.auth.token - feature using this value will be unavailable

cursive pikeBOT Apr 19, 2026, 2:42 PM

#

glacial belfryBOT Apr 19, 2026, 2:42 PM

#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

cursive pikeBOT Apr 19, 2026, 2:42 PM

#

mint hearthBOT Apr 19, 2026, 2:44 PM

#

Let me verify the docs path and the expected .env behavior before I answer.

#

I’ve got the relevant docs. I want to confirm one likely gotcha too: whether an already-set empty env var will block .env from filling it.

#

That path is correct, but one important detail: ~/.openclaw/.env is only a fallback source. OpenClaw loads env from:

process/service env
current working dir .env
~/.openclaw/.env

and it does not override an existing value.

So the common causes here are:

OPENCLAW_GATEWAY_TOKEN is not actually in ~/.openclaw/.env
you added provider tokens, but not the gateway token specifically
the gateway needs a restart after editing the file
the service is using a different HOME / OPENCLAW_STATE_DIR
OPENCLAW_GATEWAY_TOKEN is already set somewhere else as empty/stale, so .env won’t replace it

A couple quick checks:

#

does your file contain a line exactly like
OPENCLAW_GATEWAY_TOKEN=...
after editing it, did you run
openclaw gateway restart
what does
openclaw --version
print?
are you running it directly, or via installed service/systemd/launchd?

If you’re on macOS, also run this locally and just tell me whether it returns anything, don’t paste the token:

launchctl getenv OPENCLAW_GATEWAY_TOKEN

Docs: https://docs.openclaw.ai/help/faq#env-vars-and-env-loading and https://docs.openclaw.ai/help/environment

#

If you want, paste a redacted version of the relevant .env lines and I’ll spot the issue fast.

frigid canyon Apr 19, 2026, 2:47 PM

#

OPENCLAW_GATEWAY_TOKEN="xxxxxxxxxx"

#

and the launchctl command returned nothing

mint hearthBOT Apr 19, 2026, 2:48 PM

#

I want to confirm one install-method-specific gotcha before I answer, because Docker/Clawdock handles the gateway token a bit differently.

#

Your .env line itself looks plausible, but I want to verify whether quoted values are accepted before I tell you that part is definitely fine.

#

That line itself looks fine, so I don’t think the quotes are the problem.

The next important question is how you installed/running OpenClaw:

native/service install: ~/.openclaw/.env is the right place, but you need to restart the gateway, and .env will not override an env var that already exists as empty/stale
Docker / ClawDock: the gateway token often belongs in the project .env, while ~/.openclaw/.env is for provider keys/bot tokens
Podman: ~/.openclaw/.env is correct

Can you paste:

openclaw --version

and tell me whether you’re running:

native / service
Docker / ClawDock

#

Podman

Also, after editing the file, did you run:

openclaw gateway restart

One more gotcha on macOS: a launchctl env var can override what’s in .env. If that’s your setup, run this locally and just tell me whether it says set or missing:

launchctl getenv OPENCLAW_GATEWAY_TOKEN >/dev/null && echo set || echo missing

Docs: https://docs.openclaw.ai/help/faq#env-vars-and-env-loading
If Docker/ClawDock: https://docs.openclaw.ai/install/clawdock

#

Also, if xxxxxxxxxx was your real token and not redacted, rotate it.

frigid canyon Apr 19, 2026, 2:49 PM

#

here is the version: OpenClaw 2026.4.15 (041266a)

mint hearthBOT Apr 19, 2026, 2:49 PM

#

Since launchctl isn’t setting it, I want one more verified diagnostic that won’t expose the token: whether OpenClaw is actually looking at the state dir you think it is.

#

Nice, that rules out the launchctl override.

At this point, the most likely issue is a config/state-dir mismatch, meaning the CLI and the running gateway service are looking at different places.

Can you run these and paste the output?

openclaw --version
openclaw gateway status

I’m specifically looking for whether gateway status shows different values for:

Config (cli)
Config (service)

If those differ, you’re editing one ~/.openclaw/.env while the service is reading another profile/state dir.

#

Also tell me whether this is:

native/service install
Docker / ClawDock
Podman

If you paste the gateway status output, I should be able to pinpoint it pretty fast. Redact anything sensitive if needed.

#

Thanks, that version looks fine, so this probably isn’t a stale-release bug.

The next thing I need is:

openclaw gateway status

Please paste that output, especially these lines if they appear:

Config (cli)
Config (service)

That will tell us if the gateway service is reading a different state dir/profile than the one where you put ~/.openclaw/.env.

Also, if you’re using Docker / ClawDock / Podman, say that too, because the gateway token path can differ there.

frigid canyon Apr 19, 2026, 2:50 PM

#

the command returned: set

mint hearthBOT Apr 19, 2026, 2:50 PM

#

Aha, that’s the smoking gun.

If the launchctl check says set, then OPENCLAW_GATEWAY_TOKEN already exists in the macOS service environment, probably as an empty or stale value. OpenClaw does not let ~/.openclaw/.env override an existing env var, so that would produce exactly what you’re seeing.

That also explains why the raw launchctl getenv OPENCLAW_GATEWAY_TOKEN looked blank earlier, it can be set but empty.

Try this:

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
openclaw gateway restart

If you may have used password auth before, also clear that one:

#

launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

Then try OpenClaw again.

If it still complains after that, paste:

openclaw gateway status

Docs: https://docs.openclaw.ai/cli/doctor#macos-launchctl-env-overrides

frigid canyon Apr 19, 2026, 2:50 PM

#

I installed via npm

#

on Macos

mint hearthBOT Apr 19, 2026, 2:51 PM

#

Yep, with a plain npm/native install, ~/.openclaw/.env is the right file.

So this points even more strongly to the macOS launchctl env override we just found. Most likely OPENCLAW_GATEWAY_TOKEN is set there as blank/stale, and that blocks .env from being used.

I’d do this next:

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
openclaw gateway restart

If you may have used password auth before too:

launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

#

Then try again.

If it still fails after that, paste:

openclaw gateway status

and I’ll keep digging.

#

Yep, that matches the diagnosis exactly.

macOS + npm install + launchctl says the var is set = the launchd env is overriding your ~/.openclaw/.env, probably with an empty/stale value.

Please run:

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
openclaw gateway restart

Then try again.

If it still complains after that, paste:

#

openclaw gateway status

I’m pretty confident this is the issue.

frigid canyon Apr 19, 2026, 2:54 PM

#

The gateway did not start. Here's the output from openclaw gateway status:

Config (/Users/garcia/.openclaw/openclaw.json): missing env var "OPENCLAW_GATEWAY_TOKEN" at gateway.auth.token - feature using this value will be unavailable
Config (/Users/garcia/.openclaw/openclaw.json): missing env var "TELEGRAM_BOT_TOKEN" at channels.telegram.botToken - feature using this value will be unavailable
Config (/Users/garcia/.openclaw/openclaw.json): missing env var "GOOGLE_PLACES_TOKEN" at skills.entries.goplaces.apiKey - feature using this value will be unavailable

🦞 OpenClaw 2026.4.15 (041266a) — I'm not AI-powered, I'm AI-possessed. Big difference.

│
◇
Service: LaunchAgent (loaded)
File logs: /tmp/openclaw/openclaw-2026-04-19.log
Command: /opt/homebrew/opt/node/bin/node /opt/homebrew/lib/node_modules/openclaw/dist/index.js gateway --port 18789
Service file: ~/Library/LaunchAgents/ai.openclaw.gateway.plist
Service env: OPENCLAW_GATEWAY_PORT=18789

Config (cli): ~/.openclaw/openclaw.json
Config (service): ~/.openclaw/openclaw.json

Gateway: bind=loopback (127.0.0.1), port=18789 (service args)
Probe target: ws://127.0.0.1:18789
Dashboard: http://127.0.0.1:18789/
Probe note: Loopback-only gateway; only local clients can connect.

Runtime: running (pid 4199, state active)
Warm-up: launch agents can take a few seconds. Try again shortly.
RPC probe: failed
RPC auth: gateway.auth.token SecretRef is unresolved in this command path; probing without configured auth credentials.
RPC target: ws://127.0.0.1:18789
gateway closed (1006):

Gateway port 18789 is not listening (service appears running).
Last gateway error: 2026-04-19T10:52:53.675-04:00 Gateway failed to start: Error: Startup failed: required secrets are unavailable. SecretRefResolutionError: Environment variable "GOOGLE_PLACES_TOKEN" is missing or empty.
Logs: ~/.openclaw/logs/gateway.log
Errors: ~/.openclaw/logs/gateway.err.log

Troubles: run openclaw status
Troubleshooting: https://docs.openclaw.ai/troubleshooting

mint hearthBOT Apr 19, 2026, 2:55 PM

#

The new output narrows it down a lot. I want to check one implementation detail: whether a single bad line in .env causes OpenClaw to ignore the whole file.

#

This helps a lot.

Good news: CLI and service are using the same config, so it’s not a profile/state-dir mismatch.

The important line is this one:

Gateway failed to start ... GOOGLE_PLACES_TOKEN is missing or empty

So two things are true right now:

OpenClaw is still not successfully loading your ~/.openclaw/.env
The fatal blocker is GOOGLE_PLACES_TOKEN being unresolved

A very common macOS gotcha here is that the .env file is malformed or not plain text. Can you run these and paste the output?

#

sed -E 's/=.*$/=REDACTED/' ~/.openclaw/.env
file ~/.openclaw/.env

That will let me check the formatting safely.

Also, to keep it simple, make sure the file uses plain dotenv format, one per line, with no spaces around = and preferably no quotes:

OPENCLAW_GATEWAY_TOKEN=...
TELEGRAM_BOT_TOKEN=...
GOOGLE_PLACES_TOKEN=...

If you don’t actually use Telegram or the Google Places skill, we can also remove/disable those config references so the gateway stops hard-failing.

frigid canyon Apr 19, 2026, 2:57 PM

#

Strangely, the response to those commands is "No such file or directory". Which is crazy, because I literally see the file in the directory.

mint hearthBOT Apr 19, 2026, 2:58 PM

#

That actually explains a lot.

On macOS, this usually means the file is not really named exactly ~/.openclaw/.env, even if Finder makes it look like it is. Common culprits are:

.env.txt
.env.rtf
weird hidden characters / extension hiding
saved in a different folder than you think

Can you run these and paste the output?

ls -la ~/.openclaw
find ~/.openclaw -maxdepth 1 -name '.env*' -print

I strongly suspect we’re going to find something like .env.txt.

#

If that’s what it is, rename it to exactly:

~/.openclaw/.env

and make sure it’s plain text, not rich text.

TextEdit is especially sneaky here on macOS. If you used it, that’s very likely the issue.

frigid canyon Apr 19, 2026, 2:59 PM

#

/Users/garcia/.openclaw/.env.example

mint hearthBOT Apr 19, 2026, 2:59 PM

#

There it is 😄

OpenClaw reads:

~/.openclaw/.env

It does not read:

~/.openclaw/.env.example

So that’s the issue.

Do this:

#

cp ~/.openclaw/.env.example ~/.openclaw/.env
openclaw gateway restart

Or rename it instead if you want:

mv ~/.openclaw/.env.example ~/.openclaw/.env
openclaw gateway restart

After that, OpenClaw should actually see those env vars.

If it still fails after the rename/copy, paste the new openclaw gateway status output and I’ll check the next thing.

frigid canyon Apr 19, 2026, 3:02 PM

#

It runs! Perfect! Can you recommend a better text editor for macOS than TextEdit?

mint hearthBOT Apr 19, 2026, 3:02 PM

#

Nice, glad we caught it 🎉

For macOS, I’d recommend:

BBEdit: my top pick for plain-text/config editing on Mac, solid, very Mac-native
CotEditor: lightweight, fast, great for .env, JSON, YAML, etc.
VS Code: great if you already do coding and want one editor for everything

If you just want a better TextEdit replacement, I’d go with BBEdit or CotEditor.

Also, if this fixed it, please right-click the solution message → Apps → ✅ Mark Solution. That helps Answer Overflow index it for future users.

#Environment variables not being read