Docs: document secrets refs runtime and migration

docs/start/setup.md

@@ -134,6 +134,8 @@ Use this when debugging auth or deciding what to back up:
   - `~/.openclaw/credentials/<channel>-allowFrom.json` (default account)
   - `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json` (non-default accounts)
 - **Model auth profiles**: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+- **Encrypted secrets payload (optional)**: `~/.openclaw/secrets.enc.json`
+- **Secrets migration backups (optional)**: `~/.openclaw/backups/secrets-migrate/<backupId>/`
 - **Legacy OAuth import**: `~/.openclaw/credentials/oauth.json`
   More detail: [Security](/gateway/security#credential-storage-map).
 

docs/start/wizard-cli-automation.md

@@ -22,6 +22,7 @@ openclaw onboard --non-interactive \
   --mode local \
   --auth-choice apiKey \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --secret-input-mode plaintext \
   --gateway-port 18789 \
   --gateway-bind loopback \
   --install-daemon \
@@ -31,6 +32,18 @@ openclaw onboard --non-interactive \
 
 Add `--json` for a machine-readable summary.
 
+Use `--secret-input-mode ref` to store env-backed refs in auth profiles instead of plaintext values.
+
+Example:
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice openai-api-key \
+  --secret-input-mode ref \
+  --accept-risk
+```
+
 ## Provider-specific examples
 
 <AccordionGroup>

docs/start/wizard-cli-reference.md

@@ -139,8 +139,7 @@ What you set:
 
   </Accordion>
   <Accordion title="OpenAI API key">
-    Uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to
-    `~/.openclaw/.env` so launchd can read it.
+    Uses `OPENAI_API_KEY` if present or prompts for a key, then stores the credential in auth profiles.
 
     Sets `agents.defaults.model` to `openai/gpt-5.1-codex` when model is unset, `openai/*`, or `openai-codex/*`.
 
@@ -202,6 +201,12 @@ Credential and profile paths:
 - OAuth credentials: `~/.openclaw/credentials/oauth.json`
 - Auth profiles (API keys + OAuth): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
 
+API key storage mode:
+
+- Default onboarding behavior persists API keys as plaintext values in auth profiles.
+- `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext values (for example `keyRef: { source: "env", id: "OPENAI_API_KEY" }`).
+- Existing plaintext setups continue to work unchanged.
+
 <Note>
 Headless and server tip: complete OAuth on a machine with a browser, then copy
 `~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`)

docs/start/wizard.md

@@ -65,6 +65,7 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
 
 1. **Model/Auth** — Anthropic API key (recommended), OpenAI, or Custom Provider
    (OpenAI-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model.
+   For non-interactive runs, `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext API key values.
 2. **Workspace** — Location for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files.
 3. **Gateway** — Port, bind address, auth mode, Tailscale exposure.
 4. **Channels** — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, or iMessage.