Codex+Hermes+Ollama：本地多智能体编码协作方案搭建指南

最近的讨论里，Codex 和 Ollama 经常被放在一起，因为很多人想把编码 Agent 接到本地模型上，让代码逻辑不离开自己的机器。再加一个 Hermes 做任务编排，就成了“Codex + Hermes + Ollama”的多智能体协作方案。先说结论：这套组合确实能跑，而且不需要你一开始就有一张高端显卡。你需要先想清楚三件事：谁负责规划，谁负责写代码，谁负责跑模型。这篇文章就按“部署、接线、跑通、排错”的顺序，把从零搭建的流程拆开讲。标题里提到的教程文档和安装包，建议你先解压看 README，核对版本和依赖，再跟着下面的流程走。

1. 先看懂分工：Codex、Hermes、Ollama 到底各干什么

1.1 多智能体不是多个模型排队

很多人以为多智能体就是把几个大模型串在一起，前一个吐结果，后一个接着吃。实际不是这样。多智能体系统里，真正被调度的是“Agent”，而 Agent 背后可以共用同一个模型，也可以各自用不同模型。你可以把 Agent 理解成一个“有角色、有目标、有工具调用能力的程序”，模型只是它的推理引擎。

Codex 在这里的角色是编码 Agent。它负责接收需求、生成代码、修改文件、执行命令。Hermes 在下面这套方案里承担编排 Agent 的角色，它负责把任务拆开、分发给各个执行者、收集结果。Ollama 则在最底层，负责把模型跑起来，对外提供接口。三者不是平级关系，而是一条链条：用户需求先进 Hermes，Hermes 调度 Codex，Codex 再向 Ollama 要模型推理结果。

这里顺便解释一个常见问题：Harness 和 Agent 有什么区别。Harness 是运行 Agent 的框架，决定 Agent 怎么定义上下文、怎么调用工具、怎么循环执行；Agent 是任务主体。你可以用 Harness 去约束 Agent 的行为，避免它乱跑。搭建多智能体时，最该先确定的不是“用哪个模型”，而是“哪个组件是 Harness，哪个组件是 Agent”。

1.2 三个组件到底依赖什么

用表格看会更清楚：

依赖关系上，Ollama 在最底层，Codex 和 Hermes 都需要模型接口。Hermes 负责调度 Codex，Codex 负责具体编码。如果 Hermes 项目本身只是一个模型名，那它应该作为 Ollama 里拉取的模型；如果 Hermes 是一个服务，那就把它放在 Codex 上层。我在下文主要按“Hermes 是编排服务”的场景展开，因为这个场景更接近多智能体协作。

还要注意一个问题：Ollama 和 Codex 之间的连接不是“文件拷贝”，而是 HTTP 接口调用。Ollama 默认监听 11434 端口，并提供了一个 OpenAI 兼容接口。Codex 只要能配置自定义模型端点，就能把 Ollama 当作模型后端使用。这个思路也适合其他本地模型：只要模型服务提供 OpenAI 兼容协议，Codex 的接入方式基本不变。

1.3 先认清边界，别一上来就上全套

不是所有任务都需要三件套。简单问答，直接ollama run hermes3就行；单文件脚本，让 Codex 直接调用模型也行。需要上多智能体的场景，一般是任务周期长、步骤多、需要反复检查，比如“写一个带接口的项目，先规划目录，再写核心逻辑，再让另一个角色检查漏洞”。

另外，低配置机器也能尝试。Ollama 可以纯 CPU 跑小参数模型，Codex 如果用本地模型就不需要云端 GPU，Hermes 只是个轻量调度服务。真正的瓶颈不是能不能跑，而是响应速度和上下文长度。你在第一次实验前要想好：如果每一步都很慢，能不能接受？如果能接受，就继续往下走。如果完全不能接受慢响应，那就要考虑使用云端 API，但本地数据不出机器的优势也就没有了。

2. 搭建前的环境准备：先确定系统、硬件、模型、客户端

2.1 用 Linux 或 WSL2 能少踩很多坑

Codex、Hermes、Ollama 三件套在 Windows、macOS、Linux 上都有安装路径。但我的建议是，如果你想少踩坑，优先用 Linux 或 WSL2。原因很简单：很多命令行工具和脚本默认按 Unix 路径写，在 Windows 原生环境会出现路径分隔符、权限、命令解析不一致的问题。

如果你使用 Windows，建议先装 WSL2，在 WSL2 里安装 Ollama 和 Hermes。Codex 如果提供 Windows 安装包，也可以装在 Windows 侧，但跨系统通信时要注意localhost是否能互通、防火墙是否放行。更省心的做法是全部装在 WSL2 里，这样目录、命令、依赖版本基本一致。

基础依赖一般需要 Python 3.10 以上、Node.js 18 以上、Git，以及一个能正常访问终端的环境。Hermes 如果依赖 Python，就先用python --version确认版本。Codex 如果提供 npm 安装方式，需要先把 Node.js 配好。不要凭感觉，先用命令确认。

2.2 先看内存和显存，再决定模型大小

不要一上来就问“要多少 G 显存”。先定模型，再定硬件。如果你打算跑 7B/8B 的量化模型，16GB 内存的机器可以试试，但推理速度明显偏慢。如果有 NVIDIA 显卡，显存 6GB 以上可以跑小参数模型，速度会好很多。如果你的机器只有 16GB 内存、没有独显，也不是不能玩，只是单次响应可能要几十秒到几分钟。

我的判断顺序是这样：先看机器内存，再看显卡显存，然后选择合适大小的模型。内存不足时，即使模型加载成功，模型权重也会被交换到磁盘，速度会断崖式下降。跑批量任务前，先开一个终端用nvidia-smi或任务管理器观察资源占用，不要等到卡死再查。

模型体积和硬件的关系，有个大致规律：模型参数越大，显存和内存占用越高，量化版本会低一些。7B/8B 模型在 16GB 内存的机器上能跑，但只能跑比较小的上下文；13B 以上模型，建议至少 32GB 内存或 12GB 以上显存。这个不是硬性标准，只是一个快速判断参考。

2.3 Ollama 安装、启动和拉取模型

Ollama 安装本身不难，去官网下载对应系统的安装包，或者用包管理器安装。安装完成后，先启动服务：

ollama serve

服务默认监听 11434 端口。不要改端口，除非你有明确理由，因为后续 Codex 和 Hermes 都按这个地址访问。

模型下载用 ollama pull：

ollama pull hermes3

这里要特别说明一下：Hermes 在社区里存在多个同名项目。如果你用的 Hermes 是 Ollama 上的模型，直接按模型名拉取；如果你用的是 Hermes Agent 服务，那模型名可能不同。拉取前先确认你下载的到底是什么，不要看到一个命令就复制执行。

下载慢是常见问题，尤其模型文件几个 GB 的时候。处理办法按顺序试：换个下载时段、选择更小的模型、配置可用的镜像源。模型文件建议放在剩余空间充足的磁盘，不要塞在系统盘里。你可以在环境变量里指定模型缓存目录，比如OLLAMA_MODELS=/data/ollama，这样模型不会占满 C 盘。

2.4 Codex 安装和登录，不要轻信第三方脚本

Codex 客户端常见的安装方式有两种：官方安装包和 npm 全局安装。如果你已经拿到离线安装包，优先按安装包里的文档来，因为离线包通常锁定了版本和依赖。安装完成后，先执行版本命令确认命令可用。

Codex 可能需要登录账号或配置 API Key，不同版本要求不一样。这个环节按官方提示操作即可，不要相信“免登录、免配置”的第三方脚本。如果你的目标是把 Codex 接到本地模型，那么登录环节可能不是必须的，具体要看你的 Codex 版本是否支持自定义模型提供方。如果支持，就跳到下一节；如果不支持，你只能把 Codex 当云端服务用，本地 Hermes 和 Ollama 仍然可以作为其他 Agent 的模型后端。

安装完成后，建议先执行codex --help看当前版本的参数和配置入口。很多人在网上找到旧版教程，套用后发现字段对不上，原因就是版本差异。

3. 先跑通最小闭环：让 Codex 通过 Ollama 使用 Hermes 模型

3.1 验证 Ollama 服务和 OpenAI 兼容接口

最小闭环的第一步不是配置 Codex，而是确认 Ollama 本身没问题。检查命令：

ollama list

这个命令会列出本地已有的模型。如果没有显示 hermes3，说明拉取失败或拉取到了其他名字。然后用一行对话验证生成能力：

ollama run hermes3 "用一句话介绍你自己"

它能正常返回内容，说明模型可运行。接着验证 OpenAI 兼容接口，因为 Codex 需要走这个接口：

curl http://localhost:11434/v1/models

返回 JSON 中包含模型列表，就说明接口正常。到这里，最小依赖链的下半段已经通了。

这一步的关键是“先证明接口通，再连业务逻辑”。如果直接跳到 Codex 配置，一旦报错，你会分不清是 Ollama 没启动、端口不对、模型没拉对，还是 Codex 配置写错。

3.2 配置 Codex 指向本地模型

Codex 怎么接本地模型，不同版本差别很大。我这里给的是通用思路：把 Codex 的模型端点指到 Ollama，模型名填 Hermes 在 Ollama 里的名字。Ollama 提供了 OpenAI 兼容接口，所以 Codex 不需要特殊适配，只要它支持自定义 base URL。

环境变量示例：

export CODEX_MODEL=hermes3 export CODEX_BASE_URL=http://localhost:11434/v1

如果 Codex 使用配置文件，大致是这个结构：

model = "hermes3" model_provider = "ollama" [model_providers.ollama] name = "Ollama" base_url = "http://localhost:11434/v1"

注意，这只是一个示例，具体字段名以你当前 Codex 版本的文档为准。找不到配置入口时，先看codex --help和安装目录里的示例配置，不要凭记忆硬填。

配置完成后，可以用一个很简单的 prompt 试一下，看 Codex 是否能把请求转发到 Ollama。如果它立刻提示找不到模型，先检查 model 名称是否和ollama list里的名字完全一致。模型名区分大小写，不要多写前缀。

3.3 用一个小任务验证协作

配置完成后，给 Codex 一个非常小的编码任务，比如“写一个 Python 函数，输入整数 n，返回斐波那契数列前 n 项，并带注释”。为什么要用这么小的任务？因为第一次验证只需要确认“Codex 能通过 Ollama 拿到模型返回”，而不是测试模型能力。任务越大，变量越多，出错时不好定位。

判断是否成功的标准有三个：

• Codex 没有立刻报连接错误。
• 模型返回内容正确生成代码。
• 代码文件写到了你指定的目录。

如果前面两步成功，但文件没生成，优先看 Codex 的权限配置和输出目录。不要急着调模型参数。这个任务能跑通，说明 Codex 调用本地模型的链路已经完整，接下来再升级到多 Agent 编排就有基础了。

3.4 调整生成参数时，一次只改一个

接入本地模型后，你可能会遇到两种问题：生成内容太发散，或者输出被截断。前者看 temperature，写代码场景建议调低；后者看 max_tokens 或 num_predict，输出限制调大一点。Ollama 里也有temperature和num_predict参数，Codex 可能通过配置传给它。

我的建议是先保持默认参数跑通，再每次只改一个参数。不要同时调 temperature、max_tokens、top_p，因为你不知道是哪个参数带来变化。记录每次调参前后的结果，比“感觉好了很多”更可靠。

对于代码生成类任务，一个比较稳的起点是 temperature 调到 0.2 左右，top_p 保持默认；如果模型经常话痨、不直接给代码，可以试着重写 system prompt，而不是继续增大输出限制。问题经常出在“角色定位不够清楚”，而不是参数不够大。

4. 引入 Hermes：从单 Agent 到多 Agent 协作

4.1 先确认你的 Hermes 是模型还是服务

引入 Hermes 之前，先确认你要用哪个 Hermes。如果 Hermes 是模型，那么它已经在 Ollama 里，不需要额外安装；如果 Hermes 是 Agent 编排服务，那它应当放在 Codex 上层。我这里按编排服务来写，因为这样才能体现“多智能体协作”的概念：用户需求先进 Hermes，Hermes 把任务拆成规划、编码、审查、修复等子任务，分发给不同的 Agent。

其实很多项目里，Agent 不一定非要由不同模型驱动。同一个模型，配上不同的 system prompt，也可以扮演不同角色。Hermes 的核心价值是流程控制：谁先执行、谁等待谁的结果、失败后怎么办、结果在哪里确认。如果你已经有一个能跑的 Codex + Ollama，加入 Hermes 的主要收益就是“步骤变得可管理了”。

4.2 安装和配置 Hermes 的通用流程

如果你拿到的 Hermes 是二进制发布包，安装步骤一般就是解压、配置、启动三个动作。我不建议从源码开始编译，除非文档明确要求，或者你想改源码。先用发布包把环境跑通，源码放在以后深入看。

启动前先看三样东西：

• 版本要求：需要 Python、Node、Go 还是纯二进制。
• 默认端口：是否和 Ollama 的 11434 冲突。
• 配置文件：采用 YAML、JSON 还是 TOML。

一个示例配置：

server: port: 18080 planner: model: hermes3 system_prompt: "你负责把需求拆成可执行的子任务" coder: model: codex endpoint: http://localhost:11434/v1 reviewer: model: hermes3 system_prompt: "你负责检查代码逻辑和错误"

这只是演示结构，不代表任何具体项目。你用的时候，把组件名和字段换成实际情况。如果文档里有模板，优先用模板。

很多服务型 Agent 工具都支持“先校验配置，再启动”。如果有类似命令，启动前先跑一遍，能省掉大量排错时间。比如hermes validate -c hermes.yml，可以检查 YAML 格式和必填字段。

4.3 设计最简单的任务流：规划、编码、审查、修复

多智能体协作的第一步，不是写复杂代码，而是画流程。我设计的第一个流程很简单：

1. 用户输入需求。
2. Planner 把需求拆成任务，写入任务列表。
3. Coder 从任务列表取一个任务，调用 Codex 生成代码。
4. Reviewer 检查代码，把结果写回。
5. 审查不通过，任务回到 Coder 处理；通过，任务标记完成。

为什么用任务列表？因为多智能体协作最容易出问题的就是“谁在等谁”。任务列表可以明确每个任务的当前状态。你可以用一个 JSON 文件当作任务列表，避免一开始就上数据库。

一个任务对象示例：

{ "task_id": "task-001", "status": "pending", "input": "写一个读取 CSV 并按其中一列排序的脚本", "output": "", "error": "", "attempts": 0 }

任务对象里一定要有status和attempts。status用于流程判断，`attempt