新手配置hermes agent必须严格遵循五步：一、确认git与python 3.10+可用；二、按优先级（命令行＞.env＞环境变量）配置api key；三、校验config.yaml中model字段顶格、provider值准确、base_url格式正确；四、运行hermes memory init初始化记忆文件并验证权限与状态；五、检测浏览器/shell依赖存在后，执行hermes tools refresh再启用工具。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您刚接触 Hermes Agent，但在配置过程中频繁遇到模型无法调用、记忆不生效或工具无响应等问题，则很可能是关键配置步骤被跳过或执行错误。以下是新手配置中必须严格遵循的关键步骤解析：
一、确认系统与前置依赖完整性
该步骤确保 Hermes Agent 运行环境底层稳定，避免因缺失基础组件导致后续所有配置失效。Hermes 依赖 Git 和 Python 3.10+，且安装脚本不会自动降级或修复损坏的 Python 环境。
1、检查 Git 是否可用：在终端输入 git --version，若返回“command not found”，需按系统安装 Git。
2、验证 Python 版本：运行 python3 --version 或 python --version，确认输出为 3.10.x 或更高版本。
3、确认 pip 可用性：执行 pip list，若报错“no module named pip”，需手动安装 pip 或重装 Python。
二、API Key 配置的三种等效方式及优先级判定
Hermes 通过环境变量、.env 文件或命令行参数加载 API Key，但三者存在明确的覆盖顺序：命令行参数 > .env 文件 > 系统环境变量。若同时存在多处配置，低优先级项将被静默忽略，极易造成“已填密钥却报认证失败”的假象。
1、使用 hermes config set 命令写入（最高优先级）：hermes config set OPENAI_API_KEY sk-xxx。
2、编辑 ~/.hermes/.env 文件（推荐长期使用）：用 nano 或 vim 打开后，在新行添加 OPENAI_API_KEY=sk-xxx，保存退出。
3、临时设置环境变量（仅当前终端会话有效）：export OPENAI_API_KEY="sk-xxx"，随后必须运行 source ~/.bashrc 或重新启动终端才可能被加载（取决于 shell 类型）。
三、config.yaml 中主模型配置的字段校验规则
config.yaml 的 model.default 区块是 Hermes 启动时默认加载的模型入口，任意字段拼写错误或层级错位都会导致模型初始化失败，且错误日志中不提示具体哪一行出错。
1、确认 model 字段位于文件顶层，不可嵌套在其他 key 下：model: 必须顶格书写，后接换行与缩进。
2、provider 字段值必须与 Hermes 支持列表完全一致：provider: openai（不可写作 open_ai、OpenAI 或 openai-api）。
3、base_url 若非空，必须以 https:// 开头且末尾不含斜杠：base_url: https://api.openai.com/v1（https://api.openai.com/v1/ 将触发连接拒绝）。
四、记忆系统启用前的强制初始化操作
Hermes 的双层记忆（USER.md + MEMORY.md）不会在首次启动时自动创建，必须显式触发初始化，否则所有用户偏好、对话历史、技能上下文均无法持久化。
1、运行初始化命令：hermes memory init，该命令生成 ~/.hermes/memories/ 目录及两个空白 Markdown 文件。
2、检查文件权限：执行 ls -l ~/.hermes/memories/，确认 USER.md 与 MEMORY.md 均为当前用户可读写（权限码应含 rw-）。
3、验证记忆服务状态：hermes memory status，预期输出包含 “status: active” 与 “backend: file”。
五、工具模块启用时的依赖冲突规避
启用浏览器控制（browser）、Shell 执行（shell）等工具时，Hermes 会尝试调用系统命令，若对应二进制不存在或版本过旧，将静默禁用该工具而非报错，导致功能“看似启用实则无效”。
1、检测浏览器工具依赖：which chromium-browser || which google-chrome || which firefox，至少一项需返回路径。
2、验证 Shell 工具可用性：sh -c 'echo test' && bash -c 'echo test'，两行均需输出 test。
3、启用工具前先刷新缓存：hermes tools refresh，避免旧缓存中残留已卸载工具的残余声明。
