Feihan

Name: Feihan
Rating: 3.5 (1 reviews)
Author: feihan-im

By feihan-im 👁 7 views ▲ 0 votes

Feihan plugin for OpenClaw

GitHub

Install

npm install              #

Configuration Example

{
  "channels": {
    "feihan": {
      "accounts": {
        "default": {
          "enabled": true,
          "appId": "your_app_id",
          "appSecret": "your_app_secret",
          "backendUrl": "http://your-feihan-backend:21000"
        }
      }
    }
  }
}

README

# @feihan-im/openclaw-feihan

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-blue.svg)](https://nodejs.org/)

中文 | [English](./README.en.md)

飞函 IM 频道插件，用于 OpenClaw。将飞函机器人接入 OpenClaw 的 AI Agent 管线，通过飞函与 Agent 对话。

## 功能

- 支持私聊和群聊
- 收发文本消息
- 输入状态指示和已读回执
- 多账号登录，通过 `channels.feihan.accounts.<id>` 配置
- 群聊触发策略，支持仅 @提及 模式
- 入站白名单访问控制
- 消息去重（5 分钟 TTL）
- 自身消息过滤
- 客户端自动重连与鉴权重试

## 安装

从本地路径安装：

```bash
openclaw plugins install /path/to/openclaw-feihan
```

或以开发模式链接：

```bash
openclaw plugins install -l /path/to/openclaw-feihan
```

## 标识映射

- npm 包名：`@feihan/openclaw-feihan`
- 插件 ID：`openclaw-feihan`（用于 `plugins.entries` 和 `plugins.allow`）
- 频道 ID：`feihan`（用于 `channels.feihan`）

## 配置

编辑 `~/.openclaw/openclaw.json`：

```json
{
  "channels": {
    "feihan": {
      "accounts": {
        "default": {
          "enabled": true,
          "appId": "your_app_id",
          "appSecret": "your_app_secret",
          "backendUrl": "http://your-feihan-backend:21000"
        }
      }
    }
  }
}
```

也支持单账号简写（不需要 `accounts` 包装层）：

```json
{
  "channels": {
    "feihan": {
      "appId": "your_app_id",
      "appSecret": "your_app_secret",
      "backendUrl": "http://your-feihan-backend:21000"
    }
  }
}
```

`default` 账号支持环境变量回退：

- `FEIHAN_APP_ID`
- `FEIHAN_APP_SECRET`
- `FEIHAN_BACKEND_URL`
- `FEIHAN_REQUIRE_MENTION`

### 配置项参考

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `appId` | string | 必填 | 飞函应用 ID |
| `appSecret` | string | 必填 | 飞函应用密钥 |
| `backendUrl` | string | 必填 | 飞函后端地址 |
| `enableEncryption` | boolean | `true` | 是否启用加密传输 |
| `requestTimeout` | number | `30000` | API 请求超时时间（毫秒） |
| `requireMention` | boolean | `true` | 群聊中是否仅在被 @提及 时响应 |
| `botUserId` | string | 可选 | 机器人自身的用户 ID（用于过滤自身消息） |
| `inboundWhitelist` | string[] | `[]` | 非空时，仅接受这些用户 ID 的消息 |
| `enabled` | boolean | `true` | 启用/禁用该账号 |

## 架构

```
src/
  index.ts                   # 插件入口 — register(api)，服务生命周期
  channel.ts                 # 频道插件对象（元信息、能力声明、出站接口）
  config.ts                  # 配置解析、校验、环境变量回退
  targets.ts                 # 发送目标解析与规范化（user:ID, chat:ID）
  types.ts                   # TypeScript 类型定义
  core/
    feihan-client.ts         # SDK 客户端管理（按账号生命周期管理、重连）
  messaging/
    inbound.ts               # 解析 -> 过滤 -> 去重 -> 构建上下文 -> 分发
    outbound.ts              # 发送文本、输入状态、已读回执
```

**消息流程：**

```
飞函消息
  -> SDK WebSocket 事件
  -> normalizeSdkEvent（snake_case -> camelCase）
  -> parseMessageEvent（提取文本内容）
  -> checkMessageGate（自身消息、白名单、@提及 检查）
  -> isDuplicate（5 分钟 TTL 去重）
  -> buildContext（构建 OpenClaw ctxPayload）
  -> dispatchReplyWithBufferedBlockDispatcher（OpenClaw Agent 处理）
  -> deliver 回调 -> sendText（飞函 API）
  -> 回复出现在聊天中
```

## 开发

```bash
npm install              # 安装依赖
npm run build            # 编译 TypeScript
npm run typecheck        # 仅类型检查，不输出文件
npm run test             # 运行全部测试（108 个）
npm run dev              # 监听模式（修改后自动重编译）
```

## 常见问题

### "unknown channel id: feihan"

插件未加载。OpenClaw 在识别 `feihan` 之前会校验配置。请确认已通过 `openclaw plugins install` 安装插件，然后重启 OpenClaw。

### "no enabled account config found"

配置未被读取。请检查配置键是否为 `channels.feihan`，并确认 `appId`、`appSecret` 和 `backendUrl` 已正确设置。

### 已连接但机器人不回复

- 检查 OpenClaw 日志中是否有 `[feihan] dispatching message=...`，有则表示消息已接收。
- 如果看到 `gated ... reason=group-no-mention`，请设置 `requireMention: false` 或在群聊中 @提及 机器人。
- 如果看到 `gated ... reason=self-message`，请将 `botUserId` 设置为机器人的用户 ID。

### 连接错误

- Token/Preheat 错误：检查 `backendUrl`、`appId` 和 `appSecret` 是否正确。
- WebSocket 错误：检查到后端的网络连通性。
- 超时错误：增大 `requestTimeout`（默认 30 秒）。

## 许可证

MIT

tools