Codex Harness是什么？开源Agent框架完整解析
解析OpenAI Codex Harness开源框架，介绍Agent运行时、SDK、app-server接口、自定义模型接入与自动化开发。
摘要
2026年8月19日，OpenAI正式对外开源Codex Agent Harness，该框架是支撑Codex桌面端、CLI工具、VS Code插件的底层运行时，基于Apache‑2.0开源协议发布。截止2026‑08‑21，GitHub仓库收获107443颗Star，16354次Fork，稳定版本v0.149.0于8月20日同步上线。本次开源的核心价值是放出三层集成接口：轻量非交互codex exec、程序化Codex SDK、长会话codex app‑server，覆盖从CI脚本到独立Agent产品的全链路开发场景。Harness负责会话状态管理、工具调度、沙箱隔离、输出流式处理与人工作业审批，开发者可以在此之上构建自有业务逻辑，也可以对接第三方模型端点。在多模型接入场景，koalaapi作为API网关可以简化不同大模型服务的统一接入工作。本文拆解Rust底层模块、三层接口用法、版本更新要点、自定义模型接入方案与常见问题。
一、Codex Harness核心定位与设计理念
Codex Harness属于Agent执行运行时，不直接面向终端用户，而是作为底层基础设施，把模型能力封装成可控、可审批、可持久化调用的服务。应用层产品掌握业务上下文与业务规则，Harness只负责Agent循环执行链路。
该设计思路和DeepSeek Harness有很强的相似性，二者都采用插件扩展架构。差异在于Codex Harness底层采用Rust实现codex‑rs核心，搭配TypeScript SDK，更偏向生产环境高性能部署；DeepSeek Harness主要基于TypeScript构建，迭代速度更快，更适合原型快速验证。
本次开源之前，OpenAI仅开放Codex CLI前端代码，codex‑rs底层、app‑server服务均为内部闭源实现。v0.149.0版本完整开放app‑server协议与SDK接口，带来三项关键能力：
- 将Codex Agent能力嵌入自有业务系统，不再局限于调用独立CLI程序；
- 替换底层模型提供方，兼容任意OpenAI协议的模型端点；
- 在CI/CD流水线实现无人值守自动化Agent任务，无需人工介入。
官方给出ARC‑AGI‑3测试数据可以直观体现Harness层优化带来的收益：借助retained reasoning与上下文压缩优化，GPT‑5.6 Sol在ARC‑AGI‑3评测得分由13.3%提升至38.3%，同时输出侧Token消耗降低六倍；相同模型下，不同Harness实现可以带来最高3倍效果差距。这也说明Agent系统的最终表现，不只是取决于大模型本身，运行时框架的调度策略同样起到决定性作用。
二、codex‑rs Rust底层模块总览
codex‑rs是整套Harness的高性能底层，全部由Rust编写，承担性能敏感任务，包含一系列功能子模块。
| 子模块 | 功能说明 |
|---|---|
| app‑server | 为VS Code插件、桌面应用提供JSON‑RPC服务 |
| exec‑server | 支撑非交互任务执行服务 |
| sandboxing / linux‑sandbox / windows‑sandbox‑rs | 跨平台沙箱隔离，管控文件与命令权限 |
| exec / execpolicy | 执行策略、权限校验逻辑 |
| skills | 可复用Skill能力框架 |
| hooks | 生命周期钩子回调 |
| tools | 工具调用运行时 |
| tui | 终端交互UI组件 |
| mcp‑server | MCP协议服务端实现 |
| thread‑store / history | 会话持久化存储，管理对话历史 |
| responses‑api‑proxy | Responses API代理转发层 |
| model‑provider | 模型提供方抽象层，用来对接各类兼容端点 |
部分组件并未开源：IDE扩展内部实现、Codex Cloud托管服务不在本次开源清单内。
三、三层集成接口完整解析
OpenAI设计三层接口，分别适配一次性脚本、代码开发编排、产品级长会话三类场景，开发者按需选择接入方式。
第一层：codex exec — CLI脚本、非交互批量任务
codex exec属于最轻量接入方案，适合CI流水线、批量脚本、一次性任务。后台启动exec‑server，任务执行完成自动退出，不维持持久会话。
基础示例：
# 安装
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# 执行非交互任务
codex exec "重构 src/utils.ts 中的 fetchData 函数，增加错误捕获逻辑"
# 指定项目工作目录运行
codex exec --cwd /path/to/project "运行测试并修复失败的测试用例"
该模式没有会话记忆，每次调用独立运行，适合自动化流水线场景。
第二层：Codex SDK — 程序化Agent编排
SDK包路径为@openai/codex‑sdk，封装app‑server通信协议，允许在TypeScript代码内创建、恢复、分支Agent会话。支持thread/fork分支会话、thread/resume恢复历史会话、turn/interrupt中断当前轮次，可以快速搭建多轮交互Agent应用。
import { CodexAgent } from '@openai/codex‑sdk'
const agent = new CodexAgent({
model: "gpt‑5.6",
cwd: "/path/to/project",
approvalPolicy: "auto"
})
// 开启全新会话
const thread = await agent.thread.start()
借助SDK，开发者可以把Agent逻辑完整嵌入后端服务，不用调用外部二进制命令行。
第三层：codex app‑server — 持久会话、流式事件、审批流程
app‑server面向正式产品，作为独立进程对外提供JSON‑RPC 2.0协议服务，VS Code插件、Codex桌面客户端都依赖该服务。支持三种通信传输方式：stdio标准输入输出、Unix socket、WebSocket。
| 传输方式 | 命令示例 | 适用场景 |
|---|---|---|
| stdio（默认） | codex app‑server --stdio | 嵌入子进程，标准流收发JSON消息 |
| Unix socket | codex app‑server --listen unix://xxx | 本地多进程协同，控制面板 |
| WebSocket | codex app‑server --listen ws://127.0.0.1:PORT | 跨进程流式传输（实验特性） |
WebSocket接口标记为实验性质，官方不建议直接用于生产环境，生产优先选用stdio或者Unix socket。
核心概念定义：
- Thread：完整会话对象，包含多轮交互Turn，支持暂停、恢复；
- Turn：一轮交互单元，用户输入到Agent完成输出；
- Item：会话内消息条目，可以是提示、Shell命令、文件修改、工具调用结果。
框架内置命令可以生成TypeScript、JSON Schema类型定义，方便前后端开发：
codex app‑server generate‑ts --out ./schema
codex app‑server generate‑json‑schema --out ./schema
四、v0.149.0版本主要更新（2026‑08‑20）
伴随开源同步发布的稳定版本，新增多项面向工程落地的能力：
- codex‑agents仪表盘：交互式Agent管理界面，支持搜索、启动、暂停、重命名、终止任务，支持快捷键自定义，直观管控Agent生命周期。
- codex‑queue消息队列：向正在运行的会话追加消息，不需要等待当前轮任务结束。典型场景：Agent正在执行测试，外部追加新需求。
codex queue --thread‑id <thread‑id> "同时帮我更新 CHANGELOG.md"
- 工作目录切换：TUI终端内置
cd、pwd指令，不用重启会话切换工作目录。 - SDK推理强度控制：代码内可设置
reasoningEffort，支持max、ultra档位。
agent.config({ reasoningEffort: "ultra" })
- codex‑doctor诊断工具：一键检查端点连通性、网络代理、桌面服务运行状态，快速定位连接故障。
同时修复一批关键缺陷：会话唤醒恢复、分支会话权限还原、子代理任务稳定性、WebRTC重连逻辑等问题。
五、接入自定义模型提供方
Harness内部model‑provider模块做了抽象层，兼容全部OpenAI协议的模型端点。多模型统一接入平台如koalaapi，可以统一管理DeepSeek、Kimi、GLM等模型服务，只需要修改base‑url即可完成切换。
两种配置方式：环境变量注入，或者修改本地~/.codex/config.toml配置文件。
环境变量方式示例：
export OPENAI_API_KEY="你的APIKEY"
export OPENAI_BASE_URL="https://xxx/v1"
codex exec --model deepseek‑v4‑flash "帮我优化这段代码"
toml配置文件示例：
[provider]
type = "openai"
model = "deepseek‑v4‑flash"
base‑url = "https://xxx/v1"
[auth]
api‑key‑env = "YOUR_API_KEY_ENV"
密钥建议使用环境变量引用，禁止明文写死在配置文件提交代码仓库。
六、开源组件总览与常见FAQ
开源组件清单
| 组件 | 仓库地址 | 协议 |
|---|---|---|
| codex‑rs Harness核心 | openai/codex | Apache‑2.0 |
| Codex SDK | openai/codex‑sdk | Apache‑2.0 |
| codex app‑server | openai/codex‑app‑server | Apache‑2.0 |
高频问题整理
Q：Codex Harness 和 DeepSeek Harness是同一套框架吗？ 不是。两套独立开发，设计思想趋同。Codex Harness由OpenAI基于Rust开发，面向生产级Agent产品；DeepSeek Harness由DeepSeek AI开发，TypeScript实现，原型迭代快。有趣的是Codex子代理Bundle还可以安装到DeepSeek Harness中，实现两套框架联动。
Q：Rust重写版本对比旧Node.js版本有什么提升？ codex‑rs接管全部性能敏感路径，调度、沙箱、IO全部下沉Rust；SDK层保留TypeScript。整体响应速度、内存占用、稳定性相比旧版得到明显优化。
Q：WebSocket传输能不能上生产？ 属于实验接口，官方不推荐生产负载，生产环境优先 stdio / unix socket。
Q：CI流水线如何实现无人工审批？
调用codex exec时设置--approval‑policy suggest，配置文件同步修改policy，关闭交互弹窗，适配自动化流水线。
Q：OSS计划是什么？ OpenAI面向开源项目提供Codex OSS申请通道，审核通过项目可以拿到API额度，用于开源项目开发。
七、总结
Codex Harness开源最重要的意义，是OpenAI把自身商业化产品内部的Agent运行时完整对外交付。三层接口覆盖从简单脚本到完整Agent产品，开发者不用从零搭建工具调度、沙箱、会话管理整套基础设施。v0.149.0配套的仪表盘、消息队列、诊断工具，补齐了Agent生命周期运维能力。
同时评测数据证明，Agent系统效果不只取决于基座大模型，Harness运行时的调度、上下文压缩、推理留存策略会显著改变最终输出质量。开发者既可以直接使用OpenAI模型，也可以通过model‑provider抽象层对接各类第三方模型服务，灵活构建混合模型架构。
了解更多：https://koalaapi.com
