OpenClaw Easemob Plugin

OpenClaw 的 环信IM (Easemob) 通道插件，让你的 AI 代理可以通过环信平台与用户聊天。

---

安装

openclaw plugins install @saber3555/openclaw-easemob

快速开始

1. 获取环信凭据

1. 登录 环信控制台

2. 创建新应用或选择现有应用

3. 在「应用概览」中获取:

   • OrgName - 组织名称
   • AppName - 应用名称
   • Client ID - 客户端 ID
   • Client Secret - 客户端密钥

4. 在 「运营管理/运营操作」 创建一个用户作为机器人账号

2. 配置插件

openclaw channels add

选择 Easemob 后，按提示输入:

• OrgName
• AppName
• Client ID
• Client Secret
• 机器人用户名

3. 配置 Webhook 回调

1. 确保 OpenClaw Gateway 可以从公网访问
2. 登录环信控制台
3. 进入「应用设置」→「消息回调」
4. 添加回调 URL:
   1. https://your-gateway-host 就是访问 OpenClaw Control UI，默认为 127.0.0.1:18789，这里需要能从公网访问。
   2. 在后面拼接 /webhooks/easemob

https://your-gateway-host/webhooks/easemob

5. 选择回调类型: 单聊消息
6. 保存配置

4. 开始聊天

现在用户可以通过环信向你的机器人发送消息了！

配置说明

配置文件位置: ~/.openclaw/openclaw.json

{
  "channels": {
    "easemob": {
      "accounts": {
        "robot_username": {
          "accountId": "robot_username",
          "orgName": "your-org",
          "appName": "your-app",
          "clientId": "your-client-id",
          "clientSecret": "your-client-secret",
          "enabled": true,
          "dmPolicy": "pairing",
          "allowFrom": ["user1", "user2"],
          "showToolCalls": "full"
        }
      }
    }
  }
}

配置项说明

配置项	类型	必填	说明
accountId	string	✅	环信用户 ID (用户名)
orgName	string	✅	环信组织名称
appName	string	✅	环信应用名称
clientId	string	✅	环信 Client ID
clientSecret	string	✅	环信 Client Secret
enabled	boolean	❌	是否启用此账号
name	string	❌	显示名称
dmPolicy	string	❌	DM 策略: open/pairing/allowlist
allowFrom	array	❌	允许列表
showToolCalls	string	❌	是否显示工具调用详情: "off"/"on"/"full" (默认: "off")

DM 策略说明

• pairing (默认) - 需要用户先与代理配对
• allowlist - 只允许列表中的用户发送消息
• open - 允许任何用户发送消息（不推荐）

工具调用显示 (showToolCalls)

控制是否向用户实时显示 AI 工具调用的详细过程。

模式	说明	示例输出
"off" (默认)	只发送最终答案，隐藏所有工具调用过程	"今天北京天气晴朗，25°C"
"on"	显示工具开始/结束状态	"正在查询天气..." → 最终答案
"full"	显示完整工具输出，包括执行结果	"正在查询天气..." → "API返回: {温度:25,天气:晴}" → 最终答案

配置示例：

{
  "channels": {
    "easemob": {
      "accounts": {
        "robot_username": {
          "accountId": "robot_username",
          "orgName": "your-org",
          "appName": "your-app",
          "clientId": "your-client-id",
          "clientSecret": "your-client-secret",
          "showToolCalls": "full"
        }
      }
    }
  }
}

验证方法：

1. 配置 showToolCalls: "full"
2. 向机器人发送需要工具调用的消息，如："查询北京天气"
3. 观察是否收到多条消息：
   • 工具开始提示（如"正在查询天气..."）
   • 工具执行结果（如 API 返回的原始数据）
   • 最终整理后的答案

实现逻辑：

插件通过以下机制实现工具调用显示：

1. Session 级别设置：根据 showToolCalls 配置，自动设置对应 session 的 verboseLevel 字段
2. Dispatcher 回调：在 dispatchReplyFromConfig 中注册 sendToolResult 回调函数
3. 实时推送：当 OpenClaw Agent 执行工具时，通过回调将工具状态/结果实时发送给用户
4. 非阻塞发送：使用 void sendMessageToUser() 异步发送，不影响主流程

核心代码位于 src/index.ts:180-260，通过修改 ~/.openclaw/agents/main/sessions/sessions.json 中的 verboseLevel 来控制 OpenClaw 的详细输出级别。

常用命令

# 查看通道状态
openclaw channels status

# 测试发送消息
openclaw message send --channel easemob --to <user_id> "Hello!"

# 查看配置
openclaw config get channels.easemob

# 重新配置
openclaw channels add

# 禁用通道
openclaw config set channels.easemob.enabled false

# 查看网关日志
openclaw gateway logs

# 调试模式运行网关
DEBUG=easemob openclaw gateway run

开发

本地安装测试

# 克隆仓库
git clone https://github.com/XuCpeng/openclaw-easemob.git
cd openclaw-easemob

# 安装依赖
pnpm install

# 构建
pnpm run build

# 本地安装到 OpenClaw
openclaw plugins install ./

# 重新安装（自动保留配置）
./local-reinstall.sh

# 开发模式（自动重编译）
pnpm run dev

常见问题

Q: 为什么收不到消息？

A: 请检查:

1. Gateway 是否运行: openclaw gateway status
2. Webhook URL 是否正确配置
3. 防火墙是否允许外部访问 Gateway 端口
4. 环信控制台中的回调是否启用

Q: Token 过期怎么办？

A: 插件会自动管理 Token，在过期前自动刷新，无需手动处理。

Q: 支持群聊吗？

A: 当前版本 (P0) 仅支持单聊。群聊支持将在后续版本添加。

Q: 如何配置多账号？

A: 在 accounts 对象中添加多个账号配置:

{
  "accounts": {
    "robot1": { ... },
    "robot2": { ... }
  }
}

技术架构

本插件采用 Webhook 网关模式：

用户手机 ──→ 环信服务器 ──→ OpenClaw Gateway ──→ OpenClaw Agent
                              (Webhook)

• 不保持长连接，通过环信 Webhook 接收消息
• 通过 REST API 发送消息
• 支持 OAuth2 Token 自动管理

详细设计说明见 ARCHITECTURE.md

相关链接

• OpenClaw 官方文档
• 环信官方文档
• OpenClaw GitHub
• 参考项目

贡献

欢迎提交 Issue 和 PR！

许可证

MIT License - 详见 LICENSE

---

Made with ❤️ by XuCpeng