SecretRef during onboarding | Friends of the Crustacean 🦞🤝 | Page 1

low anvilBOT Mar 12, 2026, 2:32 AM

#

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

fleet nicheBOT Mar 12, 2026, 2:35 AM

#

If you pick SecretRef, the wizard assumes the token already exists outside of OpenClaw (usually as an env var), and it validates it immediately. That’s why you get:

<VAR_NAME> is missing or empty in this session

Option A (recommended): let onboarding generate it

Re-run openclaw onboard and when it asks about the gateway token, choose:

Generate/store plaintext token (default)

Finish onboarding, then you can copy it into your env later:

openclaw config get gateway.auth.token

If you want it in a .env, put it in the global fallback env file OpenClaw loads:

~/.openclaw/.env (aka $OPENCLAW_STATE_DIR/.env)

#

Docs: https://docs.openclaw.ai/help/faq#env-vars-and-env-loading
Wizard reference: https://docs.openclaw.ai/start/wizard-cli-reference

Option B: keep SecretRef, but pre-create the env var

Before running onboarding, set the env var in the same shell session:

export OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)"
openclaw onboard

Then when it asks “Where is the gateway token stored?”, enter OPENCLAW_GATEWAY_TOKEN.

To make it work for the service/daemon too, put the same line in ~/.openclaw/.env (since launchd/systemd often won’t inherit your interactive shell env).

Option C: have OpenClaw generate one via Doctor

OpenClaw can generate one for you:

#

openclaw doctor --generate-gateway-token

(Then read it with openclaw config get gateway.auth.token and place it into ~/.openclaw/.env if that’s where you want it.)

Docs note: https://docs.openclaw.ai/help/faq#the-control-ui-says-unauthorized-or-keeps-reconnecting-what-now

Also: what openclaw --version are you on? (There have been a bunch of wizard/SecretRef improvements lately, so version really matters here.)

torn pewter Mar 12, 2026, 2:38 AM

#

If I do option A, doesn't the token go into the JSON file? is that safe? Should the config be changed after that?

fleet nicheBOT Mar 12, 2026, 2:39 AM

#

Yes — Option A stores the gateway token inline in ~/.openclaw/openclaw.json (as gateway.auth.token).

Is that safe?

Generally yes, as long as that file stays private:

It lives under your home dir (~/.openclaw/…), not in a project repo.
The wizard’s default is plaintext token storage because for many setups that’s totally fine.

But treat it like a real secret anyway: anyone who gets that token can fully control your Gateway (send messages, run tools, read session state, etc.), especially if you bind the Gateway beyond loopback.

Also note: putting it in ~/.openclaw/.env is not inherently “more secure” than openclaw.json — it’s just a different file. Both need to be protected.

Should you change it after onboarding?

Only if you want SecretRef semantics (e.g. you manage secrets externally, rotate via env injection, avoid secrets in config backups, etc.).

A common pattern is:

#

Finish onboarding with plaintext token (easy / unblocks you)
Move it to ~/.openclaw/.env
Switch config to an env SecretRef
Restart the gateway

Example:

Put token in ~/.openclaw/.env:

OPENCLAW_GATEWAY_TOKEN=...paste token here...

Change config to SecretRef:

openclaw config set gateway.auth.token '{"source":"env","provider":"default","id":"OPENCLAW_GATEWAY_TOKEN"}' --strict-json

#

Restart the gateway service.

Docs refs:

Wizard SecretRef behavior (it validates env var must exist): https://docs.openclaw.ai/start/wizard-cli-reference
.env loading locations + precedence: https://docs.openclaw.ai/help/faq#env-vars-and-env-loading

If you tell me your openclaw --version + whether you’re installing as a service (launchd/systemd) + whether your gateway bind is loopback/lan/tailnet, I can say what I’d do in your specific setup.

torn pewter Mar 14, 2026, 12:05 AM

#

When configuring the telegram api key using openclaw onboard, I receive the error "Error: channels.telegram.botToken: unresolved SecretRef "env:default:TELEGRAM_BOT_TOKEN". Resolve this command against an active gateway runtime snapshot before reading it." How do I fix this?

fleet nicheBOT Mar 14, 2026, 12:07 AM

#

That error means your config now contains:

channels.telegram.botToken = SecretRef → env:default:TELEGRAM_BOT_TOKEN

…but the wizard step you’re in is trying to use the Telegram token (not just store the reference), and in that particular code path it won’t read/print SecretRef values directly. It expects to resolve secrets via an active Gateway runtime snapshot (so the CLI can “use the secret” without the CLI ever materializing/printing it).

Fix (practical)

Make sure the env var exists where the Gateway runs:

Put it in the global env file OpenClaw loads:
~/.openclaw/.env (recommended for services)
```
TELEGRAM_BOT_TOKEN=123456:ABCDEF...
```
or export it in the shell before running things:

#

  export TELEGRAM_BOT_TOKEN="123456:ABCDEF..."

Start/restart the gateway so it can load that env and build the runtime snapshot:

openclaw gateway restart
# or if you haven't installed a service yet:
openclaw gateway run

Re-run openclaw onboard (or continue from where you left off).

Two common “gotchas”

If you’re in remote mode: that TELEGRAM_BOT_TOKEN needs to be set on the remote gateway host, not on your local client machine.
If you want onboarding to “just work” without this runtime/snapshot dance: choose plaintext storage for the Telegram token during onboarding, then switch it to SecretRef afterward.

#

Docs that match what you’re seeing:

SecretRef + onboarding validation rules: https://docs.openclaw.ai/start/wizard-cli-reference
Env + .env loading locations: https://docs.openclaw.ai/help/faq#env-vars-and-env-loading

If you paste your openclaw --version + whether you’re doing local vs remote gateway, I can tell you which of the above is the fastest path.

torn pewter Mar 14, 2026, 12:08 AM

#

OpenClaw 2026.3.8 (3caab92) It's a local gateway

fleet nicheBOT Mar 14, 2026, 12:10 AM

#

Cool — on 2026.3.8 local gateway, the fix is basically: make the env vars exist before onboarding tries to validate / use them.

What’s happening

When you choose SecretRef (env:default:…), onboarding will store only the reference (e.g. TELEGRAM_BOT_TOKEN) and then later steps may need the actual token (health check / channel probe / webhook setup). If the gateway isn’t running yet (or the env var is empty), you’ll see that “unresolved SecretRef … resolve against an active gateway runtime snapshot” error.

Do this (local gateway, service-friendly)

Put your secrets in the global env file OpenClaw loads automatically:

~/.openclaw/.env

# gateway auth (pick ONE approach below)
OPENCLAW_GATEWAY_TOKEN=...some random token...

# telegram
TELEGRAM_BOT_TOKEN=123456:ABCDEF...

#

For the gateway token value, if you don’t care what it is:

OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

(then paste that result into ~/.openclaw/.env)

Start the gateway once so there’s an “active runtime snapshot” and it can resolve refs:

openclaw gateway restart
# if you haven't installed a service yet:
openclaw gateway run

Re-run openclaw onboard (typo note: onbaord → onboard) and when asked:

Gateway token SecretRef env name → OPENCLAW_GATEWAY_TOKEN
Telegram bot token SecretRef env name → TELEGRAM_BOT_TOKEN

#

Quick sanity checks

Make sure you’re editing ~/.openclaw/.env (not a project .env).
Confirm OpenClaw is using the expected config/state dir:
```
openclaw config file
```

If you paste the exact step where onboarding errors out (right after selecting Telegram, during health check, during daemon install, etc.), I can point to the specific sub-step that’s trying to read the token and how to skip/force it.

torn pewter Mar 14, 2026, 12:21 AM

#

what does this error mean? ⚠️ Agent failed before reply: No API key found for provider "ollama". Auth store:

Ollama is running locally

fleet nicheBOT Mar 14, 2026, 12:22 AM

#

That error is OpenClaw saying: your config is trying to use the ollama provider, but OpenClaw doesn’t consider Ollama “enabled/configured” unless it can find an apiKey for it.

For local Ollama, this “API key” is just an opt-in flag / placeholder — Ollama itself doesn’t need a real key, but OpenClaw uses the presence of one to enable discovery + health checks.

Fix (local gateway)

Put this in your global env file (recommended for gateway services):

~/.openclaw/.env

OLLAMA_API_KEY=ollama-local

Then restart the gateway:

openclaw gateway restart

#

Alternative (write it into config instead of env)

openclaw config set models.providers.ollama.apiKey "ollama-local"
openclaw gateway restart

Docs

Ollama provider setup (explicitly mentions placeholder key): https://docs.openclaw.ai/providers/ollama

If you’re still stuck after that, paste:

openclaw models status
and whether you set an explicit models.providers.ollama.baseUrl (and confirm it’s not ending in /v1).

torn pewter Mar 14, 2026, 12:28 AM

#

Ollama is running slow as shit

fleet nicheBOT Mar 14, 2026, 12:30 AM

#

Yeah, that’s pretty common with Ollama: if the model is even slightly too big for your hardware, it falls off a cliff (CPU-only, RAM swapping, tiny tokens/sec).

A few fast checks + fixes:

1) You’re probably running too large a model (or it’s not using GPU)

Run:

ollama ps

If you see a big model (tens of billions params) on a normal laptop/CPU, it’ll feel painful. Pick a much smaller model that fits comfortably in RAM/VRAM.

In OpenClaw, check what it’s using:

#

openclaw config get agents.defaults.model.primary

2) Make sure the gateway service actually sees Ollama + env

If you installed the gateway as a service, it might not be inheriting your shell env; put your env in:

~/.openclaw/.env

Then restart:

openclaw gateway restart

3) Long context makes local models crawl

Onboarding / tool use can stuff a lot of text into the prompt. With local models that can tank speed hard. If you’re testing responsiveness, try a fresh short prompt and keep the session small (later, use /new or /compact once you’re chatting).

#SecretRef during onboarding