序章：启程之前

发表于 更新于 分类于 阅读次数：
安装 QwenPaw 并发送第一条消息，配置大语言模型并搭建完整的开发环境，理解 QwenPaw 的架构概览与核心能力边界，为接下来的源码深度探索之旅做好全部准备工作。
个人公众号
1
准备出发 —— 马上要跟一条消息一起穿越 QwenPaw 源码

这一站我们把 QwenPaw 装好、跑起来、发一条消息。做完这些，你就在”起点”了——下一章我们就跟着这条消息钻进源码。

QwenPaw 是什么

QwenPaw 是一个用 Python 写的个人 AI 助手，跑在你自己的电脑上。你可以通过网页、钉钉、Telegram 等渠道跟它聊天，它能调用工具（搜索网页、读写文件、执行命令）来完成复杂任务，还支持多个 Agent 协作。

底层用 FastAPI 做 Web 服务、AgentScope 做智能体框架、支持 OpenAI / Qwen / Ollama 等多种大模型。

它躺在 GitHub 上，src/qwenpaw/ 下面有 411 个 Python 文件、约 13 万行代码。打开任何一个文件，你都会看到层层叠叠的 import、类定义、异步调用和 Mixin 继承链。

从哪里开始？

这本书的回答是：从一条请求开始。

在浏览器里输入一句话，按下回车，跟着这句话穿过 HTTP 路由、Runner 调度、Agent 推理、LLM 调用、工具执行，直到它变成 AI 的回复出现在屏幕上。

但在出发之前，我们需要把 QwenPaw 装好。

安装

你需要什么

Python 3.10 或以上。打开终端确认：

1
python3 --version

如果版本太旧或者提示找不到命令，先去 python.org 装一个。

一行命令

1
pip install qwenpaw

装好之后验证：

1
qwenpaw --version

应该输出类似 qwenpaw, 1.x.x 的版本号。看到这个就说明装好了。

遇到 pip: command not found？ 试试 python3 -m pip install qwenpaw。如果还不行，先升级 pip：python3 -m pip install --upgrade pip。

另一种装法

如果不想手动装 Python，QwenPaw 提供了安装脚本。macOS 或 Linux 上运行：

1
curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash

Windows PowerShell 里运行：

1
irm https://qwenpaw.agentscope.io/install.ps1 | iex

脚本会自动下载 Python、安装 QwenPaw、配好环境。

初始化

装好之后不能直接用。QwenPaw 需要知道：工作目录放哪？用哪个模型？

运行初始化向导：

1
qwenpaw init --defaults

--defaults 让它用默认配置，跳过交互式询问。适合快速体验。

术语：工作目录（Working Directory）
QwenPaw 的”房子”——所有 Agent 的配置、记忆、技能都住在这栋房子里。默认位置是 ~/.qwenpaw/，也可以通过环境变量 QWENPAW_WORKING_DIR 自定义。每个 Agent 在房子里有自己的”房间”（即工作区 Workspace，见第 4 章），房间里有自己的办公桌。

初始化做了什么？它在你的用户目录下创建了 ~/.qwenpaw/ 文件夹：

1
2
3
4
5
6
7
8
9
10
~/.qwenpaw/
├── config.json          # 主配置文件
├── HEARTBEAT.md         # 心跳任务清单
├── workspaces/          # 各个 Agent 的工作空间
│   └── default/         # 默认 Agent
│       ├── agents/      # 智能体配置
│       ├── memory/      # 记忆存储
│       └── skills/      # 技能文件
├── .qwenpaw.secret/     # 加密的密钥存储
└── .qwenpaw.backups/    # 自动备份

配置模型

QwenPaw 需要一个”大脑”——一个大语言模型。两个选择：

选择一：云端模型（推荐） 去 阿里云 DashScope 注册，拿到 API 密钥。或者用 OpenAI、Gemini——关键是拿到一个 API 密钥。

选择二：本地模型（免费） 有显卡的话，装个 Ollama，下载模型：

1
ollama pull qwen2.5

本地模型数据不离开电脑，但需要显卡，速度取决于硬件。

术语：Provider（模型供应商）
Provider 就是”模型供应商”的抽象。不管是 OpenAI、Qwen 还是本地的 Ollama，QwenPaw 都把它们当成一个 Provider 来调用。就像手机充电器——不管你是苹果还是安卓，插上就能充，因为充电器适配了不同的接口。

在 Web 界面输入密钥

先启动 QwenPaw：

1
qwenpaw app

app_cmd 会启动一个 Uvicorn 服务器，默认监听 127.0.0.1:8088。你会看到：

1
INFO:     Uvicorn running on http://127.0.0.1:8088 (Press CTRL+C to quit)

打开浏览器，访问 http://127.0.0.1:8088/。

在界面右上角找到「设置」（齿轮图标），进入「模型」选项卡：

  1. 选择提供商（Qwen / OpenAI / Ollama）
  2. 输入 API 密钥（如果用云端模型）
  3. 保存并启用

验证：发送第一条消息

配置好模型后，在聊天框输入：

1
Hello, what can you do?

按下回车。

你应该在几秒内看到 AI 的回复。如果看到了——恭喜，QwenPaw 已经跑起来了。

如果没看到回复：

  1. 运行 qwenpaw doctor 检查配置问题
  2. 检查 API 密钥是否正确（没有多余空格）
  3. 确认密钥有足够的额度
  4. 看看终端有没有错误日志

术语：qwenpaw doctor（诊断工具）
QwenPaw 的”体检医生”。它会检查工作目录是否正确、配置文件是否合法、模型能不能连通、权限有没有问题。出了问题先跑它，十有八九能找到原因。加 --deep 可以做更深入的连通性检查。

序章的目的就是这个：让你处于”刚输入一句话、按下回车”的状态。接下来的 26 章，我们将跟随这句话，穿越 QwenPaw 的每一层代码。

我们将会经历什么

这本书不会按模块目录来讲。那种讲法就像先告诉你人体有骨骼系统、循环系统、神经系统，然后让你自己拼出一个完整的人——你永远不知道食物从嘴巴进去后经过了哪些器官。

我们会像侦探一样，跟着一条请求的足迹追踪。

卷一·启程（第 1-8 章）——跟着消息走完一整趟旅程：

1
2
Browser -> HTTP Request -> FastAPI Router -> Runner Dispatch -> Agent Creation
-> Prompt Assembly -> ReAct Loop -> LLM Call -> Tool Execution -> SSE Response

八章走完，你完整地追踪了一条请求的生命周期。那时候你已经能定位 bug、在正确的文件里找到正确的代码。

卷二·图纸（第 9-14 章）——退后一步，像登上山顶俯瞰走过的路。源码模块之间是什么关系？为什么用 Mixin 而不是普通继承？Provider 为什么是可替换的抽象层？理解了设计，你就能读懂任意模块。

卷三·工坊（第 15-19 章）——给 QwenPaw 装上新的能力。写新工具、新技能、接入新模型、新频道，最后整理成 PR 提交。

卷四·纵深（第 20-26 章）——深入工程纵深：配置、记忆、自治任务、多智能体协作、插件系统、命令行与部署、测试与质量。读完这些，你就能参与架构讨论，提交高质量的 PR。

动手环节

在进入第一章之前，做三件事：

  1. 确保 QwenPaw 正常运行 —— 在浏览器里发消息能收到回复
  2. 拿到源码 —— git clone https://github.com/agentscope-ai/QwenPaw.git
  3. 浏览源码目录 —— 在 IDE 里打开 src/qwenpaw/，随便看看文件夹名称

预期结果：你能看到一个正在运行的 QwenPaw 实例，终端显示 Uvicorn running on http://127.0.0.1:8088，浏览器中发消息能收到回复。

自检：

  • qwenpaw --version 输出了版本号
  • http://127.0.0.1:8088/ 能打开 Web 界面
  • 发送消息后收到了 AI 回复

准备好了？翻到第 1 章，我们跟着第一条请求出发。