1
0

Hermes 角色创建

2026-06-27
服务器
Hermes
Hermes 角色创建

本篇博客记录配置一个新的 Hermes 角色 profile的完整过程。以下以 companion 为例，但所有名称、模型、bot token 都可替换为其他角色。

0. 占位符说明

后续命令中的占位符按实际情况替换：

<PROFILE_NAME>            角色 profile 名，例如 companion
<PROFILE_DESC>            角色简短描述
<TELEGRAM_BOT_TOKEN>      该角色专用 Telegram Bot token
<TELEGRAM_USER_ID>        允许访问该 bot 的 Telegram 数字用户 ID
<TELEGRAM_PROXY>          Telegram 代理，例如 http://127.0.0.1:7890
<PROVIDER_NAME>           Hermes 中显示的 provider 名，例如 openai-api
<MODEL_NAME>              该角色默认模型名
<WORKSPACE_DIR>           该角色默认工作目录

本文以：

<PROFILE_NAME>=companion

作为示例。

1. 前置条件

确认以下内容已经完成：

sudo -iu hermes
export PATH="$HOME/.local/bin:$PATH"
which hermes
hermes doctor

确认测试 bot 已经跑通过最小闭环：

Telegram -> Hermes gateway -> 模型 API -> Telegram

确认 Telegram 代理可用：

curl -x http://127.0.0.1:7890 -I https://api.telegram.org

2. 创建 Telegram Bot

在 Telegram 中打开 BotFather：

@BotFather

创建新 bot：

/newbot

按提示设置：

Display name: <BOT_DISPLAY_NAME>
Username: <BOT_USERNAME_ENDING_WITH_bot>

保存 BotFather 返回的 token：

<TELEGRAM_BOT_TOKEN>

不要把 token 贴到公开位置。

3. 获取 Telegram 用户 ID

任选一种方式。

方式一：使用 @userinfobot。

/start

记录返回的数字 ID：

<TELEGRAM_USER_ID>

方式二：给自己的新 bot 发送一条消息，然后用 Bot API 查看：

curl -x http://127.0.0.1:7890 "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getUpdates"

在返回 JSON 中查找：

"from":{"id":<TELEGRAM_USER_ID>}

4. 创建 Hermes Profile

推荐从当前已跑通的默认 profile 克隆配置，但不克隆记忆和会话：

hermes profile create companion --clone --description "<PROFILE_DESC>"

通用写法：

hermes profile create <PROFILE_NAME> --clone --description "<PROFILE_DESC>"

说明：

  • --clone 会复制当前 profile 的 config.yaml、.env、SOUL.md 和 skills。
  • 不会复制 sessions 和 memory。
  • 新 profile 会获得自己的命令别名，例如 companion。

检查 profile：

hermes profile list
companion doctor

通用写法：

<PROFILE_NAME> doctor

5. 编辑 Profile 的 .env

打开新 profile 的 .env：

vim ~/.hermes/profiles/companion/.env

至少确认或写入以下内容：

TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN>
TELEGRAM_ALLOWED_USERS=<TELEGRAM_USER_ID>
TELEGRAM_PROXY=<TELEGRAM_PROXY>

如果模型供应商使用 OpenAI-compatible 接口，通常还需要：

OPENAI_API_KEY=<MODEL_API_KEY>
OPENAI_BASE_URL=<MODEL_BASE_URL>

保存后设置权限：

chmod 600 ~/.hermes/profiles/companion/.env

6. 设置默认模型

如果当前 clone 过来的模型不是该角色目标模型，可以用两种方式设置。

方式 A：通过 Telegram /model 设置

先启动该 profile 的 gateway，稍后在 Telegram 中发送：

/model

按 Hermes 的菜单选择目标 provider 和模型。完成后 Hermes 会保存到该 profile 的 config.yaml。

方式 B：通过 CLI 设置

通用格式：

<PROFILE_NAME> config set model.default <PROVIDER_NAME>/<MODEL_NAME>

示例：

companion config set model.default <PROVIDER_NAME>/<MODEL_NAME>

设置后检查：

cat ~/.hermes/profiles/companion/config.yaml

通用路径：

cat ~/.hermes/profiles/<PROFILE_NAME>/config.yaml

7. 设置 SOUL.md

打开该角色的 persona 文件：

vim ~/.hermes/profiles/companion/SOUL.md

写入该角色的核心职责和边界即可。此阶段只写必要内容，不展开细节人格。

示例结构：

# Role

You are <PROFILE_NAME>.

# Responsibilities

- <ROLE_RESPONSIBILITY_1>
- <ROLE_RESPONSIBILITY_2>

# Boundaries

- <BOUNDARY_1>
- <BOUNDARY_2>

# Shared Rules

Follow the shared profile requirements when provided.

8. 准备 Workspace

为该 profile 建一个独立 workspace（可能会默认创建，如已有可忽略）：

mkdir -p ~/.hermes/profiles/companion/workspace

如果希望该角色的终端工具默认从此目录启动，可设置 terminal.cwd：

companion config set terminal.cwd /home/hermes/.hermes/profiles/companion/workspace

通用写法：

<PROFILE_NAME> config set terminal.cwd /home/hermes/.hermes/profiles/<PROFILE_NAME>/workspace

注意：profile 本身不是沙箱。terminal.cwd 只是默认工作目录，不限制文件访问。

9. 检查 Telegram Token

先确认该 bot token 有效：

curl -x http://127.0.0.1:7890 "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getMe"

预期返回：

{"ok":true}

如果不通，先处理 token 或代理，不要继续启动 gateway。

10. 前台启动该角色 Gateway 测试

先使用前台运行，方便看日志：

companion gateway run -v

通用写法：

<PROFILE_NAME> gateway run -v

打开 Telegram，给该角色 bot 发送：

你好，收到请回复一句测试成功

如果 bot 能回复，说明该角色链路已跑通。

11. 设置 Home Channel

在该 bot 的 Telegram 私聊中发送：

/sethome

这会把当前聊天设置为 home channel，用于 cron 结果和跨平台消息投递。

12. 常见问题检查

bot 没反应

检查 gateway 是否在运行：

<PROFILE_NAME> gateway run -v

检查 token：

curl -x http://127.0.0.1:7890 "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getMe"

Unauthorized user

检查 .env：

grep TELEGRAM_ALLOWED_USERS ~/.hermes/profiles/<PROFILE_NAME>/.env

确认填写的是 Telegram 数字 ID，不是 username。

Provider authentication failed

优先在 Telegram 中发送：

/model

重新选择 provider 和模型。

也可检查：

grep -E "OPENAI|MODEL|PROVIDER" ~/.hermes/profiles/<PROFILE_NAME>/.env
cat ~/.hermes/profiles/<PROFILE_NAME>/config.yaml

同一个 token 被多个 profile 使用

每个 profile 必须使用不同的 Telegram bot token。不要让测试 bot 和正式角色共用 token。

13. 通过后再安装 systemd 服务

手动前台测试通过后，再安装常驻服务：

companion gateway install
companion gateway start
companion gateway status

通用写法：

<PROFILE_NAME> gateway install
<PROFILE_NAME> gateway start
<PROFILE_NAME> gateway status

查看日志：

companion logs

或使用系统日志查看对应 gateway 服务。

14. 配置完成标准

一个角色配置完成，需要满足：

1. profile 已创建
2. 该 profile 有独立 .env
3. 该 profile 使用独立 Telegram bot token
4. TELEGRAM_ALLOWED_USERS 正确
5. TELEGRAM_PROXY 正确
6. 模型可正常回复
7. SOUL.md 已写入基础职责
8. workspace 已创建
9. 前台 gateway run 测试通过
10. /sethome 已设置
11. systemd 服务安装并可启动

15. companion 示例清单

实际配置 companion 时，按以下顺序执行：

sudo -iu hermes
export PATH="$HOME/.local/bin:$PATH"

hermes profile create companion --clone --description "Personal companion and roleplay assistant."

vim ~/.hermes/profiles/companion/.env
chmod 600 ~/.hermes/profiles/companion/.env

vim ~/.hermes/profiles/companion/SOUL.md
mkdir -p ~/.hermes/profiles/companion/workspace
companion config set terminal.cwd /home/hermes/.hermes/profiles/companion/workspace

companion doctor
companion gateway run -v

Telegram 测试通过后：

companion gateway install
companion gateway start
companion gateway status

评论