qwenpaw-usage

QwenPaw 命令行使用技巧

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

---

场景一：添加 / 修改心跳（Heartbeat）任务

什么是心跳

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

操作步骤

1. 编写 HEARTBEAT.md

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

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

# 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 中）：

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

配置示例（每 1 小时，发到上次频道，限 08:00-22:00，写在 agent.json 中）：

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

3. 生效方式

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

qwenpaw daemon reload-config

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

心跳 vs 定时任务

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

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

完整操作示例

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

执行步骤：

# 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 命令（需服务运行中）：

# 创建 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 文件。

或手动打包：

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

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

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：恢复工作区

# 启动容器（会自动初始化默认配置）
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：验证服务

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

方案 B：docker-compose 全新部署

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

# 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：

# 基于官方镜像
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

构建并运行：

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：

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 热加载，无需重启服务。