手把手带你跑通 Hermes CLI，零基础也能丝滑配置

本文记录在 Windows 原生 PowerShell 中安装 Hermes Agent 命令行工具（CLI术语解释CLICommand-Line Interface，命令行界面。就是你在终端里输入命令和 Hermes 交互的方式，例如 hermes、hermes model、hermes update。），并配置 DeepSeek + 小米 MiMo 双模型的完整流程。

适用环境：Windows 10/11，直接在 PowerShell 中完成，不需要 WSL2。如果你的电脑上跑的是 Linux 或 macOS，请使用对应的 install.sh。

---

先回答三个问题

1. 什么是 PowerShell？

PowerShell 是 Windows 自带的命令行程序，可以理解成"Windows 里的终端"。下面说的所有命令，都要粘贴到 PowerShell 窗口里执行。

❗ 不要粘贴到浏览器地址栏、文件资源管理器地址栏，或"运行"对话框里。

2. 怎么打开 PowerShell？

1. 按键盘左下角 Windows 键
2. 输入 PowerShell
3. 点击 Windows PowerShell 或 PowerShell

3. 什么时候需要管理员 PowerShell？

• 安装 Hermes：普通 PowerShell 就可以，不需要管理员权限
• 安装 WSL2：才需要以管理员身份运行 PowerShell（右键 → 以管理员身份运行）

---

前置条件

安装器会自动检查并处理以下工具，你也可以提前确认：

工具	最低要求	验证命令
Python	≥ 3.11	python --version
Node.js	≥ 18	node --version
Git	任意版本	git --version
ripgrep	推荐	rg --version
ffmpeg	推荐	ffmpeg -version

💡 安装器会优先复用系统已有的 Python 和 Node.js，不会重复安装。

---

安装 Hermes CLI

一键安装

在 PowerShell 中执行以下命令：

irm https://res1.hermesagent.org.cn/install.ps1 | iex

粘贴小提示

• 现在多数 Windows 终端都支持 Ctrl+V
• 如果不行，也可以直接在窗口里 右键粘贴

🔧 irm = Invoke-RestMethod（下载网页），iex = Invoke-Expression（执行脚本）。这条命令从 Hermes Agent 中文社区维护的国内镜像服务器下载安装器并直接执行，国内可直连，比访问 GitHub 快很多。

安装器会自动完成以下工作

步骤	操作	预期耗时	说明
1	检查 uv 包管理器	即时	用于加速 Python 包安装
2	检查 Python 环境	即时	优先复用系统已有的 ≥ 3.11
3	检查基础工具	即时	Node.js、ripgrep、ffmpeg
4	克隆代码仓库	约 1-2 分钟	从 CNB.cool 镜像下载（~130MB），国内直连
5	创建 Python 虚拟环境	约 30 秒	隔离 Hermes 的 Python 依赖
6	安装核心依赖	约 1-3 分钟	通过清华 PyPI 镜像安装
7	配置命令与目录	即时	加入 PATH，创建 .env、config.yaml
8	同步内置技能	即时	自动同步 72 个内置技能

⚠️ 为提高 Windows 直装速度，安装器默认跳过了浏览器自动化等体积较大的可选组件（受外网下载影响）。Hermes 核心功能不受影响，后续可按需补装。

安装后操作

安装完成后，关闭当前 PowerShell 窗口，重新打开一个（让 PATH 生效），然后运行：

hermes --version

看到类似以下输出即表示安装成功：

Hermes Agent v0.17.0 (2026.6.19) · upstream 44ddc552

🔄 如果 hermes 命令找不到，最常见的解决方法就是——关掉当前 PowerShell 窗口，再开一个新的。

安装后文件在哪里

%LOCALAPPDATA%\hermes\          # 即 C:\Users\<用户名>\AppData\Local\hermes\
├── hermes-agent\                # Hermes 源码仓库
│   └── venv\Scripts\hermes.exe  # Hermes CLI 入口
├── config.yaml                  # 主要配置文件（模型、终端后端等）
├── .env                         # API 密钥等敏感信息（不要分享！）
├── SOUL.md                      # Agent 人格设定（可自行编辑）
├── skills\                      # 技能目录
├── sessions\                    # 会话历史
├── memories\                    # 持久记忆
├── cron\                        # 定时任务
└── logs\                        # 运行日志

关于各文件的详细说明，可参考 官方文档 → 配置。

---

配置模型提供商

Hermes术语解释Hermes Agent开源 AI 智能体框架与产品的正式名称。Hermes Agent 是项目和产品的正式名称。文档、GitHub 仓库、安装命令、社区讨论和搜索结果都统一使用这一写法。 需要至少一个大模型提供商术语解释Provider模型或服务的提供方。LLM Provider 指提供模型 API 的服务商，如 DeepSeek、OpenAI、OpenRouter 等。才能工作。这里我们配置 DeepSeek 作为默认模型，同时配置 小米 MiMo 作为第二个可手动切换的模型。

配置 DeepSeek（默认模型）

💡 DeepSeek 是国内的大模型提供商，注册简单、价格便宜、国内直连不需要翻墙。Hermes 完全兼容 DeepSeek 的 API。

在 PowerShell 中依次执行：

hermes config set model.provider custom
hermes config set model.base_url https://api.deepseek.com/v1
hermes config set model.default deepseek-chat
hermes config set model.api_key sk-你的DeepSeek密钥

各字段说明：

配置项	值	说明
model.provider	custom	使用自定义 OpenAI 兼容端点术语解释OpenAI-compatible指 API 格式与 OpenAI 的 Chat Completions API 兼容的服务。
model.base_url	https://api.deepseek.com/v1	DeepSeek 的 API 地址
model.default	deepseek-chat	默认模型名，指向 DeepSeek 最新版
model.api_key	sk-...	从 platform.deepseek.com → API Keys 获取

❗ 敏感信息提醒：model.api_key 的值会自动保存到 .env 文件（不会出现在 config.yaml 中），.env 文件默认不会被分享或提交到版本控制。

配置小米 MiMo（第二个可切换模型）

💡 小米 MiMo（Xiaomi MiMo）是小米推出的模型服务平台，提供 mimo-v2.5-pro 等模型，支持文本生成、深度思考、函数调用和联网搜索。Hermes 已内置对 MiMo 的支持，provider 名称为 xiaomi。

hermes config set XIAOMI_API_KEY sk-你的MiMo密钥
hermes config set XIAOMI_BASE_URL https://api.xiaomimimo.com/v1

然后编辑 %LOCALAPPDATA%\hermes\config.yaml，在末尾添加模型别名，方便在 /model 菜单中快速切换：

# 模型别名 —— 通过 /model 命令或别名名快速切换
model_aliases:
  deepseek:
    model: deepseek-chat
    provider: custom
    base_url: "https://api.deepseek.com/v1"
  mimo:
    model: mimo-v2.5-pro
    provider: xiaomi
    base_url: "https://api.xiaomimimo.com/v1"

🔑 前往 platform.xiaomimimo.com → API Keys 创建密钥。MiMo 支持按量付费（sk- 开头）和 Token Plan 订阅（tp- 开头）两种方式。

验证配置

运行诊断命令检查两个 provider 是否正常：

hermes doctor

在输出的 API Connectivity 部分关注以下信息：

◆ API Connectivity
  ✓ DeepSeek             # DeepSeek 连通成功
  ✓ xiaomi               (key configured)  # MiMo 密钥已配置

绿色 ✓ = 正常，黄色 ⚠ = 可选组件缺失（不影响核心功能）。如果两个都显示正常，说明模型配置已全部完成。

双模型切换方法

配置完成后，你可以随时在 DeepSeek 和 MiMo 之间切换：

方式一：交互式菜单（推荐）

hermes model

在列表中选择需要的提供商和模型即可。

方式二：切换默认配置

hermes config set model.provider xiaomi    # 切换到 MiMo（mimo-v2.5-pro）
hermes config set model.provider custom    # 切换回 DeepSeek（deepseek-chat）

方式三：单次临时指定（不改变默认配置）

hermes chat --provider xiaomi --model mimo-v2.5-pro
hermes chat --provider custom --model deepseek-chat

使用交互式配置向导（备选）

如果你更习惯问答式配置，也可以运行：

hermes setup

选择 Full setup → 提供商列表中选择 16. DeepSeek → 按提示输入 API Key 和选择模型。

配置文件的优先级

设置按以下顺序解析（高优先级覆盖低优先级）：

1. CLI 参数 — 如 hermes chat --model xxxx（每次调用的覆盖）
2. config.yaml — 主要配置文件（模型、终端后端等非敏感设置）
3. .env — 环境变量文件（API 密钥等敏感信息）
4. 内置默认值 — 硬编码的安全默认值

原则：API 密钥放 .env，其他配置放 config.yaml。hermes config set 命令会自动将值路由到正确的文件。

---

快速参考：完整安装命令

# 1. 安装 Hermes CLI
irm https://res1.hermesagent.org.cn/install.ps1 | iex

# 2. 关闭并重新打开 PowerShell

# 3. 验证安装
hermes --version

# 4. 配置 DeepSeek
hermes config set model.provider custom
hermes config set model.base_url https://api.deepseek.com/v1
hermes config set model.default deepseek-chat
hermes config set model.api_key sk-你的DeepSeek密钥

# 5. 配置小米 MiMo
hermes config set XIAOMI_API_KEY sk-你的MiMo密钥
hermes config set XIAOMI_BASE_URL https://api.xiaomimimo.com/v1

# 6. 验证配置
hermes doctor

# 7. 开始使用
hermes                          # CLI 聊天
hermes --tui                    # 现代 TUI 模式

---

常见问题排查

问题	解决方案
PowerShell 提示"禁止运行脚本"	使用 irm ... | iex 模式，无需修改执行策略
hermes 不是内部或外部命令	关闭并重新打开 PowerShell
安装卡住或超时	重试；安装器支持断点续传
配置文件解析错误	用 UTF-8 无 BOM 格式保存 config.yaml
Config version outdated	运行 hermes doctor --fix
OpenRouter API (not configured)	正常现象，因为用的是 DeepSeek 而非 OpenRouter

Q1: PowerShell 提示"无法加载文件，因为在此系统上禁止运行脚本"

原因：Windows 默认执行策略为 Restricted。

解决：使用 irm ... | iex 模式（下载后通过管道传给 Invoke-Expression）可以正常运行，无需修改执行策略。如果运行的是 .ps1 文件，可以临时绕过：

powershell -ExecutionPolicy Bypass -File 安装脚本.ps1

Q2: hermes 不是内部或外部命令

原因：安装器修改了用户 PATH，但需要重新打开终端才能生效。

解决：关掉当前 PowerShell 窗口，再开一个新的。如果重启后仍然找不到：

# 永久添加到用户 PATH
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$hermesPath = "$env:LOCALAPPDATA\hermes\hermes-agent\venv\Scripts"
if ($userPath -notlike "*$hermesPath*") {
    [Environment]::SetEnvironmentVariable("Path", "$userPath;$hermesPath", "User")
}

Q3: 配置文件解析错误 'utf-8' codec can't decode byte

原因：config.yaml 文件编码不是 UTF-8（可能是 GBK 或混合编码），导致解析失败。Hermes 会自动创建备份文件（.yaml.corrupt.xxx.bak）。

解决：用正确的编码重新保存：

$configPath = "$env:LOCALAPPDATA\hermes\config.yaml"
$content = Get-Content $configPath -Raw
[System.IO.File]::WriteAllText($configPath, $content, [System.Text.UTF8Encoding]::new($false))

Q4: Config version outdated

原因：安装后首次运行时，配置模板版本（v0）低于当前 Hermes 版本所需的版本（如 v32）。

解决：

hermes doctor --fix

Q5: hermes doctor 显示 OpenRouter API (not configured)

原因：DeepSeek 使用 custom provider 直接调用，不走 OpenRouter 中转。

解决：无需处理。只要输出中有 ✓ DeepSeek 即表示模型配置正常。

---

让你的 Agent 自动完成配置

如果你电脑上已经有其他 Agent术语解释Agent具备自主性、能调用工具以完成目标的 AI 程序。Agent 是一种基于大语言模型的智能程序，能够感知环境、做出决策、调用工具执行操作，并自主推进任务。 了（如 Claude Code、Trae、Cursor、Qoder 等），可以让它按照本文档的步骤自动帮你完成安装和配置。

方式一（最简单）：把本文档的文件路径或链接发给你的 Agent，让它自己阅读并执行。

方式二（更精准，推荐）：直接把下面这段话复制给你的 Agent：

请根据这篇 Hermes CLI 安装指南帮我完成安装和配置：

文档路径：D:\Hermes CLI Windows 安装与模型配置指南.md

需要完成的内容：
1. 安装 Hermes CLI（使用 irm ... | iex 社区镜像）
2. 配置 DeepSeek 为默认模型（provider=custom，base_url=https://api.deepseek.com/v1）
3. 配置小米 MiMo 作为第二个可切换模型（provider=xiaomi，base_url=https://api.xiaomimimo.com/v1）
4. 用 hermes doctor 验证配置
5. 启动 hermes 测试聊天

API Key 我会在需要时提供，或你按文档中的占位符提示我填入。

💡 如果你的 Agent 支持 MCP术语解释MCPModel Context Protocol，Anthropic 提出的开放标准，用于将 AI 应用连接到外部数据源与工具。，也可以先接入 Hermes 中文文档 MCP Server（https://mcp.hermesagent.org.cn/v1），让 Agent 直接检索最新文档来指导安装。

---

参考与延伸阅读

如果你对 AI Agent 的搭建和配置感兴趣，欢迎关注我的 CSDN 专栏，更多实战经验持续更新中：

文章	简介
从小白到大神：MiMo Code 配置与使用"零基础"通关秘籍	小米 MiMo Code 终端 AI 编程助手的完整安装、配置、使用教程（含 Web 图形界面）
VS Code 安装 Claude Code 并接入 DeepSeek V4 Model	在 VS Code 中配置 Claude Code 并接入 DeepSeek V4 模型的完整流程
使用 Reasonix 接入 DeepSeek：从零搭建你的 AI 编程助手	基于 Reasonix 框架从零搭建 AI 编程助手的实战教程