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

手把手带你跑通 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 和 Node.js，不会重复安装。

安装 Hermes CLI

一键安装

在 PowerShell 中执行以下命令：

irmhttps://res1.hermesagent.org.cn/install.ps1|iex

粘贴小提示

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

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

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

⚠️ 为提高 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 configsetmodel.provider custom hermes configsetmodel.base_url https://api.deepseek.com/v1 hermes configsetmodel.default deepseek-chat hermes configsetmodel.api_key sk-你的DeepSeek密钥

各字段说明：

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

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

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

hermes configsetXIAOMI_API_KEY sk-你的MiMo密钥 hermes configsetXIAOMI_BASE_URL https://api.xiaomimimo.com/v1

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

# 模型别名 —— 通过 /model 命令或别名名快速切换model_aliases:deepseek:model:deepseek-chatprovider:custombase_url:"https://api.deepseek.com/v1"mimo:model:mimo-v2.5-proprovider:xiaomibase_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 configsetmodel.provider xiaomi# 切换到 MiMo（mimo-v2.5-pro）hermes configsetmodel.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 CLIirmhttps://res1.hermesagent.org.cn/install.ps1|iex# 2. 关闭并重新打开 PowerShell# 3. 验证安装hermes--version# 4. 配置 DeepSeekhermes configsetmodel.provider custom hermes configsetmodel.base_url https://api.deepseek.com/v1 hermes configsetmodel.default deepseek-chat hermes configsetmodel.api_key sk-你的DeepSeek密钥# 5. 配置小米 MiMohermes configsetXIAOMI_API_KEY sk-你的MiMo密钥 hermes configsetXIAOMI_BASE_URL https://api.xiaomimimo.com/v1# 6. 验证配置hermes doctor# 7. 开始使用hermes# CLI 聊天hermes--tui# 现代 TUI 模式

常见问题排查

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 专栏，更多实战经验持续更新中：