openclaw-lark-multi-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Lark Multi-Agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,301 @@
+# OpenClaw Lark Multi-Agent
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Run multiple Lark/Feishu bots against one OpenClaw Gateway, with each bot bound to its own model and isolated conversation state.
+
+This project is a bridge layer for OpenClaw. It does **not** implement an agent runtime itself; messages are forwarded into normal OpenClaw sessions so every bot still uses the full OpenClaw pipeline, tools, memory, slash commands, and delivery behavior.
+
+## Why this exists
+
+Lark/Feishu gives each bot its own app identity, but OpenClaw normally exposes one assistant identity per channel account. This bridge lets you create several Lark bots such as:
+
+- `GPT Bot` → `github-copilot/gpt-5.5`
+- `Gemini Bot` → `github-copilot/gemini-3.1-pro-preview`
+- `Claude Bot` → `github-copilot/claude-opus-4.7`
+
+All of them connect to the same OpenClaw Gateway while keeping sessions, queues, and private chats isolated.
+
+## Features
+
+- Multiple Lark/Feishu bot apps in one process
+- Per-bot model binding via OpenClaw session model override
+- Per-chat OpenClaw sessions: `lma-<bot>-<chatId>`
+- Private chat isolation: a p2p chat belongs to exactly one bot
+- Group chat routing:
+  - reply when directly mentioned
+  - reply to `@all` / `@_all`
+  - optional Free Discussion mode
+- Local SQLite message store for context, trigger tracking, and duplicate prevention
+- `pending_triggers` queue so restart recovery does not replay every context message
+- `delivered_replies` table so one trigger message gets at most one delivered reply per bot
+- Feishu image download and OpenClaw multimodal attachment forwarding
+- Bridge-level slash commands and escaped OpenClaw slash commands
+- Linux systemd installer with separate runtime and state directories
+
+## Architecture
+
+```text
+Lark Bot App A ┐
+Lark Bot App B ├─ WebSocket events ─→ openclaw-lark-multi-agent ─→ OpenClaw Gateway
+Lark Bot App C ┘                                              └─ SQLite state
+```
+
+The bridge stores every message as local context, but only messages that should trigger a bot response are inserted into `pending_triggers`. This distinction prevents startup drains from accidentally replaying unrelated history.
+
+## Requirements
+
+- Node.js 22+
+- npm
+- An OpenClaw Gateway reachable over HTTP/WebSocket
+- One or more Lark/Feishu self-built apps with WebSocket event subscription enabled
+- Linux systemd for the provided installer, or another process manager such as pm2
+
+## Quick start with npm
+
+After the package is published to npm:
+
+```bash
+npm install -g openclaw-lark-multi-agent
+openclaw-lark-multi-agent init
+```
+
+This creates:
+
+- config: `~/.openclaw/openclaw-lark-multi-agent/config.json`
+- data dir: `~/.openclaw/openclaw-lark-multi-agent/data/`
+
+Edit the generated config and fill in your OpenClaw Gateway token and Lark app credentials. Then run:
+
+```bash
+openclaw-lark-multi-agent start
+```
+
+Install as a systemd user service:
+
+```bash
+openclaw-lark-multi-agent install-systemd --user
+```
+
+On Windows, install [NSSM](https://nssm.cc/download), make sure `nssm.exe` is in `PATH`, then run PowerShell or Command Prompt as Administrator:
+
+```powershell
+openclaw-lark-multi-agent install-windows-service
+```
+
+Useful CLI commands:
+
+```bash
+openclaw-lark-multi-agent --help
+openclaw-lark-multi-agent doctor
+openclaw-lark-multi-agent start [config]
+openclaw-lark-multi-agent init [--state-dir DIR] [--force]
+openclaw-lark-multi-agent install-systemd [--user|--system] [--state-dir DIR]
+```
+
+## Quick start from source
+
+```bash
+git clone https://github.com/hackerphysics/openclaw-lark-multi-agent.git
+cd openclaw-lark-multi-agent
+npm ci
+cp config.example.json config.json
+```
+
+Edit `config.json`:
+
+```json
+{
+  "openclaw": {
+    "baseUrl": "http://127.0.0.1:18789",
+    "token": "YOUR_OPENCLAW_GATEWAY_TOKEN"
+  },
+  "bots": [
+    {
+      "name": "GPT",
+      "appId": "cli_xxx",
+      "appSecret": "YOUR_LARK_APP_SECRET",
+      "model": "github-copilot/gpt-5.5"
+    },
+    {
+      "name": "Gemini",
+      "appId": "cli_yyy",
+      "appSecret": "YOUR_LARK_APP_SECRET",
+      "model": "github-copilot/gemini-3.1-pro-preview"
+    }
+  ]
+}
+```
+
+Build and run locally:
+
+```bash
+npm run build
+npm start -- config.json
+```
+
+> `config.json` contains secrets and is ignored by git. Do not commit it.
+
+## Recommended Linux deployment
+
+Use the installer:
+
+```bash
+./scripts/install-linux-systemd.sh --system
+```
+
+By default it uses:
+
+- runtime files: `~/.local/lib/openclaw-lark-multi-agent/`
+- state/config/data: `~/.openclaw/openclaw-lark-multi-agent/`
+- systemd service: `openclaw-lark-multi-agent.service`
+
+Only built runtime files are deployed to the runtime directory (`dist/`, `package.json`, `package-lock.json`, production `node_modules`). Source files are not copied there.
+
+For a user service instead of a system service:
+
+```bash
+./scripts/install-linux-systemd.sh --user
+```
+
+Custom directories:
+
+```bash
+./scripts/install-linux-systemd.sh \
+  --deploy-dir ~/.local/lib/openclaw-lark-multi-agent-prod \
+  --state-dir ~/.openclaw/openclaw-lark-multi-agent-prod
+```
+
+Useful commands:
+
+```bash
+systemctl status openclaw-lark-multi-agent
+journalctl -u openclaw-lark-multi-agent -f
+sudo systemctl restart openclaw-lark-multi-agent
+```
+
+
+## Windows deployment
+
+The npm CLI works on Windows as well. It uses `%USERPROFILE%\.openclaw\openclaw-lark-multi-agent` as the default state directory.
+
+```powershell
+npm install -g openclaw-lark-multi-agent
+openclaw-lark-multi-agent init
+notepad $env:USERPROFILE\.openclaw\openclaw-lark-multi-agent\config.json
+openclaw-lark-multi-agent start
+```
+
+To run as a Windows service, install [NSSM](https://nssm.cc/download), put `nssm.exe` in `PATH`, open an elevated terminal, then run:
+
+```powershell
+openclaw-lark-multi-agent install-windows-service
+```
+
+A legacy helper script is also available at `scripts/install-windows-service.bat`.
+
+## macOS launchd
+
+A sample launchd plist is available at `scripts/openclaw-lark-multi-agent.plist`. For most users, npm CLI + a process manager is simpler.
+
+## Lark/Feishu app setup
+
+For each bot:
+
+1. Create a self-built Lark/Feishu app.
+2. Enable bot capability.
+3. Enable event subscription over WebSocket / long connection.
+4. Subscribe to message receive events.
+5. Copy the app ID and app secret into `config.json`.
+6. Add the bot to the target chats.
+
+Each bot app should have its own identity and credentials.
+
+## Commands
+
+Bridge-level commands use a single slash and are handled by this project:
+
+- `/help` — show command help
+- `/status` — show bot model, token usage, and session state
+- `/compact` — compact the OpenClaw session
+- `/reset` — reset the OpenClaw session
+- `/verbose` — toggle tool-call messages for this bot in this chat
+- `/free` — toggle Free Discussion mode in group chats
+
+OpenClaw-level slash commands can be sent by escaping with a double slash:
+
+```text
+//status
+//reset
+//compact
+```
+
+The bridge converts `//status` to `/status` and forwards it to OpenClaw instead of handling it locally.
+
+## Message routing rules
+
+### Private chats
+
+A private chat is owned by the bot connected to that chat. Other bots ignore it.
+
+### Group chats
+
+By default, a bot responds when:
+
+- it is directly mentioned;
+- `@all` / `@_all` appears in the message;
+- Free Discussion is enabled for that group.
+
+Bot messages do not trigger other bots unless they mention them. A bot-streak guard prevents infinite bot-to-bot loops.
+
+## Data model
+
+SQLite state lives in the configured data directory. Important tables:
+
+- `messages` — local conversation log and context
+- `sync_state` — per-bot/per-chat sync cursor
+- `pending_triggers` — messages that should actively trigger a bot run
+- `delivered_replies` — delivered response markers for idempotency
+- `processed_events` — Feishu event de-duplication
+- `bot_chat_settings` — per-bot/per-chat settings such as verbose mode
+
+## Development
+
+```bash
+npm ci
+npm run build
+npm run dev -- config.json
+```
+
+TypeScript output goes to `dist/`.
+
+## Repository hygiene
+
+The repository intentionally excludes:
+
+- `config.json`
+- `config*.json.bak*`
+- `.env*`
+- `data/`
+- `dist/`
+- `node_modules/`
+
+Before publishing or pushing, run:
+
+```bash
+git status --short
+git ls-files | grep -E 'config|secret|\.env' || true
+```
+
+If a secret is ever committed, remove it from the current tree and rewrite git history before making the repository public. Also rotate the leaked credential.
+
+## Security notes
+
+- Treat every Lark app secret and OpenClaw Gateway token as sensitive.
+- Use one bot app per model/identity.
+- Prefer private repositories until credentials have been audited and rotated if needed.
+- Do not expose the OpenClaw Gateway to the public internet without authentication.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,301 @@
+# OpenClaw Lark Multi-Agent
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+让多个 Lark/飞书机器人接入同一个 OpenClaw Gateway，并且每个机器人可以绑定不同模型、拥有隔离的会话状态。
+
+这个项目是 OpenClaw 的桥接层。它本身不实现 Agent Runtime；消息会被转发到标准 OpenClaw Session，因此每个机器人仍然走完整的 OpenClaw pipeline，包括工具、记忆、slash commands 和交付逻辑。
+
+## 为什么需要它
+
+Lark/飞书里每个机器人都有自己的 App 身份，但 OpenClaw 通常在一个 channel account 下暴露一个助手身份。这个桥接层可以让你创建多个飞书机器人，例如：
+
+- `GPT Bot` → `github-copilot/gpt-5.5`
+- `Gemini Bot` → `github-copilot/gemini-3.1-pro-preview`
+- `Claude Bot` → `github-copilot/claude-opus-4.7`
+
+它们共享同一个 OpenClaw Gateway，同时保持各自的 session、队列和私聊隔离。
+
+## 功能特性
+
+- 单进程接入多个 Lark/飞书机器人应用
+- 每个 bot 绑定独立模型（通过 OpenClaw session model override）
+- 每个聊天一个 OpenClaw session：`lma-<bot>-<chatId>`
+- 私聊隔离：一个私聊只归属一个 bot
+- 群聊路由：
+  - 直接 @ 某个 bot 时回复
+  - `@all` / `@_all` 时回复
+  - 可选 Free Discussion 模式
+- 本地 SQLite 消息存储，用于上下文、触发队列和重复投递防护
+- `pending_triggers` 队列，避免重启后把所有历史上下文都重新发给 OpenClaw
+- `delivered_replies` 表，保证同一个触发消息每个 bot 最多投递一次回复
+- 支持飞书图片下载，并以 OpenClaw multimodal attachment 形式转发
+- 桥接层 slash command + 转义后的 OpenClaw slash command
+- Linux systemd 安装脚本，运行产物和状态目录分离
+
+## 架构
+
+```text
+Lark Bot App A ┐
+Lark Bot App B ├─ WebSocket events ─→ openclaw-lark-multi-agent ─→ OpenClaw Gateway
+Lark Bot App C ┘                                              └─ SQLite state
+```
+
+桥接层会把所有消息存为本地上下文，但只有真正应该触发回复的消息才会写入 `pending_triggers`。这样重启恢复时不会误把普通上下文消息重新发给 OpenClaw。
+
+## 环境要求
+
+- Node.js 22+
+- npm
+- 可访问的 OpenClaw Gateway（HTTP/WebSocket）
+- 一个或多个 Lark/飞书自建应用，并启用 WebSocket 事件订阅
+- 使用内置安装脚本时需要 Linux systemd；也可以用 pm2 等其他进程管理器
+
+## 使用 npm 快速开始
+
+发布到 npm 后，可以这样安装：
+
+```bash
+npm install -g openclaw-lark-multi-agent
+openclaw-lark-multi-agent init
+```
+
+这会创建：
+
+- 配置文件：`~/.openclaw/openclaw-lark-multi-agent/config.json`
+- 数据目录：`~/.openclaw/openclaw-lark-multi-agent/data/`
+
+编辑生成的配置文件，填入 OpenClaw Gateway token 和 Lark/飞书应用凭证。然后运行：
+
+```bash
+openclaw-lark-multi-agent start
+```
+
+安装成 systemd user service：
+
+```bash
+openclaw-lark-multi-agent install-systemd --user
+```
+
+Windows 下先安装 [NSSM](https://nssm.cc/download)，确保 `nssm.exe` 在 `PATH`，然后用管理员权限打开 PowerShell 或命令提示符：
+
+```powershell
+openclaw-lark-multi-agent install-windows-service
+```
+
+常用 CLI 命令：
+
+```bash
+openclaw-lark-multi-agent --help
+openclaw-lark-multi-agent doctor
+openclaw-lark-multi-agent start [config]
+openclaw-lark-multi-agent init [--state-dir DIR] [--force]
+openclaw-lark-multi-agent install-systemd [--user|--system] [--state-dir DIR]
+```
+
+## 从源码快速开始
+
+```bash
+git clone https://github.com/hackerphysics/openclaw-lark-multi-agent.git
+cd openclaw-lark-multi-agent
+npm ci
+cp config.example.json config.json
+```
+
+编辑 `config.json`：
+
+```json
+{
+  "openclaw": {
+    "baseUrl": "http://127.0.0.1:18789",
+    "token": "YOUR_OPENCLAW_GATEWAY_TOKEN"
+  },
+  "bots": [
+    {
+      "name": "GPT",
+      "appId": "cli_xxx",
+      "appSecret": "YOUR_LARK_APP_SECRET",
+      "model": "github-copilot/gpt-5.5"
+    },
+    {
+      "name": "Gemini",
+      "appId": "cli_yyy",
+      "appSecret": "YOUR_LARK_APP_SECRET",
+      "model": "github-copilot/gemini-3.1-pro-preview"
+    }
+  ]
+}
+```
+
+本地构建和运行：
+
+```bash
+npm run build
+npm start -- config.json
+```
+
+> `config.json` 包含密钥，已被 git ignore。不要提交它。
+
+## 推荐的 Linux 部署方式
+
+使用安装脚本：
+
+```bash
+./scripts/install-linux-systemd.sh --system
+```
+
+默认目录：
+
+- 程序运行产物：`~/.local/lib/openclaw-lark-multi-agent/`
+- 状态、配置、数据：`~/.openclaw/openclaw-lark-multi-agent/`
+- systemd 服务：`openclaw-lark-multi-agent.service`
+
+安装脚本只会把运行所需文件部署到 runtime 目录：`dist/`、`package.json`、`package-lock.json` 和 production `node_modules`。源码不会复制过去。
+
+如果想安装成 user service：
+
+```bash
+./scripts/install-linux-systemd.sh --user
+```
+
+自定义目录：
+
+```bash
+./scripts/install-linux-systemd.sh \
+  --deploy-dir ~/.local/lib/openclaw-lark-multi-agent-prod \
+  --state-dir ~/.openclaw/openclaw-lark-multi-agent-prod
+```
+
+常用命令：
+
+```bash
+systemctl status openclaw-lark-multi-agent
+journalctl -u openclaw-lark-multi-agent -f
+sudo systemctl restart openclaw-lark-multi-agent
+```
+
+
+## Windows 部署
+
+npm CLI 也支持 Windows。默认状态目录是 `%USERPROFILE%\.openclaw\openclaw-lark-multi-agent`。
+
+```powershell
+npm install -g openclaw-lark-multi-agent
+openclaw-lark-multi-agent init
+notepad $env:USERPROFILE\.openclaw\openclaw-lark-multi-agent\config.json
+openclaw-lark-multi-agent start
+```
+
+如果要作为 Windows Service 运行，安装 [NSSM](https://nssm.cc/download)，把 `nssm.exe` 放进 `PATH`，用管理员权限打开终端，然后运行：
+
+```powershell
+openclaw-lark-multi-agent install-windows-service
+```
+
+兼容用的 bat 脚本也保留在 `scripts/install-windows-service.bat`。
+
+## macOS launchd
+
+示例 launchd plist 放在 `scripts/openclaw-lark-multi-agent.plist`。多数用户用 npm CLI 配合进程管理器会更简单。
+
+## Lark/飞书应用配置
+
+每个 bot 都需要一个独立的自建应用：
+
+1. 创建 Lark/飞书自建应用。
+2. 启用机器人能力。
+3. 启用 WebSocket / 长连接事件订阅。
+4. 订阅消息接收事件。
+5. 把 App ID 和 App Secret 写入 `config.json`。
+6. 把机器人加入目标聊天。
+
+建议每个模型/身份对应一个独立 bot app。
+
+## 命令
+
+单斜杠命令由桥接层处理：
+
+- `/help` — 显示命令帮助
+- `/status` — 显示 bot 模型、token 使用和 session 状态
+- `/compact` — 压缩 OpenClaw session
+- `/reset` — 重置 OpenClaw session
+- `/verbose` — 开关当前 bot 在当前聊天里的 tool-call 展示
+- `/free` — 开关群聊 Free Discussion 模式
+
+如果你想把 slash command 直接发给 OpenClaw，可以用双斜杠转义：
+
+```text
+//status
+//reset
+//compact
+```
+
+桥接层会把 `//status` 转成 `/status` 并转发给 OpenClaw，而不是自己处理。
+
+## 消息路由规则
+
+### 私聊
+
+私聊归属当前 bot，其他 bot 不会处理这个私聊。
+
+### 群聊
+
+默认情况下，bot 会在这些场景回复：
+
+- 被直接 @；
+- 消息里出现 `@all` / `@_all`；
+- 当前群开启了 Free Discussion 模式。
+
+bot 发出的消息默认不会触发其他 bot，除非明确 @。同时有 bot-streak 防护，避免 bot 之间无限互相回复。
+
+## 数据模型
+
+SQLite 状态位于配置的数据目录。主要表：
+
+- `messages` — 本地对话日志和上下文
+- `sync_state` — 每个 bot / chat 的同步游标
+- `pending_triggers` — 应主动触发 bot run 的消息
+- `delivered_replies` — 已投递回复标记，用于幂等防重复
+- `processed_events` — 飞书事件去重
+- `bot_chat_settings` — 每个 bot / chat 的设置，例如 verbose mode
+
+## 开发
+
+```bash
+npm ci
+npm run build
+npm run dev -- config.json
+```
+
+TypeScript 输出目录是 `dist/`。
+
+## 仓库卫生
+
+仓库会忽略：
+
+- `config.json`
+- `config*.json.bak*`
+- `.env*`
+- `data/`
+- `dist/`
+- `node_modules/`
+
+发布或 push 前建议检查：
+
+```bash
+git status --short
+git ls-files | grep -E 'config|secret|\.env' || true
+```
+
+如果密钥曾经被提交，需要从当前 tree 删除、重写 git 历史、force push，并轮换泄露的凭证。
+
+## 安全说明
+
+- Lark/飞书 App Secret 和 OpenClaw Gateway token 都是敏感信息。
+- 建议一个模型/身份对应一个 bot app。
+- 在完成凭证审计和必要轮换前，建议保持私有仓库。
+- 不要在没有认证保护的情况下把 OpenClaw Gateway 暴露到公网。
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+## Supported versions
+
+This project is pre-1.0. Security fixes are applied to the default branch.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for suspected credential leaks or security vulnerabilities.
+
+If this repository is hosted on GitHub, use GitHub private vulnerability reporting when available, or contact the repository owner privately.
+
+## Credential handling
+
+Never commit:
+
+- `config.json`
+- Lark/Feishu app secrets
+- OpenClaw Gateway tokens
+- `.env` files
+- database files under `data/`
+
+If a secret is committed:
+
+1. Remove it from the current tree.
+2. Rewrite git history to purge it.
+3. Force-push the cleaned history.
+4. Rotate the leaked credential.
+5. Re-clone any local working copies from the cleaned repository.

package/config.example.json

@@ -0,0 +1,26 @@
+{
+  "openclaw": {
+    "baseUrl": "http://127.0.0.1:18789",
+    "token": "YOUR_GATEWAY_TOKEN"
+  },
+  "bots": [
+    {
+      "name": "Claude",
+      "appId": "cli_xxx1",
+      "appSecret": "xxx1",
+      "model": "github-copilot/claude-opus-4.6-1m"
+    },
+    {
+      "name": "GPT",
+      "appId": "cli_xxx2",
+      "appSecret": "xxx2",
+      "model": "github-copilot/gpt-5.5"
+    },
+    {
+      "name": "Gemini",
+      "appId": "cli_xxx3",
+      "appSecret": "xxx3",
+      "model": "github-copilot/gemini-3.1-pro-preview"
+    }
+  ]
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};