QwenPaw：个人智能体操作系统与本地AI工作流部署指南

1. 这不是又一个“AI聊天框”：QwenPaw 的本质是你的数字分身操作系统

你点开这个标题，大概率刚在知乎、V2EX 或某个技术群看到别人晒 QwenPaw 的截图——一个带 UI 的本地 AI 助手，能连 DingTalk、能读 PDF、能自动整理邮件。但如果你真把它当成“国产免费版 Claude Code”或“离线版 ChatGPT”，那安装完的第一分钟就会困惑：它怎么不直接回答问题？为什么非要先配模型？为什么控制台里一堆“技能”“代理”“记忆演化”的术语？

这不是设计缺陷，而是它的底层定位根本不同。QwenPaw 不是一个“调用 API 的前端界面”，而是一套可编程的个人智能体操作系统（Personal Agent OS）。它的核心逻辑是：你定义任务 → 它调度技能 → 技能调用工具 → 工具操作文件/网络/本地服务 → 结果反馈并存入记忆 → 下次同类任务自动优化路径。整个过程像 Linux 的 shell 脚本链式执行，只是每一步都由 LLM 驱动决策。

举个最典型的例子：你想让 QwenPaw 每天早上 8 点自动抓取 Zhihu 热榜前 10 条，生成摘要，推送到 Feishu 群。在传统工具里，这需要写爬虫 + 写定时任务 + 写 Feishu Bot 接口调用代码。而在 QwenPaw 里，你只需在 Console 中启用“新闻摘要”技能，配置 Zhihu 数据源和 Feishu 通道，设置 Cron 表达式0 0 8 * * ?，然后保存。它会自动生成并维护整个工作流，甚至能根据你后续对摘要质量的反馈，主动调整关键词提取策略——这就是“记忆演化”的真实含义，不是记住对话历史，而是记住任务执行的有效性模式。

这也解释了为什么安装过程如此强调环境隔离与路径管理。它不像普通 Python 包只依赖几个库，而是要同时协调：Python 后端运行时、Node.js 前端构建环境、本地模型服务（Ollama/LM Studio）、加密密钥存储、多通道 Webhook 服务器、沙箱化的文件访问权限。任何一个环节的路径错位或权限越界，都会导致技能无法加载或工具被安全模块拦截。所以你看 GitHub README 里反复强调uv、.qwenpaw/bin、host.docker.internal这些细节，不是过度设计，而是操作系统级部署的必然要求。

关键词里的Windows/macOS/Linux/Python并非简单罗列支持平台，而是暗示了三类完全不同的部署哲学：

• Windows 用户面临的是企业级安全策略冲突（Constrained Language Mode）、PowerShell 执行策略限制、以及 NTFS 权限模型与 Python 虚拟环境的兼容性问题；
• macOS 用户的核心矛盾在于 Gatekeeper 网络签名验证与本地二进制（如uv.exe）的冲突，以及 Apple Silicon 与 Intel 芯片下 Node.js 二进制兼容性差异；
• Linux 用户表面最“自由”，实则隐藏着最深的坑：systemd 服务管理、Docker 网络命名空间隔离、以及/tmp目录挂载策略对 Ollama 模型缓存的影响。

而Python在这里已不是开发语言，而是系统运行时载体。QwenPaw 的pip install qwenpaw实际上是在你的 Python 环境中注入一个轻量级服务容器，它通过uv（比 pip 更快的 Python 包管理器）预编译所有依赖，再用tauri（Rust 构建的桌面框架）打包前端，最终形成跨平台的二进制入口。你安装的不是“一个程序”，而是一个可自我更新、可热重载、可沙箱隔离的智能体运行时。

所以，这篇教程的起点不是“如何敲命令”，而是帮你建立一个认知坐标系：当你在终端输入qwenpaw init时，你启动的不是一个聊天应用，而是在初始化一个数字分身的“生物神经突触连接”；当你配置DASHSCOPE_API_KEY时，你不是在填密钥，而是在为这个分身接入外部知识感官；当你点击“启用 PDF 处理技能”时，你不是在勾选功能，而是在给它安装一套视觉皮层。理解这一点，才能真正避开那些看似“安装成功”实则“功能残缺”的陷阱。

2. 为什么必须用 uv 而不是 pip？Python 环境隔离的底层战争

在 QwenPaw 的安装文档里，“curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash” 这行命令被放在最显眼位置，而它背后最关键的依赖是uv—— 一个用 Rust 编写的超高速 Python 包管理器。很多用户会疑惑：我系统里明明有 pip，为什么还要额外下载 uv？甚至有人手动删掉 install.sh 里关于 uv 的逻辑，强行用pip install qwenpaw，结果在启动时遇到ModuleNotFoundError: No module named 'qwenpaw.console'。这不是 bug，而是你跳过了 QwenPaw 对 Python 生态的“降维打击”。

2.1 pip 的时代局限性：包冲突与构建地狱

pip 的核心问题是它把“依赖解析”和“包安装”耦合在一起。当你执行pip install qwenpaw时，它会：

1. 解析pyproject.toml中声明的依赖树（包括fastapi==0.115.0,uvicorn==0.32.0,nodejs构建工具等）；
2. 逐个下载.whl或源码包；
3. 对每个包执行setup.py或pyproject.toml构建流程；
4. 将构建产物复制到当前 Python 环境的site-packages。

这个过程在 QwenPaw 场景下会崩溃三次：

• 第一次崩溃在前端构建：QwenPaw 的 Web 控制台（Console）是用 TypeScript + React 开发的，需要npm ci && npm run build生成静态资源。pip 无法识别package.json，更不会自动安装 Node.js。而 uv 通过pyproject.toml的[build-system]配置，能触发npm构建流程，并将dist/目录内容自动复制到 Python 包结构中。
• 第二次崩溃在版本锁死：QwenPaw 依赖的llama-cpp-python==2.5.0必须与llama.cpp的 C++ ABI 兼容。pip 安装时可能拉取llama-cpp-python==2.5.1（新版本），但该版本默认链接llama.cpp v0.3.0，而 QwenPaw 的scripts/目录里预编译的llama.cpp是v0.2.7。uv 则严格按pyproject.toml的requires-python = ">=3.9,<3.13"和dependencies = ["llama-cpp-python==2.5.0"]锁定版本，避免 ABI 不匹配。
• 第三次崩溃在环境污染：如果你全局 pip install，qwenpaw的fastapi会覆盖你项目里fastapi==0.104.1，导致其他 Python 服务报错。uv 默认创建.venv虚拟环境，且其虚拟环境是“隔离式”的——它不 symlink 系统 site-packages，而是硬拷贝所有依赖，彻底杜绝跨项目污染。

提示：你可以用uv python list查看 uv 管理的所有 Python 版本，用uv venv .qwenpaw-venv手动创建环境。这比python -m venv快 3-5 倍，因为 uv 的虚拟环境是预编译的二进制模板。

2.2 uv 的三大杀手锏：速度、确定性、跨语言协同

uv 的设计哲学是“把 Python 包管理变成操作系统级原语”。它在 QwenPaw 安装中的具体价值体现在：

第一，冷启动速度提升 10 倍
传统 pip 安装 QwenPaw 依赖（约 127 个包）需 4-6 分钟，uv 只需 22-35 秒。原因在于：

• uv 使用 Rust 的tokio异步引擎，并行下载所有包（pip 是串行）；
• uv 的 wheel 解析器是零拷贝的（pip 需解压.whl到临时目录）；
• uv 的依赖解析器使用增量式 SAT 求解（pip 用回溯法），对复杂依赖树（如 QwenPaw 的langchain-core+llama-index+transformers组合）求解更快。

第二，构建确定性保障
QwenPaw 的pyproject.toml包含：

[build-system] requires = ["setuptools>=61.0", "wheel", "setuptools_scm[toml]>=6.2"] build-backend = "setuptools.build_meta"

uv 会严格按此配置执行构建，而 pip 可能因--no-build-isolation参数被忽略，导致构建环境缺失setuptools_scm，进而使qwenpaw的版本号变成0.0.0.dev0（影响插件市场兼容性）。

第三，无缝衔接 Node.js 生态
QwenPaw 的前端构建脚本console/package.json依赖@tauri-apps/cli@^2.2.0，而该 CLI 需要rustc和cargo。uv 通过pyproject.toml的[project.optional-dependencies]声明：

[project.optional-dependencies] dev = ["@tauri-apps/cli"]

在安装时自动触发npm install @tauri-apps/cli，并将tauri二进制注入 PATH。这是 pip 永远做不到的——它只认 Python 包，而 uv 认的是“项目构建图谱”。

2.3 Windows LTSC 用户的血泪教训：Constrained Language Mode 如何杀死 PowerShell

Windows 企业版 LTSC 用户是 uv 安装失败的重灾区。根本原因在于：LTSC 默认启用 PowerShell 的 Constrained Language Mode（受限语言模式），该模式会禁用所有反射 API（[System.Reflection.Assembly]::LoadFile）、禁用动态代码生成（Add-Type）、禁用Invoke-Expression。而 uv 的 PowerShell 安装脚本install.ps1依赖：

# install.ps1 片段 $uvPath = "$env:USERPROFILE\.local\bin\uv.exe" if (-not (Test-Path $uvPath)) { # 下载 uv.exe 并解压 $webClient = New-Object System.Net.WebClient $webClient.DownloadFile("https://github.com/astral-sh/uv/releases/download/...", $uvPath) } # 关键：动态加载 uv.exe 并执行 & $uvPath venv --python 3.12 .qwenpaw-venv

在受限模式下，New-Object System.Net.WebClient被拦截，& $uvPath被拒绝执行。此时你会看到错误：

The term 'New-Object' is not recognized as the name of a cmdlet...

解决方案不是“关闭安全策略”（企业环境禁止），而是绕过 PowerShell：

1. 用 CMD 执行install.bat（CMD 不受 Constrained Language Mode 限制）；
2. 若install.bat仍失败，则手动下载uv-x86_64-pc-windows-msvc.zip（从 GitHub Releases），解压到%USERPROFILE%\.local\bin；
3. 手动添加%USERPROFILE%\.local\bin和%USERPROFILE%\.qwenpaw\bin到系统 PATH（通过sysdm.cpl图形界面）；
4. 在新 CMD 窗口中执行qwenpaw init --defaults。

注意：不要用pip install uv！因为 pip 安装的 uv 是 Python 包，而 QwenPaw 的 install.sh 需要的是独立二进制uv.exe。两者 ABI 不同，会导致qwenpaw app启动时报uv: command not found。

3. 桌面版 vs 脚本安装：两种部署哲学的终极对决

QwenPaw 官方提供了六种安装方式：pip、脚本、Docker、ECS、ModelScope、桌面版。但真正适合绝大多数个人用户的只有两种：脚本安装（推荐）和桌面版（妥协）。它们代表了两种截然不同的技术价值观——前者追求“可控的极致”，后者选择“可用的平衡”。理解它们的差异，比盲目跟风更重要。

3.1 桌面版：为“不想碰终端”的用户设计的温柔陷阱

桌面版（QwenPaw-Setup- .exe / QwenPaw- -macOS.zip）的核心承诺是：“下载即用，双击启动”。它确实做到了——但代价是牺牲了 QwenPaw 作为“操作系统”的灵魂。

桌面版的三大妥协：

• 前端被固化：桌面版的 Web 控制台是预构建的静态资源（dist/目录），无法热更新。当你发现 Console 的“技能管理”UI 有 Bug，官方在 GitHub 修复了console/src/components/SkillCard.tsx，但你的桌面版永远卡在旧版本，除非等下一个大版本发布。而脚本安装的qwenpaw app会实时读取src/qwenpaw/console/目录，git pull && npm run build即可更新。
• 后端被沙箱化：桌面版将 Python 运行时打包进 Electron 容器，所有subprocess.run()调用都被重定向到沙箱环境。这意味着：
  • 你无法在技能中执行os.system("ffmpeg -i input.mp4 output.mp3")（ffmpeg 不在沙箱 PATH）；
  • 你无法用shutil.copy("/path/to/file", "/backup/")访问任意路径（沙箱只开放~/.qwenpaw/working）；
  • 你无法调试qwenpaw进程（ps aux | grep qwenpaw查不到，因为它被 Electron 主进程托管）。
• 更新机制不可控：桌面版的自动更新检查是硬编码在main.js里的，它只检查 GitHub Releases 的latesttag。如果你正在测试v1.1.12-beta分支，桌面版永远收不到通知。而脚本安装的qwenpaw update命令支持--channel beta参数，可切换到任意分支。

桌面版的真实适用场景：

• 你用 macOS 14+ 或 Windows 10，且只打算用 QwenPaw 做基础聊天（连 DingTalk、读 PDF）；
• 你完全不关心“技能开发”“本地模型接入”“自定义 MCP 工具”；
• 你愿意接受每月一次的全量更新（而非每日的渐进式修复）。

提示：macOS 桌面版首次启动慢（10-60 秒）是因为它要在后台静默执行uv venv --python 3.12+pip install -e .+npm ci && npm run build。这不是卡顿，而是它在为你构建一个完整的 Python+Node.js 环境。你可以用Activity Monitor观察Python和Node.js进程的 CPU 占用峰值来确认。

3.2 脚本安装：掌控一切的硬核选择

脚本安装（curl ... | bash）的本质，是把 QwenPaw 的安装过程变成一个可审计、可复现、可调试的 Shell 脚本流水线。它的输出目录结构清晰暴露了所有决策点：

~/.qwenpaw/ ├── bin/ # qwenpaw 可执行文件（符号链接到 ~/.local/bin/qwenpaw） ├── working/ # 工作目录（skills、memory、config 存放处） ├── working.secret/ # 敏感数据（API keys、证书） ├── working.backups/ # 自动备份（每天凌晨 2 点压缩 tar.gz） └── venv/ # uv 创建的虚拟环境（含 Python 3.12.7 和所有依赖）

这种结构让你能精准干预每一个环节：

• 想换 Python 版本？删掉~/.qwenpaw/venv/，执行uv venv --python 3.13 ~/.qwenpaw/venv；
• 想调试技能加载失败？cd ~/.qwenpaw/working && ls -la skills/查看技能文件权限；
• 想禁用 Telemetry？编辑~/.qwenpaw/working/config.yaml，将telemetry_enabled: true改为false；
• 想查看实时日志？tail -f ~/.qwenpaw/working/logs/app.log。

脚本安装的隐藏优势：Docker 兼容性
脚本安装生成的~/.qwenpaw/working/目录结构，与 Docker 容器的卷挂载完全一致。这意味着：

• 你在本地用脚本安装调试好所有技能；
• 然后用docker run -v ~/.qwenpaw/working:/app/working ...启动容器；
• 容器内的 QwenPaw 会直接复用你本地的配置、记忆、技能，无需重新 setup。
  这种“本地开发 → 容器部署”的无缝切换，是桌面版永远无法提供的 DevOps 流程。

3.3 一个真实案例：当桌面版在 macOS 上静默失败

一位 macOS Sonoma 用户报告：“双击 QwenPaw.app 后，浏览器没打开，Activity Monitor 里也看不到进程”。排查过程揭示了桌面版的脆弱性：

1. 用console.app查看系统日志，发现错误：Failed to load libnode.dylib: dlopen(/Applications/QwenPaw.app/Contents/Frameworks/libnode.dylib, 0x0001): tried: '/Applications/QwenPaw.app/Contents/Frameworks/libnode.dylib' (mach-o file, but is an incompatible architecture)；
2. file /Applications/QwenPaw.app/Contents/Frameworks/libnode.dylib显示x86_64，而他的 Mac 是 M2 芯片（arm64）；
3. 原因：他下载的是QwenPaw-1.1.10-macOS.zip（Intel 版），但官网 Release 页面未明确标注架构。

如果是脚本安装，这个问题根本不存在：curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash会自动检测uname -m，下载对应架构的uv二进制，并用pyenv安装 arm64 版 Python。桌面版却把架构适配的决策权交给了用户——而大多数用户根本不知道x86_64和arm64的区别。

4. Docker 部署的致命盲区：localhost 不是你的 localhost

Docker 是 QwenPaw 官方推荐的部署方式之一，尤其适合想长期运行、避免污染宿主机环境的用户。但几乎所有 Docker 新手都会踩同一个坑：在容器里配置 Ollama 模型时，把 Base URL 写成http://localhost:11434，结果 QwenPaw 报错Connection refused。这不是 QwenPaw 的 Bug，而是 Docker 网络模型的必然结果。

4.1 Docker 网络的三个真相

Docker 容器拥有独立的网络命名空间（network namespace），这意味着：

• 真相一：localhost在容器内指向容器自身，不是宿主机。当你在容器里执行curl http://localhost:11434，实际是在访问容器自己的 11434 端口（而该端口什么都没监听）；
• 真相二：宿主机的localhost对容器不可见，因为 Docker 默认使用bridge网络，容器通过虚拟网桥docker0与宿主机通信，但docker0的 IP（如172.17.0.1）才是容器眼中的“宿主机”；
• 真相三：host.docker.internal是 Docker Desktop 的魔法别名，它在 macOS/Windows 上被自动解析为宿主机 IP，但在 Linux 上默认不存在（需手动添加--add-host=host.docker.internal:host-gateway）。

4.2 三种解决方案的深度对比

QwenPaw 文档给出了两种方案，但实际还有第三种更优解：

方案 C 的实操步骤（推荐）：

1. 创建docker-compose.yml：

version: '3.8' services: qwenpaw: image: agentscope/qwenpaw:latest ports: - "8088:8088" volumes: - "./qwenpaw-data:/app/working" - "./qwenpaw-secrets:/app/working.secret" - "./qwenpaw-backups:/app/working.backups" environment: - DASHSCOPE_API_KEY=${DASHSCOPE_API_KEY} # 关键：让 QwenPaw 容器能访问宿主机的 Ollama extra_hosts: - "host.docker.internal:host-gateway" # 如果 Ollama 也在 Docker 中运行，用 service 名 # depends_on: # - ollama # ollama: # 可选：在同一 compose 中运行 Ollama # image: ollama/ollama # ports: # - "11434:11434" # volumes: # - "./ollama-models:/root/.ollama/models"

2. 启动：docker-compose up -d；
3. 在 QwenPaw Console 的 Models 设置中，Base URL 填http://host.docker.internal:11434。

提示：如果宿主机防火墙开启（如 macOS 的“防火墙”设置），需确保11434端口未被阻止。用nc -zv localhost 11434在宿主机测试 Ollama 是否正常监听。

4.3 Docker 卷挂载的权限地狱：为什么qwenpaw-data目录突然变只读？

另一个高频问题：QwenPaw 在 Docker 中启动后，Console 里提示Permission denied: /app/working/skills。根源在于 Linux 的 UID/GID 映射。

Docker 容器默认以 root 用户运行，而 QwenPaw 的 Python 进程尝试以uid=1001（普通用户）写入挂载卷。当宿主机的./qwenpaw-data目录属于uid=1000（你的用户），容器内uid=1001就没有写权限。

终极解决方案（三步）：

1. 在宿主机创建专用用户：

sudo useradd -u 1001 -m qwenpaw-user sudo chown -R 1001:1001 ./qwenpaw-data ./qwenpaw-secrets ./qwenpaw-backups

2. 修改docker-compose.yml，指定用户：

services: qwenpaw: user: "1001:1001" # 强制容器以 uid=1001 运行 # ... 其他配置

3. 启动：docker-compose up -d。

这样，容器内进程的 UID 与宿主机目录 UID 完全一致，权限问题彻底消失。这是 Docker 生产环境部署的黄金法则，远比chmod 777安全可靠。

5. 从 init 到 app：启动流程的每一秒都在做什么

当你在终端输入qwenpaw init --defaults然后qwenpaw app，表面上只是两行命令，但背后是 QwenPaw 运行时的一整套初始化流水线。理解这个过程，是调试任何启动失败问题的关键。

5.1 qwenpaw init：不只是填表，而是构建数字分身的基因图谱

qwenpaw init的交互式流程看似简单，但它在后台执行了 7 个关键动作：

1. 工作目录初始化：在~/.qwenpaw/working/创建标准目录树：

   skills/ # 技能插件存放处（自动从 plugins/ 目录同步） memory/ # 长期记忆数据库（SQLite 文件） config.yaml # 核心配置（模型、通道、安全策略） logs/ # 日志轮转目录（按天分割）

2. 模型提供者注册：根据你选择的模型（如 DashScope），在config.yaml中写入：

   models: dashscope: api_key: "sk-xxx" # 加密存储在 working.secret/ base_url: "https://dashscope.aliyuncs.com/api/v1" model: "qwen-max"

3. 通道配置生成：若你选择 DingTalk，会生成channels/dingtalk.yaml，包含 Webhook URL 和加签密钥；
4. Telemetry 配置：询问是否启用遥测，写入config.yaml的telemetry_enabled字段；
5. 安全策略初始化：创建security/policy.yaml，默认启用tool_guard和file_access_guard；
6. 技能索引构建：扫描plugins/目录，生成skills/index.json，记录每个技能的元数据（名称、描述、所需权限）；
7. 首次记忆快照：在memory/下创建initial_snapshot.db，记录初始化时间戳和系统信息。

注意：--defaults参数会跳过所有交互，使用内置默认值（DashScope + Console 通道 + telemetry_enabled=true）。但如果你的网络无法访问 DashScope，qwenpaw app启动后会卡在“等待模型响应”，因为默认模型配置是强制的。

5.2 qwenpaw app：一个进程，三层架构

qwenpaw app命令启动的是一个单进程多线程服务，但它内部划分为清晰的三层：

第一层：FastAPI Web 服务器（主线程）

• 绑定0.0.0.0:8088，处理所有 HTTP 请求；
• 提供/api/REST 接口（技能调用、记忆查询）；
• 提供/ws/WebSocket 接口（实时聊天流式响应）；
• 静态文件服务/static/（Console 前端资源）。

第二层：Agent Runtime（后台线程池）

• 启动ThreadPoolExecutor(max_workers=4)，负责：
  • 执行技能（skills/pdf_reader.py）；
  • 调度 Cron 任务（heartbeat每 5 分钟检查一次）；
  • 处理 MCP（Model Context Protocol）客户端连接；
• 每个技能执行都在独立线程中，避免阻塞 Web 服务器。

第三层：Memory Engine（异步事件循环）

• 使用asyncio运行memory/engine.py；
• 监听所有agent_event（如skill_executed,message_sent）；
• 自动触发记忆演化：当pdf_reader技能连续 3 次返回空摘要，会降低该 PDF 的优先级权重；
• 每 30 分钟将内存变更持久化到 SQLite。

5.3 启动失败的黄金排查链路

当qwenpaw app启动后浏览器打不开，或 Console 显示空白，按以下顺序排查（90% 问题可定位）：

第一步：检查进程是否存活

# Linux/macOS ps aux | grep qwenpaw | grep -v grep # Windows tasklist | findstr qwenpaw

如果无输出，说明进程已崩溃退出。

第二步：查看实时日志

# 脚本安装 tail -f ~/.qwenpaw/working/logs/app.log # Docker docker logs -f qwenpaw_qwenpaw_1

重点关注ERROR和CRITICAL级别日志。常见错误：

• OSError: [Errno 98] Address already in use→ 端口 8088 被占用，改用qwenpaw app --port 8089；
• sqlite3.OperationalError: unable to open database file→~/.qwenpaw/working/memory/目录权限不足；
• ConnectionRefusedError: [Errno 111] Connection refused→ 模型服务（Ollama）未启动或 URL 配置错误。

第三步：验证模型连通性
在浏览器打开http://127.0.0.1:8088/api/health，返回：

{ "status": "healthy", "model_provider": "dashscope", "model_status": "ready", "memory_status": "ready" }

如果model_status是error，说明模型配置失败。此时：

• 检查~/.qwenpaw/working.secret/DASHSCOPE_API_KEY文件是否存在；
• 用curl -H "Authorization: Bearer sk-xxx" https://dashscope.aliyuncs.com/api/v1/models测试 API Key 是否有效。

第四步：Console 前端调试
在浏览器开发者工具（F12）的 Console 标签页，输入：

// 检查前端是否加载了后端配置 window.QWENPAW_CONFIG // 检查 WebSocket 连接状态 window.ws.readyState // 0=connecting, 1=open, 2=closing, 3=closed

如果QWENPAW_CONFIG为空，说明qwenpaw app未正确提供/static/config.js，通常是~/.qwenpaw/working/目录结构损坏。

6. 本地模型实战：Ollama + QwenPaw 的零 API Key 工作流

QwenPaw 最诱人的特性之一，是支持完全离线的本地模型（Ollama / LM Studio / llama.cpp）。这不仅规避了 API Key 管理的麻烦，更实现了真正的数据主权——你的 PDF、邮件、本地文件，永远不会离开你的硬盘。但“支持本地模型”不等于“一键即用”，它需要你亲手搭建一条从模型下载、量化、加载到技能调用的完整流水线。

6.1 Ollama 部署：为什么必须用--gpu all启动？

Ollama 默认以 CPU 模式运行，这对 QwenPaw 是灾难性的。因为 QwenPaw 的技能（如pdf_reader）会并发发起多个推理请求，CPU 推理速度（< 1 token/sec）会导致整个工作流卡死。

正确启动 Ollama（Linux/macOS）：

# 确保 NVIDIA 驱动已安装 nvidia-smi # 应显示 GPU 信息 # 启动 Ollama 并启用 GPU OLLAMA_NUM_GPU=1 ollama serve # 或更明确地指定 GPU OLLAMA_NUM_GPU=1 OLLAMA_GPU_LAYERS=35 ollama serve

Windows WSL2 用户注意：WSL2 的 GPU 支持需额外配置：

1. 安装 NVIDIA CUDA on WSL ；
2. 在 WSL2 中执行nvidia-smi确认 GPU 可见；
3. 启动 Ollama 时添加--gpus all：

docker run -d --gpus all -p 11434:11434 --name ollama -v ~/.ollama:/root/.ollama -it ollama/ollama

GPU 层数（GPU Layers）的科学配置：
Ollama 的--gpu-layers参数决定有多少层 Transformer 被卸载到 GPU。层数越多，推理越快，但显存占用越高。经验公式：

推荐 GPU Layers = 总层数 × 0.8

例如qwen2:7b有 32 层，设--gpu-layers 26；`qwen