WxAgent—— AI 微信聊天助手部署教程

前言

WxAgent是一个将任意 AI 大模型接入微信个人号的开源智能体底座。基于腾讯官方 iLink Bot 协议，纯 Python 实现，支持 DeepSeek、OpenAI、Claude、Qwen、智谱等主流大模型。无需 Node.js、无需 Docker、无需 GPU，只需一台个人电脑即可运行。

核心能力一览：

类别	能力
对话	多轮自然语言对话，流式输出，长消息智能分段（600字/段）
工具	58+ 工具（55 内置 + 3 桥接），覆盖文件/代码/系统/网络/下载/媒体/磁盘/批量/监控/飞书/地图 12 大类
记忆	短期对话压缩 + 长期 ChromaDB 向量记忆 + 偏好自动学习 + 混合检索
安全	路径沙箱 + 命令风险分级 + AI 安全审查 + 审计日志 + 数据出境同意 + 剪贴板脱敏
调度	APScheduler 定时任务 + URL 变化监控 + Skill 场景模式
语音	SILK→WAV→Whisper 自动转录，支持本地/云端双模式
多用户	按微信用户 ID 隔离对话历史与记忆，LRU + TTL 会话管理
面板	Web 管理面板（FastAPI + React），13 个配置页面

1. 环境要求

在开始部署之前，请确保你的电脑满足以下条件：

项目	要求
操作系统	Windows / macOS / Linux
Python 版本	3.11 及以上（推荐 3.12）
Node.js	可选（仅构建 Web 管理面板时需要，建议 18+）
网络	能访问所选 LLM 的 API 地址
微信	手机端微信可正常扫码

2. 克隆仓库

2.1 打开终端

• Windows： 按 Win + R，输入 cmd 或 powershell，回车打开终端
• macOS / Linux： 打开 Terminal 终端
  

2.2 进入你想放置项目的目录

cd D:\Code

将 D:\Code 替换为你自己的目标路径。

2.3 执行克隆命令

选择一个执行：

方式一：从 GitHub 克隆（原作者地址）

git clone https://github.com/Elaine-one/WxAgent.git

从 GitHub 克隆在国内可能较慢，有时会克隆失败。如果失败，请尝试方式二。

方式二：使用 GitHub 镜像加速

git clone https://ghfast.top/https://github.com/Elaine-one/WxAgent.git

克隆成功后，终端会显示类似如下信息：

Receiving objects: 100% (xxx/xxx), done.
Resolving deltas: 100% (xxx/xxx), done.

• 进入你想放置该项目的文件夹

• 克隆成功字样如下：

• 且在项目文件夹可以看见

• 如果失败，字样如下：

2.4使用pycharm打开该文件夹，项目整体结构如下

了解项目结构有助于后续的自定义和扩展：

WxAgent/
├── main.py                  # 主入口：消息循环、防抖去重、初始化
├── config.py                # 全局配置 + System Prompt 动态构建
├── config.yaml              # YAML 细粒度配置
├── .env                     # 环境变量配置（API Key 等）
│
├── channel/                 # 微信通道层（iLink 协议）
│   ├── client.py            #   HTTP 客户端、AES 加密
│   ├── receiver.py          #   长轮询收消息
│   ├── sender.py            #   发文本/媒体消息
│   ├── login.py             #   扫码登录
│   ├── upload.py            #   CDN 文件上传
│   ├── session.py           #   Session 持久化
│   └── message.py           #   消息签名、防抖合并
│
├── core/                    # 核心引擎层
│   ├── graph.py             #   LangGraph 状态图
│   ├── dispatcher.py        #   多用户会话调度
│   ├── agent_loop.py        #   Legacy 简单循环
│   └── nodes/
│       ├── classify.py      #   意图分类
│       └── react.py         #   ReAct 推理 + Skill 注入
│
├── llm/                     # LLM 抽象层
│   ├── universal.py         #   统一接口
│   ├── format_openai.py     #   OpenAI 兼容格式
│   ├── format_anthropic.py  #   Anthropic 原生格式
│   ├── router.py            #   多模态任务路由
│   ├── fallback.py          #   主模型失败降级
│   └── streaming.py         #   流式输出 + 智能分段
│
├── tools/                   # 工具层（58+ 工具）
│   ├── registry.py          #   工具注册表
│   ├── bridge.py            #   桥接工具
│   └── builtin/             #   内置工具（12 个模块）
│
├── memory/                  # 记忆系统
│   ├── manager.py           #   短期 + 长期 + 偏好提取
│   ├── short_term.py        #   对话压缩
│   ├── long_term.py         #   ChromaDB 向量嵌入
│   └── retriever.py         #   混合检索
│
├── security/                # 安全体系（6 层防护）
├── parsers/                 # 文件解析器（PDF/Word/Excel/图片）
├── mcp_client/              # MCP 协议层
├── web/                     # Web 管理面板
│   ├── run_web.py           #   启动入口
│   ├── api/                 #   FastAPI 后端
│   └── frontend/            #   React 前端
│
├── tasks/                   # 异步任务 + APScheduler
└── observability/           # 日志 + 指标采集

3. 安装依赖

3.1 更新 pip（推荐）

使用清华镜像源加速：

python -m pip install -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple --upgrade pip

3.2 安装项目依赖

pip install -r requirements.txt

说明： Python 版本需 ≥ 3.11，推荐 3.12。如果安装失败，可以尝试创建虚拟环境后重新安装，或将错误信息交给大模型辅助排查。

3.3 安装可选依赖（按需选择）

以下为可选依赖，缺少时对应功能会自动降级，不影响核心对话和工具调用：

# 语音消息转录（SILK 解码 + Whisper 语音识别）
pip install pilk faster-whisper

# 本地 OCR 文字识别
pip install paddleocr paddlepaddle

# 后台文件索引监控
pip install watchdog

# 网页快照（无头浏览器渲染）
pip install playwright && playwright install

4. 配置项目

4.1 创建配置文件

将 .env.example 复制为 .env：

cp .env.example .env

Windows 用户注意： 如果 cp 命令不可用，请使用 copy .env.example .env。

4.2 编辑 .env 文件

用任意文本编辑器打开 .env 文件，填入你的 API 配置。以下为各厂商配置示例：

厂商速查表

厂商	LLM_PROVIDER	LLM_BASE_URL	LLM_MODEL 示例
DeepSeek	openai	https://api.deepseek.com/v1	deepseek-chat
DeepSeek V4	openai	https://api.deepseek.com	deepseek-v4-flash
通义千问	openai	https://dashscope.aliyuncs.com/compatible-mode/v1	qwen-plus
智谱 GLM	openai	https://open.bigmodel.cn/api/paas/v4	glm-4
OpenAI	openai	https://api.openai.com/v1	gpt-4o
Claude	anthropic	https://api.anthropic.com	claude-sonnet-4-6

4.3 其他可选配置

以下配置均为可选项，根据需要填写：

# 备用 LLM 配置（主模型不可用时自动切换）
# LLM_FALLBACK_API_KEY=sk-你的备用APIKey
# LLM_FALLBACK_BASE_URL=https://api.openai.com/v1
# LLM_FALLBACK_MODEL=gpt-4o

# 视觉模型配置（图片理解，不设置则默认使用 LLM_API_KEY）
# VISION_API_KEY=sk-你的视觉APIKey
# VISION_BASE_URL=https://api.openai.com/v1
# VISION_MODEL=gpt-4o

# HuggingFace 镜像（国内用户建议设置，加速模型下载）
# HF_ENDPOINT=https://hf-mirror.com

# Agent 工作区目录（不设置则默认为项目目录下的 workspace/）
# WORKSPACE_DIR=D:\Code\WxAgent\workspace

# 百度地图 API Key（https://lbsyun.baidu.com/ 申请）
# BAIDU_MAPS_API_KEY=你的百度地图APIKey

# 高德地图 API Key（https://lbs.amap.com/ 申请）
# AMAP_MAPS_API_KEY=你的高德地图APIKey

# 飞书应用凭据（https://open.feishu.cn 创建应用后获取）
# FEISHU_APP_ID=cli_xxxxx
# FEISHU_APP_SECRET=xxxxx

4.4 config.yaml 高级配置（可选）

项目根目录下的 config.yaml 提供了更细粒度的配置，包括：

• 模型路由： 按模态/任务类型路由不同模型
• 安全策略： 命令风险分级、路径沙箱、AI 审查器
• 工作区： venv 包管理、子目录结构
• 记忆检索： 向量/关键词/时间衰减权重
• Skill 场景： 触发词匹配 → 动态注入 LLM
• MCP 服务器： 外部工具服务器列表
• 提示词模板： 系统提示词、分类提示词等

初次部署无需修改 config.yaml，使用默认配置即可正常运行。

---

5. 启动项目

5.1 启动主程序

python main.py

启动后，系统会自动进行以下工作：

1. 初始化数据目录和工作区
2. 安装工作区基础 Python 包（pandas、numpy 等）
3. 初始化 jieba 分词
4. 初始化记忆系统、审计日志、任务调度器
5. 加载 MCP 服务器（如已配置）
6. 构建工具注册表

终端将显示类似如下信息：

5.2 扫码登录

系统会显示登录二维码，使用手机微信扫码授权即可连接。

注意： 同一微信账号只能绑定一个 Bot。如需更换设备，请删除项目目录下的 session.json 文件后重新扫码。

根据提示，点击链接手机授权，可以进行测试

6. Web 管理面板（可选）

Web 管理面板提供了可视化的配置和管理界面，强烈推荐使用。

6.1 构建前端

首次使用需先构建前端资源：

cd web/frontend
npm install
npm run build
cd ../..

前提： 需要已安装 Node.js（建议 18+）。如果未安装，请前往 Node.js 官网 下载。

6.2 启动 Web 面板

python web/run_web.py

启动后，在浏览器访问 http://127.0.0.1:8765 即可进入管理面板。

6.3 管理面板功能详解

面板共包含 13 个配置页面，以下逐一介绍各页面的功能与使用场景。

---

• 模型配置

可进行项目系统模型的配置，包括 LLM 提供商选择、API Key 填写、模型名称设置等。支持连接测试，确认配置无误后再投入使用。还可配置备用模型（主模型不可用时自动切换）和视觉模型（图片理解）。

---

• 安全审查

可对系统执行的高风险命令进行审查、隔离和阻隔。支持命令风险分级（safe / caution / dangerous 三级）、路径沙箱设置（限制读写目录）、AI 审查器开关（由 LLM 判断命令是否有恶意意图）。例如，del、rm、shutdown 等危险命令会被标记为 dangerous 级别，执行前需人工确认或被直接拦截。

---

• 工具配置

可进行各工具的细节参数配置，包括 Aria2 下载器 RPC 地址、Whisper 语音识别模型与设备、OCR 语言设置、GitHub 加速镜像源、网页抓取超时等。

使用场景示例： 配置 GitHub 加速镜像后，让助手帮你下载并总结 GitHub 项目——

---

• 工具注册表

展示系统所有已注册的工具列表（58+ 个），可查看每个工具的名称、描述、参数定义。支持对部分工具进行启用/禁用操作——当你不希望 AI 使用某个工具时，直接关闭即可，无需修改代码。

---

• 提示词

系统内置 5 个提示词模板，均可在线编辑：

• 系统提示词： 定义 AI 助手的角色和行为准则
• 分类提示词： 控制消息意图分类逻辑
• 视觉提示词： 图片理解时的描述指令
• 偏好提取提示词： 控制用户偏好自动学习
• AI 安全提示词： 危险命令审查判断逻辑

用户可根据需求自定义，例如修改系统提示词实现纯对话式聊天、角色扮演等不同风格。

---

• Skill 管理

Skill 即场景，场景即 Skill。每个 Skill 定义了一组触发词和对应的 LLM 注入指令，当用户消息匹配触发词时，系统自动激活该场景。

使用场景示例：

• 学习模式： 触发词"学习"，自动打开 VS Code、浏览器等应用，并注入专注学习的系统提示词
• 办公模式： 触发词"办公"，自动打开飞书、邮件等工具
• 代码审查模式： 触发词"审代码"，注入代码审查相关的提示词和工具配置

支持 AI 自动生成 Skill，也可手动创建和编辑。

---

• MCP 管理

MCP（Model Context Protocol）管理页面可自由配置外部 MCP 服务器。添加 MCP 服务器后，其提供的工具会自动注册到系统工具表中，AI 可直接调用，无需手动编写工具代码。

支持 stdio、SSE、飞书 MCP 等多种传输方式，可随时连接/断开 MCP 服务器，浏览其提供的工具列表。

---

• 飞书控制台

飞书控制台为飞书机器人工作后台的管理界面。配置飞书应用凭据（App ID / App Secret）后，可实现微信与飞书的跨域协同——在微信中直接操作飞书文档、多维表格、云空间、日历等，共 23 个飞书工具全覆盖。

---

• 系统控制

可进行系统操作定义和应用白名单配置：

• 系统操作： 定义休眠、锁屏、音量调节等操作的命令与风险等级
• 应用白名单： 限制 AI 只能打开白名单内的应用程序（如 VS Code、Chrome、记事本等），防止误操作打开敏感程序

---

• 其他页面

页面	功能说明
仪表盘	服务状态总览、启动检测、LLM 调用统计
行为限制	超时时间、调用上限、会话参数调整
工作区	目录结构浏览、venv 包管理
记忆检索	索引器配置、检索器权重调整、嵌入模型选择

---

8. 常见问题

Q1：扫码后提示"已连接过此机器"？

同一微信账号只能绑定一个 Bot。删除项目目录下的 session.json 文件后重新扫码即可。

Q2：发送图片微信端显示"图片已过期或被清理"？

检查 channel/client.py 中 _build_base_info() 的 channel_version 是否为 "2.4.4"。

Q3：支持哪些文件格式？

• 图片：png / jpg / gif / webp
• 视频：mp4 / mov / avi
• 普通文件：pdf / zip / doc 等
• 单文件大小限制：50MB

Q4：对话能记住多少上下文？

• 短期： 每用户保留最近 20 条消息
• 长期： ChromaDB 向量记忆跨会话持久化，超 50 条自动压缩摘要

Q5：可选依赖不装会影响使用吗？

不会。所有可选依赖均为条件导入，缺少时对应功能自动降级，不影响核心对话和工具调用。

Q6：安全机制有哪些？

六层防护：路径沙箱、命令风险分级、AI 安全审查、审计日志、数据出境同意、剪贴板脱敏。

Q7：legacy 和 langgraph 后端有什么区别？

• legacy：简单循环，消息 → LLM → 工具 → 回复
• langgraph（默认推荐）：完整状态机，支持消息分类、人机确认、中断恢复、元命令

Q8：pip install 安装依赖失败怎么办？

1. 确认 Python 版本 ≥ 3.11
2. 尝试使用国内镜像源：pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
3. 尝试创建虚拟环境后重新安装
4. 将错误信息交给大模型辅助排查

Q9：如何添加新工具？

在 tools/builtin/ 下新建模块，注册即可被 LLM 发现。示例：

from tools.base import ToolDef, ToolResult
from tools.registry import ToolRegistry

def _my_handler(query: str, state=None, user_id: str = "") -> ToolResult:
    result = do_something(query)
    return ToolResult(success=True, content=result)

ToolRegistry.register(
    ToolDef(
        name="my_tool",
        description="做什么用的工具。当用户说xxx时使用。",
        parameters={"query": {"type": "string", "description": "查询关键词"}},
        required=["query"],
    ),
    _my_handler,
)

---

9. 扩展方向

方向	思路
数据库查询	工具直接查 MySQL/PostgreSQL，Bot 变身数据助手
多 IM 平台	扩展 channel/ 包，接入 QQ/钉钉/Telegram
邮件发送	SMTP 发邮件，Bot 变成办公助理
智能家居	通过 MCP 接入 Home Assistant 等平台
知识库	利用 ChromaDB 向量记忆构建个人知识库

---

10. 总结

本文档详细介绍了WxAgent的完整部署流程，从环境准备、仓库克隆、依赖安装、项目配置到启动运行，以及 Web 管理面板的构建和使用。项目具备以下特点：

• 零门槛部署： 纯 Python 实现，无需 Docker / GPU / Node.js（核心功能）
• 多模型支持： 兼容 OpenAI / Anthropic 等主流 API，一键切换
• 丰富的工具生态： 58+ 内置工具 + MCP 动态扩展
• 完善的安全体系： 六层防护机制，保障本地运行安全
• 可视化面板： 13 个配置页面，管理便捷

如果在部署过程中遇到问题，欢迎提交反馈。