Hermes Agent + WeCom: Enterprise WeChat Agent Gateway Setup Guide

This guide explains how to connect Hermes Agent to WeCom (Enterprise WeChat) so your team can interact with Hermes directly from company chat. It covers the full setup path, safe rollout patterns, common workflows, and troubleshooting for the WeCom gateway adapter. This is for teams that already coordinate in WeCom and want to turn chat requests into tool-backed actions without leaving the app.

What You Need

Before you begin, make sure you have the following:

• A Hermes Agent installation (CLI) with the gateway feature available. The gateway is a component of Hermes that listens for incoming messages from chat platforms.
• A WeCom (Enterprise WeChat) bot, app, or account that can send and receive messages. You will need the credentials (token, secret, or similar) for this account.
• The credentials must be stored in the active Hermes profile environment, not in source control or a shared note. This is a security requirement from the official documentation.
• A test user or test room in WeCom that you control. This is used for the private smoke test before rolling out to production channels.
• Basic familiarity with the Hermes CLI commands, especially hermes gateway setup.

Concepts: How the WeCom Gateway Works

The Hermes WeCom gateway is a platform adapter that lets WeCom act as a messaging frontend for Hermes. When a user sends a message to the WeCom bot, the gateway receives it, processes it through the active Hermes profile (including its tools, skills, and MCP servers), and returns a response back to the chat. The official documentation emphasizes that WeCom 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.

Best Use Cases

The documentation identifies several scenarios where the WeCom gateway excels:

• Operational alerts and status reports: Deliver cron reports, deployment notes, incident summaries, or approval prompts directly to a WeCom channel so team members see them without opening a terminal.
• Approval workflows: Let Hermes draft an action (e.g., a deployment or a configuration change) and then ask for human confirmation in chat before executing.
• Project-specific agents: Scope a bot to a narrow channel boundary (e.g., one project room) rather than having one global bot everywhere. This keeps sensitive tools and data restricted to the right trust level.
• Knowledge capture: Turn a chat thread into a task, document, issue, or reusable skill by asking Hermes to process the conversation.

What the Gateway Can Use

When a request comes through WeCom, the gateway can access the same Hermes skills and MCP servers that are available from the CLI, but only those enabled in the active profile. The official documentation warns that tool access must be scoped carefully because chat channels often have different trust levels than your terminal. For example, you might allow file reading but not file editing in a group chat.

Setup: Step-by-Step

The official documentation provides a clear setup path. Follow these steps in order to avoid exposing unverified behavior to a wide audience.

Step 1: Create or Configure the WeCom Bot/App

First, create or configure the WeCom bot, app, or account that Hermes will use to send and receive messages. This is done entirely within the WeCom administrative interface. The exact steps depend on your WeCom setup, but you will need to obtain credentials (such as a token or secret) that Hermes will use to authenticate. The official documentation does not specify the exact credential type, so consult WeCom's own documentation for creating a bot or custom app.

Step 2: Store Credentials in the Active Hermes Profile

Once you have the credentials, store them in the active Hermes profile environment. The official documentation is explicit: do not store credentials in source control or a shared note. The recommended approach is to use environment variables or a secrets manager that Hermes can read. The exact variable names are not specified in the source, but you would typically set them in your shell profile or in a .env file that Hermes loads. For example:

export WECOM_TOKEN="your_wecom_bot_token"
export WECOM_SECRET="your_wecom_app_secret"

Make sure these are set before running the gateway.

Step 3: Run hermes gateway setup

With the credentials in place, run the Hermes gateway setup command:

hermes gateway setup

This command will present you with a list of available platform adapters. Enable only the WeCom platform for now. The official documentation recommends enabling only the platform you are testing during initial setup. This avoids confusion if multiple adapters are active.

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

Before sending any test messages, configure the allowlist. The official documentation lists four types of restrictions: users, rooms, groups, or contacts. You must specify at least one allowed entity before the gateway will respond. This is a safety measure to prevent unauthorized access. For the initial test, allowlist only one private user (yourself) or one test room that you control.

How you configure this depends on the Hermes profile. The documentation does not provide the exact configuration syntax, but it is likely a setting in the profile's YAML or JSON configuration file. For example:

gateway:
  wecom:
    allowed_users:
      - "user_id_1"
    allowed_rooms:
      - "test_room_id"

Check the Hermes Agent documentation for the exact format.

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

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

hermes gateway restart

Then, send one harmless private test message to the WeCom bot. The official documentation recommends a prompt such as:

reply with the active profile and enabled platform name

This verifies that the gateway is running, the platform is enabled, and the allowlist is working. If the bot responds with the correct information, the smoke test passes.

Step 6: Connect Project Skills, Cron Reports, MCP Tools, or Team Rooms

Only after the smoke test succeeds should you connect project-specific skills, cron reports, MCP tools, or team rooms. The official documentation emphasizes that the safest rollout is always private first, group later. Add production channels or free-response behavior only when permissions and response rules are clear.