adp-openclaw 0.0.2

package/USAGE.md

@@ -0,0 +1,910 @@
+# Simple Go Plugin - 完整使用说明
+
+## 目录
+- [简介](#简介)
+- [系统架构](#系统架构)
+- [环境要求](#环境要求)
+- [安装步骤](#安装步骤)
+- [配置说明](#配置说明)
+- [启动服务](#启动服务)
+- [测试验证](#测试验证)
+- [API接口文档](#api接口文档)
+- [故障排查](#故障排查)
+- [开发指南](#开发指南)
+
+---
+
+## 简介
+
+Simple Go 是一个 OpenClaw 演示插件，展示如何通过 Go HTTP 后端集成自定义消息通道。该插件实现了完整的消息收发流程，支持多用户对话和会话管理。
+
+### 主要特性
+- ✅ Go HTTP 后端服务器
+- ✅ API Token 认证
+- ✅ 多客户端支持
+- ✅ 多轮对话管理
+- ✅ 会话持久化
+- ✅ 负载均衡（最少消息队列优先）
+- ✅ 实时消息轮询
+
+---
+
+## 系统架构
+
+```
+┌─────────────┐      HTTP       ┌─────────────┐
+│   外部用户   │ ────────────►  │  Go Server  │
+│             │   /inbound      │  (port 9876)│
+└─────────────┘                 └──────┬──────┘
+                                       │
+                                       │ /poll (1s)
+                                       ▼
+                                ┌─────────────┐
+                                │  OpenClaw   │
+                                │   Gateway   │
+                                └──────┬──────┘
+                                       │
+                                       ▼
+                                ┌─────────────┐
+                                │  AI Agent   │
+                                │  (Claude)   │
+                                └──────┬──────┘
+                                       │
+                                       │ /send
+                                       ▼
+                                ┌─────────────┐
+                                │  Go Server  │
+                                │   /outbox   │
+                                └─────────────┘
+```
+
+### 组件说明
+
+1. **Go HTTP Server** (`server/main.go`)
+   - 监听端口：9876
+   - 管理消息队列和会话
+   - 提供 REST API 接口
+
+2. **OpenClaw Plugin** (`src/`)
+   - `channel.ts`: 插件配置和生命周期管理
+   - `monitor.ts`: 消息轮询和处理逻辑
+   - `runtime.ts`: 运行时状态管理
+
+3. **OpenClaw Gateway**
+   - 管理插件生命周期
+   - 路由消息到 AI 代理
+   - 处理认证和会话
+
+---
+
+## 环境要求
+
+### 必需软件
+- **Go**: 1.22.0 或更高版本
+- **Node.js**: 22.22.0 或更高版本
+- **OpenClaw**: 2026.1.29 或更高版本
+
+### 系统要求
+- Linux/macOS/Windows
+- 至少 512MB 可用内存
+- 网络连接（用于 AI API 调用）
+
+---
+
+## 安装步骤
+
+### 1. 安装 Go
+
+```bash
+# 如果未安装 Go
+cd server
+wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
+sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz
+export PATH=$PATH:/usr/local/go/bin
+```
+
+### 2. 安装依赖
+
+```bash
+# 安装 Node.js 依赖
+cd /root/simplego
+npm install
+```
+
+### 3. 安装 OpenClaw 插件
+
+```bash
+# 插件已在 ~/simplego 目录，OpenClaw 会自动加载
+openclaw plugins list | grep "Simple Go"
+```
+
+预期输出：
+```
+│ Simple Go    │ simplego │ loaded   │ ~/simplego/index.ts    │ 0.0.1     │
+```
+
+---
+
+## 配置说明
+
+### 1. 启动 Go 服务器
+
+```bash
+cd /root/simplego/server
+
+# 启动服务器（会自动生成 admin token）
+go run main.go
+
+# 或指定 admin token
+go run main.go --admin-token "your-admin-token-here"
+
+# 后台运行
+nohup go run main.go --admin-token "your-admin-token" > /tmp/go-server.log 2>&1 &
+```
+
+服务器启动后会显示：
+```
+Generated admin token: <token>
+Simple Go channel server starting on http://localhost:9876
+```
+
+**保存 admin token，后续需要使用！**
+
+### 2. 注册 OpenClaw 客户端
+
+使用 admin token 注册客户端：
+
+```bash
+curl -X POST http://localhost:9876/clients \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <admin-token>" \
+  -d '{"name": "openclaw-main"}'
+```
+
+响应示例：
+```json
+{
+  "clientId": "client-666580ae8729e2b7",
+  "token": "92527c1a861bb50bd1acc47180ef317369e97529c7a5491b2bc67839992cfbb8",
+  "name": "openclaw-main"
+}
+```
+
+**保存 client token，配置插件时需要使用！**
+
+### 3. 配置 OpenClaw 插件
+
+```bash
+# 方式 1: 使用环境变量
+export SIMPLEGO_SERVER_URL="http://localhost:9876"
+export SIMPLEGO_API_TOKEN="<client-token>"
+
+# 方式 2: 使用配置文件
+openclaw config set channels.simplego.enabled true
+openclaw config set channels.simplego.serverUrl "http://localhost:9876"
+openclaw config set channels.simplego.apiToken "<client-token>"
+openclaw config set channels.simplego.pollIntervalMs 1000
+```
+
+### 4. 配置 AI API Key
+
+```bash
+# 检查环境变量
+echo $ANTHROPIC_AUTH_TOKEN
+
+# 如果未设置，需要配置
+export ANTHROPIC_AUTH_TOKEN="your-api-key"
+export ANTHROPIC_BASE_URL="https://api.anthropic.com"  # 可选
+```
+
+或者编辑 `~/.openclaw/agents/main/agent/models.json`：
+
+```json
+{
+  "providers": {
+    "anthropic": {
+      "baseUrl": "https://api.anthropic.com/v1",
+      "apiKey": "your-api-key",
+      "api": "anthropic",
+      "models": [
+        {
+          "id": "claude-opus-4-5-20251101",
+          "name": "Claude Opus 4.5",
+          "reasoning": true,
+          "input": ["text"],
+          "contextWindow": 200000,
+          "maxTokens": 8192
+        }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 启动服务
+
+### 1. 启动 Go 服务器
+
+```bash
+cd /root/simplego/server
+nohup go run main.go --admin-token "17b86aef58c8a92d9152f7b1ccf3b10482b9b71ea3209bf6ff964189378e742e" > /tmp/go-server.log 2>&1 &
+```
+
+### 2. 启动 OpenClaw Gateway
+
+```bash
+# 启动网关
+openclaw gateway start
+
+# 检查状态
+openclaw gateway status
+
+# 查看日志
+openclaw logs --follow
+```
+
+### 3. 验证服务状态
+
+```bash
+# 检查 Go 服务器
+curl http://localhost:9876/health
+
+# 检查插件状态
+openclaw channels list
+
+# 检查网关状态
+openclaw health
+```
+
+预期输出：
+```
+Simple Go: configured
+```
+
+---
+
+## 测试验证
+
+### 1. 发送测试消息
+
+```bash
+# 发送消息
+curl -X POST http://localhost:9876/inbound \
+  -H "Content-Type: application/json" \
+  -d '{"from": "testuser", "text": "Hello! What is 2 plus 2?"}'
+```
+
+响应示例：
+```json
+{
+  "id": "msg-1",
+  "conversationId": "conv-abc123",
+  "clientId": "client-666580ae8729e2b7",
+  "from": "testuser",
+  "to": "bot",
+  "text": "Hello! What is 2 plus 2?",
+  "timestamp": 1770213375101
+}
+```
+
+### 2. 查看响应
+
+```bash
+# 等待几秒让 AI 处理
+sleep 5
+
+# 查看所有响应
+curl http://localhost:9876/outbox | jq .
+
+# 查看最新响应
+curl http://localhost:9876/outbox | jq '.messages[-1]'
+```
+
+预期响应：
+```json
+{
+  "id": "msg-2",
+  "conversationId": "conv-abc123",
+  "clientId": "client-666580ae8729e2b7",
+  "from": "bot",
+  "to": "testuser",
+  "text": "2 plus 2 equals 4.",
+  "timestamp": 1770213378456
+}
+```
+
+### 3. 查看会话历史
+
+```bash
+# 获取会话 ID（从上面的响应中）
+CONV_ID="conv-abc123"
+
+# 查看会话历史
+curl -H "Authorization: Bearer <client-token>" \
+  http://localhost:9876/conversations/$CONV_ID | jq .
+```
+
+### 4. 测试多轮对话
+
+```bash
+# 第一轮
+curl -X POST http://localhost:9876/inbound \
+  -H "Content-Type: application/json" \
+  -d '{"from": "alice", "text": "My name is Alice"}'
+
+sleep 5
+
+# 第二轮（同一用户）
+curl -X POST http://localhost:9876/inbound \
+  -H "Content-Type: application/json" \
+  -d '{"from": "alice", "text": "What is my name?"}'
+
+sleep 5
+
+# 查看响应
+curl http://localhost:9876/outbox | jq '.messages[-2:]'
+```
+
+---
+
+## API接口文档
+
+### 公共端点（无需认证）
+
+#### 1. 健康检查
+```
+GET /health
+```
+
+响应：
+```json
+{
+  "ok": true,
+  "server": "simplego",
+  "clients": 1,
+  "conversations": 5
+}
+```
+
+#### 2. 发送消息（支持多用户身份）
+```
+POST /inbound
+Content-Type: application/json
+```
+
+**基础请求（简单模式）**：
+```json
+{
+  "from": "user_123",
+  "text": "你好，请帮我查询订单"
+}
+```
+
+**完整请求（多用户/多租户模式，类似飞书）**：
+```json
+{
+  "userId": "user_123",
+  "query": "你好，请帮我查询订单",
+  "user": {
+    "userId": "user_123",
+    "username": "张三",
+    "avatar": "https://example.com/avatar.png",
+    "email": "zhangsan@company.com",
+    "tenantId": "tenant_abc",
+    "source": "web",
+    "extra": {
+      "department": "技术部",
+      "role": "developer"
+    }
+  }
+}
+```
+
+**快捷请求（部分用户信息）**：
+```json
+{
+  "from": "user_123",
+  "text": "你好",
+  "username": "张三",
+  "tenantId": "tenant_abc",
+  "source": "mobile_app"
+}
+```
+
+**字段说明**：
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `from` / `userId` / `user.userId` | 是 | 用户唯一标识（三选一） |
+| `text` / `query` | 是 | 用户查询内容（二选一） |
+| `user` | 否 | 完整用户信息对象 |
+| `user.username` | 否 | 用户显示名称 |
+| `user.avatar` | 否 | 用户头像 URL |
+| `user.email` | 否 | 用户邮箱 |
+| `user.tenantId` | 否 | 租户/组织 ID（多租户场景） |
+| `user.source` | 否 | 请求来源平台 |
+| `user.extra` | 否 | 额外用户元数据 |
+| `username` | 否 | 快捷用户名字段 |
+| `tenantId` | 否 | 快捷租户 ID 字段 |
+| `source` | 否 | 快捷来源字段 |
+
+响应：
+```json
+{
+  "message": {
+    "id": "msg-1",
+    "conversationId": "conv-abc123",
+    "clientId": "client-xxx",
+    "from": "user_123",
+    "to": "bot",
+    "text": "你好，请帮我查询订单",
+    "timestamp": 1770213375101,
+    "user": {
+      "userId": "user_123",
+      "username": "张三",
+      "tenantId": "tenant_abc",
+      "source": "web"
+    }
+  },
+  "delivered": true,
+  "websocket": true,
+  "conversationId": "conv-abc123",
+  "userId": "user_123"
+}
+```
+
+#### 3. 查看发送的消息
+```
+GET /outbox
+```
+
+响应：
+```json
+{
+  "messages": [
+    {
+      "id": "msg-2",
+      "conversationId": "conv-abc123",
+      "clientId": "client-xxx",
+      "from": "bot",
+      "to": "user_id",
+      "text": "response text",
+      "timestamp": 1770213378456
+    }
+  ]
+}
+```
+
+### 管理端点（需要 Admin Token）
+
+#### 4. 注册客户端
+```
+POST /clients
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+
+{
+  "name": "client-name"
+}
+```
+
+响应：
+```json
+{
+  "clientId": "client-xxx",
+  "token": "client-token-xxx",
+  "name": "client-name"
+}
+```
+
+#### 5. 列出所有客户端
+```
+GET /clients
+Authorization: Bearer <admin-token>
+```
+
+响应：
+```json
+{
+  "clients": [
+    {
+      "id": "client-xxx",
+      "name": "openclaw-main",
+      "lastSeenAt": 1770213375101
+    }
+  ]
+}
+```
+
+#### 6. 列出所有会话
+```
+GET /conversations
+Authorization: Bearer <admin-token>
+```
+
+响应：
+```json
+{
+  "conversations": [
+    {
+      "id": "conv-abc123",
+      "userId": "alice",
+      "clientId": "client-xxx",
+      "messages": [...],
+      "createdAt": 1770213375101,
+      "updatedAt": 1770213378456
+    }
+  ]
+}
+```
+
+### 客户端端点（需要 Client Token）
+
+#### 7. 轮询消息
+```
+GET /poll
+Authorization: Bearer <client-token>
+```
+
+响应：
+```json
+{
+  "messages": [
+    {
+      "id": "msg-1",
+      "conversationId": "conv-abc123",
+      "from": "user_id",
+      "text": "message content",
+      "timestamp": 1770213375101
+    }
+  ]
+}
+```
+
+#### 8. 发送回复
+```
+POST /send
+Authorization: Bearer <client-token>
+Content-Type: application/json
+
+{
+  "to": "user_id",
+  "text": "response text",
+  "conversationId": "conv-abc123"
+}
+```
+
+响应：
+```json
+{
+  "ok": true,
+  "message": {
+    "id": "msg-2",
+    "conversationId": "conv-abc123",
+    "clientId": "client-xxx",
+    "from": "bot",
+    "to": "user_id",
+    "text": "response text",
+    "timestamp": 1770213378456
+  }
+}
+```
+
+#### 9. 查看会话详情
+```
+GET /conversations/:id
+Authorization: Bearer <client-token>
+```
+
+响应：
+```json
+{
+  "id": "conv-abc123",
+  "userId": "alice",
+  "clientId": "client-xxx",
+  "messages": [
+    {
+      "id": "msg-1",
+      "from": "alice",
+      "text": "Hello",
+      "timestamp": 1770213375101
+    },
+    {
+      "id": "msg-2",
+      "from": "bot",
+      "text": "Hi there!",
+      "timestamp": 1770213378456
+    }
+  ],
+  "createdAt": 1770213375101,
+  "updatedAt": 1770213378456
+}
+```
+
+---
+
+## 故障排查
+
+### 问题 1: Go 服务器无法启动
+
+**症状：**
+```
+bind: address already in use
+```
+
+**解决方案：**
+```bash
+# 查找占用端口的进程
+lsof -i :9876
+
+# 杀死进程
+kill -9 <PID>
+
+# 或使用不同端口
+go run main.go --port 9877
+```
+
+### 问题 2: 插件未加载
+
+**症状：**
+```
+openclaw plugins list
+# Simple Go 显示为 disabled
+```
+
+**解决方案：**
+```bash
+# 检查插件目录
+ls -la ~/simplego/
+
+# 检查 package.json
+cat ~/simplego/package.json
+
+# 重新加载插件
+openclaw gateway restart
+```
+
+### 问题 3: 认证失败
+
+**症状：**
+```
+[simplego] authentication failed - check apiToken
+```
+
+**解决方案：**
+```bash
+# 验证 token
+curl -H "Authorization: Bearer <client-token>" \
+  http://localhost:9876/poll
+
+# 重新注册客户端
+curl -X POST http://localhost:9876/clients \
+  -H "Authorization: Bearer <admin-token>" \
+  -d '{"name": "openclaw-main"}'
+
+# 更新配置
+openclaw config set channels.simplego.apiToken "<new-token>"
+openclaw gateway restart
+```
+
+### 问题 4: 消息未收到响应
+
+**症状：**
+消息发送成功，但 outbox 为空
+
+**解决方案：**
+```bash
+# 1. 检查网关状态
+openclaw gateway status
+
+# 2. 查看日志
+tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep simplego
+
+# 3. 检查 API key
+echo $ANTHROPIC_AUTH_TOKEN
+
+# 4. 测试轮询
+curl -H "Authorization: Bearer <client-token>" \
+  http://localhost:9876/poll
+```
+
+### 问题 5: API Key 错误
+
+**症状：**
+```
+No API key found for provider "anthropic"
+```
+
+**解决方案：**
+```bash
+# 设置环境变量
+export ANTHROPIC_AUTH_TOKEN="your-api-key"
+
+# 或编辑配置文件
+vim ~/.openclaw/agents/main/agent/models.json
+
+# 重启网关
+openclaw gateway restart
+```
+
+### 问题 6: 内存泄漏警告
+
+**症状：**
+```
+MaxListenersExceededWarning: Possible EventTarget memory leak detected
+```
+
+**解决方案：**
+```bash
+# 重启网关
+openclaw gateway stop
+sleep 3
+openclaw gateway start
+```
+
+---
+
+## 开发指南
+
+### 项目结构
+
+```
+simplego/
+├── server/                 # Go 后端服务器
+│   ├── main.go            # 主服务器代码
+│   └── go.mod             # Go 依赖
+├── src/                   # TypeScript 插件代码
+│   ├── channel.ts         # 插件配置
+│   ├── monitor.ts         # 消息轮询逻辑
+│   ├── runtime.ts         # 运行时管理
+│   └── config-schema.ts   # 配置模式
+├── index.ts               # 插件入口
+├── package.json           # Node.js 配置
+├── openclaw.plugin.json   # 插件元数据
+├── README.md              # 项目说明
+├── DESIGN.md              # 设计文档
+└── USAGE.md               # 本文档
+```
+
+### 修改轮询间隔
+
+编辑配置：
+```bash
+openclaw config set channels.simplego.pollIntervalMs 2000  # 2秒
+```
+
+或修改 `src/channel.ts`:
+```typescript
+pollIntervalMs: section.pollIntervalMs ?? 2000,  // 默认 2 秒
+```
+
+### 添加自定义字段
+
+1. 修改 Go 服务器的 `Message` 结构：
+```go
+type Message struct {
+    ID             string `json:"id"`
+    ConversationID string `json:"conversationId"`
+    ClientID       string `json:"clientId"`
+    From           string `json:"from"`
+    To             string `json:"to"`
+    Text           string `json:"text"`
+    Timestamp      int64  `json:"timestamp"`
+    CustomField    string `json:"customField"`  // 新字段
+}
+```
+
+2. 修改 `src/monitor.ts` 的类型定义：
+```typescript
+type InboundMessage = {
+  id: string;
+  conversationId: string;
+  from: string;
+  text: string;
+  timestamp: number;
+  customField?: string;  // 新字段
+};
+```
+
+3. 在 context 中传递：
+```typescript
+const ctx = runtime.channel.reply.finalizeInboundContext({
+  Body: msg.text,
+  // ... 其他字段
+  CustomField: msg.customField,  // 传递新字段
+});
+```
+
+### 调试技巧
+
+1. **启用详细日志：**
+```bash
+# 查看实时日志
+tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep simplego
+
+# 查看 Go 服务器日志
+tail -f /tmp/go-server.log
+```
+
+2. **测试单个组件：**
+```bash
+# 测试 Go 服务器
+curl http://localhost:9876/health
+
+# 测试插件轮询
+curl -H "Authorization: Bearer <token>" http://localhost:9876/poll
+
+# 测试消息发送
+curl -X POST http://localhost:9876/inbound \
+  -H "Content-Type: application/json" \
+  -d '{"from": "test", "text": "debug message"}'
+```
+
+3. **使用 jq 格式化输出：**
+```bash
+curl http://localhost:9876/outbox | jq '.messages | map({from, to, text})'
+```
+
+### 性能优化
+
+1. **调整轮询间隔：**
+   - 高频场景：500ms
+   - 正常场景：1000ms（默认）
+   - 低频场景：3000ms
+
+2. **限制消息队列大小：**
+修改 `server/main.go`:
+```go
+const maxQueueSize = 100
+
+if len(s.inbound[clientID]) > maxQueueSize {
+    s.inbound[clientID] = s.inbound[clientID][1:]
+}
+```
+
+3. **添加消息过期机制：**
+```go
+const messageExpiry = 5 * time.Minute
+
+if time.Now().UnixMilli() - msg.Timestamp > messageExpiry.Milliseconds() {
+    continue  // 跳过过期消息
+}
+```
+
+---
+
+## 常见问题 (FAQ)
+
+### Q1: 支持多少并发用户？
+A: 默认配置支持数百个并发用户。可以通过增加 Go 服务器实例和调整轮询间隔来扩展。
+
+### Q2: 消息是否持久化？
+A: 当前版本消息存储在内存中。生产环境建议添加数据库持久化。
+
+### Q3: 如何实现消息加密？
+A: 可以在发送前加密 `text` 字段，在接收后解密。建议使用 TLS/HTTPS 传输。
+
+### Q4: 支持文件上传吗？
+A: 当前版本仅支持文本。可以扩展 `Message` 结构添加 `mediaUrl` 字段。
+
+### Q5: 如何实现消息撤回？
+A: 需要添加新的 API 端点和消息状态管理。参考 `server/main.go` 添加 DELETE 端点。
+
+---
+
+## 许可证
+
+本项目为演示用途，遵循 OpenClaw 项目许可证。
+
+## 支持
+
+- 文档：https://docs.openclaw.ai
+- 问题反馈：https://github.com/anthropics/openclaw/issues
+- 社区：https://discord.gg/openclaw
+
+---
+
+**最后更新：** 2026-02-04
+**版本：** 0.0.1
+**作者：** OpenClaw Team