Onboarding redesign

Onboarding redesign 문서는 OpenClaw 공식 문서(start/onboarding-redesign)를 한국어로 정리한 가이드입니다. Implementation plan for the custodian onboarding redesign (living document) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Implementation plan for the custodian onboarding redesign (living document)

한국어 가이드 범위: start/onboarding-redesign 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Onboarding redesign implementation plan
North star
Current shipped flow (after phases 1-3)
Phases
Implementation notes per phase
Phase 1 — app recommendations (PR #109668)
Phase 2 — CLI custodian spine (PR #109841)
Phase 3 — browser-first handoff (PR #110054, merged)
Phase 4 — web custodian surface (merged: #110141, #110242)
Phase 5 — hatch and bootstrap (merged: #110173, #110331)
Phase 6 — custodian presence (PR1 merged: #110269; commentary/summon are PR2)
Phase 7 — resilience (needs an owner decision before building)
Testing and landing playbook (hard-won; read before phases 4-6)
Decision log
Known gaps and follow-ups

상세 내용

Onboarding redesign implementation plan

North star

A non-technical user types openclaw onboard (or opens the app) and is greeted by one conversational presence — OpenClaw, the system custodian ("custodian" is the internal name only; the user always sees "OpenClaw") — that finds their AI, sets everything up with announced defaults instead of questions, hatches their agent as a visible identity moment, and stays reachable forever after as the system's caretaker. Magic by default, one consent boundary, no dead ends.

주요 항목:

Announced defaults with easy undo replace blocking questions. The only
Question zero is the consent boundary: "Full access" (recommended) means
Conversation as UI with progressive intelligence: the custodian surface
The hatch is a ceremony: same thread, avatar swap, the agent names itself
Trust is tiered by source: official catalog entries may be pre-selected;
Configured installs are sacred: re-running onboarding is a verification
The terminal is the fallback, not a question: prefer the browser
Weak models get a trimmed surface (auto localModelLean), explained in

Current shipped flow (after phases 1-3)

openclaw onboard on a fresh macOS install, happy path — four Enters total:

Phases

#	Phase	Surface	Status
1	Installed-app plugin recommendations (scan, candidates, AI matcher, wizard step, `device.apps` node command)	classic + guided CLI	merged (#109668)
2	CLI custodian spine (question zero, discovery theater, auto-apply + hatch)	guided CLI	merged (`a83ed13204f1`)
3	Browser-first handoff (GUI-session detection, wait-for-dashboard-connect, TUI as fallback)	CLI → web	merged (#110054)
4	Web custodian surface (option cards, typed `question` field on `openclaw.chat`, wizard-step mirroring, first-run handoff)	Control UI	merged (#110141, #110242)
5	Hatch and bootstrap (recommendations store with once-semantics, self-naming birth sequence, auto-hatch handoff after fresh setup; avatar ladder deferred)	agent bootstrap	merged (#110173, #110331)
6	Custodian presence PR1 (pinned sidebar entry, Ask OpenClaw in Settings, normal-chrome caretaker greeting; event commentary and channel summon are PR2)	web + channels	merged (#110269)
7	Resilience (custodian reachable on broken config, partial-surface salvage, auto-doctor)	gateway	follow-up

Implementation notes per phase

이 섹션의 세부 항목은 공식 문서 Implementation notes per phase를 참고하세요.

Phase 1 — app recommendations (PR #109668)

offline degradation to catalog-only candidates. Catalog entries are package manifests without a top-level id — candidates are keyed by the resolved plugin id (regression-tested against the real bundled catalogs; keying by entry.id once collapsed the whole catalog and dropped every official recommendation).

주요 항목:

Scanner: src/infra/installed-apps.ts (TCC-free macOS enumeration; follows
Candidates: official catalogs + ClawHub search, 20s overall budget, graceful
AI matcher: one completion on the verified route
Supply-chain guard: ClawHub listing text is publisher-controlled and
Node command device.apps (TS node-host, Android envelope parity), sharing
Delivery lives in the classic wizard and guided custodian flow
Also fixed: custom completeSetupInference prompts no longer inherit the

Phase 2 — CLI custodian spine (PR #109841)

keeps its legacy chat handoff via handoffMode: "chat".

주요 항목:

Flow rework in src/commands/onboard-guided.ts; remote-gateway onboarding
Question zero persists wizard.accessMode ("full" | "guarded"); reruns
Discovery: quiet failure collection (single summary line; details behind
Fresh installs: applySystemAgentSetup (the deterministic conversational

Phase 3 — browser-first handoff (PR #110054, merged)

detection (SSH_CONNECTION/SSH_TTY; DISPLAY/WAYLAND_DISPLAY on Linux) and the 60-second GUI / 300-second SSH wait. Guided onboarding currently enables the handoff only on macOS; --tui and other platforms keep the terminal hatch. Linux/Windows enablement is a follow-up.

주요 항목:

src/commands/onboard-browser-handoff.ts owns pure graphical-session
Dashboard links use the same resolveAdvertisedControlUiLinks,
Readiness polls the existing system-presence RPC as a **CLI-mode loopback
gateway.controlUi.enabled: false short-circuits before any URL is shown.
Proven end-to-end against an isolated same-config gateway: URL print → real

Phase 4 — web custodian surface (merged: #110141, #110242)

(2-4 cards, one recommended max, always skippable); onboarding chrome via ?onboarding=1; model-setup first-run completion hands off into it.

주요 항목:

/custodian page over openclaw.chat with the option-card component
Structured questions are a typed additive question field on
Session ownership is scoped to gateway URL + every presented credential

Phase 5 — hatch and bootstrap (merged: #110173, #110331)

with self-naming. PR1 ships the ceremony capped at three beats (name → soul line → skills question) and defers the self-drawn avatar/image-gen ladder (model-generated candidates → preset marks → keep logo) to a follow-up. Same thread, avatar swap; the claw mark stays reserved for the custodian. The agreed identity persists twice: into IDENTITY.md/SOUL.md (what the agent reads) and via openclaw agents set-identity (what channels and the UI display).

주요 항목:

Custodian creates a nameless agent (tool call); the agent's bootstrap opens
Recommendations (phase 1 service, stored scan with once-semantics) land as
Self-learning is asked, not announced, and doubles as skill-workshop
Auto-hatch shipped: a fresh-install setup apply announces the hatch and

Phase 6 — custodian presence (PR1 merged: #110269; commentary/summon are PR2)

existing users keep saved pins and reach it via customize/More), "Ask OpenClaw" as the first Settings entry, and normal-chrome /custodian visits that request the caretaker greeting (no onboarding welcome variant), with Exit setup rendered only in onboarding mode. A docked inline Settings pane needs shared conversation-view extraction (follow-up).

주요 항목:

Shipped in PR1: default-pinned "OpenClaw" sidebar entry (fresh profiles;
Event-reactive commentary with anti-Clippy guardrails: consequential or
Channels: day-to-day invisible (the agent relays); reachable by explicit
Weak model detected at setup: auto-set localModelLean, and the custodian
The custodian knows its internal nickname ("some folks call me the

Phase 7 — resilience (needs an owner decision before building)

The original sketch — "the custodian must be reachable no matter how broken the config is" — collides with the repo's security policy: the root guide states the Gateway refuses startup when config is structurally invalid, and only SecretRef-owner failures degrade into configured-unavailable capabilities. Serving any surface from an invalid config is a policy change, not an implementation detail. Two scopes, pick one:

주요 항목:

Option A (recommended, policy-compliant): CLI-side auto-doctor. When a
**Option B (needs explicit owner sign-off + security review): gateway

Testing and landing playbook (hard-won; read before phases 4-6)

LaunchAgent label (ai.openclaw.gateway) is machine-global: a fresh-install onboarding test with an isolated state dir will REWRITE and RESTART the real machine's service (wrapper scripts land inside the isolated dir; the next service start breaks when that dir is cleaned). After any fresh-install test, restore with openclaw gateway install --force && openclaw gateway restart from the real environment and verify the plist. Product follow-up: state-dir-scoped service labels, or onboarding detecting a foreign service.

주요 항목:

OPENCLAW_STATE_DIR does not isolate the Gateway service. The
Safe end-to-end harness: pre-seed the isolated config with a gateway
Auth paths differ by client identity, not only credentials. Presence and
Completion probes: runSetupInferenceTest caps the verification probe at
Agent landing needs exact-head hosted CI. The heavy CI workflow may
Gates that CI enforces beyond focused tests: docs map

gh workflow run ci.yml --ref <branch> -f target_ref=<head-sha> -f release_gate=true -f pull_request_number=<pr>

Decision log

discloses model and ClawHub use before scanning, and the results note repeats it).

주요 항목:

Magical scan with kill switch, not consent-first (phase 1; persistent output
Full vertical including the node device.apps command (phase 1).
Third-party ClawHub skills are never pre-selected and are labeled as
Two access cards, not three; consent front-loaded into the choice (phase 2).
Auto-hatch with announcement, not a blocking button (phases 2/5).
Browser-first: the terminal hatch is the fallback, never a "terminal or
Custodian gets channel presence (summon + recovery), not web/CLI only
Hatch happens in the same thread with an avatar swap; after completion the
The settings surface keeps the name "Settings"; the custodian lives there
Option cards are constrained: 2-4 options, exactly one recommended, always
"Asking OpenClaw…" is the canonical delegation idiom; souls may add flavor,
User-facing copy never says "code mode", "tools", or "context window" when

Known gaps and follow-ups

주요 항목:

LaunchAgent label is not state-dir-scoped (testing pitfall above; also a
Recommendations once-semantics and the stored scan (phase 5); reruns
Browser handoff is macOS-only; Linux/Windows enablement pending.
Session-count quip is qualitative; counts need a cheap session-count seam.
Browser handoff lands on the normal dashboard; onboarding-mode custodian

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/start/onboarding-redesign
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

gh workflow run ci.yml --ref <branch> -f target_ref=<head-sha> -f release_gate=true -f pull_request_number=<pr>

Onboarding redesign

핵심 요약

Implementation plan for the custodian onboarding redesign (living document)

한국어 가이드 범위: start/onboarding-redesign 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Onboarding redesign implementation plan
North star
Current shipped flow (after phases 1-3)
Phases
Implementation notes per phase
Phase 1 — app recommendations (PR #109668)
Phase 2 — CLI custodian spine (PR #109841)
Phase 3 — browser-first handoff (PR #110054, merged)
Phase 4 — web custodian surface (merged: #110141, #110242)
Phase 5 — hatch and bootstrap (merged: #110173, #110331)
Phase 6 — custodian presence (PR1 merged: #110269; commentary/summon are PR2)
Phase 7 — resilience (needs an owner decision before building)
Testing and landing playbook (hard-won; read before phases 4-6)
Decision log
Known gaps and follow-ups

상세 내용

Onboarding redesign implementation plan

North star

주요 항목:

Announced defaults with easy undo replace blocking questions. The only
Question zero is the consent boundary: "Full access" (recommended) means
Conversation as UI with progressive intelligence: the custodian surface
The hatch is a ceremony: same thread, avatar swap, the agent names itself
Trust is tiered by source: official catalog entries may be pre-selected;
Configured installs are sacred: re-running onboarding is a verification
The terminal is the fallback, not a question: prefer the browser
Weak models get a trimmed surface (auto localModelLean), explained in

Current shipped flow (after phases 1-3)

openclaw onboard on a fresh macOS install, happy path — four Enters total:

Phases

#	Phase	Surface	Status
1	Installed-app plugin recommendations (scan, candidates, AI matcher, wizard step, `device.apps` node command)	classic + guided CLI	merged (#109668)
2	CLI custodian spine (question zero, discovery theater, auto-apply + hatch)	guided CLI	merged (`a83ed13204f1`)
3	Browser-first handoff (GUI-session detection, wait-for-dashboard-connect, TUI as fallback)	CLI → web	merged (#110054)
4	Web custodian surface (option cards, typed `question` field on `openclaw.chat`, wizard-step mirroring, first-run handoff)	Control UI	merged (#110141, #110242)
5	Hatch and bootstrap (recommendations store with once-semantics, self-naming birth sequence, auto-hatch handoff after fresh setup; avatar ladder deferred)	agent bootstrap	merged (#110173, #110331)
6	Custodian presence PR1 (pinned sidebar entry, Ask OpenClaw in Settings, normal-chrome caretaker greeting; event commentary and channel summon are PR2)	web + channels	merged (#110269)
7	Resilience (custodian reachable on broken config, partial-surface salvage, auto-doctor)	gateway	follow-up

Implementation notes per phase

이 섹션의 세부 항목은 공식 문서 Implementation notes per phase를 참고하세요.

Phase 1 — app recommendations (PR #109668)

주요 항목:

Scanner: src/infra/installed-apps.ts (TCC-free macOS enumeration; follows
Candidates: official catalogs + ClawHub search, 20s overall budget, graceful
AI matcher: one completion on the verified route
Supply-chain guard: ClawHub listing text is publisher-controlled and
Node command device.apps (TS node-host, Android envelope parity), sharing
Delivery lives in the classic wizard and guided custodian flow
Also fixed: custom completeSetupInference prompts no longer inherit the

Phase 2 — CLI custodian spine (PR #109841)

keeps its legacy chat handoff via handoffMode: "chat".

주요 항목:

Flow rework in src/commands/onboard-guided.ts; remote-gateway onboarding
Question zero persists wizard.accessMode ("full" | "guarded"); reruns
Discovery: quiet failure collection (single summary line; details behind
Fresh installs: applySystemAgentSetup (the deterministic conversational

Phase 3 — browser-first handoff (PR #110054, merged)

주요 항목:

src/commands/onboard-browser-handoff.ts owns pure graphical-session
Dashboard links use the same resolveAdvertisedControlUiLinks,
Readiness polls the existing system-presence RPC as a **CLI-mode loopback
gateway.controlUi.enabled: false short-circuits before any URL is shown.
Proven end-to-end against an isolated same-config gateway: URL print → real

Phase 4 — web custodian surface (merged: #110141, #110242)

(2-4 cards, one recommended max, always skippable); onboarding chrome via ?onboarding=1; model-setup first-run completion hands off into it.

주요 항목:

/custodian page over openclaw.chat with the option-card component
Structured questions are a typed additive question field on
Session ownership is scoped to gateway URL + every presented credential

Phase 5 — hatch and bootstrap (merged: #110173, #110331)

주요 항목:

Custodian creates a nameless agent (tool call); the agent's bootstrap opens
Recommendations (phase 1 service, stored scan with once-semantics) land as
Self-learning is asked, not announced, and doubles as skill-workshop
Auto-hatch shipped: a fresh-install setup apply announces the hatch and

Phase 6 — custodian presence (PR1 merged: #110269; commentary/summon are PR2)

주요 항목:

Shipped in PR1: default-pinned "OpenClaw" sidebar entry (fresh profiles;
Event-reactive commentary with anti-Clippy guardrails: consequential or
Channels: day-to-day invisible (the agent relays); reachable by explicit
Weak model detected at setup: auto-set localModelLean, and the custodian
The custodian knows its internal nickname ("some folks call me the

Phase 7 — resilience (needs an owner decision before building)

주요 항목:

Option A (recommended, policy-compliant): CLI-side auto-doctor. When a
**Option B (needs explicit owner sign-off + security review): gateway

Testing and landing playbook (hard-won; read before phases 4-6)

주요 항목:

OPENCLAW_STATE_DIR does not isolate the Gateway service. The
Safe end-to-end harness: pre-seed the isolated config with a gateway
Auth paths differ by client identity, not only credentials. Presence and
Completion probes: runSetupInferenceTest caps the verification probe at
Agent landing needs exact-head hosted CI. The heavy CI workflow may
Gates that CI enforces beyond focused tests: docs map

gh workflow run ci.yml --ref <branch> -f target_ref=<head-sha> -f release_gate=true -f pull_request_number=<pr>

Decision log

discloses model and ClawHub use before scanning, and the results note repeats it).

주요 항목:

Magical scan with kill switch, not consent-first (phase 1; persistent output
Full vertical including the node device.apps command (phase 1).
Third-party ClawHub skills are never pre-selected and are labeled as
Two access cards, not three; consent front-loaded into the choice (phase 2).
Auto-hatch with announcement, not a blocking button (phases 2/5).
Browser-first: the terminal hatch is the fallback, never a "terminal or
Custodian gets channel presence (summon + recovery), not web/CLI only
Hatch happens in the same thread with an avatar swap; after completion the
The settings surface keeps the name "Settings"; the custodian lives there
Option cards are constrained: 2-4 options, exactly one recommended, always
"Asking OpenClaw…" is the canonical delegation idiom; souls may add flavor,
User-facing copy never says "code mode", "tools", or "context window" when

Known gaps and follow-ups

주요 항목:

LaunchAgent label is not state-dir-scoped (testing pitfall above; also a
Recommendations once-semantics and the stored scan (phase 5); reruns
Browser handoff is macOS-only; Linux/Windows enablement pending.
Session-count quip is qualitative; counts need a cheap session-count seam.
Browser handoff lands on the normal dashboard; onboarding-mode custodian

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/start/onboarding-redesign
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

gh workflow run ci.yml --ref <branch> -f target_ref=<head-sha> -f release_gate=true -f pull_request_number=<pr>

Onboarding redesign

핵심 요약

문서 구성

상세 내용

Onboarding redesign implementation plan

North star

Current shipped flow (after phases 1-3)

Phases

Implementation notes per phase

Phase 1 — app recommendations (PR #109668)

Phase 2 — CLI custodian spine (PR #109841)

Phase 3 — browser-first handoff (PR #110054, merged)

Phase 4 — web custodian surface (merged: #110141, #110242)

Phase 5 — hatch and bootstrap (merged: #110173, #110331)

Phase 6 — custodian presence (PR1 merged: #110269; commentary/summon are PR2)

Phase 7 — resilience (needs an owner decision before building)

Testing and landing playbook (hard-won; read before phases 4-6)

Decision log

Known gaps and follow-ups

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Onboarding redesign

핵심 요약

문서 구성

상세 내용

Onboarding redesign implementation plan

North star

Current shipped flow (after phases 1-3)

Phases

Implementation notes per phase

Phase 1 — app recommendations (PR #109668)

Phase 2 — CLI custodian spine (PR #109841)

Phase 3 — browser-first handoff (PR #110054, merged)

Phase 4 — web custodian surface (merged: #110141, #110242)

Phase 5 — hatch and bootstrap (merged: #110173, #110331)

Phase 6 — custodian presence (PR1 merged: #110269; commentary/summon are PR2)

Phase 7 — resilience (needs an owner decision before building)

Testing and landing playbook (hard-won; read before phases 4-6)

Decision log

Known gaps and follow-ups

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드