Hermes Agent 接入 MiniMax 国内站：Key 申请、MiniMax (China) 选项与 M2.7 验收

为什么国内用户优先接 MiniMax

国内网络装 Hermes Agent 的两个真痛点是 GitHub 慢和 OpenRouter 要梯子。安装那一步绕不开 GitHub，但运行阶段完全可以不碰境外服务：Hermes 上游把 MiniMax 国内站做成了独立的 Provider 选项 MiniMax (China)，走 MiniMax 的 Anthropic Messages 兼容端点，工具调用、流式输出和上下文管理都复用 Hermes 最成熟的那套适配器，不需要任何额外配置。一把 Key 配好，CLI、Gateway 和语音合成都能用。

它和 OpenRouter 不冲突。国内用户的合理分工是：日常默认走 MiniMax，确实需要某个海外模型时再单独配 OpenRouter，配置思路见 Hermes Agent 接入 OpenRouter。其他国内 Provider 的选项名和环境变量汇总在 国内安装与使用指南，智谱 GLM、Kimi 和 小米 MiMo 各有单独教程。

先分清两个站，Key 不能混用

MiniMax 有海外站和国内站两套账号体系，Key 互不通用，Hermes 里也是两个独立选项：

• 海外站 minimax.io：hermes model 里选 MiniMax，环境变量 MINIMAX_API_KEY，端点 https://api.minimax.io/anthropic。
• 国内站 minimaxi.com：hermes model 里选 MiniMax (China)，环境变量 MINIMAX_CN_API_KEY，端点 https://api.minimaxi.com/anthropic。

国内账号申请的 Key 填进 MiniMax 那一项，结果一定是 401。Hermes 不会拿一个站的 Key 去试另一个站，也不会把 ANTHROPIC_API_KEY 拿来兜底，这是上游刻意做的限制，避免把 Anthropic 的凭据发到第三方端点。国内站在配置文件里的 Provider ID 是 minimax-cn，别名 minimax-china 和 minimax_cn 也能识别。

申请 Key

在 MiniMax 开放平台（minimaxi.com）登录后创建接口密钥，确保账户有可用额度。平台菜单会变，以当前界面为准；Key 创建后只会完整显示一次，直接粘到 Hermes 里，不要存进聊天记录、截图或代码仓库。

上游还提供浏览器登录的 MiniMax (OAuth · minimax.io) 选项，不需要 Key，但它面向海外站账号；官方文档对国内账号的说法是"如果你的中国账户支持 OAuth"，并建议国内用户直接配置 MINIMAX_CN_API_KEY。本文按 Key 的路线走。

配置方式一：hermes model 向导

hermes model
# → Provider 列表里选 "MiniMax (China)"，不要选 "MiniMax"
# → 粘贴在 minimaxi.com 创建的 Key，Hermes 会写进 ~/.hermes/.env
# → 模型选 MiniMax-M2.7

有一点和 OpenRouter 不同：MiniMax 没有 /models 接口，向导里的模型列表是 Hermes 内置的静态目录，hermes model --refresh 对它不起作用。列表里没有的新模型（例如 MiniMax-M3）要靠 hermes update 升级 Hermes 之后才会出现。

配置方式二：直接写 .env 和 config.yaml

在服务器上或者想脚本化时，不走向导：

echo 'MINIMAX_CN_API_KEY=你的Key' >> ~/.hermes/.env
hermes config set model.provider minimax-cn
hermes config set model.default MiniMax-M2.7

三点说明：

• ~/.hermes/.env 的优先级高于 shell 里 export 的同名变量，重启后以文件为准。只在终端里 export 过、没写进文件，换个窗口就失效。
• 不要动 MINIMAX_CN_BASE_URL，默认值已经是 /anthropic 端点，只有走自建中转时才需要覆盖。
• 只想临时试一次、不改默认配置，用 hermes chat --provider minimax-cn --model MiniMax-M2.7。

验收：三条命令确认链路

hermes doctor
hermes -z "用一句话确认你能正常回复"
hermes gateway restart

hermes doctor 会读取 .env 里的 Key，并对 MiniMax (China) 做一次连通性检查。它知道国内站的 /v1/models 会返回 404，不会把这个 404 当成失败，所以看不到模型列表是正常的。hermes -z 跑一句短问答是最直接的验收，能回复就说明 Key、端点和模型名都对。已经在跑 Gateway 的话，最后一条让它重新加载 Key，否则群里还是旧配置。

选哪个模型

• MiniMax-M2.7：新旧版本 Hermes 的列表里都有，先用它把链路跑通。
• MiniMax-M3：只出现在较新版本的目录里。Hermes 按 100 万 token 记录它的上下文长度，并且会忽略 models.dev 上偏低的数值。
• MiniMax-M2.7-highspeed：只在 OAuth 通道的列表里，API Key 通道没有这一项。
• MiniMax-M2.5、MiniMax-M2.1、MiniMax-M2：仍在列表里，留给老项目兼容，新项目没必要选。

成本方面，Hermes 内置的计价表（2026 年 4 月快照）把国内站的 M2.7 记为输入每百万 token 0.30 美元、输出 1.20 美元。这张表只用于 Hermes 自己的用量估算；国内站按人民币结算，真实花费以平台账单为准，建议照 成本记录模板 跑一两周再决定要不要换模型。

常见报错

1. 401 或 invalid api key：九成是 Key 配错了站。先确认 hermes model 里选的是 MiniMax (China)，再用 grep MINIMAX ~/.hermes/.env 看 Key 是否真的在文件里。另一个终端 export 的变量不算。
2. 提示模型不在 MiniMax 目录里：模型名大小写不敏感，但要和平台实际开放的 ID 一致。Hermes 对目录外的名字只会提示、不会拦截，真的不存在会在第一次请求时报错。
3. 回复里混进 <think> 标签或思考内容：M2.7 流式输出时会把思考段拆成多个片段，旧版本 Hermes 处理不好，先 hermes update。
4. 请求很慢或超时：国内站直连不需要代理。如果为了装 Hermes 开了全局代理，把 api.minimaxi.com 加进 no_proxy，或者测试时先关掉代理。
5. CLI 正常、群里还是旧模型：Gateway 没重启，跑 hermes gateway restart。

更多排查思路见 Hermes Agent 故障排查清单。

顺手能做的两件事

同一个 Key 还能给语音合成用。在 config.yaml 里把 tts.provider 设成 minimax，tts.minimax.region 设成 cn；只配了国内 Key 时 Hermes 会自动选 cn 区域，并且绝不会借用海外站的 Key。默认模型是 speech-02-hd，Telegram 要显示成语音气泡需要装 ffmpeg。

另一件是把 MiniMax 设成兜底模型。主模型遇到 429、503、529 或连接失败时，Hermes 会自动切到兜底：

fallback_model:
  provider: minimax-cn
  model: MiniMax-M2.7

反过来用 MiniMax 做主、OpenRouter 做兜底也行，取决于你哪条线路更稳。

核对说明

本文的选项名、环境变量、端点、模型列表和计价数据对照上游 v2026.9.24（v0.21.5）的 hermes_cli/auth.py、models_catalog_static.py、doctor_connectivity.py 和官方 Providers 文档核对，命令参数在本地 v0.15.1 验证过。编辑组没有用国内站账号做真实计费测试，价格和额度以你的控制台为准。

下一步

链路通了以后，按 setup 输出验收清单 把 Memory、Skills 和 Gateway 逐项过一遍，再回到 模型接入指南 看按任务分层选模型的思路。

还没有真实场景？可以先领取 Free Starter 模板包，从低风险只读任务开始试跑。