CoPaw 更名 QwenPaw 后怎么装：pip init 两步上线，8088 端口搭起多模型个人助理

CoPaw 更名 QwenPaw：为什么要重写这份部署教程

一次改名带来的连锁反应

CoPaw 是阿里 AgentScope 团队推出的开源个人 AI Agent 项目。它把”一个能干活的助理”做成了一个可以在本地跑起来、6 分钟就能上手的东西：接入模型、挂上工具、开一个 Web 界面，剩下的交给对话。这个项目最近完成了一次更名，CoPaw 改叫 QwenPaw，对应的 Python 包名、命令行入口、文档域名也一并迁移。

对老用户来说，这不是一条”看完就忘”的新闻。更名意味着你脚本里的命令、CI 里的依赖、Dockerfile 里的包名、同事群里转发的教程链接，全都可能在一个早上失效。对第一次接触的人来说，更名的窗口期更麻烦：搜索引擎里”CoPaw 教程”和”QwenPaw 部署”两套结果同时在跑，你下载到的到底是哪一版、命令该写哪个，全靠自己去分辨。

这篇教程把 QwenPaw 部署全流程拆开讲：环境怎么准备、pip 装完为什么还要 init、8088 端口起不来怎么查、三种计费方式到底怎么选、模型配置模板长什么样、常见报错怎么排。全文以一个”从零到能用”的路径组织，中间穿插一些踩过坑才会注意到的细节。

写作顺序说明一下，方便你按需跳读。前四节解决”认知问题”：更名改了什么、旧脚本怎么办、文档混乱期怎么判断真假、以及为什么我建议你在动手前先做一次盘点。中间四节是”动手问题”：环境、安装、初始化、启动与 8088 验证。再往后是”配置与钱”：三种接入方式、成本测算、模型配置模板。最后是”救火与选型”：报错排查、同类对比、上线维护。如果时间紧，直接跳到第五节开始照做，遇到卡点再回翻前四节。

这篇文章想解决的问题清单

把需求列清楚，你才好判断它是否值得读完。第一，我机器上装着旧版 CoPaw，升级会不会丢配置。第二，pip install qwenpaw 之后为什么还有一步 init，能不能跳过。第三，qwenpaw app 起来了但 8088 打不开，问题出在哪一层。第四，Token Plan、Coding Plan、按量计费到底怎么选，我会不会买贵了。第五，我想接的不是 Qwen，模板怎么写。第六，报错了我该怎么一步步缩小范围。

这六个问题覆盖了九成以上的实际诉求。剩下的细节，比如日志格式、内部实现、插件机制，本文不展开——那属于二次开发话题，而不是 QwenPaw 部署话题。

先说结论：三条命令，两个坑

如果你只想知道最快路径：pip install qwenpaw、qwenpaw init --defaults、qwenpaw app，然后浏览器打开 http://127.0.0.1:8088。真的就是三步（社区常说的”pip init 两步”，指的是装完之后的初始化和启动这两个动作）。

但有两个坑几乎人人都会踩。坑一，忘了用虚拟环境，装完命令找不到。坑二，以为 --defaults 会顺便把模型配好，结果界面能开、对话报错。这两个坑后文都会给明确解法，并在报错那一节给出排查路径。先把这句结论记住，接下来慢慢展开。

更名到底改了什么：三层变化

先把变化说清楚。一次项目更名，通常涉及三层：仓库与文档层、包与命令层、生态与调用层。QwenPaw 这次改名，三层都动了。

仓库与文档层

仓库名、README、官方文档地址都换成了 QwenPaw 的命名。这是影响最大也最容易被低估的一层——因为大量第三方教程、博客、视频教程是直接抄 README 写出来的，它们会在相当长一段时间里保留旧名字。你在搜索”CoPaw 部署”时命中的一半结果，可能指向已经 404 的旧链接，或者指向旧链接的镜像页面。

包与命令层

Python 包名从旧名迁移到 qwenpaw，命令行入口也相应变成 qwenpaw。这一层的变化最直接：pip install qwenpaw、qwenpaw init、qwenpaw app。老脚本里的 copaw 命令如果还能用，多半是过渡期留的兼容别名，而不是长期承诺；新项目不要依赖它。

生态与调用层

项目名称里带上了 Qwen，意味着它和 Qwen 系列模型的协同会更紧密：默认模型指向、文档示例、控制台配置模板，都会优先以 Qwen 系列为参照。这不代表它只支持 Qwen——QwenPaw 仍然支持接入其他模型，这一点在后文的模型配置模板里会详细展开。

旧命令还能用吗：兼容性处理的三条原则

更名期最实际的问题是：我到底该用哪个命令。先说一个判断标准，再给三条原则。判断标准很简单——先看官方包的最新版本是否仍在发布，再看你的使用场景是否需要新特性。如果两者都指向”可以用新的”，就迁移，别犹豫。

迁移前先做一次盘点

三条原则之前，先盘点。盘点清单有四行：装了哪个包、什么版本、配置文件在哪、凭据存在哪。这四行记录在手，后面的任何操作都有退路。

# 一行一行记下来
python3 -m pip list 2>/dev/null | grep -i -E "qwenpaw|copaw"
ls -a ~ | grep -i -E "qwenpaw|copaw"
find ~ -maxdepth 3 -name "*.yaml" 2>/dev/null | grep -i -E "qwenpaw|copaw"
env | grep -i -E "qwen|dashscope" | sed -E 's/(=.{6}).*/\1***/'

最后一行做了脱敏，只打印前六位。这是个小技巧：排查时你需要知道”哪个变量被设了”，但不需要看到完整 Key，尤其是当你在共享屏幕或截图汇报的时候。

原则一：新装一律用新名

无论是虚拟机、云主机还是本地开发机，新装的 QwenPaw 部署全部使用 qwenpaw 包名与命令。不要因为”看到一篇老教程”就退回去装旧包。旧包可能在 PyPI 上仍然可见，但版本迭代、安全修复、模型适配都会跟着新走。

原则二：老环境先确认再迁移，别急着卸载

如果你机器上已经装着旧版本并且正在用，先查清楚两件事：配置文件位置、以及已配置的模型凭据。典型做法是先用旧命令把当前配置导出一份备份，再安装新包、跑 init，最后对照着把配置补回去。直接 pip uninstall 是很多人在更名期丢失配置的原因。

# 1. 确认当前装的是哪一个包、什么版本
pip show qwenpaw 2>/dev/null || pip show copaw 2>/dev/null

# 2. 在动任何东西之前，备份配置目录（假设在 ~/.qwenpaw 或 ~/.copaw 下）
ls -la ~ | grep -i -E "qwenpaw|copaw"
cp -r ~/.qwenpaw ~/.qwenpaw.bak.$(date +%Y%m%d) 2>/dev/null || \
cp -r ~/.copaw  ~/.copaw.bak.$(date +%Y%m%d)  2>/dev/null

# 3. 卸载旧包（确认备份完成后再执行）
pip uninstall -y copaw

# 4. 安装新包
pip install -U qwenpaw

# 5. 校验命令入口指向新包
which qwenpaw && qwenpaw --version

原则三：脚本里的命令做别名过渡，但设一个退出日期

团队协作场景下，不可能一夜之间把所有人的脚本改完。一个务实的做法是在 shell 配置里加过渡别名，同时给它一个明确的移除时间。

# ~/.zshrc 或 ~/.bashrc 中追加（过渡期使用，不要长期保留）
alias copaw='qwenpaw'

# 确认生效
source ~/.zshrc
qwenpaw --version

但要注意：别名只解决”当前 shell 里敲命令”的问题，解决不了 CI 配置、Dockerfile、systemd service 文件、文档里的硬编码。这些地方必须逐个改。经验做法是全局搜一遍：

# 在项目目录里找出所有还在写旧命令的地方
grep -rn --exclude-dir=.git -E "copaw" . | head -50

怎么绕开更名期的文档混乱

这是本次更名里我认为最值得单独讲的一节。更名期（尤其是前两三个月）的信息质量极差，原因很简单：内容生产的滞后性。一篇写得再好、配图再全的教程，在改名当天就变成了”过时教程”，但它在搜索结果里的排名不会当天掉下去。

更麻烦的是”半对半错”的教程：命令改成了新的，截图还是旧的，配置项名字已经变了但文中还在用旧的。这类内容比纯旧教程更坑，因为它让你以为自己在按新流程走，实际上每一步都对不上。

判断一篇教程是否过时的四个信号

我自己判断一篇 QwenPaw 部署教程能不能照抄，会看四个信号，命中任意两个以上就直接关掉：

第一，命令里出现 copaw init 或 pip install copaw，且全文没有”更名/别名”的说明。第二，截图里的 Web 界面顶部标题仍是旧名，且文中没有提到新旧版本的界面差异。第三，安装步骤里附带了一串复杂的依赖补丁（比如手动装某个特定版本的 transformers），这通常是某个旧版本的特有问题。第四，末尾的”参考链接”点进去是 404 或跳转到新域名但没有重定向说明。

以包元数据为准，不以文章为准

比”读教程”更可靠的办法是直接问包本身。PyPI 上的包信息、本地安装后的命令行帮助、--help 输出的参数列表，这三样是权威源。教程可能错，包不会哄你。

# 查 PyPI 上的最新版本与发布时间（不需要安装）
pip index versions qwenpaw

# 查本地已安装版本的元信息
pip show qwenpaw

# 命令行自带的参数说明，永远比文章新
qwenpaw --help
qwenpaw init --help
qwenpaw app --help

还有一个细节：qwenpaw --help 的子命令列表是最值得抄的东西。本文后面用到的 init --defaults、app，都是从帮助输出里确认过的形态。如果某个版本的帮助里没有 --defaults 参数，说明版本偏旧，先升级再往下走。

更名期的三种典型误信

除了判断教程新旧，更名期还有三类说法特别容易让人走错路，我按常见的顺序摆出来。

误信一：”先装旧包再升级”

有些教程会说”先 pip install copaw 装老版本，再升级到新的”。这在更名期没有任何收益，只会污染环境：旧包可能引入与新版冲突的依赖，卸载时还会留下残留文件。正确做法是直接装 qwenpaw，一次到位。

误信二：”必须用某个特定 Python 小版本”

更名那段时间恰逢 Python 新版本发布，于是社交平台上流传”必须用 3.12.2，否则装不上”。这类说法通常来自某一个人在自己机器上的偶然成功，并不具有普遍性。稳妥的判断方法是自己跑一遍：用 3.10 或 3.11 的稳定补丁版本，如果 pip install qwenpaw 能顺利装完、qwenpaw --help 能输出，就说明这个版本可用，不必追某个具体补丁号。

误信三：”要用 GPU 才能跑”

QwenPaw 是调用云端模型的 Agent 框架，本地并不需要跑推理。CPU 机器完全够用。唯一需要注意的是首次启动的初始化耗时，以及日志目录的磁盘占用。这一点对想做 QwenPaw 部署但手上只有一台 2 核 4G 小机器的人很重要——你不需要显卡。

动手前的环境盘点

正式开始前，花两分钟把机器摸清楚。这一步不是仪式感，而是为了在出现问题时能立刻回答”我的环境到底是什么样”。

# 系统信息
uname -a
cat /etc/os-release 2>/dev/null | head -3

# 资源情况
nproc
free -h
df -h ~

# Python 与 pip
python3 -V
python3 -m pip -V

# 端口占用情况（确认 8088 是否已被别人占）
ss -lntp 2>/dev/null | grep 8088 || echo "8088 free"

把这段输出复制到一个文本文件里存着。等后面真出问题时，你会省下大量”我的系统到底啥版本”的来回确认。这也是我这些年维护服务养成的习惯：上线前先固化一份基线快照。

Python 环境准备：版本、隔离、网络三件事

QwenPaw 部署的第一道坎几乎从来不是 QwenPaw 本身，而是 Python 环境。把这一步做扎实，后面的 pip 安装和 init 会顺得不像话。这一节按三件事展开：版本、隔离、网络。三件事都做完，安装环节基本不会出问题。

版本：不要太新也不要太旧

版本选择的经验值

原则是”不要太新也不要太旧”。太旧（3.8 以下）会缺语法特性和部分依赖；太新（刚发布的次版本）会撞上依赖包还没发预编译 wheel 的情况，pip 会退化成源码编译，装半小时然后失败。稳妥的选择是 3.10 或 3.11 的较新补丁版本。

# 查看系统里有哪些 Python
ls /usr/bin/python3* /usr/local/bin/python3* 2>/dev/null

# 查当前默认版本
python3 -V

# macOS 用 Homebrew 装指定版本（示例）
brew install python@3.11

# Ubuntu/Debian 装 3.11
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3.11-dev

隔离：必须用虚拟环境

这一条没有例外。QwenPaw 会拉一堆依赖，装进系统 Python 里，三个月后你想升级某个包，会发现整个系统工具链被拖下水。虚拟环境是成本最低的保险。

# 创建工作目录并进入
mkdir -p ~/qwenpaw-lab && cd ~/qwenpaw-lab

# 用指定 Python 版本创建虚拟环境
python3.11 -m venv .venv

# 激活（zsh / bash 通用）
source .venv/bin/activate

# Windows PowerShell 用：
# .\.venv\Scripts\Activate.ps1

# 确认当前 python 指向虚拟环境
which python && python -V

# 升级 pip / setuptools / wheel，这一步别省
python -m pip install -U pip setuptools wheel

网络：pip 源与代理

国内环境下，pip 安装慢、超时、SSL 报错是最常见的前置问题。配置一个国内镜像源能省掉大半烦恼。

# 临时使用清华源
pip install -U qwenpaw -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或者写成全局配置（推荐，一次性解决）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

# 验证配置
pip config list

如果你在服务器上做 QwenPaw 部署，且有企业代理，记得同时配好 HTTP_PROXY / HTTPS_PROXY 环境变量，并用 --proxy 参数传给 pip。这两个东西是分开的：系统代理环境变量管的是应用发起的 HTTP 请求（比如 QwenPaw 调模型 API），pip 的 --proxy 管的是包下载。

三个使用习惯

习惯一：每个项目一个 venv，放在项目目录下叫 .venv，而不是集中放在某个全局目录。这样做的好处是删项目就等于删环境，不会留下孤儿依赖。

习惯二：每次开新终端第一件事是激活。很多人报”命令找不到”，九成是忘了激活。可以在 shell 配置里加一段提示，让终端提示符显示当前虚拟环境名。

# zsh: 让提示符显示当前 venv 名称
autoload -Uz vcs_info
precmd() { echo -n "${VIRTUAL_ENV:t} " }

# 确认激活状态（输出为空说明没激活）
[ -n "$VIRTUAL_ENV" ] && echo "in venv: $VIRTUAL_ENV" || echo "NOT in venv"

习惯三：任何 pip 操作都用 python -m pip 而不是裸 pip。前者确定走的是当前解释器，后者可能指向系统里另一个 pip，这是”装完了却导入不到”的头号原因。

容器环境下的准备

如果你打算用 Docker 做 QwenPaw 部署，准备工作可以简化：官方镜像里通常已经带好了 Python。自建镜像的话，基础镜像选 python:3.11-slim，然后按下面这段写。

FROM python:3.11-slim

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    QWENPAW_HOME=/data/qwenpaw

RUN pip install -U pip && pip install qwenpaw

EXPOSE 8088
VOLUME ["/data/qwenpaw"]

# 首次启动时执行 init；重复执行是幂等的
CMD ["sh", "-c", "qwenpaw init --defaults && qwenpaw app"]

这里有两个细节值得注意。PYTHONUNBUFFERED=1 让日志实时输出，否则 docker logs 里看不到东西，排查会非常痛苦。QWENPAW_HOME 指向一个挂载卷，这样容器重建不会丢配置。端口用 8088 暴露，映射到宿主机时建议只绑本机：docker run -p 127.0.0.1:8088:8088。

pip install qwenpaw：安装这一步的细节

环境就绪后，安装本身只有一行。但这一行前后有几件事值得确认：装到哪了、版本是多少、怎么锁住、怎么升级。这一节按”装、验、锁、升”四步讲。

装与验

标准安装

# 激活虚拟环境（每次新开终端都要做）
cd ~/qwenpaw-lab
source .venv/bin/activate

# 安装 QwenPaw
pip install qwenpaw

# 查看装到了什么版本、装在哪
pip show qwenpaw

# 确认命令入口可用
qwenpaw --version
qwenpaw --help

如果 qwenpaw --version 报 “command not found”，九成是虚拟环境没激活，或者 pip 装到了另一个 Python 环境里。排查顺序是：先 which python 确认 python 路径、再 which pip 确认 pip 路径、两者应该都在 ~/qwenpaw-lab/.venv/bin/ 下。不一致就用 python -m pip install qwenpaw 强制走当前解释器。

锁：别让”下次重装”变成噩梦

个人助理这种东西，配置一旦跑顺，你不会想每周重装。把版本钉住，把依赖导出。

# 导出完整依赖锁定文件
pip freeze > requirements.lock.txt

# 下次在新机器上复现
pip install -r requirements.lock.txt

# 只想钉住 QwenPaw 主版本
pip install "qwenpaw==$(pip show qwenpaw | awk '/^Version:/{print $2}')"

升：升级策略

更名期前后版本迭代会比较密（修 bug、补模型适配、改配置项）。建议的策略是：生产环境跟 LTS 式的小版本、测试环境跟最新。升级前先备份配置目录，升级后先 qwenpaw --help 看子命令有没有变化，再启动服务。

# 查看可升级的版本
pip index versions qwenpaw

# 升级到最新
pip install -U qwenpaw

# 升级后核对命令是否变了
qwenpaw --help

离线与内网安装

有些企业内网机器不能出网，这时候 pip 的在线安装会失败。做法是在一台能出网的机器上把 wheel 包下载齐，再拷过去。

# 能出网的机器上：下载 qwenpaw 及其全部依赖
pip download qwenpaw -d ./wheels \
  --only-binary=:all: \
  --platform manylinux2014_x86_64 \
  --python-version 311 \
  --implementation cp

# 打包
tar czf qwenpaw-wheels.tar.gz ./wheels

# 内网机器上：从本地目录安装
tar xzf qwenpaw-wheels.tar.gz
pip install --no-index --find-links=./wheels qwenpaw

离线安装最容易失败的点是平台标签不匹配（--platform 写错导致下载到的是 macOS 的包）。如果内网机器和下载机器架构不同，一定要显式指定 --platform 与 --python-version。

qwenpaw init –defaults 到底做了什么

很多人卡在这一步：pip 装完了，为什么还要 init？直接 qwenpaw app 能不能跑？能跑，但你会在后面配置模型时抓瞎。理解 init 干了什么，比背命令有用得多。

init 的执行逻辑

init 不是装依赖，也不是下载模型。它是把 QwenPaw 的运行参数从出厂默认变成这台机器上的可用状态。理解这一点，后面的参数选择就有依据了。

三个动作

初始化命令本质上是做三件事，不同版本细节略有差异，但主干一致。

第一，建立配置目录与目录结构。–defaults 的含义就是”所有可选项都用默认值，不要弹交互式提问”。这些默认值通常包括监听地址、端口（8088）、日志级别、默认模型提供商占位。第三，生成或提示生成模型接入所需的凭据点。

默认值意味着什么

--defaults 最适合第一次体验和自动化部署（比如 Dockerfile、CI 里跑一遍）。它的代价是：模型凭据大概率是空的，你启动后 Web 界面能打开，但真正对话时会提示未配置模型。这不是 bug，是设计。

反过来，如果你想在 init 阶段就把模型接好，可以不带 --defaults，走交互式流程逐个填。CI 场景下则是 --defaults + 环境变量注入凭据。

# 方式一：全默认，非交互（推荐首次体验与容器部署）
qwenpaw init --defaults

# 方式二：交互式，逐项确认配置
qwenpaw init

# 方式三：查看 init 支持的全部参数
qwenpaw init --help

# 初始化完成后，看一眼生成了什么
ls -la ~/.qwenpaw 2>/dev/null || ls -la ~

初始化产物清单

init 跑完后，建议立刻核对一遍它生成了什么。这是了解一个项目最快的方式，也方便你后续做备份策略。

# 列出配置目录下的文件与目录
find ~/.qwenpaw -maxdepth 2 -type f 2>/dev/null | head -30
find ~/.qwenpaw -maxdepth 2 -type d 2>/dev/null

# 看一眼主配置文件（注意不要外泄 key）
sed -n '1,40p' ~/.qwenpaw/config.yaml 2>/dev/null

通常你会看到配置文件、日志目录、可能还有缓存与工作区目录。把这几类分别处理：配置文件进版本库（脱敏后），日志与缓存不进，工作区按需备份。这个划分在”上线之后的维护清单”那节还会再用到。

什么时候不该用 –defaults

三种情况。第一，你要改监听地址，希望从外部直接访问（虽然我不建议）。第二，你有多套环境，需要把配置目录指到别处，此时更稳妥的是先设 QWENPAW_HOME 再 init。第三，你要在 init 阶段就把模型凭据填好，走交互式流程更省事，免得后面再翻配置文件。

初始化失败怎么回滚

init 本身是幂等的：重复执行不会把已有配置毁掉，但会覆盖部分默认项。如果你 init 到一半发现填错了，最干净的恢复方式是删掉配置目录重来（记得先备份）。

# 备份后重来
mv ~/.qwenpaw ~/.qwenpaw.broken.$(date +%s)
qwenpaw init --defaults

# 或者指定自定义配置目录（多实例、多环境隔离时很有用）
export QWENPAW_HOME=~/qwenpaw-lab/instance-a
qwenpaw init --defaults

qwenpaw app：启动服务与 8088 端口验证

初始化完成，启动就是一条命令。

启动与验证

启动这一步看似只有一行命令，但验证方式决定了你出问题时能不能快速定位。先启动，再按层验证，别凭页面能不能打开就下结论。

一行命令起服务

# 前台启动（Ctrl+C 停止），默认监听 8088
qwenpaw app

# 查看 app 支持的参数（监听地址、端口等以帮助输出为准）
qwenpaw app --help

启动几分钟后（第一次启动会做一些初始化工作，稍慢），在浏览器打开 http://127.0.0.1:8088，应该能看到 Web 界面。服务器部署的话，需要额外注意监听地址——如果默认只监听 127.0.0.1，从外部访问是连不上的。

三层验证法

不要只看”浏览器能不能打开”。分层验证能让你在出问题时立刻定位到是哪一层。

# 第一层：进程在不在
ps -ef | grep -i qwenpaw | grep -v grep

# 第二层：端口有没有被监听、监听在哪个地址
ss -lntp | grep 8088
# 或
lsof -iTCP:8088 -sTCP:LISTEN

# 第三层：本机 HTTP 是否通
curl -i http://127.0.0.1:8088

# 只想看状态码
curl -o /dev/null -s -w "%{http_code}\n" http://127.0.0.1:8088

三层里任意一层断了，问题范围立刻缩小：第一层断说明进程崩了，看日志；第二层断说明进程在但没监听端口（配置问题或启动未完成）；第三层不通但第二层通，通常是防火墙或监听地址的问题。

让服务长期在后台跑

qwenpaw app 前台运行适合调试。要长期跑，用 systemd（Linux）或 nohup + 日志。

# 简单后台方案：nohup + 日志
nohup qwenpaw app > ~/qwenpaw-lab/app.log 2>> ~/qwenpaw-lab/app.log &
echo $! > ~/qwenpaw-lab/app.pid

# 看日志
tail -f ~/qwenpaw-lab/app.log

systemd 版本（以虚机部署为例）：

sudo tee /etc/systemd/system/qwenpaw.service > /dev/null <<'EOF'
[Unit]
Description=QwenPaw personal assistant
After=network-online.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/qwenpaw-lab
Environment="PATH=/home/ubuntu/qwenpaw-lab/.venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/home/ubuntu/qwenpaw-lab/.venv/bin/qwenpaw app
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now qwenpaw
sudo systemctl status qwenpaw --no-pager
journalctl -u qwenpaw -f

关于 8088 端口暴露的安全提醒

8088 是个”看起来无害”的端口，但一旦把你的个人助理放到公网 IP 上、且防火墙全开，任何扫描器都能扫到它。而个人助理天然会挂载工具、可能带凭据。最稳的做法是：只监听 127.0.0.1，通过 SSH 隧道访问。

# 在本机建立隧道，把远端 8088 映射到本地 8088
ssh -N -L 8088:127.0.0.1:8088 ubuntu@your-server-ip

# 然后本机浏览器打开 http://127.0.0.1:8088 即可

为什么不用固定端口硬编码

看到 qwenpaw app --port 8090 这类写法时，别急着写进 systemd。端口硬编码会让配置分散在两处：一处是配置文件，一处是启动参数。时间一长，你改了配置文件却没改参数，就会出现”我明明改了端口，怎么还是 8088″的困惑。建议只在临时排查、多实例并行时用命令行参数覆盖，长期运行统一在配置文件里管端口。

多实例并行的端口规划

如果你想在同一台机器上跑”个人用”和”团队用”两个 QwenPaw 实例，用 QWENPAW_HOME 隔离配置目录、用不同端口区分入口，是成本最低的做法。建议把个人实例放 8088，团队实例放 8098 或 8188，避免与常见端口冲突。两个实例各自独立 init，互不干扰。

# 实例 A（个人，8088）
QWENPAW_HOME=~/qwenpaw-lab/instance-a qwenpaw init --defaults
QWENPAW_HOME=~/qwenpaw-lab/instance-a qwenpaw app --port 8088

# 实例 B（团队，8098）
QWENPAW_HOME=~/qwenpaw-lab/instance-b qwenpaw init --defaults
QWENPAW_HOME=~/qwenpaw-lab/instance-b qwenpaw app --port 8098

8088 这个端口的选择逻辑

为什么是 8088 而不是 8000、3000？这类选择通常有几个考虑：避开最常见的 8000（大量开发服务器默认占它）和 3000（前端脚手架标配），同时 8088 语义上接近 HTTP 端口，记忆成本低。对部署者来说，这意味着一个现实结论：8088 被占用的概率明显低于 8000，但你仍然会遇到自家机器上另一个服务刚好用它。这就是后文端口冲突排查存在的理由。

另外一个提醒：如果你的机器上跑着别的 Agent 或 Web 应用，先 ss -lntp 扫一遍再启动，比启动失败再回头查要快得多。

日志怎么看

启动后第一件事是盯日志，而不是刷页面。日志能告诉你监听地址、加载了哪些 provider、有没有配置项告警。前台启动时日志直接打到终端；后台启动时看文件。

# 前台启动时：关注这几类关键词
qwenpaw app 2>&1 | grep -E -i "listen|port|8088|provider|error|warn"

# 后台启动时：跟踪日志
tail -f ~/qwenpaw-lab/app.log

# 已装 systemd 时
journalctl -u qwenpaw -n 100 --no-pager

三种接入方式：Token Plan、Coding Plan 与按量计费

这是整篇教程里最容易被写错、也最值得认真对待的一节。QwenPaw 支持三种计费/接入方式：Token Plan、Coding Plan、按量计费（API Key）。它们的差别不只是”付钱方式”，而是”你以什么身份、通过什么链路调用模型”。

三种方式的本质差异

在对比表格之前，先说一句容易被忽略的话：这三种方式在 QwenPaw 里最终都表现为一组可调用的模型端点与凭据，差别在于你以什么身份、通过什么链路调用模型。

先理解差异再谈价格

按量计费最直白：你申请 API Key，调用多少 token 付多少钱，链路最干净，也最容易按调用方拆分成本。Token Plan 更接近”包 token 额度”的订阅形态：先买额度、再用，单位成本更低但存在过期与用不完的风险。Coding Plan 面向编码场景：额度与调用模式针对代码生成/补全类负载优化，在 IDE 与 Agent 场景下更划算，但用于非编码任务时优势会被摊薄。

对比维度	Token Plan	Coding Plan	按量计费（API Key）
计费形态	预购 token 额度包	面向编码场景的订阅/额度包	按实际消耗的 token 实时计费
准入门槛	中：需预估用量后购买	中：需确认编码场景适配	低：申请 Key 即可用
单位成本	较低（量大更优）	编码类负载下最优	标准价，量越大越接近阶梯价
成本可控性	中：额度用完即止，但有过期风险	中：场景偏移时性价比下降	高：可设配额告警，也可随时停
适合人群	用量稳定、可预估的重度用户	主要用来写代码、跑 Agent 编码任务	新用户验证、用量波动大、需精细核算
推荐阶段	跑顺之后	跑顺且以编码为主	第一周试跑
配置复杂度	中	中	低

成本测算：先把”一周真实用量”测出来

网上大量”选哪个更划算”的文章，都跳过了一个前提：你得先知道自己用多少。给出一个可执行的测算法，任何人都能在半小时内算清楚自己的量级。

步骤一，用按量计费跑一周，记录每天的 token 消耗（大多数平台控制台有明细）。步骤二，算出日均与峰值。步骤三，把日均乘以 30 得到月用量，再分别套进三档套餐的单价做对比。关键不是”哪个名义单价低”，而是”你的用量曲线落在哪一档”。如果日均用量远低于套餐门槛，套餐就是浪费；如果峰值很高但日均很低，套餐反而省钱。

# 一个极简的成本估算脚本（把数值换成你自己的）
python3 - <<'PY'
daily_in  = 120_000      # 日均输入 token
daily_out = 40_000       # 日均输出 token
days      = 30

month_in  = daily_in  * days
month_out = daily_out * days
print(f"月输入 {month_in:,} tokens / 月输出 {month_out:,} tokens")

# 按量计费示例价（请以官方最新价格为准，这里只演示算式）
price_in, price_out = 2.0 / 1_000_000, 8.0 / 1_000_000
pay_as_you_go = month_in * price_in + month_out * price_out
print(f"按量计费月成本约 {pay_as_you_go:.2f} 元")

# 假设 Token Plan 月费为 120 元，含 600 万 token
plan_fee, plan_tokens = 120, 6_000_000
print(f"Token Plan 单价折合 {plan_fee / plan_tokens * 1_000_000:.2f} 元/百万 token")
PY

提醒：上面的单价只是演示算式用的占位数值，实际价格请以官方控制台为准。方法论比数字重要——先量化，再比价。

我的选择建议

第一阶段（第 1 周）：按量计费。目的不是省钱，是测出真实用量，同时避免一上来就锁死套餐。第二阶段（第 2～4 周）：如果主要是跑编码类任务、且用量稳定，切 Coding Plan；如果任务类型杂、用量稳定，看 Token Plan 的档位是否覆盖。第三阶段（第 2 个月起）：用量稳定后，用套餐锁定成本，按量计费保留作为溢出兜底。

成本测算里最容易被忽略的三项

单纯算 token 单价会严重低估真实成本。第一项是上下文膨胀：Agent 每轮对话都会带上系统提示、工具描述、历史消息，实际输入 token 往往是”你打的那句话”的几十倍。一个看起来只有几十字的问题，背后可能是上万 token 的输入。所以测算时要用控制台记录的真实消耗，而不是自己数消息长度。

第二项是重试与失败调用。网络抖动导致的一次超时重试，往往也计费。如果用量曲线出现不合理的锯齿，先查是不是有失败重试在放大消耗。

第三项是闲置成本。套餐买了用不完，等价于单位成本上升。这就是为什么我一直建议先按量跑一段时间——它天然不会产生闲置浪费，是成本测量的最佳起点。

三种方式在 QwenPaw 里的配置差异

配置上的差异没想象中大。三种方式最终都落到”一个可调用的模型端点 + 一组凭据”上，区别在于凭据的来源与形态。按量计费最直接：一个 API Key，填进环境变量即可。Token Plan 与 Coding Plan 通常也会给你一个接入凭据（可能形态不同），填写位置一致，但要注意额度与有效期在控制台管理，而不是在 QwenPaw 里管理。

换句话说，QwenPaw 本身不关心你买了哪种套餐。切换方式时，理论上只需要换凭据，不需要改 QwenPaw 的任何代码。这一点对做长期 QwenPaw 部署的人很友好：选型可以后置，先跑起来再决定。

模型接入配置模板

接下来是配置。不同版本配置文件的字段名可能略有差异，所以下面给的是”结构模板 + 字段说明”，你照着填即可；具体键名以 qwenpaw init --help 与生成的默认配置文件为准。

配置文件怎么写

配置是 QwenPaw 部署里最需要耐心的一步。写错了不会立刻报错，而是在你发起第一次对话时才暴露。所以这里的模板给得细一些。

YAML 结构模板

# ~/.qwenpaw/config.yaml 结构示意（字段名以实际生成为准）
providers:
  # 1) 主力模型：Qwen 系列，按量计费方式接入
  qwen-main:
    type: openai-compatible          # 走兼容 OpenAI 协议的端点
    base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
    api_key: ${QWEN_API_KEY}         # 用环境变量注入，不要把 Key 写死
    model: qwen-plus
    context_window: 131072

  # 2) 备用模型：其他厂商，OpenAI 兼容端点
  backup:
    type: openai-compatible
    base_url: https://api.example.com/v1
    api_key: ${BACKUP_API_KEY}
    model: some-model-name

defaults:
  provider: qwen-main
  temperature: 0.7
  max_tokens: 2048

app:
  host: 127.0.0.1                    # 对外暴露请走 SSH 隧道
  port: 8088

logging:
  level: info
  file: ~/.qwenpaw/logs/app.log

把凭据放进环境变量

配置文件里出现明文 Key 是最常见的泄漏来源。用环境变量注入，配合 .env 文件（加进 .gitignore）或 systemd 的 EnvironmentFile。

# ~/qwenpaw-lab/.env  内容（权限收紧）
cat > ~/qwenpaw-lab/.env <<'EOF'
QWEN_API_KEY=sk-xxxxxxxxxxxxxxxx
BACKUP_API_KEY=sk-yyyyyyyyyyyyyyyy
EOF
chmod 600 ~/qwenpaw-lab/.env

# 启动前加载（zsh 示例）
set -a; source ~/qwenpaw-lab/.env; set +a
qwenpaw app

多模型切换的实用方式

QwenPaw 与 Qwen 系列协同更深，但”支持其他模型”意味着你可以按任务分流：日常问答走主力，长文档分析走大上下文模型，编码任务走 Coding Plan 对应的模型。在配置文件里定义多个 provider，在 Web 界面或会话中切换，比改配置重启体验好得多。

一个实践建议：给每个 provider 起”能看懂的名字”，比如 qwen-coding、qwen-long-ctx、third-party-fast。三个月后回来看配置文件，你会感谢当时取名字的自己。

配置校验的四个检查点

配完别急着重启，按顺序检查四件事。检查点一：YAML 缩进。YAML 对缩进极其敏感，用空格不用 Tab，同一个层级对齐。可以用 python -c 快速校验语法。

# 校验 YAML 语法（需要 pyyaml，虚拟环境里通常已有）
python -c "import yaml,sys; yaml.safe_load(open('$HOME/.qwenpaw/config.yaml')); print('yaml ok')"

# 检查是否有误用的 Tab 字符
grep -Pn "\t" ~/.qwenpaw/config.yaml | head

检查点二：环境变量名与配置里引用的一致。${QWEN_API_KEY} 要求环境变量就叫这个名字，大小写敏感。检查点三：base_url 末尾的路径，OpenAI 兼容端点通常以 /v1 结尾，多一个或少一个斜杠都可能 404。检查点四：model 字段必须是该端点实际支持的模型名，拼错会报”模型不存在”。

一个最小可用配置

如果你想从最小面开始，先只配一个 provider，跑通再说。把下面这段填进配置，只改 api_key 的来源和 model 名即可。

providers:
  main:
    type: openai-compatible
    base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
    api_key: ${QWEN_API_KEY}
    model: qwen-plus

defaults:
  provider: main

app:
  host: 127.0.0.1
  port: 8088

跑通之后再逐个加 provider，每加一个就验证一次。一次性把所有 provider 都写进去、再统一排查，是效率最低的做法。

常见报错排查

下面四个是 QwenPaw 部署里出现频率最高的报错，每个都给定位方法和修复命令。

四类高频报错逐个拆

下面四个是 QwenPaw 部署里出现频率最高的报错，每个都给症状、定位方法和修复命令。排查的总原则是：先缩小范围，再动手改。

报错一：8088 端口被占用

启动直接失败，错误信息里带 address already in use 或 EADDRINUSE。

# 找出谁在占用 8088
sudo lsof -iTCP:8088 -sTCP:LISTEN
# 或
sudo ss -lntp | grep 8088

# 情况 A：是上一次启动残留的 QwenPaw 进程
kill <PID>
# 不行再强杀
kill -9 <PID>

# 情况 B：是别的程序，换成别的端口启动
qwenpaw app --help          # 先看端口参数名
qwenpaw app --port 8090     # 具体参数以帮助输出为准

# 情况 C：Docker 容器占了端口
docker ps --format '{{.Names}}\t{{.Ports}}' | grep 8088

报错二：pip 版本过低或依赖解析失败

症状是 ERROR: Could not find a version that satisfies the requirement，或者 pip is being invoked by an old script wrapper。

# 先升级 pip 本身（注意用 python -m pip，避免装到别处）
python -m pip install -U pip

# 查真实版本
python -m pip --version

# 清理缓存后重试
pip cache purge
pip install qwenpaw --no-cache-dir

# 国内网络下换源重试
pip install qwenpaw -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

# 依赖冲突时看完整解析过程
pip install qwenpaw -v

如果仍失败且报的是某个具体依赖编译错误，通常是缺系统编译工具。Ubuntu 上装 build-essential python3-dev；macOS 上确认 Xcode Command Line Tools 已装。

报错三：init 失败

常见两种：权限不足（配置目录不可写）和配置目录已存在损坏文件。

# 权限问题：检查配置目录归属
ls -ld ~/.qwenpaw
# 修正归属
sudo chown -R $(whoami):$(whoami) ~/.qwenpaw

# 目录损坏：备份后重建
mv ~/.qwenpaw ~/.qwenpaw.corrupt.$(date +%s)
qwenpaw init --defaults

# 自定义目录时确认环境变量生效
echo $QWENPAW_HOME
qwenpaw init --defaults

还有一种隐蔽的失败：init 显示成功，但 qwenpaw app 启动后 Web 界面白屏或报版本不匹配。这往往是因为命令行和配置文件来自不同版本。修复方式是升级包后重新 init。

pip install -U qwenpaw
qwenpaw --version
qwenpaw init --defaults   # 重新生成与当前版本匹配的默认配置
qwenpaw app

报错四：启动后能打开界面但无法对话

这通常不是报错，是”没配模型”。回到配置模板那一节，确认 provider、base_url、api_key 三项都填了，并且用的是环境变量注入。可以在启动终端里确认变量是否真的被加载。

# 确认环境变量在启动终端里是可见的（不要打印完整 Key）
echo ${QWEN_API_KEY:0:6}...

# 若无输出，说明没有 source .env
set -a; source ~/qwenpaw-lab/.env; set +a

与同类开源 Agent 的定位对比

QwenPaw 不是唯一的选择。开源个人 Agent 这个赛道最近一年挤得很。把它放进对比表里看，才能判断它是不是你的菜。

项目	定位	上手成本	模型接入	适合场景	不足
QwenPaw（原 CoPaw）	开箱即用的个人 AI Agent，Web 界面为主	低：pip 两步上线	Qwen 系列深度协同，同时支持其他模型	个人助理、日常任务、多模型对比	生态还在早期，第三方插件偏少
通用 Agent 框架类（如 AgentScope 本身）	面向开发的 Agent 编排框架	高：需要写代码	灵活，需自行接线	定制化复杂 Agent 系统	没有现成的个人助理体验
终端类编码 Agent	命令行内完成读写文件、跑命令	中：需一定的命令行习惯	多为云模型按量接入	编码、仓库维护	非编码任务体验一般
本地模型 + 通用 Web UI	自建模型服务 + 前端聊天界面	高：需 GPU 与推理服务部署	本地模型为主	数据不出内网	硬件门槛高，Agent 能力需自建
桌面客户端类 Agent	安装包形式，图形化操作电脑	低：双击安装	绑定特定厂商	GUI 自动化	难以在服务器上跑、难以脚本化

QwenPaw 的差异化在哪

看完对比表，再说说我的判断。选型这件事没有绝对的优劣，只有场景匹配度。

三点稀缺性

三点。第一，”pip 两步上线”这个体验是稀缺的——大多数同类项目要么需要 clone 仓库配一堆东西，要么提供的是安装包而不是可编程部署形态。qwenpaw init --defaults && qwenpaw app 这两行能塞进 Dockerfile、能塞进云主机初始化脚本，这对”想在自己服务器上搭个助理”的人非常友好。

第二，与 Qwen 系列协同更深意味着默认配置更省心：不用先研究半天怎么接模型，默认指向就是能用的。第三，同时支持其他模型，避免被单一厂商锁死。这个平衡点其实是它最聪明的地方——既给了”开箱即用”，又保留了”可换”。

什么情况下别选它

如果你需要高度定制的多 Agent 编排、需要精确控制每一步的 prompt 与工具调用链，那 AgentScope 框架本身或其他编排框架更合适。如果你完全不想碰命令行、只要一个下载就能用的桌面应用，那桌面客户端类产品更省事。QwenPaw 的甜蜜区是：愿意用几条命令换来自托管控制权的个人用户与小型团队。

上线之后的维护清单

部署完成只是开始。给一份极简维护清单，每个月花十分钟过一遍就够。

常规检查项

维护不是每天盯着看，而是建立几个固定检查点，到点跑一遍。下面这几项，一个月十分钟就够。

五项例行检查

一是版本：pip index versions qwenpaw 看有没有更新，有就按前文的升级策略处理。二是磁盘：日志目录和缓存目录别无限增长，du -sh ~/.qwenpaw 定期看一眼。三是配置备份：.env 与 config.yaml 备份到安全位置，别只留在服务器上。四是端口对外暴露检查：ss -lntp | grep 8088 确认监听地址仍是本地。

# 一条命令的健康巡检
echo "== version =="; qwenpaw --version
echo "== port  =="; ss -lntp 2>/dev/null | grep 8088 || echo "8088 not listening"
echo "== http  =="; curl -o /dev/null -s -w "%{http_code}\n" http://127.0.0.1:8088
echo "== space =="; du -sh ~/.qwenpaw 2>/dev/null
echo "== log   =="; tail -n 5 ~/.qwenpaw/logs/app.log 2>/dev/null

迁移到新机器的标准流程

换机器、扩容、灾备都走这个流程：旧机导出依赖锁定文件与配置、新机建虚拟环境、装包、还原配置、init 校验、启动验证。顺序别乱，尤其是”还原配置后再 init”，因为 init 会补齐缺失的默认项。

# 旧机导出
pip freeze > requirements.lock.txt
tar czf qwenpaw-config.tar.gz ~/.qwenpaw/config.yaml ~/qwenpaw-lab/.env

# 新机还原
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.lock.txt
tar xzf qwenpaw-config.tar.gz -C ~/
qwenpaw init --defaults
qwenpaw app

常见问题 FAQ

Q1：CoPaw 改名成 QwenPaw 后，我原来装的还能用吗？需要重装吗？

短期内可以继续用，但建议尽快迁移。判断标准是”旧包是否还在收到更新、以及你依赖的模型接入是否正常”。如果旧版本一切正常且你不急着用新特性，可以暂缓；一旦出现模型调用异常或接口变更，就按前文”兼容性三条原则”迁移：先备份配置目录、记录当前模型凭据，再卸载旧包、pip install qwenpaw、重新 qwenpaw init --defaults，最后把配置补回去。不要在没备份的情况下直接卸载。

Q2：qwenpaw init –defaults 和普通的 qwenpaw init 有什么区别？该用哪个？

区别在于是否交互。--defaults 全程使用默认值、不弹任何提问，适合自动化脚本、Docker 构建、CI，以及”先跑起来再慢慢配”的首次体验。不带参数则进入交互式流程，逐项询问，适合你已经知道自己要接哪个模型、要改哪个端口的情况。实践建议：第一次用 --defaults 快速验证链路是否通，通了之后再决定是走交互式重配，还是直接手改配置文件。

Q3：启动后 8088 端口打不开，最快的排查路径是什么？

按三层验证法走。第一层 ps -ef | grep qwenpaw 看进程在不在，不在就看日志为什么崩。第二层 ss -lntp | grep 8088 看端口是否被监听、监听地址是 127.0.0.1 还是 0.0.0.0——如果是前者，从别的机器访问必然不通，这是最常见的原因。第三层 curl -i http://127.0.0.1:8088 在本机测 HTTP，通了说明服务正常只是网络层没放开。服务器上记得检查安全组与 ufw/iptables。

Q4：Token Plan、Coding Plan 和按量计费（API Key）到底怎么选？

新用户先用按量计费跑一周，目的不是省钱而是量化用量。拿到日均和峰值 token 数后，再套进另外两种方式的档位做对比。经验规律：日均用量远低于套餐门槛的，套餐不划算；用量稳定且以编码任务为主的，Coding Plan 通常最优；任务类型杂、用量稳定且较高的，Token Plan 更合适；用量波动剧烈或刚起步的，按量计费最灵活。切勿在没测用量前就买大额套餐，这是更名期教程里最容易误导人的地方。

Q5：QwenPaw 能接 Qwen 以外的模型吗？怎么配？

可以，这是它明确支持的。方式是走 OpenAI 兼容协议：在配置文件的 providers 下新增一个条目，填 base_url、api_key、model 三项即可，用不同的 provider 名称区分（例如 third-party-fast）。凭据一律用环境变量注入，不要写进配置文件。配好后在界面里切换默认 provider 就能验证。如果对方端点不是 OpenAI 兼容协议，则需要看该版本是否提供了对应的适配器，具体以 qwenpaw --help 与文档为准。

Q6：把 QwenPaw 部署在公网服务器上安全吗？有什么必须做的防护？

默认不建议直接暴露。个人助理通常能读写文件、执行工具、携带模型凭据，一旦被扫描到风险很高。最低限度做三件事：一是让服务只监听 127.0.0.1，通过 SSH 隧道 ssh -N -L 8088:127.0.0.1:8088 访问；二是凭据用 .env 注入并 chmod 600，确保不进 Git；三是安全组只开放 SSH 端口，不开 8088。如果确实需要团队远程访问，用带认证的反向代理（Nginx + Basic Auth 或 OAuth）在前面挡一层，并开启访问日志，别让 8088 裸奔。