微信 AI 助手

跟普通聊天机器人的区别？ CowAgent/QClaw 只能文字对话。本项目通过 Claude Code / Open Interpreter 让 AI 真正操作你的电脑——读写文件、执行命令、修改代码、运行测试。PyQt6 桌面客户端，支持多 AI 引擎切换，极简高级设计风格。

目录

• 功能特性
• 为什么不直接用 OpenClaw？
• 微信连接方式
• 工作原理
• 快速开始
• 配置说明
• 使用指南
• 用户场景
• 命令列表
• 项目结构
• 常见问题

功能特性

核心能力

• 微信远程操控 — 通过微信消息直接操控本机 Claude Code，无需打开电脑终端
• 退出微信也能用 — 基于服务端长轮询，关闭微信 App 后消息仍会排队，重新打开即可收到回复，Bot 7×24 不间断运行
• 完整电脑操作能力 — Claude Code 能真正操作你的电脑：读写任意文件、执行任意终端命令、搜索代码、安装依赖、Git 操作等，不只是聊天
• 直接操作真实项目 — Claude Code 运行在你的本机项目目录中，直接修改真实代码文件，改完即生效
• 多 AI 引擎 — 三个适配器可选：Claude Code CLI（完整电脑操控）、Open Interpreter（多模型支持）、纯 API（Anthropic/OpenAI/DeepSeek 对话）

交互体验

• 实时进度反馈 — Claude Code 读文件、写代码、执行命令时，实时推送进度到微信（如 📖 正在读取文件: src/app.js）
• 思考状态提示 — 处理前 3 秒内推送"🧠 正在思考..."，配合 Typing 状态让用户知道 Bot 在工作
• 文件自动发回 — Claude Code 读取、创建的图片/PDF/文档/视频会自动发送到微信，无需手动操作
• 图片/文件/视频接收 — 接收微信发来的图片、文件、视频，自动下载并交给 AI 分析（PDF 总结、CSV 分析数据、代码审查等）
• 智能消息拆分 — 长回复自动按代码块边界智能拆分，分片标注序号
• Markdown 转换 — 自动将 Claude 的 Markdown 输出转为微信友好的纯文本格式
• 语音消息支持 — 支持微信语音转文字，自动标注语音来源提高容错
• 斜杠命令 — /new 重置对话、/model 切换模型、/cwd 切换项目目录、/send 发送文件、/status 查看状态

桌面客户端

• PyQt6 原生 GUI — 极简高级设计风格（受 Linear/Raycast/Apple 启发），不是终端工具
• 实时操作视图 — 看到 AI 正在做什么：读了哪些文件、执行了什么命令、写了哪些代码
• 引擎切换 — 在 GUI 设置中切换 AI 引擎和模型，无需重启
• 系统托盘 — 最小化到托盘后台运行，双击恢复

稳定性与安全

• 多用户会话隔离 — 每个微信用户独立 session，对话上下文连续，互不干扰
• 并发控制 — 最多同时处理 3 个任务，超出提示"请稍等"
• 会话永久保持 — 会话不设过期时间，上下文持续保持（和 VS Code 中使用 Claude Code 体验一致）
• 会话持久化 — sessionId 保存到磁盘，重启后自动恢复，不丢上下文
• 自动重连 — Token 过期自动重新扫码登录，Token 持久化免重复扫码
• 超时保护 — 5 分钟无响应强制结束，返回已有的部分结果
• 优雅退出 — 关闭窗口最小化到托盘，退出时自动清理所有子进程
• 本机运行 — 代码和数据不经过任何第三方服务器，凭据文件权限仅 owner 可读写

为什么不直接用 OpenClaw？

微信官方的 OpenClaw 是一个功能丰富的 AI 智能体框架，支持接入多种模型后端并通过 ClawBot 协议连接微信。它是一个完整的平台级方案，适合需要自定义 AI 能力的场景。

但如果你的目标是 通过微信远程操控本机 Claude Code，OpenClaw 并不是最优解。以下是两者的核心差异：

轻量 vs 重量

Token 成本

这是最关键的区别：

Claude Code 的独特能力

本项目之所以选择连接 Claude Code CLI 而非直接调 API，是因为 Claude Code 本身提供了 API 调用无法替代的能力：

• 完整电脑操控 — 读写任意文件、执行任意终端命令、搜索整个代码库，不是简单的文字对话
• 项目级上下文 — 整个项目目录都是 Claude Code 的上下文，它能理解完整的代码库结构
• 10+ 内置工具 — Read、Write、Edit、Bash、Glob、Grep、WebSearch 等，工具链完整
• 真正的代码操作 — 直接修改真实文件、执行 Git 操作、安装依赖，改完即生效
• 实时进度反馈 — 每一步操作（读文件、执行命令、编辑代码）都实时推送到微信
• 会话连续 — 独立 session 管理，对话上下文跨多轮保持

这些能力通过 API 调用 + 自行实现工具链也能做到，但 Claude Code CLI 已经是一个打磨好的成熟产品，没必要重复造轮子。

一句话总结

OpenClaw = 功能齐全的 AI 框架，适合需要自定义 AI 能力的通用场景，但重、贵、装起来费劲

本项目 = 轻量 Python 桌面客户端、零额外成本、专注做一件事：让你在微信里远程操控 AI

怎么选

• 想搭建通用 AI 微信机器人，接入不同模型、自定义插件 → OpenClaw
• 想通过微信远程操控电脑、修改代码、执行命令 → 本项目
• 已经有 Claude Code 订阅，想零成本获得微信远程控制能力 → 本项目

微信连接方式

本项目基于微信官方 iLink Bot (ClawBot) 协议，通过微信扫码建立连接：

启动客户端后 GUI 显示二维码，用微信扫码即可连接。连接后即使退出微信，Bot 仍持续运行并处理消息，重新打开微信即可看到回复。

工作原理

┌──────────┐         ┌──────────────────┐         ┌───────────────┐
│  微信用户  │ ──消息──▶│  iLink Bot API   │ ──轮询──▶│  本机 Bot      │
│  (手机端)  │ ◀─回复── │ (weixin.qq.com)  │ ◀─发送── │ (PyQt6 客户端) │
└──────────┘         └──────────────────┘         └──────┬────────┘
                                                         │
                                                         │ 调用适配器
                                                         ▼
                                              ┌─────────────────────┐
                                              │  Claude Code CLI    │
                                              │  Open Interpreter   │
                                              │  Direct API         │
                                              │  (三选一)            │
                                              └─────────────────────┘

1. Bot 通过微信 iLink Bot API（长轮询）接收用户消息
2. 将消息转发给当前选择的 AI 引擎（默认 Claude Code CLI，stream-json 模式）
3. 实时解析 AI 的工具调用（读文件、写代码、执行命令等），推送进度到微信
4. AI 完成后，将最终结果格式化发送回微信，创建的文件自动发回

快速开始

前置条件

• Python >= 3.11
• Claude Code CLI 已安装（npm install -g @anthropic-ai/claude-code）— 使用 Claude Code 引擎时需要
• 微信账号

安装步骤

# 1. 克隆项目
git clone https://github.com/mrliuzhiyu/Wechat-Claude-bot.git
cd Wechat-Claude-bot

# 2. 安装依赖
pip install -r requirements.txt

# 3. (可选) 配置工作目录
cp .env.example .env
# 编辑 .env 设置 CLAUDE_CWD 为你的项目路径

# 4. 启动客户端
python main.py

首次连接

1. 启动后 GUI 会进行环境检测（检查 Claude CLI、网络连接等）
2. 检测通过后显示二维码
3. 打开微信 → 扫描二维码 → 确认连接
4. 进入操作视图后即可使用
5. 在微信中直接发消息给 Bot 即可

首次登录后 Token 会自动保存，下次启动无需重复扫码（除非 Token 过期）。

配置说明

环境变量

通过 .env 文件或环境变量配置：

每个用户可通过 /cwd 命令独立切换工作目录，不影响其他用户。默认模型为 Sonnet。

GUI 设置

在客户端设置页面可以：

• 切换 AI 引擎（Claude Code / Open Interpreter / Direct API）
• 选择模型（Sonnet / Opus / Haiku）
• 配置 API Key（Open Interpreter 和 Direct API 引擎需要）
• 修改工作目录
• 清除用户会话

使用指南

基本用法

在微信中直接用自然语言描述你的需求，Claude Code 会自动执行：

你: 看看项目结构
Bot: 🤖 收到，正在处理...
Bot: 🔍 正在搜索文件: **/*
Bot: 项目结构如下：
     ├── src/
     │   ├── components/
     │   ├── pages/
     │   └── utils/
     ├── package.json
     └── README.md

实时进度

Claude Code 执行操作时，你会收到实时进度反馈：

📖 正在读取文件: src/app.js
✏️ 正在编辑文件: src/utils.js
⚡ 正在执行命令: npm test
🔍 正在搜索文件: **/*.ts
🔍 正在搜索内容: handleClick
📝 正在创建文件: src/helper.js
📋 正在规划任务

长消息处理

当 Claude Code 的回复超过 4000 字时，消息会被智能拆分：

• 优先在代码块边界断开
• 其次在空行断开
• 每个分片标注序号，如 (续 2/3)

用户场景

场景 1：通勤路上修 Bug

同事反馈线上有个紧急 Bug，你正在地铁上。

你: 看看 src/api/auth.js 的 login 函数
Bot: [显示代码内容]

你: 第 42 行的 token 校验逻辑有问题，过期时间应该用 > 而不是 >=
Bot: ✏️ 正在编辑文件: api/auth.js
Bot: 已修改，将 >= 改为 >

你: 跑一下测试
Bot: ⚡ 正在执行命令: npm test
Bot: 全部 23 个测试通过 ✓

你: 提交改动，消息写"fix: 修复 token 过期判断边界条件"
Bot: 已提交并推送到远程仓库

场景 2：手机上开发新功能

周末在外面，突然有个灵感想快速加个功能。

你: 在 src/components 下创建一个 ThemeToggle 组件，支持深色/浅色模式切换
Bot: 📝 正在创建文件: components/ThemeToggle.jsx
Bot: ✏️ 正在编辑文件: App.jsx
Bot: 已创建 ThemeToggle 组件并在 App.jsx 中引入...

场景 3：代码审查和学习

接手一个新项目，想快速了解代码结构。

你: 这个项目的整体架构是什么样的？
Bot: [分析项目结构、主要模块、技术栈...]

你: 数据库连接的逻辑在哪里？
Bot: 🔍 正在搜索内容: database|connection|mongoose
Bot: 数据库连接在 src/config/db.js 中...

场景 4：运维和监控

在外面需要检查服务状态。

你: 看看 docker 容器运行状态
Bot: ⚡ 正在执行命令: docker ps
Bot: [显示容器列表...]

你: 看看最近的日志有没有报错
Bot: ⚡ 正在执行命令: docker logs --tail 50 my-app
Bot: [显示日志...]

命令列表

除斜杠命令外，所有消息都会发送给 AI 引擎处理。Claude Code 读取或创建的媒体文件会自动发送到微信。

项目结构

Wechat-Claude-bot/
├── main.py              # PyQt6 应用入口
├── core/                # 核心逻辑
│   ├── config.py        # 全局配置（路径、常量、模型定义）
│   ├── weixin_api.py    # 微信 iLink Bot API 封装
│   ├── media.py         # 媒体收发（CDN + AES-128-ECB 加解密）
│   └── bot_engine.py    # Bot 引擎（消息路由、会话管理、并发控制）
├── adapters/            # AI 模型适配器
│   ├── base.py          # 抽象基类 ModelAdapter
│   ├── claude_code.py   # Claude Code CLI 适配器
│   ├── open_interpreter.py  # Open Interpreter 适配器
│   ├── direct_api.py    # 纯 API 适配器（Anthropic/OpenAI/DeepSeek）
│   └── registry.py      # 适配器注册中心（工厂 + 引擎检测）
├── ui/                  # PyQt6 界面
│   ├── main_window.py   # 主窗口（5 视图 + 自定义组件）
│   └── theme.py         # 极简高级主题（颜色令牌 + QSS）
├── requirements.txt     # Python 依赖
├── .env.example         # 环境变量示例
├── DESIGN.md