Hermes Feishu Group Chat Unresponsive: Complete Troubleshooting & Fix Guide for Linux

When using Hermes Agent to integrate with Feishu group chats on Linux systems, a highly common issue is that the bot responds normally in private chats but shows no reaction when mentioned in group chats. This problem does not stem from a single cause; it mainly arises from incomplete Feishu application configurations, unenabled Hermes gateway policies, unauthorized permissions, or unreleased versions. This guide breaks down the full troubleshooting process from basic status checks to in-depth log analysis, providing copy-and-run repair commands and configuration solutions to help technical professionals efficiently locate and resolve response issues between Hermes and Feishu group chats.

1. Core Logic of Hermes Group Chat Support

Before starting troubleshooting, clarify the core support rules of Hermes for Feishu group chats to quickly narrow down the root cause:

  • Hermes uses a whitelist mode for Feishu group chats by default; you must manually set it to an open policy to receive group messages.
  • In group chat scenarios, Hermes does not auto-respond to messages and can only be triggered by @mentioning the bot (no @mention is required in private chats).
  • Whether Feishu messages can be pushed to the Hermes gateway depends on permission configurations, event subscriptions, and version release status in the Feishu Open Platform.
  • Gateway connection status and model pairing authorization are fundamental prerequisites for Hermes to respond to messages—neither can be missing.

2. Step 1: Basic Status Check & Gateway Restart

The core troubleshooting principle is verify basic connectivity first, then troubleshoot advanced configurations. First, check the Hermes gateway status and restart it to eliminate basic issues caused by an inactive gateway.

2.1 Check Hermes Gateway Status

Run the following command to directly view the gateway running status and Feishu channel connection:

hermes status

In normal status, the output will include running (gateway active) and feishu connected (Feishu channel connected). If these statuses are missing, the gateway is not running properly or the Feishu channel is disconnected.

2.2 Restart the Hermes Gateway

Regardless of the status, perform a restart to ensure the gateway loads the latest configurations:

hermes gateway restart

If the restart prompts a permission error or service not found, stop the background service and start it manually:

hermes gateway stop
hermes gateway

Manual (foreground) startup allows real-time log viewing, which is critical for subsequent troubleshooting.

3. Step 2: Hermes Core Configuration Fix (One-Click Linux Commands)

The primary configuration issues causing unresponsive Feishu group chats are unenabled group chat policies, user permission blocks, and missing Feishu credentials. Below are copy-and-run repair commands that resolve 90% of configuration issues when executed in sequence:

# 1. Enable Feishu group chat policy (whitelist blocks all group messages by default)
hermes config set FEISHU_GROUP_POLICY open

# 2. Allow access for all users (enable for testing to avoid user permission blocks)
hermes config set GATEWAY_ALLOW_ALL_USERS true

# 3. Disable @mention-only reply (optional, improves group chat usability)
hermes config set GATEWAY_REPLY_AT_ONLY false

# 4. Configure Feishu app credentials (replace with your App ID and Secret)
hermes config set FEISHU_APP_ID cli_xxxx
hermes config set FEISHU_APP_SECRET xxxx

# 5. Add encryption/verification parameters if configured in Feishu (match platform settings)
# hermes config set FEISHU_ENCRYPT_KEY xxxx
# hermes config set FEISHU_VERIFICATION_TOKEN xxxx

# 6. Restart the gateway to apply configurations
hermes gateway restart

3.1 Optimized Configurations for Common Scenarios

Below are optimized environment variable configurations for two typical use cases—replace directly for immediate use:

Scenario 1: Backup Hermes Bot Configuration

HERMES_MAX_ITERATIONS=90
FEISHU_APP_ID=cli_a969108d0e78dbb5
FEISHU_APP_SECRET=BaHhJsjiaLy4jxRKclPiXeo7onKjTBcf
GATEWAY_ALLOW_ALL_USERS=true
FEISHU_GROUP_POLICY=open
FEISHU_BOT_NAME=Backup Hermes       # Must exactly match the bot name in the Feishu Admin Console
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOW_ALL_USERS=true
FEISHU_ALLOWED_USERS=            # Leave blank in open policy mode
FEISHU_BOT_AT_MENTION_USE_NAME=true  # Match @mentions by bot name
FEISHU_LOG_LEVEL=debug               # Enable Debug mode for log analysis

Scenario 2: Hermes@Cloud Bot Configuration

HERMES_MAX_ITERATIONS=90
FEISHU_APP_ID=cli_a957ae909b38dcdd
FEISHU_APP_SECRET=NfaVIGuTczYnfVOZ3mtRshkMYUyP8hpq
FEISHU_BOT_NAME=Hermes@Cloud
FEISHU_CONNECTION_MODE=websocket
FEISHU_GROUP_POLICY=open
FEISHU_ALLOW_ALL_USERS=true
GATEWAY_ALLOW_ALL_USERS=true
FEISHU_LOG_LEVEL=debug

3.2 Critical Configuration Notes

  • FEISHU_BOT_NAME must exactly match the bot name displayed in the Feishu Open Platform and group chats (including spaces and special characters like @). A name mismatch will prevent the bot from detecting @mentions.
  • FEISHU_CONNECTION_MODE must be set to websocket to match the event subscription method in the Feishu Open Platform.
  • Enable FEISHU_LOG_LEVEL=debug to simplify root-cause identification via logs.

4. Step 3: Feishu Open Platform Configuration (Most Commonly Overlooked)

Even with correct local Hermes configurations, group messages will not reach the Hermes gateway without completed permissions, event subscriptions, and version releases in the Feishu Open Platform. Follow these mandatory configuration steps strictly:

4.1 Enable Core Feishu Open Platform Permissions

Log in to the Feishu Open Platform, navigate to your application, and go to Permission Management. You must enable the following API permissions (all are required):

  1. im:message.group_at_msg:readonly (Read messages that @mention the bot in groups)
  2. im:message.p2p_msg:readonly (Receive private chat messages—foundation for normal private chat responses)
  3. im:message (Send messages—core permission for bot replies)
  4. Optional additions: im:chat:readonly (Retrieve group information), admin:app.info:readonly (Auto-detect Bot ID)

4.2 Configure Event Subscriptions

Go to Events & Callbacks → Event Configuration and complete the following setup:

  1. Toggle on Enable Subscription.
  2. Add the core event: im.message.receive_v1 (Message Reception v1.0—required for Feishu to push messages to Hermes).
  3. Select the subscription method: Long Connection (WebSocket) (matches FEISHU_CONNECTION_MODE=websocket in Hermes).
  4. Confirm the event status is Enabled.

4.3 Release a Version (Mandatory for Permissions to Take Effect)

After configuring permissions and events, you must publish a new version for changes to apply:

  1. Navigate to Version Management & Release.
  2. Click Create Version and add a description (e.g., “Group chat function fix”).
  3. Save and click Publish, then select Enterprise Internal Release.
  4. Wait 1–2 minutes for configurations to take effect in the Feishu backend.

“

Important: Unpublished versions mean all permission and event configurations are inactive—the top hidden cause of unresponsive group chats.

5. Step 4: Group Chat Usage & Authorization Requirements

After completing configurations, ensure your group chat operations comply with Hermes trigger rules to avoid false unresponsiveness:

  1. Add the bot to the target group: Go to Feishu group Settings → Apps and add your bot.
  2. Group chat trigger rule: Only @mention the bot to trigger a response (e.g., @Backup Hermes Hello). Hermes does not auto-respond to unmentioned group messages.
  3. First-time pairing authorization:

    • Send a private message to the bot to receive a pairing code.
    • Run hermes pairing approve <code> in the Linux terminal to complete authorization.
    • Simplify authorization by setting a default channel with /sethome.
  4. Avoid anonymous messages: Feishu anonymous messages cannot be received by the bot and will cause @mentions to fail.

6. Step 5: Log Analysis (Ultimate Troubleshooting Method)

If the issue persists after all configurations, use log analysis to pinpoint the root cause. Two primary methods are available for viewing Hermes gateway logs on Linux:

6.1 Foreground Startup for Real-Time Logs (Recommended)

Stop the background gateway and start it in the foreground to view live log output:

hermes gateway stop
hermes gateway

@mention the bot in the Feishu group and observe the logs. The table below explains key log keywords:

Log Keyword Meaning Troubleshooting Direction
✓ Feishu channel connected Feishu channel is connected Basic gateway-Feishu connectivity is normal
message received Group message received Issue lies in Hermes permissions/model configuration
Mention detected Bot @mention recognized Bot name matching is normal
Group message allowed (policy=open) Open group policy active Policy configuration is normal
No log output No message pushed by Feishu Unpublished Feishu configs or missing permissions

6.2 Background Service Logs (systemd Deployment)

If the Hermes gateway runs as a systemd service, view real-time logs with these commands:

# For non-root user services
journalctl --user -u hermes-gateway -f

# For root user services
journalctl -u hermes-gateway -f

The -f flag enables real-time log refresh to monitor activity when @mentioning the bot.

7. Frequently Asked Questions (FAQ)

Below are precise answers to the most common issues encountered during troubleshooting:

Q1: How do I check if group @mention permissions are enabled in the Feishu backend?

  1. Log in to the Feishu Open Platform and select your application.
  2. Click Permission Management in the left sidebar.
  3. Search for im:message.group_at_msg:readonly in the API permission list.
  4. If marked Enabled, the permission is active; if Disabled, click to enable and authorize.

“

Note: Permissions only take effect after publishing a new version—enablement alone is insufficient.

Q2: How long does it take for a Feishu published version to take effect?

Versions typically take 1–2 minutes to take effect after publication. For enterprises with custom permission approval workflows, this may extend to up to 5 minutes.

“

Validation: Restart the Hermes gateway (hermes gateway restart) after publication, run it in the foreground, and check for ✓ Feishu channel connected, then test with an @mention.

Q3: How do I verify if Feishu is pushing messages to the bot?

Log analysis is the most direct method:

  1. Start the Hermes gateway in the foreground (hermes gateway).
  2. Send a test message by @mentioning the bot (e.g., @Hermes@Cloud Test).
  3. Check logs:

    • New log output = Feishu is pushing messages.
    • No log output = No message push—recheck permissions, events, and version release.

Q4: Why does the bot work in private chats but not group chats?

90% of cases are caused by one of these issues:

  1. Missing or unpublished im:message.group_at_msg:readonly permission in the Feishu Open Platform.
  2. Mismatch between FEISHU_BOT_NAME and the bot name in the Feishu backend.
  3. FEISHU_GROUP_POLICY remains in whitelist mode (not set to open).

Q5: Why is the Feishu channel disconnected with correct App ID and Secret?

Common causes include:

  1. Unconfigured app availability scope: Set Available Scope to All Employees or test users in the Feishu Admin Console.
  2. Network issues: Test connectivity with ping open.feishu.cn to confirm the Linux server can access Feishu WebSocket services.
  3. Mismatched encryption parameters: Sync FEISHU_ENCRYPT_KEY/FEISHU_VERIFICATION_TOKEN with Feishu Open Platform settings if enabled.

8. Full Troubleshooting Checklist (Quick Self-Validation)

Use this checklist to cover 99% of issues with a quick review:

  • [ ] Hermes gateway shows ✓ Feishu channel connected
  • [ ] FEISHU_GROUP_POLICY is set to open
  • [ ] GATEWAY_ALLOW_ALL_USERS is set to true
  • [ ] im:message.group_at_msg:readonly and im:message.receive_v1 are enabled in Feishu
  • [ ] A new Feishu app version has been published
  • [ ] FEISHU_BOT_NAME exactly matches the Feishu bot name
  • [ ] The bot is added to the target Feishu group
  • [ ] Messages are sent by @mentioning the bot
  • [ ] Logs show message received or Mention detected

9. Conclusion

Troubleshooting unresponsive Hermes-Feishu group chats follows a three-layer localization framework:

  1. Basic Layer: Verify gateway status and local Hermes configurations (group policy, bot name, credentials).
  2. Platform Layer: Validate Feishu Open Platform permissions, event subscriptions, and version releases.
  3. Log Layer: Confirm message push and processing status via real-time logs.

In practice, unpublished Feishu versions, bot name mismatches, and missing group @mention permissions are the three most frequent issues—prioritizing these checks drastically reduces troubleshooting time. All commands and configurations in this guide are validated for Linux systems and can be copied directly. For Windows deployments, address special issues such as os.kill errors and encoding (e.g., export LANG=zh_CN.UTF-8).

By following this end-to-end troubleshooting and repair process, you can fully resolve unresponsive Hermes group chat issues and ensure stable bot responses to @mentions in Feishu group chats.