Feishu Plus

Name: Feishu Plus
Rating: 3.5 (1 reviews)
Author: hchen13

By hchen13 👁 3 views ▲ 0 votes

Maintained Feishu channel plugin for OpenClaw

GitHub

Install

npm install
openclaw

Configuration Example

{
  "plugins": {
    "allow": ["feishu-plus"],
    "load": {
      "paths": ["/absolute/path/to/feishu-plus"]
    },
    "entries": {
      "feishu-plus": {
        "enabled": true
      }
    }
  }
}

README

# Feishu Plus

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

Maintained Feishu channel plugin for OpenClaw.

This repository is a derivative of [`m1heng/clawdbot-feishu`](https://github.com/m1heng/clawdbot-feishu) and also backports newer bundled changes from [`openclaw/openclaw`](https://github.com/openclaw/openclaw). The real differentiators of this fork are its GroupSense-style group context experience, the dedicated sheet tool suite, and expanded bitable support.

This repo is documented and positioned as Feishu-only. Some inherited code still uses `Lark` naming because the official SDK package is `@larksuiteoapi/node-sdk`, but Lark is not a supported target here.

## Why This Fork

- GroupSense-style group context. When multiple agents share one group, you can `@` one agent and refer directly to another agent's recent message, opinion, or decision without manually restating the whole thread.
- More human-like multi-agent chat. Agents behave more like they were already in the room, instead of only seeing the last isolated prompt.
- Stronger context stack. This fork injects milestone summaries together with recent full group history, so the active agent gets both long-range memory and near-term room state.
- Dedicated sheet tooling. This repo carries a full sheet tool path instead of only the baseline document and drive capabilities inherited from bundled Feishu support.
- Expanded bitable support. Bitable functionality here goes beyond the bundled plugin and fills capability gaps that mattered in real workflows.
- Bundled doc, drive, wiki, and other upstream Feishu capabilities are still preserved here, but they are not the main reason this fork exists.

## Requirements

- OpenClaw `>= 2026.3.13`
- Node.js `>= 20`
- One or more Feishu self-built apps
- For `milestoneContext`: a host OpenClaw instance with a working local gateway and a headless `summarizer` agent

## Install

### Local path install

```bash
git clone https://github.com/hchen13/feishu-plus.git
cd feishu-plus
npm install
openclaw plugins install /absolute/path/to/feishu-plus
```

### GitHub npm-style install

```bash
openclaw plugins install github:hchen13/feishu-plus
```

### Load from config

```json
{
  "plugins": {
    "allow": ["feishu-plus"],
    "load": {
      "paths": ["/absolute/path/to/feishu-plus"]
    },
    "entries": {
      "feishu-plus": {
        "enabled": true
      }
    }
  }
}
```

## Minimal configuration

```json
{
  "channels": {
    "feishu": {
      "enabled": true,
      "connectionMode": "websocket",
      "renderMode": "auto",
      "textChunkLimit": 30000,
      "milestoneContext": {
        "enabled": false
      },
      "accounts": {
        "xinge": {
          "enabled": true,
          "appId": "cli_xxxxx",
          "appSecret": "xxxx",
          "requireMention": true,
          "dmPolicy": "open",
          "groupPolicy": "open",
          "chunkMode": "length",
          "textChunkLimit": 30000,
          "streaming": true
        }
      }
    }
  }
}
```

## Feishu App Checklist

### Base permissions

- `im:message`
- `im:message.p2p_msg:readonly`
- `im:message.group_at_msg:readonly`
- `im:message:send_as_bot`
- `im:resource`

### Tool-related permissions

Grant only the scopes you need. Typical extra scopes are:

- `docx:document` or `docx:document:readonly`
- `docx:document.block:convert`
- `drive:drive` or `drive:drive:readonly`
- `wiki:wiki` or `wiki:wiki:readonly`
- `bitable:app` or `bitable:app:readonly`
- `sheets:spreadsheet` or `sheets:spreadsheet:readonly`
- `task:task:read` or `task:task:write`
- `drive:permission` if you enable `perm`

### Event subscriptions

For `connectionMode: "websocket"`, select **Long connection** in the Feishu console.  
For `connectionMode: "webhook"`, select **Request URL** and configure webhook credentials.

Subscribe at least to:

- `im.message.receive_v1`
- `im.chat.member.bot.added_v1`
- `im.chat.member.bot.deleted_v1`

### Resource sharing

Feishu permissions alone are not enough. The bot must also be added to or shared on the actual resource:

- docs
- wiki spaces
- drive folders/files
- bitables
- sheets

If a tool can authenticate but returns empty or permission-denied results, check sharing before debugging code.

## Long Markdown And Streaming

- `textChunkLimit` controls when a reply is split into multiple Feishu messages. If you care about keeping lists or tables intact, this is the main knob.
- `chunkMode` controls how those splits happen after the limit is reached.
- `streaming: true` only enables Feishu streaming cards for that account.
- `renderMode` decides whether replies stay raw or use markdown cards. `auto` is conservative. `card` gives the most obvious streaming-card UX.
- This branch backports `disableBlockStreaming: true` for Feishu replies so OpenClaw block flushes do not prematurely close the streaming card.
- If you want smoother typing-card behavior, tune `renderMode` and upstream partial delivery first. Do not treat global `blockStreamingChunk.minChars` as the main Feishu streaming control.

## GroupSense And Milestone Context

What this repo currently does:

- stores recent group messages per chat
- periodically summarizes a discussion window
- writes milestone records under `~/.openclaw/shared-knowledge/feishu-group-milestones`
- injects recent milestone summaries back into prompts when the bot is mentioned again

What it does not do:

- it is not a fully standalone subsystem
- it depends on OpenClaw internals and a dedicated `summarizer` agent

### Required host-side pieces

1. Add a headless `summarizer` agent to `openclaw.json`:

```json
{
  "id": "summarizer",
  "name": "Summarizer",
  "workspace": "/Users/you/.openclaw/agents/summarizer",
  "model": {
    "primary": "zhipu-coding/GLM-5"
  },
  "skills": [],
  "subagents": {
    "allowAgents": []
  }
}
```

2. Keep the OpenClaw local gateway reachable. The plugin resolves an internal `callGateway` helper and uses RPC methods such as `agent`, `agent.wait`, `chat.history`, and `sessions.delete`.

3. Keep the summarizer workspace headless:

- `AGENTS.md` should define strict JSON extraction for `objectives`, `decisions`, `todos`, `risks`, and `nextSteps`
- `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`, `SOUL.md`, and `TOOLS.md` may exist, but they are not the public interface of this feature
- the summarizer agent should not be attached to any user-facing channel

4. If the summarizer path fails, the plugin falls back to a regex summarizer. The feature still works, but summary quality is materially lower.

### Important distinction

- `milestoneContext` is the actual plugin feature that records, summarizes, and injects group context.
- `groupSense` in some deployments is only a configuration namespace or deployment convention around per-group policy. It is not the milestone pipeline by itself.

## AI Agents

If you are an AI agent helping a human configure this plugin, do this in order:

1. Confirm the host is running OpenClaw `>= 2026.3.13` and decide whether the plugin will be loaded from a local path or from this GitHub repo.
2. Collect the Feishu app IDs, app secrets, and the OpenClaw agent IDs each app should serve.
3. Set the minimal `channels.feishu` block first, then add per-account overrides under `channels.feishu.accounts`.
4. Verify permissions and event subscriptions before debugging message flow. Missing event subscriptions are the most common cause of "can send but cannot receive".
5. Ask whether the human optimizes for long-markdown integrity or visible typing-card UX. Use `textChunkLimit` for the first problem and `renderMode` or `streaming` for the second.
6. If `milestoneContext` is enabled, verify that the host also has a headless `summarizer` agent and a reachable local gateway.
7. Validate with four tests:

- DM round-trip
- group `@mention`
- one long markdown reply with headings, list items, and a table
- one doc, wiki, or drive operation against a resource already shared with the bot

## Tooling

This repo exposes OpenClaw tools for:

- doc/docx
- chat
- wiki
- drive
- bitable
- sheet
- task
- permission management

`perm` is disabled by default because it changes ACLs.

## Attribution

- Derived from [`m1heng/clawdbot-feishu`](https://github.com/m1heng/clawdbot-feishu)
- Includes backports from the bundled Feishu extension in [`openclaw/openclaw`](https://github.com/openclaw/openclaw)
- Distributed under the MIT license in [LICENSE](./LICENSE)
- Additional provenance notes live in [NOTICE](./NOTICE)

channels