Hermes Agent配置疏漏会导致命令不可用、密钥失效等问题，需依次验证Python版本（≥3.11）、Git等基础工具、API密钥格式与环境变量、PATH路径注入，以及国内网络镜像配置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已完成Hermes Agent基础安装，但在首次运行时遇到命令不可用、密钥失效、依赖缺失或环境冲突等问题，则很可能是配置环节存在疏漏。以下是覆盖99%新手常见安装问题的系统性配置清单：
一、验证并修正Python环境版本
Hermes Agent严格要求Python 3.11及以上版本运行，全局Python版本过低或过高（如3.13）均会导致依赖编译失败或pyo3扩展崩溃。安装脚本虽会创建3.11虚拟环境，但系统级Python若被误调用仍会触发报错。
1、在终端中执行python3 --version或python --version确认当前默认Python版本。
2、若显示低于3.11（例如3.9.7），需升级：Ubuntu用户执行sudo apt install -y python3.12 python3.12-venv；macOS用户执行brew install python@3.12。
3、若显示为3.13或更高，需强制隔离：运行uv python install 3.11，再通过uv venv --python 3.11 ~/.hermes/venv重建专用环境。
4、激活新环境后，验证python -c "import sys; print(sys.version)"输出是否为3.11.x。
二、确保Git与基础工具链就绪
Git是唯一必须手动安装的前置依赖，用于克隆仓库及后续技能更新；ripgrep（rg）、ffmpeg、Node.js等由安装脚本自动处理，但若脚本中断或跳过检测，将导致工具调用功能异常或搜索类Skill失效。
1、执行git --version检查Git是否存在，若提示command not found，则需下载安装：Windows用户从git-scm.com获取安装包，Linux用户执行sudo apt install git -y，macOS用户执行brew install git。
2、运行rg --version验证ripgrep，缺失时Ubuntu用户执行sudo apt install ripgrep，macOS用户执行brew install ripgrep。
3、执行node --version确认Node.js ≥18，若未安装或版本过低，使用nvm管理：curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash，随后nvm install 20 && nvm use 20。
4、检查ffmpeg -version输出，缺失则按系统对应方式补装，Ubuntu执行sudo apt install ffmpeg，macOS执行brew install ffmpeg。
三、正确配置API密钥与环境变量
API密钥未加载或格式错误是Authentication failed、API key not found等错误的主因。Hermes仅读取~/.hermes/.env文件中的OPENAI_API_KEY=行，且对空格、换行、引号极度敏感。
1、确保~/.hermes/.env文件存在，若不存在则手动创建：mkdir -p ~/.hermes && touch ~/.hermes/.env。
2、使用文本编辑器打开该文件，写入单行：OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx，注意不得添加任何空格、引号或注释。
Qwen 视频智能分析基础客户端（免费版），基于 Qwen 3.5 Plus 多模态模型对本地视频进行内容分析，支持场景描述与基础内容理解，采用默认抽帧频率和提示词，适合快速概览视频，API Key 读取自 ~/.skill-platform/skill-platform.json 的 skills 配置。
3、确认密钥本身有效：前往对应平台（如OpenAI Platform）检查Key状态、配额及模型访问权限。
4、若使用非OpenAI服务（如DashScope、OpenRouter），需额外设置HERMES_MODEL_PROVIDER和HERMES_MODEL_NAME，例如：HERMES_MODEL_PROVIDER=dashscope与HERMES_MODEL_NAME=qwen-max。
四、修复PATH与命令可执行性
安装完成后输入hermes提示command not found，本质是可执行文件路径未纳入系统PATH。一键安装脚本默认将二进制写入$HOME/.local/bin，但该路径未被当前shell会话识别。
1、检查当前PATH是否包含该路径：echo $PATH | grep local，若无输出则需注入。
2、Bash用户执行：echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc。
3、Zsh用户执行：echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc。
4、验证生效：which hermes应返回/home/用户名/.local/bin/hermes（Linux/WSL）或/Users/用户名/.local/bin/hermes（macOS）。
五、处理国内网络连接异常
安装过程卡在GitHub克隆、pip源超时、或技能市场连接失败，基本可判定为直连GitHub与PyPI受阻。无需梯子，可通过镜像或代理快速绕过。
1、替换安装脚本URL：使用国内加速地址执行一键安装：curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash。
2、为pip配置清华源：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple。
3、若需手动克隆，改用镜像仓库：git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git ~/.hermes/hermes-agent。
4、启动后首次执行hermes setup若卡在“Fetching skill market”，可在交互中选择Skip skill market initialization，后续联网稳定后再运行hermes skill update。
