QwenPaw 2.2.2 常用 CLI 命令与工具详解

目标：把 QwenPaw 2.2.2 自带的 qwenpaw 命令行工具按使用场景讲透——每个子命令干什么、关键参数怎么填、真实执行长什么样。本文全部命令与回显逐条实测于 Ubuntu 22.04.5 LTS 服务器（查询与实测日期 2026-10-22），未实测的命令只给参数说明并明确标注。

一、环境信息

本文实测环境：

项目	值	来源
操作系统	Ubuntu 22.04.5 LTS	`cat /etc/os-release` 实测
架构	x86_64	`uname -m` 实测
QwenPaw 版本	2.2.2（官方当前稳定版）	`qwenpaw --version` 实测
Python 环境	3.12.15（QwenPaw 自管 venv）	`qwenpaw doctor` 实测
安装目录	`/root/.qwenpaw`（含 `venv/`、`bin/qwenpaw` 包装器）	`qwenpaw doctor` 实测

系统信息实测回显（cat /etc/os-release 节选前三行）：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"

版本确认（qwenpaw --version）：

QwenPaw, version 2.2.2

更细的运行态信息用 qwenpaw daemon version（回显含工作目录与日志路径，排障时常用）：

Agent: default

**Daemon version**

- Version: 2.2.2
- Working dir: /root/.qwenpaw/workspaces/default
- Log file: /root/.qwenpaw/qwenpaw.log

⚠️ 注意：非登录 Shell 下 PATH 可能不含 /root/.qwenpaw/bin，直接敲 qwenpaw 会报 command not found。实测用绝对路径 /root/.qwenpaw/bin/qwenpaw 最稳，或重新登录让安装时写入的 PATH 生效。

二、工具概览

qwenpaw 是一个 Click 风格的 CLI，共 24 个子命令（含单复数别名）。按用途分六组：

分组	子命令	一句话用途
初始化与生命周期	`init` / `app` / `shutdown` / `clean` / `doctor` / `update` / `uninstall`	初始化工作区、启动/停止服务、体检、升级、卸载
对话与任务	`tui` / `task` / `chat`（别名 `chats`）	终端交互、无头单任务、会话增删查
定时任务	`cron`	计划任务的创建/查询/暂停/恢复/删除
智能体与模型	`agent`（别名 `agents`）/ `models` / `env`	多智能体管理、模型提供方配置、环境变量
渠道与扩展	`channel` / `skills` / `plugin` / `hub` / `acp` / `auth` / `desktop`	IM 渠道、技能、插件、多用户 Hub、ACP 接入、Web 登录、桌面窗口
守护运维	`daemon`	状态查看、配置热重载、日志、版本

三条通用约定，先记住能少走弯路：

每个子命令都支持 -h/--help，本文参数表均提炼自实测 --help 输出；
chat/cron/agent/skills 等命令通过 HTTP API 与后端通信，后端没起会直接报连接错误；task/doctor/clean/init 是本地命令，不需要后端在线（依据：task --help 自述 "headlessly (no web server)"，chat --help 自述 "via the HTTP API (/chats)"）；
带 --host/--port 全局参数的命令默认连 127.0.0.1:8088，改过端口要显式带上。

三、前置条件

按《Ubuntu 22.04 安装 QwenPaw 2.2.2 指南》完成 0→1 部署并初始化后，本文所有命令的前置状态是：后端服务已启动、监听 8088 端口。启动与验证三连（实测）：

nohup /root/.qwenpaw/bin/qwenpaw app >/root/app.out 2>&1 &

app 启动成功后会在前台打印横幅（下为实测回显，本文另测过 --port 8098 场景，横幅同款）：

╭──────────────────────────────────────╮
│                                      │
│  ✓ QwenPaw                           │
│  ├── Status:  Ready                  │
│  ├── Address: http://127.0.0.1:8098  │
│  └── Startup: 1.851s                 │
│                                      │
╰──────────────────────────────────────╯

验证监听与探活（fuser 属于 psmisc 包，Ubuntu 22.04 最小安装不带，apt install psmisc 即可，为什么用它见 4.1 节排障实录）：

fuser 8088/tcp
ps -p $(fuser 8088/tcp 2>/dev/null | tr -d " ") -o pid,args
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8088/

实测回显：

8088/tcp:             6720
    PID COMMAND
   6720 /root/.qwenpaw/venv/bin/python /root/.qwenpaw/venv/bin/qwenpaw app
200

再跑一次自检命令 qwenpaw doctor，确认环境、配置、智能体各段全 OK（节选）：

=== Environment ===
  python version: 3.12.15
  qwenpaw version: 2.2.2
  platform: Linux x86_64
  doctor_python_environment: venv (sys.prefix=/root/.qwenpaw/venv)
  qwenpaw_python_environment: venv (sys.prefix=/root/.qwenpaw/venv)
  working_dir: /root/.qwenpaw
  sqlite library: 3.53.1
  disk free (working dir volume): 365.11 GiB

=== Config ===
OK — /root/.qwenpaw/config.json

💡 提示：生产环境不建议 nohup 直启，用 systemd 托管更稳（单元文件与开机自启实测见《Ubuntu 22.04 安装 QwenPaw 2.2.2 指南》第七章）。

四、各工具详解

4.1 服务生命周期：app / shutdown / clean / doctor

app——启动 FastAPI 后端。关键参数：--host（默认 127.0.0.1）、--port（默认 8088）、--log-level（critical/error/warning/info/debug/trace）、--reload（仅开发用）。对局域网开放时用 --host 0.0.0.0，同时建议在 config.json 的 security.allow_no_auth_hosts 里收敛白名单（参数含义见《QwenPaw 2.2.2 配置参数详解》5.3 节）。

shutdown——按端口定位并停止后端。它就是 8088 端口上那个 qwenpaw app 进程的官方停止方式。但实测在最小化 Ubuntu 服务器上直接踩坑：app 明明在跑（curl 探活 200），qwenpaw shutdown 却报找不到进程：

Backend listener processes: nothing to stop
Frontend development processes: nothing to stop
Desktop wrapper processes: nothing to stop
Related wrapper processes: nothing to stop
Error: No running QwenPaw backend/frontend process was found.

排障实录：阅读 CLI 源码（qwenpaw/cli/shutdown_cmd.py）确认，shutdown 靠 lsof -iTCP:8088 -sTCP:LISTEN 或 fuser 8088/tcp 找监听端口的 PID，两个工具都没有就返回空集。处置：apt install psmisc（或 lsof）。装好后重跑，成功定位并停止了进程：

Backend listener processes (1 total):
  PID 6594: /root/.qwenpaw/venv/bin/python /root/.qwenpaw/venv/bin/qwenpaw app
Frontend development processes: nothing to stop
Desktop wrapper processes: nothing to stop
Related wrapper processes: nothing to stop
Failed to stop the following processes:
  PID 6594: /root/.qwenpaw/venv/bin/python /root/.qwenpaw/venv/bin/qwenpaw app
Error: Failed to shutdown process(es): 6594

虽然 CLI 报了 "Failed to stop"，但停后探活 curl 返回 000——进程实际已被 SIGTERM 停止。误报的根因同样在源码注释里写明：没有 init 进程收割的环境里，已退出的进程以 zombie（defunct）状态残留，os.kill(pid, 0) 仍判定其存在；正式服务器有 systemd 收割僵尸进程，不会遇到这个误报。systemd 托管场景下停止服务直接 systemctl stop qwenpaw，不走这条命令。

clean——清空 WORKING_DIR（~/.qwenpaw）。高危命令，先 --dry-run 看清单再决定（实测回显）：

WORKING_DIR: /root/.qwenpaw
Will remove:
  - /root/.qwenpaw/.qwenpaw_restore.lock
  - /root/.qwenpaw/HEARTBEAT.md
  - /root/.qwenpaw/bin
  - /root/.qwenpaw/config.json
  - /root/.qwenpaw/governance
  - /root/.qwenpaw/nm-bridge.json
  - /root/.qwenpaw/plugins
  - /root/.qwenpaw/qwenpaw.log
  - /root/.qwenpaw/skill_pool
  - /root/.qwenpaw/skill_scanner_blocked.json

配置、会话、技能池全在里面，确认无误才加 --yes 执行；本文实测止步于 --dry-run。

doctor——本地体检，覆盖环境/配置/智能体/渠道凭据/MCP 客户端/技能布局/安全基线/记忆嵌入八段。全量回显与逐段解读见《QwenPaw 2.2.2 配置参数详解》第二章；常用参数 --deep（附加渠道可达性与本地模型服务检查）、--timeout（API 检查超时，默认 5 秒）。

4.2 对话入口：tui / task

tui——终端聊天界面，交互式程序（无法在文档里回放画面），关键参数：--agent 指定智能体、--resume SESSION_ID 恢复历史会话。

task——无头执行单条任务指令，跑完即退出，是脚本与定时场景的官方入口。第一个坑：-i 必填，缺了直接报错（实测）：

Usage: qwenpaw task [OPTIONS]
Try 'qwenpaw task --help' for help.

Error: Missing option '-i' / '--instruction'.

带上指令后真实回环一次（模型走已配置的 Kilo 免费路由，实测）：

qwenpaw task -i "请只回复四个字：测试成功"

ERROR .qwenpaw/venv/lib/python3.12/site-packages/qwenpaw/agents/skill_system/registry.py:1310 | 2026-10-22 16:10:02 | Skipping skill 'mailbox' in workspace /root/.qwenpaw/workspaces/default: MCP server not configured: qwenpawmail
WARNING .qwenpaw/venv/lib/python3.12/site-packages/qwenpaw/governance/resource_governor.py:201 | 2026-10-22 16:10:03 | ResourceGovernor: sandbox not available — Cannot read /sys/kernel/security/lsm. SANDBOX_FALLBACK will escalate to ASK.
{
  "status": "success",
  "elapsed_seconds": 2.24,
  "response": "\n\n测试成功",
  "usage": {}
}

逐行解读：前两行是日志流——mailbox 技能依赖的 MCP 邮件服务没配，跳过不影响本任务；沙箱因内核缺 LSM 支持回退为 ASK 审批（对应 sandbox_enabled: false 的默认配置）。核心结果是 JSON：status: success、耗时 2.24 秒、模型回复「测试成功」。常用参数：-m 指定模型（如 dashscope/qwen3.8-max）、--max-iters 最大 ReAct 迭代数（默认 30）、-t 超时秒数（默认 900）、--agent-id 指定智能体、--output-dir 落盘执行日志。

💡 技术拓展：QwenPaw 有四种对话入口，选型差异如下——

入口	形态	交互性	典型场景
`qwenpaw tui`	终端 TUI	持续交互	服务器上随手调试
`qwenpaw task`	单次进程	一问一答即退出	脚本/CI/无人值守
Web Console（`app` 的 8088）	浏览器	持续交互	日常主力使用
`qwenpaw hub`	多用户控制面	多人同时	团队共享一套部署

本文实测采用 task 做功能验证、curl 做 Web 探活；tui 与 hub 为交互式程序，参数见各自 --help。

4.3 会话管理：chat

chat（别名 chats）管理 Web 侧会话记录，五个子命令 create/list/get/update/delete。创建一条测试会话（实测）：

qwenpaw chat create --session-id s-demo-1 --user-id root

{
  "id": "5afc1c26-bbc5-4f34-841a-b5cf7107e7af",
  "name": "New Chat",
  "session_id": "s-demo-1",
  "user_id": "root",
  "channel": "console",
  "created_at": "2026-10-22T16:34:08.167640Z",
  "updated_at": "2026-10-22T16:34:08.167641Z",

（节选；后续字段为 last_finished_at/meta/status 等。）列表与详情：

qwenpaw chat list
qwenpaw chat get 5afc1c26-bbc5-4f34-841a-b5cf7107e7af

get 实测回显（节选）：

{
  "messages": [],
  "status": "idle"
}

删除用 chat delete <chat_id>，实测回显 {"deleted": true}。会话内容本身存于工作区，chat 只维护索引与元数据；改名用 chat update <chat_id> --name <新名字>（参数见 --help，本文未演示）。

4.4 定时任务：cron

cron 共九个子命令：create/get/list/state/update/delete/pause/resume/run。创建支持两种方式：内联参数或 -f 指定 JSON spec 文件（二者互斥）。内联必填五件套：--type（text=发固定文案 / agent=让 Agent 跑问题）、--name、--cron（五段 cron 表达式）、--channel（投递渠道，如 console）、--target-user、--text。可选项里最常用的是 --timezone（默认继承 config 的 user_timezone）与 --mode（stream 逐段推送 / final 只发终稿）。

实测创建一个 agent 型任务「每日摘要演示」（每天 09:30，节选回显）：

qwenpaw cron create --type agent --name "每日摘要演示" --cron "30 9 * * *" \
  --channel console --target-user root --text "用一句话播报今日待办"

    "max_concurrency": 1,
    "timeout_seconds": 120,
    "misfire_grace_seconds": 600,
    "share_session": false,
    "tool_safety": false
  },
  "meta": {}
}

查询三连（list 返回数组，get 返回单个 spec，state 返回运行态）：

qwenpaw cron list
qwenpaw cron get f96fd510-9d65-4685-bea3-2069190c9b93
qwenpaw cron state f96fd510-9d65-4685-bea3-2069190c9b93

list 实测节选（任务定义主体）：

[
  {
    "id": "f96fd510-9d65-4685-bea3-2069190c9b93",
    "name": "每日摘要演示",
    "enabled": true,
    "schedule": {
      "type": "cron",
      "cron": "30 9 * * *",
      "run_at": null,
      "timezone": "UTC",

state 实测回显（下次执行时间一目了然）：

{
  "next_run_at": "2026-10-23T09:30:00Z",
  "last_run_at": null,
  "last_status": null,
  "last_error": null
}

暂停与恢复（实测）：

{
  "paused": true
}
{
  "resumed": true
}

删除（实测）：

{
  "deleted": true
}
[]

（第二行是删除后紧跟的 cron list，已为空数组。）cron run <id> 立即触发一次（无视计划），pause/resume 之外还有 update 修改既有任务，参数同 create。

时区继承实测：把 config.json 的 user_timezone 改为 Asia/Shanghai 并热重载后，新建任务自动继承新时区（完整链路实测）：

user_timezone -> Asia/Shanghai

qwenpaw daemon reload-config

**Config reloaded**

- load_config() re-invoked successfully.

随后 cron create 的新任务 spec 里 "timezone": "Asia/Shanghai"（节选），验证完 cron delete 清理（回显 "deleted": true）。改时区相关配置的细节见《QwenPaw 2.2.2 配置参数详解》3.2 节。

4.5 智能体管理：agent

agent（别名 agents）四个子命令：create/list/delete/chat。创建一个新智能体（实测，节选回显）：

qwenpaw agent create --name "Research Bot" --agent-id research_bot

  "workspace_dir": "/root/.qwenpaw/workspaces/research_bot",
  "enabled": true,
  "pinned": false
}

每个智能体有独立 workspace 目录。agent list 实测能看到默认就存在的两个智能体（default 与内置的 QwenPaw_QA_Agent_0.2，后者是官方问答助手），节选：

{
  "agents": [
    {
      "id": "default",
      "name": "Default",
      "workspace_dir": "/root/.qwenpaw/workspaces/default",
      "enabled": true,
      "pinned": true,
      "startup_status": "running",
      "backend": "qwenpaw",

排障实录：删除智能体默认有交互确认，在脚本/无终端场景会直接中断（实测回显）：

WARNING: This will stop the agent and remove it from agent list.
Continue with deletion? [y/N]: Aborted!

加 --yes 跳过确认即可（实测）：

qwenpaw agent delete research_bot --yes

  "success": true,
  "agent_id": "research_bot"
}

追加 --remove-workspace 会连工作区目录一起删。agent chat 用于智能体间通信（--from-agent/--to-agent/--text），本文未演示。

4.6 模型管理：models

models 十个子命令，覆盖提供方与模型的全生命周期：list/config/config-key/add-provider/add-model/remove-provider/remove-model/set-llm/download/local/remove-local。models list 实测输出很长（内置 20+ 提供方），看 DashScope 段落感受格式：

────────────────────────────────────────────
  DashScope (dashscope)
────────────────────────────────────────────
  base_url        : https://dashscope.aliyuncs.com/compatible-mode/v1
  api_key         : (not set)
  api_key_prefix  : sk
  models          :
    - Qwen3.8 Max (qwen3.8-max)
    - Qwen3.7 Max (qwen3.7-max)
    - Qwen3.7 Plus (qwen3.7-plus)
    - Qwen3.6 Plus (qwen3.6-plus)
    - DeepSeek-V4 Pro (deepseek-v4-pro)
    - GLM-5.2 (glm-5.2)

输出末尾是当前生效模型（实测走的是 Kilo 免费路由）：

════════════════════════════════════════════
  Active Model Slot
════════════════════════════════════════════
  LLM             : kilo / kilo-auto/free

本地模型两条：models local 列出已下载的本地模型（实测输出 No local models downloaded.，并提示用 models download <repo_id> 下载）、models remove-local 删除。换用某家提供方：先 models config-key 填 API Key，再 models set-llm 交互选定模型——两条都是交互式命令，脚本场景请直接改 config.json 后热重载（见《QwenPaw 2.2.2 配置参数详解》第三章）。

4.7 环境变量：env

env 三个子命令管理运行时环境变量（写入工作区配置，供 Agent 工具调用时读取）。实测一轮增查删：

qwenpaw env set DASHSCOPE_API_KEY q1w2e3r4

✓ DASHSCOPE_API_KEY = q1w2e3r4

qwenpaw env list

  Key                             Value
  ────────────────────────────────────────────────────────
  DASHSCOPE_API_KEY               q1w2e3r4

qwenpaw env delete DASHSCOPE_API_KEY

✓ Deleted: DASHSCOPE_API_KEY

⚠️ 注意：env list 会明文回显值。生产服务器上放真实 API Key 前先想清楚谁能登录这台机器；本文按惯例全程用演示口令 q1w2e3r4，你应换成自己的密钥并控制好文件权限。

4.8 渠道管理：channel

channel 三个子命令：config（交互式配置）、list（查看当前配置）、send（向渠道发文本）。channel list 按 Agent 逐渠道展示全部键值，disabled 渠道同样完整展示（实测节选，第一个渠道 iMessage；略去 5 行依赖库 DeprecationWarning，其余 17 个渠道同格式）：

────────────────────────────────────────
  iMessage  [disabled]
────────────────────────────────────────
  bot_prefix          : 
  show_tool_calls     : True
  show_tool_results   : True
  tool_call_max_length: 200
  tool_result_max_length: 500
  show_thinking       : True
  dm_policy           : open
  group_policy        : open
  allow_from          : []
  deny_message        : 
  require_mention     : False
  no_text_debounce    : True
  access_control_dm   : False

渠道启停在 config.json 的 channels 段（18 个渠道键与准入参数见《QwenPaw 2.2.2 配置参数详解》5.1 节）；channel send --channel console --text "..." 可向指定渠道推一条消息做联通验证。

4.9 技能与插件：skills / plugin

skills——工作区与共享技能池管理，八个子命令：list/info/enable/disable/install/uninstall/test/config。skills list 实测（default 工作区，16 个内置技能全启用）：

Skills for agent: default


──────────────────────────────────────────────────
  Skill Name                     Source       Status
──────────────────────────────────────────────────
  QA_source_index                builtin      ✓ enabled
  browser                        builtin      ✓ enabled
  channel_message                builtin      ✓ enabled
  chat_with_agent                builtin      ✓ enabled
  cron                           builtin      ✓ enabled
  dingtalk_channel               builtin      ✓ enabled
  docx                           builtin      ✓ enabled
  file_reader                    builtin      ✓ enabled
  guidance                       builtin      ✓ enabled
  mailbox                        builtin      ✓ enabled
  make-skill                     builtin      ✓ enabled
  make_plan                      builtin      ✓ enabled
  multi_agent_collaboration      builtin      ✓ enabled
  pdf                            builtin      ✓ enabled
  pptx                           builtin      ✓ enabled
  xlsx                           builtin      ✓ enabled
──────────────────────────────────────────────────
  Showing: 16 of 16 skills, 16 enabled, 0 disabled

skills list --pool 看共享池（同一批技能，表尾 Total: 16 skills）。看单个技能详情（实测）：

qwenpaw skills info cron

Skill: cron
Enabled: yes
Channels: all
Source: builtin
Path: /root/.qwenpaw/workspaces/default/skills/cron
Description: Use this skill only for scheduled or recurring tasks. Manage jobs with qwenpaw cron list/create/get/state/update/pause/resume/delete/run, and always pass --agent-id explicitly.

启停验证（实测一轮 disable/enable）：

  ✓ Disabled: xlsx
  ✓ Enabled: xlsx

plugin——五个子命令 list/info/install/uninstall/validate。实测默认装了两个内置插件（技能市场源）：

📦 Installed Plugins:

  • ModelScope Hub (v1.0.0)
    ID: modelscope-hub
    Description: ModelScope Skill marketplace source.

  • QwenPaw Hub (v1.0.0)
    ID: qwenpaw-hub
    Description: QwenPaw Skill marketplace source.

4.10 守护运维：daemon

daemon 五个子命令：status/version/reload-config/logs/restart。daemon status 实测：

**Daemon Status**

- Config loaded: yes
- Max input length: 256000
- Working dir: /root/.qwenpaw/workspaces/default
- Memory manager: not attached

daemon reload-config 热重载配置（实测回显 **Config reloaded** 与 - load_config() re-invoked successfully.，配合时区继承的闭环验证见 4.4 节）；daemon version 回显见第一章；daemon logs 直接尾部输出 WORKING_DIR 下的 qwenpaw.log（等效 tail 该文件）；daemon restart 只打印重启指引——CLI 自身不持有进程，systemd 场景请 systemctl restart qwenpaw。

4.11 其余命令速览

以下命令参数提炼自实测 --help（本文未跑其主流程，不贴编造回显）：

命令	用途	关键参数/说明
`init`	初始化工作区（config.json + HEARTBEAT.md）	`--defaults` 免交互；脚本/无人值守须追加 `--accept-security` 跳过安全确认
`hub`	多用户控制面（多管理员/多用户共享一套部署）	`--host/--port` 同 app；`--init-admin 用户名` 本地初始化首个管理员；`--force-public` 才允许绑公网地址
`acp`	以 ACP 协议（stdio）供编辑器等客户端接入	`--agent` 指定智能体；`--runtime-provider openai-env` 从环境变量取临时模型配置
`auto`	由 `@api_action` 自动生成的内部 API 命令集	目前仅 crons 三个：`crons-list_jobs` / `crons-create_or_replace_job` / `crons-delete_job`
`auth`	Web 登录管理	唯一子命令 `reset-password`：重置已注册 Web 用户的密码
`desktop`	自动选空闲端口起服务并打开原生 webview 桌面窗口	适合本机桌面场景；服务器无显示环境用不上
`update`	在当前 Python 环境内升级	`-y` 免确认；`--prerelease` 升到预发布版；升级前会先停运行中的服务
`uninstall`	移除运行环境、CLI 包装器与 PATH 写入	`--purge` 连数据（配置/会话/模型）一起删；`--yes` 免确认；卸载实测见《Ubuntu 22.04 安装 QwenPaw 2.2.2 指南》第十一章

其中 update/uninstall 的完整实测（含升级降级回退链路与卸载清理）属于安装篇职责范围，本文不重复。

五、注意事项

交互确认是无头脚本的头号杀手。agent delete、clean、init 交互提问在非终端环境一律 Aborted!，脚本里分别用 --yes、--yes、--defaults --accept-security 绕过（三处均为实测踩坑）。
shutdown 依赖 lsof/fuser。最小化 Ubuntu 两个都没有，shutdown 会「睁眼瞎」；先 apt install psmisc（排障实录见 4.1 节）。
分清本地命令与 API 命令。task/doctor/clean/init 不需要后端在线；chat/cron/agent/models 配置类/skills 增删类 走 HTTP API，后端没起直接连接失败。报 Connection refused 先看 fuser 8088/tcp。
task 的默认超时 900 秒、最大迭代 30 次。长任务用 -t/--max-iters 放宽；被 OOM 或配额打断时看 --output-dir 里的 result.json。
配置改动一律热重载验证。改 config.json 后 qwenpaw daemon reload-config，再跑一条受影响命令确认（如改时区后建 cron 看继承，见 4.4 节）。
密钥纪律。env list、channel list、models list 都会明文展示已配置的凭据字段；对外分享排障输出前先过滤，密钥不进文档、不进仓库。

六、常见问题

Q1：命令报连接错误（Connection refused）？ 后端没起或端口不对。fuser 8088/tcp 确认监听，没有就 qwenpaw app（或 systemd 场景 systemctl start qwenpaw）启动；改过端口的记得给 API 类命令带 --port。

Q2：脚本里交互命令全部 Aborted？ 见第五章第 1 条：删除/清理类加 --yes，初始化加 --defaults --accept-security。凡 --help 里出现 "Skip ... confirmation/prompt" 字样的参数就是为脚本准备的。

Q3：cron 任务没有按我预期的时区跑？ 两级时区：任务级 --timezone 优先，否则继承 config 的 user_timezone（默认 UTC）。改完配置必须 daemon reload-config；验证方法照抄 4.4 节的继承实测。

Q4：qwenpaw shutdown 说找不到进程，但服务明明在跑？ 缺 lsof/fuser，见 4.1 节排障实录。装 psmisc 后重试；systemd 托管场景直接 systemctl stop qwenpaw，不用这条命令。

Q5：task 跑一半卡住不动？ 先看是不是模型侧问题（免费路由偶发限流），-m 换稳定提供方重试；再检查 -t 超时与 --max-iters 是否太小导致提前截断；需要留证据就加 --output-dir，结果与执行日志会落盘。

Q6：装了新技能但 Agent 行为没变化？ skills list 确认状态列是 ✓ enabled；skills info <名字> 看 Description 是否符合预期；用 skills test <名字> 做本地校验。技能按工作区隔离，注意操作的是哪个 Agent 的工作区。

七、参考链接

GitHub 仓库：https://github.com/agentscope-ai/QwenPaw （查询日期 2026-10-22）
官方文档站：https://qwenpaw.agentscope.io/ （查询日期 2026-10-22）
PyPI 项目页：https://pypi.org/project/qwenpaw/ （查询日期 2026-10-22）
本系列同版本篇目：《QwenPaw 介绍与选型指南》、《QwenPaw 2.2.2 配置参数详解》、《Ubuntu 22.04 安装 QwenPaw 2.2.2 指南》