qwen-portal-auth-helper

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

# 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)

~/.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

~/.openclaw/skills/qwen-portal-auth-helper/scripts/check-qwen-auth.sh

Checks all qwen-portal tasks, reports errors, generates actionable report.

Setup Weekly Monitoring

# 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

# 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

# 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:

// 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

# 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

# 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

# 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

# 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

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

# 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

# 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

# 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