hermes教程-教程：团队 Telegram 助手

设置团队 Telegram 助手

本教程将引导你设置一个由 Hermes Agent 驱动的 Telegram 机器人，供团队成员共同使用。完成后，你的团队将拥有一个共享的 AI 助手，可以通过消息请求代码、研究、系统管理等方面的帮助——并通过按用户授权确保安全。

构建内容

一个 Telegram 机器人，具备以下功能：

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

前置条件

开始之前，请确保你已具备：

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

提示

一个 5 美元/月的 VPS 足以运行网关。Hermes 本身很轻量——LLM API 调用才是花钱的地方，而这些调用是远程进行的。

步骤 1：创建 Telegram 机器人

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

打开 Telegram 并搜索 @BotFather，或访问 t.me/BotFather
发送 /newbot——BotFather 会问你两件事：
- 显示名称——用户看到的名称（例如 Team Hermes Assistant）
- 用户名——必须以 bot 结尾（例如 myteam_hermes_bot）
复制机器人令牌——BotFather 会回复类似以下内容：
text
```
Use this token to access the HTTP API:
7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
```
保存此令牌——你将在下一步中用到。
设置描述（可选但推荐）：
/setdescription
选择你的机器人，然后输入类似：
Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.

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

/setcommands

选择你的机器人，然后粘贴：

text

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

警告

请保密你的机器人令牌。任何拥有该令牌的人都可以控制机器人。如果泄露，请在 BotFather 中使用 /revoke 生成新令牌。

步骤 2：配置网关

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

选项 A：交互式设置（推荐）

bash

hermes gateway setup

这将引导你完成所有步骤，使用方向键选择。选择 Telegram，粘贴你的机器人令牌，并在提示时输入你的用户 ID。

选项 B：手动配置

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

bash

## Telegram bot token from BotFather
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
## Your Telegram user ID (numeric)
TELEGRAM_ALLOWED_USERS=123456789

查找你的用户 ID

你的 Telegram 用户 ID 是一个数字值（不是你的用户名）。要找到它：

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

信息

Telegram 用户 ID 是永久的数字，例如 123456789。它们与你的 @username 不同，后者可以更改。始终使用数字 ID 进行允许列表。

步骤 3：启动网关

快速测试

首先在前台运行网关，确保一切正常：

bash

hermes gateway

你应该看到类似输出：

text

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

打开 Telegram，找到你的机器人，并发送一条消息。如果它回复，说明一切正常。按 Ctrl+C 停止。

生产环境：安装为服务

对于重启后仍能持久运行的部署：

bash

hermes gateway install
sudo hermes gateway install --system   # Linux only: boot-time system service

这将创建一个后台服务：在 Linux 上默认为用户级 systemd 服务，在 macOS 上为 launchd 服务，如果传递 --system 则为启动时 Linux 系统服务。

bash

## Linux — manage the default user service
hermes gateway start
hermes gateway stop
hermes gateway status
## View live logs
journalctl --user -u hermes-gateway -f
## Keep running after SSH logout
sudo loginctl enable-linger $USER
## Linux servers — explicit system-service commands
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

bash

## macOS — manage the service
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log

提示 — macOS PATH

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

验证运行状态

bash

hermes gateway status

然后在 Telegram 上向你的机器人发送一条测试消息。你应该在几秒内收到回复。

步骤 4：设置团队访问权限

现在让团队成员获得访问权限。有两种方法。

方法 A：静态允许列表

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

bash

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

更改后重启网关：

bash

hermes gateway stop && hermes gateway start

方法 B：私信配对（推荐用于团队）

私信配对更灵活——你无需预先收集用户 ID。工作原理如下：

团队成员给机器人发私信——由于他们不在允许列表中，机器人会回复一个一次性配对码：
text
```
🔐 Pairing code: XKGH5N7P
Send this code to the bot owner for approval.
```
团队成员将代码发送给你（通过任何渠道——Slack、电子邮件、当面）

你在服务器上批准它：

bash

hermes pairing approve telegram XKGH5N7P

他们获得访问权限——机器人立即开始回复他们的消息

管理已配对的用户：

bash

## See all pending and approved users
hermes pairing list
## Revoke someone's access
hermes pairing revoke telegram 987654321
## Clear expired pending codes
hermes pairing clear-pending

提示

私信配对非常适合团队，因为添加新用户时无需重启网关。批准立即生效。

安全考虑

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

步骤 5：配置机器人

设置主频道

主频道 是机器人发送定时任务结果和主动消息的地方。如果没有主频道，定时任务将无处发送输出。

选项 1： 在机器人所在的任何 Telegram 群组或聊天中使用 /sethome 命令。

选项 2： 在 ~/.hermes/.env 中手动设置：

bash

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

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

配置工具进度显示

控制机器人在使用工具时显示多少细节。在 ~/.hermes/config.yaml 中：

yaml

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

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

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

使用 SOUL.md 设置个性

通过编辑 ~/.hermes/SOUL.md 自定义机器人的沟通方式：

完整指南请参阅 Use SOUL.md with Hermes。

markdown

## 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.

添加项目上下文

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

markdown

<!-- ~/.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

信息

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

步骤 6：设置定时任务

网关运行后，你可以安排重复任务，将结果发送到团队频道。

每日站会摘要

在 Telegram 上给机器人发消息：

text

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.

代理会自动创建定时任务，并将结果发送到你提问的聊天（或主频道）。

服务器健康检查

text

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.

管理定时任务

bash

## From the CLI
hermes cron list          # View all scheduled jobs
hermes cron status        # Check if scheduler is running
## From Telegram chat
/cron list                # View jobs
/cron remove <job_id>     # Remove a job

警告

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

生产环境提示

使用 Docker 确保安全

在共享的团队机器人上，使用 Docker 作为终端后端，使代理命令在容器中运行，而不是在你的主机上：

bash

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

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

yaml

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

这样，即使有人要求机器人运行破坏性命令，你的主机系统也能得到保护。

监控网关

bash

## Check if the gateway is running
hermes gateway status
## Watch live logs (Linux)
journalctl --user -u hermes-gateway -f
## Watch live logs (macOS)
tail -f ~/.hermes/logs/gateway.log

保持 Hermes 更新

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

bash

hermes update
hermes gateway stop && hermes gateway start

日志位置

内容	位置
网关日志	`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 助手。以下是一些后续步骤：

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

有问题或遇到问题？在 GitHub 上提交 issue——欢迎贡献。

字节笔记本

hermes教程-教程：团队 Telegram 助手

设置团队 Telegram 助手

构建内容

前置条件

步骤 1：创建 Telegram 机器人

步骤 2：配置网关

选项 A：交互式设置（推荐）

选项 B：手动配置

查找你的用户 ID

步骤 3：启动网关

快速测试

生产环境：安装为服务

验证运行状态

步骤 4：设置团队访问权限

方法 A：静态允许列表

方法 B：私信配对（推荐用于团队）

安全考虑

步骤 5：配置机器人

设置主频道

配置工具进度显示

使用 SOUL.md 设置个性

添加项目上下文

步骤 6：设置定时任务

每日站会摘要

服务器健康检查

管理定时任务

生产环境提示

使用 Docker 确保安全

监控网关

保持 Hermes 更新

日志位置

进一步探索