企业官网建设流程全解析

最近我把 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 导航加车道线加一套交规。你还是那个司机，技术没有瞬间提升，但你不必在每个路口做决定了，只要顺着导航走，到转弯的地方打个方向盘就行。这就是"快一步"的全部秘密——不是补全模型的能力，而是压缩模型的决策空间。

这里我要特别说明一下，harness 不是银弹。后面第 5 章我会专门讲什么场景不该上 harness。但如果你手头有大量"流程固定但内容多变"的开发任务，那么这个投资是稳赚的。

2. harness 的本质：不是提示词模板，而是一层工程约束

很多第一次看到 harness 这个词的人，第一反应是"这不就是写一堆 prompts 吗"。我一开始也这么想，直到自己搭了一套才意识到，提示词模板只是 harness 里最基础的一层，真正的 harness 是一整套工程约束。

2.1 先说清楚 harness 和 agent 的区别

最近搜索热词里经常能看到"harness 和 agent 区别"这种问题，我试着用最直白的方式讲清楚。

Agent 是模型自主循环的那套机制：模型感知环境（读文件、读终端输出）→ 做出决策 → 通过工具行动 → 再感知。你给 Agent 一个目标，它自己规划自己执行。这个"自主性"是 Agent 的核心价值，但也是最大的风险源——它可能自主过头，跑到你根本不想让它去的地方。

Harness 是套在 Agent 外面的一层工程骨架。它不替代 Agent 的决策能力，而是把 Agent 的决策范围圈起来：哪些工具能用、哪些文件能碰、任务必须经过哪几个阶段、每个阶段结束的验收标准是什么。你可以把 Agent 看成 CPU，harness 则是主板——CPU 负责运算，但指令集、总线、电源规范都是主板定的。

我总结过一个对比表，直接贴出来：

理解这层区别之后，你就明白为什么"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.md

config.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 格式。

排查链路是这样的：

1. 带调试日志复现一次。大部分版本支持CODEX_DEBUG=1或者RUST_LOG=debug环境变量，启动后会打印插件加载的详细日志。
2. 从日志里找到具体是哪个插件加载失败，然后开始逐个精简。最快的定位方式是把插件目录退到只剩一个插件，能加载就说明这个插件没问题，再逐步加回来。
3. 检查 manifest 的三项：name不能为空且不能重名；version必须符合 semver 规范（比如0.1.0，不能是0.1）；hooks里的脚本路径是相对 manifest 所在目录的，别写绝对路径。
4. 检查 hook 脚本的可执行权限。chmod +x这一步特别容易被忽略——很多用户从 Windows 同步文件过来，权限位全丢了。
5. 手动执行一次 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 的别名，脚本的作用是切换工作目录和对应的环境变量。某次我在两个项目之间切换之后，所有请求都开始报这个错。

排查链路：

1. 先排除 Codex 自身问题。直接跑codex "ping"，发现是正常的，说明问题出在切换上下文的动作上。
2. 检查环境变量。发现cc脚本在切换项目时会重写HTTP_PROXY和HTTPS_PROXY两个变量，指向本地一个调试代理的端口。
3. 确认代理进程状态。我发现那个代理进程在前一次测试结束后被我手动关闭了，但环境变量还指过去，请求自然全部失败。
4. 对比正常状态和异常状态的环境变量差异，把代理配置改成不随项目切换的模式，然后再执行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 的校验。

排查链路：

1. 先看请求体里实际传给服务端的 model 名是什么。上面那个gpt-5.6-sol一看就是个不存在的模型名，很可能是某份配置文件里的笔误，或者是从某个模型的别名表里抄来的版本号。
2. 检查config.toml里model_providers和model字段。Custom provider 的模型名必须满足provider名/模型名的格式，比如deepseek/deepseek-chat。
3. 确认这个模型在对应的 API 服务商那里真实存在。DeepSeek 只有deepseek-chat和deepseek-reasoner，OpenAI 的模型名以官方文档为准。
4. 确认环境变量env_key对应的值已经正确设置。有时候报错看起来像模型名问题，其实是鉴权失败后服务端返回的误导性信息。
5. 最后一个容易被忽略的点：Codex 版本太旧时，对某些模型的校验逻辑写得很死。升级到最新版再试。

这类问题的共性是你抄了一份别人写的配置，但配置里的模型名和版本号对不上你的实际环境。我处理这类问题的原则就一条：一切以官方文档的模型列表为准，不要相信任何配置教程里写死的模型名。

4.4 codex 无法加载组织设置：登录态和缓存

热词里也有"codex 无法加载组织设置"，这个问题的表现是启动后一直转圈，然后提示无法加载 organization settings，甚至直接报超时。我遇到过一次，排查过程不算复杂。

排查链路：

1. 先确认网络本身没问题。如果 Codex 能正常调用模型 API，但加载组织设置失败，说明问题不在连通性。
2. 检查登录态。~/.codex/auth.json里保存的 token 如果过期或者被手动改过，Codex 可能能通过基础鉴权，但拉取组织信息时失败。
3. 删除缓存。Codex 会把组织信息缓存在本地（通常在~/.codex/cache或类似目录下），缓存文件如果损坏或者被残留的旧版本数据污染，也会出现这种转圈现象。
4. 重新登录。执行codex logout再codex login，重新生成登录态。
5. 如果还不行，检查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 永远不会替你思考，但它能确保你思考完之后，模型不会在同一个地方绕第三个弯。你花一晚上把约束铺好，换来的是之后每一次任务都走在最短路径上——这套东西，配得上"总比模型快一步"这句话。