CLI Automation: Non-Interactive Setup

Use openclaw onboard --non-interactive to automate setup. It depends on --accept-risk: in non-interactive mode, credentials and daemon configuration can be written without any confirmation prompt, so the flag serves as the explicit acknowledgment of that risk.

Each command has several ways to handle a managed Gateway: install one with --install-daemon, assume an already-running compatible Gateway by leaving out the daemon flags, explicitly keep the Gateway stopped with --skip-daemon, or run config-only setup with --skip-health. The explicit skip still checks for an existing Gateway and tells you whether one is reachable, but a missing listener is treated as informational, not as a setup error.

Note

--json does not turn on non-interactive mode. For scripts, pass --non-interactive --accept-risk explicitly.

Baseline non-interactive example

openclaw onboard --non-interactive --accept-risk \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --secret-input-mode plaintext \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-bootstrap \
  --skip-skills

Add --json to get a machine-readable summary.

--gateway-port is set to 18789 by default; only supply it when you need a different value.
--skip-bootstrap prevents the creation of default workspace files, useful when automation provides its own workspace.
--secret-input-mode ref saves new credentials as env-backed references ({ source: "env", provider: "default", id: "<ENV_VAR>" }); make sure the provider env var is set before adding a credential or passing an inline key flag. Existing named profiles that resolve correctly, along with their env, file, exec, or store references, are kept as is without writing a new credential or requiring an extra provider env var. Existing plaintext is not converted automatically; run openclaw secrets configure --apply, then openclaw secrets audit --check. See Secrets management.

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

Provider-specific examples

Anthropic API key example

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-bind loopback

Cloudflare AI Gateway example

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" \
  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
  --gateway-bind loopback

Gemini example

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY" \
  --gateway-bind loopback

Mistral example

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_API_KEY" \
  --gateway-bind loopback

Moonshot example

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY" \
  --gateway-bind loopback

Ollama example

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice ollama \
  --custom-model-id "qwen3.5:27b" \
  --gateway-bind loopback

OpenCode example

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice opencode-zen \
  --opencode-zen-api-key "$OPENCODE_API_KEY" \
  --gateway-bind loopback

For the Go catalog, switch to --auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY".

Synthetic example

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice synthetic-api-key \
  --synthetic-api-key "$SYNTHETIC_API_KEY" \
  --gateway-bind loopback

Vercel AI Gateway example

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
  --gateway-bind loopback

Z.AI example

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice zai-api-key \
  --zai-api-key "$ZAI_API_KEY" \
  --gateway-bind loopback

Custom provider example

openclaw onboard --non-interactive --accept-risk --skip-health \
  --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 \
  --custom-image-input \
  --gateway-bind loopback

--custom-api-key is not mandatory; some endpoints work without auth. When it is omitted, onboarding looks for CUSTOM_API_KEY in the environment. --custom-provider-id is also optional and is inferred from the base URL when not supplied. --custom-compatibility comes with a default of openai (other accepted values are openai-responses and anthropic).

OpenClaw detects whether image input is supported by matching known vision model identifier patterns, such as the gpt-4o, claude-3/4, gemini, -vl/vision suffixes and comparable forms. To enable it manually for a vision model that isn't recognized, include --custom-image-input; alternatively, --custom-text-input restricts input to text only.

A variant for ref-mode, which saves apiKey under the name { source: "env", provider: "default", id: "CUSTOM_API_KEY" }:

export CUSTOM_API_KEY="your-key"
openclaw onboard --non-interactive --accept-risk --skip-health \
  --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 \
  --custom-image-input \
  --gateway-bind loopback

Although Anthropic setup-token authentication is still supported, OpenClaw will reuse the Claude CLI login whenever a local one exists. For production environments, an Anthropic API key is the recommended choice.

Add another agent

A distinct agent, complete with its own workspace, sessions, and authentication profiles, is created by openclaw agents add <name>. When run without --workspace and with no other flags, the interactive wizard starts; supplying any of --workspace, --model, --agent-dir, --bind, or --non-interactive switches to non-interactive execution, after which --workspace is mandatory.

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.6-sol \
  --bind whatsapp:biz \
  --non-interactive \
  --json

The configuration keys written for the new agent id (the agents.entries.* entry) include:

name
workspace
agentDir
model (included only when --model is supplied)

Additional details:

If --workspace is left out during the interactive wizard, the default workspace becomes ~/.openclaw/workspace-<agentId>.
--bind <channel[:accountId]> can be repeated; add bindings so inbound messages are routed to the new agent (the wizard offers this interactively as well).
The agent name gets normalized into a valid agent id. While main is permitted, an existing named installation might need openclaw doctor --fix to complete legacy-session and shared-auth ownership migrations before the agent can be created.

Onboarding hub: Onboarding (CLI)
Full reference: CLI Setup Reference
Command reference: openclaw onboard