配置分发：共享完整代理

配置分发功能将一个完整的Hermes代理——包括其个性设定、技能、定时任务、MCP连接信息以及配置文件——打包为一个Git仓库。任何拥有该仓库访问权限的人都可以通过一条命令即可安装整个代理，对其进行更新，同时不会影响其原有的记忆、会话记录和API密钥。

如果某个配置文件代表的是本地代理，那么配置分发则意味着将该代理变为可共享的形式。

这意味着什么

在配置分发功能出现之前，要共享一个Hermes代理，就需要将以下内容传递给他人：

SOUL.md 文件
需要安装的技能列表
已移除敏感信息的 config.yaml 文件
已连接的MCP服务器说明
所设置的定时任务
需要设置的环境变量说明

……然后还要指望对方能正确地组装这些内容。每当版本升级或修复漏洞时，都不得不重复这一繁琐的过程。

而借助配置分发功能，所有这些内容都存储在同一个Git仓库中：

my-research-agent/
├── distribution.yaml    # manifest: name, version, env-var requirements
├── SOUL.md              # the agent's personality / system prompt
├── config.yaml          # model, temperature, reasoning, tool defaults
├── skills/              # bundled skills that come with the agent
├── cron/                # scheduled tasks the agent runs
└── mcp.json             # MCP servers the agent connects to

接收方运行：

hermes profile install github.com/you/my-research-agent --alias

……现在他们已经拥有了完整的智能体。只需自行填写 API 密钥（将 .env.EXAMPLE 替换为 .env），即可运行 my-research-agent chat，或通过 Telegram、Discord、Slack 以及任何网关平台与之交互。当您推送新版本时，他们只需执行 hermes profile update my-research-agent 即可获取您的更新——他们的智能体记忆和会话记录将保持不变。

为何选择 git？

我们曾考虑过使用压缩包、HTTP 归档文件或自定义格式，但都没有 git 更出色：

对开发者而言无需额外构建步骤。只需将代码推送到 GitHub，使用者即可直接安装，无需经历“打包、上传、更新索引”这样的循环流程。
标签、分支和提交本身就已构成版本控制系统。推送一个标签就能实现其他工具中“打包并上传新版本”的功能。
更新仅需简单拉取，无需重新下载整个归档文件。
透明度高。用户可以浏览代码仓库，查看不同版本之间的差异，提交问题，甚至 fork 仓库进行自定义修改。
私有代码仓库也可免费使用。无论是 SSH 密钥、git credential 工具，还是 GitHub CLI 中存储的凭证，只要终端已配置好相应认证方式，就能直接使用。
可重复性由提交 SHA 值保证，这与 pip 和 npm 的记录方式一致。

唯一的缺点是：接收方需要安装 git。而到了 2026 年，所有运行 Hermes 的机器都早已具备这一条件。

何时应该使用分发包？

适合使用的情况包括：

您希望与团队或社区共享某个专用智能体——比如合规监控工具、代码审查助手、研究辅助机器人或客户支持机器人。
您需要将同一个智能体部署到多台机器上，且不想每次都手动复制文件。
您正在对智能体进行迭代开发，希望接收方只需一条命令就能获取最新版本。
您正在将智能体作为产品进行开发——包含经过优化的默认设置、精选的技能模块以及调优过的提示词——希望他人能以此为起点进行使用。

不适合使用的情况包括：

您只是想在自己的机器上备份智能体配置。此时应使用 hermes profile export / import 命令——它们正是为此设计的。
您希望同时共享 API 密钥。auth.json 和 .env 文件会被刻意排除在分发包之外，每个安装者都需要自行提供凭证。
您希望共享智能体的记忆记录、会话内容或对话历史。这些属于用户数据，而非分发包的内容，因此永远不会被包含在内。

:::caution Hermes 并不控制 git 系统。本页所述的文件排除规则是由安装程序在用户执行 hermes profile install 或 hermes profile update 时自动应用的。当您执行 git add 或 git commit 操作时，这些规则则不会生效。: ::

生命周期：从开发者到安装者再到更新维护

以下是完整的端到端流程，您可以根据感兴趣的部分进行查看。

对于开发者：发布分发包

第一步——从可用的配置文件开始

像处理其他配置文件一样构建并优化该智能体：

hermes profile create research-bot
research-bot setup                    # configure model, API keys
# Edit ~/.hermes/profiles/research-bot/SOUL.md
# Install skills, wire up MCP servers, schedule cron jobs, etc.
research-bot chat                     # dogfood until it feels right

第 2 步 — 添加 `distribution.yaml` 文件

创建 ~/.hermes/profiles/research-bot/distribution.yaml 文件：

name: research-bot
version: 1.0.0
description: "Autonomous research assistant with arXiv and web tools"
hermes_requires: ">=0.12.0"
author: "Your Name"
license: "MIT"

# Tell installers which env vars the agent needs. These are checked against
# the installer's shell and existing .env file so they don't get nagged
# about keys they already have configured.
env_requires:
  - name: OPENAI_API_KEY
    description: "OpenAI API key (for model access)"
    required: true
  - name: SERPAPI_KEY
    description: "SerpAPI key for web search"
    required: false
    default: ""

这就是完整的清单文件了。除 name 字段外，其他所有字段都配有合理的默认值。

第 3 步——在首次提交之前创建 `.gitignore` 文件

:::warning 请在运行 git init 或 git add 之前执行此操作。如果您已经与该配置文件进行过对话、运行过设置脚本，或以其他方式使用过它，那么该目录中就会包含一些不应被纳入版本控制的文件，例如：.env、auth.json、memories/、sessions/、state.db*、logs/ 等。: ::

请至少创建 ~/.hermes/profiles/research-bot/.gitignore 文件，并在其中添加以下内容：

# Credentials & secrets — NEVER commit
auth.json
.env
.env.EXAMPLE    # generated by install, not authorship domain

# Runtime databases & state
state.db
state.db-shm
state.db-wal
hermes_state.db
response_store.db
response_store.db-shm
response_store.db-wal
gateway.pid
gateway_state.json
processes.json
auth.lock
active_profile
.update_check

# User data — NEVER commit
memories/
sessions/
logs/
plans/
workspace/
home/

# Caches & generated artifacts
image_cache/
audio_cache/
document_cache/
browser_screenshots/
cache/

# Infrastructure (should not be in profile dir, but safe to exclude)
hermes-agent/
.worktrees/
profiles/
bin/
node_modules/

# User customization namespace — your local overrides
local/

# Checkpoints & backups (can be huge)
checkpoints/
sandboxes/
backups/

# Logs
errors.log
.hermes_history

这与安装程序在自身端会移除的硬性排除路径相对应。凡是您希望不放入代码仓库的其他内容（临时文件、大型资源、仅本地可用的技能等），也应放入此处。

第 4 步 —— 推送至 git 代码仓库

cd ~/.hermes/profiles/research-bot
git init
git add .
git commit -m "v1.0.0"
git remote add origin git@github.com:you/research-bot.git
git tag v1.0.0
git push -u origin main --tags

该仓库现已升级为发行版，任何拥有访问权限的用户均可进行安装。: ::note 即便开发者意外将某些内容包含在发布包中，安装程序也会自动移除这些硬性排除的路径——但这一措施仅能保护安装程序本身，无法保护开发者。; ::

第 5 步 — 为版本化发布打标签

每当智能体达到稳定状态时，便需提升版本号并为其打标签：

# Edit distribution.yaml: version: 1.1.0
git add distribution.yaml SOUL.md skills/
git commit -m "v1.1.0: tighter research SOUL, add arxiv skill"
git tag v1.1.0
git push --tags

运行 hermes profile update research-bot 命令的接收端将会获取最新版本。

代码仓库的结构

一个完整的发布版：

research-bot/
├── .gitignore                   # excludes secrets & user data (see Step 3)
├── distribution.yaml            # required
├── SOUL.md                      # strongly recommended
├── config.yaml                  # model, provider, tool defaults
├── mcp.json                     # MCP server connections
├── skills/
│   ├── arxiv-search/SKILL.md
│   ├── paper-summarization/SKILL.md
│   └── citation-lookup/SKILL.md
├── cron/
│   └── weekly-digest.json       # scheduled tasks
└── README.md                    # human-facing description (optional)

发行版自带内容与用户自定义内容

当安装程序升级到新版本时，部分文件会被替换（属于作者维护的域），而另一部分则保持不变（属于安装程序维护的域）。默认设置如下：

类别	路径	升级时处理方式
发行版自带内容	`SOUL.md`、`config.yaml`、`mcp.json`、`skills/`、`cron/`、`distribution.yaml`	从新克隆的版本中替换
配置覆盖项	`config.yaml`	默认情况下会保留原有设置——因为安装程序可能已对模型或服务提供商进行了定制。如需重置，可在升级时使用 `--force-config` 参数
用户自定义内容	`memories/`、`sessions/`、`state.db`、`auth.json`、`.env`、`logs/`、`workspace/`、`plans/`、`home/`、`_cache/`、`local/`	完全不会被修改

您可以在清单文件中自定义发行版自带内容的列表：

distribution_owned:
  - SOUL.md
  - skills/research/            # only my research skills; other installed skills stay
  - cron/digest.json

如果未指定，则会采用上述默认设置——这正是大多数发行版所期望的。

面向安装程序：使用发行版

安装

hermes profile install github.com/you/research-bot --alias

执行流程如下：

将仓库克隆到临时目录中。
读取 distribution.yaml 文件，并展示配置清单（包括名称、版本、描述、作者以及必需的环境变量）。
检查每个必需的环境变量在您的Shell环境及目标配置文件现有的 .env 中的设置情况，分别标记为“✓ 已设置”或“需设置”，让您清晰了解需要配置的内容。
提示您确认操作。如需跳过此步骤，可输入 -y / --yes。
将发行版自带的文件复制到 ~/.hermes/profiles/research-bot/ 目录中（或配置清单中指定的其他路径）。在此复制过程中，即使作者意外将某些文件留在了仓库中，那些绝对禁止复制的路径也会被自动剔除。
生成一个包含所需键值且已添加注释的 .env.EXAMPLE 文件——您可以将其复制到 .env 文件中并填写具体数值。
若使用 --alias 参数，还会生成一个快捷命令封装，让您可以直接运行 research-bot chat。

源代码类型

任何 Git 地址均可使用：

# GitHub shorthand
hermes profile install github.com/you/research-bot

# Full HTTPS
hermes profile install https://github.com/you/research-bot.git

# SSH
hermes profile install git@github.com:you/research-bot.git

# Self-hosted, GitLab, Gitea, Forgejo — any Git host
hermes profile install https://git.example.com/team/research-bot.git

# Private repo using your configured git auth
hermes profile install git@github.com:your-org/internal-bot.git

# Local directory during development (no git push needed)
hermes profile install ~/my-profile-in-progress/

覆盖配置文件名称

有两名用户希望使用相同的发行版，但希望将其命名为不同的配置文件名称：

# Alice
hermes profile install github.com/acme/support-bot --name support-us --alias
# Bob (same distribution, different local name)
hermes profile install github.com/acme/support-bot --name support-eu --alias

填写环境变量

安装完成后，代理的配置文件中会包含一个 .env.EXAMPLE 文件：

# Environment variables required by this Hermes distribution.
# Copy to `.env` and fill in your own values before running.

# OpenAI API key (for model access)
# (required)
OPENAI_API_KEY=

# SerpAPI key for web search
# (optional)
# SERPAPI_KEY=

复制它：

cp ~/.hermes/profiles/research-bot/.env.EXAMPLE ~/.hermes/profiles/research-bot/.env
# Edit .env, paste your real keys

在安装过程中，那些已存在于您的shell环境中的必需密钥（例如在~/.zshrc文件中导出的OPENAI_API_KEY）会标记为“✓ 已设置”——您无需在.env文件中重复添加这些密钥。

查看已安装的内容

hermes profile info research-bot

显示内容：

Distribution: research-bot
Version:      1.0.0
Description:  Autonomous research assistant with arXiv and web tools
Author:       Your Name
Requires:     Hermes >=0.12.0
Source:       https://github.com/you/research-bot
Installed:    2026-05-08T17:04:32+00:00

Environment variables:
  OPENAI_API_KEY (required) — OpenAI API key (for model access)
  SERPAPI_KEY (optional) — SerpAPI key for web search

hermes profile list命令还会显示Distribution列，让您一目了然地看出哪些配置文件来自代码仓库，哪些是手动创建的。

 Profile          Model                        Gateway      Alias        Distribution
 ───────────────    ───────────────────────────    ───────────    ───────────    ────────────────────
 ◆default         claude-sonnet-4              stopped      —            —
  coder           gpt-5                        stopped      coder        —
  research-bot    claude-opus-4                stopped      research-bot research-bot@1.0.0
  telemetry       claude-sonnet-4              running      telemetry    telemetry@2.3.1

更新

hermes profile update research-bot

具体流程如下：

从记录的源地址重新克隆仓库。
替换由平台管理的文件（如 SOUL、技能文件、cron 配置及 mcp.json）。
保留您的 config.yaml 文件——您可能已对模型参数、温度值或其他设置进行了自定义调整。如需覆盖这些设置，请使用 --force-config 参数。
绝不修改用户数据：包括记忆内容、会话记录、认证信息、.env 配置文件、日志以及状态数据。

该过程无需重新下载整个压缩包，不会覆盖您对配置文件所做的本地修改，也不会删除您的对话历史记录。

删除操作

hermes profile delete research-bot

在要求您确认之前，删除提示会先显示相关分布信息。

Profile: research-bot
Path:    ~/.hermes/profiles/research-bot
Model:   claude-opus-4 (anthropic)
Skills:  12
Distribution: research-bot@1.0.0
Installed from: https://github.com/you/research-bot

This will permanently delete:
  • All config, API keys, memories, sessions, skills, cron jobs
  • Command alias (~/.local/bin/research-bot)

Type 'research-bot' to confirm:

这样，你就绝不会在不知该智能体来源且无法重新安装的情况下，误将其删除。

使用场景与模式

个人用途：在多台设备间同步同一个智能体

你在笔记本电脑上构建了一个研究助手智能体，现在希望在工作站上也能使用同一个智能体。

# Laptop — create .gitignore first (see "For authors" Step 3), then:
cd ~/.hermes/profiles/research-bot
git init && git add . && git status   # confirm no secrets staged
git commit -m "initial"
git remote add origin git@github.com:you/research-bot.git
git push -u origin main

# Workstation
hermes profile install github.com/you/research-bot --alias
# Fill in .env. Done.

在笔记本电脑上进行的任何代码迭代操作（如 git commit && push）都会通过 hermes profile update research-bot 命令同步到工作站。各设备的记忆是独立存储的——笔记本电脑仅保存自身的对话记录，工作站也仅保存自身的记录，两者之间不会产生冲突。

团队：部署经过审核的内部智能体

您的工程团队希望拥有一个具备特定 SOUL 配置、特定技能，并能自动为每份 Pull Request 执行处理任务的共享式代码审查智能体。

# Engineering lead — create .gitignore first (see "For authors" Step 3), then:
cd ~/.hermes/profiles/pr-reviewer
# ... build and tune ...
git init && git add . && git status   # confirm no secrets staged
git commit -m "v1.0 PR reviewer"
git tag v1.0.0
git push -u origin main --tags    # push to your company's internal Git host

# Each engineer
hermes profile install git@github.com:your-org/pr-reviewer.git --alias
# Fill in .env with their own API key (billed to them), .env.EXAMPLE points at what's required
pr-reviewer chat

当主版本 v1.1 发布后（带来了更强大的 SOUL 功能以及新的智能技能），工程师们只需运行 hermes profile update pr-reviewer 命令，短短几分钟内所有人就能使用到新版本。

社区版：发布公共智能体

如果您开发出了创新性的工具——比如“多市场交易助手”、“学术论文摘要生成器”或“Minecraft 服务器运维辅助工具”——并希望与他人分享，也可以这样做。

# You — create .gitignore first (see "For authors" Step 3), then:
cd ~/.hermes/profiles/polymarket-trader
# Write a solid README.md at the repo root — GitHub shows it on the repo page
git init && git add . && git status   # confirm no secrets staged
git commit -m "v1.0"
git tag v1.0.0
# Publish to a public GitHub repo
git remote add origin https://github.com/you/hermes-polymarket-trader.git
git push -u origin main --tags

# Anyone
hermes profile install github.com/you/hermes-polymarket-trader --alias

将安装命令发布到推特上。尝试使用它的人会向你反馈问题并提交 Pull Request。如果有人希望进行定制，他们就会创建分支——这正是大家早已熟悉的 Git 开发流程。

产品：推出功能完备的智能代理

你可能在 Hermes 的基础上进行了扩展——或许构建了一个合规监控工具、一套客户支持系统，或是某个特定领域的研究平台。现在你想将其作为产品进行推广。

# distribution.yaml
name: telemetry-harness
version: 2.3.1
description: "Compliance telemetry harness — monitors and reviews regulated workflows"
hermes_requires: ">=0.13.0"
author: "Acme Compliance Inc."
license: "Commercial"

env_requires:
  - name: ACME_API_KEY
    description: "Your Acme Compliance license key (email support@acme.com)"
    required: true
  - name: OPENAI_API_KEY
    description: "OpenAI API key for model access"
    required: true
  - name: GRAPHITI_MCP_URL
    description: "URL for your Graphiti knowledge graph instance"
    required: false
    default: "http://127.0.0.1:8000/sse"

您的客户只需执行一条命令即可完成安装；安装预览会明确告知他们需要准备哪些密钥；一旦您为新版本添加标签，更新便会立即推送；而他们的合规数据（位于 memories/ 和 sessions/ 目录中）则永远不会离开他们的设备。

临时型：基于共享基础设施的一次性脚本

您是运维负责人。您需要一个临时代理，用于诊断生产环境中的故障——即一个预置了所需工具及MCP连接的标准化SOUL脚本——并在接下来的一周内运行在三名值班工程师的笔记本电脑上。

# You — create .gitignore first (see "For authors" Step 3), then:
# Build the profile, commit, push a private repo
git push -u origin main

# Each on-call
hermes profile install git@github.com:your-org/incident-2026-q2.git --alias

# Incident resolved — tear it down
hermes profile delete incident-2026-q2

其安装与删除的循环成本极低，甚至可以视为一次性操作。

# Your installed version
hermes profile info research-bot | grep Version

# Latest upstream (without installing)
git ls-remote --tags https://github.com/you/research-bot | tail -5

在更新过程中保留本地配置的定制设置

默认的更新机制已可实现这一功能：config.yaml 文件会得到保留。为更加稳妥，建议将您的本地修改内容保存在发行版不拥有的文件中：

# ~/.hermes/profiles/research-bot/local/my-overrides.yaml
# (distribution never touches local/)

……并在需要时从 config.yaml 或您的 SOUL 中引用它。

强制进行完整重新安装

# Nuke and re-install from scratch (loses memories/sessions too)
hermes profile delete research-bot --yes
hermes profile install github.com/you/research-bot --alias

# Update to current main but reset config.yaml to the distribution's default
hermes profile update research-bot --force-config --yes

复制并自定义

标准的 Git 工作流程——各类发行版其实不过是仓库而已：

# Fork the repo on GitHub, then install your fork
hermes profile install github.com/yourname/forked-research-bot --alias

# Iterate locally in ~/.hermes/profiles/forked-research-bot/
# Edit SOUL.md, commit, push to your fork
# Upstream changes: pull them into your fork the usual way

在推送之前先测试分发版本

从作者的机器上操作：

# Install from a local directory (no git push needed)
hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test --alias

# Tweak, delete, re-install until it's right
hermes profile delete research-bot-test --yes
hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test

分发包中绝不会包含的内容

即便开发者意外将某些文件放入分发包中，安装程序也会强制将其排除。没有任何配置选项可以绕过这一限制——这一安全机制经过了严格的回退测试，属于不可更改的规则：

auth.json — OAuth令牌、平台凭证
.env — API密钥、敏感信息
memories/ — 对话记忆数据
sessions/ — 对话历史记录
state.db、state.db-shm、state.db-wal — 会话元数据
logs/ — 智能体运行日志及错误日志
workspace/ — 生成的临时工作文件
plans/ — 临时规划内容
home/ — Docker后端中用户的主目录
*_cache/ — 图像/音频/文档缓存文件
local/ — 用户自定义的专用空间

当您通过安装程序克隆分发包时，这些文件根本不会被复制到您的个人配置目录中。即便后续进行更新，这些文件也不会被移动。如果您在五台机器上安装了相同的分发包，每台机器都将拥有独立的数据集。: ::caution 此排除机制在安装/更新时的安装程序所在机器上生效。它无法阻止开发者提交敏感或不必要的文件。开发者必须使用.gitignore文件，避免将敏感信息纳入代码仓库。; ::

安全性与信任机制

默认情况下，个人配置分发包并未经过签名。这意味着您需要信任：

Git托管平台（GitHub/GitLab等），确保其能提供开发者上传的正确文件；
开发者本身，确保其不会上传恶意代码、智能体技能或定时任务。

分发包中的定时任务不会自动触发——安装程序会输出hermes -p <name> cron list命令，需由您手动启用。而Soul配置文件和智能体技能在您开始与对应配置对话时就会立即生效，因此如果您是从不熟悉的来源安装该配置，建议在首次使用前先查看相关文件。

简单类比：安装分发包就如同安装浏览器插件或VS Code扩展。操作简便但功能强大，关键在于信任来源。对于企业内部使用的自定义分发包，只需使用私有代码仓库及常规的Git认证方式，无需额外配置。

未来版本可能会加入签名功能、包含已确认提交SHA值的锁定文件(.distribution-lock.yaml)，以及可在应用更新前显示差异的--dry-run选项。不过这些功能目前尚未正式推出。

技术实现细节

如需了解实现细节、精确的CLI命令行为及所有参数信息，请参阅个人配置命令参考文档。

简述如下：

install、update、info命令均属于hermes profile命令集的一部分，并非独立的命令结构；
配置清单采用YAML格式，仅要求包含name字段这一最小结构；
安装程序会使用您本地的git工具进行克隆，因此Shell已处理的任何认证方式（如SSH密钥、凭证管理工具）均可无缝使用；
克隆完成后，.git/目录会被删除——安装后的配置并非Git检出结果，从而避免了“误将.env文件提交到分发包的Git历史记录”这类问题；
预留的配置名称（hermes、test、tmp、root、sudo）在安装时会被拒绝，以避免与常见系统命令冲突。

Hermes Agent Docs i18n

sidebar_position: 3