#hermes #agent #Configuration 

> 记录时间：2026-04-27  
> 场景：Vibe Coding 多角色 Agent 配置

---

## 一、给 Agent 设置预设角色和项目背景

### 问题

每次对话都要在提示词里重复角色定义和项目背景，效率低。

### 解决方案：两个配置文件分工

#### `SOUL.md` — 角色人设（全局生效，跟着 Agent 走）

**路径：** `~/.hermes/SOUL.md`（默认 profile）或 `~/.hermes/profiles/<名字>/SOUL.md`

适合放：

- 角色定位、身份定义
- 思维方式、技术偏好
- 沟通风格、语言习惯

```markdown
# 角色

你是一位资深软件架构师，有 10 年以上分布式系统设计经验。

## 核心职责
在任何 coding 任务开始前，先：
1. 分析需求，识别潜在的设计问题
2. 提出 2-3 种技术方案并给出 Trade-off 分析
3. 明确模块边界和接口设计

## 沟通风格
- 直接说结论，再给理由
- 用中文回复
```

#### `AGENTS.md` — 项目背景（项目级生效，放在项目根目录）

**路径：** `~/your-project/AGENTS.md`

适合放：

- 技术栈、架构说明
- 开发约定、命名规范
- 当前阶段、注意事项

```markdown
# 项目背景

## 技术架构
- Frontend: Next.js 14 (App Router) + Tailwind
- Backend: Python FastAPI，部署在 Docker
- 数据库: PostgreSQL，ORM 用 SQLAlchemy

## 开发约定
- API 统一返回 `{data, error, meta}` 结构
- 不直接修改 migration 文件，用 Alembic 命令
```

#### 优先级总结

|内容类型|放哪里|
|---|---|
|角色人格、沟通风格|`SOUL.md`|
|项目架构、技术栈、约定|`AGENTS.md`（项目根目录）|
|临时切换风格|`/personality teacher` （会话级）|

---

## 二、创建多个独立 Agent（Profiles）

### 问题

想用不同角色做 vibe coding，默认只有一个 Agent。

### 解决方案：使用 `hermes profile` 创建隔离实例

每个 Profile 拥有独立的：SOUL.md、配置、记忆、会话历史、技能。

#### 创建 Profile

```bash
# 克隆当前配置（推荐，省去重新配置模型和 API key）
hermes profile create nova --clone
hermes profile create werner --clone

# 给每个 profile 写专属的 SOUL.md
vim ~/.hermes/profiles/nova/SOUL.md
vim ~/.hermes/profiles/werner/SOUL.md
```

#### 启动方式

```bash
nova      # 直接用 alias 启动（Hermes 自动创建）
werner    # 同上

hermes -p nova chat     # 临时使用某个 profile，不切换默认
```

#### 常用管理命令

```bash
hermes profile list                    # 查看所有 profiles
hermes profile show nova               # 查看某个 profile 详情
hermes profile rename nova pm          # 重命名
hermes profile delete nova             # 删除（含所有记忆和会话，不可恢复）
hermes profile export nova             # 备份
hermes -p nova doctor                  # 诊断某个 profile
```

#### 角色命名参考

|角色|推荐名字|来源|
|---|---|---|
|产品经理|`marty`|Marty Cagan，《Inspired》作者|
|架构师|`werner`|Werner Vogels，Amazon CTO|
|产品经理（备选）|`nova`|前瞻、探索感|
|架构师（备选）|`atlas`|扛起系统架构|

---

## 三、Telegram Bot 配置后无响应

### 问题

给新 Profile 配了 Telegram bot token，在 Telegram 上发消息没有任何反应。

### 排查顺序

**1. Gateway 没有启动（最常见）**

配置 token ≠ gateway 在运行，新 profile 需要单独启动。

```bash
hermes -p nova gateway status   # 检查状态
hermes -p nova gateway start    # 启动
hermes -p nova gateway          # 前台运行，实时看日志
hermes -p nova gateway install  # gateway service 没有安装的前提下
```

**2. Token 没配在正确的 Profile 下**

每个 profile 有独立的 `.env`，默认 profile 的 token 不会共享。

```bash
cat ~/.hermes/profiles/nova/.env | grep TELEGRAM
# 应看到：TELEGRAM_BOT_TOKEN=xxx
```

**3. 用户 ID 不在白名单**

Hermes 默认拒绝所有未授权用户的消息（安全默认值）。

```bash
# 在 .env 里加上自己的 Telegram User ID
TELEGRAM_ALLOWED_USERS=你的TelegramUserID
```

> 不知道自己 ID？在 Telegram 搜索 `@userinfobot` 发消息获取。

**4. 同一个 token 被两个 gateway 同时使用**

会导致两个 gateway 互相冲突，都无法正常收消息。每个 Profile 必须使用独立的 Telegram Bot（在 BotFather 分别创建）。

---

## 四、Gateway 连接 Telegram 超时（国内网络）

### 问题

Gateway 服务正常运行，但日志反复出现：

```
WARNING: Primary api.telegram.org connection failed
WARNING: Fallback IP 149.154.167.220 failed
Connect attempt N/8 failed: Timed out
```

### 原因

Telegram 在国内被封，gateway 无法直连。

### 解决方案：配置代理

编辑对应 profile 的 `.env`：

```bash
vim ~/.hermes/profiles/nova/.env
```

添加代理配置（端口换成本地代理实际端口）：

```bash
# HTTP 代理（Clash 默认 7890）
HTTPS_PROXY=http://127.0.0.1:7890
HTTP_PROXY=http://127.0.0.1:7890

# SOCKS5 代理（v2rayN 默认 10809）
HTTPS_PROXY=socks5://127.0.0.1:7890
HTTP_PROXY=socks5://127.0.0.1:7890
```

重启 gateway：

```bash
hermes -p nova gateway stop
hermes -p nova gateway start
hermes -p nova logs --tail    # 观察是否连接成功
```

> **注意：** 每个 profile 的 `.env` 需要单独配置，互不共享。

---

## 快速参考：文件路径总览

```
~/.hermes/
├── SOUL.md                          # 默认 profile 的角色人设
├── profiles/
│   ├── nova/
│   │   ├── SOUL.md                  # nova 的角色人设（产品经理）
│   │   └── .env                     # nova 的 token、代理、白名单配置
│   └── werner/
│       ├── SOUL.md                  # werner 的角色人设（架构师）
│       └── .env                     # werner 的配置

~/your-project/
└── AGENTS.md                        # 项目背景（每个项目独立维护）
```