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

目标：把 Copaw（现名 QwenPaw）的 qwenpaw 命令行工具按「上手 → 配置 → 日常管理」逐条讲透：每条命令给真实回显，覆盖初始化、服务、诊断、模型、环境变量、频道、智能体、定时任务、会话、技能、清理与停止。全部输出为 2026-11-03 在 Ubuntu 24.04 服务器上的实测照抄，版本 2.2.2.post1。

一、环境信息

项目	值
主机	srv01.example.com（x86_64）
系统	Ubuntu 24.04.2 LTS
Python	3.12.3（venv：`/opt/qp-venv`）
组件	qwenpaw 2.2.2.post1
工作目录	`/root/.qwenpaw`（日志 `qwenpaw.log`）
服务地址	`127.0.0.1:8088`（`qwenpaw app` 默认）

💡 前置阅读：配置文件与目录的字段级含义见《Copaw 2.2.2 配置参数详解》；容器化部署见《Copaw 2.2.2 Docker Compose 部署指南》。

二、工具概览

qwenpaw 是单二进制入口的 Click 命令组，qwenpaw --help 实测输出（节选命令表）：

Usage: qwenpaw [OPTIONS] [COMMAND] [ARGS]...
  QwenPaw CLI.

Options:
  --version       Show the version and exit.
  --host TEXT     API Host
  --port INTEGER  API Port
  -h, --help      Show this message and exit.

Commands:
  acp        Start QwenPaw as an ACP agent (stdio).
  agent      Manage agents and inter-agent communication.
  app        Run QwenPaw FastAPI app.
  auth       Manage web authentication.
  auto       Auto-generated commands from @api_action declarations.
  channel    Manage channel configuration...
  chat       Manage chat sessions via the HTTP API (/chats).
  clean      Clear QwenPaw WORKING_DIR (~/.qwenpaw by default).
  cron       Manage scheduled cron jobs via the HTTP API (/cron).
  daemon     Daemon commands: status, restart, reload-config, version, logs.
  desktop    Run QwenPaw app on an auto-selected free port in a webview...
  doctor     Local sanity checks.
  env        Manage environment variables.
  hub        Run the multi-user QwenPaw Hub control plane.
  init       Create working dir with config.json and HEARTBEAT.md...
  models     Manage LLM models and provider configuration.
  plugin     Plugin management commands.
  shutdown   Force stop the running QwenPaw app processes.
  skills     Manage workspace and skill-pool skills.
  task       Run a single task instruction headlessly (no web server).
  tui        Open the QwenPaw terminal chat UI.
  uninstall  Remove QwenPaw environment, CLI wrapper, and shell PATH...
  update     Upgrade QwenPaw in the current Python environment.

命令分组与依赖关系（实测归纳）：

组	子命令	是否需要 `app` 在线
上手	`init` / `app` / `tui` / `desktop` / `task` / `acp`	本身即入口
巡检	`daemon`（status/version/logs/reload-config/restart）、`doctor`	否（本地读取）
配置	`models`、`env`、`channels config`	否
运行期管理	`channels list/send`、`agents list/create/delete/chat`、`cron` 全部、`chats`、`skills`	是（走 HTTP API）
运维	`clean`、`shutdown`、`auth`、`update`、`uninstall`、`plugin`	视命令而定

⚠️ 实测坑：agents list 等 API 类命令在服务未启动时直接抛 httpx Traceback（httpcore.ConnectError: [Errno 111] Connection refused）而非友好提示——先启动 qwenpaw app 再使用（见 6.2）。

寻址机制：全局 --host/--port 对所有子命令生效；未指定时 CLI 读取 config.json 的 last_api（app 启动时写入），缺省回落 127.0.0.1:8088。多智能体场景用 --agent-id（默认 default）。

三、前置条件

python3 -m venv /opt/qp-venv && source /opt/qp-venv/bin/activate
pip install "qwenpaw==2.2.2.post1"
qwenpaw --version
# QwenPaw, version 2.2.2.post1

四、各命令详解

4.1 qwenpaw init —— 初始化工作目录

qwenpaw init                 # 交互式（LLM 提供商 → 环境变量 → HEARTBEAT.md）
qwenpaw init --defaults      # 非交互默认值
qwenpaw init --force         # 覆盖已有配置

实测（脚本环境）：

$ qwenpaw init --defaults
Warning: Input is not a terminal (fd=0).
Aborted!

$ qwenpaw init --defaults --accept-security
Configuration saved to: /root/.qwenpaw/config.json
✓ Initialization complete!

⚠️ 非 TTY（cron/CI/管道）必须加 --accept-security 跳过安全须知确认，否则直接中止。另有 --workspace / -w 指定工作区路径。

4.2 qwenpaw app —— 启动服务

qwenpaw app                          # 默认 127.0.0.1:8088
qwenpaw app --host 0.0.0.0 --port 8088 --log-level debug --reload

选项实测（--help）：--host（默认 127.0.0.1）、--port（默认 8088）、--reload（开发用）、--log-level（critical/error/warning/info/debug/trace）、--workers [已废弃]——QwenPaw 设计为单 worker，多进程会破坏内存状态与 WebSocket。

启动后 config.json 的 last_api 被写为实际监听地址；daemon status 等命令即以此寻址。

4.3 tui / desktop / task / acp —— 特殊运行形态

qwenpaw tui：终端聊天界面；qwenpaw . / qwenpaw tui /path 将目录绑定为本次会话项目（启用 Coding 模式，会话级、不落盘）；--agent 指定智能体。
qwenpaw desktop：在自动选择的空闲端口以 webview 桌面窗口运行（Windows 10+/macOS 14+ 桌面版内核）。
qwenpaw task：无 Web 服务、单任务直跑（脚本/流水线场景），支持 --mode、--output-dir、--share。
qwenpaw acp：以 ACP 协议（stdio）把 QwenPaw 自身作为编码智能体暴露给外部编辑器。

以上为交互式/长驻形态，回显以官方文档口径为准。

4.4 qwenpaw daemon —— 运行状态巡检（全部本地可用）

$ qwenpaw daemon version
Agent: default
**Daemon version**
- Version: 2.2.2.post1
- Working dir: /root/.qwenpaw/workspaces/default
- Log file: /root/.qwenpaw/qwenpaw.log

$ qwenpaw daemon status
Agent: default
**Daemon Status**
- Config loaded: yes
- Max input length: 256000
- Working dir: /root/.qwenpaw/workspaces/default
- Memory manager: not attached

$ qwenpaw daemon logs -n 6
2026-11-03 04:21:45 | INFO | ...workspace.py:855 | Workspace stopped: default
2026-11-03 04:21:45 | INFO | ...multi_agent_manager.py:755 | All agents stopped
2026-11-03 04:21:45 | INFO | ..._app.py:746 | Stopping BackupManager...
2026-11-03 04:21:45 | INFO | ..._app.py:756 | Stopping local model server...
2026-11-03 04:21:45 | INFO | ..._app.py:779 | Stopping TokenUsageManager...
2026-11-03 04:21:45 | INFO | ..._app.py:813 | Application shutdown complete

$ qwenpaw daemon reload-config
Agent: default
**Config reloaded**
- load_config() re-invoked successfully.

$ qwenpaw daemon restart
Agent: default
**Restart**
- Not running inside app. Run the app (e.g. `qwenpaw app`) and use
  /daemon restart in chat, or restart the process with systemd/supervisor/…

要点：logs 直接读工作目录 qwenpaw.log（默认 100 行）；reload-config 离线也能做本地重读校验；restart 在进程外只打印指引——进程内重载需在对话中发 /daemon restart。所有 daemon 子命令支持 --agent-id。

4.5 qwenpaw doctor —— 只读体检

qwenpaw doctor 实测（服务停止状态）分段输出 Environment / Config / Agents / Channels / MCP / Skills / Security / Memory / Cron / Working directory / Startup paths 全 OK，仅 API 段失败：

=== Environment ===
  python version: 3.12.3
  qwenpaw version: 2.2.2.post1
  platform: Linux x86_64
  working_dir: /root/.qwenpaw
  disk free (working dir volume): 89.75 GiB
=== Config ===
OK — /root/.qwenpaw/config.json
=== Agents ===
OK — 2 agent profile(s); each workspace contains agent.json
...
=== API ===
FAIL — health not reachable (http://127.0.0.1:8088/api/healthz)
[Errno 111] Connection refused
Hint: start the server with `qwenpaw app` (default http://127.0.0.1:8088).

选项：--deep（已启用频道出站探测 + 本地 llama 提示）、--timeout（默认 5s）、--llm-timeout（默认 15s）、--port/--host 强制寻址。

doctor fix（唯一可写盘子命令，默认先备份到 doctor-fix-backups/<时间戳>/files/）：

$ qwenpaw doctor fix --dry-run
Nothing to do (already satisfied).

推荐流程：fix --dry-run 预览 → fix --dry-run --only ensure-working-dir,ensure-workspace-dirs 缩小范围 → fix -y --only ... 执行；--non-interactive 仅允许安全+只读类修复。

4.6 qwenpaw models —— 模型提供商

子命令：list / config（交互式全流程）/ config-key [provider] / set-llm（只换活跃模型）/ local / download <repo_id> / remove-local。

qwenpaw models list 实测节选（26+ 提供商全景，密钥脱敏）：

=== Providers ===
────────────────────────────────────────────
  QwenPaw Local (qwenpaw-local) [local]
  No models downloaded.
  Use 'qwenpaw models download' to add models.
────────────────────────────────────────────
  Ollama (ollama) [local]
────────────────────────────────────────────
  LM Studio (lmstudio) [local]
────────────────────────────────────────────
  OpenRouter (openrouter)
  base_url        : https://openrouter.ai/api/v1
  api_key         : (not set)
────────────────────────────────────────────
  ModelScope (modelscope)
  base_url        : https://api-inference.modelscope.cn/v1
  api_key         : (not set)
  models          :
    - Qwen3.5-122B-A10B (Qwen/Qwen3.5-122B-A10B)
    - GLM-5 (ZhipuAI/GLM-5)
────────────────────────────────────────────
  DashScope (dashscope)
  ...

本地模型：qwenpaw models download Qwen/Qwen3-4B-GGUF（自动选 Q4_K_M，--source modelscope 换源）；Ollama 模型由 Ollama 自身管理（ollama pull），QwenPaw 自动发现。config-key custom 可配任意 OpenAI/Anthropic 兼容端点（vLLM 等）。

4.7 qwenpaw env —— 工具环境变量

实测完整周期（存储即加密，见配置篇 5.3）：

$ qwenpaw env set TAVILY_API_KEY "tvly-demo123456"
✓ TAVILY_API_KEY = tvly-demo123456

$ qwenpaw env list
  Key                             Value
  ────────────────────────────────────────────────────────
  TAVILY_API_KEY                  tvly-demo123456

$ qwenpaw env delete TAVILY_API_KEY
✓ Deleted: TAVILY_API_KEY

$ qwenpaw env list
No environment variables configured.

4.8 qwenpaw channels —— 频道

别名 qwenpaw channel（单数）。子命令：list（密钥脱敏）/ config（交互式启用与凭据，无 configure）/ send（单向推送，5 参数齐全）。

qwenpaw channels list 实测（18 类频道全量落盘，节选）：

Channels for agent: default

────────────────────────────────────────
  iMessage  [disabled]
────────────────────────────────────────
  bot_prefix          :
  show_tool_calls     : True
  tool_call_max_length: 200
  dm_policy           : open
  group_policy        : open
  allow_from          : []
  db_path             : ~/Library/Messages/chat.db
  poll_sec            : 1.0

console 频道默认 [enabled]；其余频道需经 config 或控制台填凭据。--agent-id 支持按智能体查看。

4.9 qwenpaw agents —— 多智能体

create 不依赖服务（直接写全局配置与工作区）：

$ qwenpaw agents create --name "测试助手"
{
  "id": "FKQ2Ja",
  "workspace_dir": "/root/.qwenpaw/workspaces/FKQ2Ja",
  "enabled": true,
  "pinned": false
}

list 走 HTTP API（服务必须在线），实测返回每个智能体的 id/name/description/enabled/pinned/startup_status/backend/available_in_chat 等字段：

$ qwenpaw agents list
{
  "agents": [
    { "id": "default", "name": "Default", "enabled": true, "pinned": true,
      "startup_status": "running", "backend": "qwenpaw", ... },
    { "id": "QwenPaw_QA_Agent_0.2", "name": "QA Agent", ... }
  ]
}

delete 实测（--remove-workspace 连工作区一起删）：

$ qwenpaw agents delete FKQ2Ja --remove-workspace --yes
{
  "success": true,
  "agent_id": "FKQ2Ja",
  "workspace_dir": "/root/.qwenpaw/workspaces/FKQ2Ja",
  "workspace_removed": true
}

agents chat --to <id> "指令" 支持智能体间对话（--background 异步、--stream 流式）。

4.10 qwenpaw cron —— 定时任务

创建（--type text|agent；--schedule-type cron|once；text 任务需 --channel/--target-user/--target-session/--text）：

$ qwenpaw cron create --type text --schedule-type cron --name "喝水提醒" \
    --cron "*/30 * * * *" --channel console --target-user demo \
    --target-session demo --text "该喝水了"
{
  "id": "82cec4cd-d428-4de7-a24e-d8db0c3b9780",
  "name": "喝水提醒",
  "enabled": true,
  "schedule": { "type": "cron", "cron": "*/30 * * * *", "timezone": "Etc/UTC" },
  "task_type": "text",
  "text": "该喝水了",
  "dispatch": { "type": "channel", "channel": "console",
    "target": { "user_id": "demo", "session_id": "demo" }, "mode": "stream" },
  "runtime": { "max_concurrency": 1, "timeout_seconds": 120 }
}

生命周期实测（state/pause/resume/run/delete 均以任务 ID 操作）：

$ qwenpaw cron state 82cec4cd-d428-4de7-a24e-d8db0c3b9780
{ "next_run_at": "2026-11-03T04:30:00Z", "last_run_at": null,
  "last_status": null, "last_error": null }

$ qwenpaw cron pause 82cec4cd-d428-4de7-a24e-d8db0c3b9780
{ "paused": true }

$ qwenpaw cron resume 82cec4cd-d428-4de7-a24e-d8db0c3b9780
{ "resumed": true }

$ qwenpaw cron run 82cec4cd-d428-4de7-a24e-d8db0c3b9780
{ "started": true }

$ qwenpaw cron delete 82cec4cd-d428-4de7-a24e-d8db0c3b9780
{ "deleted": true }

cron list 返回任务数组；agent 型任务用 --request（JSON）替代 --text；--save-result-to-inbox 可把结果落入收件箱。

4.11 qwenpaw chats —— 会话管理

chats list/create/get/update/delete + 消息读取与流式 SSE。新环境实测：

$ qwenpaw chats list
[]

会话按 (channel, user_id, session_id) 唯一标识——正是 cron 的 target 坐标。

4.12 qwenpaw skills —— 技能

list（工作区）/ list --pool（共享池）/ info <name> / enable|disable / install --source zip|url|hub / test <name>。

$ qwenpaw skills list
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

$ qwenpaw skills info pdf
Skill: pdf
Enabled: yes
Channels: all
Source: builtin
Path: /root/.qwenpaw/workspaces/default/skills/pdf
Description: Use this skill whenever the user wants to do anything with PDF files...

技能启用前经安全扫描（block/warn/off，被拦截记录在 skill_scanner_blocked.json）。

4.13 qwenpaw clean —— 清空工作目录

务必先 --dry-run：

$ qwenpaw clean --dry-run
WORKING_DIR: /root/.qwenpaw
Will remove:
  - /root/.qwenpaw/HEARTBEAT.md
  - /root/.qwenpaw/config.json
  - /root/.qwenpaw/plugins
  - /root/.qwenpaw/qwenpaw.log
  - /root/.qwenpaw/skill_pool
  - /root/.qwenpaw/skill_scanner_blocked.json
  - /root/.qwenpaw/token_usage.json
  - /root/.qwenpaw/workspaces
Will keep: .telemetry_collected
dry-run: nothing deleted.

不带 --dry-run 即真删（含记忆与会话历史！），secret 目录不在其列。

4.14 qwenpaw shutdown —— 强制停止服务

正常路径（实测）：

$ qwenpaw shutdown
Backend listener processes (1 total):
  PID 5191: /opt/qp-venv/bin/python3 /opt/qp-venv/bin/qwenpaw app
Frontend development processes: nothing to stop
Desktop wrapper processes: nothing to stop
Related wrapper processes: nothing to stop
Stopped QwenPaw processes: 5191

排障实录：在一台最小化系统上，服务明明在跑（curl 200），shutdown 却报：

Backend listener processes: nothing to stop
...
Error: No running QwenPaw backend/frontend process was found.

读源码定位：shutdown 在 Linux 上通过 lsof -t -i TCP:<port> -sTCP:LISTEN（回退 fuser）找监听 PID——两个工具都没装时就什么都"找不到"。修复与验证：

$ apt-get install -y lsof
$ qwenpaw shutdown
Backend listener processes (1 total):
  PID 5191: ...
Stopped QwenPaw processes: 5191
$ curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:8088/
000   # 端口已释放

⚠️ 补充：个别场景（进程由已断开的会话托管）会报 Failed to stop PID(s) 但进程实际已退出、端口已释放——以 ps/curl/daemon logs（看到 Application shutdown complete）为准，不要盲目重复执行。

4.15 auth / update / uninstall / plugin / hub（速览）

qwenpaw auth reset-password：控制台启用认证后重置管理员密码（交互式）。
qwenpaw update：在当前 Python 环境自升级（支持 --extras 保留附加依赖、--stable/--pre 选道、--self-update-python 连 Python 一起换）。
qwenpaw uninstall：删环境、CLI 包装与 PATH 注入，--working-dir/--secret-dir 可一并清除数据（危险，先 dry 确认提示）。
qwenpaw plugin list：插件列表（实测空环境输出 No plugins installed.）。
qwenpaw hub：多用户 Hub 控制面（进阶形态，本文不展开）。

五、注意事项

单 worker 设计：app --workers 已废弃，勿写进服务单元。
API 类命令依赖服务在线：agents/chats/cron/channels/skills 多数走 HTTP；未启动时报 ConnectError 堆栈。
非交互初始化：init --defaults 必须配 --accept-security。
寻址：跨机管理用 --host/--port 全局项覆盖 last_api。
--agent-id 贯穿：daemon/channels/cron 等默认作用于 default 智能体。
clean 与 uninstall 不可逆：先 --dry-run，并与 secret 目录备份联动。
诊断优先：出问题先 qwenpaw doctor（只读），修复走 doctor fix --dry-run 预览。

六、常见问题

Q1：`init --defaults` 在脚本里 `Aborted!`？

非 TTY 无法应答安全须知。加 --accept-security（实测通过）。

Q2：`agents list` 打一长串 Traceback？

httpcore.ConnectError: Connection refused——服务没起。这类命令全部经 HTTP API，先 qwenpaw app（或确认 --host/--port 指对）。

Q3：`shutdown` 说找不到进程，但服务还在响应？

最小化系统缺 lsof/fuser。安装 lsof 后重试（完整排障见 4.14）。

Q4：`shutdown` 报 `Failed to stop PID(s)` 要不要再执行一次？

先验证：curl 端口应拒绝连接、qwenpaw daemon logs -n 20 应出现 Application shutdown complete。已退出就不要重复执行；确实残留再手工 kill。

Q5：`cron run` 后频道没收到消息？

run 返回 {"started": true} 仅表示已触发；text 任务投递依赖 target (channel,user,session) 在对应频道真实存在。console 频道消息只在 Web 控制台会话可见。

Q6：如何把 CLI 指到另一台机器的服务？

qwenpaw --host 10.0.0.5 --port 8088 agents list；同时确认远端 app 以 --host 0.0.0.0 监听并启用认证（QWENPAW_AUTH_ENABLED）。

七、参考链接

官方 CLI 文档：https://qwenpaw.agentscope.io/docs/cli.zh.md
官方配置文档：https://qwenpaw.agentscope.io/docs/config.zh.md
官方 FAQ：https://qwenpaw.agentscope.io/docs/faq.zh.md
GitHub 仓库：https://github.com/agentscope-ai/QwenPaw
站内：《Copaw 2.2.2 介绍与选型指南》、《Copaw 2.2.2 Docker Compose 部署指南》、《Copaw 2.2.2 配置参数详解》

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

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

一、环境信息

二、工具概览

三、前置条件

四、各命令详解

4.1 qwenpaw init —— 初始化工作目录

4.2 qwenpaw app —— 启动服务

4.3 tui / desktop / task / acp —— 特殊运行形态

4.4 qwenpaw daemon —— 运行状态巡检（全部本地可用）

4.5 qwenpaw doctor —— 只读体检

4.6 qwenpaw models —— 模型提供商

4.7 qwenpaw env —— 工具环境变量

4.8 qwenpaw channels —— 频道

4.9 qwenpaw agents —— 多智能体

4.10 qwenpaw cron —— 定时任务

4.11 qwenpaw chats —— 会话管理

4.12 qwenpaw skills —— 技能

4.13 qwenpaw clean —— 清空工作目录

4.14 qwenpaw shutdown —— 强制停止服务

4.15 auth / update / uninstall / plugin / hub（速览）

五、注意事项

六、常见问题

Q1：init --defaults 在脚本里 Aborted!？

Q2：agents list 打一长串 Traceback？

Q3：shutdown 说找不到进程，但服务还在响应？

Q4：shutdown 报 Failed to stop PID(s) 要不要再执行一次？

Q5：cron run 后频道没收到消息？

Q6：如何把 CLI 指到另一台机器的服务？

七、参考链接

Q1：`init --defaults` 在脚本里 `Aborted!`？

Q2：`agents list` 打一长串 Traceback？

Q3：`shutdown` 说找不到进程，但服务还在响应？

Q4：`shutdown` 报 `Failed to stop PID(s)` 要不要再执行一次？

Q5：`cron run` 后频道没收到消息？