QwenPaw Docker 部署方案

支持一键构建和运行，相比官方镜像更小

QwenPaw（原 CoPaw 项目）是一款个人 AI 助手，部署在你自己的环境中，支持多种聊天平台接入，具备强大的扩展能力。

更多信息请看官方仓库：agentscope-ai/QwenPaw

Note

如果你正在使用旧版 CoPaw 镜像，请参阅如何从 CoPaw 迁移到 QwenPaw 。

⚠️ 安全警告 ⚠️

QwenPaw v0.1.0+ 支持可选的 Web 认证功能。对于 v0.1.0 之前的版本或未启用认证时，切勿将服务端口暴露到公网！

v0.1.0+ Web 认证（推荐启用）

设置 QWENPAW_AUTH_ENABLED=true 启用 Web 认证：

首次访问显示注册页面
本地请求 (127.0.0.1) 自动绕过认证
支持环境变量自动注册（适用于自动化部署）
密码重置：docker compose exec qwenpaw qwenpaw auth reset-password

# 在 .env 文件中启用
QWENPAW_AUTH_ENABLED=true

# 可选：自动注册管理员账户（首次启动时生效）
QWENPAW_AUTH_USERNAME=admin
QWENPAW_AUTH_PASSWORD=your_secure_password

v0.0.x 或未启用认证时，WebUI 管理界面没有登录验证机制，任何能访问该端口的人都可以完全控制你的 QwenPaw 实例。点击展开安全建议。

默认端口 8088 仅应在受信任的内网环境或通过反向代理 + 认证等方式访问
如果必须远程访问，请使用以下安全措施之一：
- 通过 SSH 隧道访问：ssh -L 8088:localhost:8088 your-server
- 配置 Nginx/Caddy 等反向代理并添加 Basic Auth 或 OAuth 认证
- 使用防火墙限制访问来源 IP

快速开始

前置要求

Docker >= 20.10
Docker Compose >= 2.0

使用方式选择

方式一：快速体验

最简单的方式，直接使用 docker run 命令启动，适合快速体验。

docker run -d --name qwenpaw \
  -p 127.0.0.1:8088:8088 \
  -v copaw-data:/data/qwenpaw \
  --restart unless-stopped \
  ghcr.io/log-z/qwenpaw:latest

访问控制台：http://localhost:8088

方式二：使用 Docker Compose（推荐✨）

使用 Docker Compose 方便管理和配置。

1. （可选）配置环境变量

如需提前配置 API Keys，可复制环境变量示例文件：

cp .env.example .env

编辑 .env 文件填入你的配置。也可以在应用启动后通过 Web UI 进行配置。

2. 拉取并启动服务

docker compose pull      # 拉取或更新镜像
docker compose up -d     # 后台启动服务

3. 查看日志

docker compose logs -f qwenpaw

4. 访问控制台

浏览器打开：http://localhost:8088

方式三：自行构建镜像

如果需要自定义镜像或预构建镜像不可用，可以自行构建。

1. （可选）配置环境变量

同方式二。

2. 修改 docker-compose.yml

编辑 docker-compose.yml，注释掉预构建镜像配置，取消注释构建配置：

qwenpaw:
  # image: ghcr.io/log-z/qwenpaw:latest  # 注释预构建镜像
  build:                                 # 取消注释构建配置
    context: .
    dockerfile: Dockerfile
  image: qwenpaw:latest

3. 构建镜像

docker compose build

4. 启动服务、查看日志、访问控制台

同方式二。

项目结构

copaw-docker/
├── .github/
│   └── workflows/
│       ├── dev-test.yml       # 开发环境测试工作流
│       ├── prod-test.yml      # 生产环境测试工作流
│       ├── release-image.yml  # 发布镜像工作流
│       └── trivy-scan.yml     # Trivy 漏洞扫描工作流
├── docs/
│   └── qwenpaw-info.md        # QwenPaw 官方文档信息汇总
├── scripts/
│   ├── entrypoint.sh          # 容器启动脚本（自动初始化检查）
│   ├── healthcheck.sh         # 健康检查脚本（Docker HEALTHCHECK）
│   └── test-startup.sh        # 启动流程测试脚本
├── .dockerignore              # Docker 构建忽略文件
├── .env.example               # 环境变量配置示例
├── .gitattributes             # Git 属性配置
├── .gitignore                 # Git 忽略文件配置
├── CLAUDE.md                  # Claude Code 工作指引
├── Dockerfile                 # 多阶段构建的 Docker 镜像定义
├── LICENSE                    # 开源许可证
├── README.md                  # 本文件
├── docker-compose.override.yml # Docker Compose 覆盖配置
└── docker-compose.yml         # Docker Compose 编排配置

数据卷结构（运行时生成）

copaw-data:/
├── qwenpaw.secret -> qwenpaw/.runtime    # 软链接指向 .runtime（兼容 SECRET_DIR）
└── qwenpaw/
    ├── .runtime/              # 敏感配置目录
    │   ├── auth.json          # Web 认证数据（v0.1.0+）
    │   ├── envs.json          # 环境变量配置
    │   └── providers.json     # LLM 提供商配置
    ├── custom_channels/       # 用户自定义频道模块
    ├── mcp_clients/           # MCP 客户端配置
    ├── memory/                # Agent 记忆文件存储（含每日日志）
    ├── workspaces/            # 多代理工作区目录（v0.1.0+）
    │   └── default/           # 默认代理工作区
    │       ├── active_skills/ # 当前激活的技能
    │       ├── customized_skills/ # 用户自定义技能
    │       ├── plugins/       # 插件扩展（v1.0.2+）
    │       ├── AGENTS.md      # 详细工作流程与指南（必填）
    │       ├── PROFILE.md     # 身份和用户画像
    │       ├── SOUL.md        # Agent 核心身份与行为原则（必填）
    │       └── agent.json     # 代理配置
    ├── chats.json             # 会话列表
    ├── config.json            # 根配置文件（包含代理引用，v0.1.0+）
    ├── HEARTBEAT.md           # 心跳任务配置
    └── jobs.json              # 定时任务列表

v0.1.0 多工作区迁移：现有配置会在首次启动时自动迁移到新的多工作区架构。

常用命令

容器管理

# 启动服务
docker compose up -d

# 停止服务
docker compose stop

# 重启服务
docker compose restart

# 查看日志
docker compose logs -f qwenpaw

# 进入容器
docker compose exec qwenpaw bash

# 停止并删除容器
docker compose down

数据管理

# 查看数据卷
docker volume inspect copaw-data

# 备份数据
docker run --rm -v copaw-data:/data -v $(pwd):/backup \
    alpine tar czf /backup/qwenpaw-backup-$(date +%Y%m%d).tar.gz -C /data .

# 恢复数据
docker run --rm -v copaw-data:/data -v $(pwd):/backup \
    alpine tar xzf /backup/qwenpaw-backup-YYYYMMDD.tar.gz -C /data

QwenPaw 命令（在容器内执行）

# 初始化
docker compose exec qwenpaw qwenpaw init --defaults   # 默认配置（不交互）
docker compose exec qwenpaw qwenpaw init              # 交互式初始化

# 模型管理（云端提供商）
docker compose exec qwenpaw qwenpaw models list                    # 查看所有提供商
docker compose exec qwenpaw qwenpaw models config                  # 交互式配置
docker compose exec qwenpaw qwenpaw models config-key modelscope   # 配置 ModelScope API Key
docker compose exec qwenpaw qwenpaw models config-key dashscope    # 配置 DashScope API Key
docker compose exec qwenpaw qwenpaw models config-key anthropic    # 配置 Anthropic API Key（v0.0.5+）
docker compose exec qwenpaw qwenpaw models config-key gemini       # 配置 Gemini API Key（v0.0.6+）
docker compose exec qwenpaw qwenpaw models config-key lmstudio     # 配置 LM Studio（v0.0.7+）
docker compose exec qwenpaw qwenpaw models config-key deepseek     # 配置 DeepSeek（v0.1.0+）
docker compose exec qwenpaw qwenpaw models config-key minimax      # 配置 MiniMax（v0.1.0+）
docker compose exec qwenpaw qwenpaw models config-key kimi         # 配置 Kimi（v0.1.0+）
docker compose exec qwenpaw qwenpaw models config-key zhipu        # 配置智谱（v1.0.1+）
docker compose exec qwenpaw qwenpaw models config-key siliconflow  # 配置 SiliconFlow（v1.0.2+）
docker compose exec qwenpaw qwenpaw models config-key openrouter   # 配置 OpenRouter（v1.1.1+）
docker compose exec qwenpaw qwenpaw models config-key opencode     # 配置 OpenCode/Zen（v1.1.1+）
docker compose exec qwenpaw qwenpaw models config-key custom       # 配置自定义提供商
docker compose exec qwenpaw qwenpaw models set-llm                 # 切换活跃模型

# 模型管理（本地模型 - 需额外依赖）
docker compose exec qwenpaw qwenpaw models download <repo_id>      # 下载本地模型 (llama.cpp/MLX)
docker compose exec qwenpaw qwenpaw models local                   # 查看已下载模型
docker compose exec qwenpaw qwenpaw models remove-local <model_id> # 删除已下载模型
docker compose exec qwenpaw qwenpaw models ollama-pull <model>     # 拉取 Ollama 模型
docker compose exec qwenpaw qwenpaw models ollama-list             # 列出 Ollama 模型

# 频道管理
docker compose exec qwenpaw qwenpaw channels list           # 查看所有频道
docker compose exec qwenpaw qwenpaw channels config         # 交互式配置
docker compose exec qwenpaw qwenpaw channels install <key>  # 安装自定义频道
docker compose exec qwenpaw qwenpaw channels add <key>      # 添加频道到配置
docker compose exec qwenpaw qwenpaw channels remove <key>   # 删除自定义频道

# 技能管理
docker compose exec qwenpaw qwenpaw skills list         # 查看所有技能
docker compose exec qwenpaw qwenpaw skills config       # 交互式启用/禁用

# 定时任务
docker compose exec qwenpaw qwenpaw cron list            # 列出所有任务
docker compose exec qwenpaw qwenpaw cron create ...      # 创建任务
docker compose exec qwenpaw qwenpaw cron state <job_id>  # 查看任务状态
docker compose exec qwenpaw qwenpaw cron pause <job_id>  # 暂停任务
docker compose exec qwenpaw qwenpaw cron resume <job_id> # 恢复任务
docker compose exec qwenpaw qwenpaw cron run <job_id>    # 立即执行一次

# 环境变量
docker compose exec qwenpaw qwenpaw env list            # 列出所有变量
docker compose exec qwenpaw qwenpaw env set KEY VALUE   # 设置变量
docker compose exec qwenpaw qwenpaw env delete KEY      # 删除变量

# 会话管理
docker compose exec qwenpaw qwenpaw chats list          # 列出所有会话
docker compose exec qwenpaw qwenpaw chats get <id>      # 查看会话详情
docker compose exec qwenpaw qwenpaw chats create ...    # 创建新会话
docker compose exec qwenpaw qwenpaw chats update <id> --name "新名称"  # 重命名会话
docker compose exec qwenpaw qwenpaw chats delete <id>   # 删除会话

# 维护
docker compose exec qwenpaw qwenpaw clean               # 清空工作目录（交互确认）
docker compose exec qwenpaw qwenpaw clean --yes         # 不确认直接清空

# 配置重载（无需重启容器，v0.0.5+）
docker compose exec qwenpaw qwenpaw daemon reload-config # 重新加载配置
docker compose exec qwenpaw qwenpaw daemon version       # 查看 QwenPaw 版本

# 更新与认证（v0.1.0+）
docker compose exec qwenpaw qwenpaw update              # 更新 QwenPaw 到最新版本（在容器中更新无意义）
docker compose exec qwenpaw qwenpaw auth reset-password # 重置 Web UI 密码

# Agent 与消息（v0.2.0+）
docker compose exec qwenpaw qwenpaw agents list            # 列出所有代理
docker compose exec qwenpaw qwenpaw agents enable <agent>  # 启用代理（v1.0.0+）
docker compose exec qwenpaw qwenpaw agents disable <agent> # 禁用代理（v1.0.0+）
docker compose exec qwenpaw qwenpaw message push           # 向频道推送消息
docker compose exec qwenpaw qwenpaw message send           # 向代理发送请求

# 任务执行（v1.0.2+）
docker compose exec qwenpaw qwenpaw task <prompt>      # 运行一次性任务，无需 Web 服务

环境变量说明

完整的环境变量列表及说明请参见 .env.example 。

注意：模型提供商的 API Key 不支持通过环境变量配置，需通过以下方式设置：

WebUI 控制台 → Settings → Models

CLI 命令：docker compose exec qwenpaw qwenpaw models config

数据持久化

⚠️ 重要提示：本项目的 copaw-data 存储卷与 QwenPaw 官方镜像的存储卷不能通用，原因是文件权限设置不一致。官方镜像可能使用不同的用户权限运行，直接挂载可能导致权限问题。

本项目使用 Docker 数据卷 copaw-data 持久化以下内容：

.runtime/ - 敏感配置目录
- auth.json - Web 认证数据（v0.1.0+）
- envs.json - 环境变量配置
- providers.json - LLM 提供商配置
custom_channels/ - 用户自定义频道模块
memory/ - Agent 记忆文件
workspaces/default/ - 默认代理工作区（v0.1.0+）
- active_skills/ - 当前激活的技能
- customized_skills/ - 用户自定义技能
- plugins/ - 插件扩展（v1.0.2+）
- AGENTS.md - 详细的工作流程、规则和指南
- PROFILE.md - 身份和用户画像
- SOUL.md - 核心身份与行为原则
- agent.json - 代理配置
chats.json - 会话列表
config.json - 根配置文件（包含代理引用，v0.1.0+）
HEARTBEAT.md - 心跳配置
jobs.json - 定时任务列表

容器重启后，所有数据都会保留。

v0.1.0 多工作区迁移：现有配置会在首次启动时自动迁移到新的多工作区架构。

多模态消息支持

各频道对不同消息类型的支持情况：

频道	接收文本	接收图片	接收视频	接收音频	接收文件	发送文本	发送图片	发送视频	发送音频	发送文件
钉钉	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
飞书	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
企业微信	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
微信 iLink	🚧	🚧	🚧	🚧	🚧	🚧	🚧	🚧	🚧	🚧
OneBot v11 / NapCat (v1.0.1+)	✓	✓	✓	✓	✓	✓	✓	✓	🚧	🚧
Discord	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
iMessage	✓	✓	✓	✓	✗	✓	✓	✓	✓	✗
QQ	✓	✓	✓	✓	✓	✓	✓	🚧	🚧	✓ (v1.0.2+)
Telegram	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
Twilio Voice	✓	✗	✗	✓	✗	✓	✗	✗	✓	✗
MQTT	✓	✗	✗	✗	✗	✓	✗	✗	✗	✗
Mattermost	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
Matrix	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
小艺	✓	✓	✓	✗	✓	✓	✓	✗	✗	✓

✓ = 已支持；🚧 = 施工中；✗ = 不支持

端口说明

⚠️ 安全提醒：v0.1.0 之前或未启用认证时，请勿将端口暴露到公网！环境变量启用 QWENPAW_AUTH_ENABLED=true 后可降低风险。

容器端口	主机端口	说明
`8088`	`127.0.0.1:8088`	QwenPaw Web 服务端口（v0.0.5+ 默认绑定 127.0.0.1）

如需修改主机端口，编辑 docker-compose.yml：

ports:
  - "9000:8088"  # 使用 9000 端口访问
  # 或 v0.1.0+ 启用认证后允许外部访问
  # - "0.0.0.0:8088:8088"

安全更新：v0.0.5 起，默认端口绑定改为 127.0.0.1 以提高安全性。v0.1.0+ 启用认证后可降低风险。

网络配置

默认使用 qwenpaw-network 桥接网络。如需连接其他容器，可以：

# 在 docker-compose.yml 中添加外部网络
networks:
  qwenpaw-network:
    name: your-existing-network
    external: true

故障排除

1. 容器无法启动

检查日志：

docker compose logs qwenpaw

2. 健康检查失败

检查服务是否正常运行：

docker compose ps
curl http://localhost:8088/

3. 数据丢失

数据存储在 Docker 卷中，除非手动删除卷，否则不会丢失。

检查卷状态：

docker volume ls | grep qwenpaw

4. API Key 无效

确保 .env 文件中的 API Key 正确，并重启服务：

docker compose restart

镜像信息

预构建镜像

镜像地址: ghcr.io/log-z/qwenpaw:latest
拉取命令: docker pull ghcr.io/log-z/qwenpaw:latest
更新频率: 随 QwenPaw 官方版本更新

自行构建

基础镜像: python:3.13-slim
Python 版本: 3.13
Node.js 版本: 24.x LTS（用于 MCP 功能）
工作目录: /data/qwenpaw
运行用户: qwenpaw（非 root）

新功能支持

历史版本更新详见 docs/qwenpaw-info.md。

v1.1.1 更新（最新）

新功能

OpenRouter 提供商 - 内置 OpenRouter，支持模型发现、系列浏览、按模态和价格筛选
OpenCode (Zen) 提供商 - 内置 OpenAI 兼容提供商，提供免费模型
模型 ID 自动补全 - 添加模型时自动补全模型 ID，默认启用模型发现
内置 Agent 协作工具 - list_agents 和 chat_with_agent 工具，支持 Agent 间通信
Matrix 频道重写 - 端到端加密 (E2EE)、@提及处理、消息历史、Markdown 渲染
飞书引用消息 - 回复链消息处理，支持文本、帖子、图片和文件内容提取
钉钉 QR 认证 - 控制台钉钉频道设置支持二维码设备流认证
扩展 Shell 命令防护 - 新增 $IFS 注入、控制字符、Unicode 空白字符等防护规则
ClawHub 技能需求格式 - 支持 ClawHub 格式的技能需求
媒体 URL 直接查看 - view_image 和 view_video 支持 HTTP/HTTPS URL

优化

多模态探测统一（Anthropic/Gemini/OpenAI 共享评估路径）
切换模型提供商时保留媒体附件
钉钉迁移至阿里云官方 SDK
飞书 WebSocket 重连稳定性改进
浏览器默认启动策略改为托管 CDP
模型管理 UI 重设计（能力标签、搜索、卡片布局）
Agent 配置页面重构为标签页界面
技能选择 UI 改进（标签建议、批量操作）

Bug 修复

QQ WebSocket 关闭不再阻塞 8 秒
修复 Windows 本地模型下载失败
vLLM 兼容性：省略 tool_choice=auto 避免 400 错误

控制台功能

服务启动后访问 http://localhost:8088/ 进入控制台，包含以下功能模块：

组	功能	说明
聊天	聊天	和 QwenPaw 对话、管理会话、切换模型、多模态支持、SSE 流式响应、音视频支持（v0.2.0+）、多模态预览（v1.0.0+）、频道标签（v1.0.0+）、命令建议（v1.0.0+）、选择 Agent 对话（v1.0.0.post1+）、聊天搜索（v1.0.2+）、置顶会话（v1.0.2+）、输入历史（v1.0.2+）
控制	频道	启用/禁用频道、填入凭据、快速文档链接、飞书区域选择器（v0.2.0+）
控制	会话	筛选、重命名、删除会话
控制	定时任务	创建/编辑/删除任务、立即执行
智能体	工作区	编辑人设文件、查看记忆、上传/下载、代理选择器、标签页界面（v1.1.1+）
智能体	技能	启用/禁用/创建/导入/AI优化/删除技能、安全扫描、Skill Pool 双层架构（v1.0.0+）、技能命令 `/<skill>` （v1.0.2+）、技能池标签（v1.0.2+）、技能选择改进（v1.1.1+）
智能体	MCP	启用/禁用/创建/删除 MCP 客户端、控制台 MCP 配置（v1.0.0.post2+）、MCP 工具发现（v1.0.2+）
智能体	运行配置	修改最大迭代次数和最大输入长度、LLM 重试配置（v0.2.0+）
智能体	上下文管理	调整压缩比例、保留比例、工具结果压缩设置
智能体	工具	启用/禁用内置工具、批量切换、glob_search/grep_search
设置	模型	配置提供商（含自定义提供商）、管理本地/Ollama/LM Studio 模型、选择模型、搜索过滤（v0.2.0+）、QwenPaw Local Model（v1.0.0+）、视频分析（v1.0.0.post1+）、`/model` 聊天命令（v1.0.2+）、模型 ID 自动补全（v1.1.1+）
设置	环境变量	添加/编辑/删除环境变量（敏感值遮罩）
设置	安全	Tool Guard 安全规则管理、文件访问保护（v0.2.0+）、系统重启/服务保护（v1.0.0+）、中文提示注入检测（v1.0.0+）、扩展 Shell 命令防护（v1.1.1+）
设置	Token 使用	追踪各提供商 token 使用量
设置	语音转录	语音转录设置
设置	主题	暗黑模式切换
设置	账户	更改用户名密码（v0.2.0+，认证启用时）

Skills Hub 导入：支持从社区平台导入技能

https://skills.sh/...
https://clawhub.ai/...
https://skillsmp.com/...
https://github.com/...
LobeHub
ModelScope Skill Hub

License

本项目基于 QwenPaw 的官方部署方案构建。QwenPaw 由 AgentScope 团队开发，采用 Apache License 2.0 开源许可。

Name		Name	Last commit message	Last commit date
Latest commit History 88 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

QwenPaw Docker 部署方案

⚠️ 安全警告 ⚠️

快速开始

前置要求

使用方式选择

方式一：快速体验

方式二：使用 Docker Compose（推荐✨）

1. （可选）配置环境变量

2. 拉取并启动服务

3. 查看日志

4. 访问控制台

方式三：自行构建镜像

1. （可选）配置环境变量

2. 修改 docker-compose.yml

3. 构建镜像

4. 启动服务、查看日志、访问控制台

项目结构

数据卷结构（运行时生成）

常用命令

容器管理

数据管理

QwenPaw 命令（在容器内执行）

环境变量说明

数据持久化

多模态消息支持

端口说明

网络配置

故障排除

1. 容器无法启动

2. 健康检查失败

3. 数据丢失

4. API Key 无效

镜像信息

预构建镜像

自行构建

新功能支持

v1.1.1 更新（最新）

新功能

优化

Bug 修复

控制台功能

相关链接

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 21

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages