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
This commit is contained in:
Lauren ten Hoor
2026-02-12 12:31:50 +08:00
parent 3b508ca293
commit 93d616b0dc

View File

@@ -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.