第一次本地搭建 Codex Harness：3 分钟跑通你的首个 Agent 任务

EveryLink

26人浏览 · 2026-08-25 18:27:06

EveryLink · 2026-08-25 18:27:06 发布

原文链接：第一次本地搭建 Codex Harness：3 分钟跑通你的首个 Agent 任务

本篇是《Codex Harness实战与原理》合集第 1 篇（共 25 篇）。

2026 年 8 月，OpenAI 把驱动 Codex 的底层执行框架完全开源了——可身边 90% 的工程师还在只聊模型。

这篇你能得到什么：三分钟内看 Codex 动起来；搞懂 Harness 到底是什么、为什么比模型更值得研究；拿到本专栏 25 篇六阶段地图。

先跑通：3 分钟看 Codex 动起来

好模型不等于能用的 Agent。想让一个 AI 真正帮你改代码，至少需要：看懂仓库、保持记忆、调工具、处理崩溃、在关键时刻停下来让你审批。包揽这些"脏活累活"的执行系统，就是 Harness。

Codex Harness 开源后，你不需要先读源码，我们从简单应用逐步深入到原理特性，先跑起来最直观：

# 1) 安装
npm i -g @openai/codex

# 2) 终端注入 DeepSeek 密钥
export DEEPSEEK_API_KEY="sk-你的密钥"

想用Codex使用DeepSeekV4模型的，可以像我一样，添加如下配置：

# ~/.codex/config.toml
model = "deepseek-v4-flash"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"

# 3) 确认版本（v0.149.0 起含完整 harness）
codex --version

# 4) 进入一个 git 仓库目录再执行（Codex 要求运行在 git 仓库内，
# 否则会报 "Not inside a trusted directory" 错误）
cd /path/to/your-git-repo

# 5) 用 read-only 沙箱让它"只看不改"
codex exec --sandbox read-only "总结这个仓库并列出 5 个风险点"

前几步把环境建好，最后一步最关键。它把当前目录当成工作区，让 Agent 在"只读"沙箱里分析代码。这一步能跑通，说明 Codex Harness 的心脏已经在你机器上跳动。

跑通只读版本后，不妨把同一个任务在两种沙箱下各跑一次。先说结论：对"总结仓库"这类纯分析任务，两种模式结果几乎一致——这是正常的，因为任务全程不写文件，沙箱权限无从表态。

只读任务：总结仓库并列出 5 个风险点	read-only	workspace-write
是否允许写文件	否	是（工作区内）
是否允许联网	否	默认否，可配置
弹窗次数	0	0
自主执行命令数	12	13
实测耗时	1分10秒	1分20秒

这张表的价值不在"差异"而在"一致"：两种权限下 Agent 的读分析行为完全趋同，说明沙箱只管"写边界"，不干扰"读智能"。

真正能看出沙箱意义的，是会写文件的任务。把命令换成：

codex exec --sandbox read-only "给这个仓库新建一个 README.md，写一段项目简介"

在 read-only 下，Agent 会明确卡在写边界（报错或声明无写权限）；切到 workspace-write 后，它才真正把 README.md 落盘。

写任务：新建 README.md	read-only	workspace-write
能否生成文件	否（卡在写边界）	是（已落盘）
弹窗次数	0	3
自主执行命令数	10	12
实测耗时	1分2秒	1分10秒

read-only的权限提示

workspace-write的完成提示

结论：沙箱权限是执行层里你给 Agent 划的"安全红线"——只读任务它隐形，写任务它立刻见效。这正是 Harness 把"可控性"交到你手里的地方。

Harness 是什么：Agent 的"外骨骼"

"Codex Harness"不是模型，也不是"模型 + Prompt"的包装。它是一套把模型变成生产力的执行框架。

官方博客《Codex as a platform》把它拆成六件事：上下文（Context）、执行（Execution）、策略（Policy）、状态（State）、可观测（Observability）、人工控制（Human control）。少任何一块，Agent 都上不了生产。

一张图就能看懂它的四层结构。

核心层 Core 是心脏。它只做一件事：组装 prompt、调模型、处理 function call、管理上下文窗口。

表面层 Surface 是接入方式。TUI、VS Code 插件、Web、桌面 App、MCP Server、SDK——它们共享同一颗心脏。

会话层 Session 管 Thread 的创建、恢复、fork 与配置加载。执行层 Execution 管沙箱隔离、shell、文件编辑、MCP tool 调度。核心层不知道自己在哪个表面层上跑，这正是它能被快速嵌入各种产品的原因。

开源了什么，没开源什么

Codex Harness 开源的内容比很多人以为的更值钱。它不只是"又一个聊天客户端"，而是一整套可复用的 Agent 运行时。

开源了什么	没开源什么
CLI（`codex exec` / `codex review`）	模型权重本身
App Server（JSON-RPC 协议，可接 IDE/Web）	OpenAI 云端算力
SDK（编程接口，可造自己的 Agent）	部分高级 endpoint（如 compaction）
codex-rs 核心源码（Apache-2.0）	—

这张表的含义很直接：你可以"基于 Codex 造 Agent"，而不必从零写一个 Agent Loop。模型负责思考，Harness 负责把思考落地。

同时它也意味着，如果你要接本地模型或内网部署，模型侧完全可以换成 Ollama、LM Studio 或私有 endpoint。Harness 的 model-provider 抽象层已经把这些差异包掉了。

一个反常识真相：执行层才是你能掌控的杠杆

过去一年，行业把太多注意力放在"哪个模型更强"。但当你真正在本地把 Codex 跑起来，会发现 Agent 好不好用，往往不取决于模型多聪明，而取决于执行层怎么调度它。

前面两张对比表就是证据。第一张：同一个"总结仓库"只读任务，两种沙箱下命令数、耗时几乎一致——沙箱权限对"读智能"毫无干扰。第二张：换成"新建 README"写任务，read-only 卡在写边界、workspace-write 真正落盘——沙箱权限一下成了分水岭。这正是执行层在起作用：它不是被动的运行环境，而是你直接掌控 Agent 安全性、可用性、成本的主动杠杆。

模型是引擎，Harness 是把引擎变成一辆车的底盘、悬挂、刹车和方向盘。没有底盘，引擎再强也开不到目的地。

维度	模型	Harness
做什么	推理、生成、规划	上下文管理、工具调用、沙箱、审批、恢复
改它能影响	智商上限	可用性、稳定性、安全性、成本
企业能否自研	通常不能	完全可以，因为它已开源

对企业来说，Harness 的可控性比模型权重更值钱。你可以改审批流、加 hook、换模型、私有化部署——这些动作都不需要重新训练模型。

本专栏地图：25 篇六阶段递进

25 篇不是随机堆知识点，而是按"由用到造、实操驾驭理论"递进。目标只有一个：让你从"会用 Codex"走到"能基于它造产品、能在企业内网落地"。

应用基础（01–03）：装好、跑通、搞懂审批 / 沙箱 / AGENTS.md 三件套。
核心特性精讲（04–09）：审批、配置、Hooks、Skills、Rollback、模型路由逐个实测拆解。
场景实战（10–12）：CI 自动 Review、MCP 接入、多 Agent 编排三条真实链路。
原理拆解（13–19）：Agent Loop、上下文压缩、安全架构、App Server 协议、Responses API、编译核心，最后提炼 10 大设计模式地图。
产品化（20–22）：用 SDK 造 Agent、可观测与成本治理、企业系统集成打通。
企业级进阶（23–25）：私有化离线部署、安全治理与评测、完整落地路线图。

难度单调递增，但每一篇都以"可复现实操"开场。理论只用来解释你亲手跑出的数据，不会先抛概念再找例子。