hermes agent v0.19.1启动失败需四步修复：一、确认hermes --version为v0.19.1且hermes doctor显示pydantic 1.10.17（incompatible）；二、rm -rf ~/.hermes/venv后执行hermes setup重建环境；三、将config.yaml中model.default改为openai/gpt-4o，确保.env中openai_api_key未被注释且无空格；四、pkill -f "hermes"后hermes start --foreground验证端口绑定与技能加载。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Mac用户升级Hermes Agent到v0.19.1后启动异常，常见表现为终端执行hermes start后立即退出、无日志输出或报错ModuleNotFoundError: No module named 'pydantic.v1'——这是v0.19.1强制切换Pydantic v2后，旧虚拟环境中残留v1兼容层引发的典型冲突。
确认是否真为v0.19.1升级导致的启动失败
先验证当前版本与异常关联性：运行hermes --version，若输出含v0.19.1且紧接着报错，说明问题确由本次升级触发；若版本仍显示旧版（如v0.18.7），则实际未完成升级，跳过本流程，改走hermes update重试。
执行hermes doctor，重点观察输出中pydantic一行：若显示pydantic 1.10.17 (incompatible)，即锁定根源——v0.19.1不再支持Pydantic v1，但旧venv未清理干净。
清除旧虚拟环境并重建
Mac上Hermes默认将venv建在~/.hermes/venv，v0.19.1升级脚本不会自动删除旧环境，必须手动干预。
执行rm -rf ~/.hermes/venv，这一步不可跳过——残留的pydantic.v1模块会污染新环境。
运行hermes setup，该命令会重新创建Python 3.11虚拟环境，并安装v0.19.1所需全部依赖，包括pydantic>=2.8.0和pydantic-settings>=2.4.0。
【注意】不要用pip install --upgrade hermes-agent单独升级包——Mac的Homebrew或uv管理器可能绕过Hermes内置的依赖解析逻辑，导致pydantic版本错乱。
修复模型配置兼容性断点
v0.19.1对config.yaml中模型字段校验更严格，旧版允许的openai/gpt-4写法会被拒绝，必须升级为openai/gpt-4o或openai/gpt-4-turbo。
打开~/.hermes/config.yaml，定位model.default:行，将值改为官方支持的新格式，例如：model.default: openai/gpt-4o。
同步检查~/.hermes/.env，确保OPENAI_API_KEY=sk-...值末尾无空格，且该行未被#注释掉——v0.19.1读取.env时遇到注释行会中断解析，直接报KeyError: 'OPENAI_API_KEY'。
执行hermes config validate，若输出✅ Configuration is valid，说明配置已通过v0.19.1校验；若报错，按提示修正yaml缩进或缺失字段。
启动并验证网关端口绑定
v0.19.1默认启用网关组件，且将监听端口从8080改为9090，若旧进程残留会抢占端口。
第一步：杀掉所有残留进程——pkill -f "hermes"，这比单次hermes stop更彻底，避免后台守护进程僵死。
第二步：手动前台启动Agent并捕获实时日志——hermes start --foreground，观察终端输出是否出现INFO Starting Hermes Agent on http://localhost:8080或INFO Gateway listening on http://localhost:9090。
若卡在Loading skills...超过30秒，说明某项Skill加载超时，此时需进入~/.hermes/skills/目录，临时重命名疑似有问题的自定义Skill文件夹（如my_custom_tool/ → my_custom_tool.bak），再重试启动。
