Hermes Feishu Guide

Hermes Agent 飞书 Bot 本地部署指南（WebSocket 模式）。包含 Kimi API 配置、WebSocket vs Webhook 对比、环境变量配置等完整步骤。适合本地机器部署，不需要公网域名。

Security Scan

The guide appears to be a plausible local-deploy guide for Hermes Feishu Bot, but the SKILL.md asks you to supply and store sensitive credentials and to run a remote install script while the skill metadata declares no required credentials — these mismatches and the curl|bash instruction are risky and warrant caution.

Purpose & Capability

The README content matches the stated purpose (local Hermes Feishu WebSocket deployment) and legitimately requires Feishu App ID/Secret and a Kimi/Moonshot API key. However, the registry metadata claims no required environment variables or credentials while the instructions explicitly require and show storing sensitive secrets (FEISHU_APP_SECRET, KIMI_CN_API_KEY). That metadata/instruction mismatch is unexpected and reduces transparency.

Instruction Scope

Runtime instructions tell the operator to run a one-line installer fetched from raw.githubusercontent.com (curl -fsSL ... | bash) and to create ~/.hermes/.env containing API keys/secrets. Aside from those, the steps are scoped to starting the gateway and checking local logs. The main concern is the broad discretion granted by piping a remote script to the shell and the requirement to place secrets in a local env file (which is normal for this product but should be clearly declared in the skill metadata).

Install Mechanism

There is no formal install spec in the skill metadata, but the SKILL.md explicitly instructs running a remote install script via curl | bash from raw.githubusercontent.com/NousResearch/hermes-agent. While GitHub raw is a common host, executing remote scripts without review is high-risk; the skill should declare the install or at least list the exact URL and recommend reviewing the script before executing.

Credentials

The instructions require multiple sensitive values (KIMI_CN_API_KEY, FEISHU_APP_ID, FEISHU_APP_SECRET) and recommend configuration options that affect bot behavior (FEISHU_GROUP_POLICY, GATEWAY_ALLOW_ALL_USERS). Those items are proportionate to deploying a chat bot, but they are not declared in the skill metadata. The missing declaration of required secrets reduces transparency and could cause accidental secret exposure if users follow the installer without review. Also the guide suggests making the group policy 'open' which increases exposure.

Persistence & Privilege

The skill does not request always: true and does not itself persist in the agent. The instructions show installing and running a local Hermes gateway service (hermes gateway start), which is appropriate for the stated purpose. This creates a persistent local process, but that behavior aligns with a deploy guide rather than requiring elevated platform privileges.

What to consider before installing

Key things to consider before proceeding: - The SKILL.md asks you to run a remote installer with `curl ... | bash`. Do NOT run that blindly — inspect the script at the GitHub URL first (or clone the repo and review code) before executing. - The guide requires sensitive credentials (FEISHU_APP_ID/FEISHU_APP_SECRET and KIMI_CN_API_KEY). Treat these as secrets: use least-privilege keys, rotate them if exposed, and avoid pasting them into shared terminals or logs. - The registry metadata does not declare those required env vars; this mismatch reduces transparency. Confirm you understand what credentials are needed and why before installing. - If you must install, prefer a manual install (download and inspect files, run in a restricted environment or container) rather than piping a remote script to the shell. - Consider keeping FEISHU_GROUP_POLICY on allowlist until you trust the deployment; setting it to open will let the bot respond to any group mention. - If you are not familiar with the NousResearch/hermes-agent repo, verify the publisher and repository integrity (stars, recent commits, official docs) before trusting the installer.

Hermes 飞书 Bot 本地部署指南

概述

Hermes Agent 从 v0.6.0 开始支持飞书（Feishu/Lark）平台。飞书国内版支持 WebSocket 模式，不需要公网域名，直接本地运行。

前置准备

1. 飞书开放平台创建应用

• 创建企业自建应用
• 获取 App ID 和 App Secret
• 启用 Bot 能力
• 开通权限：im:message、im:message:send_as_bot、im:message:group_at_msg（群聊@消息）

2. Kimi API Key

• 获取 Moonshot API Key
• 注意模型名称：kimi-k2.5（不是 moonshotai/Kimi-K2.5）

一键安装

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.zshrc

配置环境变量

编辑 ~/.hermes/.env：

KIMI_CN_API_KEY=sk-xxx
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_CONNECTION_MODE=websocket
FEISHU_GROUP_POLICY=open        # 群聊策略：open/allowlist/disabled
GATEWAY_ALLOW_ALL_USERS=true

群聊策略说明

值	说明
open	✅ 响应任何用户的 @提及
allowlist	⚠️ 只响应 FEISHU_ALLOWED_USERS 白名单用户
disabled	❌ 忽略所有群聊消息

⚠️ 重要：默认值是 allowlist，如果不在白名单，群聊 @机器人不会响应！单聊不受此限制。

启动网关

hermes gateway start
hermes gateway status

验证连接

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

看到 connected to wss://msg-frontier.feishu.cn/ws/v2... 表示成功。

WebSocket vs Webhook

对比项	WebSocket	Webhook
需要公网域名	❌	✅
需要 HTTPS 证书	❌	✅
飞书国内版	✅	✅
Lark 国际版	❌	✅

常见问题

Q: Kimi API 认证失败

检查模型名称，去掉 moonshotai/ 前缀，使用 kimi-k2.5。

Q: 群聊 @机器人没反应

检查 FEISHU_GROUP_POLICY 配置：

• 默认是 allowlist，需要改成 open
• 或添加用户到 FEISHU_ALLOWED_USERS

Q: 单聊可以，群聊不行

这是群聊策略限制，单聊绕过策略检查。添加 FEISHU_GROUP_POLICY=open 即可。

排障经验

Kimi API Key 认证失败

模型名称写错：moonshotai/Kimi-K2.5 → 正确是 kimi-k2.5

群聊 @机器人无响应

默认 FEISHU_GROUP_POLICY=allowlist，改成 open

参考

• Hermes 官方文档
• 飞书开放平台