打造专属离线 AI 助手：HermesAgent 联动 Ollama+OpenWebUI 的 config.toml 配置骨架

1. 离线 AI 助手为什么绕不开 config.tomlHermesAgent 是一个可以本地部署的 Agent 网关Ollama 负责在本地跑大模型OpenWebUI 提供聊天界面和知识库。三者拼在一起就是一套不依赖外部网络的专属 AI 助手。很多人卡住的地方不是装不上而是 HermesAgent 的config.toml不知道怎么写模型地址填localhost还是容器名API Key 用哪个工具调用参数怎么开端口怎么对齐。这篇就把这套配置骨架拆开讲清楚你照着改就能跑通。先说清楚适合谁看。如果你手上有一台带独显的机器显存 8G 起步想在内网或者断网环境里跑一个能对话、能调工具的助手这套方案就是给你准备的。HermesAgent 在这里扮演的是「调度中枢」它对外暴露 OpenAI 兼容接口对内把请求转给 Ollama同时管理工具调用和会话。OpenWebUI 则是你日常用的那个网页界面。我试过把三个服务塞进同一个 compose 网络里最容易出问题的就是地址写法。容器之间通信用服务名容器访问宿主机用host.docker.internal这两个搞混了就会一直连接超时。下面从 config.toml 的骨架开始一层层把参数填对。2. TaoToken 前置先把模型出口和 Key 理清楚在纯离线场景里Ollama 就是你的模型出口不需要外部 API。但实际搭建时经常遇到一种情况本地小模型能力不够某些任务想临时走一下云端大模型做补充。这时候就需要一个统一的出口层把本地和云端模型都挂在同一个 OpenAI 兼容接口后面。TaoToken 在这里的作用就是提供这样一个兼容层。它的 API 地址是https://taotoken.net/api接口格式和 OpenAI 一致HermesAgent 的config.toml里只要把base_url指过去再填上对应的 Key就能把云端模型当成一个 provider 来用。本地 Ollama 和云端模型可以同时配置按任务切换。你需要提前准备两样东西。第一是 TaoToken 的 API Key在控制台的 API Keys 页面生成格式一般是sk-开头。第二是确认要用的模型 ID比如对话用哪个、代码用哪个这些在模型对话页面能看到当前可用的列表。Key 生成后先复制存好后面填进 config.toml 的api_key字段。注意离线部署时如果完全不接外部模型这一节可以跳过config.toml 里只保留 Ollama 的 provider 即可。但只要你想留一个云端兜底就先把 Key 和 base_url 准备好。3. config.toml 配置骨架模型地址、Key 与工具调用HermesAgent 的配置文件通常放在数据目录下容器部署时对应挂载出来的hermes_data目录。文件名就是config.toml。下面这份骨架把 provider、模型、工具调用三块都列出来了你按自己的环境替换地址和 Key。# HermesAgent config.toml 骨架 # 全局设置 [gateway] host 0.0.0.0 port 8642 api_key sk-hermes-local-001 # 对外暴露的网关 KeyOpenWebUI 用它来连 # 模型 provider 定义 [providers.ollama] type openai base_url http://host.docker.internal:11434/v1 api_key ollama # Ollama 不校验占位即可 default_model qwen2.5:7b [providers.taotoken] type openai base_url https://taotoken.net/api/v1 api_key sk-你的TaoToken密钥 default_model gpt-4o-mini # 按控制台实际可用模型填 # 模型路由哪个模型走哪个 provider [models] default ollama/qwen2.5:7b [models.routes] ollama/qwen2.5:7b ollama taotoken/gpt-4o-mini taotoken # 工具调用参数 [tools] enabled true max_iterations 8 # 单轮最多调用工具次数防止死循环 timeout_seconds 60 allow_shell false # 离线环境建议关掉 shell 工具 allow_http true http_allowlist [http://host.docker.internal:11434] # 会话与上下文 [context] max_tokens 8192 history_rounds 10几个关键点解释一下。base_url末尾的/v1不能少HermesAgent 走的是 OpenAI 兼容协议少了这段路径会 404。Ollama 的地址在容器里必须用host.docker.internal因为 Ollama 跑在宿主机或者另一个容器上用localhost会指向 HermesAgent 自己。api_key对 Ollama 来说随便填它不做鉴权但字段不能空。工具调用这块max_iterations是防止 Agent 陷入无限调用循环的保险丝设成 8 比较稳。allow_shell在离线内网环境建议关掉避免误执行命令。http_allowlist只放行你信任的地址这样即使模型被诱导去请求外部 URL 也会被拦下来。如果你只用本地模型把[providers.taotoken]整段删掉[models.routes]里也只留 ollama 那条就行。配置改完记得重启 HermesAgent 容器让配置生效。4. 验证请求从 Ollama 到 HermesAgent 再到 OpenWebUI配置写完不能直接信得一层层验证连通性。顺序是从内到外先确认 Ollama 能出结果再确认 HermesAgent 能转发最后确认 OpenWebUI 能拿到模型列表。第一步验证 Ollama 本身。进容器执行docker exec -it ollama bash ollama list curl http://localhost:11434/v1/modelsollama list能看到你拉下来的模型curl返回一个 JSON 列表说明 Ollama 的 OpenAI 兼容接口是通的。如果curl报连接拒绝检查 Ollama 容器的OLLAMA_HOST是不是0.0.0.0。第二步验证 HermesAgent 到 Ollama 的链路。在 HermesAgent 容器里执行docker exec -it hermes bash curl http://host.docker.internal:11434/v1/models这一步能返回模型列表说明容器间的地址解析没问题。如果这里失败但上一步成功八成是host.docker.internal没配好检查 compose 里的extra_hosts有没有加上host.docker.internal:host-gateway。第三步验证 HermesAgent 自己的网关接口。在宿主机上执行curl http://localhost:8642/v1/models \ -H Authorization: Bearer sk-hermes-local-001返回的列表里应该包含你在 config.toml 里配置的模型。如果返回 401说明api_key对不上返回空列表说明[models.routes]没配对。第四步发一条真实对话请求curl http://localhost:8642/v1/chat/completions \ -H Authorization: Bearer sk-hermes-local-001 \ -H Content-Type: application/json \ -d { model: ollama/qwen2.5:7b, messages: [{role: user, content: 用一句话介绍你自己}] }能拿到正常的choices回复整条链路就通了。最后打开 OpenWebUI在管理员面板的外部链接里把 OpenAI 接口指向http://hermes:8642/v1Key 填sk-hermes-local-001保存后模型下拉框里就能看到配置的模型。5. 本篇常见错排查配置过程中报错集中在几个地方对照着查能省不少时间。连接超时或 connection refused。最常见的原因是地址写错。容器内访问宿主机服务必须用host.docker.internal不能用127.0.0.1。反过来宿主机访问容器用映射出来的端口比如localhost:8642。两个方向别搞反。401 Unauthorized。HermesAgent 网关的 Key 和 OpenWebUI 里填的 Key 必须一致。config.toml 里[gateway]的api_key是网关对外的钥匙OpenWebUI 配置里填的也是这个值。provider 里的api_key是 HermesAgent 去连上游用的两者不是一回事。模型列表为空。检查[models.routes]里的键名格式必须是provider/model这种带斜杠的写法且要和[providers]下的名字对得上。另外确认default_model在 Ollama 里确实已经 pull 下来了。工具调用不生效。先看[tools]的enabled是不是 true再看max_iterations是不是设成了 0。如果模型本身不支持 function calling工具调用也不会触发换一个支持工具调用的模型再试。配置改了不生效。HermesAgent 读取的是启动时加载的 config.toml改完必须重启容器。执行docker restart hermes再验证。OpenWebUI 里模型能选但发消息报错。多半是 OpenWebUI 到 HermesAgent 的网络不通。确认两个容器在同一个 compose 网络里OpenWebUI 里填的地址用服务名http://hermes:8642/v1而不是localhost。6. 后续怎么扩展跑通基础对话之后这套骨架还能往上加东西。工具调用那块可以接入本地文件检索、数据库查询这类自定义工具只要在 config.toml 的[tools]下面注册对应的 endpoint 就行。OpenWebUI 的 RAG 知识库可以挂本地文档目录配合 Ollama 的 embedding 模型做离线检索。如果你后面想让 Agent 承担更长期的编码任务或者需要更稳定的多轮工具编排可以了解一下 Coding Plan 这类方案它针对长时间运行的 Agent 场景做了优化。日常调试模型和验证接口直接用模型对话页面就够了。Key 的管理和生成都在控制台的 API Keys 页面接入细节可以翻接入文档。整套配置的核心就一句话地址写对、Key 对齐、路由配准。把这三样在 config.toml 里填明白离线 AI 助手就能稳定跑起来。