1. 为什么要在本地把 Hermes Agent 和 Ollama 串起来
Hermes Agent 是 Nous Research 推出的开源 agent framework，核心卖点是自动学习 skills、三层记忆结构（MEMORY.md、USER.md、Session Search）以及多平台一致接入。Ollama 则是本地跑大模型最省心的方案之一，一条ollama pull就能把模型拉到本机，暴露一个 OpenAI 兼容的/v1接口。把这两个东西接在一起，你得到的是一个完全跑在自己机器上的长期个人助理：模型推理不出网，记忆存在本地 SQLite，skills 也是自己攒出来的。
这套组合适合谁？三类人最合适。第一类是隐私敏感、不想把项目背景和聊天记录交给云端的人；第二类是手上有闲置 Mac、Linux 小主机或者带独显的机器，想把它变成 7x24 常驻的 agent；第三类是已经在用 Ollama 跑本地模型，但缺一个能记住上下文、能调工具、能自动沉淀经验的壳。Hermes Agent 正好补上这一层。
不过实际部署时，很多人会卡在同一个地方：Hermes 的 setup wizard 默认引导你去选 Claude、OpenAI 这类云端 provider，本地 Ollama 的 endpoint 怎么填、填完为什么连不上、状态栏为什么还显示 Claude，这些细节官方文档写得比较散。这篇就把整条链路拆开，从环境准备、模型拉取、endpoint 配置到连通性验证和报错排查，一步步走完。中途我还会给一个可选的加速方案：如果你某些任务想用更强的云端模型，可以把 endpoint 指向 TaoToken 的兼容接口，本地和云端随时切换，配置方式完全一样，只是 Base URL 和 Key 不同。
先说清楚整体链路长什么样。Ollama 在本机11434端口起一个服务，暴露 OpenAI 风格的/v1/chat/completions；Hermes Agent 通过 "Custom OpenAI-compatible endpoint" 这个 provider 选项去连它；Hermes 自己负责 memory、skills、工具调用和消息平台接入。三者关系是：Ollama 管推理，Hermes 管 agent 逻辑，你的机器管一切。理解了这个分层，后面配置就不会乱。
环境要求不复杂。Linux、macOS、Windows（走 WSL）都行。内存建议 16GB 起步，因为要同时跑 Ollama 模型和 Hermes 的 Python/Node 运行时。如果模型选 20B 级别，显存或统一内存最好有 16GB 以上，否则会频繁 swap，响应慢到没法用。磁盘留 30GB 以上给模型权重。Python 3.10+ 和 Node.js 18+ 是 Hermes 的依赖，安装脚本会自动处理，但系统里最好先有curl和git。
2. 前置准备：装好 Ollama 并拉取本地模型
第一步是把 Ollama 装好。macOS 和 Windows 直接去 ollama.com 下载安装包，Linux 用官方脚本：
curl -fsSL https://ollama.com/install.sh | sh装完确认服务在跑：
ollama --version curl http://localhost:11434/api/tags第二条命令如果返回一个 JSON（哪怕 models 是空数组），说明服务正常。如果报 connection refused，Linux 上检查 systemd 服务systemctl status ollama，macOS 上确认菜单栏有 Ollama 图标。
接下来拉模型。Hermes 对模型的工具调用能力有要求，纯聊天模型跑 agent 会很难受，因为它不会正确输出 tool call 格式。建议选支持 function calling 的模型。20B 级别里gpt-oss:20b是原文用的选择，工具调用比较稳；如果机器弱一点，可以退到qwen2.5:7b或llama3.1:8b，这两个对 tool use 的支持也不错。
ollama pull gpt-oss:20b拉完之后验证模型能正常对话，并且确认它暴露的 OpenAI 兼容接口可用：
curl http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-oss:20b", "messages": [{"role": "user", "content": "say hi in one word"}] }'返回里能看到choices[0].message.content就说明/v1路径通了。这一步很关键，因为 Hermes 走的就是这个接口，如果这里不通，后面配 Hermes 一定失败。注意 Ollama 的/v1接口默认不需要 API key，但有些客户端会强制要求非空，随便填一个字符串即可。
这里插一句关于 endpoint 的选择。本地 Ollama 的地址是http://localhost:11434/v1。如果你想让 Hermes 在某些任务上调用云端更强的模型，可以把 Base URL 换成 TaoToken 的兼容接口https://taotoken.net/api，配上在控制台申请的 API Key，模型 ID 填对应名称。两种配置在 Hermes 里是同一套流程，只是 URL 和 Key 不同，所以你可以本地跑日常、云端跑重活，随时切换。这个思路在后面配置章节会具体展开。
模型拉取还有个坑：Ollama 默认会把模型加载进内存后保持一段时间（默认 5 分钟）才卸载。如果你机器内存紧张，可以设环境变量OLLAMA_KEEP_ALIVE=30s缩短驻留时间，代价是每次调用要重新加载，首次响应变慢。这个权衡自己把握。
3. 安装 Hermes Agent 并配置 Ollama endpoint
装 Hermes 就一条命令：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash脚本会创建虚拟环境、装 Python 和 Node 依赖。装完自动进入 setup wizard，分五步：选 Model 和 Provider、配 Terminal Backend、调 Agent Settings、连 Messaging Platforms、配 Tools。
关键在第一步。Provider 列表里选Custom OpenAI-compatible endpoint，因为 Ollama 的/v1正好是这个形式。然后填：
Base URL: http://localhost:11434/v1 API Key: （本地留空，或随便填一个非空字符串） Model ID: gpt-oss:20b Context Length: 交给 Hermes 自动识别如果你要接 TaoToken 作为云端备选，同一位置填：
Base URL: https://taotoken.net/api API Key: 在 https://taotoken.net/api-keys 申请 Model ID: 控制台里对应的模型名Hermes 的配置最终会落到它的 settings 文件里。以常见的 JSON 结构为例，provider 段落大致长这样，你可以直接对照修改：
{ "provider": { "type": "openai-compatible", "base_url": "http://localhost:11434/v1", "api_key": "ollama", "model": "gpt-oss:20b", "context_length": "auto" }, "agent": { "max_iterations": 60, "tool_progress_display": "all", "context_compression": 0.5 }, "session_reset": { "idle_hours": 24, "daily_at": "03:00" } }注意api_key字段即使本地不需要，也建议填个占位符，因为部分 OpenAI 兼容客户端在 key 为空时会直接抛错。context_compression: 0.5表示上下文用到一半就开始压缩旧消息，配合max_iterations: 60能让长任务不至于爆上下文。session_reset那段是原文提到的稳妥组合：24 小时无操作自动 reset，加每天凌晨固定 reset 一次，重要信息会先被写进 memory 再清会话。
Agent Settings 里另外三项值得留意。Max iterations 设 60 意味着单个任务最多 60 次工具调用，太小会中途断掉，太大可能陷入循环烧 token。Tool Progress Display 设成all能实时看到 agent 在调什么工具，调试期强烈建议开着。Context Compression 前面说了，0.5 是个平衡点。
Messaging Platforms 这一步，本地试跑可以全部跳过，后面想接 Telegram、Discord、Slack 再回来配。Tools 阶段大部分默认开启：网页搜索、浏览器控制、终端访问、文件处理、代码执行、vision、memory。Browser automation 选 Local Browser，TTS 保留默认的 Microsoft Edge TTS，web search 不想接付费服务就用内置的 DuckDuckGo。
如果你机器上装过 OpenClaw，wizard 会检测~/.openclaw并问你要不要迁移配置、memory、skills 和 API keys。老用户直接迁移省事，想干净开始就跳过。
4. 启动验证：确认请求真的走本地模型
配置完启动：
hermes你会看到 dashboard，tools 和 skills 都加载好了。但这里有个高频问题：状态栏默认可能还显示 Claude，而不是你刚配的本地模型。原因是 wizard 里保存的 provider 和实际激活的模型可能不是同一个，需要手动切一次。
退出后执行：
hermes model在列表里选你刚保存的本地 endpoint，模型设为gpt-oss:20b，URL 保持http://localhost:11434/v1。重新hermes启动，状态栏应该显示gpt-oss:20b，说明当前完全本地运行。
验证连通性最直接的办法是发一句话，比如hey, how are you doing today?，看是否快速返回正常响应。同时观察状态栏的模型名和上下文大小，确认链路跑在本机。更严谨的验证是看 Ollama 侧的日志：另开一个终端跑ollama ps，如果能看到gpt-oss:20b处于 loaded 状态，说明 Hermes 的请求确实打到了 Ollama。
再进一步，你可以测一次工具调用，确认 agent 逻辑正常。输入类似「列出当前目录下的文件」，Hermes 应该调用 terminal 工具执行ls并返回结果。如果它只是用文字描述而不真正执行，说明模型的 function calling 没被正确识别，多半是模型选得不对，换qwen2.5:7b或gpt-oss:20b再试。
如果你同时配了 TaoToken 的云端 endpoint，可以用hermes model在两个 provider 之间切换，验证两边都能正常返回。切换后状态栏的模型名会变，这是最直观的确认方式。云端那条链路验证时，建议先用模型对话页面单独测一下 Key 是否有效，排除 Key 本身的问题，再去 Hermes 里配。
实测下来，本地链路首次响应会慢一些，因为 Ollama 要把模型加载进内存。20B 模型在 16GB 内存的 Mac 上首次加载大概十几秒，之后连续对话就快了。如果你觉得首次太慢，可以提前用ollama run gpt-oss:20b把模型预热，再启动 Hermes。
5. 常见报错排查：401、local proxy failed 与 choices 解析失败
这一节按真实会撞到的报错来排。
报错一：401 Unauthorized。本地 Ollama 一般不会 401，出现这个基本是两种情况。一是你把 Base URL 填成了 TaoToken 或别的云端地址，但 Key 没填或填错。去 https://taotoken.net/api-keys 重新生成一个，确认复制时没有多余空格。二是 Ollama 前面挂了反向代理且要求鉴权，检查代理配置。排查动作：先用 curl 直接打http://localhost:11434/v1/chat/completions，如果 curl 通而 Hermes 不通，问题在 Hermes 的 key 字段；如果 curl 也 401，问题在 Ollama 或代理侧。
报错二：local proxy failed / connection refused。这个通常是 Hermes 连不上localhost:11434。原因可能是 Ollama 服务没起，或者 Hermes 跑在容器/WSL 里而 Ollama 在宿主机，localhost指向了不同网络命名空间。排查动作：curl http://localhost:11434/api/tags确认服务活着；如果在 WSL 里，把 Base URL 换成宿主机的实际 IP，或者确认 WSL 的 localhost 转发是否开启。macOS 上如果 Ollama 是 App 形式运行，确认它监听的是127.0.0.1:11434而不是只绑了 IPv6。
报错三：reading choices / index out of range。这个报错说明 Hermes 收到了响应，但解析choices数组时失败。常见原因是模型返回了非标准格式，或者请求被中间层拦截返回了错误 JSON。排查动作：看 Ollama 日志journalctl -u ollama -f（Linux）或 App 的日志窗口，确认模型是否真的返回了choices。如果用的是不支持 OpenAI 格式的模型，换模型。如果中间挂了代理，确认代理没有改写响应体。
报错四：OAuth / token 过期。这个只在接云端 provider 时出现，本地 Ollama 不涉及。如果你切到 TaoToken 后报鉴权失败，去控制台重新签发 Key，并确认 Hermes 配置里的api_key已更新。注意有些客户端会缓存旧 Key，改完配置要重启 Hermes。
报错五：模型加载 OOM。Ollama 报 out of memory，说明模型太大。换更小的量化版本，比如gpt-oss:20b换成 7B 级别，或者用ollama pull时选 q4 量化。同时检查有没有别的进程占着内存。
排查通用思路：先分层定位。curl 直连 Ollama 通不通？通，问题在 Hermes 配置；不通，问题在 Ollama 或网络。Hermes 配置里 Base URL、Key、Model ID 三件套是否齐全且一致？这三个字段任何一个错都会导致失败。最后看日志，Hermes 和 Ollama 两侧的日志对照着看，报错信息基本能定位到具体哪一层。
6. 本地跑通之后：把 endpoint 切换成 TaoToken 的完整做法
本地链路跑通后，你可能会遇到本地模型搞不定的重活，比如复杂代码生成、长文档分析。这时候不用重装 Hermes，只要把 endpoint 切到云端就行。做法和配 Ollama 完全一样，因为都是 OpenAI 兼容接口。
在hermes model里新增一个 provider，填：
Base URL: https://taotoken.net/api API Key: 在 https://taotoken.net/api-keys 获取 Model ID: 控制台里选定的模型名保存后，用hermes model在本地和云端之间切换。日常轻量任务走 Ollama，重活切 TaoToken，记忆和 skills 是共享的，因为 Hermes 的 memory 存在本地，跟 provider 无关。这一点是这套方案最舒服的地方：推理后端可换，agent 的长期记忆不丢。
如果你更偏向长期编码和 Agent 场景，可以了解一下 Coding Plan，它针对这类高频、长上下文的使用做了优化。配置方式还是那三件套：Base URL、Key、Model ID，在 Hermes 里新增 provider 即可。想先验证模型对话是否正常，可以单独用模型对话页面测一轮，确认 Key 有效、模型可用，再回到 Hermes 里配。
切换后记得做一次连通性验证：发一句话看响应，同时确认状态栏模型名变了。如果切换后报 401，回到上一节的排查流程，重点检查 Key 和 Base URL 是否匹配。本地和云端两套配置建议在 settings 文件里都保留，用注释区分，切换时改激活项就行，不用反复重填。
最后给个实用建议：把 Ollama 的OLLAMA_KEEP_ALIVE设长一点（比如30m），这样在 Hermes 里连续对话时模型常驻内存，响应更稳；只在内存紧张时才缩短。另外 Hermes 的 memory 文件（MEMORY.md、USER.md）建议定期备份，这是你长期使用攒下来的核心资产，换机器时直接拷过去就能延续。
