yach（知音楼）OpenClaw 渠道插件

将好未来内部 IM 工具知音楼接入 OpenClaw，让员工在熟悉的聊天界面直接与 AI 助手对话。

安装

openclaw plugins install openclaw-plugin-yach.zip

配置

在 ~/.openclaw/openclaw.json 中添加渠道配置：

{
  "channels": {
    "yach": {
      "enabled": true,
      "accounts": {
        "my-bot": {
          "name": "AI 助手",
          "appKey": "your-app-key",
          "appSecret": "your-app-secret",
          "baseUrl": "https://yach-oapi.zhiyinlou.com"
        }
      },
      "replyMode": "stream",
      "dmPolicy": "open",
      "groupPolicy": "disabled"
    }
  }
}

知音楼平台配置

在知音楼开放平台，将机器人的回调地址设置为：

http://<openclaw-host>:18789/yach/<accountId>/messages

其中 <accountId> 是 channels.yach.accounts 中的账号 key（如上例中的 my-bot）。

也可以通过 webhookPath 自定义路径：

{
  "channels": {
    "yach": {
      "accounts": {
        "my-bot": {
          "webhookPath": "/my-bot/webhook"
        }
      }
    }
  }
}

消息接收模式（connectionMode）

支持两种消息接收传输方式：

| 值 | 效果 | |----|------| | webhook（默认）| HTTP POST 回调，需公网可达 | | channel | Channel SDK 长连接，适合无公网 IP 的内网环境 |

{
  "channels": {
    "yach": {
      "accounts": {
        "my-bot": {
          "connectionMode": "channel"
        }
      }
    }
  }
}

两种模式下回复均走 OAPI，仅消息接收方式不同。

Agent 路由

在顶层 bindings 中配置消息路由规则：

{
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "yach"
      }
    }
  ]
}

也支持按账号或按用户精细路由：

{
  "bindings": [
    {
      "agentId": "vip-agent",
      "match": {
        "channel": "yach",
        "accountId": "my-bot",
        "peer": { "kind": "direct", "id": "some-user-id" }
      }
    }
  ]
}

动态 Agent（多用户隔离）

开启后，私聊用户在首次发消息时自动创建独立的 Agent 实例，群聊每个群也会获得独立 Agent，各拥有隔离的 workspace 和对话历史，无需手动配置 bindings。

{
  "channels": {
    "yach": {
      "dynamicAgentCreation": {
        "enabled": true,
        "maxAgents": 1000
      }
    }
  }
}

Agent ID 自动生成规则：

• 私聊：yach-{accountId}-{senderId}
• 群聊：yach-{accountId}-group-{groupId}

生成的 Agent 自动写入配置文件的 agents.list 和 bindings。

访问控制

私聊（dmPolicy）

| 值 | 效果 | |----|------| | open（默认）| 所有人均可使用 | | allowlist | 仅 allowFrom 白名单中的用户 | | pairing | 未授权用户收到配对码，管理员通过 openclaw pairing list yach 审批 |

群聊（groupPolicy）

| 值 | 效果 | |----|------| | open | 响应所有群（知音楼只回调 @ 机器人的消息） | | allowlist | 仅 groupAllowFrom 白名单中的群 | | disabled（默认）| 禁用所有群消息 |

回复模式（replyMode）

| 值 | 效果 | |----|------| | stream（默认）| 流式消息卡片，AI 生成内容实时逐字推送到卡片（create → push → close） | | direct | AI 生成完成后一次性发送 markdown 消息，无超时限制 |

流式模式特性：

• 懒启动：首次收到 AI 内容时才创建卡片
• 智能限流：最多 10 次/秒推送，超频内容自动合并
• 自动轮换：卡片有效期 10 分钟，9 分钟时自动切换新卡片
• 显式关闭：AI 输出完成后关闭卡片，客户端不再显示等待状态

支持的消息类型

| msgtype | 处理方式 | |---------|---------| | text | 直接转发给 AI | | audio | 提取语音识别文本（audio_text） | | image | 提取 OCR 识别文本（image_text）或下载图片 | | file / video | 下载附件供 AI 处理 | | reply / fold / link / merge_forward | 提取 content 字段 | | start_new_session | 触发 /new 重置会话 | | 其他 | 静默忽略，返回 { msgtype: "empty" } |

发布

1. openclaw.install.npmSpec 的值为 name@version（与 package.json 顶层 name、version 保持一致）。
2. CDN 脚本安装构建：

   make publish          # 发布当前版本到 CDN
   make publish-latest   # 发布并设为 latest，刷新 CDN

3. npm 包构建发布：

   npm run npm:publish:beta     # 发布到 npm，tag 为 beta
   npm run npm:publish  # 发布到 npm，tag 为 latest

更多

• 架构说明：docs/ARCHITECTURE.md