知识引擎/Hermes 知识引擎/教程：团队 Telegram 助手

返回分馆所属主题：教程与指南更新于 2026年4月16日官方来源

本教程将引导你设置一个由 Hermes Agent 驱动的 Telegram Bot，供多个团队成员使用。完成后，你的团队将拥有一个共享的 AI 助手，他们可以通过消息请求帮助处理代码、研究、系统管理和任何事情——并通过用户级授权确保安全。一个 Telegram Bot，具备以下功能：

教程：团队 Telegram 助手

> 📖 本文档翻译自 Hermes Agent 官方文档 > 最后更新：2026-04-16

设置团队 Telegram 助手

本教程将引导你设置一个由 Hermes Agent 驱动的 Telegram Bot，供多个团队成员使用。完成后，你的团队将拥有一个共享的 AI 助手，他们可以通过消息请求帮助处理代码、研究、系统管理和任何事情——并通过用户级授权确保安全。

我们要构建什么

一个 Telegram Bot，具备以下功能：

任何已授权的团队成员都可以私信求助——代码审查、研究、Shell 命令、调试
运行在你的服务器上，拥有完整的工具访问权限——终端、文件编辑、网络搜索、代码执行
用户级会话——每个人都有独立的对话上下文
默认安全——只有经过批准的用户可以交互，提供两种授权方式
计划任务——每日站会、健康检查和提醒，投递到团队频道

前置条件

开始之前，请确保你具备以下条件：

在一台服务器或 VPS 上安装了 Hermes Agent（不是你的笔记本电脑——Bot 需要持续运行）。如果还没有安装，请按照安装指南操作。
一个 Telegram 账户（作为 Bot 所有者）
已配置 LLM 提供商——至少需要一个 OpenAI、Anthropic 或其他受支持提供商的 API 密钥，配置在 ~/.hermes/.env 中

提示

每月 5 美元的 VPS 就足够运行 Gateway。Hermes 本身非常轻量——LLM API 调用才是产生费用的部分，而这些都在远程执行。

第一步：创建 Telegram Bot

每个 Telegram Bot 都从 @BotFather 开始——Telegram 官方用于创建 Bot 的机器人。

打开 Telegram，搜索 @BotFather，或访问 t.me/BotFather
发送 /newbot — BotFather 会问你两个问题：
- 显示名称 — 用户看到的名称（例如 Team Hermes Assistant）
- 用户名 — 必须以 bot 结尾（例如 myteam_hermes_bot）
复制 Bot Token — BotFather 会回复类似以下内容：
```
Use this token to access the HTTP API:
7123456789:***...
```
保存好这个 token——下一步会用到。

设置描述（可选但推荐）：

/setdescription

选择你的 Bot，然后输入类似以下内容：

Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.

设置 Bot 命令（可选——为用户提供命令菜单）：

/setcommands

选择你的 Bot，然后粘贴：

new - Start a fresh conversation
model - Show or change the AI model
status - Show session info
help - Show available commands
stop - Stop the current task

警告

保管好你的 Bot Token。任何拥有 token 的人都可以控制 Bot。如果泄露，在 BotFather 中使用 /revoke 生成新的 token。

第二步：配置 Gateway

你有两个选项：交互式设置向导（推荐）或手动配置。

方式 A：交互式设置（推荐）

hermes gateway setup

它会通过方向键选择引导你完成所有配置。选择 Telegram，粘贴你的 Bot Token，在提示时输入你的用户 ID。

方式 B：手动配置

将以下行添加到 ~/.hermes/.env：

# Telegram bot token from BotFather
TELEGRAM_BOT_TOKEN=712345...p...

# Your Telegram user ID (numeric)
TELEGRAM_ALLOWED_USERS=123456789

查找你的用户 ID

你的 Telegram 用户 ID 是一个数字值（不是你的用户名）。查找方法：

在 Telegram 上给 @userinfobot 发消息
它会立即回复你的数字用户 ID
将该数字复制到 TELEGRAM_ALLOWED_USERS 中

信息

Telegram 用户 ID 是永久性的数字，如 123456789。它们与你的 @username 不同，后者可以更改。白名单中请始终使用数字 ID。

第三步：启动 Gateway

快速测试

先在前台运行 Gateway，确保一切正常：

hermes gateway

你应该看到类似以下输出：

[Gateway] Starting Hermes Gateway...
[Gateway] Telegram adapter connected
[Gateway] Cron scheduler started (tick every 60s)

打开 Telegram，找到你的 Bot，给它发一条消息。如果它回复了，说明一切正常。按 Ctrl+C 停止。

生产环境：安装为服务

要实现重启后仍然运行的持久部署：

hermes gateway install
sudo hermes gateway install --system   # 仅限 Linux：开机时启动的系统服务

这会创建一个后台服务：在 Linux 上默认为用户级 systemd 服务，在 macOS 上为 launchd 服务，如果使用 --system 参数则为开机启动的 Linux 系统服务。

# Linux — 管理默认用户服务
hermes gateway start
hermes gateway stop
hermes gateway status

# 查看实时日志
journalctl --user -u hermes-gateway -f

# SSH 登出后保持运行
sudo loginctl enable-linger $USER

# Linux 服务器 — 显式系统服务命令
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

# macOS — 管理服务
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log

macOS PATH 注意事项

launchd plist 在安装时捕获你的 shell PATH，以便 Gateway 子进程能找到 Node.js 和 ffmpeg 等工具。如果你之后安装了新工具，需要重新运行 hermes gateway install 来更新 plist。

验证运行状态

hermes gateway status

然后在 Telegram 上给你的 Bot 发一条测试消息。你应该在几秒内收到回复。

第四步：设置团队访问

现在让你的团队成员也能使用。有两种方式。

方式 A：静态白名单

收集每个团队成员的 Telegram 用户 ID（让他们给 @userinfobot 发消息），然后以逗号分隔的列表添加：

# 在 ~/.hermes/.env 中
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555

修改后重启 Gateway：

hermes gateway stop && hermes gateway start

方式 B：DM 配对（推荐用于团队）

DM 配对更灵活——你不需要预先收集用户 ID。工作原理如下：

团队成员私信 Bot — 由于他们不在白名单中，Bot 会回复一个一次性配对码：
```
🔐 Pairing code: XKGH5N7P
Send this code to the bot owner for approval.
```
团队成员将配对码发给你（通过任何渠道——Slack、邮件、当面）

你在服务器上批准：

hermes pairing approve telegram XKGH5N7P

完成 — Bot 立即开始响应他们的消息

管理已配对用户：

# 查看所有待审批和已批准的用户
hermes pairing list

# 撤销某人的访问权限
hermes pairing revoke telegram 987654321

# 清除过期的待审批配对码
hermes pairing clear-pending

提示

DM 配对非常适合团队使用，因为添加新用户时不需要重启 Gateway。批准操作立即生效。

安全注意事项

绝对不要在拥有终端访问权限的 Bot 上设置 GATEWAY_ALLOW_ALL_USERS=true — 任何找到你 Bot 的人都可能在你服务器上执行命令
配对码在 1 小时后过期，并使用加密随机性生成
速率限制防止暴力攻击：每用户每 10 分钟 1 次请求，每个平台最多 3 个待审批配对码
5 次失败的批准尝试后，平台进入 1 小时锁定状态
所有配对数据使用 chmod 0600 权限存储

第五步：配置 Bot

设置主频道

主频道是 Bot 投递计划任务结果和主动消息的地方。没有主频道，计划任务无处发送输出。

方式 1： 在 Bot 所在的任何 Telegram 群组或聊天中使用 /sethome 命令。

方式 2： 在 ~/.hermes/.env 中手动设置：

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

要查找频道 ID，将 @userinfobot 添加到群组中——它会报告群组的聊天 ID。

配置工具进度显示

控制 Bot 使用工具时显示的详细程度。在 ~/.hermes/config.yaml 中：

display:
  tool_progress: new    # off | new | all | verbose

模式	显示内容
`off`	仅显示干净的回复——无工具活动
`new`	每个新工具调用的简要状态（消息平台推荐）
`all`	每个工具调用及详细信息
`verbose`	完整的工具输出，包括命令结果

用户也可以在聊天中使用 /verbose 命令按会话更改此设置。

使用 SOUL.md 设置个性

通过编辑 ~/.hermes/SOUL.md 来自定义 Bot 的沟通风格：

完整指南请参阅使用 SOUL.md 自定义 Hermes。

# Soul
You are a helpful team assistant. Be concise and technical.
Use code blocks for any code. Skip pleasantries — the team
values directness. When debugging, always ask for error logs
before guessing at solutions.

添加项目上下文

如果你的团队在特定项目上工作，创建上下文文件让 Bot 了解你的技术栈：

<!-- ~/.hermes/AGENTS.md -->
# Team Context
- We use Python 3.12 with FastAPI and SQLAlchemy
- Frontend is React with TypeScript
- CI/CD runs on GitHub Actions
- Production deploys to AWS ECS
- Always suggest writing tests for new code

信息

上下文文件会注入到每个会话的系统提示中。保持简洁——每个字符都计入你的 token 预算。

第六步：设置计划任务

Gateway 运行后，你可以设置定期任务，将结果投递到团队频道。

每日站会摘要

在 Telegram 上给 Bot 发消息：

Every weekday at 9am, check the GitHub repository at
github.com/myorg/myproject for:
1. Pull requests opened/merged in the last 24 hours
2. Issues created or closed
3. Any CI/CD failures on the main branch
Format as a brief standup-style summary.

Agent 会自动创建计划任务，并将结果投递到你提问的聊天（或主频道）。

服务器健康检查

Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
and Docker container status with 'docker ps'. Report anything unusual —
partitions above 80%, containers that have restarted, or high memory usage.

管理计划任务

# 从 CLI
hermes cron list          # 查看所有计划任务
hermes cron status        # 检查调度器是否在运行

# 从 Telegram 聊天
/cron list                # 查看任务
/cron remove <job_id>     # 删除任务

警告

计划任务提示在完全全新的会话中运行，没有之前对话的记忆。确保每个提示包含 Agent 所需的全部上下文——文件路径、URL、服务器地址和清晰的指令。

生产环境建议

使用 Docker 确保安全

在共享团队 Bot 上，使用 Docker 作为终端后端，让 Agent 命令在容器中运行而非直接在主机上：

# 在 ~/.hermes/.env 中
TERMINAL_BACKEND=docker
TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20

或在 ~/.hermes/config.yaml 中：

terminal:
  backend: docker
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

这样，即使有人让 Bot 运行破坏性操作，你的主机系统也会受到保护。

监控 Gateway

# 检查 Gateway 是否在运行
hermes gateway status

# 查看实时日志（Linux）
journalctl --user -u hermes-gateway -f

# 查看实时日志（macOS）
tail -f ~/.hermes/logs/gateway.log

保持 Hermes 更新

在 Telegram 上给 Bot 发送 /update——它会拉取最新版本并重启。或在服务器上：

hermes update
hermes gateway stop && hermes gateway start

日志位置

内容	位置
Gateway 日志	`journalctl --user -u hermes-gateway`（Linux）或 `~/.hermes/logs/gateway.log`（macOS）
计划任务输出	`~/.hermes/cron/output/{job_id}/{timestamp}.md`
计划任务定义	`~/.hermes/cron/jobs.json`
配对数据	`~/.hermes/pairing/`
会话历史	`~/.hermes/sessions/`

进阶探索

你已经拥有一个可用的团队 Telegram 助手。以下是一些下一步可以探索的方向：

安全指南 — 深入了解授权、容器隔离和命令审批
消息网关 — Gateway 架构、会话管理和聊天命令的完整参考
Telegram 设置 — 平台特定详情，包括语音消息和 TTS
计划任务 — 进阶计划任务调度，包括投递选项和 Cron 表达式
上下文文件 — AGENTS.md、SOUL.md 和 .cursorrules 用于项目知识
个性 — 内置个性预设和自定义角色定义
添加更多平台 — 同一个 Gateway 可以同时运行 Discord、Slack 和 WhatsApp

有问题或建议？在 GitHub 上提交 Issue——欢迎社区贡献。

Continue Exploring

继续探索

这不是课程式的上一篇下一篇，而是从当前节点向外继续漫游。

教程与指南

使用 SOUL

SOUL.md 是你的 Hermes 实例的主要身份文件。它是系统提示中的第一个内容——定义了 agent 是谁、如何说话以及避免什么。如果你希望 Hermes 每次对话都像同一个助手——或者你想用自己的设定完全替换 Hermes 的人设——这就是要使用的文件。使用 SOUL.md 来定义：

使用指南

安全 (Security)

Hermes Agent is designed with a defense-in-depth security model. This page covers every security boundary — from command approval to container isolation to user

消息平台

Hermes Agent integrates with Telegram as a full-featured conversational bot. Once connected, you can chat with your agent from any device, send voice memos that

核心功能

定时任务 (Cron Scheduler)

通过自然语言或 cron 表达式自动调度任务。Hermes 通过单个 cronjob 工具暴露 cron 管理，使用动作风格的命令操作，而不是独立的 schedule/list/remove 工具。 Cron 任务可以： - 调度一次性或重复性任务 - 暂停、恢复、编辑、触发和删除任务

核心功能

上下文文件 (Context Files)

Hermes Agent automatically discovers and loads context files that shape how it behaves. Some are project-local and discovered from your working directory. SOUL.

核心功能

个性与 SOUL (Personality & SOUL)

Hermes Agent 的个性是完全可定制的。SOUL.md 是主要身份 ——它是系统提示中的第一项内容，定义了 Agent 是谁。 - SOUL.md — 一个持久的人格文件，位于 HERMES HOME 中，作为 Agent 的身份（系统提示中的槽位 1） - 内置或自定义的 /personality 预设 —

Guides

教程与指南

从实践用法、最佳实践到真实工作流模板，适合直接照着走一遍。

16 篇文档16 个节点

当前节点

教程：团队 Telegram 助手

返回分馆回到知识引擎

同主题继续探索

技巧与最佳实践

一份实用技巧速查集合，让你立刻更高效地使用 Hermes Agent。每个部分针对不同的方面——浏览标题，跳转到你需要的内容。模糊的提示产生模糊的结果。不要说"修复代码"，而要说"修复 api/handlers.py 第 47 行的 TypeError — process request() 函数从 parse bo

在 Mac 上运行本地 LLM

本指南带你了解如何在 macOS 上运行本地 LLM 服务器（提供 OpenAI 兼容 API）。你将获得完全的隐私、零 API 费用，以及在 Apple Silicon 上出人意料的好性能。我们介绍两种后端：两者都提供 OpenAI 兼容的 /v1/chat/completions 端点。Hermes 可以配合其

教程：每日简报机器人

在本教程中，你将构建一个个人简报机器人——它每天早上自动启动，研究你关心的话题，总结发现的内容，并将简洁的简报直接发送到你的 Telegram 或 Discord。完成后，你将拥有一个完全自动化的工作流，结合了网络搜索、计划任务（Cron）、任务委派和消息投递 ——无需编写任何代码。

作为 Python 库使用

Hermes 不仅仅是一个 CLI 工具。你可以直接导入 AIAgent，在自己的 Python 脚本、Web 应用或自动化流水线中以编程方式使用它。本指南将向你展示如何操作。直接从仓库安装 Hermes：或者使用 uv：你也可以将其固定在 requirements.txt 中：

使用 MCP

本指南展示如何在实际日常工作流中使用 MCP 与 Hermes Agent。如果说功能页面解释了 MCP 是什么，那么本指南则是关于如何快速、安全地从中获取价值。在以下情况使用 MCP：已有 MCP 形式的工具，且你不想自己构建 Hermes 原生工具你想让 Hermes 通过干净的 RPC 层操作本地或远程系

使用 SOUL

教程：团队 Telegram 助手

设置团队 Telegram 助手

我们要构建什么

前置条件

第一步：创建 Telegram Bot

第二步：配置 Gateway

方式 A：交互式设置（推荐）

方式 B：手动配置

查找你的用户 ID

第三步：启动 Gateway

快速测试

生产环境：安装为服务

验证运行状态

第四步：设置团队访问

方式 A：静态白名单

方式 B：DM 配对（推荐用于团队）

安全注意事项

第五步：配置 Bot

设置主频道

配置工具进度显示

使用 SOUL.md 设置个性

添加项目上下文

第六步：设置计划任务

每日站会摘要

服务器健康检查

管理计划任务

生产环境建议

使用 Docker 确保安全

监控 Gateway

保持 Hermes 更新

日志位置

进阶探索

继续探索

使用 SOUL

安全 (Security)

Telegram

定时任务 (Cron Scheduler)

上下文文件 (Context Files)

个性与 SOUL (Personality & SOUL)

教程与指南

知识引擎 AI 问答