Skip to main content
Agent skill

Qwenpaw Usage

QwenPaw 命令行使用技巧:涵盖心跳(Heartbeat)配置、定时任务管理、Docker 打包部署、工作区导出迁移等操作。当用户要求添加心跳任务、配置定时自检、打包 QwenPaw 实例、部署到其他服务器、生成 Dockerfile 或 docker-compose 文件时使用本 skill。

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Qwenpaw Usage when an AI agent needs a reusable SKILL.md workflow for this job: QwenPaw 命令行使用技巧:涵盖心跳(Heartbeat)配置、定时任务管理、Docker 打包部署、工作区导出迁移等操作。当用户要求添加心跳任务、配置定时自检、打包 QwenPaw 实例、部署到其他服务器、生成 Dockerfile 或 docker-compose 文件时使用本 skill。

When not to use it

Skip Qwenpaw Usage when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/qwenpaw-usage
# Save SKILL.md to ~/.claude/skills/qwenpaw-usage/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/qwenpaw-usage/SKILL.md. For a shared project, commit the folder at .claude/skills/qwenpaw-usage/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Qwenpaw Usage skill for this task: Use Qwenpaw Usage when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
76/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamainferred

    The skill text mentions Llama or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# QwenPaw 命令行使用技巧

本 Skill 覆盖两类高频场景:**心跳(Heartbeat)任务配置** 和 **打包部署 QwenPaw 实例到其他服务器**。

---

## 场景一:添加 / 修改心跳(Heartbeat)任务

### 什么是心跳

心跳是 QwenPaw 的定时自检机制:按固定间隔读取 `HEARTBEAT.md` 的内容作为用户消息发给 QwenPaw,QwenPaw 执行后可选择将回复投递到上次对话的频道。适合做「定期自检、每日摘要、定时提醒」。

### 操作步骤

**1. 编写 HEARTBEAT.md**

文件位于工作目录下,默认路径:`~/.qwenpaw/HEARTBEAT.md`。 可通过环境变量 `QWENPAW_HEARTBEAT_FILE` 更改文件名。

直接用文本编辑器或 `cat` / `echo` 写入即可,内容是每次心跳要问 QwenPaw 的问题:

```markdown # Heartbeat checklist

- 扫描收件箱紧急邮件 - 查看未来 2h 的日历 - 检查待办是否卡住 - 若安静超过 8h,轻量 check-in ```

> 文件为空则跳过心跳,不会触发任何操作。

**2. 配置心跳参数**

心跳参数有两层配置:

- **全局默认**:`~/.qwenpaw/config.json` → `agents.defaults.heartbeat`(对所有智能体生效) - **智能体独立**:`~/.qwenpaw/workspaces/{agent_id}/agent.json` → `heartbeat`(覆盖全局默认)

可用字段:

| 字段 | 类型 | 默认值 | 说明 | | --------------------- | ----------- | ----------- | ----------------------------------------------------------- | | `every` | string | `"30m"` | 间隔,支持 `Nh`、`Nm`、`Ns` 组合(如 `"1h30m"`) | | `target` | string | `"main"` | `"main"` 仅执行不投递;`"last"` 发到上次对话的频道/用户 | | `activeHours` | object/null | `null` | 可选活跃时段限制 | | `activeHours.start` | string | `"08:00"` | 开始时间(HH:MM) | | `activeHours.end` | string | `"22:00"` | 结束时间(HH:MM) |

配置示例(每 30 分钟自检,不发到频道,写在 config.json 中):

```json "agents": { "defaults": { "heartbeat": { "every": "30m", "target": "main" } } } ```

配置示例(每 1 小时,发到上次频道,限 08:00-22:00,写在 agent.json 中):

```json "heartbeat": { "every": "1h", "target": "last", "activeHours": { "start": "08:00", "end": "22:00" } } ```

**3. 生效方式**

保存文件后,若服务正在运行会自动加载新配置。也可通过以下命令手动重载:

```bash qwenpaw daemon reload-config ```

> 注意:频道和 MCP 配置的变更需要在对话中执行 `/daemon restart` 或重启进程后才能生效。

### 心跳 vs 定时任务

| | 心跳 | 定时任务 (cron) | | ---- | ------------------------------------------ | ---------------------------- | | 数量 | 每个智能体只有一份 HEARTBEAT.md | 可创建多个 | | 间隔 | 一个全局间隔 | 每个任务独立 cron 表达式 | | 投递 | 仅 `main`(不发)或 `last`(上次频道) | 每个任务独立指定频道和用户 | | 适用 | 固定的一套自检/摘要 | 多条不同时间、不同内容的任务 |

> 如果用户需要的是「每天 9 点发早安到钉钉」「每 2 小时检查待办发到飞书」这类多条独立任务,应引导使用 `qwenpaw cron create`(参见下方定时任务部分),而非心跳。

### 完整操作示例

用户说:「帮我添加一个 heartbeat 任务,每小时检查一下有没有新邮件,如果有就通知我」

执行步骤:

```bash # 1. 写入心跳内容 cat > ~/.qwenpaw/HEARTBEAT.md << 'EOF' # 心跳任务

- 检查收件箱是否有新邮件 - 如果有新的未读邮件,列出发件人和主题 - 如果有紧急邮件,标注提醒 EOF

# 2. 编辑 agent.json 中的 heartbeat 配置 # 将 heartbeat 设为: # { # "every": "1h", # "target": "last", # "activeHours": { "start": "08:00", "end": "22:00" } # }

# 3. 重载配置 qwenpaw daemon reload-config ```

---

## 补充:定时任务(Cron)快速参考

当用户需要多条定时任务时,使用 `qwenpaw cron` 命令(需服务运行中):

```bash # 创建 agent 类型任务(向 QwenPaw 提问并发结果到频道) qwenpaw cron create \ --type agent \ --name "检查邮件" \ --cron "0 */1 * * *" \ --channel dingtalk \ --target-user "USER_ID" \ --target-session "SESSION_ID" \ --text "检查收件箱有没有新邮件,如果有列出来"

# 创建 text 类型任务(定时发固定文案) qwenpaw cron create \ --type text \ --name "每日早安" \ --cron "0 9 * * *" \ --channel dingtalk \ --target-user "USER_ID" \ --target-session "SESSION_ID" \ --text "早上好!新的一天开始了!"

# 常用管理命令 qwenpaw cron list # 列出所有任务 qwenpaw cron get <job_id> # 查看任务配置 qwenpaw cron state <job_id> # 查看运行状态 qwenpaw cron pause <job_id> # 暂停任务 qwenpaw cron resume <job_id> # 恢复任务 qwenpaw cron run <job_id> # 立刻执行一次 qwenpaw cron delete <job_id> # 删除任务

# 从 JSON 文件创建(复杂配置) qwenpaw cron create -f job_spec.json ```

可选参数:`--timezone`(默认用户时区)、`--enabled/--no-enabled`、`--mode`(`stream`/`final`)、`--base-url`、`--agent-id`。

Cron 表达式速查(五段式:分 时 日 月 周):

``` 0 9 * * * 每天 09:00 0 */2 * * * 每 2 小时 30 8 * * 1-5 工作日 08:30 */15 * * * * 每 15 分钟 0 0 * * 0 每周日零点 ```

---

## 场景二:打包 QwenPaw 实例部署到其他服务器

### 方案概览

| 方案 | 适用场景 | 复杂度 | | --------------------------------- | -------------------------------------- | ------ | | **工作区导出 + 官方镜像** | 已有配置和记忆需迁移到新服务器(推荐) | 低 | | **docker-compose 快速部署** | 新服务器全新部署 | 低 | | **自定义 Dockerfile** | 需要定制镜像(加自定义依赖/技能) | 中 |

### 方案 A:工作区导出 + 官方 Docker 镜像(推荐)

最简单的方式:导出当前工作区,在新服务器上用官方镜像挂载。

**步骤 1:导出当前工作区**

通过控制台(智能体 -> 工作区 -> 下载)可将整个工作区下载为 `.zip` 文件。

或手动打包:

```bash # 打包工作目录(包含配置、对话、记忆、技能等) cd ~/.qwenpaw tar czf qwenpaw-workspace.tar.gz \ config.json \ workspaces/ ```

**步骤 2:在新服务器创建 docker-compose.yml**

```yaml version: '3.8'

volumes: qwenpaw-data: name: qwenpaw-data qwenpaw-secrets: name: qwenpaw-secrets

services: qwenpaw: image: agentscope/qwenpaw:latest container_name: qwenpaw restart: always ports: - "127.0.0.1:8088:8088" volumes: - qwenpaw-data:/app/working - qwenpaw-secrets:/app/working.secret environment: # 按需传入 API Key - DASHSCOPE_API_KEY=${DASHSCOPE_API_KEY} # 如需连接宿主机的 Ollama/LM Studio,取消下方注释 # - OLLAMA_BASE_URL=http://host.docker.internal:11434 # 如需连接宿主机服务,取消下方注释 # extra_hosts: # - "host.docker.internal:host-gateway" ```

> 国内用户可替换为 ACR 镜像:`agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw:latest`

**步骤 3:恢复工作区**

```bash # 启动容器(会自动初始化默认配置) docker compose up -d

# 找到数据卷挂载点 MOUNT_PATH=$(docker volume inspect qwenpaw-data --format '{{ .Mountpoint }}')

# 将备份解压到数据卷 sudo tar xzf qwenpaw-workspace.tar.gz -C "$MOUNT_PATH"

# 重启使配置生效 docker compose restart ```

或在控制台中使用「上传工作区」功能恢复 `.zip` 文件(最大 100 MB)。

**步骤 4:验证服务**

```bash curl -s http://localhost:8088/api/agent/status | head -20 ```

### 方案 B:docker-compose 全新部署

适合不需要迁移旧数据的场景。

```bash # 1. 创建 docker-compose.yml(同方案 A 的 step 2)

# 2. 通过环境变量传入 API Key echo "DASHSCOPE_API_KEY=your-key-here" > .env

# 3. 启动 docker compose up -d

# 4. 访问控制台完成初始化 # 浏览器打开 http://<server_ip>:8088 ```

如需对外暴露,将 `127.0.0.1:8088:8088` 改为 `0.0.0.0:8088:8088`(注意安全风险,建议配合反向代理和认证)。

### 方案 C:自定义 Dockerfile

当需要在镜像中预装自定义技能、额外 Python 包或特殊系统依赖时使用。

参考 Dockerfile:

```dockerfile # 基于官方镜像 FROM agentscope/qwenpaw:latest

# 预装额外 Python 包 RUN pip install --no-cache-dir some-package another-package

# 复制自定义技能 COPY my_skills/ /app/working/customized_skills/

# 复制自定义配置(可选) # COPY config.json /app/working/config.json

# 如需更改默认端口 # ENV QWENPAW_PORT=3000 # EXPOSE 3000 ```

构建并运行:

```bash docker build -t my-qwenpaw . docker run -d \ --name qwenpaw \ --restart always \ -p 127.0.0.1:8088:8088 \ -v qwenpaw-data:/app/working \ -v qwenpaw-secrets:/app/working.secret \ -e DASHSCOPE_API_KEY="your-key" \ my-qwenpaw ```

### Docker 部署关键参数

| 环境变量 | 默认值 | 说明 | | -------------------------- | ----------------------------------------------- | ------------------ | | `QWENPAW_WORKING_DIR` | `/app/working` | 工作目录(容器内) | | `QWENPAW_SECRET_DIR` | `/app/working.secret` | 敏感数据目录 | | `QWENPAW_PORT` | `8088` | 服务端口 | | `QWENPAW_ENABLED_CHANNELS` | `discord,telegram,dingtalk,feishu,qq,console` | 启用的频道 |

### Docker 中连接本机模型服务

容器内 `localhost` 指向容器自身,需使用 `host.docker.internal`:

```bash docker run ... \ --add-host=host.docker.internal:host-gateway \ -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \ agentscope/qwenpaw:latest ```

---

## 使用建议

- 用户描述模糊时,先询问确认:是要心跳(单一自检循环)还是定时任务(多条独立任务)?是要迁移现有实例还是全新部署? - 涉及 API Key 等敏感信息时,引导用户使用环境变量或 `qwenpaw env set` 命令,不要在配置文件中明文写入。 - 多智能体场景下,几乎所有命令支持 `--agent-id` 参数,默认为 `default`。 - 配置修改后可用 `qwenpaw daemon reload-config` 热加载,无需重启服务。

Intended uses

  • Use Qwenpaw Usage when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.