Copaw 2.2.2 Docker Compose 部署指南

目标：在 Linux 服务器上用 Docker Compose 把 Copaw（现名 QwenPaw）个人 AI 助手从 0 部署到可登录状态，覆盖镜像选型、三卷持久化、登录认证、进程结构、等价 docker run 与日常运维命令。全部命令与回显均为 2026-11-03 实测照抄，版本 v2.2.2.post1。

一、环境信息

项目	值
宿主系统	Linux x86_64（内存 16 GiB，磁盘可用约 90 GiB）
Docker	29.9.2（build a82e528）
Docker Compose	v5.6.1
组件版本	agentscope/qwenpaw:v2.2.2.post1（PyPI 最新稳定版，镜像发布于 2026-10-22）
对外端口	`127.0.0.1:8129`（宿主端口，映射容器 8088；实验槽位 8128-8152 内取空闲值）
部署目录	`/opt/data/quzuo/tmp/copaw/compose/`（本文示例用 `/opt/qwenpaw/` 作通用路径）
演示账号	admin / q1w2e3r4（开启认证时经环境变量自动注册）

💡 提示：Copaw 已更名为 QwenPaw，镜像、容器内目录、CLI 全部使用新名 qwenpaw；背景见《Copaw 2.2.2 介绍与选型指南》开头更名说明。

二、镜像选型说明

官方镜像发布在 Docker Hub agentscope/qwenpaw，tag 策略如下（官方快速开始文档口径）：

tag	含义	建议
`latest`	跟随最新稳定版	生产可用，但升级时内容会变，建议配合固定版本号
`v2.2.2.post1`	具体版本号标签	推荐，可复现部署
`pre`	PyPI 预发布版	尝鲜用，勿上生产

国内拉取可切换阿里云 ACR：agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw（tag 相同）。

镜像体积实测 4.35 GB：

$ docker compose images
CONTAINER           REPOSITORY           TAG                 PLATFORM            IMAGE ID            SIZE                CREATED
copaw-2.2.2-web     agentscope/qwenpaw   v2.2.2.post1        linux/amd64         a1e93b221dbb        4.35GB              11 days ago

体积大的原因：镜像是「全家桶」——除 Python 服务外还内置 Xvfb 虚拟显示 + XFCE 桌面环境，为浏览器自动化类技能提供图形栈。运行期内存占用实测约 774 MiB（docker stats 空闲态）：

$ docker stats --no-stream copaw-2.2.2-web
7d61319f716a   copaw-2.2.2-web   22.96%   773.8MiB / 15.57GiB   4.85%   3.5kB / 40kB   327MB / 61.4kB   147

三、前置条件

Docker 与 Compose 插件可用：docker info 正常输出；
磁盘余量 ≥ 15 GB（镜像 4.35 GB + 三卷数据增长）；
选定宿主端口并确认空闲（本文用 8129）：

$ ss -ltn | grep -E ':8129\b' || echo "8129 free"
8129 free

已规划数据目录（bind mount 方式）或接受命名卷（named volume）方式。

四、部署步骤

4.1 编写 compose 文件

官方仓库根目录自带 docker-compose.yml（命名卷版，见 4.5 节对照）。本文采用 bind mount 版，便于直接在宿主查看/修改配置与日志：

# /opt/qwenpaw/docker-compose.yml
name: copaw-2.2.2-stack

services:
  qwenpaw:
    image: agentscope/qwenpaw:v2.2.2.post1
    container_name: copaw-2.2.2-web
    init: true
    restart: unless-stopped
    ports:
      - "127.0.0.1:8129:8088"
    environment:
      - QWENPAW_AUTH_ENABLED=true
      - QWENPAW_AUTH_USERNAME=admin
      - QWENPAW_AUTH_PASSWORD=q1w2e3r4
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/app/working
      - ./secrets:/app/working.secret
      - ./backups:/app/working.backups

要点：init: true 由官方 compose 保留（PID 1 收尸）；ports 显式绑 127.0.0.1 避免控制台裸奔公网；三卷路径是镜像内固定约定，不可改映射目标。

4.2 拉取镜像

$ docker pull agentscope/qwenpaw:v2.2.2.post1
...
a16d7ef8f525: Pull complete
02916587f7fd: Pull complete
Digest: sha256:a1e93b221dbb8f0826f7294dd3fa1df9e804000d7564272f113e29c13929de32
Status: Downloaded newer image for agentscope/qwenpaw:v2.2.2.post1
docker.io/agentscope/qwenpaw:v2.2.2.post1

4.3 启动

$ mkdir -p data secrets backups
$ docker compose up -d
 Network copaw-222-stack_default Creating
 Network copaw-222-stack_default Created
 Container copaw-2.2.2-web Creating
 Container copaw-2.2.2-web Created
 Container copaw-2.2.2-web Starting
 Container copaw-2.2.2-web Started

$ docker compose ps
NAME              IMAGE                             COMMAND                  SERVICE   CREATED         STATUS         PORTS
copaw-2.2.2-web   agentscope/qwenpaw:v2.2.2.post1   "docker-entrypoint.s…"   qwenpaw   5 seconds ago   Up 3 seconds   127.0.0.1:8129->8088/tcp

注意 compose 对栈名的规范化：copaw-2.2.2-stack 中的点被剥掉，网络实际叫 copaw-222-stack_default。

4.4 首次初始化与验证

首次启动时镜像入口脚本会自动完成初始化（等效 qwenpaw init --defaults，含技能安全扫描与人设文件落盘），日志节选：

$ docker compose logs --tail 20
copaw-2.2.2-web  | INFO ... skill_scanner/scanner.py:235 | Scan of 'xlsx' completed in 0.09s – 0 finding(s), safe=True
copaw-2.2.2-web  | ✓ 16 new skill(s) enabled.
copaw-2.2.2-web  | Checking MD files [language: zh]...
copaw-2.2.2-web  | ✓ Copied 8 md file(s): CONTACTS.md, BOOTSTRAP.md, HEARTBEAT.md, AGENTS.md, SOUL.md, PROFILE.md, MAIL_TRIAGE.md, MEMORY.md
copaw-2.2.2-web  | ✓ Heartbeat query saved to /app/working/HEARTBEAT.md
copaw-2.2.2-web  | ✓ Initialization complete!
copaw-2.2.2-web  | ✅ Initialization complete!
copaw-2.2.2-web  | 2026-11-03 12:00:42,425 INFO supervisord started with pid 7
copaw-2.2.2-web  | 2026-11-03 12:00:43,428 INFO spawned: 'xvfb' with pid 55
copaw-2.2.2-web  | 2026-11-03 12:00:43,430 INFO spawned: 'xfce4' with pid 56
copaw-2.2.2-web  | 2026-11-03 12:00:43,431 INFO spawned: 'app' with pid 57
copaw-2.2.2-web  | 2026-11-03 12:00:43,432 INFO spawned: 'dbus' with pid 59
copaw-2.2.2-web  | 2026-11-03 12:00:44,513 INFO success: xvfb entered RUNNING state ...

进程树印证「supervisord 托管图形栈 + 应用」的结构：

$ docker compose top | head -7
SERVICE  #   UID   PID      PPID    C   STIME  TTY  TIME      CMD
qwenpaw  1   root  932900   ...     0   12:00  ?    00:00:00  /sbin/docker-init -- docker-entrypoint.sh /entrypoint.sh
qwenpaw  1   root  932968   ...     0   12:00  ?    00:00:00  /usr/bin/python3 /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf
qwenpaw  1   root  933443   ...     0   12:00  ?    00:00:00  /usr/bin/Xvfb :1 -screen 0 1280x800x24
qwenpaw  1   root  933444   ...     0   12:00  ?    00:00:00  dbus-run-session startxfce4
qwenpaw  1   root  933445   ...    13   12:00  ?    00:00:09  /app/venv/bin/python /app/venv/bin/qwenpaw app --host 0.0.0.0 --port 8088

启动约 10 秒后验证控制台可达：

$ curl -sS -i http://127.0.0.1:8129/ | head -12
HTTP/1.1 200 OK
server: uvicorn
content-type: text/html; charset=utf-8
content-length: 38125
...
<!doctype html>
<html lang="en">
  <head>
    <title>QwenPaw Console</title>

浏览器打开 http://<宿主IP不可达，需SSH隧道>:8129/（端口只绑 127.0.0.1，远程访问建议 ssh -L 8129:127.0.0.1:8129 user@server 后本地访问 http://127.0.0.1:8129/），用演示账号 admin / q1w2e3r4 登录。开启认证后未登录调 API 会被拒：

$ curl -sS http://127.0.0.1:8129/api/agents
{"detail":"Not authenticated"}
$ curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8129/api/agents
401

进控制台后最后一步：设置 → 模型，配置任一 LLM 提供商的 API Key（或下载本地模型），否则助手不会回复。

4.5 与官方 compose 的对照

官方仓库根目录 docker-compose.yml 使用命名卷 + latest + restart: always，认证环境变量默认注释：

version: '3.8'
volumes:
  qwenpaw-data:
    name: qwenpaw-data
  qwenpaw-secrets:
    name: qwenpaw-secrets
  qwenpaw-backups:
    name: qwenpaw-backups
services:
  qwenpaw:
    image: agentscope/qwenpaw:latest
    init: true
    container_name: qwenpaw
    restart: always
    ports:
      - "127.0.0.1:8088:8088"
    volumes:
      - qwenpaw-data:/app/working
      - qwenpaw-secrets:/app/working.secret
      - qwenpaw-backups:/app/working.backups

两种方式的取舍：命名卷隔离性好、down 不误删数据（需 -v 才删）；bind mount 便于直接编辑配置、看日志、做宿主侧备份。功能完全等价。

五、数据持久化

三个挂载点各司其职（容器内路径固定）：

容器内路径	内容	宿主侧（bind 方式）
`/app/working`	工作目录：`config.json`、`workspaces/{agent_id}/`、`skill_pool/`、`qwenpaw.log`、`HEARTBEAT.md`、`plugins/`	`./data`
`/app/working.secret`	敏感数据：`auth.json`（登录用户）、`.master_key`（主密钥）、`providers/`（提供商配置与 Key）	`./secrets`
`/app/working.backups`	备份归档	`./backups`

首次启动后实测落盘结构：

$ ls -la data/
total 88
-rw-------  1 root root 32125 config.json
-rw-r--r--  1 root root   145 HEARTBEAT.md
drwxr-xr-x  6 root root  4096 plugins
-rw-r--r--  1 root root 21252 qwenpaw.log
drwxr-xr-x 18 root root  4096 skill_pool
-rw-r--r--  1 root root  1228 skill_scanner_blocked.json
-rw-------  1 root root   167 .telemetry_collected
drwxr-xr-x  4 root root  4096 workspaces

$ ls -la secrets/
-rw------- 1 root root 397 auth.json
-rw------- 1 root root  64 .master_key
drwx------ 5 root root 4096 providers

workspaces/ 下自动生成 default（默认智能体）与 QwenPaw_QA_Agent_0.2（内置 QA 智能体）两个工作区，各含 agent.json、chats.json、jobs.json、人设 MD 文件与 skills/。

⚠️ 备份提示：迁移或备份时 data 与 secrets 必须一起带走——secrets/.master_key 丢失后，加密保存的 API Key 与环境变量无法恢复。

六、环境变量表

compose environment 段常用变量（完整清单见《Copaw 2.2.2 配置参数详解》第四章）：

变量	默认	说明
`QWENPAW_AUTH_ENABLED`	`false`	是否启用 Web 控制台登录认证
`QWENPAW_AUTH_USERNAME`	-	自动注册的管理员用户名
`QWENPAW_AUTH_PASSWORD`	-	自动注册的管理员密码
`QWENPAW_WORKING_DIR`	`/app/working`	工作目录（镜像内默认已对齐挂载点，一般无需设置）
`QWENPAW_SECRET_DIR`	`/app/working.secret`	敏感数据目录
`QWENPAW_LOG_LEVEL`	`info`	日志级别 debug/info/warning/error/critical
`TZ`	容器默认	建议 `Asia/Shanghai`，影响日志与定时任务默认时区
`DASHSCOPE_API_KEY` 等	-	可在 `docker run`/compose 直传提供商 Key（官方快速开始口径），或启动后在控制台配置
`QWENPAW_TOOL_GUARD_ENABLED`	`true`	工具守卫开关
`QWENPAW_SKILL_SCAN_MODE`	`warn`	技能扫描模式 block/warn/off

七、配置文件挂载与修改

bind mount 方式下，宿主直接改 ./data/config.json 或 ./data/workspaces/default/agent.json 即可：

智能体配置（agent.json）由服务进程以 2 秒轮询自动热加载，无需重启（实测验证见《Copaw 2.2.2 配置参数详解》）；
频道/MCP 结构性变更建议执行 docker compose exec qwenpaw qwenpaw daemon reload-config 或在对话中 /daemon restart；
环境变量类（QWENPAW_LOG_LEVEL、流式超时等）在进程启动时读取，改动需 docker compose up -d 重建。

命名卷方式改配置可用 docker compose cp：

docker compose cp qwenpaw:/app/working/config.json ./config.json
# 编辑后回灌
docker compose cp ./config.json qwenpaw:/app/working/config.json

八、等价 docker run

不用 compose 时，与第四节 compose 完全等价的单命令：

docker run -d --name copaw-2.2.2-web --init --restart unless-stopped \
  -p 127.0.0.1:8129:8088 \
  -e QWENPAW_AUTH_ENABLED=true \
  -e QWENPAW_AUTH_USERNAME=admin \
  -e QWENPAW_AUTH_PASSWORD=q1w2e3r4 \
  -e TZ=Asia/Shanghai \
  -v /opt/qwenpaw/data:/app/working \
  -v /opt/qwenpaw/secrets:/app/working.secret \
  -v /opt/qwenpaw/backups:/app/working.backups \
  agentscope/qwenpaw:v2.2.2.post1

九、常用运维命令

# 状态与端口
docker compose ps

# 实时日志 / 最近 N 行
docker compose logs -f qwenpaw
docker compose logs --tail 100

# 重启（数据无损，实测 8 秒后恢复 200）
docker compose restart

# 进入容器执行 CLI（镜像内 CLI 在 venv 中，入口脚本已处理 PATH）
docker compose exec qwenpaw qwenpaw --version
# QwenPaw, version 2.2.2.post1

docker compose exec qwenpaw qwenpaw daemon status
# Agent: default
# **Daemon Status**
# - Config loaded: yes
# - Max input length: 256000
# - Working dir: /app/working/workspaces/default
# - Memory manager: not attached

# 资源占用
docker stats --no-stream copaw-2.2.2-web

# 升级到新稳定版：改 image tag 后重建
sed -i 's/v2\.2\.2\.post1/v2.3.0/' docker-compose.yml   # 示例
docker compose up -d

# 停止（保留数据）
docker compose down
# 停止并删除数据卷（命名卷方式时！）——数据不可恢复，慎用
docker compose down -v

十、常见问题

10.1 `docker compose up` 后 curl 返回 401/跳登录，是不是没装好？

不是。设置了 QWENPAW_AUTH_ENABLED=true 后 API 即要求登录，属预期行为（实测 {"detail":"Not authenticated"}）。用 compose 里的 admin/q1w2e3r4 登录即可；忘记密码可在容器内执行 qwenpaw auth reset-password。

10.2 首次启动多久才算就绪？

入口脚本先跑初始化（技能扫描 + 人设文件落盘，约 2-5 秒），supervisord 拉起四个进程后 app 才监听 8088。实测 up -d 后约 10 秒 curl http://127.0.0.1:8129/ 返回 200；若更慢，用 docker compose logs 看是否卡在 Initialization complete! 之前。

10.3 国内拉取 Docker Hub 超时怎么办？

按序降级：① 换阿里云 ACR 镜像源 agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw:v2.2.2.post1（tag 与 Docker Hub 相同）；② 给宿主 Docker daemon 配置代理后重试；③ 在可拉取机器上 docker save 导出再传输 docker load。

10.4 8088 端口被占用？

改 ports 左侧宿主端口即可（本文实测即用 8129）："127.0.0.1:8129:8088"，容器内端口不要动。

10.5 想让容器里的助手连宿主机上的 Ollama？

compose 增加：

    extra_hosts:
      - "host.docker.internal:host-gateway"

然后在控制台把 Ollama 提供商 API 地址设为 http://host.docker.internal:11434（官方模型文档口径）。

10.6 镜像为什么 4 GB 多？能瘦身吗？

镜像内置 Xvfb + XFCE 以支撑浏览器类技能。若完全不用浏览器技能可考虑自研精简镜像，但官方未提供 slim 标签，生产建议直接用官方镜像保证行为一致。

十一、参考链接

官方快速开始（Docker 章节）：https://qwenpaw.agentscope.io/docs/quickstart.zh.md
官方仓库（含 docker-compose.yml）：https://github.com/agentscope-ai/QwenPaw
Docker Hub 镜像页：https://hub.docker.com/r/agentscope/qwenpaw
配置与工作目录：https://qwenpaw.agentscope.io/docs/config.zh.md
站内：《Copaw 2.2.2 介绍与选型指南》、《Copaw 2.2.2 配置参数详解》、《Copaw 2.2.2 常用 CLI 命令与工具详解》

Copaw 2.2.2 Docker Compose 部署指南

Copaw 2.2.2 Docker Compose 部署指南

一、环境信息

二、镜像选型说明

三、前置条件

四、部署步骤

4.1 编写 compose 文件

4.2 拉取镜像

4.3 启动

4.4 首次初始化与验证

4.5 与官方 compose 的对照

五、数据持久化

六、环境变量表

七、配置文件挂载与修改

八、等价 docker run

九、常用运维命令

十、常见问题

10.1 docker compose up 后 curl 返回 401/跳登录，是不是没装好？

10.2 首次启动多久才算就绪？

10.3 国内拉取 Docker Hub 超时怎么办？

10.4 8088 端口被占用？

10.5 想让容器里的助手连宿主机上的 Ollama？

10.6 镜像为什么 4 GB 多？能瘦身吗？

十一、参考链接

10.1 `docker compose up` 后 curl 返回 401/跳登录，是不是没装好？