配置文件：运行多个代理

hermes 运行多个代理指南

在同一台机器上运行多个相互独立的 Hermes 代理 —— 每个代理都拥有自己独立的配置、API 密钥、记忆、会话、技能以及网关状态。

什么是配置文件（Profiles）？

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

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

快速开始

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

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

创建配置文件

空白配置文件

hermes profile create mybot

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

如果你计划将此配置集（profile）用作看板工人（或者希望看板编排器将工作路由给它），请在创建时传入 --description "<role>"，以便编排器了解它擅长什么：

hermes profile create researcher --description "Reads source code and external docs, writes findings."

你也可以在稍后使用 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 密钥、性格、所有记忆、完整的会话历史、技能、定时任务和插件。这是一个完整的快照，适用于备份或派生一个已经拥有上下文的代理。

从特定配置文件克隆

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

使用配置文件

命令别名

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

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 <name>。

-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 沙箱 (Profiles vs workspaces vs sandboxing)

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

配置文件 (Profile) 为 Hermes 提供独立的状态目录：包含 config.yaml、.env、SOUL.md、会话、记忆、日志、定时任务和网关状态。
工作区 (Workspace) 或 工作目录 (Working directory) 是终端命令启动的地方。这由 terminal.cwd 独立控制。
沙箱 (Sandbox) 是限制文件系统访问权限的机制。配置文件并不会对代理进行沙箱化。

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

如果您希望某个配置文件在特定的项目文件夹中启动，请在该配置文件的 config.yaml 中设置明确的绝对路径 terminal.cwd：

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

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

另请注意：

SOUL.md 可以引导模型，但它不具备强制执行工作区边界的功能。
对 SOUL.md 的更改会在新会话中完全生效。现有会话可能仍在沿用旧的提示词状态。
询问模型 “你在哪个目录下？” 并不是一种可靠的隔离测试。如果您需要为工具提供一个可预测的起始目录，请明确设置 terminal.cwd。

运行网关 (Running gateways)

每个配置文件（Profile）都作为一个独立的进程运行自己的网关，并拥有专属的机器人令牌（bot token）：

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 服务

每个配置文件都拥有独立的服务名称，它们互不干扰地运行。

配置配置文件（Configuring profiles）

每个配置文件都拥有独立的：

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

coder config set model.default anthropic/claude-sonnet-4
echo "You are a focused coding assistant." > ~/.hermes/profiles/coder/SOUL.md

如果您希望此配置文件默认在特定项目中工作，还可以设置其专属的 terminal.cwd：

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

更新（Updating）

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

hermes update
# → 代码已更新 (12 commits)
# → 技能已同步: default (最新), coder (+2 new), assistant (+2 new)

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

管理配置文件

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

Tab 键补全

# 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 开始。

默认配置文件即为 ~/.hermes 本身。无需迁移 —— 现有安装的运行方式完全一致。

作为分发包（Distributions）共享配置文件

您在某台机器上构建的配置文件可以封装为 Git 仓库，并在另一台机器（您自己的工作站、队友的笔记本电脑或社区用户的环境）上通过一条命令安装。共享包包含 SOUL、配置、技能、定时任务和 MCP 连接。凭据、记忆和会话保持在每台机器各自独立。

# 从 git 仓库安装整个代理
hermes profile install github.com/you/research-bot --alias

# 当作者发布新版本时进行更新（保留您的记忆和 .env）
hermes profile update research-bot

完整指南请参阅 Profile Distributions: Share a Whole Agent —— 包含创作、发布、更新语义、安全模型及使用场景。