Feishu Agent Relay - Multi-Bot Collaboration

Enables multi-Agent collaboration on Feishu by relaying tasks between coordinator and specialist Bots with user ID mapping and proactive messaging.

Security Scan

The skill's functionality (Feishu multi‑bot relay) matches the included code and docs, but there are clear inconsistencies around declared credentials/environment requirements and an insecure manual registration flow that make it risky for anything beyond local/personal testing.

Purpose & Capability

The skill's stated purpose—coordinating multiple Feishu Bots and maintaining a cross‑Bot user mapping—matches the provided documentation and the mapping-api.js code. However, the skill expects Feishu App IDs, App Secrets, verification tokens, webhook endpoints and runtime tools (sessions_send, message) yet declares no required environment variables or primary credential in the registry metadata. That omission is inconsistent: a legitimate Feishu integration normally requires storing bot credentials (appId/appSecret/verification token) and/or connector configuration.

Instruction Scope

SKILL.md instructs the agent and the user to create multiple Feishu Bots, enable event subscriptions, expose webhooks (ngrok or cloud function), copy mapping-api.js into the workspace, and read/write a local user-mapping.json. The instructions don't ask the agent to read unrelated system files or exfiltrate data. The major functional risk described in the docs is explicit: manual User ID registration in multi-user mode has no verification and can be spoofed. The instructions also recommend exposing webhook URLs (ngrok/OpenClaw gateway), which increases the attack surface if misconfigured.

Install Mechanism

This is an instruction-only skill with a single small JavaScript utility file included; there is no external download/install step or third‑party package installation mandated by the skill. The mapping-api.js uses only node fs/path and will operate locally. No high‑risk install URLs or archive extraction are present.

Credentials

The skill clearly requires Feishu bot credentials and runtime configuration (App IDs, App Secrets, verification tokens, webhook endpoints) to function, but the registry metadata lists no required environment variables or primary credential. That mismatch is concerning because it hides the real secrets the deployment must have and may lead users to misconfigure secrets or store them insecurely. Additionally, the mapping table stored on disk contains user IDs and Feishu open_ids which are sensitive and should be protected; the skill does not include guidance for secure storage/ACLs beyond basic docs.

Persistence & Privilege

The skill does not request always:true or system-wide privileges. The included code writes to a local user-mapping.json file in the agent workspace; that is expected for the stated purpose. It does not modify other skills or system settings. Persistent presence and autonomous invocation are default platform behaviors and are not elevated by this skill.

What to consider before installing

This skill appears to do what it says (relay tasks between Feishu Bots) but has two practical concerns you should weigh before installing: (1) it needs per‑Bot Feishu credentials (App ID/Secret/verification token) and webhook endpoints even though the registry metadata doesn't declare any required env vars — make sure you won't accidentally paste secrets into an insecure file or public workspace; (2) Multi‑user mode relies on manual User ID input with no verification, so user identity can be spoofed and the mapping table will contain sensitive open_id ↔ user_id mappings. Recommended precautions: test in single‑user mode or an isolated workspace first; store App Secrets in a secure secret store (not checked into the workspace); set strict filesystem permissions on user-mapping.json; avoid exposing webhooks publicly during testing (or secure them); and add an authentication/verification layer (SSO/LDAP) before using multi‑user mode in production.

Feishu Agent Relay

🚨 Installation: Choose Your Mode First!

⚠️ BEFORE SETUP: You must choose a deployment mode!

Mode	For	User ID	Setup	Security
Single-User	Personal use	Auto ("me")	✅ 5 min	✅ High
Multi-User	Teams	Manual entry	⚠️ 30 min	⚠️ Low

Quick Decision Guide

Choose Single-User Mode if:

• ✅ Only YOU will use the Bots
• ✅ Personal productivity system
• ✅ Want ZERO manual configuration
• ✅ Want fastest setup (5 minutes)

📖 Guide: references/single-user-setup.md

Choose Multi-User Mode if:

• ✅ Multiple people will use the system
• ✅ Team or organization
• ✅ Need to track different users
• ✅ Planning to add verification later

📖 Guide: references/feishu-bot-setup.md

---

⚠️ Important Limitations

Read this before using the skill:

1. Manual User ID Registration ⚠️ SECURITY LIMITATION (Multi-User Mode Only)

Current flow requires users to manually enter their User ID:

User → Bot: "你好"
Bot → User: "请告诉我您的 User ID（工号/用户名）"
User → Bot: "我的 user ID 是：user_demo_001"  ← ⚠️ MANUAL STEP - NO VERIFICATION

⚠️ Risks:

• ❌ No identity verification - System trusts whatever user types
• ❌ Identity spoofing possible - User could claim another person's ID
• ❌ Human error - Users may mistype their ID
• ❌ No audit trail - Cannot prove who actually registered
• ❌ NOT production-ready - Internal/personal use ONLY

✅ Acceptable for:

• Personal projects (use Single-User Mode!)
• Small team internal tools
• Testing and prototyping

❌ NOT acceptable for:

• Production systems
• External-facing applications
• Security-sensitive operations

🔧 Single-User Mode avoids this: No manual ID entry needed!

---

2. Multiple Feishu Bots Required 🔧 SETUP REQUIRED

This skill requires multiple Feishu Bot applications:

Bot Type	Quantity	Example Names
Coordinator	1	协调员
Specialists	2+	技术专家，产品专家

📖 Setup Guide: references/feishu-bot-setup.md

---

⚡ Single-User Mode: Zero Configuration

Recommended for personal use!

# 1. Set environment variable
export DEPLOYMENT_MODE=single-user

# 2. Create empty mapping table (no users needed)
cat > user-mapping.json << 'EOF'
{
  "version": "1.0",
  "users": {},
  "agents": { ... }
}
EOF

# 3. Contact any Bot - auto-registers you!
# That's it! No manual User ID entry needed.

How it works:

• First contact: Bot auto-registers you as userid "me"
• All Bots: Automatically track your open_id
• Relay: Uses hardcoded userid "me" (no queries needed)
• Security: No identity spoofing risk (only you)

📖 Full guide: references/single-user-setup.md

---

👥 Multi-User Mode: Manual Configuration

For teams and organizations.

# 1. Set environment variable
export DEPLOYMENT_MODE=multi-user

# 2. Each user must register:
User → Bot: "你好"
Bot → User: "请告诉我您的 User ID"
User → Bot: "我的 user ID 是：zhangsan"

⚠️ Security Warning: Manual User ID entry has NO verification. Internal use only!

📖 Full guide: references/feishu-bot-setup.md

---

Quick Start

This skill enables multi-Agent collaboration on Feishu where:

• Users contact a coordinator Bot
• Coordinator relays tasks to specialist Bots
• Specialists proactively message users

User → Coordinator Bot → sessions_send → Specialist Bot → User (proactive DM)
                          (userid only)    queries mapping

---

📋 Setup Checklist

Phase 1: Feishu Bot Configuration (~30 minutes)

• Create Feishu Developer Account
• Create Coordinator Bot + Specialist Bots
• Configure Permissions
• Configure Event Subscriptions
• Test Each Bot

📖 Guide: references/feishu-bot-setup.md

Phase 2: Choose Deployment Mode

• Single-User: Set DEPLOYMENT_MODE=single-user
• Multi-User: Set DEPLOYMENT_MODE=multi-user
• Initialize mapping table
• Deploy mapping API

📖 Single-User Guide: references/single-user-setup.md

Phase 3: Testing (~15 minutes)

• Test first contact (auto-register or manual)
• Test relay flow
• Test proactive message
• Verify mapping table

---

When to Use This Skill

Use when:

• ✅ Multiple Feishu Bots working together
• ✅ Users contact one Bot, receive responses from different Bots
• ✅ Cross-Bot user identity management needed
• ✅ Specialist Bots proactively message users

Don't use for:

• ❌ Single-Bot scenarios
• ❌ Production without verification (multi-user)
• ❌ External-facing applications

---

Architecture

┌─────────────────┐
│     User        │
│  (Feishu DM)    │
└────────┬────────┘
         │ 1. User contacts coordinator
         ▼
┌─────────────────┐     2. Coordinator identifies user
│  Coordinator    │        (auto or manual)
│    Agent        │
│  (orchestrator) │     3. Relay via sessions_send
└────────┬────────┘        (userid only)
         │
         ▼
┌─────────────────┐     4. Specialist queries mapping
│   Specialist    │        for own open_id
│    Agent        │
└────────┬────────┘     5. Send proactive DM
         │
         ▼
┌─────────────────────────┐
│   user-mapping.json     │
│  userid → open_id map   │
└─────────────────────────┘

---

Critical Concept: Feishu open_id Isolation

Each Bot has different open_id for the same user:

Same user (userid: user_demo_001):
├─ Coordinator Bot:    ou_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
├─ Tech Expert Bot:    ou_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
└─ Product Expert Bot: ou_cccccccccccccccccccccccccccccccc

You CANNOT use one Bot's open_id for another Bot!

Correct Relay Pattern ✅

// 1. Coordinator queries userid
const user = await mapping.getUserByOpenId('coordinator', userOpenId);

// 2. Send relay (userid only, NO open_id)
await sessions_send({
  agentId: 'product-expert',
  sessionKey: 'agent:product-expert:main',  // ✅ Key!
  message: `【转接任务】用户 User ID: ${user.userid}`
});

// 3. Specialist queries mapping for ITS OWN open_id
const userOpenId = mapping.users[userId]?.botOpenIds?.['product-expert'];

// 4. Send message using correct open_id
await message({
  action: 'send',
  channel: 'feishu',
  target: userOpenId,  // ✅ This Bot's open_id
  message: '您好，我是产品专家...'
});

---

Workflows

Workflow 1A: Single-User - Auto Registration

const DEPLOYMENT_MODE = process.env.DEPLOYMENT_MODE || 'single-user';
const SINGLE_USER_ID = 'me';

const userOpenId = getMessageContext().from;

// Auto-register on first contact
const existing = await mapping.getBotOpenId(SINGLE_USER_ID, 'coordinator');

if (!existing) {
  await mapping.updateBotOpenId(SINGLE_USER_ID, 'coordinator', userOpenId, 'Default User');
  
  await message({
    message: `您好！🎉 系统已自动配置完成（单用户模式）。`
  });
  return;
}

Workflow 1B: Multi-User - Manual Registration

const userOpenId = getMessageContext().from;
const user = await mapping.getUserByOpenId('coordinator', userOpenId);

if (!user) {
  // Ask for User ID
  await message({
    message: `您好！请告诉我您的 User ID（工号/用户名）。`
  });
  return;
}

await mapping.updateBotOpenId(user.userid, 'coordinator', userOpenId, user.name);

Workflow 2: Coordinator Relay

const user = await mapping.getUserByOpenId('coordinator', userOpenId);

await sessions_send({
  agentId: 'product-expert',
  sessionKey: 'agent:product-expert:main',
  message: `【转接任务】用户 User ID: ${user.userid}, 任务：${task}`
});

Workflow 3: Specialist Proactive Message

const userId = extractUserId(message);
const userOpenId = mapping.users[userId]?.botOpenIds?.['product-expert'];

if (!userOpenId) {
  await sessions_send({
    agentId: 'coordinator',
    message: `用户 ${userId} 尚未与我建立对话`
  });
  return;
}

await message({
  action: 'send',
  channel: 'feishu',
  target: userOpenId,
  message: '您好，我是产品专家...'
});

---

User Mapping Table

Single-User Mode (Auto-populated)

{
  "version": "1.0",
  "users": {
    "me": {
      "name": "Default User",
      "botOpenIds": {
        "coordinator": "ou_xxx",
        "tech-expert": "ou_yyy",
        "product-expert": "ou_zzz"
      }
    }
  },
  "agents": { ... }
}

Multi-User Mode (Manual registration)

{
  "version": "1.0",
  "users": {
    "zhangsan": {
      "name": "张三",
      "botOpenIds": {
        "coordinator": "ou_abc...",
        "product-expert": "ou_def..."
      }
    },
    "lisi": { ... }
  },
  "agents": { ... }
}

---

Configuration

Environment Variables

Variable	Values	Default	Description
DEPLOYMENT_MODE	single-user, multi-user	multi-user	Deployment mode
SINGLE_USER_ID	Any string	"me"	User ID for single-user

Agent SOUL.md Template

# SOUL.md - 协调者

## 部署模式
- Mode: single-user (或 multi-user)
- User ID: "me" (single-user) 或 dynamic (multi-user)

## 配置
- Bot App ID: cli_xxx
- 映射表：/path/to/user-mapping.json

---

Error Handling

400 "cross app open_id"

Cause: Using wrong Bot's open_id.

Fix: Each Bot must use its own open_id from mapping.

User not found

Cause: First-time user, not registered.

Fix: Auto-register (single-user) or ask for ID (multi-user).

---

Testing Checklist

• Bots created and configured
• Deployment mode set
• Mapping table initialized
• First contact works
• Relay flow works
• Proactive message works
• Mapping table updated correctly

---

Best Practices

DO ✅

• Use agent:xxx:main for sessionKey
• Pass only userid in relay
• Let specialists query own open_id
• Use mapping API (not direct file access)
• Choose appropriate deployment mode
• Auto-register in single-user mode

DON'T ❌

• Pass open_id in relay
• Use one Bot's open_id for another
• Use feishu:direct:openid sessionKey
• Use multi-user for production without verification
• Share single-user Bots with others

---

Security Considerations

Single-User Mode ✅

• No identity spoofing risk (only you)
• No manual ID entry
• Automatic registration
• Recommended for personal use

Multi-User Mode ⚠️

• Manual ID entry (no verification)
• Identity spoofing possible
• Internal use only
• Add verification for production

---

Resources

scripts/

• mapping-api.js - Unified mapping API

references/

• single-user-setup.md - Single-user mode guide (START HERE for personal use)
• feishu-bot-setup.md - Multi-user mode guide
• mapping-schema.md - Schema details
• relay-examples.md - Code examples

---

Version: 1.2
Last Updated: 2026-03-07
Deployment Modes: Single-User (zero-config) | Multi-User (manual)
Recommendation: Start with Single-User for testing, switch to Multi-User for teams
Status: ✅ Functional for internal/personal use | ⚠️ Not production-ready (multi-user mode)