🤖 云之家 Channel 插件

OpenClaw 金蝶云之家 (YunzhiJia) 消息渠道插件，支持在云之家中集成 OpenClaw AI 能力。

📋 简介

云之家 Channel 插件允许你在金蝶云之家的群组或私聊中使用 OpenClaw AI 机器人。支持：

• ✅ Webhook 消息接收（HmacSHA1 签名验证）
• ✅ AI 智能回复（基于上下文的对话）
• ✅ 多账户支持
• ✅ 群组消息处理
• ✅ 访问控制（白名单机制）

🚀 快速开始

方式一：从 NPM 安装（推荐）⭐

# 从 NPM 安装插件
openclaw plugins install @zzedbot/yunzhijia

# 启用插件
openclaw plugins enable yunzhijia

# 重启 Gateway
openclaw gateway restart

💡 优点:

• ✅ 自动下载最新版本
• ✅ 支持版本管理
• ✅ 易于更新 (openclaw plugins update yunzhijia)

方式二：从源码安装

# 安装插件到 OpenClaw 扩展目录
openclaw plugins install <YOUR_WORKSPACE>/projects/yunzhijiachannel

# 或手动复制到扩展目录
cp -r <YOUR_WORKSPACE>/projects/yunzhijiachannel ~/.openclaw/extensions/yunzhijia

# 启用插件
openclaw plugins enable yunzhijia

# 重启 Gateway
openclaw gateway restart

方式三：从开发目录链接（开发者）

# 开发模式下，直接链接到开发目录
openclaw plugins install -l <YOUR_WORKSPACE>/projects/yunzhijiachannel

# 重启 Gateway
openclaw gateway restart

💡 说明:

• 生产环境使用 方式一（NPM 安装）
• 开发环境使用 方式三（链接到开发目录）

⚙️ 配置

1. 获取云之家凭证

登录 云之家开放平台，创建对话机器人并获取：

| 凭证 | 获取位置 | |------|---------| | appId | 应用详情 | | appSecret | 安全设置 | | token | 消息配置 | | webhookToken | Webhook 设置 |

2. 配置 OpenClaw

编辑 ~/.openclaw/openclaw.json：

{
  "channels": {
    "yunzhijia": {
      "enabled": true,
      "accounts": {
        "default": {
          "enabled": true,
          "appId": "<YOUR_APP_ID>",
          "appSecret": "<YOUR_APP_SECRET>",
          "token": "<YOUR_TOKEN>",
          "webhookToken": "<YOUR_WEBHOOK_TOKEN>",
          "webhookPort": 18790,
          "webhookHost": "0.0.0.0",
          "dmPolicy": "allowlist",
          "allowFrom": ["<USER_OPENID_1>", "<USER_OPENID_2>"]
        }
      }
    }
  },
  "plugins": {
    "allow": ["yunzhijia"],
    "entries": {
      "yunzhijia": {
        "enabled": true
      }
    }
  }
}

⚠️ 安全提示:

• 不要将真实密钥提交到 Git
• 建议使用环境变量或密钥管理工具
• 定期轮换密钥

3. 配置云之家 Webhook

在云之家机器人设置中配置消息接收地址：

消息接收地址：https://<YOUR_DOMAIN>/yunzhijia/webhook/default

💡 如果使用内网部署，需要配置外网映射（如 Nginx 反向代理）

4. 重启 Gateway

openclaw gateway restart

📖 配置说明

必需字段

| 字段 | 说明 | 示例 | |------|------|------| | appId | 云之家应用 ID | app_12345 | | appSecret | 应用密钥（用于签名验证） | abc123... | | token | 消息接收 Token | token_xyz... | | webhookToken | Webhook 发送授权码 | c7d28f... |

可选字段

| 字段 | 说明 | 默认值 | |------|------|--------| | webhookPort | Webhook 监听端口 | 18790 | | webhookHost | Webhook 监听地址 | 0.0.0.0 | | webhookPath | Webhook 路径 | /yunzhijia/webhook/<accountId> | | dmPolicy | DM 策略 (pairing | allowlist | open) | pairing | | allowFrom | 允许的用户 OpenID 列表 | [] | | groupPolicy | 群组策略 (allowlist | open) | allowlist |

获取用户 OpenID

方法 1: 查看 Gateway 日志

tail -f /tmp/openclaw/openclaw.log | grep operatorOpenid

方法 2: 用户首次发消息后，从日志中提取 operatorOpenid 字段

🧪 测试

1. 本地 Webhook 测试

cd <YOUR_WORKSPACE>/projects/yunzhijiachannel
./test-webhook.sh

2. 查看日志

# 实时日志
tail -f /tmp/openclaw/openclaw.log | grep yunzhijia

# 最近 100 条
tail -100 /tmp/openclaw/openclaw.log | grep yunzhijia

3. 云之家测试

1. 在云之家群组中 @机器人
2. 发送消息：你好
3. 查看是否收到 AI 回复

📚 文档导航

部署与配置

• docs/DEPLOYMENT.md - 详细部署指南
• docs/PRODUCTION_CONFIG.md - 生产环境配置

技术文档

• docs/IMPLEMENTATION.md - 实现说明
• docs/AI_INTEGRATION_GUIDE.md - AI 集成指南
• docs/YUNZHIJIA_API.md - 云之家 API 文档

开发文档

• docs/development/ - 开发过程文档

🏗️ 项目结构

yunzhijiachannel/
├── src/                      # 源代码
│   ├── channel.ts            # Channel 核心实现
│   ├── webhook-server.ts     # Webhook 服务器
│   ├── crypto.ts             # 签名验证
│   ├── api.ts                # 消息发送 API
│   └── ...
├── docs/                     # 文档目录
│   ├── DEPLOYMENT.md
│   ├── PRODUCTION_CONFIG.md
│   └── ...
├── package.json              # NPM 配置
├── openclaw.plugin.json      # OpenClaw 插件清单
└── tsconfig.json             # TypeScript 配置

目录说明

| 目录 | 说明 | |------|------| | src/ | TypeScript 源代码 | | docs/ | 项目文档 | | dist/ | 编译输出（自动忽略） | | node_modules/ | NPM 依赖（自动忽略） |

🛠️ 开发

环境要求

• Node.js >= 18
• npm >= 9
• OpenClaw >= 2026.3.0

安装依赖

cd <YOUR_WORKSPACE>/projects/yunzhijiachannel
npm install

编译

npm run build

开发模式

npm run dev

测试

npm test

🔒 安全最佳实践

1. 保护敏感信息

   • 不要将 appSecret 和 webhookToken 提交到 Git
   • 使用环境变量或密钥管理工具
   • 定期轮换密钥

2. 访问控制

   • 使用 allowFrom 白名单限制用户
   • 配置 dmPolicy: "allowlist"
   • 群组启用 requireMention: true

3. 网络安全

   • 使用 HTTPS 部署 Webhook
   • 配置防火墙限制访问来源
   • 定期审计日志

🐛 故障排查

收不到消息

1. 检查云之家 Webhook 地址是否正确
2. 检查外网映射是否正常
3. 检查防火墙设置
4. 查看 Gateway 日志

签名验证失败

# 检查 appSecret 是否正确
tail /tmp/openclaw/openclaw.log | grep "Invalid signature"

无法发送回复

# 检查 webhookToken 是否正确
tail /tmp/openclaw/openclaw.log | grep "发送失败"

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

版本: v2.0.0
最后更新: 2026-03-07
维护者: Zed