Feature Request: Feishu (Lark) Channel ACP Runtime Support

Summary

Request to add ACP (Agent Client Protocol) runtime support for the Feishu (Lark) channel, enabling automatic ACP session routing for external coding harnesses like OpenCode, Claude Code, Codex, etc.

Problem Statement

Currently, when configuring an ACP agent with runtime.type: "acp" in openclaw.json, messages routed to this agent via the Feishu channel do not automatically use the ACP runtime. Instead, they use the default subagent runtime, resulting in:

1. Static identity responses - The agent returns pre-configured自我介绍 instead of actually invoking the ACP tool
2. No external tool execution - ACP-backed tools (OpenCode, Claude Code, etc.) are never invoked
3. Manual workarounds required - Users must manually send /acp spawn <agent> --mode persistent to create an ACP session

Current Behavior

Feishu message → Gateway → route to agent:opencode
                                    ↓
                          Uses default runtime (subagent)
                                    ↓
                          Returns static self-introduction

Expected Behavior

Feishu message → Gateway → route to agent:opencode
                                    ↓
                          Detects runtime.type: "acp"
                                    ↓
                          Automatically creates/uses ACP session
                                    ↓
                          Invokes OpenCode via ACP protocol
                                    ↓
                          Returns actual tool execution result

Root Cause Analysis

1. Feishu Channel Limitations

• ❌ Feishu channel does not support type: "acp" bindings
• ❌ Feishu channel does not support thread: true sessions
• ❌ ACP sessions require thread binding for persistence (currently unavailable)

2. Runtime Configuration Not Auto-Applied

The agents.list[].runtime.acp configuration serves as a default template but is not automatically applied during message routing. It's only used when:

• Using /acp spawn command explicitly
• Using sessions_spawn tool with runtime: "acp"
• Using type: "acp" binding (unsupported by Feishu)

3. Official Feishu Plugin Architecture

The Feishu official plugin (@larksuite/openclaw-lark) operates at the channel layer (message I/O), while ACP runtime operates at the execution layer. The plugin currently:

• ✅ Handles message send/receive
• ✅ Handles document/calendar/task operations
• ❌ Does not handle ACP runtime routing

Proposed Solution

Option A: Automatic ACP Runtime Detection (Recommended)

Implementation: Modify the Gateway message routing logic to automatically detect and apply runtime.type: "acp" when dispatching messages to agents with ACP configuration.

Configuration:

{
  "agents": {
    "list": [
      {
        "id": "opencode",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "opencode",
            "backend": "acpx",
            "mode": "oneshot"
          }
        }
      }
    ]
  },
  "channels": {
    "feishu": {
      "acpSupport": {
        "enabled": true,
        "autoCreateSession": true,
        "sessionMode": "oneshot"
      }
    }
  }
}

Behavior:

• When a Feishu message is routed to an agent with runtime.type: "acp"
• Gateway automatically creates a temporary ACP session (if none exists)
• Message is processed through ACP runtime
• Response is sent back to Feishu

Option B: Feishu Thread Binding Support

Implementation: Add thread binding support for Feishu channel, similar to Discord/Telegram.

Configuration:

{
  "channels": {
    "feishu": {
      "threadBindings": {
        "enabled": true,
        "spawnAcpSessions": true
      }
    }
  }
}

Behavior:

• Feishu topic threads can be bound to ACP sessions
• Follow-up messages in the same thread route to the bound ACP session
• Enables persistent ACP sessions for Feishu

Option C: Feishu Plugin ACP Hook

Implementation: Add ACP runtime hook to the Feishu official plugin (@larksuite/openclaw-lark).

Configuration:

{
  "plugins": {
    "entries": {
      "feishu": {
        "config": {
          "acp": {
            "enabled": true,
            "defaultBackend": "acpx"
          }
        }
      }
    }
  }
}

Behavior:

• Feishu plugin detects ACP-configured agents
• Automatically invokes ACP runtime before processing
• Transparent to Gateway routing logic

Use Cases

Use Case 1: OpenCode Integration (Current User Need)

Setup:

{
  "agents": {
    "list": [
      {
        "id": "opencode",
        "workspace": "~/.openclaw/workspace/agents/opencode",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "opencode",
            "backend": "acpx",
            "mode": "oneshot"
          }
        }
      }
    ]
  },
  "bindings": [
    {
      "type": "route",
      "agentId": "opencode",
      "match": {
        "channel": "feishu",
        "accountId": "opencode"
      }
    }
  ]
}

Expected Flow:

1. User sends "帮我创建一个 Python 项目" to OpenCode Bot in Feishu
2. Gateway routes to agent:opencode
3. ACP runtime is automatically invoked
4. OpenCode tool executes via ACP protocol
5. Result is sent back to Feishu

Use Case 2: Multi-Agent ACP Routing

Setup: Multiple ACP agents (Claude Code, Codex, Gemini CLI) with different Feishu bots.

Expected Behavior:

• Each Feishu bot automatically uses its configured ACP runtime
• No manual /acp spawn command required
• Natural conversation flow maintained

Benefits

1. Better User Experience: Natural conversation without manual commands
2. Consistency: All channels (Discord, Telegram, Feishu) behave the same way
3. Enterprise Adoption: Feishu is widely used in Chinese enterprises; ACP support enables coding harness integration
4. Plugin Ecosystem: Enables Feishu-specific ACP tools and integrations

Technical Considerations

Session Management

• Oneshot mode: Create temporary ACP session per message (stateless)
• Persistent mode: Create long-lived ACP session (requires thread binding or session key tracking)
• Session key tracking: Store session key in Feishu conversation metadata

Performance

• ACP session creation overhead: ~100-500ms
• Consider session pooling/caching for frequently-used agents
• Implement idle timeout and cleanup

Security

• ACP sessions run on host (not sandboxed)
• Require explicit user authorization for ACP tool execution
• Implement permission gating for sensitive operations

Implementation Priority

1. High Priority: Option A (Automatic ACP Runtime Detection)

   • Minimal changes to existing architecture
   • Works with current Feishu plugin
   • No thread binding required

2. Medium Priority: Option B (Thread Binding Support)

   • Requires Feishu API support for thread metadata
   • Enables persistent sessions

3. Low Priority: Option C (Plugin ACP Hook)

   • Requires plugin architecture changes
   • More invasive changes

Current Workarounds

Workaround 1: Manual ACP Session Creation

User must send once:

/acp spawn opencode --mode persistent

Drawbacks:

• Not user-friendly
• Requires knowledge of ACP commands
• Session may expire

Workaround 2: Use Alternative Channels

Use Discord or Telegram instead of Feishu.

Drawbacks:

• Not feasible for enterprise users (Feishu is standard)
• Loses Feishu-specific integrations (docs, calendar, etc.)

References

• ACP Agents Documentation
• Feishu Plugin Documentation
• sessions_spawn Tool
• Runtime Configuration

Additional Context

This feature request originates from a real user scenario:

• User wants to integrate OpenCode (ACP-backed coding tool) with Feishu
• Current configuration routes messages correctly but doesn't invoke ACP runtime
• User receives static identity responses instead of actual code generation
• Feishu is the standard communication platform in Chinese enterprises

Labels: feature-request, acp, feishu, channel, runtime

Priority: High

Estimated Effort: Medium (2-3 days for Option A)