Nix & NixOS 部署

Hermes Agent 隨附一個 Nix flake，提供三個層級的集成：

層級	適用對象	你將獲得
`nix run` / `nix profile install`	任何 Nix 用戶（macOS、Linux）	包含所有依賴的預構建二進制文件 —— 然後使用標準 CLI 工作流
NixOS 模塊（原生）	NixOS 服務器部署	聲明式配置、強化的 systemd 服務、受管理的密鑰
NixOS 模塊（容器）	需要自我修改的 Agent	上述所有功能，外加一個持久化的 Ubuntu 容器，Agent 可在其中執行 `apt`/`pip`/`npm install`

與標準安裝的不同之處

curl | bash 安裝程序自行管理 Python、Node 和依賴項。而 Nix flake 替代了所有這些內容 —— 每個 Python 依賴都是由 uv2nix 構建的 Nix 衍生品，運行時工具（Node.js、git、ripgrep、ffmpeg）也被封裝進二進制文件的 PATH 中。運行時不再需要 pip，無需虛擬環境激活，也不再需要 npm install。

對於非 NixOS 用戶，這僅改變了安裝步驟。之後的所有操作（hermes setup、hermes gateway install、配置編輯）與標準安裝完全相同。

對於 NixOS 模塊用戶，整個生命週期完全不同：配置位於 configuration.nix，密鑰通過 sops-nix/agenix 管理，服務為 systemd 單元，CLI 配置命令被禁用。你管理 hermes 的方式與管理其他任何 NixOS 服務一致。

先決條件

啟用 flakes 的 Nix —— 推薦使用 Determinate Nix（默認啟用 flakes）
你希望使用的服務的 API 密鑰（至少需要一個 OpenRouter 或 Anthropic 密鑰）

快速入門（任何 Nix 用戶）

無需克隆。Nix 會自動獲取、構建並運行所有內容：

# 直接運行（首次使用時構建，之後緩存）
nix run github:NousResearch/hermes-agent -- 設置
nix run github:NousResearch/hermes-agent -- 聊天

# 或者持久安裝
nix profile install github:NousResearch/hermes-agent
hermes setup
hermes chat

nix profile install 之後，hermes、hermes-agent 和 hermes-acp 將出現在你的 PATH 中。從這一步開始，工作流與標準安裝完全相同 —— hermes setup 會引導你完成提供者選擇，hermes gateway install 會設置 launchd（macOS）或 systemd 用戶服務，配置文件位於 ~/.hermes/。

從本地克隆構建

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
nix build
./result/bin/hermes setup

NixOS 模塊

flake 導出了 nixosModules.default —— 一個完整的 NixOS 服務模塊，聲明式地管理用戶創建、目錄、配置生成、密鑰、文檔和服務生命週期。

備註

此模塊需要 NixOS。對於非 NixOS 系統（macOS、其他 Linux 發行版），請使用 nix profile install 和上述標準 CLI 工作流。

添加 Flake 輸入

# /etc/nixos/flake.nix（或您的系統碎片）
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hermes-agent.url = "github:NousResearch/hermes-agent";
  };

  outputs = { nixpkgs, hermes-agent, ... }: {
    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        hermes-agent.nixosModules.default
        ./configuration.nix
      ];
    };
  };
}

最小配置

# configuration.nix
{ config, ... }: {
  services.hermes-agent = {
    enable = true;
    settings.model.default = "anthropic/claude-sonnet-4";
    environmentFiles = [ config.sops.secrets."hermes-env".path ];
    addToSystemPackages = true;
  };
}

僅此而已。nixos-rebuild switch 會創建 hermes 用戶，生成 config.yaml，連接密鑰，並啟動網關 —— 一個長時間運行的服務，將 Agent 連接到消息平臺（Telegram、Discord 等）並監聽傳入消息。

密鑰是必需的

上面的 environmentFiles 行假設你已配置 sops-nix 或 agenix。該文件應至少包含一個 LLM 提供商密鑰（例如 OPENROUTER_API_KEY=sk-or-...）。完整設置請參見密鑰管理。如果你尚未配置密鑰管理器，可以先使用普通文件作為起點 —— 但請確保它不可被世界讀取：

echo "OPENROUTER_API_KEY=sk-or-your-key" | sudo install -m 0600 -o hermes /dev/stdin /var/lib/hermes/env

services.hermes-agent.environmentFiles = [ "/var/lib/hermes/env" ];

addToSystemPackages

設置 addToSystemPackages = true 有兩點作用：將 hermes CLI 添加到系統 PATH 並且全局設置 HERMES_HOME，使交互式 CLI 與網關服務共享狀態（會話、技能、cron）。若不設置，你在 shell 中運行 hermes 會創建一個獨立的 ~/.hermes/ 目錄。

驗證是否正常工作

nixos-rebuild switch 之後，檢查服務是否正在運行：

# 檢查服務狀態
systemctl status hermes-agent

# 查看日誌（按 Ctrl+C 停止）
journalctl -u hermes-agent -f

# 如果 addToSystemPackages 為 true，則測試 CLI
hermes version
hermes config       # 顯示生成的配置

選擇部署模式

該模塊支持兩種模式，由 container.enable 控制：

	原生（默認）	容器
運行方式	主機上的強化 systemd 服務	持久化的 Ubuntu 容器，`/nix/store` 綁定掛載
安全性	`NoNewPrivileges`、`ProtectSystem=strict`、`PrivateTmp`	容器隔離，以非特權用戶運行
Agent 能否在運行時安裝包	否 —— 僅限 Nix 提供的 PATH 中的工具	是 —— `apt`、`pip`、`npm` 安裝在重啟後仍持久存在
配置面	相同	相同
何時選擇	標準部署、最大安全性、可復現性	Agent 需要運行時包安裝、可變環境、實驗性工具

要啟用容器模式，只需添加一行：

{
  services.hermes-agent = {
    enable = true;
    container.enable = true;
    # ...配置的其餘部分是相同的
  };
}

信息

容器模式會通過 mkDefault 自動啟用 virtualisation.docker.enable。如果你使用 Podman 而非 Docker，請設置 container.backend = "podman" 並將 virtualisation.docker.enable = false。

配置

聲明式設置

settings 選項接受一個任意的 attrset，該 attrset 會被渲染為 config.yaml。它支持通過 lib.recursiveUpdate 在多個模塊定義之間進行深度合併，因此你可以將配置拆分到多個文件中：

# base.nix
services.hermes-agent.settings = {
  model.default = "anthropic/claude-sonnet-4";
  toolsets = [ "all" ];
  terminal = { backend = "local"; timeout = 180; };
};

# personality.nix
services.hermes-agent.settings = {
  display = { compact = false; personality = "kawaii"; };
  memory = { memory_enabled = true; user_profile_enabled = true; };
};

兩者在評估時都會被深度合併。Nix 聲明的鍵始終優先於磁盤上已存在的 config.yaml 中的鍵，但 Nix 不會觸及的用戶添加的鍵將被保留。這意味著，如果 Agent 或手動編輯添加了如 skills.disabled 或 streaming.enabled 這樣的鍵，它們在執行 nixos-rebuild switch 後依然會保留。

模型命名

settings.model.default 使用的是你的提供商所期望的模型標識符。使用 OpenRouter（默認）時，這些標識符看起來像 "anthropic/claude-sonnet-4" 或 "google/gemini-3-flash"。如果你直接使用提供商（如 Anthropic、OpenAI），請將 settings.model.base_url 設置為指向其 API，並使用其原生模型 ID（例如 "claude-sonnet-4-20250514"）。當未設置 base_url 時，Hermes 默認使用 OpenRouter。

查看可用的配置鍵

運行 nix build .#configKeys && cat result 可以查看從 Python 的 DEFAULT_CONFIG 中提取的所有葉級配置鍵。你可以將現有的 config.yaml 粘貼到 settings attrset 中——其結構完全一一對應。

完整示例：所有常見自定義設置

{ config, ... }: {
  services.hermes-agent = {
    enable = true;
    container.enable = true;

    # ── Model ──────────────────────────────────────────────────────────
    settings = {
      model = {
        base_url = "https://openrouter.ai/api/v1";
        default = "anthropic/claude-opus-4.6";
      };
      toolsets = [ "all" ];
      max_turns = 100;
      terminal = { backend = "local"; cwd = "."; timeout = 180; };
      compression = {
        enabled = true;
        threshold = 0.85;
        summary_model = "google/gemini-3-flash-preview";
      };
      memory = { memory_enabled = true; user_profile_enabled = true; };
      display = { compact = false; personality = "kawaii"; };
      agent = { max_turns = 60; verbose = false; };
    };

    # ── 秘密──────────────────────────────────────────────────────────
    environmentFiles = [ config.sops.secrets."hermes-env".path ];

    # ── 文件──────────────────────────────────────────────────────
    documents = {
      "SOUL.md" = builtins.readFile /home/user/.hermes/SOUL.md;
      "USER.md" = ./documents/USER.md;
    };

    # ── MCP 服務器 ────────────────────────────────────────────────────
    mcpServers.filesystem = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-filesystem" "/data/workspace" ];
    };

    # ── 容器選項──────────────────────────────────────────────
    container = {
      image = "ubuntu:24.04";
      backend = "docker";
      extraVolumes = [ "/home/user/projects:/projects:rw" ];
      extraOptions = [ "--gpus" "all" ];
    };

    # ── 服務調整──────────────────────────────────────────────────
    addToSystemPackages = true;
    extraArgs = [ "--verbose" ];
    restart = "always";
    restartSec = 5;
  };
}

逃生通道：使用你自己的配置

如果你更願意完全在 Nix 之外管理 config.yaml，請使用 configFile：

services.hermes-agent.configFile = /etc/hermes/config.yaml;

這將完全繞過 settings —— 不進行合併，也不生成配置。該文件會在每次激活時原封不動地複製到 $HERMES_HOME/config.yaml。

自定義速查表

Nix 用戶最常需要自定義的快速參考：

我想...	選項	示例
更改 LLM 模型	`settings.model.default`	`"anthropic/claude-sonnet-4"`
使用不同的提供商端點	`settings.model.base_url`	`"https://openrouter.ai/api/v1"`
添加 API 密鑰	`environmentFiles`	`[ config.sops.secrets."hermes-env".path ]`
給 Agent 賦予個性	`documents."SOUL.md"`	`builtins.readFile ./my-soul.md`
添加 MCP 工具服務器	`mcpServers.<name>`	參見 MCP 服務器
將主機目錄掛載到容器中	`container.extraVolumes`	`[ "/data:/data:rw" ]`
向容器傳遞 GPU 訪問權限	`container.extraOptions`	`[ "--gpus" "all" ]`
使用 Podman 而非 Docker	`container.backend`	`"podman"`
向服務 PATH 添加工具（僅原生）	`extraPackages`	`[ pkgs.pandoc pkgs.imagemagick ]`
使用自定義基礎鏡像	`container.image`	`"ubuntu:24.04"`
覆蓋 hermes 包	`package`	`inputs.hermes-agent.packages.${system}.default.override { ... }`
更改狀態目錄	`stateDir`	`"/opt/hermes"`
設置 Agent 的工作目錄	`workingDirectory`	`"/home/user/projects"`

密鑰管理

永遠不要將 API 密鑰放入 settings 或 environment

Nix 表達式中的值最終會出現在 /nix/store 中，而該目錄對世界可讀。請始終使用 environmentFiles 配合密鑰管理器。

environment（非敏感變量）和 environmentFiles（密鑰文件）會在激活時（nixos-rebuild switch）合併到 $HERMES_HOME/.env。Hermes 在每次啟動時都會讀取該文件，因此更改只需通過 systemctl restart hermes-agent 即可生效——無需重建容器。

sops-nix

{
  sops = {
    defaultSopsFile = ./secrets/hermes.yaml;
    age.keyFile = "/home/user/.config/sops/age/keys.txt";
    secrets."hermes-env" = { format = "yaml"; };
  };

  services.hermes-agent.environmentFiles = [
    config.sops.secrets."hermes-env".path
  ];
}

密鑰文件包含鍵值對：

# Secrets/hermes.yaml（使用 sops 加密）
hermes-env: |
    OPENROUTER_API_KEY=sk-or-...
    TELEGRAM_BOT_TOKEN=123456:ABC...
    ANTHROPIC_API_KEY=sk-ant-...

agenix

{
  age.secrets.hermes-env.file = ./secrets/hermes-env.age;

  services.hermes-agent.environmentFiles = [
    config.age.secrets.hermes-env.path
  ];
}

OAuth / 認證種子

對於需要 OAuth 的平臺（如 Discord），請使用 authFile 在首次部署時注入憑據：

{
  services.hermes-agent = {
    authFile = config.sops.secrets."hermes/auth.json".path;
    # authFileForceOverwrite = true；  # 每次激活時覆蓋
  };
}

該文件僅在 auth.json 不存在時才會被複制（除非設置 authFileForceOverwrite = true）。運行時的 OAuth 令牌刷新會寫入狀態目錄，並在重建之間保留。

文檔

documents 選項將文件安裝到 Agent 的工作目錄中（即 workingDirectory，Agent 將其作為工作區讀取）。Hermes 會按約定查找特定文件名：

SOUL.md —— Agent 的系統提示 / 個性。Hermes 在啟動時讀取此文件，並將其作為持久化指令，影響其在所有對話中的行為。
USER.md —— Agent 交互的用戶的相關上下文。
你在此處放置的任何其他文件都會被 Agent 作為工作區文件可見。

{
  services.hermes-agent.documents = {
    "SOUL.md" = ''
      You are a helpful research assistant specializing in NixOS packaging.
      Always cite sources and prefer reproducible solutions.
    '';
    "USER.md" = ./documents/USER.md;  # 路徑參考，從 Nix 商店複製
  };
}

值可以是內聯字符串或路徑引用。每次執行 nixos-rebuild switch 時都會安裝這些文件。

MCP 服務器

mcpServers 選項聲明式地配置 MCP（模型上下文協議）服務器。每個服務器使用 stdio（本地命令）或 HTTP（遠程 URL）傳輸。

Stdio 傳輸（本地服務器）

{
  services.hermes-agent.mcpServers = {
    filesystem = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-filesystem" "/data/workspace" ];
    };
    github = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-github" ];
      env.GITHUB_PERSONAL_ACCESS_TOKEN = "\${GITHUB_TOKEN}"; # 從 `.env` 解析
    };
  };
}

提示

env 值中的環境變量會在運行時從 $HERMES_HOME/.env 解析。請使用 environmentFiles 注入密鑰——永遠不要將令牌直接寫入 Nix 配置。

HTTP 傳輸（遠程服務器）

{
  services.hermes-agent.mcpServers.remote-api = {
    url = "https://mcp.example.com/v1/mcp";
    headers.Authorization = "Bearer \${MCP_REMOTE_API_KEY}";
    timeout = 180;
  };
}

使用 OAuth 的 HTTP 傳輸

對於使用 OAuth 2.1 的服務器，請設置 auth = "oauth"。Hermes 實現了完整的 PKCE 流程 —— 元數據發現、動態客戶端註冊、令牌交換以及自動刷新。

{
  services.hermes-agent.mcpServers.my-oauth-server = {
    url = "https://mcp.example.com/mcp";
    auth = "oauth";
  };
}

令牌存儲在 $HERMES_HOME/mcp-tokens/<server-name>.json 中，並在重啟和重建之間持久化。

無頭服務器上的初始 OAuth 授權

首次 OAuth 授權需要基於瀏覽器的同意流程。在無頭部署中，Hermes 會將授權 URL 輸出到 stdout/logs，而不是打開瀏覽器。

選項 A：交互式引導 —— 通過 docker exec（容器）或 sudo -u hermes（原生）運行一次流程：

# 容器模式
docker exec -it hermes-agent \
  hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth

# 本機模式
sudo -u hermes HERMES_HOME=/var/lib/hermes/.hermes \
  hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth

容器使用 --network=host，因此 127.0.0.1 上的 OAuth 回調監聽器可從主機瀏覽器訪問。

選項 B：預先填充令牌 —— 在工作站上完成流程後，複製令牌：

hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth
scp ~/.hermes/mcp-tokens/my-oauth-server{,.client}.json \
    server:/var/lib/hermes/.hermes/mcp-tokens/
# 確保：chown hermes:hermes，chmod 0600

採樣（由服務器發起的 LLM 請求）

某些 MCP 服務器可以向 Agent 請求 LLM 完成：

{
  services.hermes-agent.mcpServers.analysis = {
    command = "npx";
    args = [ "-y" "analysis-server" ];
    sampling = {
      enabled = true;
      model = "google/gemini-3-flash";
      max_tokens_cap = 4096;
      timeout = 30;
      max_rpm = 10;
    };
  };
}

管理模式

當通過 NixOS 模塊運行 hermes 時，以下 CLI 命令將被阻止，並返回描述性錯誤，提示您前往 configuration.nix：

被阻止的命令	原因
`hermes setup`	配置是聲明式的 —— 編輯 Nix 配置中的 `settings`
`hermes config edit`	配置由 `settings` 生成
`hermes config set <key> <value>`	配置由 `settings` 生成
`hermes gateway install`	systemd 服務由 NixOS 管理
`hermes gateway uninstall`	systemd 服務由 NixOS 管理

這可防止 Nix 聲明的內容與磁盤上的實際內容之間出現偏差。檢測機制使用兩個信號：

HERMES_MANAGED=true 環境變量 —— 由 systemd 服務設置，對網關進程可見
.managed 標記文件 在 HERMES_HOME 中 —— 由激活腳本設置，對交互式 shell 可見（例如 docker exec -it hermes-agent hermes config set ... 也被阻止）

如需更改配置，請編輯您的 Nix 配置並運行 sudo nixos-rebuild switch。

容器架構

信息

本節僅適用於使用 container.enable = true 的情況。原生模式部署請跳過。

啟用容器模式後，Hermes 在一個持久的 Ubuntu 容器中運行，Nix 構建的二進制文件以只讀方式從主機綁定掛載：

Host                                    Container
────                                    ─────────
/nix/store/...-hermes-agent-0.1.0  ──►  /nix/store/... (ro)
/var/lib/hermes/                    ──►  /data/          (rw)
  ├── current-package -> /nix/store/...    (symlink, updated each rebuild)
  ├── .gc-root -> /nix/store/...           (prevents nix-collect-garbage)
  ├── .container-identity                  (sha256 hash, triggers recreation)
  ├── .hermes/                             (HERMES_HOME)
  │   ├── .env                             (merged from environment + environmentFiles)
  │   ├── config.yaml                      (Nix-generated, deep-merged by activation)
  │   ├── .managed                         (marker file)
  │   ├── state.db, sessions/, memories/   (runtime state)
  │   └── mcp-tokens/                      (OAuth tokens for MCP servers)
  ├── home/                                ──►  /home/hermes    (rw)
  └── workspace/                           (MESSAGING_CWD)
      ├── SOUL.md                          (from documents option)
      └── (agent-created files)

Container writable layer (apt/pip/npm):   /usr, /usr/local, /tmp

Nix 構建的二進制文件能在 Ubuntu 容器中運行，因為 /nix/store 被綁定掛載 —— 它自帶解釋器和所有依賴項，因此不依賴容器的系統庫。容器入口點通過 current-package 符號鏈接解析：/data/current-package/bin/hermes gateway run --replace。在 nixos-rebuild switch 時，僅更新符號鏈接 —— 容器保持運行。

什麼在什麼之間持久化

事件	容器是否重新創建？	`/data`（狀態）	`/home/hermes`	可寫層（`apt`/`pip`/`npm`）
`systemctl restart hermes-agent`	否	持久化	持久化	持久化
`nixos-rebuild switch`（代碼變更）	否（僅更新符號鏈接）	持久化	持久化	持久化
主機重啟	否	持久化	持久化	持久化
`nix-collect-garbage`	否（GC 根）	持久化	持久化	持久化
鏡像變更（`container.image`）	是	持久化	持久化	丟失
卷/選項變更	是	持久化	持久化	丟失
`environment`/`environmentFiles` 變更	否	持久化	持久化	持久化

容器僅在它的身份哈希發生變化時才會被重新創建。該哈希涵蓋：模式版本、鏡像、extraVolumes、extraOptions 和入口腳本。對環境變量、設置、文檔或 hermes 包本身的更改不會觸發重建。

可寫層丟失

當身份哈希發生變化時（鏡像升級、新增卷、新增容器選項），容器會被銷燬並從 container.image 的新鏡像中重新創建。可寫層中的任何 apt install、pip install 或 npm install 包都將丟失。/data 和 /home/hermes 中的狀態會被保留（這些是綁定掛載）。

如果 Agent 依賴特定包，建議將其打包進自定義鏡像（container.image = "my-registry/hermes-base:latest"）或在 Agent 的 SOUL.md 中編寫安裝腳本。

GC 根保護

preStart 腳本在 ${stateDir}/.gc-root 創建一個 GC 根，指向當前的 hermes 包。這可防止 nix-collect-garbage 刪除正在運行的二進制文件。如果 GC 根意外損壞，重啟服務將重新創建它。

開發

開發 Shell

flake 提供了一個開發 shell，包含 Python 3.11、uv、Node.js 和所有運行時工具：

cd hermes-agent
nix develop

# 殼牌提供：
#   - Python 3.11 + uv（首次進入時安裝到 .venv 中）
#   - Node.js 20、ripgrep、git、openssh、ffmpeg 在 PATH 上
#   - 標記文件優化：如果 deps 沒有改變，重新進入幾乎是即時的

hermes setup
hermes chat

direnv（推薦）

包含的 .envrc 會自動激活開發 shell：

cd hermes-agent
direnv allow    # 一度
# 後續條目幾乎是即時的（標記文件跳過 dep 安裝）

Flake 檢查

flake 包含構建時驗證，會在 CI 和本地運行：

# 運行所有檢查
nix flake check

# 個人支票
nix build .#checks.x86_64-linux.package-contents   # 二進制文件存在+版本
nix build .#checks.x86_64-linux.entry-points-sync  # pyproject.toml ↔ Nix 包同步
nix build .#checks.x86_64-linux.cli-commands        # gateway/config 子命令
nix build .#checks.x86_64-linux.managed-guard       # HERMES_MANAGED 阻止突變
nix build .#checks.x86_64-linux.bundled-skills      # skills 存在於包裝中
nix build .#checks.x86_64-linux.config-roundtrip    # 合併腳本保留用戶密鑰

每個檢查項驗證的內容

檢查項	驗證內容
`package-contents`	`hermes` 和 `hermes-agent` 二進制文件存在，且 `hermes version` 命令可執行
`entry-points-sync`	`pyproject.toml` 中的每個 `[project.scripts]` 條目在 Nix 包中都有對應的封裝二進制文件
`cli-commands`	`hermes --help` 正確暴露 `gateway` 和 `config` 子命令
`managed-guard`	`HERMES_MANAGED=true hermes config set ...` 命令會打印 NixOS 錯誤信息
`bundled-skills`	技能目錄存在，包含 SKILL.md 文件，且 `HERMES_BUNDLED_SKILLS` 在包裝器中已設置
`config-roundtrip`	7 種合併場景：全新安裝、Nix 覆蓋、用戶密鑰保留、混合合併、MCP 增量合併、嵌套深度合併、冪等性

選項參考

核心配置

選項	類型	默認值	描述
`enable`	`bool`	`false`	啟用 hermes-agent 服務
`package`	`package`	`hermes-agent`	使用的 hermes-agent 包
`user`	`str`	`"hermes"`	系統用戶
`group`	`str`	`"hermes"`	系統組
`createUser`	`bool`	`true`	自動創建用戶/組
`stateDir`	`str`	`"/var/lib/hermes"`	狀態目錄（`HERMES_HOME` 的父目錄）
`workingDirectory`	`str`	`"${stateDir}/workspace"`	Agent 工作目錄（`MESSAGING_CWD`）
`addToSystemPackages`	`bool`	`false`	將 `hermes` CLI 添加到系統 PATH，並全局設置 `HERMES_HOME`

配置

選項	類型	默認值	描述
`settings`	`attrs`（深度合併）	`{}`	以 `config.yaml` 形式渲染的聲明式配置。支持任意嵌套；多個定義通過 `lib.recursiveUpdate` 合併
`configFile`	`null` 或 `path`	`null`	指向現有 `config.yaml` 的路徑。若設置，則完全覆蓋 `settings`

密鑰與環境

選項	類型	默認值	描述
`environmentFiles`	`listOf str`	`[]`	包含密鑰的環境文件路徑。在激活時合併到 `$HERMES_HOME/.env`
`environment`	`attrsOf str`	`{}`	非密鑰環境變量。可見於 Nix 存儲 —— 請勿在此處放置密鑰
`authFile`	`null` 或 `path`	`null`	OAuth 憑據種子文件。僅在首次部署時複製
`authFileForceOverwrite`	`bool`	`false`	在激活時始終從 `authFile` 覆蓋 `auth.json`

文檔

選項	類型	默認值	描述
`documents`	`attrsOf (either str path)`	`{}`	工作區文件。鍵為文件名，值為內聯字符串或路徑。在激活時安裝到 `workingDirectory`

MCP 服務器

選項	類型	默認值	描述
`mcpServers`	`attrsOf submodule`	`{}`	MCP 服務器定義，合併到 `settings.mcp_servers`
`mcpServers.<name>.command`	`null` 或 `str`	`null`	服務器命令（標準輸入輸出傳輸）
`mcpServers.<name>.args`	`listOf str`	`[]`	命令參數
`mcpServers.<name>.env`	`attrsOf str`	`{}`	服務器進程的環境變量
`mcpServers.<name>.url`	`null` 或 `str`	`null`	服務器端點 URL（HTTP/StreamableHTTP 傳輸）
`mcpServers.<name>.headers`	`attrsOf str`	`{}`	HTTP 頭信息，例如 `Authorization`
`mcpServers.<name>.auth`	`null` 或 `"oauth"`	`null`	認證方式。`"oauth"` 啟用 OAuth 2.1 PKCE
`mcpServers.<name>.enabled`	`bool`	`true`	啟用或禁用此服務器
`mcpServers.<name>.timeout`	`null` 或 `int`	`null`	工具調用超時時間（秒），默認為 120
`mcpServers.<name>.connect_timeout`	`null` 或 `int`	`null`	連接超時時間（秒），默認為 60
`mcpServers.<name>.tools`	`null` 或 `submodule`	`null`	工具過濾配置（`include`/`exclude` 列表）
`mcpServers.<name>.sampling`	`null` 或 `submodule`	`null`	服務器發起的 LLM 請求的採樣配置

服務行為

選項	類型	默認值	描述
`extraArgs`	`listOf str`	`[]`	傳遞給 `hermes gateway` 的額外參數
`extraPackages`	`listOf package`	`[]`	服務 PATH 上的額外包（僅原生模式）
`restart`	`str`	`"always"`	systemd `Restart=` 策略
`restartSec`	`int`	`5`	systemd `RestartSec=` 值

容器

選項	類型	默認值	描述
`container.enable`	`bool`	`false`	啟用 OCI 容器模式
`container.backend`	`enum ["docker" "podman"]`	`"docker"`	容器運行時
`container.image`	`str`	`"ubuntu:24.04"`	基礎鏡像（運行時拉取）
`container.extraVolumes`	`listOf str`	`[]`	額外的卷掛載（`host:container:mode` 格式）
`container.extraOptions`	`listOf str`	`[]`	傳遞給 `docker create` 的額外參數

目錄結構

原生模式

/var/lib/hermes/                     # stateDir（由 hermes:hermes、0750 擁有）
├── .hermes/                         # HERMES_HOME
│   ├── config.yaml                  # Nix 生成（深度合併每個重建）
│   ├── .managed                     # 標記：CLI 配置突變被阻止
│   ├── .env                         # 由環境 + 環境文件合併
│   ├── auth.json                    # OAuth 憑證（種子，然後自我管理）
│   ├── gateway.pid
│   ├── state.db
│   ├── mcp-tokens/                  # OAuth tokens 適用於 MCP 服務器
│   ├── sessions/
│   ├── memories/
│   ├── skills/
│   ├── cron/
│   └── logs/
├── home/                            # Agent HOME
└── workspace/                       # MESSAGING_CWD
    ├── SOUL.md                      # 從文檔選項
    └── (agent-created files)

容器模式

相同佈局，掛載至容器中：

容器路徑	主機路徑	模式	說明
`/nix/store`	`/nix/store`	`ro`	Hermes 二進制文件 + 所有 Nix 依賴
`/data`	`/var/lib/hermes`	`rw`	所有狀態、配置、工作區
`/home/hermes`	`${stateDir}/home`	`rw`	持久化 Agent 主目錄 — `pip install --user`、工具緩存
`/usr`, `/usr/local`, `/tmp`	(可寫層)	`rw`	`apt`/`pip`/`npm` 安裝 — 重啟後仍保留，重建容器時丟失

更新

# 更新 flake 輸入
nix flake update hermes-agent --flake /etc/nixos

# 重建
sudo nixos-rebuild switch

在容器模式下，current-package 符號鏈接會被更新，Agent 在重啟時會自動加載新二進制文件。無需重建容器，也不會丟失已安裝的包。

故障排除

Podman 用戶

下面所有的 docker 命令在 podman 中使用方式相同。如果設置了 container.backend = "podman"，請相應替換。

服務日誌

# 錯誤 500（服務器錯誤）！！1500。這是一個錯誤。出現錯誤。請稍後重試。我們只知道這些。
journalctl -u hermes-agent -f

# 容器模式：也可直接使用
docker logs -f hermes-agent

容器檢查

systemctl status hermes-agent
docker ps -a --filter name=hermes-agent
docker inspect hermes-agent --format='{{.State.Status}}'
docker exec -it hermes-agent bash
docker exec hermes-agent readlink /data/current-package
docker exec hermes-agent cat /data/.container-identity

強制重建容器

如果需要重置可寫層（全新 Ubuntu 環境）：

sudo systemctl stop hermes-agent
docker rm -f hermes-agent
sudo rm /var/lib/hermes/.container-identity
sudo systemctl start hermes-agent

驗證密鑰已加載

如果 Agent 啟動但無法與 LLM 提供商認證，請檢查 .env 文件是否正確合併：

# 本機模式
sudo -u hermes cat /var/lib/hermes/.hermes/.env

# 容器模式
docker exec hermes-agent cat /data/.hermes/.env

GC 根驗證

nix-store --query --roots $(docker exec hermes-agent readlink /data/current-package)

常見問題

現象	原因	解決方法
`Cannot save configuration: managed by NixOS`	CLI 保護機制啟用	編輯 `configuration.nix` 並執行 `nixos-rebuild switch`
容器意外重建	`extraVolumes`、`extraOptions` 或 `image` 發生變化	正常行為 — 可寫層重置。需重新安裝包或使用自定義鏡像
`hermes version` 顯示舊版本	容器未重啟	執行 `systemctl restart hermes-agent`
`/var/lib/hermes` 權限拒絕	狀態目錄權限為 `0750 hermes:hermes`	使用 `docker exec` 或 `sudo -u hermes`
`nix-collect-garbage` 刪除了 hermes	GC 根缺失	重啟服務（preStart 會重新創建 GC 根）

先決條件​

快速入門（任何 Nix 用戶）​

NixOS 模塊​

添加 Flake 輸入​

最小配置​

驗證是否正常工作​

選擇部署模式​

配置​

聲明式設置​

逃生通道：使用你自己的配置​

自定義速查表​

密鑰管理​

sops-nix​

agenix​

OAuth / 認證種子​

文檔​

MCP 服務器​

Stdio 傳輸（本地服務器）​

HTTP 傳輸（遠程服務器）​

使用 OAuth 的 HTTP 傳輸​

採樣（由服務器發起的 LLM 請求）​

管理模式​

容器架構​

什麼在什麼之間持久化​

GC 根保護​

開發​

開發 Shell​

direnv（推薦）​

Flake 檢查​

選項參考​

核心配置​

配置​

密鑰與環境​

文檔​

MCP 服務器​

服務行為​

容器​

目錄結構​

原生模式​

容器模式​

更新​

故障排除​

服務日誌​

容器檢查​

強制重建容器​

驗證密鑰已加載​

GC 根驗證​

常見問題​

先決條件

快速入門（任何 Nix 用戶）

NixOS 模塊

添加 Flake 輸入

最小配置

驗證是否正常工作

選擇部署模式

配置

聲明式設置

逃生通道：使用你自己的配置

自定義速查表

密鑰管理

sops-nix

agenix

OAuth / 認證種子

文檔

MCP 服務器

Stdio 傳輸（本地服務器）

HTTP 傳輸（遠程服務器）

使用 OAuth 的 HTTP 傳輸

採樣（由服務器發起的 LLM 請求）

管理模式

容器架構

什麼在什麼之間持久化

GC 根保護

開發

開發 Shell

direnv（推薦）

Flake 檢查

選項參考

核心配置

配置

密鑰與環境

文檔

MCP 服務器

服務行為

容器

目錄結構

原生模式

容器模式

更新

故障排除

服務日誌

容器檢查

強制重建容器

驗證密鑰已加載

GC 根驗證

常見問題