WxAgent—— 微信 AI 聊天助手部署教程支持 DeepSeek、通义千问、GPT、多轮对话、文件处理和工作助手功能文章目录WxAgent—— 微信 AI 聊天助手部署教程前言1. 环境要求2. 克隆仓库2.1 打开终端2.2 进入你想放置项目的目录2.3 执行克隆命令2.4使用pycharm打开该文件夹项目整体结构如下3. 安装依赖3.1 更新 pip推荐3.2 安装项目依赖3.3 安装可选依赖按需选择4. 配置项目4.1 创建配置文件4.2 编辑 .env 文件厂商速查表4.3 其他可选配置4.4 config.yaml 高级配置可选5. 启动项目5.1 启动主程序5.2 扫码登录6. Web 管理面板可选6.1 构建前端6.2 启动 Web 面板6.3 管理面板功能详解8. 常见问题Q1扫码后提示已连接过此机器Q2发送图片微信端显示图片已过期或被清理Q3支持哪些文件格式Q4对话能记住多少上下文Q5可选依赖不装会影响使用吗Q6安全机制有哪些Q7legacy 和 langgraph 后端有什么区别Q8pip install 安装依赖失败怎么办Q9如何添加新工具9. 扩展方向10. 总结如果你之前使用过 KouriChat但目前遇到项目无法启动、接口失效或无法继续使用的问题可以尝试本文介绍的 WxAgent。WxAgent 是一个面向微信的 AI 聊天助手项目支持多轮对话、DeepSeek、通义千问、GPT 等主流模型同时提供文件处理、语音识别、工具调用和 Web 管理面板等能力。本文将从环境准备、项目安装、模型配置到微信登录完整介绍部署流程。需要说明的是WxAgent 是独立项目并非 KouriChat 的官方升级版。两者的实现方式和配置流程不同请按照本文步骤重新部署。前言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 React13 个配置页面1. 环境要求在开始部署之前请确保你的电脑满足以下条件项目要求操作系统Windows / macOS / LinuxPython 版本3.11 及以上推荐 3.12Node.js可选仅构建 Web 管理面板时需要建议 18网络能访问所选 LLM 的 API 地址微信手机端微信可正常扫码2. 克隆仓库2.1 打开终端Windows按Win R输入cmd或powershell回车打开终端macOS / Linux打开 Terminal 终端2.2 进入你想放置项目的目录cdD:\Code将D:\Code替换为你自己的目标路径。2.3 执行克隆命令选择一个执行方式一从 GitHub 克隆原作者地址gitclone https://github.com/Elaine-one/WxAgent.git从 GitHub 克隆在国内可能较慢有时会克隆失败。如果失败请尝试方式二。方式二使用 GitHub 镜像加速gitclone 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-mpipinstall-ihttps://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple--upgradepip3.2 安装项目依赖pipinstall-rrequirements.txt说明Python 版本需 ≥ 3.11推荐 3.12。如果安装失败可以尝试创建虚拟环境后重新安装或将错误信息交给大模型辅助排查。3.3 安装可选依赖按需选择以下为可选依赖缺少时对应功能会自动降级不影响核心对话和工具调用# 语音消息转录SILK 解码 Whisper 语音识别pipinstallpilk faster-whisper# 本地 OCR 文字识别pipinstallpaddleocr paddlepaddle# 后台文件索引监控pipinstallwatchdog# 网页快照无头浏览器渲染pipinstallplaywrightplaywrightinstall4. 配置项目4.1 创建配置文件将.env.example复制为.envcp.env.example .envWindows 用户注意如果cp命令不可用请使用copy .env.example .env。4.2 编辑 .env 文件用任意文本编辑器打开.env文件填入你的 API 配置。以下为各厂商配置示例厂商速查表厂商LLM_PROVIDERLLM_BASE_URLLLM_MODEL示例DeepSeekopenaihttps://api.deepseek.com/v1deepseek-chatDeepSeek V4openaihttps://api.deepseek.comdeepseek-v4-flash通义千问openaihttps://dashscope.aliyuncs.com/compatible-mode/v1qwen-plus智谱 GLMopenaihttps://open.bigmodel.cn/api/paas/v4glm-4OpenAIopenaihttps://api.openai.com/v1gpt-4oClaudeanthropichttps://api.anthropic.comclaude-sonnet-4-64.3 其他可选配置以下配置均为可选项根据需要填写# 备用 LLM 配置主模型不可用时自动切换# LLM_FALLBACK_API_KEYsk-你的备用APIKey# LLM_FALLBACK_BASE_URLhttps://api.openai.com/v1# LLM_FALLBACK_MODELgpt-4o# 视觉模型配置图片理解不设置则默认使用 LLM_API_KEY# VISION_API_KEYsk-你的视觉APIKey# VISION_BASE_URLhttps://api.openai.com/v1# VISION_MODELgpt-4o# HuggingFace 镜像国内用户建议设置加速模型下载# HF_ENDPOINThttps://hf-mirror.com# Agent 工作区目录不设置则默认为项目目录下的 workspace/# WORKSPACE_DIRD:\Code\WxAgent\workspace# 百度地图 API Keyhttps://lbsyun.baidu.com/ 申请# BAIDU_MAPS_API_KEY你的百度地图APIKey# 高德地图 API Keyhttps://lbs.amap.com/ 申请# AMAP_MAPS_API_KEY你的高德地图APIKey# 飞书应用凭据https://open.feishu.cn 创建应用后获取# FEISHU_APP_IDcli_xxxxx# FEISHU_APP_SECRETxxxxx4.4 config.yaml 高级配置可选项目根目录下的config.yaml提供了更细粒度的配置包括模型路由按模态/任务类型路由不同模型安全策略命令风险分级、路径沙箱、AI 审查器工作区venv 包管理、子目录结构记忆检索向量/关键词/时间衰减权重Skill 场景触发词匹配 → 动态注入 LLMMCP 服务器外部工具服务器列表提示词模板系统提示词、分类提示词等初次部署无需修改config.yaml使用默认配置即可正常运行。5. 启动项目5.1 启动主程序python main.py启动后系统会自动进行以下工作初始化数据目录和工作区安装工作区基础 Python 包pandas、numpy 等初始化 jieba 分词初始化记忆系统、审计日志、任务调度器加载 MCP 服务器如已配置构建工具注册表终端将显示类似如下信息5.2 扫码登录系统会显示登录二维码使用手机微信扫码授权即可连接。注意同一微信账号只能绑定一个 Bot。如需更换设备请删除项目目录下的session.json文件后重新扫码。根据提示点击链接手机授权可以进行测试6. Web 管理面板可选Web 管理面板提供了可视化的配置和管理界面强烈推荐使用。6.1 构建前端首次使用需先构建前端资源cdweb/frontendnpminstallnpmrun buildcd../..前提需要已安装 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 管理MCPModel 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 等单文件大小限制50MBQ4对话能记住多少上下文短期每用户保留最近 20 条消息长期ChromaDB 向量记忆跨会话持久化超 50 条自动压缩摘要Q5可选依赖不装会影响使用吗不会。所有可选依赖均为条件导入缺少时对应功能自动降级不影响核心对话和工具调用。Q6安全机制有哪些六层防护路径沙箱、命令风险分级、AI 安全审查、审计日志、数据出境同意、剪贴板脱敏。Q7legacy 和 langgraph 后端有什么区别legacy简单循环消息 → LLM → 工具 → 回复langgraph默认推荐完整状态机支持消息分类、人机确认、中断恢复、元命令Q8pip install 安装依赖失败怎么办确认 Python 版本 ≥ 3.11尝试使用国内镜像源pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple尝试创建虚拟环境后重新安装将错误信息交给大模型辅助排查Q9如何添加新工具在tools/builtin/下新建模块注册即可被 LLM 发现。示例fromtools.baseimportToolDef,ToolResultfromtools.registryimportToolRegistrydef_my_handler(query:str,stateNone,user_id:str)-ToolResult:resultdo_something(query)returnToolResult(successTrue,contentresult)ToolRegistry.register(ToolDef(namemy_tool,description做什么用的工具。当用户说xxx时使用。,parameters{query:{type:string,description:查询关键词}},required[query],),_my_handler,)9. 扩展方向方向思路数据库查询工具直接查 MySQL/PostgreSQLBot 变身数据助手多 IM 平台扩展 channel/ 包接入 QQ/钉钉/Telegram邮件发送SMTP 发邮件Bot 变成办公助理智能家居通过 MCP 接入 Home Assistant 等平台知识库利用 ChromaDB 向量记忆构建个人知识库10. 总结本文档详细介绍了WxAgent的完整部署流程从环境准备、仓库克隆、依赖安装、项目配置到启动运行以及 Web 管理面板的构建和使用。项目具备以下特点零门槛部署纯 Python 实现无需 Docker / GPU / Node.js核心功能多模型支持兼容 OpenAI / Anthropic 等主流 API一键切换丰富的工具生态58 内置工具 MCP 动态扩展完善的安全体系六层防护机制保障本地运行安全可视化面板13 个配置页面管理便捷如果在部署过程中遇到问题欢迎提交反馈。
)
