Skip to content

README.md

Latest commit

 

History

History
244 lines (191 loc) · 5.75 KB

README.md

File metadata and controls

244 lines (191 loc) · 5.75 KB

OpenClaw Email Plugin

📧 OpenClaw 邮箱插件 - 支持 IMAP/SMTP、邮件 Relay 和本地 RAG 知识库（使用 FAISS 向量搜索）

功能特性

  • ✅ IMAP 收信 - 连接任意 IMAP 邮箱读取邮件
  • ✅ SMTP 发信 - 通过 SMTP 发送邮件
  • ✅ FAISS RAG 知识库 - 使用 Facebook FAISS 进行向量语义搜索
  • ✅ 本地缓存 - 所有邮件向量化后本地存储，保护隐私
  • ✅ GPU 加速 - 支持 ONNX Runtime GPU 加速（可选）
  • ✅ 语义搜索 - 支持自然语言搜索邮件

快速开始

前置要求

  • Node.js 18+
  • Python 3.8+
  • (可选) CUDA 12.x + cuDNN 9.x - 用于 GPU 加速

1. 安装

# 克隆仓库
git clone https://github.com/your-repo/openclaw-plugin-email.git
cd openclaw-plugin-email

# 安装依赖
npm install

2. 下载模型

# 自动下载模型（需要 Hugging Face 访问）
npm run download-model

# 或使用镜像
HF_ENDPOINT=https://hf-mirror.com npm run download-model

模型会自动下载到 ~/models/embedding/bge-small-zh-v1.5-onnx/

3. 构建

npm run build

4. 配置

创建或编辑 ~/.openclaw/openclaw.json，添加插件配置：

{
  "plugins": {
    "allow": ["email"],
    "load": {
      "paths": ["/path/to/openclaw-plugin-email"]
    },
    "entries": {
      "email": {
        "enabled": true,
        "config": {
          "modelPath": "~/models/embedding/bge-small-zh-v1.5-onnx/onnx/model_quantized.onnx",
          "useGpu": false,
          "syncInterval": 300000,
          "accounts": [
            {
              "id": "my-email",
              "name": "我的邮箱",
              "email": "your-email@example.com",
              "imap": {
                "host": "imap.example.com",
                "port": 993,
                "secure": true
              },
              "smtp": {
                "host": "smtp.example.com",
                "port": 465,
                "secure": true
              },
              "auth": {
                "user": "your-email@example.com",
                "pass": "YOUR_APP_PASSWORD"
              },
              "rag": {
                "enabled": true,
                "indexPath": "~/.openclaw/plugins/email/faiss-index"
              }
            }
          ]
        }
      }
    }
  }
}

配置说明：

配置项 类型 默认值 说明
modelPath string ~/models/embedding/bge-small-zh-v1.5-onnx/onnx/model_quantized.onnx ONNX 模型文件路径
useGpu boolean false 是否使用 GPU 加速
syncInterval number 300000 自动同步间隔（毫秒）
accounts array [] 邮箱账户列表

账户配置说明：

配置项 说明
id 账户唯一标识
name 显示名称
email 邮箱地址
imap.host IMAP 服务器地址
imap.port IMAP 端口（通常 993）
imap.secure 是否使用 SSL/TLS
smtp.host SMTP 服务器地址
smtp.port SMTP 端口（通常 465）
smtp.secure 是否使用 SSL/TLS
auth.user 用户名（通常是完整邮箱地址）
auth.pass 应用专用密码（非登录密码）
rag.enabled 是否启用 RAG 索引
rag.indexPath FAISS 索引存储路径

5. 链接到 OpenClaw

# 在插件目录创建链接
npm link

# 在 OpenClaw 目录链接插件
cd ~/.npm-global/lib/node_modules/openclaw
npm link @openclaw/email

# 或直接将插件复制到 OpenClaw 插件目录
cp -r /path/to/openclaw-plugin-email ~/.config/openclaw/extensions/email

6. 重启 OpenClaw

systemctl --user restart openclaw-gateway.service

可用工具

插件提供以下工具供 OpenClaw AI 调用：

工具 说明
email_search 语义搜索邮件
email_get 获取邮件详情
email_get_by_index 按搜索结果序号获取邮件
email_get_recent 获取最近邮件
email_get_by_date_range 按日期范围查询邮件
email_search_by_date_range 按日期范围语义搜索
email_send 发送邮件
email_sync 手动同步邮件
email_list_accounts 列出账户
email_rag_stats RAG 索引统计
email_gpu_status GPU 状态

使用示例

# 搜索邮件
/agent 帮我找一下上周关于项目进度的邮件

# 发送邮件
/agent 给 team@example.com 发个邮件，主题是"会议通知"

# 查看本周邮件
/agent 本周都有哪些邮件

# 按日期范围搜索
/agent 帮我找3月份关于GPU的邮件

开发

# 开发模式（监听编译）
npm run dev

# 运行测试
npm test

# 代码检查
npm run lint

目录结构

openclaw-plugin-email/
├── src/
│   ├── index.ts              # 插件入口
│   ├── services/
│   │   └── email-service.ts  # IMAP/SMTP 服务
│   ├── rag/
│   │   └── rag-service.ts    # FAISS RAG 服务
│   └── embeddings/
│       └── gpu-embedding-service.ts  # ONNX 嵌入服务
├── scripts/
│   └── embedding-service.py  # Python 嵌入服务
├── dist/                     # 编译输出
├── package.json
├── tsconfig.json
└── README.md

常见问题

1. 邮件同步失败

检查：

  • IMAP/SMTP 配置是否正确
  • 账户密码是否为应用专用密码（非登录密码）
  • 网络是否可达

2. 搜索结果为空

确保已同步邮件：email_sync

3. GPU 加速无效

确认：

  • CUDA 和 cuDNN 已正确安装
  • ONNX Runtime 支持 CUDA
  • 配置中 useGpu: true

4. Schema 验证错误

如果遇到 "schema invalid" 错误，尝试重启 OpenClaw：

systemctl --user restart openclaw-gateway.service

许可证

MIT