Feishu Integration in Practice

Feishu is one of the best platforms for integrating Hermes Agent in China. This chapter walks you through a complete Feishu integration from scratch, including common pitfalls and optimizations.

Scenario Description

You use Feishu at work and want to integrate Hermes Agent as a team Bot so that team members can use AI capabilities through Feishu.

Prerequisites

• ✅ Feishu account (with Open Platform access)
• ✅ Hermes Agent installed
• ✅ Gateway configured

Basic Configuration

Feishu is the mainstream enterprise collaboration platform in China. Hermes receives messages via the Feishu Open Platform's WebSocket long connection — no need to expose a public webhook URL. It works in both direct message and group chat scenarios.

Create a Feishu Application

1. Open the Feishu Open Platform, log in, and click "Create Enterprise Custom App"
2. Fill in the application name (e.g., "My AI Cuttlefish"), description, and choose an app icon
3. Go to the app details page → "Credentials & Basic Info", and copy and securely store the App ID (format cli_xxx) and App Secret

Security Reminder

Keep your App Secret confidential. Do not commit it to code repositories or share it publicly. If it is accidentally leaked, reset it immediately on the Open Platform.

Lark (International Version) Users: Visit open.larksuite.com/app, and set FEISHU_DOMAIN to lark in subsequent configuration.

Configure Application Permissions

Go to the app's "Permission Management" page, click "Batch Import", and paste the following JSON:

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg:readonly",
      "im:resource",
      "im:chat",
      "im:chat:readonly",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.base:readonly",
      "contact:user.employee_id:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write"
    ],
    "user": [
      "im:message",
      "im:message:readonly",
      "im:chat",
      "im:chat:readonly",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

These permissions cover core functionality including message sending and receiving, group chat management, contact access, and card messages. Some permissions may fail to import due to Feishu version differences — skip them; they won't affect core messaging functionality.

Enable the Bot Capability & Configure Event Subscription

1. Go to "App Capabilities" → "Bot", enable the Bot capability, and set the Bot name and description
2. Go to the "Event Subscription" page:
   • Select "Use long connection to receive events" (WebSocket mode)
   • Add the event: im.message.receive_v1

Note

Make sure you've completed the Hermes-side configuration and started the Gateway, otherwise the long connection settings may not save.

Publish the Application

Go to "Version Management & Release" → Create an app version → Submit for review and publish. Enterprise Custom Apps are typically approved automatically.

Install Dependencies

Critical: venv vs System Python

The Hermes binary uses the Python interpreter inside the project's venv. All pip installs must target the venv, otherwise installed packages won't be visible to Hermes.

# For source installation users
/path/to/hermes-agent/venv/bin/pip install lark_oapi websockets python-socks

# For one-click installer users
hermes pip install lark_oapi websockets python-socks

Known Issue: Missing python-socks

If your system environment has SOCKS proxy variables set (e.g., ALL_PROXY), the Lark SDK will require the python-socks package at import time. If it's not installed in the venv, Gateway startup will fail:

[Lark] [ERROR] connect failed, err: python-socks is required to use a SOCKS proxy

Fix: Make sure it's installed in the correct Python environment — venv/bin/pip install python-socks, not the system pip.

Configure Hermes

Option A: Interactive Configuration

hermes gateway
# Select Feishu / Lark
# Enter your App ID and App Secret when prompted
# Select WebSocket mode

Option B: Manual Configuration

Edit ~/.hermes/.env and add:

# Feishu / Lark basic configuration
FEISHU_APP_ID=cli_xxxxxxxxxx         # Replace with your App ID
FEISHU_APP_SECRET=***    # Replace with your App Secret
FEISHU_DOMAIN=feishu                 # feishu (China) or lark (International)
FEISHU_CONNECTION_MODE=websocket     # Recommended: WebSocket long connection mode

# User access control
GATEWAY_ALLOW_ALL_USERS=true         # Testing phase: allow all users
# For production, change to false and configure the whitelist:
# FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy  # Users' open_id, comma-separated

Start the Gateway

hermes gateway start

After starting, check the logs to confirm the WebSocket connection is established:

tail -f ~/.hermes/logs/gateway.log

A successful log entry should contain:

[Lark] [INFO] connected to wss://msg-frontier.feishu.cn/ws/v2?...

Search for your Bot's name in Feishu and send a test message. If Cuttlefish replies, the connection is successful!

Set Up Home Chat

/set-home

After this, all Cron task results will be sent to this chat.

Advanced: Group Chat Configuration

After adding the Bot to a group chat, configure the group chat policy:

# ~/.hermes/.env
# always: Respond to all messages that @mention the Bot in group chats
# mention_only: Only respond to @mentions
FEISHU_GROUP_POLICY=always

Bot Name Auto-Discovery

For accurate @mention detection, Hermes needs to know the Bot's name. After granting the application:application:self_manage permission, it will be fetched automatically at startup. You can also set it manually:

FEISHU_BOT_NAME=My AI Cuttlefish

Common Issues & Solutions

Issue 1: WebSocket Connection Drops Immediately After Connecting

Cause: Incorrect App Secret or permissions not enabled

Solution:

1. Confirm the App Secret was copied in full (no extra spaces)
2. Check that the "Send and Receive Messages" permission has been approved
3. Confirm the app has been published (unpublished apps cannot be used)

Issue 2: Message Sent Successfully but No Reply Received

Cause: LLM Provider not configured or API Key expired

Solution:

hermes doctor
hermes model    # Check current model

Issue 3: Bot Doesn't Respond in Group Chats

Cause: Improper FEISHU_GROUP_POLICY configuration or Bot name mismatch

Solution:

1. Check the FEISHU_GROUP_POLICY setting
2. Make sure the Bot is actually @mentioned in the group chat
3. Check whether Bot name auto-discovery succeeded

Issue 4: Connection Fails in a Proxy Environment

Cause: The Feishu SDK doesn't use the system proxy

Solution:

# Ensure python-socks is installed in the venv
venv/bin/pip install python-socks

# Set proxy environment variables
HTTPS_PROXY=http://127.0.0.1:7890
HTTP_PROXY=http://127.0.0.1:7890

Production Optimization

User Permission Management

# Switch from ALLOW_ALL to specific users
GATEWAY_ALLOW_ALL_USERS=false
FEISHU_ALLOWED_USERS=ou_user1,ou_user2,ou_user3

# Or enable the DM pairing system (more secure)
# Don't set ALLOW_ALL; let new users join via pairing code

Webhook Encryption (Webhook Mode Only)

FEISHU_ENCRYPT_KEY=xxxxxxxx        # Obtain from the Event Subscription page
FEISHU_VERIFICATION_TOKEN=***     # Double verification

Message Format Optimization

Adjust message display in config.yaml:

display:
  tool_progress: true
  background_process_notifications: true

Operations Command Reference

hermes gateway start      # Start background service
hermes gateway stop       # Stop service
hermes gateway restart    # Restart service
hermes gateway status     # Check status
hermes doctor             # Health check
hermes doctor --fix       # Auto-fix issues
tail -f ~/.hermes/logs/gateway.log  # Live logs

Further Reading

• Chapter 4: Chat Platform Integration — Basic configuration
• Chapter 8: Gateway Operations — Gateway management
• Feishu Official Documentation