命令不可用、网络异常或Python版本不兼容是hermes调用失败主因：一、重载~/.bashrc或~/.zshrc使PATH生效；二、换国内镜像源或配Git代理解决GitHub拉取失败；三、确保Python为3.11，高/低版本需分别处理；四、pip用清华源加速；五、hermes doctor失败时检查uv、权限及网络。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已完成Hermes Agent本地部署脚本执行，但无法通过命令行调用hermes或服务启动失败，则很可能是环境变量未生效、网络连接异常或Python版本不兼容所致。以下是解决此类问题的步骤：
一、命令不可用（hermes: command not found）
该问题通常因安装脚本将可执行文件路径写入Shell配置文件后未重新加载导致，当前终端会话无法识别新安装的命令。
1、确认安装路径是否已写入Shell配置文件：执行cat ~/.bashrc | grep "local/bin"（Bash用户）或cat ~/.zshrc | grep "local/bin"（Zsh用户）。
2、若存在相关export语句，执行source ~/.bashrc（Bash）或source ~/.zshrc（Zsh）强制重载配置。
3、若仍未生效，手动追加路径：执行echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc（Bash）或echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc（Zsh），再执行对应source命令。
4、验证是否成功：输入echo $PATH，确认输出中包含/home/用户名/.local/bin（Linux/macOS）或%USERPROFILE%\AppData\Local\bin（Windows WSL2）。
二、安装过程卡在GitHub克隆阶段
国内直连GitHub常因网络策略导致超时或连接中断，官方安装脚本首步即拉取远程资源，因此极易在此环节停滞。
1、使用国内加速镜像替代原始URL：执行curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash。
2、若加速镜像不可用，改用GitCode镜像手动安装：执行git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git ~/.hermes/hermes-agent。
3、进入项目目录：cd ~/.hermes/hermes-agent。
4、运行本地安装脚本：bash scripts/install.sh --local。
5、如具备代理条件，可配置Git全局代理：git config --global https.proxy http://127.0.0.1:7890，并确保代理服务正在运行。
三、Python版本冲突引发依赖报错
Hermes Agent明确要求CPython 3.11运行时，部分系统默认Python为3.9或3.13，前者导致模块缺失，后者引发pyo3/tiktoken等C扩展编译失败。
1、检查当前Python版本：python3 --version或python --version。
2、若版本低于3.11，执行sudo apt install -y python3.12 python3.12-venv python3.12-dev（Ubuntu/Debian）或brew install python@3.12（macOS）。
3、若版本高于3.11（如3.13），需显式指定安装脚本使用3.11：在执行安装命令前，设置环境变量export HERMES_PYTHON_VERSION=3.11。
4、验证虚拟环境是否正确创建：安装完成后，执行hermes doctor，确认输出中Python: OK且版本号显示为3.11.x。
四、依赖包安装超时或失败
pip从PyPI下载依赖时受网络影响显著，尤其涉及large-model相关包（如transformers、torch）时易触发超时或校验失败。
1、临时使用清华源安装单个依赖：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ torch。
2、配置pip全局镜像源：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/。
3、若仍失败，尝试跳过依赖校验：pip install --trusted-host pypi.tuna.tsinghua.edu.cn -i https://pypi.tuna.tsinghua.edu.cn/simple/ transformers。
4、对于特定缺失工具（如ripgrep），单独安装：sudo apt install -y ripgrep（Ubuntu/Debian）或brew install ripgrep（macOS）。
五、安装后hermes doctor检测失败
该命令用于诊断基础运行环境，若返回Environment: FAIL或Python: FAIL，说明核心依赖链断裂或权限异常。
1、检查uv是否正常安装：uv --version，若提示command not found，需手动安装uv：curl -LsSf https://astral.sh/uv/install.sh | sh。
2、确认~/.local/bin是否在PATH中且具有执行权限：ls -l ~/.local/bin/hermes，若无x权限，执行chmod +x ~/.local/bin/hermes。
3、查看doctor详细日志：hermes doctor --verbose，定位具体失败项（如network、git、python-interpreter）。
4、若提示network检测失败，测试GitHub连通性：curl -I https://github.com，返回HTTP 200即正常，否则需启用代理或更换DNS。
