本文为您汇总了安装、使用 Hermes 相关的常见问题及解决方案。 |问题分类 |问题 | |---|---| |安装 Hermes Agent 插件 |[ArkClaw 升级失败怎么处理？](https://www.volcengine.com/docs/87732/2358943#DcL3Kixj) | ||[安装 Hermes Agent 插件时报错“可用空间不足 5GB”，如何解决?](https://www.volcengine.com/docs/87732/2358943#8Z0x2KRh) | ||[Hermes Agent 插件安装失败如何解决？](https://www.volcengine.com/docs/87732/2358943#kLdhduml) | ||[安装 Hermes Agent 插件时，ArkClaw 重启失败如何解决？](https://www.volcengine.com/docs/87732/2358943#v1lLvfKi) | ||[如何查看 Hermes Agent 插件的安装日志？](https://www.volcengine.com/docs/87732/2358943#avyCegDc) | ||[Hermes Agent 插件安装完成后，其安装文件会自动删除吗？](https://www.volcengine.com/docs/87732/2358943#gyxp6DkW) | ||[已安装 Hermes Agent 的 ArkClaw 升级版本后无法使用，如何解决？](https://www.volcengine.com/docs/87732/2358943#8jqAVchB) | |使用 Hermes Agent

|[开启/关闭 Hermes Agent 时报错“开启/关闭 Hermes 失败”、“读取配置文件失败”或“解析配置文件失败”如何解决？](https://www.volcengine.com/docs/87732/2358943#r0g2dejP) | ||[Hermes Agent 生成的数据在哪里？](https://www.volcengine.com/docs/87732/2358943#UstZAXzH) | ||[删除 Hermes Agent 容器后，其历史生成的数据还在吗？](https://www.volcengine.com/docs/87732/2358943#0lbPKxm7) | ||[如何卸载 Hermes Agent 插件？](https://www.volcengine.com/docs/87732/2358943#vKpCetXN) | ||[如何读取 Hermes 生成的文件？](https://www.volcengine.com/docs/87732/2358943#6HeLHSiz) | ||[可以通过 ArkClaw 集成的渠道（例如飞书、微信）使用 Hermes Agent 吗？](https://www.volcengine.com/docs/87732/2358943#TPpxsu68) | ||[提示“OpenClaw 配置文件不是有效 JSON:/root/.openclaw/openclaw.json”如何解决？](https://www.volcengine.com/docs/87732/2358943#JJcEvl0Z) | ||[如何更换 Hermes Agent 使用的模型？](https://www.volcengine.com/docs/87732/2358943#c1jbs5Xr) | ||[Hermes 执行任务时报错“ACP error [-32603]: Internal error”如何解决？](https://www.volcengine.com/docs/87732/2358943#EUiP85bc) | ||[如何查看 Hermes Agent 使用的推理模型信息？](https://www.volcengine.com/docs/87732/2358943#lIl0RBH2) | ## 安装 Hermes Agent 插件 ### ArkClaw 升级失败怎么处理？ ArkClaw 需升级到 `ark-26.4.23` 及之后的版本才支持安装 Hermes Agent 插件，升级过程中可能由于兼容性、网络波动等问题导致升级失败。若升级失败，ArkClaw （包含部分已升级的系统/组件）将自动回滚至升级前的版本。您可根据 [升级 ArkClaw 系统/组件版本](https://www.volcengine.com/docs/87732/2275231) 指引再次尝试升级，也可通过 [问题反馈](https://www.volcengine.com/docs/87732/2275227) 获取技术支持。 ### 安装 Hermes Agent 插件时报错“可用空间不足 5GB”，如何解决? 安装 Hermes Agent 需要**不低于 5GB** 的存储空间。您可以与 ArkClaw 对话，安排其帮您梳理安全、可删除的缓存和临时文件数据，在您确认后进行删除，释放被占用的存储空间。

注意

删除文件属于高危操作，强烈建议您在手动备份 ArkClaw 数据且充分了解待删除文件作用后，再进行删除操作。

1. 您可以在 ArkClaw 详情页“状态与用量”页签，查看当前 ArkClaw 可用存储空间。[了解更多](https://www.volcengine.com/docs/87732/2341045)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6b943ee0de1829b225e59a0dbe6b615d.png) 2. 让 ArkClaw 帮您找出可安全删除的 npm 下载缓存并进行清理。

说明

npm 缓存是本地存储的安装包副本。清理该缓存属于安全操作，通常可释放 3~5 GB 的存储空间，唯一的影响是下次安装同名依赖时需重新通过网络下载。

1. 检测并评估可安全删除的文件。 **Prompt** **：** 帮我检测下系统中 npm 缓存目录（如 ~/.npm），列举可以安全删除的 npm 下载缓存文件、大小、作用和删除风险。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_99607dc520aefb2342b5757770fa013e.png) 2. 清理文件。 **Prompt：** 帮我安全清理上述 npm 下载缓存文件。清理完成后，重新检查并告诉我实际释放了多少存储空间。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6503ef33f316f6b9846ddb5980dfa5f9.png) 3. 若清理 npm 缓存后可用的存储空间依然不足 5 GB，您可以考虑清理未使用的 ArkClaw 插件（Plugin）。

注意

删除 ArkClaw 插件属于高风险操作。由于 ArkClaw 许多核心功能深度依赖特定内置插件，误删插件会导致对应功能不可用。强烈建议您仅在存储空间极度匮乏时才进行此操作。

1. 检测并评估可安全删除的文件。 **Prompt** **：** 扫描并列出当前 ArkClaw 已安装的 Plugin 列表及其占用的磁盘大小，并简要说明用途及删除风险。优先推荐删除老旧的备份目录、未使用的消息渠道插件。【严格安全约束】：lancedb、apmplus、arkclaw\-mode\-switch、ai\-assistant\-security、env\-logger、skill\-switch 等属于核心依赖组件，绝对禁止删除！基于上述约束，帮我筛并输出一份“建议安全删除清单”。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_5f2cc291c53302b91fb528f08299396e.png) 2. 清理文件。 **Prompt：** 我确认不再需要使用 XX 插件。请帮我安全卸载并彻底删除该插件的目录及其残留缓存。请勿触碰任何核心依赖，操作完成后告诉我实际释放了多少存储空间。

说明

请将 XX 替换为您希望删除的插件名，例如 qqbot。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e672a59048c2e7d95e320a6d048a9c75.png) ### Hermes Agent 插件安装失败如何解决？ Hermes Agent 插件在安装过程中可能因兼容性问题导致安装失败。您可以： 1. 根据 [自动修复 ArkClaw](https://www.volcengine.com/docs/87732/2270355?) 指引进行修复，再尝试安装 Hermes Agent 插件。 2. 若插件依旧安装失败，可通过 [问题反馈](https://www.volcengine.com/docs/87732/2275227) 获取技术支持。 ### 安装 Hermes Agent 插件时，ArkClaw 重启失败如何解决？ Hermes Agent 插件安装完成后，需要重启 ArkClaw 网关使其生效，重启过程可能由于各类兼容性问题导致失败。此时，您可以手动 [重启 ArkClaw](https://www.volcengine.com/docs/87732/2266924)，重启完成后，Hermes Agent 插件将自动生效。 ### 如何查看 Hermes Agent 插件的安装日志？ Hermes Agent 插件安装日志存放在 `/var/log/hermes-agent/` 目录下，您可以通过该日志文件查看其安装过程及出现的问题详情。通过对话查看 1. 关闭 Hermes。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a5fa8e7f5e6d2c7931574a156714e190.png) 2. 向 ArkClaw 发送 Prompt，查看相关日志。例如：帮我查看/var/log目录下Hermes 最新安装日志。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_904fa09ace679fdafe5f999e27c9ba0a.png) 通过终端查看 1. [打开 ArkClaw 终端](https://www.volcengine.com/docs/87732/2270411)。 2. 执行如下命令，查看最新的 200 条安装日志信息。 ```Bash sudo tail -n 200 "$(ls -1t /var/log/hermes-agent/upgrade-*.log | head -n 1)" sudo docker logs --tail 200 hermes-agent ``` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_84eae5d821c8c692bb80a42cf0a9ee44.png) ### Hermes Agent 插件安装完成后，其安装文件会自动删除吗？ Hermes Agent 插件安装文件不会自动删除，该文件存放于 `/var/cache/hermes-agent` 目录下。您可以按需自行删除：通过对话 1. 关闭 Hermes。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_28c0fef6242eeb89c6931f17ef314ffb.png) 2. 向 ArkClaw 发送 Prompt，删除相关文件。例如：删除 /var/cache/hermes\-agent 目录及其中的所有文件。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e4f78b44db2b47942c775969a1e2db86.png) 通过终端 1. [打开 ArkClaw 终端](https://www.volcengine.com/docs/87732/2270411)。 2. 执行如下命令，强制删除 Hermes Agent 缓存目录及其中的文件。 ```Bash rm -rf /var/cache/hermes-agent ``` ### 已安装 Hermes Agent 的 ArkClaw 升级版本后无法使用，如何解决？由于 OpenClaw `2026.5.7` 版本存在兼容性问题，您在低版本安装的 Hermes Agent 插件在升级后无法正常使用，您需要重新安装 Hermes Agent 插件。 1. [打开 ArkClaw 终端](https://www.volcengine.com/docs/87732/2270411)。 2. 执行如下命令查看 ArkClaw 对应的 OpenClaw 版本。 ```Bash openclaw --version ``` 回显如下所示时，表示您ArkClaw 对应的 OpenClaw 版本为 `2026.5.7`，请按如下步骤重新安装 Hermes Agent 插件。否则，请通过 [问题反馈](https://www.volcengine.com/docs/87732/2275227) 获取技术支持。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_77f0a8028d8fbddcdd9121d79a7fedfb.png) 3. 执行如下命令，重新安装 Hermes Agent 插件。

说明

重新安装 Hermes Agent 插件将完整保留原有数据，不会造成数据丢失。

```Bash REGION=$(curl --connect-timeout 5 --max-time 10 -s "http://100.96.0.96/latest/region_id"); curl -fsSL "https://scarif-${REGION}.tos-${REGION}.ivolces.com/arkclaw/hermes/hermes-install-v2.sh" -o hermes-install-v2.sh bash hermes-install-v2.sh ``` 4. 命令执行完成后，ArkClaw 将自行安装 Hermes 插件，请关闭终端并**等待 5\-10 分钟**。 5. 安装完成后，请再次单击“Hermes”按钮，即可正常开启本功能。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1119d91c912ea2a0764187165af6c882.png) ## 使用 Hermes Agent ### 开启/关闭 Hermes Agent 时报错“开启/关闭 Hermes 失败”、“读取配置文件失败”或“解析配置文件失败”如何解决？该问题通常是由于您手动修改了 ArkClaw 的配置文件，出现兼容性问题导致的。您可以根据 [自动修复 ArkClaw](https://www.volcengine.com/docs/87732/2270355?) 指引进行修复，再尝试开启/关闭 Hermes Agent。 ### Hermes Agent 生成的数据在哪里？ Hermes Agent 执行任务后输出的结果、沉淀的 Skill 等数据默认存放在 `/opt/hermes-data` 目录下。 ### 删除 Hermes Agent 容器后，其历史生成的数据还在吗？ Hermes Agent 执行任务后输出的结果、沉淀的 Skill 等数据默认存放在 `/opt/hermes-data` 目录下，删除 Hermes Agent Docker 容器不会删除其中的数据。 ### 如何卸载 Hermes Agent 插件？ 1. Hermes Agent 插件。 1. [打开 ArkClaw 终端](https://www.volcengine.com/docs/87732/2270411)。 2. 执行如下命令，卸载 Hermes Agent 插件并删除其缓存、历史数据。 ```Bash REGION=$(curl --connect-timeout 5 --max-time 10 -s "http://100.96.0.96/latest/region_id"); curl -fsSL "https://scarif-${REGION}.tos-${REGION}.ivolces.com/arkclaw/hermes/hermes-uninstall.sh" -o hermes-uninstall.sh bash hermes-uninstall.sh --yes ``` 回显如下所示时，表示已成功卸载 Hermes Agent 插件并删除其缓存、历史数据。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2a4aa14fbf44688deab211d56d53818e.png) 2. 确认已完整卸载 Hermes Agent 插件。通过对话 1. 关闭 Hermes。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e56f2ae2f0ded16b137f7ebae8977acc.png) 2. 向 ArkClaw 发送 Prompt，检查相关文档是否还有残留。例如：帮我检查 Hermes 容器、缓存、数据目录还在不在。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c2f4afbb591f69da5afe353d3a60aee3.png) 通过终端执行如下命令，查看 Hermes 容器、缓存及数据目录是否还存在。 ```Bash docker ps -a | grep hermes-agent docker images | grep hermes-agent ls -la /root/.openclaw/extensions | grep openclaw-plugin-hermes ``` 若所有命令均无回显内容，表示已完整卸载 Hermes Agent 插件。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_fcb9c76472e34f6797c9c51a5e2b2930.png) ### 可以通过 ArkClaw 集成的渠道（例如飞书、微信）使用 Hermes Agent 吗？可以，您在 ArkClaw 控制台开启 Hermes 功能后，可在 ArkClaw 集成的渠道（例如飞书、微信）中发送如下快捷指令进行切换即可。 * `/model hermes`：切换至 Hermes 处理后续所有任务。 * `/model ark`：切换至 ArkClaw 处理后续所有任务。 ### 如何读取 Hermes 生成的文件？ Hermes 目前在 Docker 容器内运行，如需进行文件传输，可使通过 Prompt 让 Hermes 将文件生成或移动至 `/opt/data` 目录，之后可以 [通过终端访问 ArkClaw](https://www.volcengine.com/docs/87732/2270411) 并在 `/opt/data-hermes` 目录中查看对应文件。 ### 提示“OpenClaw 配置文件不是有效 JSON:/root/.openclaw/openclaw.json”如何解决？您可以参考如下步骤，修复该问题： 1. [自动修复 ArkClaw](https://www.volcengine.com/docs/87732/2270355)。 2. 单击“Hermes \> 安装插件”按钮，[重新安装 Hermes Agent 插件](https://www.volcengine.com/docs/87732/2356398#AftdJI5y)。 ### 如何更换 Hermes Agent 使用的模型？暂不支持通过 ArkClaw 控制台更新 Hermes Agent 使用的模型，您可以根据如下指引完成调整： 1. [打开 ArkClaw 终端](https://www.volcengine.com/docs/87732/2270411)。 2. 执行如下命令，下载更换 Hermes Agent 使用模型的脚本。 ```Bash REGION=$(curl --connect-timeout 5 --max-time 10 -s "http://100.96.0.96/latest/region_id"); curl -fsSL "https://scarif-${REGION}.tos-${REGION}.ivolces.com/arkclaw/hermes/hermes-model-switch.sh" -o hermes-model-switch.sh ``` 3. 按需执行对应命令，通过脚本更新 Hermes Agent 使用的模型。仅更换模型当您仅需更换模型，无需调整提供商或调用地址时，请使用此方式。

注意

本场景命令执行过程将重启运行 Hermes Agent 的 Docker 容器，可能导致其正在运行的任务中断，请在其空闲时进行操作。

```Bash bash hermes-model-switch.sh --model ```

说明

请将替换为您希望 Hermes Agent 使用的目标模型名称。

若您使用方舟 Coding Plan 模型，支持的模型名称可查看模型配置。

若您使用方舟模型广场模型，请填写目标模型 ID。

更换模型及服务提供商当您不仅需要更换模型，还需要调整模型提供商或调用地址时，请使用本方式。

注意

本场景命令执行过程将删除运行 Hermes Agent 的 Docker 容器并进行重建。容器内的数据（除持久化目录外）将被删除且无法找回，请谨慎操作。持久化目录 /opt/hermes-data（对应容器内 /opt/data目录）中的数据在容器重建后仍会保留，无需额外备份。

```Bash bash hermes-model-switch.sh --api-key --model --base-url ```

说明

请将替换为调用目标模型的实际 API Key。

请将替换为目标模型名称，例如：doubao-seed-2-0-lite-260215。

请将替换为调用目标模型的URL，例如：https://ark.cn-beijing.volces.com/api/v3。

### Hermes 执行任务时报错“ACP error [\-32603]: Internal error”如何解决？该问题通常是由于 Hermes 使用的推理模型配置不正确，或对应模型已达到限额导致的。您可以： * [更换 Hermes Agent 使用的模型](https://www.volcengine.com/docs/87732/2358943#c1jbs5Xr)。 * 等待对应模型恢复额度。例如：使用火山方舟 Coding Plan 时，可前往 [Coding Plan 控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe)，查看超限情况并了解额度刷新时间。 ### 如何查看 Hermes Agent 使用的推理模型信息？您可以通过 Hermes Agent 配置文件 `/opt/hermes-data/config.yaml`，了解其使用的推理模型信息。 1. [打开 ArkClaw 终端](https://www.volcengine.com/docs/87732/2270411)。 2. 执行如下命令，查看 Hermes Agent 使用的推理模型。 ```Bash cat /opt/hermes-data/config.yaml | grep default: | head -n 1 ``` 回显如下所示时，表示当前 Hermes Agent 使用的是 `doubao-seed-2-0-code-preview-260215` 模型。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d801e02411b810f2288c5f35cca04c95.png)

ArkClaw 企业版