523 lines
12 KiB
Markdown
523 lines
12 KiB
Markdown
# QwenClaw 🐾
|
|
|
|
**A persistent personal assistant daemon for Qwen Code that never sleeps.**
|
|
|
|
QwenClaw runs as a background daemon, executing scheduled tasks, responding to Telegram messages, and providing a web dashboard for monitoring and management. It automatically starts with your system and persists across all restarts.
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
| Feature | Description |
|
|
|---------|-------------|
|
|
| **💓 Heartbeat** | Periodic check-ins on configurable intervals with quiet hours support |
|
|
| **⏰ Cron Jobs** | Schedule any prompt using standard cron syntax (timezone-aware) |
|
|
| **📱 Telegram Bot** | Chat with your agent via text, images, and voice commands |
|
|
| **🌐 Web Dashboard** | Monitor runs, edit jobs, and view logs in real-time |
|
|
| **🔒 Security Levels** | Four granular levels from read-only to full system access |
|
|
| **🔄 Auto-Start** | Automatically starts when you log in (Windows/Linux/macOS) |
|
|
| **💾 Persistent State** | All settings, jobs, and sessions saved to disk |
|
|
|
|
---
|
|
|
|
## Quick Install
|
|
|
|
### One-Command Install
|
|
|
|
**Windows (PowerShell):**
|
|
```powershell
|
|
git clone https://github.rommark.dev/admin/QwenClaw-with-Auth.git
|
|
cd QwenClaw-with-Auth
|
|
.\install.ps1
|
|
```
|
|
|
|
**Linux/macOS (Bash):**
|
|
```bash
|
|
git clone https://github.rommark.dev/admin/QwenClaw-with-Auth.git
|
|
cd QwenClaw-with-Auth
|
|
chmod +x install.sh
|
|
./install.sh
|
|
```
|
|
|
|
This will:
|
|
1. Install dependencies (Bun if missing)
|
|
2. Create all necessary directories
|
|
3. Set up auto-start for your system
|
|
4. Create default configuration
|
|
5. Add example scheduled job
|
|
|
|
---
|
|
|
|
## Manual Installation
|
|
|
|
### Prerequisites
|
|
|
|
- [Qwen Code](https://github.com/QwenLM/Qwen-Code) installed and configured
|
|
- [Bun](https://bun.sh/) package manager
|
|
- Git
|
|
|
|
### Steps
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.rommark.dev/admin/QwenClaw-with-Auth.git
|
|
cd QwenClaw-with-Auth
|
|
|
|
# Install dependencies
|
|
bun install
|
|
|
|
# Start the daemon
|
|
bun run start --web
|
|
```
|
|
|
|
---
|
|
|
|
## Auto-Start Configuration
|
|
|
|
QwenClaw is configured to start automatically when you log in.
|
|
|
|
### Windows
|
|
- Uses Startup Folder (`shell:startup`)
|
|
- No admin privileges required
|
|
- To disable: Run `.\scripts\uninstall-startup.ps1`
|
|
|
|
### Linux
|
|
- **Systemd service** (if available, requires sudo)
|
|
- **Desktop autostart** (for GUI sessions)
|
|
- To disable: `systemctl disable qwenclaw.service` or remove `~/.config/autostart/qwenclaw.desktop`
|
|
|
|
### macOS
|
|
- Uses LaunchAgent
|
|
- To disable: `launchctl unload ~/Library/LaunchAgents/com.qwenclaw.daemon.plist`
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### Start the Daemon
|
|
|
|
```bash
|
|
# Start with web UI
|
|
bun run start --web
|
|
|
|
# Start with custom port
|
|
bun run start --web --web-port 8080
|
|
|
|
# Start with trigger prompt
|
|
bun run start --trigger --prompt "Check my pending tasks"
|
|
|
|
# One-shot prompt (no daemon)
|
|
bun run start --prompt "What's the weather?"
|
|
```
|
|
|
|
### Check Status
|
|
|
|
```bash
|
|
bun run status
|
|
```
|
|
|
|
### Stop the Daemon
|
|
|
|
```bash
|
|
bun run stop
|
|
```
|
|
|
|
### Send a Prompt
|
|
|
|
```bash
|
|
# Send to running daemon
|
|
bun run send "Check my calendar"
|
|
|
|
# Send and forward to Telegram
|
|
bun run send --telegram "Summarize my tasks"
|
|
```
|
|
|
|
### Clear State
|
|
|
|
```bash
|
|
bun run clear
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### Settings File
|
|
|
|
Location: `~/.qwen/qwenclaw/settings.json`
|
|
|
|
```json
|
|
{
|
|
"model": "qwen-plus",
|
|
"api": "",
|
|
"autoStart": true,
|
|
"fallback": {
|
|
"model": "",
|
|
"api": ""
|
|
},
|
|
"timezone": "UTC",
|
|
"timezoneOffsetMinutes": 0,
|
|
"heartbeat": {
|
|
"enabled": true,
|
|
"interval": 15,
|
|
"prompt": "",
|
|
"excludeWindows": [
|
|
{
|
|
"start": "22:00",
|
|
"end": "08:00",
|
|
"days": [0, 1, 2, 3, 4, 5, 6]
|
|
}
|
|
]
|
|
},
|
|
"telegram": {
|
|
"token": "",
|
|
"allowedUserIds": []
|
|
},
|
|
"security": {
|
|
"level": "moderate",
|
|
"allowedTools": [],
|
|
"disallowedTools": []
|
|
},
|
|
"web": {
|
|
"enabled": true,
|
|
"host": "127.0.0.1",
|
|
"port": 4632
|
|
}
|
|
}
|
|
```
|
|
|
|
### Security Levels
|
|
|
|
| Level | Description |
|
|
|-------|-------------|
|
|
| `locked` | Read-only access (Read, Grep, Glob tools only) |
|
|
| `strict` | No Bash, WebSearch, or WebFetch |
|
|
| `moderate` | All tools available, scoped to project directory |
|
|
| `unrestricted` | All tools, no directory restrictions |
|
|
|
|
---
|
|
|
|
## Scheduled Jobs
|
|
|
|
Create jobs in `~/.qwen/qwenclaw/jobs/` as markdown files with frontmatter.
|
|
|
|
### Example: Daily Standup
|
|
|
|
File: `~/.qwen/qwenclaw/jobs/daily-standup.md`
|
|
|
|
```markdown
|
|
---
|
|
schedule: 0 9 * * *
|
|
recurring: true
|
|
notify: true
|
|
---
|
|
|
|
Good morning! Here's your daily check-in:
|
|
1. What are today's priorities?
|
|
2. Any pending tasks from yesterday?
|
|
3. Summarize my calendar for today.
|
|
```
|
|
|
|
### Cron Syntax
|
|
|
|
```
|
|
┌───────────── minute (0 - 59)
|
|
│ ┌───────────── hour (0 - 23)
|
|
│ │ ┌───────────── day of month (1 - 31)
|
|
│ │ │ ┌───────────── month (1 - 12)
|
|
│ │ │ │ ┌───────────── day of week (0 - 6)
|
|
│ │ │ │ │
|
|
* * * * *
|
|
```
|
|
|
|
### Examples
|
|
|
|
| Expression | Description |
|
|
|------------|-------------|
|
|
| `*/5 * * * *` | Every 5 minutes |
|
|
| `0 */2 * * *` | Every 2 hours |
|
|
| `0 9 * * 1-5` | 9 AM on weekdays |
|
|
| `0 0 1 * *` | First day of every month |
|
|
| `0 0 * * 0` | Every Sunday at midnight |
|
|
|
|
---
|
|
|
|
## Telegram Integration
|
|
|
|
### Setup
|
|
|
|
1. Create a bot via [@BotFather](https://t.me/BotFather) on Telegram
|
|
2. Get your bot token
|
|
3. Find your Telegram user ID (use [@userinfobot](https://t.me/userinfobot))
|
|
4. Add to settings:
|
|
|
|
```json
|
|
{
|
|
"telegram": {
|
|
"token": "YOUR_BOT_TOKEN",
|
|
"allowedUserIds": [YOUR_USER_ID]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Bot Commands
|
|
|
|
- `/start` - Get started with the bot
|
|
- `/reset` - Reset the conversation session
|
|
|
|
### Features
|
|
|
|
- Text messages
|
|
- Image attachments (bot downloads and sends to Qwen)
|
|
- Voice messages (transcription requires whisper setup)
|
|
- Group chat support (mention bot or reply to its messages)
|
|
- Reactions support using `[react:emoji]` syntax in responses
|
|
|
|
---
|
|
|
|
## Web Dashboard
|
|
|
|
Access at: **http://127.0.0.1:4632** (or your configured port)
|
|
|
|
### Features
|
|
|
|
- Real-time daemon status
|
|
- Heartbeat configuration
|
|
- Job management (view, add, delete)
|
|
- Logs viewer
|
|
- Technical information
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
QwenClaw-with-Auth/
|
|
├── src/
|
|
│ ├── commands/ # CLI commands
|
|
│ │ ├── start.ts # Daemon start
|
|
│ │ ├── stop.ts # Daemon stop
|
|
│ │ ├── status.ts # Status check
|
|
│ │ ├── send.ts # Send prompt
|
|
│ │ ├── clear.ts # Clear state
|
|
│ │ └── telegram.ts # Telegram bot
|
|
│ ├── ui/ # Web dashboard
|
|
│ │ ├── page/ # HTML/CSS/JS
|
|
│ │ └── services/ # API handlers
|
|
│ ├── config.ts # Configuration management
|
|
│ ├── cron.ts # Cron parsing
|
|
│ ├── jobs.ts # Job scheduling
|
|
│ ├── runner.ts # Qwen execution
|
|
│ ├── sessions.ts # Session management
|
|
│ ├── timezone.ts # Timezone utilities
|
|
│ ├── pid.ts # PID file management
|
|
│ ├── statusline.ts # Status line widget
|
|
│ ├── preflight.ts # Plugin setup
|
|
│ └── index.ts # Main entry point
|
|
├── prompts/ # Prompt templates
|
|
│ ├── IDENTITY.md
|
|
│ ├── USER.md
|
|
│ ├── SOUL.md
|
|
│ └── heartbeat/
|
|
│ └── HEARTBEAT.md
|
|
├── scripts/ # Installation scripts
|
|
│ ├── install.sh # Linux/macOS install
|
|
│ ├── install.ps1 # Windows install
|
|
│ ├── autostart.ps1 # Auto-start script
|
|
│ ├── install-startup.ps1 # Install auto-start
|
|
│ └── uninstall-startup.ps1 # Remove auto-start
|
|
├── package.json
|
|
├── tsconfig.json
|
|
├── README.md
|
|
└── QUICKSTART.md
|
|
```
|
|
|
|
---
|
|
|
|
## Data Locations
|
|
|
|
| Data | Location |
|
|
|------|----------|
|
|
| Settings | `~/.qwen/qwenclaw/settings.json` |
|
|
| Jobs | `~/.qwen/qwenclaw/jobs/*.md` |
|
|
| Logs | `~/.qwen/qwenclaw/logs/*.log` |
|
|
| Session | `~/.qwen/qwenclaw/session.json` |
|
|
| State | `~/.qwen/qwenclaw/state.json` |
|
|
| PID File | `~/.qwen/qwenclaw/daemon.pid` |
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Daemon not starting on login
|
|
|
|
1. Check auto-start is configured:
|
|
- Windows: Check `shell:startup` folder for shortcut
|
|
- Linux: Check `systemctl status qwenclaw.service`
|
|
- macOS: Check `launchctl list | grep qwenclaw`
|
|
|
|
2. Check logs:
|
|
```bash
|
|
# Auto-start logs
|
|
cat ~/.qwen/qwenclaw/autostart.log
|
|
|
|
# Daemon logs
|
|
ls -la ~/.qwen/qwenclaw/logs/
|
|
```
|
|
|
|
3. Start manually:
|
|
```bash
|
|
bun run start --web
|
|
```
|
|
|
|
### Port already in use
|
|
|
|
Edit `~/.qwen/qwenclaw/settings.json`:
|
|
```json
|
|
{
|
|
"web": {
|
|
"port": 4633
|
|
}
|
|
}
|
|
```
|
|
|
|
### Telegram bot not responding
|
|
|
|
1. Verify token is correct in settings
|
|
2. Check your user ID is in `allowedUserIds`
|
|
3. Enable debug mode: add `--debug` flag when starting
|
|
|
|
### Jobs not running
|
|
|
|
1. Verify cron syntax (use [crontab.guru](https://crontab.guru))
|
|
2. Check timezone settings
|
|
3. Review job file format (frontmatter + prompt)
|
|
|
|
---
|
|
|
|
## Updating
|
|
|
|
```bash
|
|
# Navigate to repository
|
|
cd QwenClaw-with-Auth
|
|
|
|
# Pull latest changes
|
|
git pull
|
|
|
|
# Reinstall dependencies
|
|
bun install
|
|
|
|
# Restart daemon
|
|
bun run stop
|
|
bun run start --web
|
|
```
|
|
|
|
---
|
|
|
|
## Uninstall
|
|
|
|
### Remove Auto-Start
|
|
|
|
**Windows:**
|
|
```powershell
|
|
.\scripts\uninstall-startup.ps1
|
|
```
|
|
|
|
**Linux:**
|
|
```bash
|
|
sudo systemctl disable qwenclaw.service
|
|
sudo systemctl stop qwenclaw.service
|
|
rm ~/.config/autostart/qwenclaw.desktop
|
|
```
|
|
|
|
**macOS:**
|
|
```bash
|
|
launchctl unload ~/Library/LaunchAgents/com.qwenclaw.daemon.plist
|
|
rm ~/Library/LaunchAgents/com.qwenclaw.daemon.plist
|
|
```
|
|
|
|
### Remove Data
|
|
|
|
```bash
|
|
# Remove all QwenClaw data
|
|
rm -rf ~/.qwen/qwenclaw
|
|
|
|
# Remove repository
|
|
rm -rf QwenClaw-with-Auth
|
|
```
|
|
|
|
---
|
|
|
|
## Versioning & Changelog
|
|
|
|
QwenClaw follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PATCH).
|
|
|
|
### [1.1.0] - 2026-02-26
|
|
|
|
#### Added
|
|
- **Skills Integration**: Imported 25+ skills from [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills)
|
|
- Content Research Writer
|
|
- File Organizer
|
|
- Developer Growth Analysis
|
|
- Changelog Generator
|
|
- Document Skills
|
|
- Image Enhancer
|
|
- Video Downloader
|
|
- And 19 more...
|
|
- **Cross-platform support**: Full compatibility for Windows, Linux, and macOS
|
|
- **Skills index**: `skills/skills-index.json` for skill discovery
|
|
- **Installation scripts**: `install.sh` (Linux/macOS) and `install.ps1` (Windows)
|
|
|
|
#### Fixed
|
|
- Daemon startup issue on Windows (qwen.cmd path resolution)
|
|
- Settings file path (`.qwen/qwenclaw/settings.json`)
|
|
- Statusline command path (`.qwen/statusline.cjs`)
|
|
- Async/await handling in main entry point
|
|
- Shell execution for cross-platform command spawning
|
|
|
|
#### Changed
|
|
- Removed debug logging from production code
|
|
- Improved error handling and reporting
|
|
- Updated README with comprehensive documentation
|
|
- Added versioning and changelog section
|
|
|
|
### [1.0.0] - 2026-02-26
|
|
|
|
#### Added
|
|
- Initial release
|
|
- Daemon with auto-start capability
|
|
- Heartbeat system with quiet hours
|
|
- Cron job scheduling
|
|
- Telegram bot integration
|
|
- Web dashboard (http://127.0.0.1:4632)
|
|
- Four security levels (locked, strict, moderate, unrestricted)
|
|
- Session persistence
|
|
- Hot-reload configuration
|
|
- Windows Task Scheduler integration
|
|
- Linux systemd service support
|
|
- macOS LaunchAgent support
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT License - See [LICENSE](LICENSE) file for details.
|
|
|
|
---
|
|
|
|
## Acknowledgments
|
|
|
|
QwenClaw is inspired by [ClaudeClaw](https://github.com/moazbuilds/claudeclaw) by @moazbuilds.
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
For issues, questions, or contributions:
|
|
- Repository: https://github.rommark.dev/admin/QwenClaw-with-Auth
|
|
- Issues: https://github.rommark.dev/admin/QwenClaw-with-Auth/issues
|