# lisa404_claw

**Repository Path**: ichiva_admin/lisa404_claw

## Basic Information

- **Project Name**: lisa404_claw
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev-agent
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# weixin-claude-bot

通过微信消息远程操控 **Python Agent** —— 基于腾讯 iLink 协议的微信 AI Bot。

```
微信用户 ──► iLink 协议 ──► weixin-claude-bot ──► Python Agent ──► 本地文件系统/工具
   ◄────────────────────────────────────────────────────────────────────────┘
```

在地铁上用微信让 AI 帮你改代码、查日志、跑测试。

> **这是一个实验教学项目**，配套视频讲解和完整教学文档。
>
> **视频讲解**：[YouTube](https://youtu.be/-xCZ9KtaC04) | [B站](https://www.bilibili.com/video/BV18rXbBaEK7/)
>
> **教学文档**：[docs/00-overview.md](docs/00-overview.md)（iLink 协议解析、架构设计、Claude Agent SDK 深度科普、踩坑记录等）

## 前置条件

| 依赖 | 最低版本 | 说明 |
|------|---------|------|
| **Node.js** | 18+ | 运行环境 |
| **Claude Code** | 已安装并登录 | SDK 通过子进程调用 Claude Code CLI |
| **Anthropic API Key** | — | Claude Code 登录时已配置 |
| **微信** | 手机端 | 扫码登录用 |

### 安装 Node.js

```bash
# macOS (Homebrew)
brew install node

# 或使用 nvm
nvm install 18
```

### 安装 Claude Code

```bash
npm install -g @anthropic-ai/claude-agent-sdk
claude  # 首次运行会引导登录 Anthropic 账号
```

## 安装

```bash
git clone https://github.com/crazynomad/weixin-claude-bot.git
cd weixin-claude-bot
npm install
```

### 依赖说明

**运行时依赖：**

| 包名 | 用途 |
|------|------|
| `axios` | HTTP 客户端，调用 Python Agent API |
| `express` | Web 服务器，提供登录 API |
| [`weixin-ilink`](https://github.com/crazynomad/weixin-ilink) | 轻量 iLink 协议 SDK — QR 登录、消息收发、媒体上传，零运行时依赖 |
| `qrcode-terminal` | 在终端显示微信登录二维码 |

**开发依赖：**

| 包名 | 用途 |
|------|------|
| `typescript` | TypeScript 编译器 |
| `tsx` | TypeScript 即时执行（免编译运行 .ts） |
| `@types/node` | Node.js 类型声明 |

## 快速开始

### 1. 安装 Python Agent 依赖

```bash
cd agent
pip install -r requirements.txt
```

配置 Agent API 密钥（编辑 `agent/.env`）：
```bash
cp .env.example .env
# 编辑 .env 文件，设置 OPENAI_API_KEY 等
```

### 2. 启动 Python Agent 服务

```bash
cd agent
python api.py
```

服务将在 `http://127.0.0.1:8000` 启动。

### 3. 扫码登录微信

**方式一：网页登录（推荐）**

```bash
# 启动服务（首次运行会提示未找到凭证）
npm start

# 浏览器访问登录页面
http://localhost:3456/login.html
```

**方式二：命令行登录**

```bash
npm run login
```

终端会显示二维码，用微信扫码并确认。登录凭证保存在项目目录下 `.weixin-claude-bot/credentials.json`。

### 4. 配置（可选）

```bash
# 设置 Agent API 地址（如果不在默认地址）
export AGENT_API_URL="http://127.0.0.1:8000"

# 查看当前配置
npm run config

# 多轮对话（默认开启，记住上下文）
npm run config -- --multi-turn false  # 关闭
npm run config -- --multi-turn true   # 开启（默认）
```

配置保存在项目目录下 `.weixin-claude-bot/config.json`。

### 5. 启动 Bot

```bash
npm start
```

**整合式服务输出**：

```
=== 微信 Python Agent Bot 已启动 ===
账号数量: 2
  [1] e9adeb09fecc@im.bot
  [2] another-account@im.bot
Agent API: http://127.0.0.1:8000
多轮对话: 开启
等待消息中...

=== Web 服务已启动 ===
🌐 登录页面: http://localhost:3456/login.html
📡 API 端点:
   POST   http://localhost:3456/api/login
   GET    http://localhost:3456/api/login/status/:sessionId
   GET    http://localhost:3456/api/accounts

所有 2 个账号已启动监听
```

现在在微信上给 Bot 发消息就能收到 Agent 的回复了。`Ctrl+C` 停止。

### 6. 动态添加账号（运行时）

服务运行中，通过 Web 界面或 API 添加新账号，**无需重启**：

```bash
# 浏览器访问
http://localhost:3456/login.html

# 或使用 API
curl -X POST http://localhost:3456/api/login
```

## 项目结构

```
weixin-claude-bot/
├── src/
│   ├── index.ts             # 主入口：消息循环 + Web 服务器（整合）
│   ├── login.ts             # QR 扫码登录（独立脚本）
│   ├── config.ts            # 配置管理 CLI
│   ├── store.ts             # 状态持久化
│   └── agent/
│       └── handler.ts       # Python Agent HTTP API 集成
├── public/
│   └── login.html           # 网页登录界面
├── agent/                   # Python Agent（独立项目）
│   ├── agent.py             # Agent 核心逻辑
│   ├── api.py               # HTTP API 服务
│   └── requirements.txt     # Python 依赖
├── docs/                    # 教学文档
│   ├── 00-overview.md       # 文档总览
│   ├── 01-ilink-protocol.md # iLink 协议解析
│   ├── 02-architecture.md   # 架构设计与决策
│   └── ...
├── package.json
└── tsconfig.json
```

> iLink 协议层已抽离为独立 SDK [`weixin-ilink`](https://github.com/crazynomad/weixin-ilink)。如果你想基于 iLink 协议构建自己的微信 Bot（对接其他 AI、自定义业务逻辑等），可以直接使用该包，无需依赖本项目。

## 整合式架构

**单一进程，双重功能**：

```
npm start
├── 消息监听循环
│   ├── 账号 A → 处理消息 → Agent API
│   ├── 账号 B → 处理消息 → Agent API
│   └── 动态添加新账号...
└── Web 服务器 (端口 3456)
    ├── POST /api/login → 动态添加账号
    ├── GET /api/accounts → 查看在线账号
    └── GET /login.html → 网页登录界面
```

**优势**：
- ✅ 单一部署入口：`npm start` 启动所有服务
- ✅ 动态账号管理：运行时添加/移除账号，无需重启
- ✅ 资源占用低：单进程处理所有功能
- ✅ 易于部署：PM2、Docker、Systemd 都很简单

## 本地数据

所有数据存储在**项目目录下** `.weixin-claude-bot/`，不会上传到任何服务器：

| 文件 | 内容 |
|------|------|
| `credentials.json` | 微信登录凭证（bot_token） |
| `config.json` | Bot 配置（模型、参数） |
| `sync-bufs.json` | 消息游标（断点续传，多账号） |
| `context-tokens.json` | 会话令牌（per-user） |
| `session-ids.json` | Claude 会话 ID（多轮对话用） |

**路径示例**：
- Windows: `C:\Users\YourName\weixin-claude-bot\.weixin-claude-bot\`
- macOS/Linux: `/path/to/weixin-claude-bot/.weixin-claude-bot/`

删除该目录即可完全清除所有数据：
```bash
rm -rf .weixin-claude-bot/
```

## Web API 端点

### POST /api/login
生成登录二维码，自动添加新账号到监听列表

**响应**:
```json
{
  "success": true,
  "sessionId": "mob94io1jrr8g81pjes",
  "qrUrl": "https://liteapp.weixin.qq.com/q/..."
}
```

### GET /api/login/status/:sessionId
查询登录状态

**响应**:
```json
{
  "success": true,
  "status": "waiting",  // waiting | scanned | success | failed
  "qrUrl": "https://..."
}
```

### GET /api/accounts
获取当前在线账号列表

**响应**:
```json
{
  "success": true,
  "accounts": [
    {
      "accountId": "xxx@im.bot",
      "baseUrl": "https://ilinkai.weixin.qq.com",
      "userId": "xxx@im.wechat",
      "isRunning": true
    }
  ]
}
```

## 生产部署

### PM2（推荐）

```bash
# 安装 PM2
npm install -g pm2

# 启动
pm2 start npm --name "weixin-bot" -- start

# 查看状态
pm2 status

# 查看日志
pm2 logs weixin-bot

# 自动重启
pm2 startup
pm2 save
```

### Docker

```dockerfile
FROM node:20
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
CMD ["npm", "start"]
```

```bash
# 构建
docker build -t weixin-bot .

# 运行
docker run -d -p 3456:3456 --name weixin-bot weixin-bot
```

### Systemd（Linux）

```ini
[Unit]
Description=Weixin ClawBot
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/weixin-claude-bot
ExecStart=/usr/bin/npm start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

## 注意事项

- **iLink 协议是实验性的** — 腾讯未正式公开文档，API 可能随时变更，不建议用于生产环境
- **权限模式** — 默认使用 `bypassPermissions` 模式，跳过权限检查。如果需要更安全的模式，可修改配置
- **Token 会过期** — 出现 session 过期提示时，通过 Web 界面重新登录
- **Web 服务端口** — 默认 3456，可通过环境变量 `WEB_PORT` 修改

## 背景

本项目基于对 `@tencent-weixin/openclaw-weixin` npm 包（MIT License）的源码分析构建。该包实现了 iLink Bot 协议，让第三方开发者能通过标准 HTTP 与微信交互。iLink 协议通讯层已独立封装为 [`weixin-ilink`](https://github.com/crazynomad/weixin-ilink) SDK。

详细的协议分析和构建过程记录在 [docs/](docs/00-overview.md) 目录中。

## License

MIT