Ubuntu Miniconda部署QwenPaw完整教程（支持局域网访问+用户级开机自启）

一、前言

QwenPaw是AgentScope推出的本地AI智能体框架，默认仅绑定127.0.0.1只能本机访问，本文解决局域网设备无法访问、端口占用、systemd服务找不到、配置文件覆盖监听地址等高频踩坑问题，全程保姆级操作，无冗余方案。

环境：Ubuntu 24.04/26.04 + Miniconda + Python3.11 + QwenPaw
核心解决痛点：

1. qwenpaw app不带参数仅本机可打开，局域网访问失败
2. 旧config.yaml强制绑定127.0.0.1，--host参数失效
3. 8088端口被systemd后台进程占用
4. systemctl status qwenpaw提示找不到服务单元
5. conda隔离环境变量，export全局变量不生效

二、前置环境安装Miniconda

1. 下载国内镜像Miniconda

wget https://mirrors.bfsu.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b
source ~/miniconda3/bin/activate

2. 接受conda仓库条款（新版conda必做）

conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r

三、创建Python3.11专属环境并安装QwenPaw

1. 创建隔离环境

conda create -n qwenpaw python=3.11 -y
conda activate qwenpaw

2. 换清华源加速安装

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip install -U pip
pip install qwenpaw

3. 初始化配置

qwenpaw init --defaults

四、关键：局域网访问核心配置（根治仅本机访问）

原理说明

1. 127.0.0.1：本地回环地址，仅本机浏览器可访问；
2. 0.0.0.0：监听本机所有网卡，同WiFi/局域网设备可通过内网IP访问；
3. QwenPaw参数优先级：config.yaml > 环境变量 > --host启动参数，旧配置文件会覆盖命令行参数，必须先删除。

步骤1：清理冲突配置与残留进程

# 删除强制绑定127.0.0.1的配置文件
rm -f ~/.qwenpaw/config.yaml
# 杀掉所有qwenpaw后台进程，释放8088端口
pkill -f qwenpaw

步骤2：前台测试（可局域网访问的标准启动命令）

conda activate qwenpaw
qwenpaw app --host 0.0.0.0 --port 8088

启动成功日志会输出：Uvicorn running on http://0.0.0.0:8088

步骤3：防火墙放行8088端口（必做，否则局域网拦截）

sudo ufw allow 8088/tcp
sudo ufw reload
# 查看防火墙规则确认
sudo ufw status

步骤4：获取本机局域网IP用于访问

hostname -I

示例输出：192.168.3.105
访问地址：http://192.168.3.105:8088

五、用户级systemd开机自启（无sudo、无全局冲突）

重点区分

• 系统级服务：/etc/systemd/system/，操作需要sudo systemctl；
• 用户级服务：~/.config/systemd/user/，全程加--user，普通用户权限，不会出现Unit could not be found报错。

1. 创建用户服务目录与配置文件

mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/qwenpaw.service

粘贴完整配置（内置--host 0.0.0.0永久开放局域网）：

[Unit]
Description=QwenPaw AI Agent Service
After=network.target

[Service]
# 使用conda环境内绝对路径，附带开放局域网参数
ExecStart=/home/can/miniconda3/envs/qwenpaw/bin/qwenpaw app --host 0.0.0.0 --port 8088
WorkingDirectory=/home/can
# 程序异常自动重启
Restart=always
RestartSec=5

[Install]
# 用户会话登录后自动启动
WantedBy=default.target

保存退出：Ctrl+O → 回车 → Ctrl+X

2. 重载配置、开机自启并启动服务

# 刷新用户服务列表
systemctl --user daemon-reload
# 设置开机自启并立即运行
systemctl --user enable --now qwenpaw

3. 服务管理全套命令（全部带–user，避免找不到单元）

# 查看运行状态
systemctl --user status qwenpaw
# 停止服务
systemctl --user stop qwenpaw
# 重启服务
systemctl --user restart qwenpaw
# 取消开机自启
systemctl --user disable qwenpaw
# 实时查看运行日志（排查端口、监听地址问题）
journalctl --user -u qwenpaw -f

六、高频问题排查（踩坑汇总）

问题1：局域网无法访问，仅本机127.0.0.1能打开

1. 执行rm -f ~/.qwenpaw/config.yaml删除旧覆盖配置；
2. 前台执行qwenpaw app --host 0.0.0.0测试，确认日志输出0.0.0.0:8088；
3. 放行防火墙端口sudo ufw allow 8088/tcp；
4. 手机/电脑连接同一WiFi，使用内网IP访问。

问题2：[Errno 98] address already in use 8088端口被占用

# 停止用户自启服务
systemctl --user stop qwenpaw
# 强制杀死所有qwenpaw进程
pkill -f qwenpaw
# 验证端口释放（无输出即释放成功）
ss -tuln | grep 8088
# 重新启动服务
systemctl --user start qwenpaw

问题3：systemctl status qwenpaw 提示Unit could not be found

原因：用户级服务必须加--user参数，正确命令：

systemctl --user status qwenpaw

问题4：全局export QWENPAW_HOST=0.0.0.0不生效

conda run会隔离外层shell环境变量，不要使用环境变量方案，直接用--host 0.0.0.0命令行参数最稳定。

问题5：websockets DeprecationWarning 弃用警告

属于底层依赖版本兼容提示，不影响程序运行，无需处理。

七、卸载流程（如需清理）

# 停止并禁用自启
systemctl --user stop qwenpaw && systemctl --user disable qwenpaw
# 删除用户服务文件
rm ~/.config/systemd/user/qwenpaw.service
systemctl --user daemon-reload
# 删除conda环境
conda remove -n qwenpaw --all -y
# 删除本地配置缓存
rm -rf ~/.qwenpaw

八、总结

1. 局域网访问核心：启动命令强制携带--host 0.0.0.0，提前删除~/.qwenpaw/config.yaml；
2. 后台自启优先使用用户级systemd服务，所有管理命令添加--user；
3. 端口占用先停服务、杀进程，再重启；
4. 防火墙必须放行8088端口，否则外部设备无法建立连接。