Hermes Agent自动更新失败需手动拉取代码并重装：一、确认Git部署形态并进入根目录；二、git fetch+submodule update同步主干与子模块；三、删除旧venv，用Python 3.11/3.12重建并重装依赖；四、校验hermes-cli命令与配置路径；五、执行setup.py构建并启动服务。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试运行 Hermes Agent 的自动更新脚本，但命令无输出、报错退出或提示“command not found”“No such file or directory”，则可能是由于脚本路径失效、Git 仓库结构变更、权限丢失或 Python 环境未正确挂载所致。以下是恢复更新能力的手动拉取代码与重新编译流程：
一、验证当前部署形态并进入项目根目录
区分源码安装与容器化部署是执行手动编译的前提。若未保留原始 git 工作区，则无法使用 git pull；此时需重建完整源码树。该步骤确保后续操作作用于真实可编译的代码基线。
1、检查是否存在 .git 目录以确认是否为 Git 克隆部署：ls -la ~/.hermes/hermes-agent/.git
2、若存在且输出为目录结构，进入该目录：cd ~/.hermes/hermes-agent
3、若不存在，需先重建源码：mkdir -p ~/.hermes/hermes-agent && cd ~/.hermes/hermes-agent
4、确认当前用户对目录具备读写权限：ls -ld ~/.hermes/hermes-agent
二、手动拉取最新主干代码并同步子模块
自动更新脚本失效常因子模块（如 tinker-atropos）未同步导致依赖链断裂。手动执行 git fetch + submodule update 可绕过脚本逻辑缺陷，强制补全所有嵌套组件。
1、执行远程分支同步：git fetch origin main
2、检出最新稳定提交（非 dev 分支）：git checkout `git rev-list -n 1 --first-parent origin/main`
3、初始化并更新全部子模块：git submodule update --init --recursive
4、若提示 tinker-atropos 子模块克隆失败，手动指定镜像地址：git config --file .gitmodules submodule.tinker-atropos.url https://ghfast.top/https://github.com/nousresearch/tinker-atropos.git
5、再次执行子模块更新：git submodule sync && git submodule update --init --recursive
三、重建 Python 环境并强制重装依赖
原生 venv 可能残留旧版包缓存或冲突 wheel，导致 hermes-cli 命令不可用。通过删除旧环境并基于当前 requirements.txt 完整重装，可消除 pip 冲突与 ABI 不兼容问题。
1、定位并移除现有虚拟环境：rm -rf ~/.hermes/hermes-agent/.venv
2、创建新虚拟环境（限定 Python 3.11 或 3.12）：python3.12 -m venv ~/.hermes/hermes-agent/.venv
3、激活环境：source ~/.hermes/hermes-agent/.venv/bin/activate
4、升级 pip 至最新兼容版本：pip install --upgrade pip==23.3.1
5、安装核心依赖并跳过预编译轮子（规避 manylinux 冲突）：pip install -r requirements.txt --no-binary :all:
6、以开发模式安装 Hermes Agent 主体：pip install -e . --force-reinstall
四、校验 CLI 可用性与配置路径映射
重装后需确认 hermes-cli 是否被正确注册至 PATH，且其内部配置解析路径指向用户实际数据目录。否则即使编译成功，运行时仍会加载默认空配置或报 config.py not found 错误。
1、验证命令是否可调用：hermes-cli --version
2、检查 CLI 实际解析的配置根路径：hermes-cli info | grep "config_root"
3、若输出非 ~/.hermes，需手动设置环境变量：export HERMES_CONFIG_ROOT=~/.hermes
4、确认 config.py 或 config.yaml 存在于该路径下：ls -l ~/.hermes/config.{py,yaml}
5、若两者皆缺失，从模板生成基础配置：cp ~/.hermes/hermes-agent/hermes_cli/config_template.py ~/.hermes/config.py
五、执行本地编译构建并启动服务
部分功能（如 MCP 网关、技能编译器）需调用 setup.py 构建阶段生成的 C 扩展或字节码缓存。跳过此步将导致 Web UI 加载失败或工具调用无响应。
1、运行构建脚本：python setup.py build_ext --inplace
2、生成 wheel 包用于快速复用：python setup.py bdist_wheel
3、启动后台服务并捕获初始日志：hermes-cli serve --log-level debug 2>&1 | head -n 50
4、检查关键组件加载状态：hermes-cli health-check | grep -E "(memory|skills|models)"
5、若 health-check 中 models 显示 0，需手动触发模型注册：hermes-cli model register --all
