24a - 插件架构

┌─────────────────────────────────────────────────────────────────┐
│                      OpenClaw 整体架构                           │
│                                                                 │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐    │
│  │ WhatsApp │   │ Telegram │   │ Discord  │   │ 自定义    │    │
│  │ Channel  │   │ Channel  │   │ Channel  │   │ Channel   │    │
│  └────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘    │
│       │              │              │              │            │
│       └──────────────┴──────┬───────┴──────────────┘            │
│                             ▼                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Gateway 网关层                         │   │
│  │  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐  │   │
│  │  │ 路由    │  │ 会话管理  │  │ 事件队列 │  │ Webhook  │  │   │
│  │  └─────────┘  └──────────┘  └─────────┘  └──────────┘  │   │
│  └──────────────────────┬───────────────────────────────────┘   │
│                         ▼                                       │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                  Agent 执行层                             │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐               │   │
│  │  │ 模型选择  │  │ 工具调用  │  │ 安全策略  │               │   │
│  │  └──────────┘  └──────────┘  └──────────┘               │   │
│  └──────────────────────┬───────────────────────────────────┘   │
│                         ▼                                       │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              扩展层（Skills + Plugins）                    │   │
│  │                                                          │   │
│  │  Skills（Markdown 驱动）        Plugins（代码驱动）        │   │
│  │  ┌────────────┐                ┌────────────┐            │   │
│  │  │ SKILL.md   │                │ plugin.json│            │   │
│  │  │ + scripts/ │                │ + src/     │            │   │
│  │  └────────────┘                └────────────┘            │   │
│  └──────────────────────────────────────────────────────────┘   │
│                         ▼                                       │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                  存储层                                   │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐               │   │
│  │  │ MEMORY.md│  │ 向量搜索  │  │ 文件系统  │               │   │
│  │  └──────────┘  └──────────┘  └──────────┘               │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│  安装    │───▶│  加载    │───▶│  过滤    │───▶│  注入    │───▶│  执行    │
│ Install  │    │  Load    │    │  Filter  │    │  Inject  │    │ Execute  │
└─────────┘    └─────────┘    └─────────┘    └─────────┘    └─────────┘
     │              │              │              │              │
     ▼              ▼              ▼              ▼              ▼
 放入 skills/   解析 YAML     检查 OS、      压缩为 XML    Agent 根据
 目录或从      frontmatter   bins、env      列表注入到    指令调用工具
 ClawHub 安装  和 Markdown   依赖是否满足   系统提示词    执行任务

┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│  发现    │───▶│  加载    │───▶│  注册    │───▶│  运行    │───▶│  卸载    │
│ Discover │    │  Load    │    │ Register │    │   Run    │    │ Unload  │
└─────────┘    └─────────┘    └─────────┘    └─────────┘    └─────────┘
     │              │              │              │              │
     ▼              ▼              ▼              ▼              ▼
 按优先级扫描   通过 jiti      注册 RPC、     在 Gateway     Gateway
 配置路径、     动态加载       HTTP 路由、    进程内运行     关闭时清理
 工作区、全局   TypeScript     工具、CLI      后台服务       资源

// openclaw.plugin.json 清单文件
{
  "id": "my-plugin",
  "name": "My OpenClaw Plugin",
  "version": "1.0.0",
  "description": "自定义插件示例"
}
 
// Plugin 可注册的能力类型：
// ✅ Gateway RPC 方法
// ✅ Gateway HTTP 处理器
// ✅ Agent 工具（tools）
// ✅ CLI 命令
// ✅ 后台服务（Background services）
// ✅ 配置验证
// ✅ Skills 目录（通过清单文件列出）
// ✅ 自动回复命令（无需调用 AI）

my-skill/
├── SKILL.md              # 核心文件：YAML frontmatter + Markdown 指令
├── scripts/              # 可选：辅助脚本
│   ├── main.py
│   └── utils.sh
└── data/                 # 可选：静态数据
    └── templates.json

---
name: deploy-monitor
description: 监控部署状态并在异常时发送告警
emoji: 🚀
metadata:
  openclaw:
    requires:
      bins: ["curl", "jq"]        # 必需的命令行工具
      env: ["DEPLOY_API_KEY"]     # 必需的环境变量
      config: ["monitor.url"]     # 必需的配置项
    primaryEnv: "DEPLOY_API_KEY"
    install: "pip install requests" # 首次安装时执行
---
 
# Deploy Monitor
 
当用户需要检查部署状态或配置部署监控时使用此 Skill。
 
## 使用场景
- 检查最近一次部署的状态
- 配置部署失败告警
- 查看部署历史记录
 
## 操作指令
1. 运行 `curl -H "Authorization: $DEPLOY_API_KEY" $MONITOR_URL/status`
2. 解析 JSON 响应，提取 status、timestamp、version 字段
3. 如果 status 不是 "healthy"，立即通知用户
 
## 示例对话
用户："检查一下生产环境的部署状态"
Agent：[执行 curl 命令获取状态]
Agent："生产环境当前状态：✅ 健康，版本 v2.3.1，上次部署于 10 分钟前"

┌─────────────────────────────────────────────────────────┐
│                   OpenClaw 事件输入模型                    │
│                                                         │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐           │
│  │ 1. 消息    │  │ 2. 心跳    │  │ 3. Cron   │           │
│  │ Messages  │  │ Heartbeat │  │ 定时任务   │           │
│  │           │  │ (30min)   │  │ (自定义)   │           │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘           │
│        │              │              │                  │
│  ┌─────┴──────────────┴──────────────┴─────┐            │
│  │              事件队列 (Queue)             │            │
│  └─────┬──────────────┬──────────────┬─────┘            │
│        │              │              │                  │
│  ┌─────┴─────┐  ┌─────┴─────┐  ┌────┴──────┐           │
│  │ 4. Hooks  │  │ 5.Webhook │  │ +1. A2A   │           │
│  │ 内部事件   │  │ 外部触发   │  │ Agent间   │           │
│  │           │  │           │  │ 消息      │           │
│  └───────────┘  └───────────┘  └───────────┘           │
│                                                         │
│  所有输入 → 队列 → Agent Turn → 动作 → 持久化 → 循环     │
└─────────────────────────────────────────────────────────┘

// openclaw.json 配置
{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "soul-evil": {
          "enabled": true,
          "file": "SOUL_EVIL.md",
          "chance": 0.1,
          "purge": {
            "at": "21:00",
            "duration": "15m"
          }
        }
      }
    }
  }
}

用户发送消息                    外部 Webhook              定时器触发
     │                            │                        │
     ▼                            ▼                        ▼
┌─────────────────────────────────────────────────────────────┐
│                      Gateway 事件路由                        │
│                                                             │
│  1. 识别事件类型（message / webhook / cron / heartbeat）      │
│  2. 确定目标 Agent 和会话（Session）                          │
│  3. 将事件放入对应会话的队列                                   │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
┌──────────────────────────────────────────────────────────────┐
│                    会话队列（按序处理）                         │
│                                                              │
│  ┌─────┐  ┌─────┐  ┌─────┐                                  │
│  │ Msg1│→ │ Msg2│→ │ Msg3│→ ...                              │
│  └─────┘  └─────┘  └─────┘                                  │
│  同一会话内严格顺序执行，防止回复混乱                            │
└──────────────────────────┬───────────────────────────────────┘
                           ▼
┌──────────────────────────────────────────────────────────────┐
│                    Agent Turn 执行                            │
│                                                              │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐               │
│  │ Hook:    │───▶│ 构建上下文│───▶│ LLM 推理 │               │
│  │ bootstrap│    │ SOUL.md  │    │ + 工具调用│               │
│  │          │    │ MEMORY.md│    │          │               │
│  └──────────┘    │ Skills   │    └────┬─────┘               │
│                  └──────────┘         │                     │
│                                       ▼                     │
│                              ┌──────────────┐               │
│                              │ 7 层工具策略  │               │
│                              │ 权限检查      │               │
│                              └──────┬───────┘               │
│                                     ▼                       │
│                              ┌──────────────┐               │
│                              │ 执行工具/脚本 │               │
│                              └──────┬───────┘               │
│                                     ▼                       │
│                              ┌──────────────┐               │
│                              │ 持久化状态    │               │
│                              │ 返回结果      │               │
│                              └──────────────┘               │
└──────────────────────────────────────────────────────────────┘

请求调用工具
     │
     ▼
┌─ 1. Profile ──── 认证配置文件是否允许？
│    ▼
├─ 2. Provider ─── 模型提供商是否支持？
│    ▼
├─ 3. Global ───── 全局策略是否启用？
│    ▼
├─ 4. Agent ────── 该 Agent 是否有权限？
│    ▼
├─ 5. Group ────── 当前通道是否安全？（私聊 vs 公共频道）
│    ▼
├─ 6. Sandbox ──── 文件系统限制是否满足？
│    ▼
└─ 7. Subagent ─── 父 Agent 授予了哪些权限？
     │
     ▼
  允许 / 拒绝

// src/my-tool.ts
import type { PluginApi } from '@openclaw/types';
 
export function register(api: PluginApi) {
  api.registerTool({
    name: 'stock-price',
    description: '查询实时股票价格',
    parameters: {
      symbol: { type: 'string', description: '股票代码' }
    },
    execute: async ({ symbol }) => {
      const price = await fetchStockPrice(symbol);
      return { price, currency: 'USD', timestamp: Date.now() };
    }
  });
}

┌──────────────┐         ┌──────────────┐         ┌──────────┐
│  你的应用     │◄──任意──▶│  Channel     │◄──Plugin──▶│ Gateway  │
│  / 服务      │  协议    │  Plugin      │   API     │          │
└──────────────┘         └──────────────┘         └──────────┘

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "name": "Nextcloud Talk",
      "icon": "nextcloud",
      "description": "通过 Nextcloud Talk 与 Agent 交互"
    },
    "install": {
      "hint": "需要 Nextcloud 实例和 Talk 应用"
    }
  }
}

api.registerCommand({
  name: 'my-report',
  description: '生成自定义报告',
  action: async (args) => {
    const report = await generateReport(args);
    console.log(report);
  }
});

api.registerAutoReply({
  command: '/status',
  description: '快速查看系统状态',
  handler: async () => {
    return `系统运行正常 | 上线时间: ${getUptime()} | 活跃 Agent: ${getActiveAgents()}`;
  }
});

# 1. 创建 Skill 目录
mkdir -p ~/.openclaw/skills/my-skill
cd ~/.openclaw/skills/my-skill
 
# 2. 创建 SKILL.md（核心文件）
cat > SKILL.md << 'EOF'
---
name: my-skill
description: 我的第一个自定义 Skill
metadata:
  openclaw:
    requires:
      env: ["MY_API_KEY"]
---
 
# My Skill
 
当用户需要 [功能描述] 时使用此 Skill。
 
## 操作指令
1. [具体步骤]
2. [具体步骤]
 
## 示例
用户："[示例输入]"
Agent：[示例输出]
EOF
 
# 3. 测试 Skill
openclaw skill test ./
openclaw skill validate ./

# 1. 初始化项目
mkdir my-openclaw-plugin && cd my-openclaw-plugin
npm init -y
npm install -D typescript vitest @types/node
 
# 2. 配置 TypeScript
npx tsc --init
# 修改 tsconfig.json: target=ES2022, module=ESNext
 
# 3. 创建插件清单
cat > openclaw.plugin.json << 'EOF'
{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "自定义 OpenClaw 插件"
}
EOF
 
# 4. 在 package.json 中声明入口
# "openclaw": { "extensions": ["./src/index.ts"] }
 
# 5. 编写插件代码
mkdir src && touch src/index.ts
 
# 6. 构建和测试
npm run build
vitest run

mkdir -p ~/.openclaw/skills/deploy-notify
cd ~/.openclaw/skills/deploy-notify

---
name: deploy-notify
description: 解析 GitHub 部署 Webhook 并生成人类可读的部署报告
emoji: 🚀
metadata:
  openclaw:
    requires:
      bins: ["jq"]
      env: ["GITHUB_WEBHOOK_SECRET"]
---
 
# Deploy Notify
 
当收到 GitHub 部署相关的 Webhook 事件时使用此 Skill。
 
## 触发条件
- Webhook 来源为 GitHub
- 事件类型为 deployment_status 或 workflow_run
 
## 处理逻辑
1. 验证 Webhook 签名（使用 GITHUB_WEBHOOK_SECRET）
2. 解析 JSON payload，提取关键字段：
   - 仓库名称
   - 部署环境（production / staging）
   - 状态（success / failure / pending）
   - 触发者
   - 提交 SHA 和消息
3. 生成格式化的部署报告
 
## 输出格式
🚀 **部署通知**
- 仓库：{repo}
- 环境：{environment}
- 状态：{status_emoji} {status}
- 版本：{sha_short}
- 触发者：{actor}
- 耗时：{duration}

{
  "webhooks": {
    "github-deploy": {
      "path": "/webhook/github",
      "secret": "${GITHUB_WEBHOOK_SECRET}",
      "agent": "default",
      "events": ["deployment_status", "workflow_run"]
    }
  }
}

# 验证 Skill 结构
openclaw skill validate ./deploy-notify
 
# 本地测试（模拟 Webhook）
curl -X POST http://localhost:3000/webhook/github \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: deployment_status" \
  -d '{"deployment_status":{"state":"success"},"repository":{"full_name":"my/repo"}}'