之前在做 AI 编程助手落地时我反复卡在 Codex 的登录、本地模型接入和多 Agent 协作编排上搜索到的资料不是太零散就是版本太旧。这篇文章准备把“Codex Hermes Ollama 多智能体协作”的完整闭环流程整理出来从概念、环境搭建、本地模型部署到 Codex 接入、编排器编写和常见报错排错一次性讲清楚。零基础可以按顺序跟做有经验的开发者可以直接跳到第 4 节看配置思路。1. 为什么 2026 年还需要掌握 Codex、Agent 与本地大模型1.1 Codex 是什么Codex 是 OpenAI 推出的命令行 AI 编程 Agent你可以把它理解为“跑在终端里的 AI 程序员”。它会读取你当前项目目录的文件理解你的自然语言指令然后生成代码、修改文件、执行命令并在完成后把改动结果告诉你。相比直接在网页对话框里粘贴代码Codex 最大的优势是它贴近真实开发环境可以真正操作 Git、运行测试、调试报错。目前 Codex 可以通过 npm 安装为命令行工具开源版本支持接入不同的模型供应商。2026 年的 Agent 开发已经进入工具链成熟期Codex 的角色不再只是“代码补全工具”而是整个智能体体系中的“执行体”它负责生成和修改代码但不一定负责任务拆分和决策决策部分可以由其他 Agent 或本地模型完成。1.2 Agent 与 Harness 的区别搜索“harness 和 agent 区别”的人很多这里先把这个概念厘清。Harness 在 AI Agent 领域中通常指“模型调用与工具调用的运行时框架”它负责管理模型的输入输出循环、工具注册、错误恢复和上下文窗口。可以理解为“载具”或“运行容器”。Agent 则是运行在这个环境中的“智能体逻辑”它决定下一步该调用哪个工具、生成什么内容、如何判断任务是否完成。举个例子Ollama 是一个模型运行时负责加载和推理模型它属于“底座”Codex 是模型之上的 Agent它调用底层模型并操作终端而 Hermes 在本文中承担的是“编排者”角色负责拆解任务、派发任务并汇总结果。这样一层层分工后多智能体协作就不再是一个模糊的概念而是可运行的工程结构。1.3 Hermes 和 Ollama 在体系中的位置Hermes 这个词在不同场景下有两种常见含义一种是 NousResearch 发布的开源 Hermes 系列大模型它们经常被量化后放到 Ollama 中运行另一种是社区中基于大模型封装出来的 Agent 编排框架或脚本工具。本文的实战部分会采用第二种理解通过一个轻量 Python 编排器来模拟 Hermes Agent 的调度逻辑同时也会演示如何把 Hermes 系列模型导入 Ollama 运行。Ollama 则是本地大模型部署工具它把模型下载、量化、推理接口、上下文管理都封装成了简单的命令。你只需要执行ollama run qwen2.5:7b这类命令就能在本地启动一个 OpenAI 兼容的推理服务。Ollama 在体系中的位置是最底层它不负责“思考”只负责“提供模型推理能力”。1.4 多智能体协作能解决什么问题单个 Agent 的能力有边界。Codex 擅长写代码但不擅长长时间保持任务上下文本地模型隐私性好、成本低但代码生成能力往往不如云端模型。把它们组成多智能体协作系统后可以实现“调度者 执行者 评审者”的分工Hermes Agent 负责任务拆解Codex 负责落地代码Ollama 上的本地模型负责做代码评审和常规问答。这种协作方式的直接收益有三个第一复杂任务被拆成多个子任务后每个模型只需关注相对简单的部分成功率明显提升第二涉及敏感代码时可以把子任务交给本地模型处理避免把私有代码发送到云端第三可以混合调度云端模型和本地模型在成本和效果之间取平衡。2. 环境准备与版本说明2.1 操作系统与运行环境本文以 Windows 11 WSL2 Ubuntu 22.04 作为演示环境macOS 和纯 Linux 操作基本一致。Codex CLI 依赖 Node.js 18 以上版本Python 编排脚本依赖 Python 3.10 以上版本。建议先确认版本避免后面出现莫名其妙的兼容问题。node -v npm -v python3 --version如果你的环境还没有安装 Node.js推荐使用 nvm 安装这样方便切换版本。Windows 用户建议统一在 WSL2 内操作Ollama 在 WSL2 里运行更稳定Codex 操作文件时也减少路径转换问题。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。2.2 安装 OllamaOllama 官方提供了多平台安装包Linux 和 WSL2 下可以用一条命令安装curl -fsSL https://ollama.com/install.sh | sh安装完成后启动服务并验证ollama serve新开一个终端窗口查看版本ollama --version如果看到输出类似ollama version 0.x.x说明 Ollama 已正常启动。Ollama 默认监听http://localhost:11434后续 Codex 和编排脚本都会通过这个地址调用本地模型。2.3 安装 Codex CLICodex CLI 通过 npm 发布全局安装命令npm install -g openai/codex安装后验证codex --versionCodex 的登录方式有两种一是使用 ChatGPT 账号交互式登录二是使用 API Key 登录。具体登录流程在第 4 节展开。如果你发现 npm 下载速度慢可以临时切换 npm 镜像源npm config set registry https://registry.npmmirror.com安装完成后建议换回默认源避免后续发布新版本时出现缓存不一致的问题。2.4 项目目录结构为了演示多智能体协作我们先规划一个统一目录~/codex-agent-demo/ ├── workspace/ # Codex 的工作目录代码会生成在这里 ├── scripts/ │ └── hermes_agent.py # Hermes Agent 编排脚本 ├── config/ │ └── config.toml # Codex 配置文件 └── logs/ └── agent.log # 编排器运行日志实际创建目录的命令mkdir -p ~/codex-agent-demo/{workspace,scripts,config,logs}后面的所有操作都基于这个目录展开。3. 先跑通本地模型Ollama 部署与加速下载3.1 拉取第一个模型Ollama 安装完成后第一步是拉取一个本地模型。为了方便演示这里选择qwen2.5:7b它是一个中英文能力均衡、量化后体积适中的模型普通 16G 内存的机器就能运行。ollama pull qwen2.5:7b拉取完成后直接用命令行对话框验证ollama run qwen2.5:7b 用一句话介绍你自己如果模型能正常回复说明推理链路已经通了。接下来要确认 Ollama 的 HTTP 接口可用curl http://localhost:11434/v1/models这个接口是 OpenAI 兼容格式的模型列表接口看到返回的 JSON 中包含qwen2.5:7b就说明本地模型服务已经就绪。3.2 国内下载慢的解决方案很多同学卡在ollama pull速度极慢甚至直接失败。默认情况下模型文件从境外的 registry 拉取网络不稳定时很容易中断。这里给出几种安全且合规的加速思路第一使用代理环境变量。如果你所在企业或实验室网络有 HTTP 代理可以在当前终端设置export HTTPS_PROXYhttp://your-proxy-ip:port export HTTP_PROXYhttp://your-proxy-ip:port注意这里说的是合规的企业代理或实验网络代理设置完成后重新执行ollama pull。第二通过国内模型社区下载 GGUF 文件。你可以在 ModelScope 魔搭社区等平台搜索对应模型的 GGUF 量化版本下载后通过 Modelfile 导入 Ollama这个方案最稳定不依赖 registry 的网络状态。第三如果只是安装包下载慢可以考虑从镜像站获取 Ollama 安装包但建议只从官方渠道或可信社区获取安装包避免引入安全风险。3.3 用 Modelfile 导入 GGUF 模型当你已经从可信渠道下载好了 GGUF 模型文件后创建一个ModelfileFROM ./qwen2.5-7b-instruct-q4_k_m.gguf然后在模型文件所在目录执行ollama create qwen2.5:7b -f Modelfile创建完成后同样可以用ollama run qwen2.5:7b验证。这种方式的优点是模型文件来源可控下载过程可以断点续传适合模型体积较大的场景。3.4 验证 Ollama APIOllama 不仅提供命令行交互还提供 OpenAI 兼容的 HTTP 接口。我们用 Python 脚本验证一下确保后续编排脚本可以直接调用import requests response requests.post( http://localhost:11434/v1/chat/completions, json{ model: qwen2.5:7b, messages: [ {role: user, content: 请回复Hello from Ollama} ] } ) print(response.json()[choices][0][message][content])如果一切正常你会看到模型返回了一段自然语言内容。这个接口格式非常重要后面 Codex 接入本地模型时用的就是同一套协议。4. 配置 Codex接入本地模型与云端模型4.1 Codex 的登录方式Codex 首次运行时需要登录。如果你之前了解过codex 官网登录入口相关的问题这里统一说明Codex 的官方信息以 GitHub 上的openai/codex仓库为准同时需要有 OpenAI 账号或 API Key。交互式登录执行codex login这种方式会打开浏览器让你授权 ChatGPT 账号。如果当前环境没有浏览器也可以使用 API Key 方式直接把 Key 写入环境变量export OPENAI_API_KEY你的API Key登录后可以进入交互模式测试codex在交互模式下输入一个简单的任务例如“写一个 Python 斐波那契函数”确认 Codex 能正常调用模型并返回结果。这一步可以帮你区分问题是出在“登录鉴权”还是“模型接入”上。4.2 config.toml 配置模型供应商Codex 默认使用 OpenAI 官方模型但通过配置文件可以自定义模型供应商。配置文件位于~/.codex/config.toml。下面是一个接入本地 Ollama 的示例model qwen2.5:7b model_providers [ { name ollama, base_url http://localhost:11434/v1, env_key OLLAMA_API_KEY } ]这里有几个关键参数需要理解model指定 Codex 默认使用的模型名称。name给模型供应商起一个便于识别的名字。base_url供应商的 API 地址Ollama 默认地址就是http://localhost:11434/v1。env_key读取 API Key 的环境变量名称。Ollama 本地服务不需要真实鉴权但 Codex 会尝试从环境变量里读取所以你需要先设置一个任意值的环境变量否则请求可能无法通过校验。设置环境变量export OLLAMA_API_KEYollama配置完成后还可以加上model_provider ollama来强制使用该供应商model qwen2.5:7b model_provider ollama不同版本的 Codex 对模型供应商的配置结构略有差异如果你发现配置不生效先用codex --help或codex exec --help查看当前版本支持的参数。4.3 接入 DeepSeek 等 OpenAI 兼容模型除了本地 OllamaCodex 还可以接入其他 OpenAI 兼容接口比如 DeepSeek。很多人在搜索codex 接入 deepseek配置其实很简单model deepseek-chat model_providers [ { name deepseek, base_url https://api.deepseek.com/v1, env_key DEEPSEEK_API_KEY } ] model_provider deepseek然后设置export DEEPSEEK_API_KEY你的DeepSeek API Key使用云端模型的好处是代码生成能力和复杂推理能力更强适合处理大型任务本地模型的优势是隐私和成本。实际项目中可以把两者混合使用第 5 节的编排器正有这个思想。4.4 启动方式与常用参数Codex 支持交互式启动和单次执行两种模式。单次执行在 Agent 编排中非常有用比如这个命令codex exec 创建一个 Python 计算器程序 --sandbox danger这里--sandbox danger表示允许 Codex 直接操作文件系统。生产环境不建议轻易使用正确的做法是让 Codex 在独立的工作目录中运行并严格执行权限控制。查看所有可用参数codex exec --help常见的参数包括指定工作目录-C、跳过 Git 仓库检查--skip-git-repo-check、指定输出格式等。每个版本略有差异以你本地的帮助文档为准。5. 多智能体协作实战Hermes Agent Codex Ollama5.1 协作架构设计在开始写代码之前先明确协作流程。整个系统包含三个角色编排者Hermes Agent接收用户任务拆解子任务分配执行顺序。执行者Codex负责写代码、改文件、执行终端命令。评审者Ollama 本地模型对 Codex 生成的代码做基础评审和风险提示。处理一个任务的流程如下用户在编排器中输入任务描述。编排器调用本地模型将任务拆解为多个子步骤。编排器将编码类子任务派发给 Codex 执行。Codex 执行完成后编排器将代码片段发送给本地模型做评审。编排器汇总执行结果和评审意见输出日志和报告。这个流程避免了单一 Agent 的上下文过长问题每个 Agent 都只处理自己擅长的部分任务完成后上下文就可以释放。5.2 编写编排器创建一个 Python 文件scripts/hermes_agent.py代码如下import subprocess import sys import requests import json import datetime OLLAMA_URL http://localhost:11434/v1/chat/completions OLLAMA_MODEL qwen2.5:7b WORKSPACE ../workspace def log(message): ts datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) print(f[{ts}] {message}) def call_ollama(prompt, modelOLLAMA_MODEL): payload { model: model, messages: [{role: user, content: prompt}], temperature: 0.2 } response requests.post(OLLAMA_URL, jsonpayload, timeout120) response.raise_for_status() return response.json()[choices][0][message][content] def split_task(task): log(开始拆解任务...) prompt ( 你是一个任务编排器。请把以下任务拆解为多个子步骤 每个子步骤单独一行不要编号不要写额外说明。\n f任务{task} ) result call_ollama(prompt) steps [line.strip() for line in result.splitlines() if line.strip()] log(f任务拆解为 {len(steps)} 个子步骤) return steps def run_codex(instruction, workdirWORKSPACE): log(f派发任务给 Codex{instruction[:60]}...) cmd [codex, exec, instruction, --sandbox, danger, -C, workdir] result subprocess.run(cmd, capture_outputTrue, textTrue, timeout600) log(fCodex 退出码{result.returncode}) return result.stdout, result.stderr def review_code(code_text): log(使用本地模型进行代码评审...) prompt ( 你是代码评审助手。请检查以下代码是否有明显的 bug、安全问题或改进空间。 用简洁列表输出评审意见。\n f代码\n{code_text[:3000]} ) return call_ollama(prompt) def main(): if len(sys.argv) 2: print(用法python hermes_agent.py 你的任务描述) sys.exit(1) task sys.argv[1] log(f接收任务{task}) steps split_task(task) code_outputs [] for step in steps: log(f执行子步骤{step}) code_instruction ( f{step}\n 请在当前目录下完成必要的代码编写确保代码可以运行。 ) stdout, stderr run_codex(code_instruction) code_outputs.append(stdout) log(fCodex 输出摘要{stdout[:300]}) combined_output \n.join(code_outputs) review review_code(combined_output) log( 执行结果汇总 ) log(f任务拆分得到的子步骤{steps}) log(fCodex 执行输出\n{combined_output}) log(f本地模型评审意见\n{review}) if __name__ __main__: main()这段脚本的核心逻辑有几个关键点。call_ollama函数把请求发送给本地 Ollama 的 OpenAI 兼容接口用于任务拆解和代码评审。split_task先让本地模型输出拆解后的子步骤每一行一个任务。run_codex调用系统命令codex exec并传入子步骤作为指令。review_code在代码生成完成后把代码片段交给本地模型做二次检查。注意这里用了--sandbox danger因为编排器需要让 Codex 在工作目录中自由创建文件。如果你只是实验建议单独给 workspace 目录做快照避免误操作。5.3 执行与结果说明运行编排器cd ~/codex-agent-demo/scripts python hermes_agent.py 用 Python 写一个待办事项管理 CLI 工具支持新增、列出、删除待办事项执行过程中你会看到类似这样的运行日志[2026-01-15 10:30:01] 接收任务用 Python 写一个待办事项管理 CLI 工具支持新增、列出、删除待办事项 [2026-01-15 10:30:02] 开始拆解任务... [2026-01-15 10:30:35] 任务拆解为 4 个子步骤 [2026-01-15 10:30:36] 派发任务给 Codex设计待办事项的数据结构... [2026-01-15 10:31:20] Codex 退出码0 ...整个流程执行完成后转到 workspace 目录查看生成的文件ls ~/codex-agent-demo/workspace如果 Codex 正常完成任务这里会多出 Python 源文件。编排器最后还会输出本地模型的评审意见比如“建议增加输入校验”“SQLite 连接需要关闭”等提示。这里需要说明一点codex exec的执行结果受模型能力影响很大。使用本地小模型时生成代码的准确率可能不如云端模型使用云端模型时网络延迟和费用会上升。因此实际项目里要根据任务难度动态选择执行者。6. 常见问题与排查思路6.1 Codex 报错cc switch local proxy failed while handling codex endpoint很多人遇到类似cc switch local proxy failed while handling codex endpoint /responses. provi...的报错。这个报错的本质是 Codex 在请求/responses接口时网络请求被本地代理挡了一下导致连接异常。可能原因有三个终端环境变量里设置了HTTP_PROXY或HTTPS_PROXY系统代理工具开启了全局代理Codex 内部读取了本地代理配置但代理服务突然中断。排查思路env | grep -i proxy如果输出中有代理地址并且你当前并不需要代理可以临时清空再执行unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY codex如果你确实需要代理例如企业内网环境那么应该检查代理地址是否可达、是否允许访问目标 API 域名。这个问题通常不是 Codex 本身的 bug而是网络链路不匹配。6.2 报错agent terminated due to erroragent terminated due to error you can prompt the model to try again or start是 Agent 运行时的常见报错。它表示 Agent 在某个环节执行出错可能是模型返回异常、上下文窗口超限、工具调用失败或者是网络超时。处理办法是分层排查。第一步看日志输出确认报错发生在哪个阶段是任务拆解阶段、Codex 执行阶段还是评审阶段。第二步如果是模型调用超时减小输入文本长度或者把大任务拆得更细。第三步如果是云端模型返回异常检查 API 额度是否用完如果是本地模型检查 Ollama 是否还在运行、内存是否充足。ollama ps这个命令可以查看当前加载的模型和内存占用情况。如果内存不足考虑换更小的量化版本。6.3 Ollama 下载慢怎么办这个问题在搜索里出现频率很高。Ollama 下载慢分为两种情况模型下载慢和安装包下载慢。模型下载慢最有效的解决方案是关闭当前镜像源并切换网络环境或者通过 GGUF 导入方式绕过默认下载通道。安装包下载慢则可以从可信镜像站获取。无论哪种方式都不要随意使用来路不明的脚本防止引入恶意程序。另外模型下载中断后重新执行ollama pullOllama 通常会从断点继续不需要重新下载。6.4 Codex 登录与鉴权问题如果你在登录时遇到页面无法打开、登录后显示 401、API Key 无效等提示先把鉴权文件重置重新登录rm -rf ~/.codex/auth.json codex login如果使用的是 API Key确认环境变量是否正确设置echo $OPENAI_API_KEY对于 DeepSeek 或其他兼容供应商确认 key 名称是否与配置里的env_key对应。鉴权问题百分之八十出在“配置里写的环境变量名”和“实际设置的变量名”不一致。问题现象常见原因解决思路codex 启动报 proxy failed本地代理配置与请求链路不匹配检查并清空 proxy 环境变量或检查代理可达性agent terminated due to error上下文超限、模型返回异常、超时查看日志定位阶段缩小任务粒度检查内存ollama pull 速度慢默认从境外 registry 拉取使用 GGUF 导入或者配置可信代理codex 登录失败auth.json 损坏或 Key 错误删除 auth.json 重新登录检查环境变量access to /responses failedAPI 版本不兼容更新 codex 和配置文件7. 最佳实践与工程建议7.1 安全与权限控制多智能体协作的权限管理比单 Agent 更重要。Codex 执行时尽量限制在独立的工作目录禁止让它直接操作整个系统。如果业务涉及数据库或生产环境必须让 Codex 运行在测试环境容器中遵循最小权限原则。本地模型虽然隐私性好但同样不能随意读取敏感文件。7.2 上下文与任务拆分粒度Agent 最容易翻车的点就是上下文过长。实践中的经验是子任务越小成功率越高。与其让 Codex 一次生成一个完整项目不如拆成“先设计数据结构”“再写业务逻辑”“最后补测试”这种粒度。每个子任务结束后上下文可以释放下一任务从干净状态开始。7.3 模型选型与成本控制不要把本地模型和云端模型对立起来应该按任务类型调度。日常问答、代码评审、格式转换可以交给本地模型复杂架构设计、跨文件重构、新框架使用等需要深度推理的任务建议走云端模型。这样可以同时兼顾隐私和效果。7.4 日志与可观测性Agent 出问题的时候没有日志几乎无法排查。建议给编排器加上结构化日志记录每个子任务的开始时间、结束时间、调用模型、Token 消耗和执行结果。有条件的话把任务执行历史写入 SQLite方便后续复盘和性能分析。8. 总结与下一步学习方向本文从零开始搭建了一套 Codex Hermes Ollama 多智能体协作环境先讲清楚 Codex、Agent、Harness、Ollama 的角色边界再逐步完成 Ollama 部署、Codex 配置、云模型接入最后通过一个编排脚本把任务拆解、代码生成和代码评审串联起来。如果你跟着操作到这里至少已经能够跑通“本地模型拆解任务 → Codex 生成代码 → 本地模型评审代码”的最小闭环。下一步建议往两个方向深入一是研究 Codex 的沙箱机制和自定义工具调用让 Agent 具备操作 Docker、数据库等能力二是尝试引入任务队列和记忆机制让多智能体协作具备持久化和多轮迭代能力。实际项目中优先关注安全边界和上下文管理这两点决定了你的 Agent 系统能不能从演示走向生产。如果本文对你有帮助可以收藏备用也欢迎在实际配置中多试错、多对比不同模型的效果差异。