乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > 用 OpenClaw 安装配置 Hermes 全过程 ——一个亚马逊卖家的真实踩坑记录

用 OpenClaw 安装配置 Hermes 全过程 ——一个亚马逊卖家的真实踩坑记录

当前时间： 2026-05-18 14:07:08 更新时间： 2026-05-18 分类：软件教程 评论(0)

用 OpenClaw 安装配置 Hermes 全过程 ——一个亚马逊卖家的真实踩坑记录

    对于很多亚马逊卖家运营，其实都没有太多技术背景，今天我把我用openclaw大龙虾来配置Hermes爱马仕AI助手的过程分享给大家，大家可以参考部署。用 OpenClaw 在本地跑 Hermes，目的很简单：把 常用的几家 API 统一部署到Hermes管理，按需切换模型。整个过程踩了一堆坑，全程靠 OpenClaw 内置的 AI 助手帮我排查。这篇文章把今天下午发生的所有事情原原本本记下来，包括报错信息、排查过程、最终修复方式，方便有同样需求的卖家直接参考。

一、环境说明

组件
版本/说明
操作系统
Windows 11 x64
OpenClaw
第三方稳定发行版
Hermes
hermes-desktop 0.4.x，内置 Python 3.11 runtime
Hermes Gateway
监听 127.0.X.X:XXX，由 Hermes 桌面应用管理生命周期
配置目录
 C:\Users\davie\xxx\.hermes\
Python 路径
 C:\Users\davie\XXX\XXX\uv\python\cpython-3.11-...\python.exe

为什么用 第三方的openclaw而不是官方 OpenClaw

官方 OpenClaw 更新频繁，每次大版本升级都可能导致现有配置失效，对不熟悉命令行的用户非常不友好。第三方的 Claw 是基于 OpenClaw 的稳定发行版，内置第三方的 AI 能力，适合技术小白——遇到问题直接在对话框里描述，AI 会帮你读日志、改配置、重启服务。

二、用第三方的 Claw 安装 Hermes 全过程

Hermes 是一个本地 AI agent 框架，核心能力是统一管理多个云端 LLM API，支持会话记忆、工具调用、多 provider 切换。它由 Electron 桌面壳 + Python gateway 两部分组成。理解这个架构对后续排错很有帮助。

2.1 安装 第三方的 Claw

前往 第三方的Claw官网下载 Windows 安装包，双击安装，全程 Next 即可。安装完成后托盘区会出现图标，点击打开主窗口——这就是你后续所有操作的入口。

第三方 Claw vs 官方 OpenClaw

官方 OpenClaw 走 npm 全局安装（npm install -g openclaw），需要 Node.js 环境，且随时可能大版本 breaking change。Genspark Claw 是打包好的桌面发行版，自带 Node runtime，版本锁定，Windows 用户直接双击安装，没有环境依赖问题。

2.2 安装 Hermes Desktop

第三方Claw 内置 AI 助手，直接在对话框里说：

帮我安装 Hermes

AI 助手会自动完成以下操作（你只需要等待）：

  1. 检测系统是否已安装 uv（Python 包管理器），没有则自动安装
  2. 通过 uv 创建隔离的 Python 3.11 虚拟环境，路径在 %APPDATA%\uv\python\cpython-3.11-windows-x86_64-none\
  3. 安装 hermes-cli 及所有依赖包
  4. 初始化配置目录 C:\Users\{你的用户名}\.hermes\，生成默认 config.yaml 和 .env

安装完成后，Hermes Desktop（Electron 应用）会出现在 C:\Users\{用户名}\AppData\Local\Programs\hermes-desktop\，可执行文件是 hermes-agent.exe。

⚠️ Hermes Desktop 的生命周期

Hermes 的 gateway 服务（Python 进程，监听 127.0.x.x:xxxx）由 Hermes 桌面应用管理，不是开机自启的系统服务。每次需要使用时，先打开 Hermes Desktop，点击界面里的「Start Gateway」按钮，gateway 才会启动。关闭桌面应用，gateway 也会随之停止。

2.3 配置目录结构

安装完成后，~/.hermes/ 目录的关键文件如下：

文件
作用
是否手动编辑
.env
环境变量，存放 API Key（GLM_API_KEY、_API_KEY 等）
✅ 可以，是持久化的
config.yaml
主配置，定义默认模型、custom_providers、gateway 端口等
✅ 可以，是持久化的
auth.json
运行时认证缓存，记录各 provider 的 token 和状态
❌ 禁止手动改，每次启动会被重建
models.json
UI 模型下拉列表的数据源
⚠️ 可改，但重启后被 seedDefaults() 覆盖
logs/gateway.log
gateway 启动日志
只读，排错用
logs/agent.log
每次对话的详细日志，含 provider、base_url、model 等路由信息
只读，排错最重要的文件

2.4 配置第一个 API Key（以 SiliconFlow 为例）

硅基流动 https://cloud.siliconflow.cn/i/aEOl79Lx

Hermes 安装好之后是空壳，必须配置至少一个 LLM provider 的 API key 才能使用。以 SiliconFlow 为例，完整配置步骤：

Step 1：在 .env 里写入 API Key

# ~/.hermes/.envGLM_API_KEY=sk-som****idone# SiliconFlow key，替换为你的真实 keyGLM_BASE_URL=https://api.siliconflow.cn/v1

Step 2：在 config.yaml 里配置 custom_providers 和默认模型

model:  default: "Pro/zai-org/GLM-5"provider: "custom"base_url: "https://api.siliconflow.cn/v1"# ← 必须写，不能省max_tokens: 4096custom_providers:   - name: "siliconflow"base_url: "https://api.siliconflow.cn/v1"api_key: "sk-som****idone"model: "Pro/zai-org/GLM-5"# ← 必须写，否则不出现在下拉列表

Step 3：在 Hermes Desktop 里重启 gateway

每次修改 config.yaml 或 .env 后，需要在 Hermes Desktop 界面点击重启 gateway，新配置才会生效。如果遇到模型列表没有刷新，完全退出 Hermes 应用（系统托盘右键退出），重新打开。

Step 4：验证连通性

可以直接在命令行测试 API 是否通：

# PowerShell 验证 SiliconFlow$headers = @{   "Authorization" = "Bearer sk-som****idone"   "Content-Type"  = "application/json" } $body = '{"model":"Pro/zai-org/GLM-5","messages":[{"role":"user","content":"hi"}],"max_tokens":5}' Invoke-WebRequest -Uri "https://api.siliconflow.cn/v1/chat/completions" `   -Method POST -Headers $headers -Body $body -UseBasicParsing# 返回 200 即表示 key 有效

或者更简单：直接在 第三方的 Claw 对话框里对话，如果 Hermes 配置正确，AI 会通过 Hermes gateway 响应你的消息。

✅ 安装完成的标志

在 第三方的 Claw 对话框发一条消息，Hermes Desktop 的状态栏显示 gateway running，logs/agent.log 里出现对话记录，且 base_url 指向你配置的 provider 地址——这说明整个链路通了。

三、昨天遭遇的问题时间线

16:13

问题一：ECONNREFUSED 127.0.0.1:xxxx

Error: API request failed: connect ECONNREFUSED 127.0.x.x:xxxx

16:18

问题二：401 No cookie auth credentials found

Error code: 401 – {‘error’: {‘message’: ‘No cookie auth credentials found’, ‘code’: 401}}session_id: 20260517_xxxx_xxxx

16:30 ~ 16:45

问题三：模型选择后持续 400 Bad Request

Error code: 400 – {‘error’: {‘message’: ‘gpt-5.3-chat-latest is not a valid model ID’, ‘code’: 400}}

16:31 ~ 16:46

问题四：每次重启 gateway，模型下拉列表全部消失

重启后 models.json 被 seedDefaults() 覆盖，手动修改无效。

16:46 ~ 17:11

全部问题修复，三模型稳定运行

SiliconFlow GLM-5 / 302ai GPT-5.3 / Claude Sonnet-4.5 均可正常对话。

https://share.302.ai/5CYSM3

四、问题一：ECONNREFUSED — Gateway 没有在监听

现象

Hermes 升级后，前端报连接拒绝。第一反应是 gateway 进程挂了。

排查

让 AI 助手执行 netstat -ano | findstr xxxx，结果出乎意料：

TCP    127.0.0.x:xxxx    0.0.0.0:0    LISTENING    30708

端口实际上是有在监听的，PID 30708 是 Python 进程，启动时间是 16:12（刚刚启动）。再查进程命令行：

python.exe -m hermes_cli.main gateway

然后直接 curl 健康检查接口：

Invoke-WebRequest -Uri "http://127.0.0.x:xxxx/health" → 200 OK: {"status": "ok", "platform": "hermes-agent"}

结论

Gateway 实际是正常的，ECONNREFUSED 是升级过程中的瞬态报错（服务刚启动还没就绪时客户端发起了请求）。真正的问题在下一步——认证失败。

五、问题二：401 认证失败 — auth.json 状态异常

排查 auth.json

让 AI 助手读取 ~/.hermes/auth.json，发现 credential pool 里三条记录全部处于 exhausted 状态：

Provider
Label
状态
错误
302ai
_API_KEY
 exhausted
403 Key limit exceeded（额度耗尽）
302ai
anthropic/claude-sonnet-4.5
 exhausted
401 No cookie auth credentials found（access_token 为空）
custom:siliconflow
siliconflow
 exhausted
401 Api key is invalid（旧 key 失效）

同时检查 config.yaml，发现 siliconflow custom_provider 里的 api_key 字段被 Hermes 自动打码成了 sk-mcz...izdy，Python gateway 读取这个截断的字符串作为真实 key 当然失败。

修复

更新 .env 里的 GLM_API_KEY，同时更新 config.yaml 里 siliconflow 条目的 api_key 为新的完整 key，并清除 auth.json 里旧的 last_status: exhausted 状态。

直接测试 SiliconFlow API：

POST https://api.siliconflow.cn/v1/chat/completions {"model":"Pro/zai-org/GLM-5","messages":[...],"max_tokens":5} → 200 OK ✅

六、问题三：400 Bad Request — gateway 路由到了错误的 Provider

这是今天最复杂、耗时最长的问题，前后绕了好几圈才找到根本原因。

表象

在 Hermes 下拉框选择 302ai 的 gpt-5.3-chat-latest，对话报 400：

Error code: 400 – {‘error’: {‘message’: ‘gpt-5.3-chat-latest is not a valid model ID’, ‘code’: 400}, ‘user_id’: ‘user_3A97Ly07faRFZzSKdddddY’}

user_id 里的 user_3A97... 是302ai的用户 ID 格式，说明请求根本没有发到 302ai，而是发到了302ai。

看日志定位根因

让 AI 助手读取 ~/.hermes/logs/agent.log，关键日志：

INFO run_agent: OpenAI client created   provider=custom  base_url=https://302ai.ai/api/v1   ← 问题在这里！   model=gpt-5.3-chat-latest

Gateway 用的是 302ai 的 base_url，而不是 302ai 的 https://api.302.ai/v1。原因链：

  1. 选择模型时，Hermes 桌面调用 setModelConfig(provider, model, baseUrl) 更新 config.yaml
  2. provider 被写为 custom（Hermes 的 loadCustomProviders 把所有自定义 provider 都归类为 custom）
  3. Python gateway 拿到 provider=custom，去 auth.json 的 credential pool 里找 custom:302ai
  4. 此时 auth.json 已被 Hermes 重启覆盖
，credential pool 里没有 custom:302ai
  1. Gateway fallback 到 302ai 的 base_url，把请求发给了302ai

关键发现：auth.json 是易失性的

Hermes 每次启动都会根据 .env 和 config.yaml 重新生成 auth.json，手动往 auth.json 里写的内容在下次重启后会被覆盖。所有持久化配置必须写在 .env 或 config.yaml 里。

尝试路径一：修改 models.json（失败）

Hermes 的模型列表存在 ~/.hermes/models.json，尝试手动把 302ai 条目的 provider 字段从 custom 改为 302ai：

{"name":"302ai","provider":"302ai","model":"gpt-5.3-chat-latest","baseUrl":"https://api.302.ai/v1"}

重启 gateway 后，models.json 被 seedDefaults() 重新覆盖，修改丢失。

尝试路径二：逆向 Hermes 源码理解 provider 路由逻辑（成功）

通过读取 app.asar 包内的 JS 代码（Electron 应用），搞清楚了 Hermes 的两个关键函数：

loadCustomProviders：解析 config.yaml 里的 custom_providers 块，把每个条目的 provider 统一设为 "custom"，只有当条目同时有 model 和 baseUrl 两个字段时，才会被加入模型列表。

setModelConfig：选择模型时把 config.yaml 里的 model.provider、model.default、model.base_url 三个字段同步更新。

所以，解决方案是：在 config.yaml 的 model 段显式写入 base_url。Gateway 在路由时优先使用这个 base_url，不再依赖 credential pool 的 provider 匹配。

最终修复

model:  default: "gpt-5.3-chat-latest"provider: "custom"base_url: "https://api.302.ai/v1"# ← 关键！显式写 base_urlmax_tokens: 4096

重启 gateway 后验证日志：

INFO run_agent: OpenAI client created   provider=custom  base_url=https://api.302.ai/v1   ← 正确了 ✅   model=gpt-5.3-chat-latest

302ai GPT-5.3 正常响应

此时同时还发现了另一个副作用：config.yaml 的正则替换过程中把 siliconflow 的 base_url 错误改成了 302ai 的地址，需要一并修复。

七、问题四：模型列表重启后消失 — seedDefaults 的覆盖逻辑

根本原因

通过读取 app.asar 源码，找到了 seedDefaults 函数的逻辑：

  1. 如果 models.json 不存在，调用 seedDefaults() 从默认列表 + custom_providers 生成
  2. 如果 models.json 存在，直接读取（不 seed）
  3. 关键判断
    ：custom_providers 里的条目，只有同时具备 model 和 baseUrl 两个字段，才会被加入列表

之前 siliconflow 条目缺少 model 字段，所以 seed 时被跳过，永远不出现在下拉列表。

修复：补全所有 custom_providers 的 model 字段

custom_providers:   - name: "siliconflow"base_url: "https://api.siliconflow.cn/v1"api_key: "sk-som****idone"# 脱敏model: "Pro/zai-org/GLM-5"# ← 必须有，否则 seed 时被跳过    - name: "302ai"base_url: "https://api.302.ai/v1"api_key: "sk-0nwX****UpwJ"# 脱敏model: "gpt-5.3-chat-latest"# ← 必须有    -

删除 models.json，重启 Hermes 整个应用（不只是 gateway），三个模型全部出现在下拉框。✅

八、最终稳定的配置结构

config.yaml（核心部分）

model:  default: "anthropic/claude-sonnet-4.5"# 当前默认模型provider: "custom"base_url: "https://302ai.ai/api/v1"# ← 必须显式写，随切换同步更新max_tokens: 4096custom_providers:   - name: "siliconflow"base_url: "https://api.siliconflow.cn/v1"api_key: "sk-som****idone"model: "Pro/zai-org/GLM-5"   - name: "302ai"base_url: "https://api.302.ai/v1"api_key: "sk-0nwX****UpwJ"model: "gpt-5.3-chat-latest"   -

当前可用模型一览

下拉显示名
Model ID
Provider
Base URL
状态
siliconflow
 Pro/zai-org/GLM-5
SiliconFlow
api.siliconflow.cn
 ✅ 正常
302ai
 gpt-5.3-chat-latest
302.AI
api.302.ai
 ✅ 正常

九、总结：关键结论与避坑清单

核心结论

⚠️ auth.json 不可手动持久化

Hermes 每次启动都重建 auth.json（从 .env 和 config.yaml 读取）。所有 API key 的持久化配置必须写入 .env（ENV 变量形式）或 config.yaml（custom_providers 形式）。

⚠️ model 段必须显式写 base_url

这是 302ai / 自定义 provider 路由正确的关键。不写则 gateway 按 provider 名匹配 credential pool，custom provider 的 pool key 是 custom:xxx 格式，匹配失败会 fallback 到302ai。

⚠️ custom_providers 每个条目必须有 model 字段

缺少 model 字段的条目在 seedDefaults() 里会被跳过，不会出现在下拉列表。这是导致「模型列表重启消失」的直接原因。

💡 切换模型后 base_url 会自动更新

在 Hermes UI 里切换模型，setModelConfig() 会自动把 config.yaml 里的 model.base_url 改成选中模型对应的 baseUrl。所以下次切换模型时不需要手动改配置。

操作清单（可直接复用）

  1. 安装 Hermes：
    在 OpenClaw/第三方 Claw 对话框直接说”帮我安装 Hermes”，让 AI 助手全程处理。
  2. 配置 API key：
    在 config.yaml 的 custom_providers 里添加各 provider，每个条目必须包含 name、base_url、api_key、model 四个字段。
  3. 配置当前默认模型：
    在 model 段写入 default（模型ID）和 base_url（该 provider 的接口地址）。
  4. 删除 models.json：
    让 Hermes 重新从 config.yaml 生成模型列表。
  5. 完全重启 Hermes 应用
    （不只是 gateway），等模型下拉框出现所有配置的 provider。
  6. 遇到任何报错：
    把错误信息贴给 OpenClaw AI 助手，让它读日志、定位根因、给出修复方案。