安装后hermes命令报错是因PATH未生效，需执行source ~/.bashrc（Linux/macOS）或以管理员身份重启PowerShell（Windows）；模型显示unknown是因未配置config.yaml和.env；飞书接入失败需在config.yaml中启用网关路由并配置profiles/feishu-prod.yaml。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
新手装 Hermes Agent v0.19.0 时，常在安装完成的瞬间就卡住——命令行敲 hermes 报 command not found，以为装失败了，其实只是 PATH 没生效；或刚配完 API Key 就发现模型显示 unknown，翻遍文档也找不到 config.yaml 该放哪、字段怎么填；还有人用 Windows PowerShell 装完，关掉窗口重开又得重装一遍，因为没用管理员权限写入系统路径。
装完命令找不到：PATH 没刷新是主因
安装脚本确实把 hermes 可执行文件放进了 ~/.local/bin（Linux/macOS）或 %LOCALAPPDATA%\hermes\bin\（Windows），但它只写进了 shell 配置文件（如 ~/.bashrc），当前终端并不知道。
第一步：验证是否真写进去了
运行 which hermes（Linux/macOS）或 where hermes（Windows PowerShell），有输出才算落盘成功。空返回说明脚本中途失败或权限不足。
第二步：强制加载配置
Linux/macOS 用户执行 source ~/.bashrc；zsh 用户执行 source ~/.zshrc；Windows PowerShell 必须关闭当前窗口→重新以管理员身份打开→再试。【不重启终端或不重载配置，hermes setup 会把所有配置写进错误路径，后续全白配】
第三步：手动补 PATH（仅当前两步无效时）
Linux/macOS：执行 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc；Windows：右键“此电脑”→属性→高级系统设置→环境变量→在“用户变量”的 PATH 里新增一行：%LOCALAPPDATA%\hermes\bin。
模型显示 unknown：config.yaml 和 .env 没配对
这是新手最懵的环节——装完就能跑 demo 吗？不能。v0.19.0 默认不带任何模型配置，必须手动指定 provider、base_url、model name 才能启动推理链。
方法一：用 hermes setup 交互式生成（推荐）
确保已刷新 PATH 后，运行 hermes setup → 选 “Configure model provider” → 按提示填 OpenAI / DeepSeek / Ollama 等对应字段。它会自动生成 ~/.hermes/config.yaml 和 ~/.hermes/.env，API Key 写进 .env，其他结构化参数写进 config.yaml。
方法二：手写 config.yaml（适合已有 API 的老用户）
在 ~/.hermes/ 下新建 config.yaml，内容至少包含：provider: openaibase_url: https://api.openai.com/v1model: gpt-4o
然后在同目录建 .env，写 OPENAI_API_KEY=sk-xxx。注意：字段名大小写敏感，model 不能写成 model_name，否则启动时直接 fallback 到 unknown。
【provider 字段必须与 .env 中的密钥前缀严格匹配：填 openai → .env 里必须是 OPENAI_API_KEY；填 deepseek → 必须是 DEEPSEEK_API_KEY】
统一LLM网关 - 一个API对接70+AI模型，使用单一API密钥即可调用GPT、Claude、Gemini、Qwen、Deepseek、Grok等主流模型。
飞书/Telegram 接入失败：网关 Profile 路由未启用
v0.19.0 开始，飞书、Discord、Telegram 等平台不再默认启用网关，必须显式声明路由规则，否则消息发进来就石沉大海。
打开 ~/.hermes/config.yaml，在末尾添加：gateway: profile_routes: - platform: feishu app_id: "你的飞书App ID" profile: feishu-prod
然后为该 profile 单独建配置文件：~/.hermes/profiles/feishu-prod.yaml，内容至少含：provider: openaimodel: gpt-4o-minimemory: sqlite
改完保存，重启 Hermes：hermes gateway --reload。若仍连不上，检查飞书后台的「IP 白名单」是否加了 Hermes 服务器出口 IP——v0.19.0 不再自动透出真实 IP，需手动配置。
升级后还连不上飞书：remote 源冲突导致更新卡死
从 v0.17 升级到 v0.19.0 的用户，常见现象是：终端显示 “Update completed”，但客户端仍弹窗提示 “update available”，点进去版本还是旧的。
根因是本地 git remote 存在两个源：origin（官方）和 upstream（社区镜像），hermes update 默认拉 origin，但部分社区版构建包绑定了 upstream 的 commit hash，造成校验失败。
运行 git -C ~/.hermes/hermes-agent remote -v 查看远程列表。如果看到两行 origin（一个 fetch 一个 push）或同时存在 origin/upstream，执行：cd ~/.hermes/hermes-agent && git remote remove upstream && git remote set-url origin https://github.com/NousResearch/hermes-agent.git
然后清理缓存：hermes cache clear → 再执行 hermes update。这一步必须做完才能继续配飞书 webhook。
