应采用与语义化版本兼容性机制深度对齐的平滑升级路径：一、用hermes_cli内置upgrade命令自动合并配置；二、git分支手动切换并重装；三、跨主版本时导出-初始化-迁移-验证；四、容器环境镜像热替换。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在运行旧版本的Hermes Agent，但希望获得新功能、修复或配置优化，同时避免破坏现有记忆索引、技能沉淀和OpenClaw迁移成果，则需采用与语义化版本兼容性机制深度对齐的升级路径。以下是多种可行的平滑升级方案：
一、使用hermes_cli内置升级命令
该方法适用于所有通过pip或源码安装且保留了CLI工具链的部署场景，利用项目内建的版本检查与依赖同步逻辑，确保配置合并机制（_deep_merge）自动生效。
1、打开终端或命令行界面，确认当前已激活Hermes Agent运行环境。
2、执行hermes-cli upgrade命令，系统将自动检测远程最新稳定版本（如v0.8.0）及本地当前版本。
3、确认升级提示后，工具将拉取新版本包、备份原有config.py与workspace/目录结构，并调用_deep_merge函数完成默认配置与用户自定义配置的深度融合。
4、升级完成后，运行hermes-cli health-check验证记忆索引服务、技能加载器及MCP网关连接状态。
二、基于Git分支的手动版本切换
该方法适用于从GitHub源码构建、需精确控制修订号或需回滚至特定次版本的高级用户，可绕过包管理器限制，直接复用现有workspace路径与数据目录。
1、进入Hermes Agent项目根目录，执行git fetch origin同步全部远程分支与标签。
2、运行git tag --sort=version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | tail -n 5查看最近五个语义化版本标签。
3、检出目标版本，例如git checkout v0.8.0，确保工作区处于干净状态（无未提交修改）。
4、执行pip install -e . --force-reinstall --no-deps仅重装当前代码，跳过依赖重复安装，保留已配置的模型路径、Nous Portal凭证及datagen-config-examples/映射关系。
OpenClaw专家 — 用于任何OpenClaw问题或需求，包括配置错误、网关崩溃、网关未启动、斜杠指令、频道路由等。
5、启动代理前，手动确认hermes_cli/config.py中DEFAULT_CONFIG结构与user_config.yaml字段无键冲突，若存在主版本变更（如v0.7.x → v1.0.0），必须查阅对应版本CHANGELOG.md中的迁移字段说明。
三、跨主版本的迁移式升级
当升级涉及主版本号变更（例如从v0.x系列升至v1.0.0），配置结构发生不兼容改动时，必须启用迁移式流程，以保障历史记忆索引与技能库的可读性延续。
1、在旧版本环境下执行hermes-cli export-workspace --format json --output backup_v0.7.json，导出完整workspace快照，含MEMORY_INDEX、SKILL_REGISTRY及对话元数据。
2、全新安装目标主版本（如v1.0.0），初始化空白workspace，运行一次hermes-cli init生成适配新版schema的默认结构。
3、调用迁移工具：hermes-cli migrate-from-json --input backup_v0.7.json --target-version 1.0.0，该命令将自动映射旧版字段至新版配置键，并对已沉淀技能执行AST级语法校验与重编译。
4、迁移完成后，必须运行hermes-cli verify-memory-integrity验证索引哈希一致性，防止因向量嵌入维度变化导致检索失效。
四、容器化环境的镜像热替换升级
该方法专为Docker或Podman部署设计，通过镜像标签绑定语义化版本，实现零停机配置热加载与服务平滑过渡。
1、拉取新版镜像：docker pull ghcr.io/nous-research/hermes-agent:v0.8.0。
2、停止当前容器但保留卷挂载：docker stop hermes-agent-main，注意卷路径如/opt/hermes/workspace不得被删除。
3、以相同环境变量与卷映射启动新镜像：docker run -d --name hermes-agent-main -v /opt/hermes/workspace:/app/workspace -e MODEL_GATEWAY_URL=https://api.nous.xyz -p 8080:8080 ghcr.io/nous-research/hermes-agent:v0.8.0。
4、新容器启动后，检查日志输出中是否出现Merged user config with v0.8.0 defaults字样，确认_deep_merge已触发且未跳过自定义插件路径。
