Skip to content

[Feature]: conversational chat-based zeroclaw onboard (port of OpenClaw onboard --modern / Crestodian) #8034

Description

@JordanTheJet

Summary

Replace the deprecated zeroclaw onboard stub with a simple conversational, chat-based setup assistant — a Rust analog of OpenClaw's openclaw onboard --modern ("Crestodian").

Problem statement

Today zeroclaw onboard is a deprecation stub that just points users at zeroclaw quickstart. New users have no conversational, plain-language path to inspect their install or stand one up — they must know the quickstart checklist or memorize config set paths. OpenClaw solved this with onboard --modern, a small conversational assistant ("Crestodian") that maps natural-language requests to a fixed, safe command vocabulary with approval-gated writes. ZeroClaw (Rust) has no equivalent.

Proposed solution

A CLI-first, conversational zeroclaw onboard (bare invocation = interactive chat), modeled on OpenClaw's --modern flow but kept deliberately simple:

  • overview — resolved-on-demand snapshot (config validity, default model, agents, providers + key presence, gateway reachability), reusing existing config/doctor accessors. No cached state.
  • deterministic parser — closed command vocabulary (status, doctor, models, agents, gateway status, validate config, setup, set default model, config set, talk to agent, help). Matched before any LLM is consulted.
  • LLM planner (fallback only) — reached only on unrecognized input; maps NL → one allowed command via the agent's configured model (chat_with_system). Output is re-validated through the same parser, so model text can never execute outside the vocabulary. Deterministic-only when no model is configured (first-run safe).
  • approval-gated executor — write/lifecycle ops print a plan and require explicit approval; reuse existing surfaces (doctor::run, run_configured_models, the quickstart apply path, set_prop_persistent). Secret redaction via the schema's canonical prop_is_secret.
  • Modes: interactive (default), --message <text> one-shot, --json overview dump.

Reference — OpenClaw's implementation (MIT, same lineage):

A CLI implementation is up in #8033.

Non-goals / out of scope (v1)

  • No new config schema fields; every write goes through the existing sanctioned set_prop_persistent/save_dirty or the quickstart apply path.
  • No changes to quickstart (reused as the setup path).
  • TUI pane and web-dashboard surfaces are follow-ups (OpenClaw later wired Crestodian into its TUI shell — see 385da2db60); v1 is CLI-only.

Alternatives considered

  • Keep onboard deprecated and rely on quickstart only — leaves no conversational/repair path and no plain-language entry for new users.
  • A full ratatui chat backend up front (as OpenClaw's TUI shell) — heavier; a CLI readline loop ships the core value first.

Acceptance criteria

  • Bare zeroclaw onboard opens an interactive chat; unrecognized input routes to the planner and is re-validated; persistent ops are approval-gated.
  • Read-only commands (status/doctor/models/agents/gateway status/validate config) work with no model configured.
  • All user-facing strings route through Fluent (cli-onboard-*), satisfying the cli_fluent_coverage gate.

Architecture impact

src/ CLI dispatch + a new src/onboard/ module; reuses runtime::doctor, runtime::quickstart, zeroclaw-providers (chat_with_system), and zeroclaw-config setters. No provider/schema changes.

Risk and rollback

Low — isolated to the onboard command path. Rollback = git revert (restores the prior deprecation stub). Planner is best-effort (failure → deterministic fallback); writes are gated behind approval; no new external endpoints beyond the user's already-configured model + a local gateway health probe.

Metadata

Metadata

Assignees

No one assigned

    Labels

    coreAuto scope: root src/*.rs files changed.enhancementNew feature or requestpriority:p2Medium priorityquickstartrisk:mediumAuto risk: src/** or dependency/config changes.status:in-progressOpen PR actively targets this issue; recheck when PR closes.status:no-staleExempt from 60-day stale auto-close only with public reason and revisit surface.

    Type

    No type

    Projects

    Status
    In Progress
    Status
    In Progress

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions