★ FEATURED ARTICLE 最近我把 Codex 从裸奔切换到了带 harness 的工作流跑了两周之后最大的感受就是标题这句话harness 总比模型快一步。这里的快不是模型生成 token 的速度变快而是同样的任务从开始到交付的完整路径短了一大截。我见过太多人拿到 Codex CLI 之后直接就在终端里聊让模型自己读代码、自己猜上下文、自己决定下一步干什么。不是不能用而是每次任务都在重复同样的摸索成本。这篇文章我想用我自己的实操经历把 harness 到底是什么、它凭什么快一步、怎么搭一套能用的 harness以及我踩过的那些坑插件加载失败、代理报错、模型名不支持、组织设置加载不出来完整梳理一遍。适合正在用或者准备用 Codex又觉得它不够聪明的开发者看。其实问题往往不在模型而在你根本没给模型铺路。1. 从一次对比实验说起同样一个任务裸 Codex 和 harness 封装的 Codex 差了多少先别急着聊概念。我直接用一次真实任务做对比你大概就明白 harness 在干什么了。1.1 我为什么要从裸奔切到 harness在我没上 harness 之前Codex 的用法非常简单装好 CLI登录然后给它一个自然语言任务。它确实能干活但用久了你会发现几个固定痛点。第一每次任务都在重新认识项目。Codex 的上下文是有限的每次会话它都要重新读目录、读文件、猜项目结构。哪怕你上个星期刚让它改过同一块代码这星期它又从零开始。第二它很容易跑偏。给它一个稍微复杂的任务它会顺着自己的思路一路改下去改到第五个文件的时候已经偏离你最开始的意图了。第三重复的约定它记不住。比如说你们团队的 commit message 规范、代码格式要求、测试必须先写这种规矩它每次都要你重新说一遍甚至说了它也未必执行。后来我接触到 harness 这个概念一开始以为就是提示词模板的另一种说法试过之后才发现完全不是一回事。简单说harness 是把模型外部的决策逻辑、工具调用、流程控制、上下文管理全部工程化模型只负责执行已经被约束好的路径。这才是它总比模型快一步的根本原因。1.2 对比实验任务、过程、结果为了验证这个判断我做了一个尽量公平的对比。同一个仓库同一个任务两次都在干净的会话里执行。任务内容是这样一段话给这个 Go 项目新增一个 HTTP 健康检查端点/healthz返回 200 和ok文本补齐对应的单元测试更新 README 的 API 列表。不要动其他无关文件。裸 Codex 的过程我记录得很详细。它先执行了目录列表然后开始逐个文件地读。读cmd/main.go、读internal/router/router.go、读internal/handler/下的文件中间还读了好几个我以为跟这个任务完全无关的配置文件。定位到路由注册处之后直接开始写代码写完没有立刻跑测试而是先去改 README改完 README 跑go test才发现缺一个 mock 依赖又停下来安装依赖。装完依赖测试通过了但 lint 报了一个未使用的 import 警告又折回去改了一遍。最后提交的时候它自己没法生成 commit message还得我来处理。整个流程走完37 分钟。带 harness 的那次过程是完全不同的节奏。我预先在 harness 里挂了一个叫go-service-change的 skill里面规定死了这个类型的任务必须按四步走先读路由注册文件确认接入方式再写测试用例接着实现功能最后更新 README。skill 里还写了一条硬约束只允许修改 cmd/main.go、internal/router/router.go、internal/handler/healthz.go、README.md 四个文件。这次 Codex 没有乱逛第一轮就精准锁定了路由注册的位置先写了测试再补实现跑测试的时候失败了一次因为我给的健康检查 handler 没有写 Content-Type它看到失败信息自己按 skill 里的规范修正最后 markdownlint 插件自动检查了 README 格式git commit 插件顺手帮我生成了一份符合团队规范的提交信息草稿。全程 11 分钟而且测试覆盖和 README 完成度都比裸奔那次好。1.3 快一步到底快在哪路径变短而不是模型变强这个实验最有说服力的部分不是时间差而是行为差异。裸 Codex 的行为模式是广度探索——读大量文件、尝试多种方案、中途不断修正带 harness 的 Codex 行为模式是深度执行——路径已经被预定义好它只需要在每一个节点上做好局部决策。我之前写过一篇笔记把这件事总结成一句话模型是决策器harness 是决策省略器。模型每次生成 token 之前都要做一次概率选择这个选择本身的成本不高但如果选择错了后面的所有成本都是翻倍的。harness 做的事情就是把这些高频的、可预期的选择提前固定下来让模型把算力花在真正需要判断的地方。用一个生活化的类比裸 Codex 像一个没有导航、没有车道线的新手司机到了每个路口都要停下来琢磨往哪走harness 则像是 GPS 导航加车道线加一套交规。你还是那个司机技术没有瞬间提升但你不必在每个路口做决定了只要顺着导航走到转弯的地方打个方向盘就行。这就是快一步的全部秘密——不是补全模型的能力而是压缩模型的决策空间。维度裸 CodexHarness 封装后的 Codex项目认知每次从零读文件注入项目结构摘要和历史决策任务路径模型自行探索预定义阶段和验收标准修改边界容易失控硬约束锁定文件范围质量检查靠模型自觉插件强制跑测试和 lint下次复现无法复现同一条路径可重复执行这里我要特别说明一下harness 不是银弹。后面第 5 章我会专门讲什么场景不该上 harness。但如果你手头有大量流程固定但内容多变的开发任务那么这个投资是稳赚的。2. harness 的本质不是提示词模板而是一层工程约束很多第一次看到 harness 这个词的人第一反应是这不就是写一堆 prompts 吗。我一开始也这么想直到自己搭了一套才意识到提示词模板只是 harness 里最基础的一层真正的 harness 是一整套工程约束。2.1 先说清楚 harness 和 agent 的区别最近搜索热词里经常能看到harness 和 agent 区别这种问题我试着用最直白的方式讲清楚。Agent 是模型自主循环的那套机制模型感知环境读文件、读终端输出→ 做出决策 → 通过工具行动 → 再感知。你给 Agent 一个目标它自己规划自己执行。这个自主性是 Agent 的核心价值但也是最大的风险源——它可能自主过头跑到你根本不想让它去的地方。Harness 是套在 Agent 外面的一层工程骨架。它不替代 Agent 的决策能力而是把 Agent 的决策范围圈起来哪些工具能用、哪些文件能碰、任务必须经过哪几个阶段、每个阶段结束的验收标准是什么。你可以把 Agent 看成 CPUharness 则是主板——CPU 负责运算但指令集、总线、电源规范都是主板定的。我总结过一个对比表直接贴出来对比项裸 AgentHarness 封装决策权归属模型自己决定每一步工程侧预定义大部分步骤上下文管理依赖模型的 attention主动压缩、筛选、注入工具使用模型自己发现工具预设工具集 权限边界可审计性低过程黑盒高分段日志可回放失败恢复模型自行尝试绕路预设回退策略适用场景探索、原型、未知问题生产、重复、高约束任务理解这层区别之后你就明白为什么harness 总比模型快一步了。Agent 是模型自己在跑harness 是让模型在轨道上跑。轨道本身不能代替发动机但它决定了这趟车的路径、速度和到站顺序。2.2 harness 的核心模块指令模板、插件、模型路由、上下文缓存、工作流编排我自己的 harness 里面按功能可以拆成五个模块。这五个模块覆盖了我能想到的绝大多数工程化需求。指令模板Prompt Templates。这是最基础的一层把团队的编码规范、commit 规范、目录约定、禁止事项固化成固定指令。比如我的模板里固定写了一条修改任何文件前先调用git status确认当前分支不要修改不属于任务范围的文件。指令模板的价值不在于写得多华丽而在于稳定——每次任务都给一模一样的规则模型才能形成稳定的行为习惯。插件系统Hooks / Plugins。这是 harness 真正工程化的地方。插件在关键节点插入脚本执行编辑文件之后自动跑gofmt提交之前自动跑全量测试生成文档后自动做格式检查。插件机制的核心是 hook 点——你的 harness 支持在哪些时机执行外部脚本。最常见的 hook 点有任务开始前pre-task、每次编辑后post-edit、测试执行后post-test、任务结束前pre-commit。我用的插件数量不多但每一个都解决一个明确痛点这一点第 3 章会展开说。模型路由Model Router。不同任务应该用不同模型这个思路在裸 Codex 里也能做但很麻烦。我在 harness 层做了一层简单的路由规则任务描述里包含修 bug改文案这类关键词的走便宜快速的模型包含重构设计架构这类高强度推理的走更强的模型。实测下来这个模块帮我省了大概三成 API 费用而且质量没有明显下降。上下文缓存Context Management。模型的上下文窗口再大也是有限的而且塞太多无关内容会稀释注意力。harness 会主动做上下文优化提前把项目目录树、关键文件摘要、历史决策记录注入上下文在任务执行过程中定期压缩过期对话。这层做得好不好直接决定模型是越聊越清醒还是越聊越糊涂。工作流编排Workflow Orchestration。把任务拆成阶段每个阶段有独立的验收标准。我常用的流程是plan → implement → test → review每个阶段结束都必须满足该阶段的验收条件才能推进。比如 test 阶段如果测试失败harness 会把失败信息回填给模型让它继续修而不是让它跳过测试直接进入 review。2.3 为什么harness 总比模型快一步这句话成立这句话成立的原因可以归结为三点。第一决策成本被提前支付。模型每一步的决策都是有代价的包括 token 消耗、时间消耗、出错概率。harness 通过预设路径把大量低价值的决策直接取消了。第二搜索空间被强制收敛。裸 Codex 面对一个任务时潜在的修改方案可能是几十种harness 通过约束文件范围、限定工具集把搜索空间压到两三种。搜索空间小了模型的出错率自然就低。第三行为可复现。裸 Codex 跑同一个任务两次得到的结果可能完全不一样harness 的路径是固定的结果差异会小很多。对生产环境来说可复现比新奇重要得多。这三点力量叠加就形成了快一步的体验。不是模型变聪明了而是它每一步走的都是确定性最高的路。3. 动手搭一套自己的 harness从 Codex CLI 到 DeepSeek 接入理论讲完接下来是实操。我以自己的环境为例从安装 Codex CLI 开始到接上 DeepSeek再到插件的选择和配置一步步走一遍。这套配置我现在还在用可以直接抄作业但也要提醒一句不同版本的 Codex 配置字段会有变化安装前最好看一眼对应版本的文档。3.1 Codex CLI 的安装和基础配置Codex CLI 目前的安装方式主要是两种。如果你装了 Node.js直接用 npm 装就行npm install -g openai/codex codex --version如果你用的是 macOS 且装了 Homebrew也可以走 brew 的方式brew install codex安装完之后第一次运行需要登录执行codex login按提示完成授权。登录成功后会生成~/.codex/auth.json这个文件保存着你的登录态后面第 4 章我要讲的无法加载组织设置就跟它有关。基础的模型配置在~/.codex/config.toml里。如果你只用官方模型配置非常简单model gpt-5 model_reasoning_effort high但如果你想像我一样接 DeepSeek就得走 custom provider 的方式这就稍微绕一点了。3.2 把 DeepSeek 接进 Codex模型供应商配置这阵子codex 接入 deepseek的热度很高我自己也试了一圈最终跑通的配置是这样的。在~/.codex/config.toml里加一段model deepseek/deepseek-chat model_providers [ { name deepseek, base_url https://api.deepseek.com/v1, env_key DEEPSEEK_API_KEY, wire_api responses } ]然后在你的 shell 环境里设置好密钥export DEEPSEEK_API_KEY你的密钥有几个细节我得单独拎出来说都是坑。第一base_url 要写对。DeepSeek 的接口地址是https://api.deepseek.com/v1注意有的版本写法可能需要去掉/v1取决于 Codex 版本对 base_url 的拼接逻辑。我自己在 0.1.4 版本上带/v1是能跑的。第二wire_api 很关键。早期版本的 Codex 对自定义 provider 的wire_api字段支持的是chat新版更推荐responses。如果你的 Codex 版本比较旧responses可能会报协议不兼容改成chat试试。第三模型名要跟 DeepSeek 官方名完全一致。deepseek-chat是对话模型的官方名deepseek-reasoner是推理模型的官方名别自己发明deepseek-coder-v3这种不存在的名字否则你会碰到第 4 章里的 model not supported 报错。接完之后跑一句最基础的测试codex ping如果能正常返回说明管线已经通了。我用这个组合实测下来的感受是日常的代码解释、单元测试编写、重构这类任务DeepSeek 的deepseek-chat完全能扛而且成本比直接用官方模型低不少。但非常复杂的架构设计类任务它的表现还是跟强推理模型有差距——所以我才在第 2 章说模型路由很重要简单任务别浪费强模型的额度。3.3 插件安装与提示词优化我的选择热词里频繁出现 deepseek harness 插件推荐提示词优化插件我猜很多人是冲着让模型更听话去的。我自己的插件策略是宁缺毋滥装太多插件会让 harness 变得臃肿反而拖慢速度。我的插件目录在~/.codex/plugins/每个插件一个子目录。目前保留的是这三个repo-lint在post-edit阶段自动跑代码格式化和 lint。它的作用不是修所有问题而是把模型漏掉的那些格式问题拦下来。我见过太多次模型写完代码逻辑没问题但gofmt一片红的场景这个插件就是为了干掉这类低级错误。commit-helper在任务结束前根据git diff自动生成符合团队规范的 commit message 草稿。这个插件本质上是一个 prompt 注入但它封装得比我手动复制 diff 再让模型写要顺手得多。markdown-check专门检查文档类输出。README、API 文档的格式问题比如标题层级、代码块标注都由它兜底。插件运行依赖 manifest 文件以repo-lint为例它的 manifest 长这样{ name: repo-lint, version: 0.1.0, hooks: { post-edit: [hooks/post-edit.sh] } }对应的 hook 脚本hooks/post-edit.sh就是一个普通 shell 脚本做好chmod x授权就行。除了插件的 hook 机制我会把一些固定的项目知识直接写成提示词文件放在~/.codex/skills/目录下。它的作用和插件不同——插件在事件触发时执行脚本skill 是在任务开始时注入指令。比如我的go-service-changeskill内容就是一段固定指令规定这类任务的流程和文件约束。这种方式比每次手动打一段规则稳定太多而且团队共享也方便把文件丢到 git 仓库里大家同步就行。3.4 一个可参考的 harness 目录结构和关键配置给你看我现在的完整目录结构可以直接参考~/.codex/ ├── config.toml ├── auth.json ├── plugins/ │ ├── repo-lint/ │ │ ├── manifest.json │ │ └── hooks/ │ │ └── post-edit.sh │ ├── commit-helper/ │ │ ├── manifest.json │ │ └── prompts/ │ │ └── commit.md │ └── markdown-check/ │ ├── manifest.json │ └── hooks/ │ └── post-edit.sh └── skills/ ├── go-service-change/ │ └── SKILL.md └── bug-fix-before-refactor/ └── SKILL.mdconfig.toml里除了模型配置我还会开这两个开关[hooks] [hooks.post_edit] command git diff --stat /tmp/codex_last_change.txt这段 hook 的作用是把每次编辑涉及的文件列表记录到一个临时文件后面 skill 指令里会引用这个记录提醒模型你刚才改了哪些文件。算是一种轻量的文件变更追踪。如果你要部署到内网服务器注意一点内网环境通常没有外网 API 权限我的做法是在能访问外网的机器上把依赖装好再同步整个~/.codex目录到内网服务器并把base_url换成内网网关对应的代理地址。skill 和插件都是纯文本脚本同步过去不需要重新安装这一点比其他工具方便很多。4. 实测中的坑与排查链路从插件加载失败到代理报错想用 harness 的人大概率会碰到一堆报错。我把自己真实遇到的四个问题按完整排查链路写出来。这些问题你在搜索热词里都能看到对应的影子说明不是我一个人踩。4.1 harness failed to load plugins不是插件问题是 manifest 问题报错信息长这样harness failed to load plugins。我第一次看到的时候以为插件目录坏了重装了好几次都不行后来才意识到问题根本不在插件代码而在 manifest 格式。排查链路是这样的带调试日志复现一次。大部分版本支持CODEX_DEBUG1或者RUST_LOGdebug环境变量启动后会打印插件加载的详细日志。从日志里找到具体是哪个插件加载失败然后开始逐个精简。最快的定位方式是把插件目录退到只剩一个插件能加载就说明这个插件没问题再逐步加回来。检查 manifest 的三项name不能为空且不能重名version必须符合 semver 规范比如0.1.0不能是0.1hooks里的脚本路径是相对 manifest 所在目录的别写绝对路径。检查 hook 脚本的可执行权限。chmod x这一步特别容易被忽略——很多用户从 Windows 同步文件过来权限位全丢了。手动执行一次 hook 脚本看退出码是不是 0。脚本本身如果报错Codex 会认为插件加载失败。我最后定位到的原因就是 manifest 里version写成了0.1不符合 semver 规范Codex 直接整个插件目录忽略掉了。改回0.1.0之后立刻恢复。4.2 cc switch local proxy failed while handling codex endpoint /responses代理切换的坑这条报错特别有代表性cc switch local proxy failed while handling codex endpoint /responses。cc是我对一个上下文切换 wrapper 的别名脚本的作用是切换工作目录和对应的环境变量。某次我在两个项目之间切换之后所有请求都开始报这个错。排查链路先排除 Codex 自身问题。直接跑codex ping发现是正常的说明问题出在切换上下文的动作上。检查环境变量。发现cc脚本在切换项目时会重写HTTP_PROXY和HTTPS_PROXY两个变量指向本地一个调试代理的端口。确认代理进程状态。我发现那个代理进程在前一次测试结束后被我手动关闭了但环境变量还指过去请求自然全部失败。对比正常状态和异常状态的环境变量差异把代理配置改成不随项目切换的模式然后再执行cc switch验证请求恢复。如果你的报错尾部还带着provi片段provider 相关多半是同一个场景的另一种表现——切换上下文时 provider 配置也被覆盖了。检查~/.codex/config.toml里的model_providers是否被 wrapper 脚本改动过。我的解决思路很简单环境变量只做一次初始化不要在每个项目的 wrapper 里重复定义。提示代理类配置建议集中管理而不是分散到各个 wrapper 脚本里。分散配置的后果就是这种切一次坏一次的诡异问题。4.3 gpt-5.6-sol model is not supported模型名映射错误我在尝试某个第三方配置时碰到过这么一条报错请求体里返回一段 JSON{detail:the gpt-5.6-sol model is not supported when using codex with a ...}。这个报错的本质是模型名没有通过 Codex 的校验。排查链路先看请求体里实际传给服务端的 model 名是什么。上面那个gpt-5.6-sol一看就是个不存在的模型名很可能是某份配置文件里的笔误或者是从某个模型的别名表里抄来的版本号。检查config.toml里model_providers和model字段。Custom provider 的模型名必须满足provider名/模型名的格式比如deepseek/deepseek-chat。确认这个模型在对应的 API 服务商那里真实存在。DeepSeek 只有deepseek-chat和deepseek-reasonerOpenAI 的模型名以官方文档为准。确认环境变量env_key对应的值已经正确设置。有时候报错看起来像模型名问题其实是鉴权失败后服务端返回的误导性信息。最后一个容易被忽略的点Codex 版本太旧时对某些模型的校验逻辑写得很死。升级到最新版再试。这类问题的共性是你抄了一份别人写的配置但配置里的模型名和版本号对不上你的实际环境。我处理这类问题的原则就一条一切以官方文档的模型列表为准不要相信任何配置教程里写死的模型名。4.4 codex 无法加载组织设置登录态和缓存热词里也有codex 无法加载组织设置这个问题的表现是启动后一直转圈然后提示无法加载 organization settings甚至直接报超时。我遇到过一次排查过程不算复杂。排查链路先确认网络本身没问题。如果 Codex 能正常调用模型 API但加载组织设置失败说明问题不在连通性。检查登录态。~/.codex/auth.json里保存的 token 如果过期或者被手动改过Codex 可能能通过基础鉴权但拉取组织信息时失败。删除缓存。Codex 会把组织信息缓存在本地通常在~/.codex/cache或类似目录下缓存文件如果损坏或者被残留的旧版本数据污染也会出现这种转圈现象。重新登录。执行codex logout再codex login重新生成登录态。如果还不行检查auth.json的文件权限。某些情况下权限过严0400会导致进程读取失败建议保持0600即可。这个问题的核心是登录态和本地缓存的一致性。Codex 官方文档不会把这类细节写得很清楚但实际用起来你只要记住先清缓存、再重登这个顺序基本能解决九成问题。5. harness 的边界与下一步什么场景不该上 harness写了这么多 harness 的好处我必须得补上边界。harness 不是越厚越好过度封装反而会拖累你。5.1 什么时候 harness 反而是负担我自己的判断标准很简单如果同一个任务你在当前仓库里要做三次以上才值得上 harness。一次性任务强行套 harness只会增添摩擦。典型的反面场景有这么几类。探索型任务。比如你想搞清楚某个陌生代码库的调用链或者验证一个想法可不可行这时候最需要的模型的自由探索能力而不是预设路径。我给这种任务准备的是一条特殊 skill内容只有一句话自由探索不要提交任何改动。这是我唯一一个不加约束的 skill。纯文本生成类任务。写 release notes、翻译文档、总结会议纪要这种任务不需要访问文件系统也不需要跑命令提示词模板加成有限反而因为加载了一堆插件导致启动变慢。我现在会把这类任务单独走一条轻量通道不经过完整 harness。团队规范还在剧烈变动的项目。如果你们的代码规范、目录结构、提交规范这个月改了三次那你花在维护 harness 上的时间会超过它省下来的时间。harness 的价值前提是流程稳定流程不稳定的时候先别急着上。5.2 从 harness 到 RPA 落地的一步联想搜索热词里有个组合很有意思harness rpa 落地实现。我在实践里发现harness 的思路和 RPA机器人流程自动化其实高度同构——都是把流程节点固化、把异常处理变成显式分支、把重复决策抽离出来。区别在于 RPA 的节点通常是一段固定脚本而 harness 的节点允许模型做局部决策。如果你所在团队的 SOP标准作业手册已经比较完善那么上 harness 会非常顺——因为你要做的事情其实就是把 SOP 翻译成 skill 指令和插件 hook。反过来如果连 SOP 都没有那我建议先不要急着上 harness你缺的不是工具而是流程梳理。用一套技术方案去解决管理问题结果只会让混乱变得更隐蔽。5.3 我接下来会怎么调我的 harness跑了这段时间之后我对自己的 harness 配置做了几个调整也算给打算入坑的朋友一个参考。第一插件数量控死在五个以内。每新增一个插件都要先回答一个问题这个插件解决的痛点在最近一周出现过几次少于三次就不装。第二把散装提示词沉淀成 skill。以前我习惯在任务描述里写一大段规则现在统一改成维护~/.codex/skills/目录按任务类型分文件执行时自动引用。第三按任务类型做模型路由。简单修 bug 用便宜模型架构重构用强推理模型这个我在第 2 章讲过是性价比提升最明显的一步。第四给所有 hook 脚本加审计日志。输出到统一目录之后任何一次异常都能回放排查时间至少缩短一半。我个人实操中体会最深的一件事是harness 永远不会替你思考但它能确保你思考完之后模型不会在同一个地方绕第三个弯。你花一晚上把约束铺好换来的是之后每一次任务都走在最短路径上——这套东西配得上总比模型快一步这句话。
阅读完成 · 觉得有帮助？
