Initial commit: QwenClaw persistent daemon for Qwen Code
This commit is contained in:
admin
471
README.md
Normal file
471
README.md
Normal file
@@ -0,0 +1,471 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user