# QwenClaw Integration Skill

## Overview

This skill enables **Qwen Code** to directly trigger, control, and communicate with the **QwenClaw daemon**. It provides seamless integration between your interactive Qwen Code session and the persistent QwenClaw background processes.

**Version:** 1.0.0  
**Category:** Integration  
**Author:** QwenClaw Team

---

## Features

### 1. **Daemon Control**
- Start QwenClaw daemon from within Qwen Code
- Check daemon status
- Stop daemon gracefully
- Auto-restart if daemon crashes

### 2. **Message Passing**
- Send prompts to running daemon
- Receive responses asynchronously
- Forward responses to Telegram
- Queue messages when daemon is offline

### 3. **Task Orchestration**
- Delegate long-running tasks to daemon
- Monitor task progress
- Receive completion notifications
- Handle task failures gracefully

### 4. **Shared Context**
- Share session context between Qwen Code and QwenClaw
- Synchronize settings and preferences
- Share skill configurations
- Unified logging and debugging

---

## Installation

### Prerequisites

1. **QwenClaw installed:**
   ```bash
   git clone https://github.rommark.dev/admin/QwenClaw-with-Auth.git
   cd QwenClaw-with-Auth
   bun install
   ```

2. **Qwen Code installed:**
   ```bash
   # Follow Qwen Code installation guide
   ```

### Setup

1. **Copy skill to Qwen Code:**
   ```bash
   # Copy this skill to Qwen Code skills directory
   cp -r skills/qwenclaw-integration ~/.qwen/skills/qwenclaw-integration
   ```

2. **Enable in Qwen Code:**
   Edit `~/.qwen/settings.json`:
   ```json
   {
     "enabledSkills": [
       "qwenclaw-integration"
     ]
   }
   ```

3. **Configure paths:**
   Create `~/.qwen/skills/qwenclaw-integration/config.json`:
   ```json
   {
     "qwenclawPath": "/path/to/qwenclaw",
     "autoStart": true,
     "checkInterval": 30000,
     "forwardToTelegram": false
   }
   ```

---

## Usage

### From Qwen Code Chat

#### Start QwenClaw

```
Use qwenclaw-integration to start the daemon with web UI
```

#### Check Status

```
Use qwenclaw-integration to check if QwenClaw is running
```

#### Send Task

```
Use qwenclaw-integration to send this task to QwenClaw:
"Monitor my GitHub notifications and summarize new issues"
```

#### Schedule Task

```
Use qwenclaw-integration to schedule a daily standup at 9 AM
```

#### Forward to Telegram

```
Use qwenclaw-integration to forward the response to Telegram
```

---

## API Reference

### QwenClawClient Class

```typescript
import { QwenClawClient } from './qwenclaw-integration';

const client = new QwenClawClient({
  qwenclawPath: '/path/to/qwenclaw',
  autoStart: true,
});

// Check if daemon is running
const status = await client.getStatus();
console.log(status); // { running: true, pid: 12345, ... }

// Start daemon
await client.start({ web: true, webPort: 4632 });

// Send message
const response = await client.send('Check my pending tasks');
console.log(response); // { success: true, output: '...' }

// Stop daemon
await client.stop();
```

### Methods

#### `getStatus(): Promise<DaemonStatus>`

Check if QwenClaw daemon is running.

**Returns:**
```typescript
interface DaemonStatus {
  running: boolean;
  pid?: number;
  uptime?: number;
  webEnabled?: boolean;
  webPort?: number;
  telegramEnabled?: boolean;
  jobsCount?: number;
}
```

#### `start(options?: StartOptions): Promise<void>`

Start QwenClaw daemon.

**Options:**
```typescript
interface StartOptions {
  web?: boolean;
  webPort?: number;
  telegram?: boolean;
  debug?: boolean;
  trigger?: boolean;
  prompt?: string;
}
```

#### `stop(): Promise<void>`

Stop QwenClaw daemon gracefully.

#### `send(message: string, options?: SendOptions): Promise<SendResult>`

Send message to running daemon.

**Options:**
```typescript
interface SendOptions {
  telegram?: boolean;
  waitForResponse?: boolean;
  timeout?: number;
}
```

**Returns:**
```typescript
interface SendResult {
  success: boolean;
  output?: string;
  error?: string;
  exitCode?: number;
}
```

#### `schedule(job: ScheduledJob): Promise<void>`

Schedule a new job with QwenClaw.

**Job:**
```typescript
interface ScheduledJob {
  name: string;
  schedule: string; // Cron expression
  prompt: string;
  recurring: boolean;
  notify: boolean | 'error';
}
```

#### `listJobs(): Promise<ScheduledJob[]>`

List all scheduled jobs.

#### `cancelJob(name: string): Promise<void>`

Cancel a scheduled job.

---

## Examples

### Example 1: Auto-Start Daemon

```typescript
import { QwenClawClient } from './qwenclaw-integration';

const client = new QwenClawClient({ autoStart: true });

// This will automatically start QwenClaw if not running
const status = await client.getStatus();
console.log(`QwenClaw is ${status.running ? 'running' : 'stopped'}`);
```

### Example 2: Delegate Long Task

```typescript
const client = new QwenClawClient();

// Delegate code review to daemon
const result = await client.send(
  'Review all TypeScript files in src/ for potential bugs and suggest improvements',
  { waitForResponse: true, timeout: 300000 }
);

console.log(result.output);
```

### Example 3: Schedule Daily Report

```typescript
await client.schedule({
  name: 'daily-report',
  schedule: '0 9 * * 1-5', // Weekdays at 9 AM
  prompt: 'Generate a daily report of my GitHub activity, pending PRs, and tasks',
  recurring: true,
  notify: true,
});
```

### Example 4: Forward to Telegram

```typescript
const result = await client.send(
  'Summarize my calendar for today',
  { telegram: true }
);

// Response will be sent to your Telegram
```

---

## Integration Patterns

### Pattern 1: Interactive + Background

```
┌─────────────────┐         ┌─────────────────┐
│   Qwen Code     │────────▶│   QwenClaw      │
│   (Interactive) │◀────────│   (Background)  │
└─────────────────┘         └─────────────────┘
       │                           │
       ▼                           ▼
  User Chat                   Long Tasks
  Quick Questions              Scheduled Jobs
  Code Review                  Monitoring
```

**Use Case:** Use Qwen Code for interactive work, delegate long-running tasks to QwenClaw.

### Pattern 2: Multi-Session Coordination

```
┌─────────────────┐
│   Qwen Code     │
│   Session 1     │────┐
└─────────────────┘    │
                       ▼
┌─────────────────┐  ┌─────────────────┐
│   Qwen Code     │──▶│   QwenClaw      │
│   Session 2     │  │   (Shared)      │
└─────────────────┘  └─────────────────┘
                            │
                            ▼
                     ┌─────────────────┐
                     │    Telegram     │
                     │  Notifications  │
                     └─────────────────┘
```

**Use Case:** Multiple Qwen Code sessions share a single QwenClaw daemon for consistency.

### Pattern 3: Task Pipeline

```
User Request
     │
     ▼
┌─────────────────┐
│   Qwen Code     │──▶ Analyze & Plan
└─────────────────┘
     │
     ▼
┌─────────────────┐
│   QwenClaw      │──▶ Execute Long Task
└─────────────────┘
     │
     ▼
┌─────────────────┐
│    Telegram     │◀── Notify Completion
└─────────────────┘
```

**Use Case:** Complex workflows spanning multiple systems.

---

## Configuration

### config.json

```json
{
  "qwenclawPath": "/absolute/path/to/qwenclaw",
  "autoStart": true,
  "checkInterval": 30000,
  "forwardToTelegram": false,
  "telegramBotToken": "",
  "telegramAllowedUserIds": [],
  "webDashboard": {
    "enabled": true,
    "port": 4632,
    "host": "127.0.0.1"
  },
  "logging": {
    "level": "info",
    "file": "~/.qwen/qwenclaw/integration.log"
  }
}
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `QWENCLAW_PATH` | Path to QwenClaw installation | `~/qwenclaw` |
| `QWENCLAW_AUTO_START` | Auto-start daemon | `true` |
| `QWENCLAW_CHECK_INTERVAL` | Status check interval (ms) | `30000` |
| `QWENCLAW_TELEGRAM_TOKEN` | Telegram bot token | - |
| `QWENCLAW_LOG_LEVEL` | Logging level | `info` |

---

## Troubleshooting

### Issue: "Daemon not found"

**Solution:**
```bash
# Verify QwenClaw installation
cd /path/to/qwenclaw
bun run status

# Reinstall if needed
bun install
```

### Issue: "Cannot start daemon"

**Solution:**
```bash
# Check if port is in use
lsof -i :4632

# Check logs
cat ~/.qwen/qwenclaw/logs/*.log
```

### Issue: "Messages not delivered"

**Solution:**
1. Check daemon is running: `qwenclaw status`
2. Verify network connectivity
3. Check firewall settings
4. Review integration logs

---

## Best Practices

### 1. **Use for Appropriate Tasks**

✅ **Good for QwenClaw:**
- Long-running analyses
- Scheduled monitoring
- Background notifications
- Multi-step workflows

❌ **Better for Qwen Code:**
- Quick questions
- Interactive coding
- Real-time collaboration
- Exploratory work

### 2. **Manage Resources**

```typescript
// Don't spawn too many daemon tasks
const client = new QwenClawClient();

// Queue tasks instead of parallel execution
await client.send('Task 1');
await client.send('Task 2'); // Waits for Task 1
```

### 3. **Handle Errors Gracefully**

```typescript
try {
  const result = await client.send('Complex task');
  if (!result.success) {
    console.error('Task failed:', result.error);
  }
} catch (err) {
  console.error('Communication error:', err);
  // Fallback to direct Qwen Code execution
}
```

### 4. **Monitor Daemon Health**

```typescript
setInterval(async () => {
  const status = await client.getStatus();
  if (!status.running) {
    console.log('Daemon stopped, restarting...');
    await client.start();
  }
}, 60000); // Check every minute
```

---

## Security Considerations

### 1. **API Key Protection**

Never commit API keys to version control:

```bash
# Use environment variables
export QWEN_API_KEY="your-key"
export TELEGRAM_BOT_TOKEN="your-token"
```

### 2. **Access Control**

Limit Telegram access to trusted users:

```json
{
  "telegramAllowedUserIds": [123456789, 987654321]
}
```

### 3. **Network Security**

Bind web dashboard to localhost:

```json
{
  "webDashboard": {
    "host": "127.0.0.1",
    "port": 4632
  }
}
```

---

## Resources

- **QwenClaw Repo:** https://github.rommark.dev/admin/QwenClaw-with-Auth
- **Documentation:** `docs/README.md` in QwenClaw repo
- **Skills:** `skills/` directory
- **Issues:** https://github.rommark.dev/admin/QwenClaw-with-Auth/issues

---

## Changelog

### v1.0.0 (2026-02-26)
- Initial release
- Daemon control (start/stop/status)
- Message passing
- Task scheduling
- Telegram forwarding
- Shared context

---

## License

MIT License - See LICENSE file for details.

---

**Skill ready for Qwen Code integration!** 🐾🤖