之前在终端里折腾 Codex 本地化接入时前后花了不少时间最大的感受是Codex、Ollama、Hermes Agent 这三类工具单独看都有教程但把它们串成一条完整的多智能体协作链路网上资料非常零散。有的讲 Codex 安装不讲模型对接有的讲 Ollama 部署不讲 Agent 调度真正把“本地模型 终端 Agent 编排框架”跑通的文章少之又少。这篇文章把最近完整搭通的整套流程整理出来从环境准备、模型拉取、Codex 配置、Agent 编排到高频报错排查和工程化建议一次性讲透。适合刚接触 AI Agent 开发的新手也适合想把手头 Codex 和 Ollama 组合起来做多智能体实验的开发者。1. 背景与核心概念Codex、Hermes、Ollama 到底解决什么问题在动手安装之前先把三个核心组件弄清楚。很多新手失败的原因不是操作不对而是没搞明白每个工具在整条链路里扮演什么角色。1.1 Codex CLI 是什么Codex 是 OpenAI 推出的终端 AI 编程助手它可以跑在命令行里直接用自然语言让 AI 帮助你完成代码编写、文件修改、命令执行、仓库阅读等一系列操作。和传统“复制代码到聊天框里问 AI”不同Codex 本身就是一个 Agent 形态它能看到当前项目目录能读出文件内容甚至能执行 Shell 命令来验证自己的修改结果。从实际体验来说Codex 更适合下面几类场景在已有项目中快速定位问题并直接生成补丁。让 AI 批量完成跨文件的代码修改。用自然语言描述需求让 AI 自动完成一个脚本或小模块。与 Git 配合在独立分支上让 AI 提交代码。Codex 的模型端点支持配置这一点非常关键。官方默认连接 OpenAI 的云服务但我们可以通过修改配置把它指向 Ollama 本地模型或者指向 DeepSeek 等第三方 OpenAI 兼容 API。这也是本文后续对接 Ollama 的技术基础。1.2 Hermes Agent 是什么Hermes 这个词在 AI 圈里有两层常见含义很容易混淆。第一层指 Nous Research 发布的一系列开源模型例如 Hermes 2、Hermes 3、Hermes 4这些模型通常以 Llama 或 Qwen 基座模型微调而来在对话、工具调用、Agent 任务上有不错表现可以通过 Ollama 直接拉取。第二层指社区中越来越多见到的“Hermes Agent”框架它本质上是一个智能体编排工具用来创建和管理多个子 Agent让它们分工协作完成一个复杂任务。比如一个 Agent 负责代码编写另一个负责测试生成第三个负责文档整理再由一个主控 Agent 来分配任务并汇总结果。在本文语境下我们更关注第二层含义即用 Hermes Agent 作为多智能体调度层让 Codex 和本地模型配合起来。如果你拿到的是 Hermes 模型文件那可以直接用 Ollama 运行如果你拿到的是 Agent 框架代码则需要安装依赖并配置模型服务地址。建议在开始前先确认你的 Hermes 包属于哪一种避免把模型和框架混在一起。1.3 Ollama 本地模型服务是什么Ollama 是目前使用门槛最低的本地大模型运行工具。它把模型的下载、存储、启动和 API 暴露封装成了一套极简命令用户不需要关心 Python 虚拟环境、CUDA 配置、推理框架等复杂细节只需要执行ollama pull和ollama run就能用上开源大模型。Ollama 对本文最重要的价值是它提供了 OpenAI 兼容的 HTTP 接口。默认地址是http://localhost:11434/v1这意味着凡是支持 OpenAI API 格式的客户端都可以把base_url改成 Ollama 地址无痛切换到本地模型。Codex 和 Hermes Agent 正是利用这一点来接入本地模型的。1.4 三者的协作关系用一句话概括三者的关系Ollama 负责“模型层”提供本地推理能力。Codex 负责“终端执行层”作为你身边的 AI 程序员。Hermes Agent 负责“调度层”把复杂任务拆给多个 Agent 并行处理。一个典型的多智能体协作流程是这样你向 Hermes Agent 主控节点提交一个需求。主控节点把需求拆成子任务分别分配给代码 Agent、测试 Agent、审查 Agent。每个子 Agent 调用模型完成自己的任务模型既可以是 Ollama 里的本地模型也可以是 DeepSeek 等云端 API。主控节点回收结果做汇总输出。Codex 可以作为其中一个承担编码执行的 Agent直接修改项目文件并运行命令。理解了这个协作关系后面的配置就会顺很多。接下来进入环境准备。2. 环境准备与版本说明2.1 基础运行环境根据多个社区案例和实际测试推荐下面的环境组合操作系统Windows 10/11、macOS 或主流 Linux 发行版。Windows 用户强烈建议启用 WSL2因为 Codex 在 Unix 环境下的命令执行更顺畅。Node.js需要 18 及以上版本Codex CLI 基于 Node.js 生态。Python建议 3.9 及以上版本多个 Agent 框架依赖 Python 环境。Git用于拉取 Agent 框架代码。终端工具Windows Terminal、iTerm2 或 VS Code 内置终端都可以。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。不同版本之间的命令差异如果出现通常体现在模型名称或配置字段上我会在对应位置提醒你注意。2.2 安装 OllamaOllama 的安装非常直接。macOS 和 Linux 用户可以执行官方安装脚本curl -fsSL https://ollama.com/install.sh | shWindows 用户则直接前往 Ollama 官网下载安装包安装完成后命令行里检查版本ollama --version如果能看到版本号就说明安装成功。接着启动服务ollama serve服务默认监听 11434 端口。不过要注意ollama serve会占用当前终端建议把它放到后台执行或者直接依赖 Ollama 安装时自带的开机自启服务。验证服务是否正常curl http://localhost:11434/v1/models如果返回一段 JSON 数组说明 API 服务已经可用了。2.3 安装 CodexCodex 的安装方式以官方 GitHub 仓库为准目前最常见的安装方式是通过 npm 全局安装npm install -g openai/codex安装完成之后检查版本codex --version如果命令找不到通常是 Node.js 的全局 bin 目录没有加入 PATH需要手动配置一下环境变量。Codex 支持两种认证方式一种是交互式登录执行codex login后按提示完成授权另一种是直接配置 API Key。对于自动化场景更推荐 API Key 方式后面第 3 节会具体讲配置方法。2.4 安装 Hermes AgentHermes Agent 的安装方式取决于你使用的具体项目因为社区里存在不同实现。这里给出一个通用思路让你拿到任何仓库都能快速装上从官方 GitHub 仓库克隆代码到本地。如果项目是 Python 写的创建虚拟环境并安装依赖。如果项目是 Node.js 写的直接执行npm install。打开配置文件把你自己的模型服务地址填进去。启动主控 Agent。以 Python 项目为例通用安装过程大致如下git clone https://github.com/your-org/hermes-agent.git cd hermes-agent python -m venv venv source venv/bin/activate pip install -r requirements.txt这里只是一个思路示意不是某个具体仓库的完整安装命令。你实际操作时一定要以仓库 README 的说明为准。如果你是希望运行 Hermes 模型本身那么不需要下载 Agent 框架直接用 Ollama 拉取即可ollama pull hermes3这样拉取下来的是模型权重可以用ollama run hermes3直接对话。务必先分清你的目标是搭建 Agent 框架还是运行 Hermes 模型。2.5 验证基础环境环境安装完成之后我习惯先做一轮“健康检查”确认每个组件都可用再继续后面的配置。检查清单如下检查项命令预期结果Ollama 服务curl http://localhost:11434/v1/models返回 JSON包含已安装模型Ollama 版本ollama --version输出版本号Codex 版本codex --version输出版本号Node.js 版本node -v输出 v18 以上版本Python 版本python --version输出 3.9 以上版本如果curl请求 Ollama 时长时间无响应检查 11434 端口是否被防火墙拦截或者ollama serve是否真的在运行。3. 核心配置与原理拆解环境搭好之后我们先不急着跑复杂任务而是把最关键的配置原理讲清楚。很多报错都源于对配置文件不理解导致改错字段。3.1 Codex 配置文件结构Codex 的配置文件默认位于用户目录下的.codex/config.toml。它的作用类似.gitconfig集中管理模型提供方、API 地址、认证信息、运行参数等。一个典型的对接本地模型的配置如下# 文件路径~/.codex/config.toml model qwen3:8b model_provider ollama [model_providers.ollama] name Ollama Local base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api chat这里的字段含义如下model指定默认使用的模型名称必须和 Ollama 里已有的模型标签一致。model_provider指定使用哪一组提供方配置对应下面的[model_providers.ollama]。base_url模型服务的 API 地址Ollama 的 OpenAI 兼容地址就是http://localhost:11434/v1。env_key从哪个环境变量读取 API Key。Ollama 本地服务不需要鉴权但 Codex 配置要求有这个字段随意填一个即可保证不报错。wire_api接口协议类型。chat表示使用 Chat Completions 协议Codex 也支持responses协议具体取决于你的 Codex 版本。Ollama 兼容端点默认支持 chat 格式。如果你要对接 DeepSeek 云端 API只需要把提供方配置换成[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat然后在系统环境变量里设置export DEEPSEEK_API_KEY你的密钥这种可插拔的配置方式让 Codex 可以灵活地在多个模型之间切换本地用 Ollama云端用 DeepSeek完全不需要改代码。3.2 Ollama 的 OpenAI 兼容 APIOllama 从较早的版本开始就提供了 OpenAI 兼容接口这对所有想接入本地模型的工具来说都至关重要。因为主流 AI 工具基本都兼容 OpenAI 的请求格式Ollama 只要“伪装”成一个 OpenAI API就能无缝接入大量生态。我们可以用一个 curl 请求来验证这个接口curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen3:8b, messages: [{role: user, content: 你好请介绍一下你自己}] }如果模型已经拉取成功接口会返回类似下面的 JSON{ id: chatcmpl-xxx, object: chat.completion, created: 1731234567, model: qwen3:8b, choices: [ { index: 0, message: { role: assistant, content: 你好我是一个基于 Qwen 模型构建的本地 AI 助手…… }, finish_reason: stop } ] }这里有两个字段要重点理解message.content模型生成的文本内容。choices模型返回的候选项数组通常只需要取第一个。Codex、Hermes Agent 本质上都是在拼这样的请求再解析返回结果。理解了协议本身哪怕你后续不用这些框架也能自己写代码调用本地模型。3.3 Hermes Agent 多智能体协作原理多智能体协作不是新鲜概念但落地时容易设计混乱。最简单可靠的模式是“主控-工人”模式主控 AgentOrchestrator负责接收用户需求理解任务结构。主控把任务拆成若干子任务分发给不同工人 AgentWorker。每个工人 Agent 只处理自己负责的子任务可以绑定不同的模型。工人把结果返回给主控主控做整合与校验。举个例子假设用户输入“帮我开发一个命令行单词查询工具”主控 Agent 可以这样拆分子任务负责 Agent绑定模型项目结构设计架构 Agentqwen3:8b核心逻辑编码编码 Agentcodex单元测试编写测试 Agenthermes3使用文档生成文档 Agentqwen3:8b每个 Agent 各司其职互不干扰。主控 Agent 只负责任务分发和结果汇总。这种模式实现简单扩展性好非常适合本地实验。4. 完整实战从零搭建 Codex Ollama 多智能体协作环境这一节我们完整走一遍实战先用 Ollama 跑起本地模型然后让 Codex 接入再实现一个最简多智能体协作 Demo。4.1 创建项目结构先在本地创建一个实验目录mkdir -p ~/codex-agent-demo/{agents,config,logs} cd ~/codex-agent-demo目录说明agents存放多智能体脚本。config存放自定义配置文件。logs存放运行日志。4.2 拉取并运行本地模型本文以qwen3:8b为例这是目前本地部署中综合表现比较均衡的模型对中文支持好显存需求适中。如果你显存较小可以换成qwen3:4b。拉取模型ollama pull qwen3:8b拉取成功后验证ollama list你应该能在列表里看到qwen3:8b。然后启动一次对话测试ollama run qwen3:8b 你好如果模型能正常回应说明本地模型已经就绪。这一步很关键它把“模型下载”和“API 调用”的问题独立出来后面接 Codex 时才不会把错误混在一起。4.3 配置 Codex 接入本地模型修改~/.codex/config.toml写入下面的完整配置# 文件路径~/.codex/config.toml model qwen3:8b model_provider ollama approval_policy on-request [model_providers.ollama] name Ollama Local base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api chat其中approval_policy表示命令执行前需要等待用户确认新手建议保留这个配置避免 Agent 自动执行高风险命令。保存配置后在项目目录里调用一次 Codexcd ~/codex-agent-demo codex 请读取当前目录结构并告诉我这个项目是做什么的如果配置成功Codex 会调用 Ollama 里的qwen3:8b来理解你的请求。由于是本地模型响应速度取决于你的 CPU/GPU 性能。这里需要特别说明如果你希望 Codex 调用云端 DeepSeek则把model_provider改了即可。逻辑完全一样区别只在于模型执行的物理位置。4.4 编写一个最简多智能体协作脚本我们不依赖任何重框架用纯 Python 写一个多智能体协作示例这样你能直观理解主控-工人模式的本质。脚本里每个 Agent 都通过 HTTP 调用 Ollama 模型。首先安装依赖pip install requests然后创建agents/orchestrator.py# 文件路径~/codex-agent-demo/agents/orchestrator.py import requests import json OLLAMA_URL http://localhost:11434/v1/chat/completions def call_model(model: str, prompt: str, max_tokens: int 1024) - str: payload { model: model, messages: [{role: user, content: prompt}], max_tokens: max_tokens, temperature: 0.7 } try: resp requests.post(OLLAMA_URL, jsonpayload, timeout300) resp.raise_for_status() data resp.json() return data[choices][0][message][content] except requests.exceptions.RequestException as e: return f[模型调用失败] {e} def run_worker(worker_name: str, task: str, model: str) - None: print(f\n {worker_name} Agent 开始执行 ) result call_model(model, task) print(f--- {worker_name} 输出 ---) print(result) def main(): # 模拟主控 Agent 的任务拆分 tasks [ (架构, 请简单设计一个Python命令行单词查询工具的模块划分只输出模块列表和职责。, qwen3:8b), (测试, 请为上述工具列出三个关键测试场景只列出场景名和验证点。, qwen3:8b), (文档, 请生成一个README模板包含安装和基本用法。, qwen3:8b) ] print(主控 Agent 开始分发任务...) for worker_name, task, model in tasks: run_worker(worker_name, task, model) print(\n 所有任务执行完毕 ) if __name__ __main__: main()这个脚本很简单但演示了多智能体最核心的三个要素每个 Worker 有独立职责对应不同的任务提示词。每个 Worker 可以绑定不同模型。主控 Agent 负责按顺序调度和汇总。你可以把call_model函数里的OLLAMA_URL替换成 DeepSeek 的官方地址再把model改成deepseek-chat同一个脚本就能对接云端模型这就是多智能体协作里的“模型可替换性”。运行脚本cd ~/codex-agent-demo python agents/orchestrator.py预期输出格式如下主控 Agent 开始分发任务... 架构 Agent 开始执行 --- 架构 输出 --- 1. 参数解析模块 2. 词典查询模块 3. 结果格式化模块 ... 测试 Agent 开始执行 --- 测试 输出 --- 1. 查询存在的单词 2. 查询不存在的单词 3. 空输入处理 ... 文档 Agent 开始执行 --- 文档 输出 --- # 单词查询工具 ...注意模型输出不是固定的每个人拿到结果都可能不同。只要脚本不报错、每个 Agent 都能返回文本链路就算跑通了。4.5 实现更真实的多智能体协作上面的示例只是顺序调用。真实场景里多个 Agent 之间往往有依赖关系比如文档 Agent 需要参考架构 Agent 的输出。下面增加一个“结果传递”的版本让你看到主控如何把前一个 Agent 的输出交给后一个 Agent 作为上下文# 文件路径~/codex-agent-demo/agents/orchestrator_with_context.py import requests import json OLLAMA_URL http://localhost:11434/v1/chat/completions def call_model(model: str, prompt: str, max_tokens: int 1024) - str: payload { model: model, messages: [{role: user, content: prompt}], max_tokens: max_tokens, temperature: 0.7 } resp requests.post(OLLAMA_URL, jsonpayload, timeout300) resp.raise_for_status() return resp.json()[choices][0][message][content] def main(): architecture_result call_model( qwen3:8b, 请设计一个Python命令行单词查询工具的模块划分只输出模块列表和职责。 ) print( 架构 Agent 输出 ) print(architecture_result) test_prompt f基于以下架构设计生成测试场景\n{architecture_result}\n只输出场景名称。 test_result call_model(qwen3:8b, test_prompt) print(\n 测试 Agent 输出 ) print(test_result) doc_prompt f基于以下架构设计生成README\n{architecture_result}\n只输出README的Markdown内容。 doc_result call_model(qwen3:8b, doc_prompt) print(\n 文档 Agent 输出 ) print(doc_result) if __name__ __main__: main()这个版本更接近真实场景后一个 Agent 站在前一个 Agent 的肩膀上继续工作。你甚至可以让测试 Agent 把架构输出中的模块名直接提取出来生成对应的测试文件。这种“级联传递”是多智能体协作的常见形态也是后续学习 LangGraph、CrewAI 等框架时最核心的思维模型。5. 高频报错与排查思路实际配置中最容易卡住新手的不是概念而是各种报错。下面把社区里出现频率较高的几个问题整理出来。5.1 Codex 报错cc switch local proxy failed while handling codex endpoint /responses这个报错经常出现在使用本地代理切换工具的情况下。字面意思是Codex 在处理/responses端点请求时本地代理切换失败导致请求没有真正发出去。可能原因本地代理工具异常退出但 Codex 持有的代理连接没有释放。系统环境变量里残留了HTTP_PROXY/HTTPS_PROXY指向一个不可用的代理端口。Codex 配置文件里存在旧的代理设置。排查步骤检查当前终端的代理环境变量env | grep -i proxy如果不需要代理直接清空unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY重启终端再执行一次codex命令。如果你确实需要通过代理访问外部 API请使用公司 IT 或机构批准的合规代理配置并确认代理端口可访问不要使用来源不明的代理服务。检查~/.codex/config.toml里是否配置了代理相关字段如果有确保地址正确。这个报错的核心是“本地代理切换失败”不是 Codex 本身坏了所以优先排查代理环境变量。5.2 Agent 运行中止agent terminated due to error you can prompt the model to try again or start这个提示比较模糊意思是一个 Agent 在执行过程中因为错误被终止系统建议你提示模型重试或重新启动。常见原因有模型服务不可用比如 Ollama 没启动或者模型没有被正确拉取。请求超出了上下文长度限制输入内容太长。模型返回了不合法格式Agent 解析失败。任务过于复杂模型在单次调用中无法完成。网络超时或代理问题。排查方法先用 curl 手动测试模型接口是否正常。查看 Codex 的完整错误日志不要只看最后一行提示。把任务拆得更小不要试图让一个 Agent 一次完成所有事情。适当增大超时时间。确认模型名称是否和 Ollama 中的标签完全一致注意版本号。5.3 Ollama 下载模型太慢Ollama 下载大模型时速度慢是国内用户最常见的痛点。一个 8B 模型动辄 5GB 以上如果直连官方源速度确实不稳定。几种缓解方案设置模型文件存放目录到空间充足的磁盘避免因空间不足反复失败。如果网络条件差可以配置可信的镜像源或企业内网代理缓存但要注意信息安全和合规性。先用小模型qwen3:4b完成链路调试确认可行后再换大模型。检查模型目录的环境变量echo $OLLAMA_MODELS如果目录空间不够可以切换export OLLAMA_MODELS/data/ollama/models设置完环境变量后需要重启 Ollama 服务。下载慢的问题普遍存在但它不影响整体架构。建议先把小模型跑通再慢慢补大模型。5.4 其他常见问题汇总问题现象常见原因解决思路Codex 提示认证失败API Key 无效或环境变量未设置检查env_key对应的环境变量重新生成 KeyOllama 端口冲突11434 被其他程序占用修改 Ollama 端口或结束占用进程内存不足导致模型崩溃模型尺寸超过物理内存/显存换更小的模型或减少并发Agent 输出乱码终端编码问题设置 UTF-8 编码环境变量Codex 无法读取项目文件权限不足检查目录权限避免在权限受限目录运行Hermes Agent 依赖安装失败Python 版本过低升级 Python 到 3.9 以上6. 生产环境最佳实践与注意事项实验环境跑通之后如果要应用到真实项目或团队协作必须注意下面几个维度。6.1 安全边界与权限管理Codex 这类 Agent 工具具备执行命令的能力这既是它的优势也是它的风险来源。在生产环境或公司内网使用时请务必遵守以下原则使用最小权限账号运行 Agent绝不要用 root 或管理员账号直接跑。API Key 不要写死在代码或配置文件里用环境变量或密钥管理平台。Ollama 服务默认监听 localhost不要随意暴露到公网。如果确实需要远程访问必须加鉴权并限制来源 IP。涉及数据库操作、文件删除、生产环境变更时应先备份并设置人工审批环节。如果你使用的是公司内网模型服务遵守公司安全规定不要私自搭建代理或绕过访问控制。6.2 资源控制与性能优化本地模型的内存占用不容小觑。以 8B 模型为例加载到内存后占用经常超过 8GB如果同时运行多个 Agent很容易撑爆内存。建议同一时间只加载一个主模型其他 Agent 共享同一个模型服务。用max_tokens限制单次模型输出长度避免 Agent 生成超长文本拖慢速度。控制并发请求数量Ollama 支持配置并发参数但默认值不一定适合你的机器。长时间不用的模型使用ollama stop释放内存。6.3 多智能体任务拆分的工程建议多智能体不是越多越好。每个 Agent 都会带来上下文传递开销任务拆碎后反而可能降低整体效率。设计时要遵循按职责拆分而不是按步骤拆分。比如“编码”“测试”“审查”是职责而“写第 1 行”“写第 2 行”不是职责。每个子 Agent 的工作产物要尽量独立方便并行执行和结果聚合。主控 Agent 必须对子 Agent 的输出做验证不能无脑相信模型结果。用统一的输入输出格式约束 Agent避免一个 Agent 输出 JSON另一个输出 Markdown导致主控无法解析。6.4 Codex 使用效率技巧Codex 在真实项目中效率很高但前提是配合良好的项目说明。官方推荐在项目根目录维护一份AGENTS.md文件里面描述项目结构、技术栈、常用命令和规范。这样 Codex 每次启动时都能快速理解项目背景生成的代码更加贴合项目现状。一个最小示例# AGENTS.md ## 项目简介 这是一个基于 Python 的命令行单词查询工具。 ## 技术栈 - Python 3.10 - Click 8.0 ## 常用命令 - 安装依赖pip install -r requirements.txt - 运行测试pytest tests/ - 启动工具python main.py --word hello ## 代码风格 - 使用 type hints - 所有函数必须有 docstring - 单测覆盖核心查询逻辑有了这样一个文件Codex 的输出质量会有明显提升。7. 总结与下一步学习方向这篇文章从零开始完整演示了 Ollama 部署本地模型、Codex 接入自定义模型端点、Hermes Agent 思路下的多智能体协作脚本编写并整理了实际运行中最常见的报错和排查手段。整个链路跑通之后你会发现所谓“多智能体协作”并不神秘本质上就是不同功能的 Agent 通过模型 API 互相配合关键在任务拆分、上下文传递和结果校验。接下来你可以往这几个方向继续深入学习 LangGraph 或 CrewAI 这类成熟的多智能体框架替代手写调度脚本。给 Ollama 配置 GPU 加速提高本地模型推理速度。研究 MCPModel Context Protocol让 Agent 接入更多外部工具。把 RAG检索增强生成加入链路让 Agent 能基于私有文档回答问题。建议你先花一个下午把本文的示例代码跑通再逐步替换成自己的任务场景。如果你在操作过程中遇到新报错保留好终端日志按“现象-原因-解决”的顺序排查大部分问题都能定位到配置或网络层面。
Codex + Ollama + Hermes Agent 本地多智能体协作搭建指南
之前在终端里折腾 Codex 本地化接入时前后花了不少时间最大的感受是Codex、Ollama、Hermes Agent 这三类工具单独看都有教程但把它们串成一条完整的多智能体协作链路网上资料非常零散。有的讲 Codex 安装不讲模型对接有的讲 Ollama 部署不讲 Agent 调度真正把“本地模型 终端 Agent 编排框架”跑通的文章少之又少。这篇文章把最近完整搭通的整套流程整理出来从环境准备、模型拉取、Codex 配置、Agent 编排到高频报错排查和工程化建议一次性讲透。适合刚接触 AI Agent 开发的新手也适合想把手头 Codex 和 Ollama 组合起来做多智能体实验的开发者。1. 背景与核心概念Codex、Hermes、Ollama 到底解决什么问题在动手安装之前先把三个核心组件弄清楚。很多新手失败的原因不是操作不对而是没搞明白每个工具在整条链路里扮演什么角色。1.1 Codex CLI 是什么Codex 是 OpenAI 推出的终端 AI 编程助手它可以跑在命令行里直接用自然语言让 AI 帮助你完成代码编写、文件修改、命令执行、仓库阅读等一系列操作。和传统“复制代码到聊天框里问 AI”不同Codex 本身就是一个 Agent 形态它能看到当前项目目录能读出文件内容甚至能执行 Shell 命令来验证自己的修改结果。从实际体验来说Codex 更适合下面几类场景在已有项目中快速定位问题并直接生成补丁。让 AI 批量完成跨文件的代码修改。用自然语言描述需求让 AI 自动完成一个脚本或小模块。与 Git 配合在独立分支上让 AI 提交代码。Codex 的模型端点支持配置这一点非常关键。官方默认连接 OpenAI 的云服务但我们可以通过修改配置把它指向 Ollama 本地模型或者指向 DeepSeek 等第三方 OpenAI 兼容 API。这也是本文后续对接 Ollama 的技术基础。1.2 Hermes Agent 是什么Hermes 这个词在 AI 圈里有两层常见含义很容易混淆。第一层指 Nous Research 发布的一系列开源模型例如 Hermes 2、Hermes 3、Hermes 4这些模型通常以 Llama 或 Qwen 基座模型微调而来在对话、工具调用、Agent 任务上有不错表现可以通过 Ollama 直接拉取。第二层指社区中越来越多见到的“Hermes Agent”框架它本质上是一个智能体编排工具用来创建和管理多个子 Agent让它们分工协作完成一个复杂任务。比如一个 Agent 负责代码编写另一个负责测试生成第三个负责文档整理再由一个主控 Agent 来分配任务并汇总结果。在本文语境下我们更关注第二层含义即用 Hermes Agent 作为多智能体调度层让 Codex 和本地模型配合起来。如果你拿到的是 Hermes 模型文件那可以直接用 Ollama 运行如果你拿到的是 Agent 框架代码则需要安装依赖并配置模型服务地址。建议在开始前先确认你的 Hermes 包属于哪一种避免把模型和框架混在一起。1.3 Ollama 本地模型服务是什么Ollama 是目前使用门槛最低的本地大模型运行工具。它把模型的下载、存储、启动和 API 暴露封装成了一套极简命令用户不需要关心 Python 虚拟环境、CUDA 配置、推理框架等复杂细节只需要执行ollama pull和ollama run就能用上开源大模型。Ollama 对本文最重要的价值是它提供了 OpenAI 兼容的 HTTP 接口。默认地址是http://localhost:11434/v1这意味着凡是支持 OpenAI API 格式的客户端都可以把base_url改成 Ollama 地址无痛切换到本地模型。Codex 和 Hermes Agent 正是利用这一点来接入本地模型的。1.4 三者的协作关系用一句话概括三者的关系Ollama 负责“模型层”提供本地推理能力。Codex 负责“终端执行层”作为你身边的 AI 程序员。Hermes Agent 负责“调度层”把复杂任务拆给多个 Agent 并行处理。一个典型的多智能体协作流程是这样你向 Hermes Agent 主控节点提交一个需求。主控节点把需求拆成子任务分别分配给代码 Agent、测试 Agent、审查 Agent。每个子 Agent 调用模型完成自己的任务模型既可以是 Ollama 里的本地模型也可以是 DeepSeek 等云端 API。主控节点回收结果做汇总输出。Codex 可以作为其中一个承担编码执行的 Agent直接修改项目文件并运行命令。理解了这个协作关系后面的配置就会顺很多。接下来进入环境准备。2. 环境准备与版本说明2.1 基础运行环境根据多个社区案例和实际测试推荐下面的环境组合操作系统Windows 10/11、macOS 或主流 Linux 发行版。Windows 用户强烈建议启用 WSL2因为 Codex 在 Unix 环境下的命令执行更顺畅。Node.js需要 18 及以上版本Codex CLI 基于 Node.js 生态。Python建议 3.9 及以上版本多个 Agent 框架依赖 Python 环境。Git用于拉取 Agent 框架代码。终端工具Windows Terminal、iTerm2 或 VS Code 内置终端都可以。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。不同版本之间的命令差异如果出现通常体现在模型名称或配置字段上我会在对应位置提醒你注意。2.2 安装 OllamaOllama 的安装非常直接。macOS 和 Linux 用户可以执行官方安装脚本curl -fsSL https://ollama.com/install.sh | shWindows 用户则直接前往 Ollama 官网下载安装包安装完成后命令行里检查版本ollama --version如果能看到版本号就说明安装成功。接着启动服务ollama serve服务默认监听 11434 端口。不过要注意ollama serve会占用当前终端建议把它放到后台执行或者直接依赖 Ollama 安装时自带的开机自启服务。验证服务是否正常curl http://localhost:11434/v1/models如果返回一段 JSON 数组说明 API 服务已经可用了。2.3 安装 CodexCodex 的安装方式以官方 GitHub 仓库为准目前最常见的安装方式是通过 npm 全局安装npm install -g openai/codex安装完成之后检查版本codex --version如果命令找不到通常是 Node.js 的全局 bin 目录没有加入 PATH需要手动配置一下环境变量。Codex 支持两种认证方式一种是交互式登录执行codex login后按提示完成授权另一种是直接配置 API Key。对于自动化场景更推荐 API Key 方式后面第 3 节会具体讲配置方法。2.4 安装 Hermes AgentHermes Agent 的安装方式取决于你使用的具体项目因为社区里存在不同实现。这里给出一个通用思路让你拿到任何仓库都能快速装上从官方 GitHub 仓库克隆代码到本地。如果项目是 Python 写的创建虚拟环境并安装依赖。如果项目是 Node.js 写的直接执行npm install。打开配置文件把你自己的模型服务地址填进去。启动主控 Agent。以 Python 项目为例通用安装过程大致如下git clone https://github.com/your-org/hermes-agent.git cd hermes-agent python -m venv venv source venv/bin/activate pip install -r requirements.txt这里只是一个思路示意不是某个具体仓库的完整安装命令。你实际操作时一定要以仓库 README 的说明为准。如果你是希望运行 Hermes 模型本身那么不需要下载 Agent 框架直接用 Ollama 拉取即可ollama pull hermes3这样拉取下来的是模型权重可以用ollama run hermes3直接对话。务必先分清你的目标是搭建 Agent 框架还是运行 Hermes 模型。2.5 验证基础环境环境安装完成之后我习惯先做一轮“健康检查”确认每个组件都可用再继续后面的配置。检查清单如下检查项命令预期结果Ollama 服务curl http://localhost:11434/v1/models返回 JSON包含已安装模型Ollama 版本ollama --version输出版本号Codex 版本codex --version输出版本号Node.js 版本node -v输出 v18 以上版本Python 版本python --version输出 3.9 以上版本如果curl请求 Ollama 时长时间无响应检查 11434 端口是否被防火墙拦截或者ollama serve是否真的在运行。3. 核心配置与原理拆解环境搭好之后我们先不急着跑复杂任务而是把最关键的配置原理讲清楚。很多报错都源于对配置文件不理解导致改错字段。3.1 Codex 配置文件结构Codex 的配置文件默认位于用户目录下的.codex/config.toml。它的作用类似.gitconfig集中管理模型提供方、API 地址、认证信息、运行参数等。一个典型的对接本地模型的配置如下# 文件路径~/.codex/config.toml model qwen3:8b model_provider ollama [model_providers.ollama] name Ollama Local base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api chat这里的字段含义如下model指定默认使用的模型名称必须和 Ollama 里已有的模型标签一致。model_provider指定使用哪一组提供方配置对应下面的[model_providers.ollama]。base_url模型服务的 API 地址Ollama 的 OpenAI 兼容地址就是http://localhost:11434/v1。env_key从哪个环境变量读取 API Key。Ollama 本地服务不需要鉴权但 Codex 配置要求有这个字段随意填一个即可保证不报错。wire_api接口协议类型。chat表示使用 Chat Completions 协议Codex 也支持responses协议具体取决于你的 Codex 版本。Ollama 兼容端点默认支持 chat 格式。如果你要对接 DeepSeek 云端 API只需要把提供方配置换成[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat然后在系统环境变量里设置export DEEPSEEK_API_KEY你的密钥这种可插拔的配置方式让 Codex 可以灵活地在多个模型之间切换本地用 Ollama云端用 DeepSeek完全不需要改代码。3.2 Ollama 的 OpenAI 兼容 APIOllama 从较早的版本开始就提供了 OpenAI 兼容接口这对所有想接入本地模型的工具来说都至关重要。因为主流 AI 工具基本都兼容 OpenAI 的请求格式Ollama 只要“伪装”成一个 OpenAI API就能无缝接入大量生态。我们可以用一个 curl 请求来验证这个接口curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen3:8b, messages: [{role: user, content: 你好请介绍一下你自己}] }如果模型已经拉取成功接口会返回类似下面的 JSON{ id: chatcmpl-xxx, object: chat.completion, created: 1731234567, model: qwen3:8b, choices: [ { index: 0, message: { role: assistant, content: 你好我是一个基于 Qwen 模型构建的本地 AI 助手…… }, finish_reason: stop } ] }这里有两个字段要重点理解message.content模型生成的文本内容。choices模型返回的候选项数组通常只需要取第一个。Codex、Hermes Agent 本质上都是在拼这样的请求再解析返回结果。理解了协议本身哪怕你后续不用这些框架也能自己写代码调用本地模型。3.3 Hermes Agent 多智能体协作原理多智能体协作不是新鲜概念但落地时容易设计混乱。最简单可靠的模式是“主控-工人”模式主控 AgentOrchestrator负责接收用户需求理解任务结构。主控把任务拆成若干子任务分发给不同工人 AgentWorker。每个工人 Agent 只处理自己负责的子任务可以绑定不同的模型。工人把结果返回给主控主控做整合与校验。举个例子假设用户输入“帮我开发一个命令行单词查询工具”主控 Agent 可以这样拆分子任务负责 Agent绑定模型项目结构设计架构 Agentqwen3:8b核心逻辑编码编码 Agentcodex单元测试编写测试 Agenthermes3使用文档生成文档 Agentqwen3:8b每个 Agent 各司其职互不干扰。主控 Agent 只负责任务分发和结果汇总。这种模式实现简单扩展性好非常适合本地实验。4. 完整实战从零搭建 Codex Ollama 多智能体协作环境这一节我们完整走一遍实战先用 Ollama 跑起本地模型然后让 Codex 接入再实现一个最简多智能体协作 Demo。4.1 创建项目结构先在本地创建一个实验目录mkdir -p ~/codex-agent-demo/{agents,config,logs} cd ~/codex-agent-demo目录说明agents存放多智能体脚本。config存放自定义配置文件。logs存放运行日志。4.2 拉取并运行本地模型本文以qwen3:8b为例这是目前本地部署中综合表现比较均衡的模型对中文支持好显存需求适中。如果你显存较小可以换成qwen3:4b。拉取模型ollama pull qwen3:8b拉取成功后验证ollama list你应该能在列表里看到qwen3:8b。然后启动一次对话测试ollama run qwen3:8b 你好如果模型能正常回应说明本地模型已经就绪。这一步很关键它把“模型下载”和“API 调用”的问题独立出来后面接 Codex 时才不会把错误混在一起。4.3 配置 Codex 接入本地模型修改~/.codex/config.toml写入下面的完整配置# 文件路径~/.codex/config.toml model qwen3:8b model_provider ollama approval_policy on-request [model_providers.ollama] name Ollama Local base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api chat其中approval_policy表示命令执行前需要等待用户确认新手建议保留这个配置避免 Agent 自动执行高风险命令。保存配置后在项目目录里调用一次 Codexcd ~/codex-agent-demo codex 请读取当前目录结构并告诉我这个项目是做什么的如果配置成功Codex 会调用 Ollama 里的qwen3:8b来理解你的请求。由于是本地模型响应速度取决于你的 CPU/GPU 性能。这里需要特别说明如果你希望 Codex 调用云端 DeepSeek则把model_provider改了即可。逻辑完全一样区别只在于模型执行的物理位置。4.4 编写一个最简多智能体协作脚本我们不依赖任何重框架用纯 Python 写一个多智能体协作示例这样你能直观理解主控-工人模式的本质。脚本里每个 Agent 都通过 HTTP 调用 Ollama 模型。首先安装依赖pip install requests然后创建agents/orchestrator.py# 文件路径~/codex-agent-demo/agents/orchestrator.py import requests import json OLLAMA_URL http://localhost:11434/v1/chat/completions def call_model(model: str, prompt: str, max_tokens: int 1024) - str: payload { model: model, messages: [{role: user, content: prompt}], max_tokens: max_tokens, temperature: 0.7 } try: resp requests.post(OLLAMA_URL, jsonpayload, timeout300) resp.raise_for_status() data resp.json() return data[choices][0][message][content] except requests.exceptions.RequestException as e: return f[模型调用失败] {e} def run_worker(worker_name: str, task: str, model: str) - None: print(f\n {worker_name} Agent 开始执行 ) result call_model(model, task) print(f--- {worker_name} 输出 ---) print(result) def main(): # 模拟主控 Agent 的任务拆分 tasks [ (架构, 请简单设计一个Python命令行单词查询工具的模块划分只输出模块列表和职责。, qwen3:8b), (测试, 请为上述工具列出三个关键测试场景只列出场景名和验证点。, qwen3:8b), (文档, 请生成一个README模板包含安装和基本用法。, qwen3:8b) ] print(主控 Agent 开始分发任务...) for worker_name, task, model in tasks: run_worker(worker_name, task, model) print(\n 所有任务执行完毕 ) if __name__ __main__: main()这个脚本很简单但演示了多智能体最核心的三个要素每个 Worker 有独立职责对应不同的任务提示词。每个 Worker 可以绑定不同模型。主控 Agent 负责按顺序调度和汇总。你可以把call_model函数里的OLLAMA_URL替换成 DeepSeek 的官方地址再把model改成deepseek-chat同一个脚本就能对接云端模型这就是多智能体协作里的“模型可替换性”。运行脚本cd ~/codex-agent-demo python agents/orchestrator.py预期输出格式如下主控 Agent 开始分发任务... 架构 Agent 开始执行 --- 架构 输出 --- 1. 参数解析模块 2. 词典查询模块 3. 结果格式化模块 ... 测试 Agent 开始执行 --- 测试 输出 --- 1. 查询存在的单词 2. 查询不存在的单词 3. 空输入处理 ... 文档 Agent 开始执行 --- 文档 输出 --- # 单词查询工具 ...注意模型输出不是固定的每个人拿到结果都可能不同。只要脚本不报错、每个 Agent 都能返回文本链路就算跑通了。4.5 实现更真实的多智能体协作上面的示例只是顺序调用。真实场景里多个 Agent 之间往往有依赖关系比如文档 Agent 需要参考架构 Agent 的输出。下面增加一个“结果传递”的版本让你看到主控如何把前一个 Agent 的输出交给后一个 Agent 作为上下文# 文件路径~/codex-agent-demo/agents/orchestrator_with_context.py import requests import json OLLAMA_URL http://localhost:11434/v1/chat/completions def call_model(model: str, prompt: str, max_tokens: int 1024) - str: payload { model: model, messages: [{role: user, content: prompt}], max_tokens: max_tokens, temperature: 0.7 } resp requests.post(OLLAMA_URL, jsonpayload, timeout300) resp.raise_for_status() return resp.json()[choices][0][message][content] def main(): architecture_result call_model( qwen3:8b, 请设计一个Python命令行单词查询工具的模块划分只输出模块列表和职责。 ) print( 架构 Agent 输出 ) print(architecture_result) test_prompt f基于以下架构设计生成测试场景\n{architecture_result}\n只输出场景名称。 test_result call_model(qwen3:8b, test_prompt) print(\n 测试 Agent 输出 ) print(test_result) doc_prompt f基于以下架构设计生成README\n{architecture_result}\n只输出README的Markdown内容。 doc_result call_model(qwen3:8b, doc_prompt) print(\n 文档 Agent 输出 ) print(doc_result) if __name__ __main__: main()这个版本更接近真实场景后一个 Agent 站在前一个 Agent 的肩膀上继续工作。你甚至可以让测试 Agent 把架构输出中的模块名直接提取出来生成对应的测试文件。这种“级联传递”是多智能体协作的常见形态也是后续学习 LangGraph、CrewAI 等框架时最核心的思维模型。5. 高频报错与排查思路实际配置中最容易卡住新手的不是概念而是各种报错。下面把社区里出现频率较高的几个问题整理出来。5.1 Codex 报错cc switch local proxy failed while handling codex endpoint /responses这个报错经常出现在使用本地代理切换工具的情况下。字面意思是Codex 在处理/responses端点请求时本地代理切换失败导致请求没有真正发出去。可能原因本地代理工具异常退出但 Codex 持有的代理连接没有释放。系统环境变量里残留了HTTP_PROXY/HTTPS_PROXY指向一个不可用的代理端口。Codex 配置文件里存在旧的代理设置。排查步骤检查当前终端的代理环境变量env | grep -i proxy如果不需要代理直接清空unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY重启终端再执行一次codex命令。如果你确实需要通过代理访问外部 API请使用公司 IT 或机构批准的合规代理配置并确认代理端口可访问不要使用来源不明的代理服务。检查~/.codex/config.toml里是否配置了代理相关字段如果有确保地址正确。这个报错的核心是“本地代理切换失败”不是 Codex 本身坏了所以优先排查代理环境变量。5.2 Agent 运行中止agent terminated due to error you can prompt the model to try again or start这个提示比较模糊意思是一个 Agent 在执行过程中因为错误被终止系统建议你提示模型重试或重新启动。常见原因有模型服务不可用比如 Ollama 没启动或者模型没有被正确拉取。请求超出了上下文长度限制输入内容太长。模型返回了不合法格式Agent 解析失败。任务过于复杂模型在单次调用中无法完成。网络超时或代理问题。排查方法先用 curl 手动测试模型接口是否正常。查看 Codex 的完整错误日志不要只看最后一行提示。把任务拆得更小不要试图让一个 Agent 一次完成所有事情。适当增大超时时间。确认模型名称是否和 Ollama 中的标签完全一致注意版本号。5.3 Ollama 下载模型太慢Ollama 下载大模型时速度慢是国内用户最常见的痛点。一个 8B 模型动辄 5GB 以上如果直连官方源速度确实不稳定。几种缓解方案设置模型文件存放目录到空间充足的磁盘避免因空间不足反复失败。如果网络条件差可以配置可信的镜像源或企业内网代理缓存但要注意信息安全和合规性。先用小模型qwen3:4b完成链路调试确认可行后再换大模型。检查模型目录的环境变量echo $OLLAMA_MODELS如果目录空间不够可以切换export OLLAMA_MODELS/data/ollama/models设置完环境变量后需要重启 Ollama 服务。下载慢的问题普遍存在但它不影响整体架构。建议先把小模型跑通再慢慢补大模型。5.4 其他常见问题汇总问题现象常见原因解决思路Codex 提示认证失败API Key 无效或环境变量未设置检查env_key对应的环境变量重新生成 KeyOllama 端口冲突11434 被其他程序占用修改 Ollama 端口或结束占用进程内存不足导致模型崩溃模型尺寸超过物理内存/显存换更小的模型或减少并发Agent 输出乱码终端编码问题设置 UTF-8 编码环境变量Codex 无法读取项目文件权限不足检查目录权限避免在权限受限目录运行Hermes Agent 依赖安装失败Python 版本过低升级 Python 到 3.9 以上6. 生产环境最佳实践与注意事项实验环境跑通之后如果要应用到真实项目或团队协作必须注意下面几个维度。6.1 安全边界与权限管理Codex 这类 Agent 工具具备执行命令的能力这既是它的优势也是它的风险来源。在生产环境或公司内网使用时请务必遵守以下原则使用最小权限账号运行 Agent绝不要用 root 或管理员账号直接跑。API Key 不要写死在代码或配置文件里用环境变量或密钥管理平台。Ollama 服务默认监听 localhost不要随意暴露到公网。如果确实需要远程访问必须加鉴权并限制来源 IP。涉及数据库操作、文件删除、生产环境变更时应先备份并设置人工审批环节。如果你使用的是公司内网模型服务遵守公司安全规定不要私自搭建代理或绕过访问控制。6.2 资源控制与性能优化本地模型的内存占用不容小觑。以 8B 模型为例加载到内存后占用经常超过 8GB如果同时运行多个 Agent很容易撑爆内存。建议同一时间只加载一个主模型其他 Agent 共享同一个模型服务。用max_tokens限制单次模型输出长度避免 Agent 生成超长文本拖慢速度。控制并发请求数量Ollama 支持配置并发参数但默认值不一定适合你的机器。长时间不用的模型使用ollama stop释放内存。6.3 多智能体任务拆分的工程建议多智能体不是越多越好。每个 Agent 都会带来上下文传递开销任务拆碎后反而可能降低整体效率。设计时要遵循按职责拆分而不是按步骤拆分。比如“编码”“测试”“审查”是职责而“写第 1 行”“写第 2 行”不是职责。每个子 Agent 的工作产物要尽量独立方便并行执行和结果聚合。主控 Agent 必须对子 Agent 的输出做验证不能无脑相信模型结果。用统一的输入输出格式约束 Agent避免一个 Agent 输出 JSON另一个输出 Markdown导致主控无法解析。6.4 Codex 使用效率技巧Codex 在真实项目中效率很高但前提是配合良好的项目说明。官方推荐在项目根目录维护一份AGENTS.md文件里面描述项目结构、技术栈、常用命令和规范。这样 Codex 每次启动时都能快速理解项目背景生成的代码更加贴合项目现状。一个最小示例# AGENTS.md ## 项目简介 这是一个基于 Python 的命令行单词查询工具。 ## 技术栈 - Python 3.10 - Click 8.0 ## 常用命令 - 安装依赖pip install -r requirements.txt - 运行测试pytest tests/ - 启动工具python main.py --word hello ## 代码风格 - 使用 type hints - 所有函数必须有 docstring - 单测覆盖核心查询逻辑有了这样一个文件Codex 的输出质量会有明显提升。7. 总结与下一步学习方向这篇文章从零开始完整演示了 Ollama 部署本地模型、Codex 接入自定义模型端点、Hermes Agent 思路下的多智能体协作脚本编写并整理了实际运行中最常见的报错和排查手段。整个链路跑通之后你会发现所谓“多智能体协作”并不神秘本质上就是不同功能的 Agent 通过模型 API 互相配合关键在任务拆分、上下文传递和结果校验。接下来你可以往这几个方向继续深入学习 LangGraph 或 CrewAI 这类成熟的多智能体框架替代手写调度脚本。给 Ollama 配置 GPU 加速提高本地模型推理速度。研究 MCPModel Context Protocol让 Agent 接入更多外部工具。把 RAG检索增强生成加入链路让 Agent 能基于私有文档回答问题。建议你先花一个下午把本文的示例代码跑通再逐步替换成自己的任务场景。如果你在操作过程中遇到新报错保留好终端日志按“现象-原因-解决”的顺序排查大部分问题都能定位到配置或网络层面。