npm package: @saber3555/openclaw-easemob
Description: Easemob (环信) channel plugin for OpenClaw - A personal AI agent supporting IM integration
Author: XuCpeng
Latest version: 1.0.6

# OpenClaw Easemob Plugin

[![npm version](https://badge.fury.io/js/@saber3555%2Fopenclaw-easemob.svg)](https://www.npmjs.com/package/@saber3555/openclaw-easemob)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[OpenClaw](https://openclaw.ai) 的 **环信IM (Easemob)** 通道插件，让你的 AI 代理可以通过环信平台与用户聊天。

---

## 安装

```bash
openclaw plugins install @saber3555/openclaw-easemob
```

## 快速开始
### 1. 获取环信凭据
1. 登录 [环信控制台](https://console.easemob.com)
2. 创建新应用或选择现有应用
3. 在「应用概览」中获取:

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

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

### 2. 配置插件

```bash
openclaw channels add
```

![](./docs/images/image3.png)

选择 Easemob 后，按提示输入:

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

### 3. 配置 Webhook 回调

![](./docs/images/image1.png)
![](./docs/images/image2.png)


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`

```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,天气:晴}" → 最终答案 |

**配置示例：**

```json
{
  "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 的详细输出级别。

## 常用命令

```bash
# 查看通道状态
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
```

## 开发

### 本地安装测试

```bash
# 克隆仓库
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` 对象中添加多个账号配置:

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

## 技术架构

本插件采用 **Webhook 网关模式**：

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

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

详细设计说明见 [ARCHITECTURE.md](./ARCHITECTURE.md)

## 相关链接

- [OpenClaw 官方文档](https://docs.openclaw.ai/channels)
- [环信官方文档](https://docs.easemob.com/)
- [OpenClaw GitHub](https://github.com/openclaw/openclaw)
- [参考项目](https://github.com/dujiepeng/openclaw)

## 贡献

欢迎提交 Issue 和 PR！

## 许可证

MIT License - 详见 [LICENSE](./LICENSE)

---

Made with ❤️ by [XuCpeng](https://github.com/XuCpeng)