BeeponyBeepony
Back

The Complete Guide to Connecting Hermes Agent to Feishu

Edit post

This is a practical guide for first-time Hermes Agent users who want to chat with Hermes through Feishu.

Goals of this guide:

This guide is based on a real setup and has been verified to work.

1. The End Result

After setup, you can:

2. Understanding the Architecture

It is easiest to understand this setup in the following order:

  1. Configure Hermes' model correctly first
  2. Then connect Feishu as a messaging channel
  3. Finally, add security and usability settings

Connecting Hermes Agent to Feishu essentially works like this:

  1. Hermes Gateway runs as a background messaging gateway process
  2. A Feishu Open Platform app is the message entry point
  3. The Feishu bot sends messages to Hermes Gateway
  4. Hermes calls the model you configured
  5. Hermes sends the result back to the Feishu conversation

For Feishu, use:

This is the officially recommended mode because it:

3. Prerequisites

Prepare the following before you begin.

1. Hermes Agent Is Installed

Confirm that the command is available:

hermes version

2. A Working Model Is Configured

For example:

If the model itself does not work, the bot still cannot reply after Feishu is connected.

3. You Have a Feishu Open Platform App

Create an app on the Feishu Open Platform in advance and obtain:

Feishu Open Platform:

4. Bot Capability Is Enabled in the Feishu App

Enable Bot in the app. Otherwise, even if Hermes connects successfully, it cannot work as a messaging bot.

4. Configure the MiniMax China Model First

If you use Hermes in mainland China, one of the best ways to start is by configuring the MiniMax China model first.

This is because:

1. The Correct Hermes Configuration

In ~/.hermes/config.yaml:

model:
  default: MiniMax-M2.7
  provider: minimax-cn

In ~/.hermes/.env:

MINIMAX_CN_API_KEY=your_MiniMax_China_key API Key

This is the recommended minimal configuration.

2. The Configuration We Actually Verified

These are the key settings that worked in practice.

~/.hermes/config.yaml

model:
  default: MiniMax-M2.7
  provider: minimax-cn

~/.hermes/.env

MINIMAX_CN_API_KEY=your_MiniMax_China_key API Key

3. Incorrect Configurations to Avoid

The first core problem we hit during setup was not Feishu at all; it was an incorrect model configuration.

Incorrect example:

model:
  default: minimax 2.7
  provider: custom
  base_url: https://api.minimaxi.com/anthropic

This setup can easily cause:

Why:

4. The MiniMax Error We Ran Into

We ran into two typical errors:

First:

404 Not Found

This usually means:

Second:

Error code: 400 - {'error': {'message': 'minimax 2.7 is not a valid model ID', 'code': 400}}

This means:

5. The Correct Fix

Change the configuration to use the built-in provider:

model:
  default: MiniMax-M2.7
  provider: minimax-cn

Then fill in .env:

MINIMAX_CN_API_KEY=your_MiniMax_China_key API Key

Do not keep old settings like these:

6. How to Verify the MiniMax China Model Works

Run:

hermes chat -Q -q "Reply with exactly: ok" --provider minimax-cn -m MiniMax-M2.7

If it returns:

ok

then at least this chain is working:

Make sure this step works before configuring Feishu.

Hermes supports Feishu natively, so you do not need to write your own middleware.

The key official settings are:

FEISHU_APP_ID=your_Feishu_AppID
FEISHU_APP_SECRET=your_Feishu_AppSecret
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_GROUP_POLICY=allowlist
FEISHU_ALLOWED_USERS=
FEISHU_HOME_CHANNEL=

Notes:

For a first setup, follow this flow instead of trying to configure every parameter immediately.

Step 1: Get the MiniMax China Model Working

Make sure Hermes can call the model normally before configuring Feishu.

For example, test:

hermes chat -Q -q "Reply with exactly: ok" --provider minimax-cn -m MiniMax-M2.7

If this does not return a response, do not continue with Feishu yet.

Step 2: Add Feishu Settings to ~/.hermes/.env

Edit:

~/.hermes/.env

Add:

FEISHU_APP_ID=YOUR_FEISHU_APP_ID
FEISHU_APP_SECRET=YOUR_FEISHU_APP_SECRET
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_GROUP_POLICY=allowlist
FEISHU_ALLOWED_USERS=
FEISHU_HOME_CHANNEL=

For your first setup, FEISHU_ALLOWED_USERS and FEISHU_HOME_CHANNEL can be left empty.

Step 3: Confirm Hermes Has the Dependencies Feishu Needs

Feishu WebSocket mode needs at least these Python dependencies:

Check:

/Users/your_username/.hermes/hermes-agent/venv/bin/python3 - <<'PY'
import importlib
for m in ["lark_oapi", "websockets"]:
    try:
        importlib.import_module(m)
        print(m, "ok")
    except Exception as e:
        print(m, "missing", e)
PY

If Hermes' own venv is missing dependencies, install them into that venv:

/Users/your_username/.hermes/hermes-agent/venv/bin/python3 -m ensurepip --upgrade
/Users/your_username/.hermes/hermes-agent/venv/bin/python3 -m pip install lark-oapi websockets

Note:

Step 4: Start or Restart Hermes Gateway

hermes gateway start

If it is already running:

hermes gateway restart

Step 5: Check the Gateway Logs

Look for:

If the connection succeeds, the logs usually include something like:

Connecting to feishu...
Connected in websocket mode (feishu)
Gateway running with 2 platform(s)

If you see this, the Feishu channel is connected.

Step 6: Send the Bot a Direct Message in Feishu

Start with a direct message first instead of testing in a group.

Send a simple direct message, for example:

hello

7. The Pairing Flow You'll See on First Use

Many people think Hermes' first Feishu reply is an error. It is not.

The first time you send a direct message, Hermes will probably reply with something like:

Hi~ I don't recognize you yet!
Here's your pairing code: XXXXXXXX
Ask the bot owner to run:
hermes pairing approve feishu XXXXXXXX

This means:

How to Handle It

On the machine running Hermes, run:

hermes pairing approve feishu your_pairing_code

After approval succeeds, Hermes indicates that the user will be recognized automatically next time.

If the Command Reports a Permission Error

Sometimes Hermes cannot write to ~/.hermes/pairing/.

This is usually not a Hermes configuration problem; the current environment lacks permission.

Solutions:

8. Security Settings to Add Right Away

Once chat works for the first time, do not stop there. Do at least two more things.

1. Add Your Feishu Account to the Allowlist

After pairing, add your open_id to:

FEISHU_ALLOWED_USERS=your_open_id

After that:

You can usually find your user ID in the Hermes logs, for example:

user=ou_xxx

2. Set FEISHU_HOME_CHANNEL

This tells Hermes:

You can set it manually:

FEISHU_HOME_CHANNEL=oc_xxx

Or send this to the bot in a Feishu conversation:

/sethome

9. Behavior Rules in Group Chats

Feishu group chats behave differently from direct messages.

Direct Messages

Group Chats

So the most common reason a bot "does not respond" in a group is not that it is broken, but that:

10. Real Problems We Hit and How We Solved Them

All of these problems happened during a real setup, and first-time users are likely to hit them.

Problem 1: Thinking Hermes Didn't Support Feishu

Symptoms:

Actual cause:

Fix:

Problem 2: MiniMax Was Misconfigured as a Custom Provider

Symptoms:

Actual cause:

Fix:

model:
  default: MiniMax-M2.7
  provider: minimax-cn
MINIMAX_CN_API_KEY=your_MiniMax_China_key API Key

Problem 3: The Model Name Was Written as minimax 2.7

Symptoms:

minimax 2.7 is not a valid model ID

Actual cause:

Fix:

default: MiniMax-M2.7

Problem 4: Feishu Dependencies Were Missing

Symptoms:

Actual cause:

Fix:

/Users/your_username/.hermes/hermes-agent/venv/bin/python3 -m ensurepip --upgrade
/Users/your_username/.hermes/hermes-agent/venv/bin/python3 -m pip install lark-oapi websockets

Problem 5: Hermes' venv Didn't Even Have pip

Symptoms:

No module named pip

Fix:

Run this first:

/Users/your_username/.hermes/hermes-agent/venv/bin/python3 -m ensurepip --upgrade

Then install the dependencies.

Problem 6: Gateway Status Looked Inconsistent

Symptoms:

Actual cause:

Fix:

If the logs show:

Connected in websocket mode (feishu)

Feishu is actually connected.

Problem 7: The First Message Returned a Pairing Code

Symptoms:

Actual cause:

Fix:

hermes pairing approve feishu your_pairing_code

Problem 8: Marked as an Unauthorized User Right After Connecting

Symptoms:

Unauthorized user

Actual cause:

Fix:

  1. Complete pairing first
  2. Then add your open_id to the allowlist

Problem 9: The Bot Replies in DMs but Not in Groups

The cause is usually:

Fix:

This configuration is a good starting point for personal use with Feishu in mainland China.

~/.hermes/config.yaml

model:
  default: MiniMax-M2.7
  provider: minimax-cn

~/.hermes/.env

MINIMAX_CN_API_KEY=your_MiniMax_China_key API Key
FEISHU_APP_ID=your_AppID
FEISHU_APP_SECRET=your_AppSecret
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_GROUP_POLICY=allowlist
FEISHU_ALLOWED_USERS=your_open_id
FEISHU_HOME_CHANNEL=your_chat_id

Its advantages:

If the setup fails, always troubleshoot in this order.

Step 1: Confirm the Model Works

Do not suspect Feishu first.

First confirm that Hermes itself can call the model.

Step 2: Confirm the .env Variables Are Correct

Check especially:

Step 3: Confirm the Dependencies Are in the Hermes venv

Check especially:

Step 4: Restart Gateway

hermes gateway restart

Step 5: Check Logs, Not Just Command Output

Look for:

Step 6: Test with a Direct Message to the Bot

Do not test in a group first.

Step 7: Handle Pairing

If you get a pairing code, approve it; do not mistake it for a failure.

13. Advice for First-Time Users

If this is your first time using Hermes Agent, I recommend this order:

  1. Get the MiniMax China model working
  2. Connect Feishu
  3. Verify with direct messages first
  4. Complete pairing
  5. Add your open_id to the allowlist
  6. Set the home channel
  7. Only then consider group chats, cron, and more channels

This is the least confusing path.

14. Quick Command Reference

Check the Hermes Version

hermes version

View the Configuration Summary

hermes dump

Test the MiniMax China Model

hermes chat -Q -q "Reply with exactly: ok" --provider minimax-cn -m MiniMax-M2.7

Check the Environment

hermes doctor

Start Gateway

hermes gateway start

Restart Gateway

hermes gateway restart

Check Gateway Status

hermes gateway status

Approve a Feishu Pairing Code

hermes pairing approve feishu pairing_code

List Approved Users

hermes pairing list

15. Conclusion

Connecting Hermes Agent to Feishu is not complicated, but first-time setups most often get stuck on these points:

If you follow the steps in this guide, especially:

the connection usually works smoothly.

If you share this guide with your team, remind them:

Edit post
Share this post:
Share on XShare on TelegramShare via email
Previous post
A Practical Cortisol Management Plan for Midlife
Next post
Kindle Paperwhite 1 Jailbreak, Repair, and KOReader Recovery Handbook