hermes教程-配置文件：运行多个代理

什么是配置文件？

配置文件是一个独立的 Hermes 主目录。每个配置文件拥有自己的目录，其中包含自己的 config.yaml、.env、SOUL.md、记忆、会话、技能、定时任务和状态数据库。配置文件允许你为不同目的运行独立的代理——例如编码助手、个人机器人、研究代理——而不会混淆 Hermes 状态。

当你创建一个配置文件时，它会自动成为自己的命令。创建一个名为 coder 的配置文件，你立即拥有 coder chat、coder setup、coder gateway start 等命令。

快速开始

hermes profile create coder       # 创建配置文件 + "coder" 命令别名
coder setup                       # 配置 API 密钥和模型
coder chat                        # 开始聊天

就是这样。coder 现在是一个独立的 Hermes 配置文件，拥有自己的配置、记忆和状态。

创建配置文件

提示

最快设置：在新配置文件中运行 hermes setup --portal 以一次性配置模型和工具。参见 Nous Portal。

空白配置文件

hermes profile create mybot

创建一个包含内置技能的新配置文件。运行 mybot setup 来配置 API 密钥、模型和网关令牌。

如果你计划将此配置文件用作看板工作节点（或希望看板编排器将工作路由到它），请在创建时传递 --description "<角色>"，以便编排器知道它擅长什么：

hermes profile create researcher --description "读取源代码和外部文档，撰写发现。"

你也可以稍后使用 hermes profile describe 设置或自动生成描述——参见 看板指南 了解完整的路由模型。

仅克隆配置（--clone）

hermes profile create work --clone

将当前配置文件的 config.yaml、.env、SOUL.md 和技能复制到新配置文件中。相同的 API 密钥、模型和能力，但全新的会话和记忆。编辑 ~/.hermes/profiles/work/.env 以使用不同的 API 密钥，或编辑 ~/.hermes/profiles/work/SOUL.md 以使用不同的个性。

克隆所有内容（--clone-all）

hermes profile create backup --clone-all

复制所有内容——配置、API 密钥、个性、所有记忆、技能、定时任务、插件。一个完整的工作快照。每个配置文件的历史记录被排除（会话历史、state.db、backups/、state-snapshots/、checkpoints/）——这些属于源配置文件，可能达到数十 GB。如需包含历史记录的完整备份，请改用 hermes profile export 或 hermes backup。

从特定配置文件克隆

hermes profile create work --clone-from coder

--clone-from <源> 直接选择源配置文件，并隐含配置/技能/SOUL 克隆。当你想要该源配置文件的完整副本时，将其与 --clone-all 结合使用：

hermes profile create work-backup --clone-from coder --clone-all

提示 — Honcho 记忆与配置文件

当启用 Honcho 时，克隆操作会自动为新配置文件创建一个专用的 AI 对等体，同时共享相同的用户工作空间。每个配置文件构建自己的观察和身份。参见 Honcho -- 多代理/配置文件 了解详情。

使用配置文件

命令别名

每个配置文件自动在 ~/.local/bin/<名称> 获得一个命令别名：

coder chat                    # 与 coder 代理聊天
coder setup                   # 配置 coder 的设置
coder gateway start           # 启动 coder 的网关
coder doctor                  # 检查 coder 的健康状态
coder skills list             # 列出 coder 的技能
coder config set model.default anthropic/claude-sonnet-4

该别名适用于所有 hermes 子命令——它本质上是 hermes -p <名称>。

-p 标志

你也可以在任何命令中显式指定目标配置文件：

hermes -p coder chat
hermes --profile=coder doctor
hermes chat -p coder -q "hello"    # 可在任何位置使用

固定默认值（hermes profile use）

hermes profile use coder
hermes chat                   # 现在目标为 coder
hermes tools                  # 配置 coder 的工具
hermes profile use default    # 切换回来

设置一个默认值，使得普通的 hermes 命令指向该配置文件。类似于 kubectl config use-context。

了解当前位置

CLI 始终显示哪个配置文件处于活动状态：

• 提示符：coder ❯ 而不是 ❯
• 横幅：启动时显示 Profile: coder
• hermes profile：显示当前配置文件名称、路径、模型、网关状态

配置文件 vs 工作区 vs 沙箱

配置文件常与工作区或沙箱混淆，但它们是不同的概念：

• 配置文件为 Hermes 提供自己的状态目录：config.yaml、.env、SOUL.md、会话、记忆、日志、定时任务和网关状态。
• 工作区或工作目录是终端命令启动的位置。这由 terminal.cwd 单独控制。
• 沙箱限制文件系统访问。配置文件不会对代理进行沙箱化。

在默认的 local 终端后端上，代理仍然拥有与你的用户账户相同的文件系统访问权限。配置文件不会阻止它访问配置文件目录之外的文件夹。

如果你希望配置文件在特定项目文件夹中启动，请在该配置文件的 config.yaml 中设置显式的绝对 terminal.cwd：

terminal:
  backend: local
  cwd: /absolute/path/to/project

在本地后端上使用 cwd: "." 意味着“启动 Hermes 的目录”，而不是“配置文件目录”。

另请注意：

• SOUL.md 可以指导模型，但不会强制执行工作区边界。
• 对 SOUL.md 的更改会在新会话中干净地生效。现有会话可能仍在使用旧的提示状态。
• 询问模型“你在哪个目录？”并不是可靠的隔离测试。如果你需要工具的可预测起始目录，请显式设置 terminal.cwd。

运行网关

每个配置文件作为独立进程运行自己的网关，拥有自己的机器人令牌：

coder gateway start           # 启动 coder 的网关
assistant gateway start       # 启动 assistant 的网关（独立进程）

不同的机器人令牌

每个配置文件拥有自己的 .env 文件。在每个文件中配置不同的 Telegram/Discord/Slack 机器人令牌：

## 编辑 coder 的令牌
nano ~/.hermes/profiles/coder/.env
## 编辑 assistant 的令牌
nano ~/.hermes/profiles/assistant/.env

安全性：令牌锁定

如果两个配置文件意外使用了相同的机器人令牌，第二个网关将被阻止，并显示明确的错误信息，指出冲突的配置文件名称。支持 Telegram、Discord、Slack、WhatsApp 和 Signal。

持久化服务

coder gateway install         # 创建 hermes-gateway-coder systemd/launchd 服务
assistant gateway install     # 创建 hermes-gateway-assistant 服务

每个配置文件获得自己的服务名称。它们独立运行。

注意 — 在官方 Docker 镜像内

每个配置文件的网关由 s6-overlay（容器中的 PID 1）监管，因此 hermes profile create <名称> 会自动在 /run/service/gateway-<名称>/ 注册一个 s6 服务槽。hermes -p <名称> gateway start/stop/restart 会分派到 s6-svc 而不是生成裸进程——崩溃会自动重启，docker restart 会保留之前运行的一组网关。参见 每个配置文件的网关监管 了解详情。

配置配置文件

每个配置文件拥有自己的：

• config.yaml — 模型、提供商、工具集、所有设置
• .env — API 密钥、机器人令牌
• SOUL.md — 个性和指令

coder config set model.default anthropic/claude-sonnet-4
echo "你是一个专注的编码助手。" > ~/.hermes/profiles/coder/SOUL.md

如果你希望此配置文件默认在特定项目中工作，还需设置自己的 terminal.cwd：

coder config set terminal.cwd /absolute/path/to/project

从仪表板

Web 仪表板 是一个机器级别的界面，可以通过侧边栏中的配置文件切换器管理任何配置文件的配置、API 密钥、技能、MCP 和模型——无需每个配置文件单独的仪表板。coder dashboard 会路由到机器仪表板，并预选 coder 配置文件。仪表板的聊天选项卡也会跟随切换器，在所选配置文件的主目录下启动对话。

注意：仪表板配置文件页面上的“设置为活动”是未来 CLI/网关运行的固定默认值（与 hermes profile use 相同）——要从仪表板编辑配置文件，请使用切换器。

更新

hermes update 拉取一次代码（共享）并自动将新的内置技能同步到所有配置文件：

hermes update
## → 代码已更新（12 次提交）
## → 技能已同步：default（最新），coder（+2 新），assistant（+2 新）

用户修改的技能永远不会被覆盖。

管理配置文件

hermes profile list           # 显示所有配置文件及其状态
hermes profile show coder     # 显示一个配置文件的详细信息
hermes profile rename coder dev-bot   # 重命名（更新别名和服务）
hermes profile export coder   # 导出为 coder.tar.gz
hermes profile import coder.tar.gz   # 从归档导入

删除配置文件

hermes profile delete coder

这会停止网关、移除 systemd/launchd 服务、移除命令别名，并删除所有配置文件数据。系统会要求你输入配置文件名称以确认。

使用 --yes 跳过确认：hermes profile delete coder --yes

注意

你不能删除默认配置文件（~/.hermes）。要删除所有内容，请使用 hermes uninstall。

标签补全

## Bash
eval "$(hermes completion bash)"
## Zsh
eval "$(hermes completion zsh)"

将这一行添加到你的 ~/.bashrc 或 ~/.zshrc 中以实现持久补全。补全 -p 后的配置文件名称、配置文件子命令以及顶级命令。

工作原理

配置文件使用 HERMES_HOME 环境变量。当你运行 coder chat 时，包装脚本会在启动 hermes 之前设置 HERMES_HOME=~/.hermes/profiles/coder。由于代码库中 119+ 个文件通过 get_hermes_home() 解析路径，Hermes 状态会自动限定到配置文件的目录——配置、会话、记忆、技能、状态数据库、网关 PID、日志和定时任务。

这与终端工作目录是分开的。工具执行从 terminal.cwd 开始（或在本地后端上使用 cwd: "." 时从启动目录开始），而不是自动从 HERMES_HOME 开始。

在主机安装中，工具子进程默认保留你真实的 OS 用户 HOME，因此 ~ 下现有的 CLI 凭据可以在不同配置文件中继续使用。配置文件数据通过 HERMES_HOME 隔离，而不是通过更改 HOME。容器后端仍然使用 {HERMES_HOME}/home 来持久化工具状态，需要严格按配置文件配置工具的主机用户可以通过 terminal.home_mode: profile 选择加入。

这意味着两件容易混淆的事情：

• HERMES_HOME 是配置文件的边界。它控制 Hermes 配置、.env、记忆、会话、技能、日志、定时任务、网关状态以及其他 Hermes 数据。
• HOME 是外部 CLI 期望的操作系统/用户主目录。在主机安装中，Hermes 默认将其保留为真实用户主目录，以便 git、ssh、gh、az、npm、Claude Code 和 Codex 等工具找到与普通 shell 中相同的凭据。

权衡是主机配置文件默认共享普通的用户级 CLI 状态。如果你需要每个配置文件有独立的 CLI 身份，请在该配置文件的 config.yaml 中设置 terminal.home_mode: profile。在该模式下，Hermes 会以 HOME={HERMES_HOME}/home 启动工具子进程；然后你需要在配置文件主目录内初始化或链接特定于配置文件的 ~/.ssh、~/.gitconfig、~/.config/gh、云 CLI 认证、Claude/Codex 认证、npm 状态等文件。

Hermes 还会向子进程暴露 HERMES_REAL_HOME，以便在 home_mode: profile 激活时脚本仍能找到实际账户主目录。

默认配置文件就是 ~/.hermes 本身。无需迁移——现有安装的工作方式完全相同。

将配置文件作为发行版共享

你在一个机器上构建的配置文件可以打包为 git 仓库，并在另一台机器上用一条命令安装——无论是你自己的工作站、队友的笔记本电脑，还是社区用户的环境。共享包包括 SOUL、配置、技能、定时任务和 MCP 连接。凭据、记忆和会话保留在每台机器上。

## 从 git 仓库安装整个代理
hermes profile install github.com/you/research-bot --alias
## 当作者发布新版本时更新（保留你的记忆和 .env）
hermes profile update research-bot

参见 配置文件发行版：共享整个代理 获取完整指南——创作、发布、更新语义、安全模型和用例。