Hermes Agent Feishu / Lark Integration: Team Chat Gateway Setup

This guide covers how to connect Hermes Agent to Feishu or Lark, turning the team chat platform into a gateway for sending prompts, receiving reports, and routing operational work through the same agent tools you use from the terminal. It is written for teams that already coordinate in Feishu or Lark and want Hermes available where work is discussed, without requiring every team member to open a terminal.

What You Need

Before starting the setup, ensure the following prerequisites are in place:

• A Feishu or Lark bot/app account: You must create or configure the bot or app account required by the platform. This is the identity that Hermes will use to send and receive messages in chat. The exact steps for creating this account depend on your Feishu or Lark admin settings; consult the platform's documentation for creating a custom bot or app.
• Hermes Agent installed and configured: You need a working Hermes Agent installation with an active profile. The gateway uses the same Hermes profile that you use from the CLI. If you have not set up Hermes yet, complete the base installation first.
• Credentials stored in the active Hermes profile: The token or credentials for the Feishu/Lark bot must be stored in the active Hermes profile environment, not in source control or a shared note. This keeps sensitive information secure and scoped to the correct profile.
• Gateway server running: The Hermes gateway must be running to accept and process messages from Feishu/Lark. The gateway is a separate process that listens for incoming chat messages and routes them to the Hermes agent.
• Allowlist configured before first test: You must restrict which users, rooms, groups, or contacts can interact with the bot before sending any test messages. This prevents accidental exposure of agent capabilities.

Understanding the Feishu / Lark Gateway

Feishu and Lark are team chat platforms (Feishu is the Chinese version, Lark is the international version). The Hermes gateway for Feishu/Lark acts as a bridge: a chat message sent to the bot is received by the gateway, processed by the Hermes agent using the same tools, skills, and MCP servers available from the CLI, and the response is posted back to the chat.

According to the official documentation, Feishu/Lark should be treated as a human-facing gateway, not the whole automation system. The chat message starts the request, but Hermes can still use files, terminal tools, MCP servers, web search, cron history, GitHub, Linear, Notion, and project-specific skills to do the real work. This means you can ask for a status summary without opening a terminal, send an incident or support request from the chat app your team already uses, receive cron reports or deployment notes in a familiar channel, and keep sensitive tools scoped to trusted chats and profiles instead of exposing every capability everywhere.

Best Use Cases

The official documentation identifies several scenarios where the Feishu/Lark gateway excels:

• Teams that already coordinate in this chat platform: If your team lives in Feishu or Lark, having Hermes there means you can ask questions, trigger workflows, and get updates without switching contexts.
• Operational alerts and status reports: Instead of requiring someone to check a terminal or dashboard, Hermes can push reports directly into chat channels.
• Approval workflows: Hermes can draft an action (like a deployment or a purchase) and ask for human confirmation in chat before executing it.
• Project-specific agents: You can scope a bot to a specific channel or group, giving it access only to the tools and skills relevant to that project, rather than having one global bot that knows everything.

Setup Path: Step by Step

The official documentation outlines a six-step setup path. Each step is explained below with practical context.

Step 1: Create or Configure the Feishu / Lark Bot

You need a bot or app account in Feishu or Lark that Hermes will use. The exact process depends on your platform:

• Feishu: Go to the Feishu Developer Console, create a custom bot, and obtain the necessary credentials (app ID, app secret, verification token, etc.).
• Lark: Similarly, use the Lark Developer Console to create a bot.

Make sure the bot has permissions to read and send messages in the chats you intend to use. You may need admin approval for certain permissions.

Step 2: Store Credentials in the Active Hermes Profile

Once you have the bot credentials, store them in the active Hermes profile environment. Do not put them in source control or a shared note. The exact environment variable names depend on the platform adapter; the official documentation does not specify the exact variable names, but typical patterns include FEISHU_APP_ID, FEISHU_APP_SECRET, LARK_APP_ID, LARK_APP_SECRET, or similar. Check the Hermes documentation for the Feishu/Lark adapter to confirm the required variables.

To store credentials in a Hermes profile, you typically edit the profile configuration file (e.g., ~/.hermes/profiles/default.yaml) and add the variables under an env section. For example:

profile:
  name: default
  env:
    FEISHU_APP_ID: "cli_xxxxxxxxxxxxxx"
    FEISHU_APP_SECRET: "your_app_secret_here"

Alternatively, you can set them as environment variables in your shell before starting the gateway. The official documentation emphasizes that credentials must not be in source control or shared notes.

Step 3: Run hermes gateway setup and Enable the Platform Adapter

With credentials in place, run the gateway setup command:

hermes gateway setup

This command walks you through configuring the gateway. When prompted, enable the Feishu or Lark platform adapter. If you are testing only one platform, enable only that one to avoid confusion. The official documentation recommends enabling only the platform you are testing during initial setup.

Step 4: Restrict Allowed Users, Rooms, Groups, or Contacts

Before sending any test messages, configure the allowlist. This is a critical safety step. The official documentation states: "Restrict allowed users, rooms, groups, or contacts before the first test." The allowlist defines who can interact with the bot. Start with one private user or test room. Do not add team-wide rooms yet.

The exact configuration depends on the Hermes gateway configuration file. Typically, you specify allowed chat IDs or user IDs in the gateway config. For example:

gateway:
  platforms:
    feishu:
      enabled: true
      allowed_users:
        - "user_id_1"
      allowed_rooms:
        - "chat_id_test_room"

Replace user_id_1 and chat_id_test_room with the actual IDs from your Feishu/Lark environment. You can find these IDs in the bot's message payload or by inspecting the platform's developer tools.

Step 5: Restart the Gateway and Send a Harmless Private Test Message

After configuring the allowlist, restart the gateway to apply the changes:

hermes gateway restart

Then send a harmless private test message to the bot. The official documentation suggests: "reply with the active profile and enabled platform name." For example, send:

What is my active profile and which platform is enabled?

The bot should respond with the profile name and the platform name (e.g., "Active profile: default, Enabled platform: feishu"). This confirms that the gateway is running, the platform adapter is enabled, and the bot can receive and respond to messages.

Step 6: After the Smoke Test, Connect Project Skills, Cron Reports, MCP Tools, or Team Rooms

Only after the smoke test succeeds should you expand the bot's capabilities. The official documentation advises: "Only after the smoke test, connect project skills, cron reports, MCP tools, or team rooms." This means:

• Add more users or rooms to the allowlist gradually.
• Enable tool access (file edits, deploys, purchases, external sends) only after verifying that the bot behaves correctly with harmless prompts.
• Connect cron reports to push scheduled updates into chat.
• Attach MCP servers to give the bot access to external data sources.