From 93d616b0dc6e9be1e2058d7fd10496787d3d1c11 Mon Sep 17 00:00:00 2001
From: Lauren ten Hoor <laurentenhoor@gmail.com>
Date: Thu, 12 Feb 2026 12:31:50 +0800
Subject: [PATCH] feat: improve onboarding with model access check and Telegram
 group guidance

Enhanced the DevClaw onboarding flow to address real-world usability issues
discovered during testing.

Changes:

1. Model Selection Improvements (Step 2):
   - Added explicit prompt to check user's available models first
   - Changed 'Default Model' table to 'Suggested default' to emphasize flexibility
   - Added model selection guidance with class descriptions:
     * junior/tester: Fast, cheap (Haiku-class, GPT-4-mini)
     * medior/reviewer: Balanced (Sonnet-class, GPT-4)
     * senior: Most capable (Opus-class, o1)
   - Emphasized guiding users to configure finer-grained mappings
   - Added warning that defaults are suggestions, not requirements

2. Telegram Group Setup Guidance (New Step 4):
   - Added comprehensive section on project isolation best practices
   - Explains the one-group-per-project model clearly
   - Provides rationale:
     * Clean issue backlogs per project
     * Isolated worker state
     * Clear audit trails
     * Team-specific access control
   - Documents mention requirement (@botname command)
   - Includes single-project mode option with strong warning
   - Provides tip for getting group ID from bot

3. Improved Flow:
   - Renumbered steps (Project Registration is now Step 5)
   - Added group ID discovery tip
   - Maintained conversational tone while being more explicit

Impact:
- Prevents configuration failures from using unavailable models
- Guides users toward sustainable multi-project setup
- Reduces support burden by proactively explaining best practices
- Still allows single-project mode for solo developers

Addresses issue #132
---
 lib/onboarding.ts | 54 +++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 50 insertions(+), 4 deletions(-)

diff --git a/lib/onboarding.ts b/lib/onboarding.ts
index 59f21b9..1069c6a 100644
--- a/lib/onboarding.ts
+++ b/lib/onboarding.ts
@@ -111,13 +111,26 @@ Ask: "Do you want to configure DevClaw for the current agent, or create a new de
      - If none selected, user can add bindings manually later via openclaw.json
 
 **Step 2: Model Configuration**
-Show the default level-to-model mapping and ask if they want to customize:
+⚠️ **IMPORTANT**: First check what models the user has access to! The defaults below are suggestions.
+
+Ask: "What models do you have access to in your OpenClaw configuration?"
+- Guide them to check their available models (router configuration, API keys, etc.)
+- If they have the default Claude models, great!
+- If not, help them map their available models to these levels:
+
+**Suggested default level-to-model mapping:**
 
 | Role | Level | Default Model | Purpose |
 |------|-------|---------------|---------|
 ${modelTable}
 
-If the defaults are fine, proceed. If customizing, ask which levels to change.
+**Model selection guidance:**
+- **junior/tester**: Fastest, cheapest models (Haiku-class, GPT-4-mini, etc.)
+- **medior/reviewer**: Balanced models (Sonnet-class, GPT-4, etc.)
+- **senior**: Most capable models (Opus-class, o1, etc.)
+
+Ask which levels they want to customize, and collect their actual model IDs.
+💡 **Tip**: Guide users to configure finer-grained mappings rather than accepting unsuitable defaults.
 
 **Step 3: Run Setup**
 Call \`setup\` with the collected answers:
@@ -125,11 +138,44 @@ Call \`setup\` with the collected answers:
 - New agent: \`setup({ newAgentName: "<name>", channelBinding: "telegram"|"whatsapp"|null, migrateFrom: "<agentId>"|null, models: { ... } })\`
   - \`migrateFrom\`: Include if user wants to migrate an existing channel-wide binding
 
-**Step 4: Optional Project Registration**
-After setup, ask: "Would you like to register a project now?"
+**Step 4: Telegram Group Setup (IMPORTANT)**
+After setup completes, explain project isolation best practices:
+
+📱 **Telegram Group Guidance:**
+DevClaw uses **one Telegram group per project** for isolation and clean backlogs.
+
+**Recommended Setup:**
+1. **Create a new Telegram group** for each project
+2. **Add your bot** to the group
+3. **Use mentions** to interact: "@botname status", "@botname pick up #42"
+4. Each group gets its own queue, workers, and audit log
+
+**Why separate groups?**
+- Clean issue backlogs per project
+- Isolated worker state (no cross-project confusion)
+- Clear audit trails
+- Team-specific access control
+
+**Single-project mode:**
+If you REALLY want all projects in one group (not recommended):
+- You can register multiple projects to the same group ID
+- ⚠️ WARNING: Shared queues, workers will see all issues
+- Only use this for personal/solo projects
+
+Ask: "Do you understand the group-per-project model, or do you want single-project mode?"
+- Most users should proceed with the recommended approach
+- Only force single-project if they insist
+
+**Step 5: Project Registration**
+Ask: "Would you like to register a project now?"
 If yes, collect: project name, repo path, Telegram group ID, group name, base branch.
 Then call \`project_register\`.
 
+💡 **Tip**: For the Telegram group ID:
+- Add the bot to your group
+- Send any message with the bot mentioned
+- Bot can tell you the group ID
+
 ## Guidelines
 - Be conversational and friendly. Ask one question at a time.
 - Show defaults so the user can accept them quickly.