openclaw configure CLI Reference

`openclaw configure`

Guided prompts let you adjust specific parts of an existing setup: credentials, devices, agent defaults, gateway, channels, plugins, skills, and health checks.

For the complete first-run experience, run openclaw onboard or openclaw setup. Use openclaw setup --baseline when only the base config or workspace needs attention, and turn to openclaw channels add if channel account setup is all you require.

Tip

Calling openclaw config without any subcommand launches the same wizard. For edits that skip interaction, use openclaw config get|set|unset.

Options

--section <section>: a repeatable filter that narrows down sections. The available sections are:

workspace, model, web, gateway, daemon, channels, plugins, skills, health

openclaw configure
openclaw configure --section web
openclaw configure --section model --section channels
openclaw configure --section gateway --section daemon

Choosing gateway, daemon, or health (or launching the full wizard without a --section) triggers a prompt about where the Gateway runs and updates gateway.mode. When section filters omit all three, you jump straight to the requested setup without any gateway-mode question. Opting for remote gateway mode writes the remote config and stops right away; local-only tasks such as plugin installation are skipped.

Note

An interactive terminal is mandatory for openclaw configure (both stdin and stdout must be TTYs). Without one, the equivalent non-interactive openclaw config get|set|patch|validate commands are printed and the process exits with an error rather than executing partially.

Gateway section

With Trusted Proxy auth, supply IPv4 or IPv6 addresses or CIDR ranges separated by commas, for example 10.0.0.1, ::1, 10.0.0.0/24. Before saving, the wizard rejects malformed addresses and blank entries; whitespace around values is ignored.

When an address or CIDR matching a loopback source is entered under Trusted Proxy auth, a security warning appears and explicit consent is requested before gateway.auth.trustedProxy.allowLoopback gets set. If you decline, the setting stays unset and a warning notes that loopback proxy requests will be refused at runtime. See Trusted proxy auth for the trust requirements.

Reconfiguring trusted-proxy mode sets the loopback prompt's default to the prior opt-in and leaves deviceAutoApprove untouched. An explicit refusal withdraws loopback consent; if no matching loopback source exists, the current setting is kept.

Model section

Note

Under Model, a multi-select shows the explicit agents.defaults.modelPolicy.allow list (the one visible in /model and the model picker). Provider-scoped setup choices merge their chosen models into the existing list rather than replacing providers already present in the config. Per-model aliases and parameters stay under agents.defaults.models; those entries alone do not constrain model overrides.

Rerunning provider auth from configure keeps an existing agents.defaults.model.primary intact, even when the provider's auth step returns a config patch that suggests its own default model. Adding or reauthing a provider exposes its models without overriding your current primary model. To change the default model deliberately, use openclaw models auth login --provider <id> --set-default or openclaw models set <model>.

When configure begins from a provider auth choice, the default-model and model-policy pickers favor that provider automatically. For paired providers like Volcengine and BytePlus, the same preference also applies to their coding-plan variants (volcengine-plan/*, byteplus-plan/*). If the preferred-provider filter would yield an empty list, configure falls back to the full catalog instead of showing an empty picker.

Web section

openclaw configure --section web selects a web-search provider and sets up its credentials. Certain providers present extra provider-specific steps:

Grok may offer optional x_search setup sharing the same xAI OAuth profile or API key, and lets you choose an x_search model.
Kimi may request the Moonshot API region (api.moonshot.ai vs api.moonshot.cn) and the default Kimi web-search model.

Other notes

Gateway reconfiguration keeps existing gateway.auth.allowTailscale, gateway.auth.rateLimit, and gateway.auth.identityScopes policies. The selected auth mode replaces its credentials or trusted-proxy settings and drops fields tied to other auth modes.
After local config writes, configure installs selected downloadable plugins when the chosen setup path calls for them. Remote gateway config skips local plugin package installation.
Channel-oriented services (Slack/Discord/Matrix/Microsoft Teams) ask for channel/room allowlists during setup. Names or IDs are accepted; the wizard resolves names to IDs when it can.
Picking Reinstall leaves the current Gateway service in place while you select its runtime and configure validates authentication and readies the replacement. Cancelling or failing during preparation keeps the existing service installed.
After a successful daemon setup, the final Gateway status applies the same platform-specific startup grace period as onboarding before reporting reachability. Service installation and Gateway reachability are separate outcomes; if the Gateway still isn't detected, run openclaw health to recheck.
Running the daemon install step with token auth requires a token. If gateway.auth.token is managed by SecretRef, configure validates the SecretRef but does not store resolved plaintext token values in supervisor service environment metadata; an unresolved SecretRef makes configure block daemon install with actionable remediation guidance.
When both gateway.auth.token and gateway.auth.password are configured and gateway.auth.mode is unset, configure blocks daemon install until the mode is explicitly set.