first commit

content/start/wizard-cli-automation.md

@@ -0,0 +1,203 @@
+---
+summary: "Scripted onboarding and agent setup for the OpenClaw CLI"
+read_when:
+  - You are automating onboarding in scripts or CI
+  - You need non-interactive examples for specific providers
+title: "CLI Automation"
+sidebarTitle: "CLI automation"
+---
+
+# CLI Automation
+
+Use `--non-interactive` to automate `openclaw onboard`.
+
+<Note>
+`--json` does not imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
+</Note>
+
+## Baseline non-interactive example
+
+```bash
+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 \
+  --daemon-runtime node \
+  --skip-skills
+```
+
+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 configured provider refs (`file` or `exec`) 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:
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice openai-api-key \
+  --secret-input-mode ref \
+  --accept-risk
+```
+
+## Provider-specific examples
+
+<AccordionGroup>
+  <Accordion title="Gemini example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice gemini-api-key \
+      --gemini-api-key "$GEMINI_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Z.AI example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice zai-api-key \
+      --zai-api-key "$ZAI_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Vercel AI Gateway example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice ai-gateway-api-key \
+      --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Cloudflare AI Gateway example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice cloudflare-ai-gateway-api-key \
+      --cloudflare-ai-gateway-account-id "your-account-id" \
+      --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
+      --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Moonshot example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice moonshot-api-key \
+      --moonshot-api-key "$MOONSHOT_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Mistral example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice mistral-api-key \
+      --mistral-api-key "$MISTRAL_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Synthetic example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice synthetic-api-key \
+      --synthetic-api-key "$SYNTHETIC_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="OpenCode Zen example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice opencode-zen \
+      --opencode-zen-api-key "$OPENCODE_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Custom provider example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice custom-api-key \
+      --custom-base-url "https://llm.example.com/v1" \
+      --custom-model-id "foo-large" \
+      --custom-api-key "$CUSTOM_API_KEY" \
+      --custom-provider-id "my-custom" \
+      --custom-compatibility anthropic \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+
+    `--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", provider: "default", id: "CUSTOM_API_KEY" }`.
+
+  </Accordion>
+</AccordionGroup>
+
+## Add another agent
+
+Use `openclaw agents add <name>` to create a separate agent with its own workspace,
+sessions, and auth profiles. Running without `--workspace` launches the wizard.
+
+```bash
+openclaw agents add work \
+  --workspace ~/.openclaw/workspace-work \
+  --model openai/gpt-5.2 \
+  --bind whatsapp:biz \
+  --non-interactive \
+  --json
+```
+
+What it sets:
+
+- `agents.list[].name`
+- `agents.list[].workspace`
+- `agents.list[].agentDir`
+
+注意事项：
+
+- Default workspaces follow `~/.openclaw/workspace-<agentId>`.
+- Add `bindings` to route inbound messages (the wizard can do this).
+- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
+
+## Related docs
+
+- Onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
+- Full reference: [CLI Onboarding Reference](/start/wizard-cli-reference)
+- Command reference: [`openclaw onboard`](/cli/onboard)