openclawwechat 1.0.4

package/CONFIG.md

@@ -0,0 +1,171 @@
+# OpenClawWeChat 插件配置说明
+
+## 📋 快速开始
+
+### 🔑 获取 API Key
+
+在开始配置之前，你需要先获取 API Key：
+
+1. 打开微信小程序 **ClawChat**
+2. 进入我的页面 APIKey管理  复制API Key 
+3. 找到并复制你的 API Key（格式：`bot_id:secret`）
+
+> 💡 **提示：** API Key 是连接 OpenClaw 和微信小程序的凭证，请妥善保管。
+
+### 推荐方式：使用配置脚本（最简单）
+
+```bash
+npm run config-init
+# 或
+node scripts/config-init.js
+```
+
+脚本会引导你完成配置，**只保存你自定义的配置项**，使用默认值的配置不会写入文件。
+
+### 手动配置
+
+配置文件位置：`~/.openclaw/openclaw.json`
+
+## ⚙️ 配置项说明
+
+| 配置项 | 类型 | 必需 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `apiKey` | string | ✅ 是 | `YOUR_API_KEY_HERE` | API Key（格式：`bot_id:secret`） |
+| `pollIntervalMs` | number | ❌ 否 | `2000` | 轮询间隔（毫秒） |
+| `sessionKeyPrefix` | string | ❌ 否 | `agent:main:wechat:miniprogram:` | Session Key 前缀 |
+| `debug` | boolean | ❌ 否 | `false` | 是否启用调试日志 |
+
+**重要提示：**
+- ✅ **只配置需要自定义的项**，使用默认值的配置**不需要写入**配置文件
+- ✅ OpenClaw 会自动从插件清单中读取默认值
+- ✅ 配置文件更简洁，只显示你自定义的配置
+
+## 📝 配置示例
+
+### 最小配置（推荐）
+
+如果你只配置 API Key，其他使用默认值：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclawwechat": {
+        "enabled": true,
+        "config": {
+          "apiKey": "20231227:EXAMPLE_SECRET_KEY_35_CHARS_LONG_12345"
+        }
+      }
+    }
+  }
+}
+```
+
+### 自定义部分配置
+
+如果你修改了轮询间隔：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclawwechat": {
+        "enabled": true,
+        "config": {
+          "apiKey": "20231227:EXAMPLE_SECRET_KEY_35_CHARS_LONG_12345",
+          "pollIntervalMs": 3000
+        }
+      }
+    }
+  }
+}
+```
+
+### 自定义多个配置
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclawwechat": {
+        "enabled": true,
+        "config": {
+          "apiKey": "20231227:EXAMPLE_SECRET_KEY_35_CHARS_LONG_12345",
+          "pollIntervalMs": 3000,
+          "debug": true
+        }
+      }
+    }
+  }
+}
+```
+
+## 🔑 API Key 格式
+
+**获取方式：** API Key 需要从**微信小程序 ClawChat** 中获取。
+
+API Key 格式：`<bot_id>:<secret>`
+
+**示例：** `20231227:EXAMPLE_SECRET_KEY_35_CHARS_LONG_12345`
+
+- `bot_id`: 数字id
+- `secret`: 35 位随机字符串
+
+> 💡 **提示：** 打开微信小程序 ClawChat，在设置或账户页面可以找到你的 API Key。
+
+## 🔧 配置方法
+
+### 方法 1：使用配置脚本（推荐）
+
+```bash
+# 在插件目录下运行
+npm run config-init
+# 或
+node scripts/config-init.js
+```
+
+脚本会：
+- ✅ 交互式引导配置
+- ✅ 验证 API Key 格式
+- ✅ 自动过滤默认值
+- ✅ 只保存你自定义的配置
+
+### 方法 2：手动编辑配置文件
+
+```bash
+# 编辑配置文件
+nano ~/.openclaw/openclaw.json
+# 或
+code ~/.openclaw/openclaw.json
+```
+
+**提示：** 手动编辑时，只需添加需要自定义的配置项，默认值不需要写入。
+
+## ✅ 验证配置
+
+配置完成后，重启 OpenClaw Gateway：
+
+```bash
+openclaw gateway restart
+```
+
+查看日志确认插件已加载：
+
+```bash
+openclaw logs --follow | grep "openclawwechat"
+```
+
+进入小程序，查看链接状态，或者测试发送。
+
+## 💡 配置最佳实践
+
+1. **使用配置脚本**：推荐使用 `config-init.js` 脚本，避免手动编辑错误
+2. **最小化配置**：只配置需要自定义的项，让配置文件保持简洁
+3. **默认值管理**：默认值由插件清单统一管理，修改默认值时只需更新 `openclaw.plugin.json`
+4. **配置验证**：配置脚本会自动验证 API Key 格式，确保配置正确
+
+## 📚 相关文档
+
+- [README.md](./README.md) - 插件使用说明
+- [CONFIG-INIT.md](./CONFIG-INIT.md) - 配置脚本使用指南
+- [INSTALL.md](./INSTALL.md) - 安装指南

package/INSTALL.md

@@ -0,0 +1,230 @@
+# OpenClawWeChat 插件安装指南
+
+## 📋 前置要求
+
+- OpenClaw 已安装并配置
+- Python 3.x 或 Bash（用于运行安装脚本）
+- 有效的 API Key（格式：`bot_id:secret`）
+  - 💡 **获取方式：** 打开微信小程序 **ClawChat**，在设置或账户页面可以找到你的 API Key
+
+## 🚀 快速安装
+
+### 方法一：使用安装脚本（推荐）
+
+安装脚本会自动完成插件安装和配置，是最简单的方式。
+
+#### Bash 脚本（Linux/macOS）
+
+```bash
+cd OpenClawWeChat
+./install.sh "your_bot_id:your_secret"
+```
+
+#### Python 脚本（跨平台）
+
+```bash
+cd OpenClawWeChat
+python3 install.py "your_bot_id:your_secret"
+```
+
+### 方法二：手动安装
+
+如果不想使用安装脚本，可以手动安装：
+
+```bash
+# 1. 安装插件
+openclaw plugins install /path/to/OpenClawWeChat
+
+# 2. 编辑配置文件 ~/.openclaw/openclaw.json
+# 添加插件配置（见下方配置示例）
+
+# 3. 重启 Gateway
+openclaw gateway restart
+```
+
+## ⚙️ 安装脚本选项
+
+### 基本用法
+
+```bash
+# 交互式输入 API Key
+./install.sh
+
+# 直接提供 API Key
+./install.sh "20231227:EXAMPLE_SECRET_KEY_35_CHARS_LONG_12345"
+```
+
+### 高级选项
+
+```bash
+# 从 NPM 安装（如果已发布）
+./install.sh "your_api_key" --method npm
+
+# 自定义轮询间隔（毫秒）
+./install.sh "your_api_key" --poll-interval 3000
+
+# 自定义 Session Key 前缀
+./install.sh "your_api_key" --session-prefix "custom:prefix:"
+
+# 启用调试日志
+./install.sh "your_api_key" --debug
+
+# 只更新配置（不安装插件）
+./install.sh "your_api_key" --skip-install
+
+# 查看帮助
+./install.sh --help
+```
+
+## 📝 配置说明
+
+安装脚本会自动在 `~/.openclaw/openclaw.json` 中添加以下配置：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclawwechat": {
+        "enabled": true,
+        "config": {
+          "apiKey": "your_bot_id:your_secret",
+          "pollIntervalMs": 2000,
+          "sessionKeyPrefix": "agent:main:wechat:miniprogram:",
+          "debug": false
+        }
+      }
+    }
+  }
+}
+```
+
+### 配置项说明
+
+| 配置项 | 类型 | 必需 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `apiKey` | string | ✅ | - | API Key（格式：`bot_id:secret`），从微信小程序 ClawChat 中获取 |
+| `pollIntervalMs` | number | ❌ | `2000` | 轮询间隔（毫秒） |
+| `sessionKeyPrefix` | string | ❌ | `agent:main:wechat:miniprogram:` | Session Key 前缀 |
+| `debug` | boolean | ❌ | `false` | 是否启用调试日志 |
+
+## ✅ 验证安装
+
+安装完成后，执行以下步骤验证：
+
+### 1. 检查插件状态
+
+```bash
+openclaw plugins list | grep openclawwechat
+```
+
+应该看到插件已启用。
+
+### 2. 验证配置
+
+```bash
+openclaw config validate
+```
+
+### 3. 重启 Gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 4. 查看日志
+
+```bash
+openclaw logs --follow | grep "openclawwechat"
+```
+
+应该看到插件加载成功的日志。
+
+## 🔧 故障排查
+
+### 问题 1：OpenClaw 未找到
+
+**错误信息：**
+```
+OpenClaw 未安装或不在 PATH 中
+```
+
+**解决方法：**
+1. 确认 OpenClaw 已安装：`openclaw --version`
+2. 如果未安装，参考 [OpenClaw 安装文档](https://docs.openclaw.ai/install)
+3. 确保 OpenClaw 在 PATH 中
+
+### 问题 2：配置文件不存在
+
+**错误信息：**
+```
+配置文件不存在: ~/.openclaw/openclaw.json
+```
+
+**解决方法：**
+安装脚本会自动创建配置文件，如果失败，可以手动创建：
+
+```bash
+mkdir -p ~/.openclaw
+cat > ~/.openclaw/openclaw.json << 'EOF'
+{
+  "plugins": {
+    "enabled": true,
+    "entries": {}
+  }
+}
+EOF
+```
+
+### 问题 3：API Key 格式错误
+
+**错误信息：**
+```
+API Key 格式可能不正确
+```
+
+**解决方法：**
+- API Key 可从**微信小程序 ClawChat** 中获取
+- API Key 格式应为：`bot_id:secret`
+- `bot_id` 应为数字
+- `secret` 应为 35 位字符
+- 示例：`20231227:EXAMPLE_SECRET_KEY_35_CHARS_LONG_12345`
+
+### 问题 4：插件安装失败
+
+**错误信息：**
+```
+插件安装失败
+```
+
+**解决方法：**
+1. 检查插件目录是否存在且完整
+2. 检查 OpenClaw 扩展目录权限：`ls -la ~/.openclaw/extensions`
+3. 查看详细错误信息：`openclaw plugins install /path/to/OpenClawWeChat`
+
+### 问题 5：配置更新失败
+
+**错误信息：**
+```
+配置更新失败
+```
+
+**解决方法：**
+1. 检查配置文件权限：`ls -la ~/.openclaw/openclaw.json`
+2. 手动编辑配置文件添加插件配置
+3. 确保 JSON 格式正确
+
+## 📚 相关文档
+
+- [README.md](./README.md) - 插件使用说明
+- [CONFIG.md](./CONFIG.md) - 详细配置说明
+- [EXAMPLE.md](./EXAMPLE.md) - 使用示例
+- [OpenClaw 插件文档](https://docs.openclaw.ai/plugins)
+
+## 🤝 获取帮助
+
+如果遇到问题：
+
+1. 查看日志：`openclaw logs --follow`
+2. 检查配置：`openclaw config validate`
+3. 查看插件状态：`openclaw plugins list`
+4. 提交 Issue：[GitHub Issues](https://github.com/hillghost86/OpenClawWeChat/issues)