桌面客户端

• 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 重量

| 对比维度 | OpenClaw | 本项目 (WeChat Claude Code Bot) | |---------|----------|-------------------------------| | 定位 | 通用 AI 智能体框架，支持多种模型和插件 | 专注一件事：微信连本机 AI 引擎 | | 安装 | 框架本身 + API Key + 模型配置 + 插件系统 + 依赖链 | 3 步：git clone → pip install → python main.py | | 依赖 | 框架庞大，依赖众多，安装易出问题 | 5 个核心依赖（PyQt6 / requests / cryptography / qrcode / python-dotenv） | | 维护 | 框架更新频繁，需跟进升级，版本兼容容易踩坑 | 代码简洁透明，核心逻辑约 3600 行 |

Token 成本

这是最关键的区别：

| | OpenClaw | 本项目 | |-|----------|--------| | 计费方式 | 每次对话调用 Claude API，按 Token 计费 | 使用本机 Claude Code CLI，走订阅额度 | | 成本特点 | 长对话、代码分析、多轮交互 Token 消耗大，费用不可控 | 零额外 Token 费用，已有 Claude Code 订阅即可 | | API Key | 必须配置 | Claude Code 引擎不需要（其他引擎可选） |

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 文件或环境变量配置：

| 变量 | 说明 | 默认值 | |------|------|--------| | CLAUDE_CWD | Claude Code 的默认工作目录 | 当前工作目录 |

每个用户可通过 /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: [显示日志...]

命令列表

| 命令 | 说明 | |------|------| | /help | 显示帮助信息 | | /new | 重置对话，开始新会话 | | /model | 切换模型（sonnet / opus / haiku），默认 Sonnet | | /cwd <路径> | 切换工作目录/项目（每用户独立） | | /send <路径> | 发送本机文件到微信（支持图片、文件、视频，上限 50MB） | | /send <路径> \| 说明 | 带说明文字发送 | | /status | 查看 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