feat(secrets): expand onboarding secret-ref flows and custom-provider parity

docs/start/wizard-cli-automation.md

@@ -33,6 +33,10 @@ 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.
+Interactive selection between env refs and encrypted file refs (`sops`) is available in the onboarding wizard flow.
+
+In non-interactive `ref` mode, provider env vars must be set in the process environment.
+Passing inline key flags without the matching env var now fails fast.
 
 Example:
 
@@ -145,6 +149,24 @@ openclaw onboard --non-interactive \
 
     `--custom-api-key` is optional. If omitted, onboarding checks `CUSTOM_API_KEY`.
 
+    Ref-mode variant:
+
+    ```bash
+    export CUSTOM_API_KEY="your-key"
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice custom-api-key \
+      --custom-base-url "https://llm.example.com/v1" \
+      --custom-model-id "foo-large" \
+      --secret-input-mode ref \
+      --custom-provider-id "my-custom" \
+      --custom-compatibility anthropic \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+
+    In this mode, onboarding stores `apiKey` as `{ source: "env", id: "CUSTOM_API_KEY" }`.
+
   </Accordion>
 </AccordionGroup>
 

docs/start/wizard-cli-reference.md

@@ -177,6 +177,10 @@ What you set:
   <Accordion title="Custom provider">
     Works with OpenAI-compatible and Anthropic-compatible endpoints.
 
+    Interactive onboarding supports the same API key storage choices as other provider API key flows:
+    - **Paste API key now** (plaintext)
+    - **Use secret reference** (env or encrypted `sops` file pointer, with preflight validation)
+
     Non-interactive flags:
     - `--auth-choice custom-api-key`
     - `--custom-base-url`
@@ -204,7 +208,19 @@ Credential and profile paths:
 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" }`).
+- `--secret-input-mode ref` enables reference mode instead of plaintext key storage.
+  In interactive onboarding, you can choose either:
+  - environment variable ref (for example `keyRef: { source: "env", id: "OPENAI_API_KEY" }`)
+  - encrypted file ref via `sops` JSON pointer (for example `keyRef: { source: "file", id: "/providers/openai/apiKey" }`)
+- Interactive reference mode runs a fast preflight validation before saving.
+  - Env refs: validates variable name + non-empty value in the current onboarding environment.
+  - File refs: validates `secrets.sources.file` + `sops` decrypt + JSON pointer resolution.
+  - If preflight fails, onboarding shows the error and lets you retry.
+- In non-interactive mode, `--secret-input-mode ref` is env-backed only.
+  - Set the provider env var in the onboarding process environment.
+  - Inline key flags (for example `--openai-api-key`) require that env var to be set; otherwise onboarding fails fast.
+  - For custom providers, non-interactive `ref` mode stores `models.providers.<id>.apiKey` as `{ source: "env", id: "CUSTOM_API_KEY" }`.
+  - In that custom-provider case, `--custom-api-key` requires `CUSTOM_API_KEY` to be set; otherwise onboarding fails fast.
 - Existing plaintext setups continue to work unchanged.
 
 <Note>

docs/start/wizard.md

@@ -66,6 +66,8 @@ 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.
+   In non-interactive `ref` mode, the provider env var must be set; passing inline key flags without that env var fails fast.
+   In interactive runs, choosing secret reference mode lets you point at either an environment variable or an encrypted `sops` file pointer, with a fast preflight validation before saving.
 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.