Qwen Portal Auth Helper

Automate qwen-portal OAuth authentication - solves the interactive TTY problem with tmux, provides monitoring and recovery tools.

Security Scan

The skill's code, scripts, and runtime instructions are coherent with its stated purpose (automating qwen-portal OAuth via tmux, monitoring, and resetting task state); it requires reasonable local tooling and modifies only user-level OpenClaw state and crontab as expected.

Purpose & Capability

Name/description match the provided files and scripts: tmux and openclaw are required and used to capture the OAuth link; health-check and reset scripts operate on OpenClaw cron jobs. No unrelated binaries, secrets, or network endpoints are requested beyond the qwen authorization URL the user must visit.

Instruction Scope

SKILL.md and scripts instruct the agent/user to run local scripts that read/write ~/.openclaw paths, read crontab output, create temporary files in /tmp, spawn and kill tmux sessions, and invoke openclaw. This is within the stated purpose, but the scripts will read and modify the user's OpenClaw cron jobs file and can add a crontab entry — review and back up those files before use.

Install Mechanism

No remote install/download is present; the skill is instruction-plus-local-scripts (no package installer). That is low-risk compared to fetching arbitrary archives. The repository claims a GitHub source in metadata, but the published 'Source: unknown' is a minor provenance inconsistency to verify.

Credentials

The skill requests no environment secrets and only requires tmux/openclaw (and optionally python3). Declared permissions (exec/read/write) are consistent with scripts that manipulate files and crontab. There are no unexplained requests for unrelated credentials or external endpoints.

Persistence & Privilege

The skill does not set always:true and defaults to normal autonomous invocation. It can add a user crontab entry (setupMonitoring) and the reset script writes to ~/.openclaw/cron/jobs.json — both are reasonable for this utility but are persistent changes to the user's environment and should be accepted explicitly by the user.

Assessment

This skill appears to do what it says, but it runs commands that modify your user crontab and your OpenClaw cron jobs file. Before installing or running it: (1) verify the repository/source you install from, (2) inspect the scripts (get-qwen-oauth-link.sh, check-qwen-auth.sh, reset-task-state.py) yourself, (3) back up ~/.openclaw/cron/jobs.json and your crontab (crontab -l > crontab.backup), (4) test in --test-only mode or in a non-production account, and (5) be prepared that the tool will create/kill tmux sessions and create files under /tmp. No external credential exfiltration is evident, but only proceed if you trust the code's origin.

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