Skill: jazzqi/qwen-portal-auth-helper (version 1.0.0)

--- name: qwen-portal-auth-helper description: Automate qwen-portal OAuth authentication - solves the interactive TTY problem with tmux, provides monitoring and recovery tools. metadata: { "openclaw": { "requires": { "bins": ["tmux", "openclaw"] }, "category": "authentication", "tags": ["qwen-portal", "oauth", "automation", "troubleshooting"], "version": "1.0.0", "author": "Bessent (based on 2026-03-09 practical experience)" }, } --- # Qwen Portal Auth Helper > **Battle-tested solution for qwen-portal OAuth automation** > Solves the "interactive TTY required" problem, prevents cron task failures, and provides full monitoring. ## 🚨 The Problem qwen-portal provides free models (2,000 requests/day) but **OAuth expires every 1-2 weeks**. When it expires: 1. Cron tasks fail with: `Qwen OAuth refresh token expired or invalid` 2. `openclaw models auth login --provider qwen-portal` fails: `requires an interactive TTY` 3. Manual intervention required, breaking automation 4. Tasks remain in error state even after authentication fix ## 💡 The Solution This skill provides a complete solution: - **Automated OAuth link extraction** using tmux (bypasses TTY requirement) - **Health monitoring** for qwen-portal tasks - **Self-healing scripts** to fix task states - **Documented best practices** from real-world experience ## 📦 Installation ```bash # Via ClawHub (recommended) clawhub install qwen-portal-auth-helper # Or manually cd ~/.openclaw/skills/ git clone <repository> ``` ## 🛠️ Quick Start ### Get OAuth Link (when authentication expired) ```bash ~/.openclaw/skills/qwen-portal-auth-helper/scripts/get-qwen-oauth-link.sh ``` Outputs: ``` 🔗 OAuth Link: https://chat.qwen.ai/authorize?user_code=M17WU0SC 📱 Device Code: M17WU0SC ``` ### Check Authentication Health ```bash ~/.openclaw/skills/qwen-portal-auth-helper/scripts/check-qwen-auth.sh ``` Checks all qwen-portal tasks, reports errors, generates actionable report. ### Setup Weekly Monitoring ```bash # Add to crontab (runs every Monday at 9 AM) 0 9 * * 1 ~/.openclaw/skills/qwen-portal-auth-helper/scripts/check-qwen-auth.sh ``` ## 🔧 Core Features ### 1. OAuth Link Automation ```bash # Traditional way (fails in automation): openclaw models auth login --provider qwen-portal # ❌ Error: requires interactive TTY # Our solution: ./scripts/get-qwen-oauth-link.sh # ✅ Works in cron, AI assistants, etc. ``` **How it works**: Uses tmux to create virtual terminal, captures output before command hangs. ### 2. Health Monitoring - Scans all cron tasks using qwen-portal models - Detects error states and consecutive failures - Generates detailed reports with actionable advice - Early warning before complete failure ### 3. Recovery Tools - Resets task error states after authentication fix - Provides step-by-step recovery checklist - Validates fixes actually work ### 4. Best Practices Documentation - Complete workflow from diagnosis to recovery - Common pitfalls and how to avoid them - Maintenance schedule recommendations ## 📋 Complete Workflow ### When tasks start failing: ``` 1. Run: check-qwen-auth.sh → Identifies failing tasks, shows error details 2. Run: get-qwen-oauth-link.sh → Provides OAuth link and device code 3. User: Click link, authenticate in browser → Authorization completes automatically 4. Test: openclaw cron run <task-id> → Verifies authentication works 5. Reset: Scripts help reset task state → Tasks return to normal operation ``` ### Weekly Maintenance: ``` Monday 9 AM: check-qwen-auth.sh runs automatically If issues detected: Email/notification sent Preventative action: Re-authenticate before expiry ``` ## 🎯 Use Cases ### 1. AI Assistants & Automation AI assistants can't provide interactive TTY. This skill enables them to: - Automatically detect qwen-portal auth issues - Get OAuth links for user approval - Complete the recovery process ### 2. Cron Task Reliability Ensure scheduled tasks don't fail due to expired OAuth: - Weekly health checks - Early detection of impending expiry - Automated recovery procedures ### 3. Team Collaboration Standardized approach for teams: - Everyone uses same proven method - Documentation prevents repeated mistakes - Shared monitoring and alerting ### 4. New User Onboarding New OpenClaw users inevitably hit this issue. This skill provides: - Immediate solution without trial-and-error - Complete documentation - Community-validated approach ## 🔍 Technical Details ### How OAuth Link Extraction Works ```bash # The core technique: tmux new-session -d -s qwen-oauth "openclaw models auth login --provider qwen-portal" sleep 5 tmux capture-pane -t qwen-oauth -p | grep -E "(http|https)://" ``` **Key discoveries from real-world testing**: - Link format is always: `https://chat.qwen.ai/authorize?user_code=XXXXXXX&client=qwen-code` - Device code: 7 uppercase alphanumeric characters (e.g., M17WU0SC) - Command hangs after showing link (`◑ Waiting for Qwen OAuth approval...`) - Must capture output actively, not wait for completion ### Task State Management Even after successful authentication, cron tasks may remain in error state: ```json // Before fix: "state": {"lastStatus": "error", "consecutiveErrors": 10} // After fix (manual reset needed): "state": {"lastStatus": "pending", "consecutiveErrors": 0} ``` This skill includes scripts to reset these states automatically. ## 📊 Monitoring & Alerting ### What We Monitor 1. **Task Status**: Error vs OK 2. **Consecutive Errors**: >3 triggers warning 3. **Last Success Time**: Tasks not running recently 4. **OAuth Expiry Estimate**: Based on 1-2 week pattern ### Alert Thresholds - **Warning**: 3+ consecutive errors - **Critical**: Task in error state + OAuth-related error message - **Recovery Needed**: Manual intervention required ### Reports Generated - Weekly health report - Error analysis with suggested fixes - Maintenance checklist - Historical trends ## 🚀 Advanced Usage ### Integration with Other Skills ```bash # Combine with system-maintenance skill ~/.openclaw/skills/system-maintenance/scripts/daily-maintenance.sh ~/.openclaw/skills/qwen-portal-auth-helper/scripts/check-qwen-auth.sh # Use with agent-team-orchestration # Assign OAuth recovery as a specialized team task ``` ### Custom Monitoring Schedule ```bash # Daily quick check (lightweight) 0 9 * * * ~/.openclaw/skills/qwen-portal-auth-helper/scripts/check-qwen-auth.sh --quick # Weekly comprehensive check 0 9 * * 1 ~/.openclaw/skills/qwen-portal-auth-helper/scripts/check-qwen-auth.sh --full # Alert on critical issues immediately */30 * * * * ~/.openclaw/skills/qwen-portal-auth-helper/scripts/check-qwen-auth.sh --alert-only ``` ### Extending for Other OAuth Providers The pattern works for other services with similar issues: 1. GitHub OAuth 2. Google OAuth 3. Other AI model providers with device-code flow ## 📝 Examples ### Example 1: Quick Recovery ```bash # 1. Check what's wrong ./check-qwen-auth.sh # 2. Get new OAuth link ./get-qwen-oauth-link.sh # Output: Link and code to give to user # 3. After user authenticates, verify openclaw cron run 71628635-03e3-414b-865b-e427af4e804f openclaw cron runs --id 71628635-03e3-414b-865b-e427af4e804f # 4. Reset task states if needed ./scripts/reset-task-state.py 71628635-03e3-414b-865b-e427af4e804f ``` ### Example 2: Proactive Maintenance ```bash # Add to crontab for Monday morning checks crontab -l | grep -q "check-qwen-auth" || echo "0 9 * * 1 ~/.openclaw/skills/qwen-portal-auth-helper/scripts/check-qwen-auth.sh >> ~/.openclaw/logs/qwen-check.log" | crontab - # Review weekly reports cat /tmp/qwen-auth-report-*.md | less ``` ### Example 3: Integration with AI Assistant ```markdown When user reports news tasks failing: 1. Run check-qwen-auth.sh to confirm qwen-portal issue 2. Run get-qwen-oauth-link.sh to get authentication link 3. Provide link and code to user 4. Guide user through browser authentication 5. Verify fix with test run 6. Reset task states if needed ``` ## ⚠️ Common Pitfalls & Solutions ### Pitfall 1: Command hangs indefinitely **Solution**: Use timeout and active output capture (implemented in scripts) ### Pitfall 2: ANSI escape codes break parsing **Solution**: Robust regex that handles colored output (included) ### Pitfall 3: Task state doesn't reset automatically **Solution**: Manual state reset scripts (provided) ### Pitfall 4: Multiple qwen-portal tasks failing **Solution**: Batch processing in monitoring script ### Pitfall 5: OAuth expires at inconvenient times **Solution**: Weekly monitoring catches it early ## 🔄 Maintenance Schedule ### Weekly (Essential) - Run health check script - Review error reports - Prepare for potential re-authentication ### Monthly (Recommended) - Review OAuth expiry patterns - Update scripts if qwen-portal changes - Clean up old log files ### Quarterly (Optional) - Test complete recovery workflow - Update documentation - Check for new best practices ## 🤝 Community & Support ### Based on Real Experience This skill was developed from solving actual production issues on 2026-03-09: - Two critical news collection tasks failing - 9-10 consecutive errors before detection - Multiple failed attempts before finding tmux solution - Documented in `.learnings/` system ### Contributing Found a better way? Have another OAuth provider with similar issues? 1. Fork the repository 2. Add your improvements 3. Submit pull request 4. Help others avoid the same pitfalls ### Getting Help - Check `examples/` directory for common scenarios - Review `docs/troubleshooting.md` for known issues - Open issue on repository for new problems ## 📈 Benefits ### For Individual Users - No more manual OAuth link hunting - Prevent task failures before they happen - Standardized recovery process - Less time spent on maintenance ### For Teams - Shared knowledge and tools - Consistent monitoring approach - Reduced support requests - Faster onboarding for new members ### For Community - Open source solution to common problem - Continuously improved by users - Foundation for other OAuth automation - Knowledge sharing prevents repeated mistakes ## 🎉 Getting Started ### Installation ```bash # Install from ClawHub clawhub install qwen-portal-auth-helper # Or clone directly cd ~/.openclaw/skills git clone https://github.com/your-username/qwen-portal-auth-helper.git ``` ### First-Time Setup ```bash # 1. Test the scripts cd ~/.openclaw/skills/qwen-portal-auth-helper ./scripts/get-qwen-oauth-link.sh --test-only ./scripts/check-qwen-auth.sh # 2. Set up monitoring echo "0 9 * * 1 $(pwd)/scripts/check-qwen-auth.sh" | crontab - # 3. Document your qwen-portal tasks # Update examples/your-tasks.md with your task IDs ``` ### Verify It Works ```bash # Simulate a failure scenario openclaw cron run <your-qwen-portal-task-id> # Check monitoring catches it ./scripts/check-qwen-auth.sh # Practice recovery workflow ./scripts/get-qwen-oauth-link.sh --dry-run ``` --- **Remember**: qwen-portal OAuth expires every 1-2 weeks. **Solution**: Weekly monitoring + this skill = no more surprises. *Skill version: 1.0.0 | Based on 2026-03-09 battle-tested experience*


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)