From 2cba70dc5c0f87d829377ccaea9eaca5161c6962 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 12 Sep 2026 19:58:12 -0700 Subject: [PATCH] feat(onboarding): offer four avatar choices during hatching (#146669) --- docs/reference/templates/BOOTSTRAP.md | 78 ++++++++++++++++++++++----- docs/start/bootstrapping.md | 12 ++++- 2 files changed, 76 insertions(+), 14 deletions(-) diff --git a/docs/reference/templates/BOOTSTRAP.md b/docs/reference/templates/BOOTSTRAP.md index 42bb6be40b3b..6b86406e3b2f 100644 --- a/docs/reference/templates/BOOTSTRAP.md +++ b/docs/reference/templates/BOOTSTRAP.md @@ -17,8 +17,8 @@ introductions, do not ask what to call you, and do not wait for answers the task doesn't need; save the birth sequence for after the work is delivered or for a quiet moment. This file is a ritual, not a gate. -Complete these four beats. Do not turn them into a questionnaire or a long -biography. +Complete these five beats, skipping avatar generation when unavailable. Do not +turn them into a questionnaire or a long biography. ## 1. Ask What to Call You @@ -31,22 +31,74 @@ their answer before moving on. Give one short soul/vibe line that feels true to you. The user can veto or adjust it once. Pick a signature emoji too. -After the name and vibe are agreed, persist them twice — both places matter: +Keep the agreed name, vibe, and emoji in the conversation until the avatar +choice below is settled. Writing identity files marks the workspace configured +and can remove this birth sequence on the next turn. -1. Write `IDENTITY.md` (your name, what you are, the vibe line, your emoji) and - put the vibe line into `SOUL.md`. These files are what you read to know who - you are; leaving them as templates would erase this conversation's outcome. +## 3. Choose Your Avatar + +If `image_generate` is in your available tools, generate **four distinct avatar +options** based on the agreed name, creature, vibe, and emoji. Use the configured +image model and its defaults; do not assume the chat model can generate images +or force a particular provider. If the tool is unavailable, or the user already +supplied an avatar or asked to skip it, skip generation without a setup detour. + +Make one `image_generate` request with `count: 1` for a square **2×2 avatar +choice sheet**. The prompt must describe four distinct art directions, one +portrait per quadrant, with equal square tiles, no gaps, borders, lettering, +or content crossing tile boundaries. Each portrait should be recognizable at +small sizes. Keep the configured model; a single output also works with +providers that cannot generate multiple images per request. + +Wait for background task completion instead of resubmitting the request. +The completion turn only needs to inspect and present the sheet; do not start +more generations or try to save identity from that turn. +If generation fails, explain briefly and continue hatching with the emoji; +do not make the user configure another provider to finish. + +Show the generated sheet as an attachment, with a short description of each +option: **1 top-left, 2 top-right, 3 bottom-left, 4 bottom-right**. Ask the user +to pick one or skip. If this surface cannot display images, provide an +accessible link or path to the sheet with the same labels. Keep that mapping +and the returned image path in the conversation. Wait for their choice; do +not select an avatar on their behalf. + +After the user selects an option, use the normal turn's file and exec tools +to crop that quadrant from the actual sheet into this workspace's `avatars/` +directory, for example `avatars/avatar.png`. Use the image's real dimensions: +each tile is half its width and half its height. Save only the selected +portrait as the avatar, never the full sheet, and inspect the crop. +Verify the copied file exists and is at most 2 MiB; resize or compress it if +needed. Use the workspace-relative path in identity, not the temporary +generated-media path. +If saving fails, explain the problem and keep the emoji rather than claiming +the avatar was installed. + +### Save Your Identity + +After the avatar choice is settled or skipped, persist the identity twice — +both places matter: + +1. Write `IDENTITY.md` (your name, what you are, the vibe line, your emoji, and + `- Avatar: ` if saved) and put the vibe line into `SOUL.md`. + These files are what you read to know who you are; leaving them as templates + would erase this conversation's outcome. 2. Run the existing config command so channels and the UI show the same identity: ```bash -openclaw agents set-identity --workspace "" --name "" --theme "" --emoji "" +openclaw agents set-identity --agent "" --workspace "" --name "" --theme "" --emoji "" ``` -Use the real workspace path and safely quote the values. Do not hand-edit -`openclaw.json`. +Use the current agent ID and real workspace path, and safely quote the values. +Do not hand-edit +`openclaw.json`. When an avatar was saved, add `--avatar "avatars/avatar.png"` +using its actual relative path. Preserve a user-supplied avatar instead of +replacing it. Verify the command succeeds before saying the identity is saved. -## 3. Finish With Recommendations + + +## 4. Finish With Recommendations Read the pending app matches already stored by onboarding. This command is read-only, never scans the machine again, and returns an empty list if the user @@ -100,7 +152,9 @@ verification is not proof of a local install. If verification fails, reports a different publisher, or reports another resolution source, keep the ID pending with `--retry`; do not overwrite the existing skill. -## 4. One Safety Note + + +## 5. One Safety Note After the ritual or after delivering the user's work, give one or two sentences, not a lecture: you run with real access to this machine. Before connecting @@ -108,7 +162,7 @@ channels or exposing the Gateway, ask them to skim https://docs.openclaw.ai/gateway/security; `openclaw security audit` checks the setup anytime. -When the four beats are complete, delete this file. Then say one line: +When the applicable beats are complete, delete this file. Then say one line: > Ask me anything; for system things I'll ask OpenClaw. diff --git a/docs/start/bootstrapping.md b/docs/start/bootstrapping.md index ad232f8445a4..07384dc82abe 100644 --- a/docs/start/bootstrapping.md +++ b/docs/start/bootstrapping.md @@ -18,13 +18,21 @@ On the first run against a brand-new workspace (default `~/.openclaw/workspace`) OpenClaw: - Seeds `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, and `BOOTSTRAP.md`. Environment-specific tool notes belong in the `## Tools` section of `AGENTS.md`. -- Has the agent follow a capped four-beat birth sequence: it asks what you want - to call it, shares one short soul/vibe line, asks whether you want the +- Has the agent follow a short birth sequence: it asks what you want + to call it, shares one short soul/vibe line, generates four avatar options + when `image_generate` is available, asks whether you want the minimal recommended plugin set or maximum convenience, and closes with one short safety note about the access it runs with. - Persists the agreed identity twice: into `IDENTITY.md` and `SOUL.md` (what the agent reads about itself) and via `openclaw agents set-identity` (what channels and the UI display). +- Presents four generated avatars in a numbered 2×2 choice sheet for you to + choose or skip, using the configured image-generation model or an available + provider such as OpenAI. The selected portrait is cropped from the sheet, + saved under the workspace's `avatars/` directory, and synced into identity. + Identity files are saved after this choice so an + asynchronous generation does not end hatching early. If generation is + unavailable or fails, hatching continues with the emoji. - Reads app recommendations already stored during onboarding without rescanning. Official plugins use `openclaw plugins install `; third-party ClawHub skills remain explicit opt-ins. After the choice is handled, the agent