# Wechat-GPT

**Repository Path**: lasuy/wechat-gpt

## Basic Information

- **Project Name**: Wechat-GPT
- **Description**: WeChat GPT Bot 是一个基于 Go 开发的智能微信机器人系统，通过桌面微信协议接入微信，支持私聊与群聊自动回复，并兼容 OpenAI 接口及图像生成能力。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WeChat GPT Bot

一个以 Go 为核心、通过桌面微信协议运行的智能微信机器人。项目同时内置 Streamlit 管理后台，用于查看登录状态、维护系统提示词、管理自动化任务和切换文本模型。

> 本项目依赖非官方微信协议。请遵守微信平台规则，仅在自有账号和可信环境中使用。频繁登录、批量发送或异常自动化行为可能触发风控。

## 项目说明

本项目基于 [code-innovator-zyx/wechat-gptbot](https://github.com/code-innovator-zyx/wechat-gptbot) 进行二次开发，并在原有微信机器人能力上持续完善后台管理、提示词配置、消息工具和部署流程。

- **当前项目**：[gitee.com/lasuy/wechat-gpt](https://gitee.com/lasuy/wechat-gpt)
- **参考项目**：[github.com/code-innovator-zyx/wechat-gptbot](https://github.com/code-innovator-zyx/wechat-gptbot)

感谢原项目作者及其依赖的开源社区。本仓库后续功能、界面与部署说明以当前 Gitee 版本为准。

## 功能概览

- 微信扫码登录与 `token.json` 热登录
- 私聊自动回复，群聊支持 `@机器人` 或配置触发词唤醒
- 按联系人隔离的多轮对话上下文
- OpenAI 兼容接口，可分别配置文本与图片模型的令牌和代理地址
- 文生图回复，并自动处理图片下载与压缩
- 模型工具调用：读取近期私聊/群聊消息，以及向好友或群聊转发文本、图片、视频和文件
- 天气预报、新闻/RSS 和 Zepp Life 运动步数定时任务
- Streamlit 管理后台：登录状态、提示词、自动化接收人、执行时间、RSS 和文本模型管理
- Windows PowerShell、Make 和 Docker Compose 三种运行方式

## 系统结构

| 组件 | 默认地址 | 作用 |
| --- | --- | --- |
| Go 主进程 | 本地进程 | 微信登录、消息分发、模型调用和定时任务 |
| Gin API | `127.0.0.1:8502` | 为管理后台提供状态与配置接口 |
| Streamlit | `127.0.0.1:8501` | 管理后台；Docker 中监听 `0.0.0.0:8501` |

Go 主进程会同时启动 API 和 Streamlit 子进程，因此正常使用时只需要启动一次 `wechat-gptbot`。

## 环境要求

本地运行需要：

- Go 1.20 或更高版本
- Python 3.9 或更高版本
- 可访问所配置模型接口的网络环境
- 一个可扫码登录的微信账号

容器运行需要 Docker Desktop 或 Docker Engine，并启用 Docker Compose。

## 快速开始

### Windows

```powershell
git clone https://gitee.com/lasuy/wechat-gpt.git
cd wechat-gpt

# 本机没有 Go 时，可在项目内安装便携版 Go
.\make.ps1 bootstrap

# 生成缺失的配置文件
.\make.ps1 init
```

编辑 `config/config.json`、`config/prompt.conf` 和 `config/cron.json` 后启动：

```powershell
.\make.ps1 local
```

首次执行会创建 `.venv`、安装 Python 依赖、下载 Go 依赖并构建 `wechat-gptbot.exe`。后续可使用后台模式：

```powershell
.\make.ps1 start
.\make.ps1 stop
```

### Linux / macOS

```bash
git clone https://gitee.com/lasuy/wechat-gpt.git
cd wechat-gpt
make init
```

完成配置后运行：

```bash
make local
```

### Docker

项目使用 `build.yaml` 从当前源码构建镜像：

```bash
make init
# 修改 config/ 下的配置文件
docker compose -f build.yaml up --build -d
```

常用容器命令：

```bash
docker compose -f build.yaml ps
docker compose -f build.yaml logs -f --tail=100
docker compose -f build.yaml down
```

容器会挂载 `config/` 和 `token.json`，升级或重启后可保留配置及微信登录状态。

## 基础配置

初始化命令会从模板创建以下文件，但不会覆盖已有配置：

| 文件 | 用途 | 是否纳入 Git |
| --- | --- | --- |
| `config/config.json` | 模型接口、触发词、上下文和默认模型 | 否 |
| `config/prompt.conf` | 全局系统提示词 | 否 |
| `config/cron.json` | 天气、新闻和运动任务 | 否 |
| `token.json` | 微信热登录状态 | 否 |

`config/config.json` 示例：

```json
{
  "gpt": {
    "text_config": {
      "proxy_url": "https://api.openai.com/v1",
      "auth_token": "YOUR_API_KEY",
      "trigger_prefix": "助手"
    },
    "image_config": {
      "proxy_url": "https://api.openai.com/v1",
      "auth_token": "YOUR_API_KEY",
      "trigger_prefix": "画图"
    }
  },
  "context_status": true,
  "base_model": "gpt-4o"
}
```

| 配置项 | 说明 |
| --- | --- |
| `proxy_url` | OpenAI 兼容接口地址；留空时使用 SDK 默认地址 |
| `auth_token` | 对应接口的访问令牌，不能为空 |
| `trigger_prefix` | 群聊触发词；私聊无需触发词 |
| `context_status` | 是否为每个联系人保留独立对话上下文 |
| `base_model` | 当前文本模型，可在管理后台切换 |

`config/prompt.conf` 中的第一个 `%s` 会注入可用插件描述。自定义提示词时如需继续使用天气和新闻插件，请保留该占位符。

定时任务使用六段 Quartz Cron 表达式。更推荐在管理后台使用自然语言修改执行时间，后端会生成并保存对应表达式。

## 管理后台

服务启动后访问 [http://127.0.0.1:8501](http://127.0.0.1:8501)。默认管理员账号为 `admin`，默认密码为 `admin777`。

后台包含以下页面：

- **控制台**：查看管理端、微信会话、消息通道和配置通道状态
- **提示词管理**：编辑、保存或恢复默认系统提示词，保存后对后续会话生效
- **自动化管理**：维护天气、新闻/RSS、Zepp Life 运动任务的执行时间和接收人
- **模型管理**：查看文本/图片模型，并切换当前文本模型

生产环境部署前必须修改 `.streamlit/secrets.toml` 中的管理密码，并避免将真实密码提交到公开仓库。管理后台能够修改运行配置并访问联系人信息，不应直接暴露到公网；建议通过防火墙、VPN 或带身份认证的反向代理限制访问。

如需让本地运行的后台监听其他网卡，可调整 `.streamlit/config.toml` 的 `server.address`。Docker 模式已经通过环境变量监听 `0.0.0.0`。

## 微信消息规则

- 私聊：普通文本会直接进入模型对话，公众号消息和机器人自己发送的消息会被忽略。
- 群聊：`@机器人`、文本触发词或图片触发词可以唤醒机器人。
- 上下文：启用后按发送者昵称隔离，最多保留近期会话记录。
- 图片：以图片触发词开头的请求使用 DALL-E 3 生成图片。
- 工具调用：支持读取机器人进程启动后捕获的近期消息，并按好友或群名称转发消息。

消息工具具备读取和转发能力。请在系统提示词中明确授权边界，不要让不可信群成员触发涉及隐私或外发数据的操作。

## 自动化任务

| 通道 | 可配置内容 |
| --- | --- |
| 天气 | 执行时间、微信接收人、查询城市 |
| 新闻 | 执行时间、用户/群接收范围、RSS 地址、推送条数 |
| 运动 | 执行时间、微信接收人、Zepp Life 账号、密码和步数区间 |

运动账号密码会保存在本地 `config/cron.json`。请限制该文件的读取权限，不要提交到代码仓库。

## 常用命令

Windows：

```powershell
.\make.ps1 help       # 查看命令
.\make.ps1 init       # 初始化配置
.\make.ps1 local      # 安装依赖、构建并前台运行
.\make.ps1 start      # 后台启动已构建程序
.\make.ps1 stop       # 停止后台程序
.\make.ps1 docker     # 构建并启动容器
.\make.ps1 logs       # 查看容器日志
.\make.ps1 test       # 运行 Go 测试
.\make.ps1 clean      # 删除本地构建产物
```

Linux / macOS：

```bash
make help
make init
make local
make docker
make logs
make status
make down
make test
make clean
```

## 项目目录

```text
.
├── config/                 # 基础配置、提示词和定时任务
├── core/
│   ├── cron/               # 定时任务调度
│   ├── gpt/                # 模型客户端与会话管理
│   ├── handler/            # 微信消息处理与工具调用
│   └── plugins/            # 天气、新闻和运动插件
├── server/                 # Gin API 与控制器
├── streamlit_app/          # Streamlit 管理后台
├── .streamlit/             # Streamlit 主题、路由和登录配置
├── make.ps1                # Windows 管理脚本
├── makefile                # Linux/macOS 管理脚本
├── build.yaml              # 源码构建用 Compose 配置
└── dockerfile              # Go + Python 多阶段镜像
```

## 故障排查

### 后台提示 API 不可用

确认 Go 主进程仍在运行，并检查 `8502` 端口是否被占用。若通过环境变量修改 API 端口，需要同时设置 `APIPORT` 供 Streamlit 使用。

### Streamlit 没有启动

本地模式需要能在当前 `PATH` 中找到 `streamlit`。Windows 用户可重新执行 `.\make.ps1 local` 创建虚拟环境并安装依赖。

### 微信反复要求扫码

确认 `token.json` 可写且没有被清空。Docker 部署时应持续挂载该文件；登录状态失效后仍需重新扫码。

### 模型请求失败

检查 `auth_token`、`proxy_url` 和 `base_model` 是否被当前 OpenAI 兼容服务支持，同时检查网络和服务端日志。

## License

本项目采用 [Apache License 2.0](LICENSE)。