404错误需按五步修复：一、验证github连通性并切换dns；二、重建~/.hermes目录并重置配置；三、手动更新网关插件manifest缓存；四、安装缺失工具如ripgrep/ffmpeg；五、直连raw.githubusercontent.com ip绕cdn污染。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试运行 Hermes Agent，但频繁收到 404 错误（如请求模型端点、加载插件、拉取配置或访问网关资源时返回 HTTP 404 Not Found），则很可能是由于环境依赖缺失、路径配置错误、远程服务不可达或本地缓存指向已失效的旧地址所致。以下是修复此问题的步骤：
一、验证并修复 GitHub 资源拉取失败导致的 404
安装脚本与网关组件常通过 raw.githubusercontent.com 加载配置模板、插件清单或 CLI 补丁；若该域名解析异常、被拦截或 URL 路径变更，将直接触发 404。此问题在企业网络、DNS 污染或 GitHub 服务临时调整期间尤为常见。
1、测试 GitHub 原始内容服务连通性：curl -I https://raw.githubusercontent.com
2、若返回 404 或超时，手动切换 DNS 并刷新解析缓存：echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf && sudo systemd-resolve --flush-caches
3、若确认 raw.githubusercontent.com 可访问但特定路径 404，检查当前 Hermes Agent 版本是否引用了已归档的旧仓库分支；执行 hermes version --verbose 查看 commit hash，并比对官方 GitHub 仓库对应 tag 的文件结构。
二、重建 ~/.hermes 目录并重置配置路径
Hermes Agent 将核心配置、插件元数据及缓存索引默认写入 ~/.hermes 目录；若该目录中存在损坏的 config.yaml、plugins.json 或 stale manifest 文件，Agent 在初始化阶段会尝试读取已删除或重命名的远程 URL，从而抛出 404。
1、备份现有配置（可选）：mv ~/.hermes ~/.hermes.backup-$(date +%s)
2、强制清除残留配置与缓存：rm -rf ~/.hermes && mkdir -p ~/.hermes
3、重新运行完整配置向导，确保生成标准路径结构：hermes setup
三、手动校验并更新网关插件注册表
飞书、微信、Telegram 等网关插件依赖动态加载的 manifest.json 描述文件，其 URL 由 Hermes 内部 registry 维护；若 registry 缓存了已下线插件的旧地址（例如 v0.12 插件在 v0.13 中被移除），调用时将返回 404。
1、查看当前激活的网关插件列表：hermes gateway list
2、定位插件 manifest 缓存路径：ls -la ~/.hermes/gateway/manifests/
Hermes Agent (v0.8.0) 是由 Nous Research 开发的开源自进化 AI 智能体，被誉为“与你共同成长的 Agent”。其核心优势在于内置学习闭环，能从任务中自动提炼技能、持久记忆用户偏好，越用越懂你。该版本聚焦“智能”升级，支持后台任务自动通知、模型实时切换及 MCP OAuth 2.1。它兼容 200+ 主流大模型，支持微信、Telegram 等多平台接入，仅需 5
3、对报错插件（如提示 Failed to fetch manifest for feishu@v0.12），手动删除对应版本文件：rm ~/.hermes/gateway/manifests/feishu-v0.12.json
4、强制刷新插件索引：hermes gateway refresh
四、修复系统级工具缺失引发的间接 404
部分网关协议（如微信扫码登录、飞书卡片渲染）依赖 ripgrep 提取 token、ffmpeg 解析媒体响应头或 curl 处理重定向；若这些工具缺失或版本过旧，Hermes 可能静默降级为 HTTP GET 请求并拼接错误 endpoint，最终返回 404。
1、运行诊断命令识别缺失项：hermes doctor
2、根据输出中 MISSING 条目安装对应工具：Ubuntu/Debian 用户执行 sudo apt install -y ripgrep ffmpeg curl
3、macOS 用户执行 brew install ripgrep ffmpeg curl
4、验证工具可用性：rg --version && ffmpeg -version | head -n1 && curl --version | head -n1
五、绕过 CDN 缓存污染强制直连原始端点
某些地区运营商 CDN 会缓存 GitHub raw 内容，但未及时同步上游删除操作，导致本地持续命中已 404 的旧 URL。此时需禁用 CDN 并直连 GitHub IP。
1、获取 raw.githubusercontent.com 当前权威 IP：dig +short raw.githubusercontent.com @114.114.114.114
2、将返回的 IPv4 地址（如 185.199.108.133）写入 hosts：echo "185.199.108.133 raw.githubusercontent.com" | sudo tee -a /etc/hosts
3、清空本地 DNS 缓存：sudo systemd-resolve --flush-caches
4、重启 Hermes Agent 并观察日志中是否仍出现相同 404 路径。
