OpenClaw onboarding: set up a self-hosted agent with a verified model
OpenClaw onboarding starts by proving the agent can use a model. It detects available access, runs a live completion, and saves the selected route only after that test succeeds. Only then does the setup flow hand over workspace, Gateway, channel, and agent configuration. That order matters: a polished setup wizard is not useful if the first real agent turn cannot run.
This guide covers the current OpenClaw onboarding path for a local or self-hosted deployment. It is about setting up the agent itself, not building an onboarding bot for employees or customers.
Table of contents
- What OpenClaw onboarding proves first
- Choose the right setup path
- A practical OpenClaw onboarding sequence
- Keep configuration changes reviewable
- When to use the classic wizard
What OpenClaw onboarding proves first
A fresh OpenClaw install needs an inference route before it needs a long list of integrations. The guided flow checks available AI access, such as a supported local CLI or API credentials, then asks a candidate model for a real response. A passing completion is the boundary: OpenClaw saves the model and credential only after the route works.
That is more reliable than treating a detected environment variable or an installed CLI as proof that the agent is ready. A credential can be expired, a selected model can be unavailable, and a local service can be installed but unreachable. The live check turns those failures into setup-time feedback rather than a broken first chat.
In OpenClaw’s architecture, the Gateway coordinates sessions, tools, and delivery. The model route is the dependency that lets the rest of that system become useful. Start there.
Choose the right setup path
OpenClaw offers three paths that overlap less than their names suggest.
| Path | Best for | What it does | Use it when |
|---|---|---|---|
openclaw onboard | A normal new install | Detects access, verifies a model with a live turn, then opens conversational setup | You want the standard route on macOS, Linux, Windows, or WSL2 |
openclaw crestodian | An already working inference route | Opens the local setup and repair assistant | Your model route already works and you want to configure the rest |
openclaw onboard --classic | Detailed or unusual configuration | Opens the step-by-step wizard | You need custom providers, advanced auth, remote Gateway choices, imports, or a daemon install |
The default command is deliberately not a shortcut around verification:
openclaw onboardOn a configured machine, the flow can detect an existing route and validate it. On a new machine, it can offer a masked manual key entry after automatic candidates fail. The important distinction is that OpenClaw tests the proposed route before it persists it.
If you are evaluating whether a self-hosted agent fits your environment, read what OpenClaw is before connecting channels or adding plugins. It helps to decide which data, tools, and machines the agent should be allowed to touch.
A practical OpenClaw onboarding sequence
1. Establish one working model route
Run openclaw onboard and let the guided flow test the candidate it finds. Do not add several providers, channels, and plugins just to discover that the default model cannot return a response.
For a custom endpoint, use the classic wizard instead. The documented classic path supports OpenAI-compatible chat and Responses endpoints, Anthropic-compatible endpoints, and an unknown compatibility mode that probes supported shapes. Keep the first configuration narrow: endpoint, model ID, authentication, and a successful live reply.
2. Let Crestodian configure the operating surface
After inference succeeds, Crestodian can help configure the workspace, Gateway, Gateway service, channels, agents, and plugins. It uses typed operations rather than treating a conversational instruction as permission to rewrite arbitrary configuration.
Read-only requests such as status, health, validate config, model status, and Gateway reachability can run immediately. Persistent work, including creating an agent, writing config, changing the default model, restarting the Gateway, or installing a plugin, requires an explicit approval. That is a sensible default for a system that can later act on your behalf.
The release notes for OpenClaw 2026.7.1 describe this same split: conversational setup runs across the CLI, web install, and macOS app, while approvals bind to exact operations and credential prompts stay masked.
3. Configure channels through the channel wizard
A messaging integration is not the same kind of setting as a workspace name. Channel setup often needs a token or other secret, so Crestodian can hand it off to a masked terminal wizard:
open channel wizard for slackUse channel info <channel> first if you need prerequisites and a documentation link. Keep secrets out of ordinary chat input and avoid pasting them into a transcript that you may later export or share.
For a broader view of boundaries around tools, channels, and approvals, see why OpenClaw is self-hostable. The useful question is not whether an agent can connect to a channel. It is who can authorize that connection, where its credential is stored, and how the resulting actions are recorded.
4. Verify the operational state before expanding scope
Before adding more agents or automations, ask Crestodian for status, run validate config, and check Gateway reachability. Then send one ordinary task through the intended model and delivery surface.
This small test catches the failures that configuration screens can hide: a service that did not start, a channel that points at the wrong account, a model alias that resolves differently than expected, or a Gateway that is only reachable from one machine. Fix that one path before making the system more complex.
Keep configuration changes reviewable
Crestodian is not a general-purpose shell with a friendly face. It separates discovery from writes, asks for approval before persistent operations, and records applied writes in ~/.openclaw/audit/crestodian.jsonl.
It also keeps its own inference route out of its writable configuration surface. Changing provider credentials, top-level authentication, model catalogs, default or per-agent model routes, and several secret-bearing roots requires leaving Crestodian and using onboarding. This avoids an assistant silently changing the model or credentials that power its own session.
That boundary has a practical benefit during debugging. If the model route is broken, return to openclaw onboard. If the config is invalid, use the classic path and openclaw doctor guidance. If the route works but an operational setting needs attention, use Crestodian. Each route has a smaller failure domain than an all-in-one setup chat.
When to use the classic wizard
Use openclaw onboard --classic when you need detailed control that should not be guessed from a brief conversation:
- a custom provider endpoint or compatibility mode
- model and authentication selection beyond the guided inference candidates
- a remote Gateway, daemon installation, imports, or channel-specific setup
- recovery from invalid configuration that needs
doctorguidance
The classic wizard is not a fallback because the conversational flow failed. It is the right tool when you want to inspect and make each setup choice directly. A stable installation often uses both paths: guided onboarding to prove inference, then classic setup for a deliberate infrastructure change later.
FAQ
Does OpenClaw onboarding save a provider before it works?
The guided flow saves a model and credential after a candidate completes a real live response. A detected CLI or API key alone is not treated as sufficient proof that the route is usable.
Can Crestodian repair model credentials?
No. Crestodian does not change the inference provider or authentication route that powers its own session. Exit to openclaw onboard to configure or repair that access.
Is openclaw crestodian the same as the classic wizard?
No. Crestodian is a conversational setup, repair, and configuration assistant for an already verified route. openclaw onboard --classic is the detailed step-by-step setup path.
Can I run OpenClaw onboarding on a server?
Yes. The CLI onboarding path supports macOS, Linux, Windows, and WSL2. For scripts, OpenClaw documents a --non-interactive path; interactive model verification and secret entry still need an appropriate secure setup process.