fnOS 应用商店版 Hermes Agent 接入本地大模型

适用场景：通过 fnOS 应用中心（trim 应用商店）安装的 Hermes Agent（版本 v0.18.0，trim.hermes 应用）， 需要接入本机 llama.cpp / Ollama 等本地大模型服务，替代默认云端 provider（避免额度耗尽报 402 错误）。

---

背景知识：先搞清楚"你装的是哪个 Hermes"

关键坑：一台机器上可能同时存在两套完全独立的 Hermes，配置互不相通：

判断依据：ps aux | grep -i hermes，看进程路径里带不带 trim.hermes 字样，或者看进程用户是不是 trim.he+（trim.hermes 账号）。

本笔记专门针对 B（fnOS 应用商店版）。

---

一、核心结论（先记住这几条，遇到问题直接对照）

1. 真正的配置文件路径：

   /vol3/@appdata/trim.hermes/hermes/config.yaml
   

   密钥文件（.env）在同一目录下：

   /vol3/@appdata/trim.hermes/hermes/.env
   

2. ⚠️ 网页里"SET MAIN MODEL"这个图形化弹窗是死胡同，走不通：

   • 它只能从内置的固定 provider 列表里选（Nous Portal、OpenRouter、Z.AI 等云端服务）

   • 搜不到、也无法新增自定义的 openai-compatible 本地 endpoint

   • 点击列表里的 "Custom endpoint (enter URL manually)" 不会弹出任何输入框，只会提示 run 'hermes model' to configure —— 这行提示就是明确告诉你：必须走 CLI / TUI 命令，GUI 这里没实现完整流程

3. ⚠️ 两种配置入口，效果不对等，优先用 A：

   • 入口 A（唯一验证过能"即时生效"的方法）：网页"对话"页面里，如果显示 "Setup Required"，直接在输入框里敲 /setup，走一遍完整设置向导。这是在当前活跃会话进程里原地初始化，配完立刻能用。

   • 入口 B（SSH 命令行 hermes model）：实测能把配置正确写入 config.yaml（用 cat 验证过两次，内容完全正确），但写入后无法让正在运行的会话加载生效——试过刷新网页、点"重启网关"、重启整个应用，都没能让网页对话恢复正常，弹窗依旧显示 (unknown)/unset，TUI 依旧提示 setup required。 结论：方法 B 目前只能当作"确认配置文件该长什么样"的验证手段，不建议单独依赖它来让服务生效；真正要让本地模型跑起来，最后一步必须走方法 A 的 /setup。

4. 必须选的 provider 类型：列表中的 custom (direct API)（不是 "Custom endpoint (enter URL manually)" 那个，虽然名字很像，行为完全不同）

---

二、方法 A：网页对话框里走 /setup（推荐，无需 SSH）

步骤 1：打开网页 Hermes 对话页面

如果模型没配置好，页面会显示黄色 ASCII 艺术字 "HERMES-AGENT" 加一段提示：

Setup Required
Hermes needs a model provider before the TUI can start a session.

Actions
/model      configure provider + model in-place
/setup      run full first-time setup wizard in-place
Ctrl+C      exit and run `hermes setup` manually

注：/model 单独命令在实测中可能没有反应（原样回显，无弹窗），直接用 /setup 更可靠。

步骤 2：在输入框中输入

/setup

回车后进入交互式设置向导，会依次出现下面几个环节：

步骤 3：How would you like to set up Hermes?

三个选项，选第二个：

(○) Quick Setup (Nous Portal) — 免费OAuth登录，不适用（我们要用本地模型）
(●) Full setup — configure every provider, tool & option yourself   ← 选这个
(○) Blank Slate — 全部关闭，逐个开启

用 ↓ 移动光标到 "Full setup"，按 Enter/Space 选中。

步骤 4：Inference Provider（★核心步骤）

会看到当前状态：

Current model:    (not set)
Active provider:  none

出现 provider 列表后，找到并选中 custom (direct API)（在列表中部，"Alibaba Cloud (Coding Plan)" 附近，注意跟 "Custom endpoint (enter URL manually)" 是两个不同选项，选前者）。

选中后会依次询问：

Custom OpenAI-compatible endpoint configuration:
API base URL [e.g. https://api.example.com/v1]: 

→ 填你本地模型服务的地址，例如：

http://127.0.0.1:8083/v1

（llama.cpp 的端口按你自己的实际部署填，Ollama 一般是 http://127.0.0.1:11434/v1）

API key [optional]:

→ 本地服务通常不校验，随便填一个占位符即可，比如：

local-key

系统会自动验证连接：

Verified endpoint via http://127.0.0.1:8083/v1/models (1 model(s) visible)

看到这行说明连接成功。

Select API compatibility mode:
  1. Auto-detect [current]   ← 直接按 Enter 保持这个
  2. Chat Completions
  3. Responses / Codex
  4. Anthropic Messages
Choice [1-4, Enter to keep current/detected]: 

直接按 Enter，保持 Auto-detect。

Detected model: /models/xxxxx.gguf
Use this model? [Y/n]: 

输入 y

Context length in tokens [leave blank for auto-detect]: 

手动填一个具体数值，别留空（自动检测不一定准，容易比服务端实际设置小，导致工具调用异常）。 填你 llama.cpp 服务端实际的 -c / --ctx-size 参数值，例如：

65536

可用 curl -s http://127.0.0.1:8083/v1/models 命令查看服务端返回的 n_ctx 字段来确认这个值。

Display name [Local (127.0.0.1:8083)]: 

可以自定义一个好记的名字，比如：

qwen36

看到这行说明保存成功：

Default model set to: /models/xxxxx.gguf (via http://127.0.0.1:8083/v1)
  💾 Saved to custom providers as "qwen36" (edit in config.yaml)

步骤 5：后续步骤（都可以用默认值/跳过）

• Terminal Backend：选 Keep current (local)，回车确认

• Messaging Platforms（Feishu/Lark、Slack、Telegram 等）：不勾选任何一项，直接回车跳过（后续可用 hermes gateway 单独配置）

• CLI 工具集：保持默认勾选即可（Web Search、Browser、Terminal、File Ops、Vision、Image Gen、TTS、Skills、Memory 等），回车确认

• Browser Automation Provider：选默认的 Local Browser [★ recommended · free]，回车确认

• 如果后续出现 [sudo] password for trim.hermes:（一般是装 Chromium 浏览器依赖时触发），这个账号通常没设密码，直接按 Ctrl+C 跳过，不影响模型配置本身，只是浏览器自动化工具装不上

步骤 6：验证

setup 流程走完（或中途 Ctrl+C 跳过非核心步骤）后：

1. 刷新一下浏览器网页（F5），让前端重新检测状态

2. 在对话框里发一条测试消息，比如"你好，你是谁？"

3. 正常情况下能看到本地模型的思考过程和回复，底部状态栏会显示：

   ready │ 你的模型文件名 │ 13.8k/65.5k │ ✓ 用时
   

   看到 ready 和正确的模型名，就说明配置成功了。

---

三、方法 B：SSH 命令行走 hermes model（⚠️ 仅供参考验证，未验证过能独立生效）

重要提醒：这个方法在实测中能把配置正确写入 config.yaml（多次用 cat 核实过内容无误）， 但从未成功让运行中的网页会话真正加载并使用这个配置——试过刷新页面、点"重启网关"、 整个应用停止再启动，网页端始终还是显示 provider 未配置。

不要指望单独靠这个方法就能让本地模型跑起来。 如果 SSH 里跑完这一套后网页还是不认， 直接去网页对话框走"方法 A"的 /setup 才是真正有效的路径。

这个方法目前的实际用途：

1. 想预先确认/理解 config.yaml 该写成什么格式，可以照着走一遍看看结果

2. 排查环境变量（HOME / HERMES_HOME）是否正确的手段

3. 不建议作为"配置本地模型"的主要操作流程

步骤 1：确认关键路径和环境变量

fnOS 应用商店装的 Hermes，可执行文件和数据目录如下：

# CLI可执行文件
/vol3/@appcenter/trim.hermes/runtime/python/bin/hermes

# 需要用到的两个环境变量（缺一不可，否则CLI会读到一个全新的空配置）
HOME=/vol3/@appdata/trim.hermes/home
HERMES_HOME=/vol3/@appdata/trim.hermes/hermes

这两个环境变量的值是通过下面命令从正在运行的 wrapper 进程里挖出来的，如果以后版本更新路径变了，可以照此方法重新确认：

ps aux | grep "trim-hermes-wrapper" | grep -v grep
# 拿到PID后
cat /proc/<PID>/environ 2>/dev/null | tr '\0' '\n' | grep -E "HERMES_HOME|^HOME="

步骤 2：运行配置命令

HOME=/vol3/@appdata/trim.hermes/home \
HERMES_HOME=/vol3/@appdata/trim.hermes/hermes \
/vol3/@appcenter/trim.hermes/runtime/python/bin/hermes model

进入交互式选择器后，操作流程和上面"方法 A 步骤 4"完全一致：选 custom (direct API) → 填 base URL → 填占位 API key → 确认识别到的模型 → 填 context length → 起个 display name。

步骤 3：验证写入

cat /vol3/@appdata/trim.hermes/hermes/config.yaml | grep -A3 "^model:"

正确的话应该显示：

model:
  default: /models/xxxxx.gguf
  provider: custom
  base_url: http://127.0.0.1:8083/v1

步骤 4：让改动生效

• 优先尝试：网页 Hermes 侧边栏点 "重启网关"

• 如果无效：去 fnOS 应用中心 界面，把 Hermes 应用停止再启动一次

• 最后手段：直接杀掉 wrapper 主进程（kill <PID>），fnOS 一般有 watchdog 会自动拉起

---

四、常用排查命令速查表

---

五、本机常用本地模型端口对照（供后续切换模型参考）

如果想切换到更快的 qwen3-2507（8084 端口），重复本文档"方法 A"或"方法 B"， 把 base URL 换成 http://127.0.0.1:8084/v1 即可，流程完全一样。

---

六、这次踩过的坑，总结成一句话版

网页图形弹窗配置不了本地模型；SSH 命令行 hermes model 能写对配置文件但不会让服务生效； 唯一确认有效的方法是在网页对话框里敲 /setup 原地走完整设置向导； provider 类型要选 "custom (direct API)"，不是 "Custom endpoint"； Context length 记得手动填，别自动检测。