Rough guide:

- **Install:** 2-5 minutes

- **Onboarding:** 5-15 minutes depending on how many channels/models you configure

- **QuickStart onboarding:** usually a few minutes

- **Full onboarding:** longer when provider sign-in, channel pairing, daemon install,

network downloads, skills, or optional plugins need extra setup

The CLI wizard shows this timeline up front. You can skip optional steps and return

later with `openclaw configure`.

If it hangs, use [Installer stuck](#quick-start-and-first-run-setup)

and the fast debug loop in [I am stuck](#quick-start-and-first-run-setup).

- **Daemon install** (LaunchAgent on macOS; systemd user unit on Linux/WSL2)

- **Health checks** and **skills** selection

It also warns if your configured model is unknown or missing auth.

It also sets duration expectations before the main prompts begin and warns if your

configured model is unknown or missing auth.

</Accordion>

```

The wizard walks you through choosing a model provider, setting an API key,

and configuring the Gateway. It takes about 2 minutes.

and configuring the Gateway. QuickStart is usually only a few minutes, but

provider sign-in, channel pairing, daemon install, network downloads, skills,

or optional plugins can make full onboarding take longer. You can skip optional

steps and return later with `openclaw configure`.

See [Onboarding (CLI)](/start/wizard) for the full reference.

openclaw onboard

```

QuickStart is usually only a few minutes, but full onboarding can take longer

when provider sign-in, channel pairing, daemon install, network downloads,

skills, or optional plugins need extra setup. The wizard shows this timeline up

front, and optional steps can be skipped and revisited later with

`openclaw configure`.

## Locale

The CLI wizard localizes fixed onboarding copy. It resolves locale from

await fs.writeFile(allowedAbsolutePath, "seed");

const tools = [

createOpenClawReadTool(createReadTool(workspaceDir) as unknown as AnyAgentTool),

wrapToolMemoryFlushAppendOnlyWrite(createHostWorkspaceWriteTool(workspaceDir), {

root: workspaceDir,

relativePath: allowedRelativePath,

}),

];

const writeTool = requireTool(tools, "write");

expect(tools.map((tool) => tool.name).toSorted()).toEqual(["read", "write"]);

expect(tools.map((tool) => tool.name)).toEqual(["write"]);

await expect(

writeTool.execute("test-call-memory-deny", {

return sessionFile;

}

async function waitUntil(predicate: () => boolean, message: string): Promise<void> {

const deadline = Date.now() + 1_000;

while (!predicate()) {

if (Date.now() >= deadline) {

throw new Error(message);

}

await new Promise<void>((resolve) => {

setTimeout(resolve, 1);

});

}

}

function cloneBigIntStatWith(

stat: Awaited<ReturnType<typeof fs.stat>>,

fields: Partial<Awaited<ReturnType<typeof fs.stat>>>,

.finally(() => {

takeoverSettled = true;

});

await new Promise<void>((resolve) => {

setImmediate(resolve);

});

await waitUntil(

() => controller.hasSessionTakeover(),

"expected takeover detection while active retained writer was still running",

);

expect(takeoverSettled).toBe(false);

expect(releaseRetained).not.toHaveBeenCalled();

releaseActiveWrite();

await expect(activeWrite).resolves.toBeUndefined();

await expect(activeWrite).rejects.toBeInstanceOf(EmbeddedAttemptSessionTakeoverError);

await expect(takeoverWrite).resolves.toBeInstanceOf(EmbeddedAttemptSessionTakeoverError);

expect(releaseRetained).toHaveBeenCalledTimes(1);

authChoiceRequired: "auth choice is required",

channelsTitle: "Channels",

configHandling: "Config handling",

durationNote:

"We'll walk through model/auth, workspace, Gateway, channels, web search, skills, and optional plugin setup. QuickStart is usually only a few minutes, but provider sign-in, channel pairing, daemon install, network downloads, and optional dependencies can take longer. You can skip optional steps and return later with {command}.",

durationTitle: "Setup timeline",

existingConfigTitle: "Existing config detected",

flowAdvanced: "Manual setup",

flowAdvancedHint: "Choose Gateway port, network exposure, Tailscale, and auth.",

authChoiceRequired: "必须选择认证方式",

channelsTitle: "频道",

configHandling: "配置处理",

durationNote:

"接下来会依次设置模型/认证、工作区、Gateway、频道、网页搜索、技能和可选插件。QuickStart 通常只需几分钟，但提供商登录、频道配对、daemon 安装、网络下载和可选依赖可能需要更久。你可以跳过可选步骤，之后用 {command} 返回配置。",

durationTitle: "设置流程",

existingConfigTitle: "检测到已有配置",

flowAdvanced: "手动设置",

flowAdvancedHint: "选择 Gateway 端口、网络暴露、Tailscale 和认证方式。",

authChoiceRequired: "必須選擇認證方式",

channelsTitle: "頻道",

configHandling: "設定處理",

durationNote:

"接下來會依序設定模型/認證、工作區、Gateway、頻道、網頁搜尋、技能和選用插件。QuickStart 通常只需幾分鐘，但提供者登入、頻道配對、daemon 安裝、網路下載和選用依賴可能需要更久。你可以略過選用步驟，之後用 {command} 返回設定。",

durationTitle: "設定流程",

existingConfigTitle: "偵測到既有設定",

flowAdvanced: "手動設定",

flowAdvancedHint: "選擇 Gateway 連接埠、網路暴露、Tailscale 和認證方式。",

expect(healthCommand).not.toHaveBeenCalled();

expect(runTui).not.toHaveBeenCalled();

});

it("shows setup duration expectations before the security acknowledgement", async () => {

const note: WizardPrompter["note"] = vi.fn(async () => {});

const confirm = vi.fn(async () => true) as unknown as WizardPrompter["confirm"];

const prompter = buildWizardPrompter({ note, confirm });

const runtime = createRuntime({ throwsOnExit: true });

await runSetupWizard(

{

flow: "quickstart",

authChoice: "skip",

installDaemon: false,

skipProviders: true,

skipSkills: true,

skipSearch: true,

skipHealth: true,

skipUi: true,

},

runtime,

prompter,

);

const calls = getWizardNoteCalls(note);

expect(calls[0]?.[1]).toBe("Setup timeline");

expect(calls[0]?.[0]).toContain("model/auth, workspace, Gateway, channels");

expect(calls[0]?.[0]).toContain("openclaw configure");

expect(calls[1]?.[1]).toBe("Security disclaimer");

});

it("persists skipBootstrap and skips workspace bootstrap creation when requested", async () => {

ensureWorkspaceAndSessions.mockClear();

replaceConfigFile.mockClear();

const onboardHelpers = await import("../commands/onboard-helpers.js");

onboardHelpers.printWizardHeader(runtime);

await prompter.intro(t("wizard.setup.intro"));

await prompter.note(

t("wizard.setup.durationNote", {

command: formatCliCommand("openclaw configure"),

}),

t("wizard.setup.durationTitle"),

);

await requireRiskAcknowledgement({ opts, prompter });

const snapshot = await readSetupConfigFileSnapshot();