hermes教程-配置文件命令参考

`hermes profile`

bash

hermes profile <subcommand>

管理配置文件（profile）的顶层命令。运行 hermes profile 而不带子命令会显示帮助信息。

子命令	描述
`list`	列出所有配置文件。
`use`	设置当前激活（默认）的配置文件。
`create`	创建新的配置文件。
`describe`	读取或设置配置文件的描述（看板编排器用于路由）。
`delete`	删除配置文件。
`show`	显示配置文件的详细信息。
`alias`	重新生成配置文件的 shell 别名。
`rename`	重命名配置文件。
`export`	将配置文件导出为 tar.gz 归档文件。
`import`	从 tar.gz 归档文件导入配置文件。
`install`	从 git URL 或本地目录安装配置文件发行版。参见配置文件发行版。
`update`	重新拉取由发行版管理的配置文件并重新应用其捆绑包。
`info`	显示配置文件的发行版元数据（来源 URL、提交、最后更新）。

`hermes profile list`

bash

hermes profile list

列出所有配置文件。当前激活的配置文件以 * 标记。

示例：

bash

$ hermes profile list
  default
* work
  dev
  personal

无选项。

`hermes profile use`

bash

hermes profile use <name>

将 <name> 设置为当前激活的配置文件。之后所有 hermes 命令（不带 -p）将使用此配置文件。

参数	描述
`<name>`	要激活的配置文件名称。使用 `default` 可返回基础配置文件。

示例：

bash

hermes profile use work
hermes profile use default

`hermes profile create`

bash

hermes profile create <name> [options]

创建新的配置文件。

参数 / 选项	描述
`<name>`	新配置文件的名称。必须是有效的目录名（字母数字、连字符、下划线）。
`--clone`	从当前配置文件复制 `config.yaml`、`.env`、`SOUL.md` 和技能。
`--clone-all`	从当前配置文件复制所有内容（配置、记忆、技能、定时任务、插件）。不包括每个配置文件的历史记录：会话、`state.db`、备份、状态快照、检查点。
`--clone-from <profile>`	从指定配置文件（而非当前配置文件）克隆配置/技能/SOUL。除非与 `--clone-all` 一起使用，否则隐含 `--clone`。
`--no-alias`	跳过包装脚本的创建。
`--description "<text>"`	用一两句话描述此配置文件擅长什么。看板编排器根据角色（而非仅配置文件名称）来路由任务。可跳过，稍后通过 `hermes profile describe` 添加。持久化存储在 `<profile_dir>/profile.yaml` 中。
`--no-skills`	创建一个空配置文件，不启用任何捆绑技能。在配置文件中写入 `.no-bundled-skills` 标记，以便将来的 `hermes update` 运行不会重新植入捆绑集，并且拒绝与 `--clone`、`--clone-from` 或 `--clone-all` 结合使用（这些选项会复制技能）。适用于狭窄的编排器配置文件或沙箱配置文件，这些配置文件不应继承完整的技能目录。要在已创建的配置文件（包括默认的 `~/.hermes`）上切换此选项，请使用 `hermes skills opt-out` / `hermes skills opt-in`。

创建配置文件不会使该配置文件目录成为终端命令的默认项目/工作目录。如果希望配置文件在特定项目中启动，请在该配置文件的 config.yaml 中设置 terminal.cwd。

示例：

bash

## 空白配置文件——需要完整设置
hermes profile create mybot
## 仅从当前配置文件克隆配置
hermes profile create work --clone
## 从当前配置文件克隆所有内容
hermes profile create backup --clone-all
## 从指定配置文件克隆配置
hermes profile create work2 --clone-from work
## 从指定配置文件克隆所有内容
hermes profile create work2-backup --clone-from work --clone-all

`hermes profile describe`

bash

hermes profile describe [<name>] [options]

读取或设置配置文件的描述。看板编排器使用此描述根据每个配置文件擅长的内容来路由任务，而不是仅从配置文件名称猜测。持久化存储在 <profile_dir>/profile.yaml 中，因此重启后仍然存在，并与网关共享。

不带标志时，打印当前描述（如果为空则打印 (no description set for '<name>')）。

参数 / 选项	描述
`<name>`	要描述的配置文件。除非使用 `--all --auto`，否则必需。
`--text "<text>"`	将描述设置为此确切文本（用户编写）。覆盖任何现有描述。
`--auto`	通过辅助 LLM 根据配置文件已安装的技能、配置的模型和名称自动生成 1-2 句描述。在 `config.yaml` 的 `auxiliary.profile_describer` 下配置模型。自动生成的描述标记为 `description_auto: true`，以便仪表板可以标记它们以供审查。
`--overwrite`	与 `--auto` 一起使用时，也替换用户编写的描述（默认：跳过已显式设置描述的配置文件）。
`--all`	与 `--auto` 一起使用时，扫描所有缺少描述的配置文件。

示例：

bash

## 读取当前描述
hermes profile describe researcher
## 显式设置描述
hermes profile describe researcher --text "Reads source code and writes findings."
## 让 LLM 生成描述
hermes profile describe researcher --auto
## 为每个缺少描述的配置文件填充描述
hermes profile describe --all --auto

`hermes profile delete`

bash

hermes profile delete <name> [options]

删除配置文件并移除其 shell 别名。

参数 / 选项	描述
`<name>`	要删除的配置文件。
`--yes`, `-y`	跳过确认提示。

示例：

bash

hermes profile delete mybot
hermes profile delete mybot --yes

警告

这将永久删除配置文件的整个目录，包括所有配置、记忆、会话和技能。无法删除当前激活的配置文件。

`hermes profile show`

bash

hermes profile show <name>

显示配置文件的详细信息，包括其主目录、配置的模型、网关状态、技能数量和配置文件状态。

这显示配置文件的 Hermes 主目录，而不是终端工作目录。终端命令从 terminal.cwd 启动（或在本地后端上，当 cwd: "." 时从启动目录启动）。

参数	描述
`<name>`	要检查的配置文件。

示例：

bash

$ hermes profile show work
Profile: work
Path:    ~/.hermes/profiles/work
Model:   anthropic/claude-sonnet-4 (anthropic)
Gateway: stopped
Skills:  12
.env:    exists
SOUL.md: exists
Alias:   ~/.local/bin/work

`hermes profile alias`

bash

hermes profile alias <name> [options]

在 ~/.local/bin/<name> 重新生成 shell 别名脚本。如果别名被意外删除，或者需要在移动 Hermes 安装后更新别名，此命令很有用。

参数 / 选项	描述
`<name>`	要创建/更新别名的配置文件。
`--remove`	移除包装脚本而不是创建它。
`--name <alias>`	自定义别名名称（默认：配置文件名称）。

示例：

bash

hermes profile alias work
## 创建/更新 ~/.local/bin/work

hermes profile alias work --name mywork
## 创建 ~/.local/bin/mywork

hermes profile alias work --remove
## 移除包装脚本

`hermes profile rename`

bash

hermes profile rename <old-name> <new-name>

重命名配置文件。更新目录和 shell 别名。

参数	描述
`<old-name>`	当前配置文件名称。
`<new-name>`	新的配置文件名称。

示例：

bash

hermes profile rename mybot assistant
## ~/.hermes/profiles/mybot → ~/.hermes/profiles/assistant
## ~/.local/bin/mybot → ~/.local/bin/assistant

`hermes profile export`

bash

hermes profile export <name> [options]

将配置文件导出为压缩的 tar.gz 归档文件。

参数 / 选项	描述
`<name>`	要导出的配置文件。
`-o`, `--output <path>`	输出文件路径（默认：`<name>.tar.gz`）。

示例：

bash

hermes profile export work
## 在当前目录创建 work.tar.gz

hermes profile export work -o ./work-2026-03-29.tar.gz

`hermes profile import`

bash

hermes profile import <archive> [options]

从 tar.gz 归档文件导入配置文件。

参数 / 选项	描述
`<archive>`	要导入的 tar.gz 归档文件路径。
`--name <name>`	导入的配置文件的名称（默认：从归档文件推断）。

示例：

bash

hermes profile import ./work-2026-03-29.tar.gz
## 从归档文件推断配置文件名称

hermes profile import ./work-2026-03-29.tar.gz --name work-restored

发行版命令

提示

刚接触发行版？ 从配置文件发行版用户指南开始——它通过完整示例介绍了原因、时机和方法。以下部分是一个简洁的 CLI 参考，适用于你已经知道想要什么的情况。

发行版将配置文件转变为可共享、带版本号的工件，以 git 仓库 的形式发布。接收者通过一条命令安装发行版，之后可以在不触及本地记忆、会话或凭据的情况下原地更新。

auth.json 和 .env 永远不会成为发行版的一部分——它们保留在安装用户的机器上。

接收者的用户数据（记忆、会话、认证、他们对 .env 的编辑）在初始安装和后续更新中始终保留。

信息

hermes profile export / import 仍然是用于在本地机器上本地备份和恢复配置文件的正确命令。发行版（install / update / info）是一个独立的概念：通过 git 发布配置文件，以便其他人可以安装它。

`hermes profile install`

bash

hermes profile install <source> [--name <name>] [--alias] [--force] [--yes]

从 git URL 或本地目录安装配置文件发行版。

选项	描述
`<source>`	Git URL（`github.com/user/repo`、`https://...`、`git@...`、`ssh://`、`git://`）或包含根目录下 `distribution.yaml` 的本地目录。
`--name NAME`	覆盖清单中的配置文件名称。
`--alias`	同时创建 shell 包装器（例如 `telemetry` → `hermes -p telemetry`）。
`--force`	覆盖同名的现有配置文件。用户数据仍然保留。
`-y`, `--yes`	跳过清单预览确认提示。

安装程序会显示清单、列出所需的环境变量，并在要求确认之前警告定时任务。所需的环境变量会放入一个 .env.EXAMPLE 文件中，你需要将其复制为 .env 并填写。

示例：

bash

## 从 GitHub 仓库安装（简写）
hermes profile install github.com/kyle/telemetry-distribution --alias
## 从完整的 HTTPS git URL 安装
hermes profile install https://github.com/kyle/telemetry-distribution.git
## 从 SSH 安装
hermes profile install [email protected]:kyle/telemetry-distribution.git
## 开发期间从本地目录安装
hermes profile install ./telemetry/

`hermes profile update`

bash

hermes profile update <name> [--force-config] [--yes]

从其记录的来源重新克隆发行版并应用更新。发行版拥有的文件（SOUL.md、skills/、cron/、mcp.json）会被覆盖；用户数据（记忆、会话、认证、.env）永远不会被触及。

默认情况下保留 config.yaml 以保持你的本地覆盖。传递 --force-config 可将其重置为发行版附带的配置。

`hermes profile info`

bash

hermes profile info <name>

打印配置文件的发行版清单——名称、版本、所需的 Hermes 版本、作者、环境变量要求、来源 URL/路径，以及上次 install 或 update 时记录的 Installed: 时间戳。用于在安装共享配置文件之前检查其需求，以及发现“此配置文件是 6 个月前安装的，尚未更新”。

hermes profile list 还会在 Distribution 列中显示发行版名称和版本，而 hermes profile show <name> / delete <name> 会显示来源 URL，以便你一眼看出哪些配置文件来自 git 仓库，哪些是本地创建的。

私有发行版

私有 git 仓库作为发行版来源无需额外配置——安装命令会调用你正常的 git 二进制文件，因此你的 shell 已设置好的任何认证（SSH 密钥、git credential 助手、GitHub CLI 存储的 HTTPS 凭据）都会透明地生效。

bash

## 使用你的 SSH 密钥，与任何其他 `git clone` 相同
hermes profile install [email protected]:your-org/internal-assistant.git
## 使用你的 git credential 助手
hermes profile install https://github.com/your-org/internal-assistant.git

如果在安装过程中克隆提示交互式输入凭据，该提示会正常显示。请先像通常使用 git clone 针对同一仓库那样设置好你的认证，然后再安装。

发行版清单（`distribution.yaml`）

每个发行版在其仓库根目录下都有一个 distribution.yaml：

yaml

name: telemetry
version: 0.1.0
description: "Compliance monitoring harness"
hermes_requires: ">=0.12.0"
author: "Your Name"
license: "MIT"
env_requires:
  - name: OPENAI_API_KEY
    description: "OpenAI API key"
    required: true
  - name: GRAPHITI_MCP_URL
    description: "Memory graph URL"
    required: false
    default: "http://127.0.0.1:8000/sse"
distribution_owned:   # 可选；默认为 SOUL.md、config.yaml、
## mcp.json、skills/、cron/、distribution.yaml
  - SOUL.md
  - skills/compliance/
  - cron/

hermes_requires 支持 >=、<=、==、!=、>、< 或裸版本号（视为 >=）。如果当前 Hermes 版本不满足规范，安装会失败并显示清晰的错误信息。

distribution_owned 是可选的。如果设置了，则只有这些路径会在更新时被替换；配置文件中的其他内容保持用户所有。如果省略，则应用上述默认值。

发布发行版

编写发行版只需一次 git push：

在你的配置文件目录中，创建包含至少 name 和 version 的 distribution.yaml。
初始化一个 git 仓库（或使用现有仓库）并推送到 GitHub / GitLab / 任何 Hermes 可以克隆的主机。
告诉接收者运行 hermes profile install <你的仓库URL>。

使用 git 标签进行版本化发布——克隆 HEAD 的接收者会获得你的最新状态，并且你随时可以更新清单中的 version:。

`hermes -p` / `hermes --profile`

bash

hermes -p <name> <command> [options]
hermes --profile <name> <command> [options]

全局标志，用于在特定配置文件下运行任何 Hermes 命令，而不更改粘性默认值。这会在此命令期间覆盖当前激活的配置文件。

选项	描述
`-p <name>`, `--profile <name>`	用于此命令的配置文件。

示例：

bash

hermes -p work chat -q "Check the server status"
hermes --profile dev gateway start
hermes -p personal skills list
hermes -p work config edit

`hermes completion`

bash

hermes completion <shell>

生成 shell 补全脚本。包括配置文件名称和配置文件子命令的补全。

参数	描述
`<shell>`	要生成补全的 shell：`bash`、`zsh` 或 `fish`。

示例：

bash

## 安装补全
hermes completion bash >> ~/.bashrc
hermes completion zsh >> ~/.zshrc
hermes completion fish > ~/.config/fish/completions/hermes.fish
## 重新加载 shell
source ~/.bashrc

安装后，Tab 补全适用于：

hermes profile <TAB> — 子命令（list、use、create 等）
hermes profile use <TAB> — 配置文件名称
hermes -p <TAB> — 配置文件名称

字节笔记本

hermes教程-配置文件命令参考

hermes profile

hermes profile list

hermes profile use

hermes profile create

hermes profile describe

hermes profile delete

hermes profile show

hermes profile alias

hermes profile rename

hermes profile export

hermes profile import

发行版命令

hermes profile install

hermes profile update

hermes profile info

私有发行版

发行版清单（distribution.yaml）

发布发行版

hermes -p / hermes --profile

hermes completion

参见

`hermes profile`

`hermes profile list`

`hermes profile use`

`hermes profile create`

`hermes profile describe`

`hermes profile delete`

`hermes profile show`

`hermes profile alias`

`hermes profile rename`

`hermes profile export`

`hermes profile import`

`hermes profile install`

`hermes profile update`

`hermes profile info`

发行版清单（`distribution.yaml`）

`hermes -p` / `hermes --profile`

`hermes completion`