docs(onboard): fix non-interactive command examples (#121954)

Align copyable onboarding commands with the mandatory risk acknowledgement and an explicit health disposition for config-only automation.\n\nRefs #121951.
2026-08-12 21:53:00 -06:00 · 2026-08-11 01:35:00 -07:00
parent 64e3712e82
commit d7df852bb4
25 changed files with 55 additions and 57 deletions
@@ -220,7 +220,7 @@ OPENCLAW_LOCALE=en openclaw onboard # Explicit English override
 `--non-interactive` requires `--accept-risk` (acknowledges that agents are powerful and full system access is risky). `--mode` defaults to `local`.

 ```bash
-openclaw onboard --non-interactive --accept-risk \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "foo-large" \
@@ -235,22 +235,20 @@ openclaw onboard --non-interactive --accept-risk \
 LM Studio also has a provider-specific key flag:

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice lmstudio \
  --custom-base-url "http://localhost:1234/v1" \
  --custom-model-id "qwen/qwen3.5-9b" \
-  --lmstudio-api-key "$LM_API_TOKEN" \
-  --accept-risk
+  --lmstudio-api-key "$LM_API_TOKEN"
 ```

 Non-interactive Ollama:

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
-  --custom-model-id "qwen3.5:27b" \
-  --accept-risk
+  --custom-model-id "qwen3.5:27b"
 ```

 `--custom-base-url` defaults to `http://127.0.0.1:11434`. `--custom-model-id` is optional; if omitted, onboarding uses Ollama's suggested defaults. Cloud model IDs such as `kimi-k2.5:cloud` also work here.
@@ -258,10 +256,9 @@ openclaw onboard --non-interactive \
 Store provider keys as refs instead of plaintext:

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice openai-api-key \
-  --secret-input-mode ref \
-  --accept-risk
+  --secret-input-mode ref
 ```

 With `--secret-input-mode ref`, onboarding stores new credentials as env-backed refs instead of plaintext: auth profiles use `keyRef: { source: "env", provider: "default", id: <envVar> }`, and custom providers use `models.providers.<id>.apiKey` (for example `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`). Set the provider env var when adding a new credential; an inline key flag without its matching env var fails fast. Existing resolvable named auth profiles and their `env`, `file`, `exec`, or `store` references are reused unchanged, without a new `apiKey` or `keyRef` write or additional provider env var. Existing plaintext profile credentials are not migrated; run `openclaw secrets configure --apply`, then `openclaw secrets audit --check`. See [Secrets management](/gateway/secrets).
@@ -279,13 +276,12 @@ With `--secret-input-mode ref`, onboarding stores new credentials as env-backed
 ```bash
 export OPENAI_API_KEY="your-provider-key"
 export OPENCLAW_GATEWAY_TOKEN="your-token"
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice openai-api-key \
  --secret-input-mode ref \
  --gateway-auth token \
-  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
-  --accept-risk
+  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN
 ```

 ### Local gateway health
@@ -309,7 +305,7 @@ openclaw onboard --non-interactive \

 ```bash
 # Promptless endpoint selection
-openclaw onboard --non-interactive --accept-risk \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice zai-coding-global \
  --zai-api-key "$ZAI_API_KEY"

@@ -319,7 +315,7 @@ openclaw onboard --non-interactive --accept-risk \
 Mistral:

 ```bash
-openclaw onboard --non-interactive --accept-risk \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_API_KEY"
 ```
@@ -148,7 +148,7 @@ openclaw gateway status --json
 For CLI-only use without a managed Gateway service:

 ```powershell
-openclaw onboard --non-interactive --skip-health
+openclaw onboard --non-interactive --accept-risk --skip-health
 openclaw gateway run
 ```

@@ -84,7 +84,7 @@ openclaw gateway restart
 <Tabs>
  <Tab title="Direct (Arcee platform)">
    ```bash
-    openclaw onboard --non-interactive \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice arceeai-api-key \
      --arceeai-api-key "$ARCEEAI_API_KEY"
@@ -93,7 +93,7 @@ openclaw gateway restart

  <Tab title="Via OpenRouter">
    ```bash
-    openclaw onboard --non-interactive \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice arceeai-openrouter \
      --openrouter-api-key "$OPENROUTER_API_KEY"
@@ -40,7 +40,7 @@ openclaw onboard --auth-choice baseten-api-key
 ```

 ```bash Direct flag
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice baseten-api-key \
  --baseten-api-key "$BASETEN_API_KEY"
 ```
@@ -40,7 +40,7 @@ openclaw onboard --auth-choice cerebras-api-key
 ```

 ```bash Direct flag
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice cerebras-api-key \
  --cerebras-api-key "$CEREBRAS_API_KEY"
 ```
@@ -65,7 +65,7 @@ export CEREBRAS_API_KEY=csk-...
 ## Non-interactive setup

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice cerebras-api-key \
  --cerebras-api-key "$CEREBRAS_API_KEY"
@@ -73,7 +73,7 @@ openclaw gateway restart
 For scripted or CI setups, pass all values on the command line:

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice cloudflare-ai-gateway-api-key \
  --cloudflare-ai-gateway-account-id "your-account-id" \
@@ -45,7 +45,7 @@ openclaw gateway restart
 3. Run onboarding:

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice cohere-api-key \
  --cohere-api-key "$COHERE_API_KEY"
 ```
@@ -40,7 +40,7 @@ openclaw onboard --auth-choice featherless-api-key
 For non-interactive setup:

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice featherless-api-key \
  --featherless-api-key "$FEATHERLESS_API_KEY"
@@ -37,7 +37,7 @@ openclaw onboard --auth-choice fireworks-api-key
 ```

 ```bash Direct flag
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice fireworks-api-key \
  --fireworks-api-key "$FIREWORKS_API_KEY"
 ```
@@ -35,7 +35,7 @@ the Gateway already runs inside a managed Google Cloud environment.
        Or pass the key directly:

        ```bash
-        openclaw onboard --non-interactive \
+        openclaw onboard --non-interactive --accept-risk --skip-health \
          --mode local \
          --auth-choice gemini-api-key \
          --gemini-api-key "$GEMINI_API_KEY"
@@ -59,7 +59,7 @@ title: "Hugging Face (inference)"
 ### Non-interactive setup

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"
@@ -21,7 +21,7 @@ spend limits, and backend failover without changing OpenClaw config.
    For non-interactive setup against a remote proxy, pass the proxy URL explicitly:

    ```bash
-    openclaw onboard --non-interactive --accept-risk --auth-choice litellm-api-key \
+    openclaw onboard --non-interactive --accept-risk --skip-health --auth-choice litellm-api-key \
      --litellm-api-key "$LITELLM_API_KEY" --custom-base-url "https://litellm.example/v1"
    ```

@@ -73,7 +73,7 @@ curl http://localhost:1234/api/v1/models
 ## Non-interactive onboarding

 ```bash
-openclaw onboard --non-interactive --accept-risk --auth-choice lmstudio
+openclaw onboard --non-interactive --accept-risk --skip-health --auth-choice lmstudio
 ```

 Or specify base URL, model, and API key explicitly:
@@ -82,6 +82,7 @@ Or specify base URL, model, and API key explicitly:
 openclaw onboard \
  --non-interactive \
  --accept-risk \
+  --skip-health \
  --auth-choice lmstudio \
  --custom-base-url http://localhost:1234/v1 \
  --lmstudio-api-key "$LM_API_TOKEN" \
@@ -56,7 +56,7 @@ primary model is already configured.
 ### Non-interactive setup

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice longcat-api-key \
  --longcat-api-key "$LONGCAT_API_KEY"
@@ -39,7 +39,7 @@ openclaw onboard --auth-choice meta-api-key
 ```

 ```bash Direct flag
-openclaw onboard --non-interactive --accept-risk \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice meta-api-key \
  --meta-api-key "$MODEL_API_KEY"
 ```
@@ -66,7 +66,7 @@ export MODEL_API_KEY=<key>
 ## Non-interactive setup

 ```bash
-openclaw onboard --non-interactive --accept-risk \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice meta-api-key \
  --meta-api-key "$MODEL_API_KEY"
@@ -86,11 +86,10 @@ OpenAI-SDK-style examples, but new config should use `baseUrl`.
    Non-interactive:

    ```bash
-    openclaw onboard --non-interactive \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --auth-choice ollama \
      --custom-base-url "http://ollama-host:11434" \
-      --custom-model-id "qwen3.5:27b" \
-      --accept-risk
+      --custom-model-id "qwen3.5:27b"
    ```

    `--custom-base-url` and `--custom-model-id` are optional; omitting them uses the local default host and the `gemma4` suggested model.
@@ -38,7 +38,7 @@ openclaw onboard --auth-choice tokenhub-api-key
 ```

 ```bash TokenHub direct flag
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice tokenhub-api-key \
  --tokenhub-api-key "$TOKENHUB_API_KEY"
 ```
@@ -48,7 +48,7 @@ openclaw onboard --auth-choice tokenplan-api-key
 ```

 ```bash TokenPlan direct flag
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice tokenplan-api-key \
  --tokenplan-api-key "$TOKENPLAN_API_KEY"
 ```
@@ -47,7 +47,7 @@ OpenClaw bundles it as the `together` provider.
 ### Non-interactive example

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice together-api-key \
  --together-api-key "$TOGETHER_API_KEY"
@@ -50,7 +50,7 @@ Anonymized models are not fully private. Venice strips metadata before forwardin
      </Tab>
      <Tab title="Non-interactive">
        ```bash
-        openclaw onboard --non-interactive \
+        openclaw onboard --non-interactive --accept-risk --skip-health \
          --auth-choice venice-api-key \
          --venice-api-key "vapi_xxxxxxxxxxxx"
        ```
@@ -60,7 +60,7 @@ refs such as `vercel-ai-gateway/openai/gpt-5.5` and
 ## Non-interactive example

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY"
@@ -60,7 +60,7 @@ vLLM serves open-source (and some custom) models through an **OpenAI-compatible*
 For non-interactive setup (CI, scripting), pass the base URL, key, and model directly:

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice vllm \
  --custom-base-url "http://127.0.0.1:8000/v1" \
@@ -58,7 +58,7 @@ The Volcengine provider gives access to Doubao models and third-party models hos
 For non-interactive setup (CI, scripting), pass the key directly:

 ```bash
-openclaw onboard --non-interactive \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice volcengine-api-key \
  --volcengine-api-key "$VOLCANO_ENGINE_API_KEY"
@@ -186,7 +186,7 @@ Gateway token SecretRef in non-interactive mode:

 ```bash
 export OPENCLAW_GATEWAY_TOKEN="your-token"
-openclaw onboard --non-interactive --accept-risk \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
@@ -9,6 +9,8 @@ sidebarTitle: "CLI automation"

 Use `openclaw onboard --non-interactive` to script setup. It requires `--accept-risk`: non-interactive setup can write credentials and daemon config without a confirmation prompt, so the flag is the explicit risk acknowledgement.

+Each command must install a managed Gateway with `--install-daemon`, use `--skip-health` for config-only setup, or run with an already-running compatible Gateway.
+
 <Note>
 `--json` does not imply non-interactive mode. Pass `--non-interactive --accept-risk` explicitly for scripts.
 </Note>
@@ -35,7 +37,7 @@ Add `--json` for a machine-readable summary.
 - `--secret-input-mode ref` stores new credentials as env-backed references (`{ source: "env", provider: "default", id: "<ENV_VAR>" }`); set the provider env var when adding a credential or passing an inline key flag. Existing resolvable named profiles and their `env`, `file`, `exec`, or `store` references are reused unchanged, without a new credential write or additional provider env var. Existing plaintext is not migrated; run `openclaw secrets configure --apply`, then `openclaw secrets audit --check`. See [Secrets management](/gateway/secrets).

 ```bash
-openclaw onboard --non-interactive --accept-risk \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice openai-api-key \
  --secret-input-mode ref
@@ -46,7 +48,7 @@ openclaw onboard --non-interactive --accept-risk \
 <AccordionGroup>
  <Accordion title="Anthropic API key example">
    ```bash
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice apiKey \
      --anthropic-api-key "$ANTHROPIC_API_KEY" \
@@ -55,7 +57,7 @@ openclaw onboard --non-interactive --accept-risk \
  </Accordion>
  <Accordion title="Cloudflare AI Gateway example">
    ```bash
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice cloudflare-ai-gateway-api-key \
      --cloudflare-ai-gateway-account-id "your-account-id" \
@@ -66,7 +68,7 @@ openclaw onboard --non-interactive --accept-risk \
  </Accordion>
  <Accordion title="Gemini example">
    ```bash
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice gemini-api-key \
      --gemini-api-key "$GEMINI_API_KEY" \
@@ -75,7 +77,7 @@ openclaw onboard --non-interactive --accept-risk \
  </Accordion>
  <Accordion title="Mistral example">
    ```bash
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice mistral-api-key \
      --mistral-api-key "$MISTRAL_API_KEY" \
@@ -84,7 +86,7 @@ openclaw onboard --non-interactive --accept-risk \
  </Accordion>
  <Accordion title="Moonshot example">
    ```bash
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice moonshot-api-key \
      --moonshot-api-key "$MOONSHOT_API_KEY" \
@@ -93,7 +95,7 @@ openclaw onboard --non-interactive --accept-risk \
  </Accordion>
  <Accordion title="Ollama example">
    ```bash
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice ollama \
      --custom-model-id "qwen3.5:27b" \
@@ -102,7 +104,7 @@ openclaw onboard --non-interactive --accept-risk \
  </Accordion>
  <Accordion title="OpenCode example">
    ```bash
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice opencode-zen \
      --opencode-zen-api-key "$OPENCODE_API_KEY" \
@@ -112,7 +114,7 @@ openclaw onboard --non-interactive --accept-risk \
  </Accordion>
  <Accordion title="Synthetic example">
    ```bash
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice synthetic-api-key \
      --synthetic-api-key "$SYNTHETIC_API_KEY" \
@@ -121,7 +123,7 @@ openclaw onboard --non-interactive --accept-risk \
  </Accordion>
  <Accordion title="Vercel AI Gateway example">
    ```bash
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice ai-gateway-api-key \
      --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
@@ -130,7 +132,7 @@ openclaw onboard --non-interactive --accept-risk \
  </Accordion>
  <Accordion title="Z.AI example">
    ```bash
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice zai-api-key \
      --zai-api-key "$ZAI_API_KEY" \
@@ -139,7 +141,7 @@ openclaw onboard --non-interactive --accept-risk \
  </Accordion>
  <Accordion title="Custom provider example">
    ```bash
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice custom-api-key \
      --custom-base-url "https://llm.example.com/v1" \
@@ -159,7 +161,7 @@ openclaw onboard --non-interactive --accept-risk \

    ```bash
    export CUSTOM_API_KEY="your-key"
-    openclaw onboard --non-interactive --accept-risk \
+    openclaw onboard --non-interactive --accept-risk --skip-health \
      --mode local \
      --auth-choice custom-api-key \
      --custom-base-url "https://llm.example.com/v1" \
@@ -368,7 +368,7 @@ The results screen lists the detected applications and shows: "App names were ma
 powerful and full system access is risky):

 ```bash
-openclaw onboard --non-interactive --accept-risk \
+openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY"
 ```