# Codex Harness 全面开源：OpenAI 向开发者开放 Agent 运行时底层，三层集成接口完整解析

- 原文：[https://news.qiniu.com/archives/1787276125198](https://news.qiniu.com/archives/1787276125198)
- 发布时间：2026-08-21
- 分类：行业动态
- 标签：AI Agent、Agent Harness、Codex

> 发布日期：2026-08-21 | 适用人群：Agent 开发者 / AI 基础设施工程师 / 开源贡献者 | 数据来源：openai/codex GitHub 仓库 + 官方博客（2026-08-21）

OpenAI 于 2026 年 8 月 19 日在官方博客宣布，驱动 Codex App、CLI 和 IDE 扩展运行的底层执行框架——**Codex agent harness**——正式完全开源，发布地址 github.com/openai/codex（Apache-2.0 协议）。此次开源的核心是 harness 的三层集成接口：轻量非交互调用（`codex exec`）、程序化编排（Codex SDK）、持久会话驱动（Codex app-server），覆盖从 CI 脚本到产品级 Agent 产品的全场景构建需求。截至 2026-08-21，仓库已累计 107,443 Star、16,354 Fork，最新稳定版为 v0.149.0（2026-08-20 发布）。

* * *

## Codex Harness 是什么？

**Harness** 是驱动 Codex 代理运行的底层执行框架——它管理对话状态、工具调用、沙箱执行、流式输出和人工审批，是 Codex App、CLI、VS Code 插件共用的同一套基础设施。

官方博客原文描述其价值："your application owns product context, business rules, and tools; Codex app-server provides the agent loop."

harness 框架的设计哲学与近期另一个引发关注的同类项目 DeepSeek Harness 高度呼应——**Everything through the harness**：模型不直接面向用户，而是被 harness 封装后以可控、可审批、可持久化的方式对外提供能力。两者均采用插件/扩展机制，但 Codex Harness 以 **Rust 核心（codex-rs）+ TypeScript SDK** 双栈实现，定位更偏向生产环境嵌入。

* * *

![](https://news-static.qiniu.com/legacy/images/9e/9e83c6d827ed6873f8deeb0a9f93bb7ab62f7ab31111c75d073f94ecd9d01216.jpg)

## 为什么这次开源值得关注？

此前 openai/codex 仓库开放的是 CLI 前端源码（2025 年 4 月首次开源），底层 Rust 核心 codex-rs 和 app-server 驱动层属于内部实现，未完整开源。**2026-08-19 的关键变化是 app-server 协议和 SDK 集成接口的完整开放**——开发者现在可以：

1. 将 Codex Agent 嵌入自己的产品，而不只是调用 CLI
2. 替换 Codex 的底层模型提供方（OpenAI、DeepSeek、七牛云统一接口等任意 OpenAI 兼容端点）
3. 在 CI/CD 流水线中无人工干预地运行 Agent 任务

**ARC-AGI-3 的数据给出了 harness 设计质量的直接证据**：通过 retained reasoning 和 context compaction 优化后，GPT-5.6 Sol 在 ARC-AGI-3 上的得分从 13.3% 跃升至 38.3%，同时输出 token 消耗减少六倍——同一模型、不同 harness 策略，效果差距 3 倍。

* * *

## codex-rs：Rust 核心的完整目录

核心仓库 `codex-rs/` 是用 Rust 实现的 harness 底层，包含以下关键子模块：

| 子模块 | 功能 |
|---|---|
| `app-server` | 驱动 VS Code 插件和桌面 App 的 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` | 模型提供方抽象层 |

* * *

## 三层集成接口详解

### 第一层：codex exec（CI 脚本 / 非交互任务）

最轻量的接入方式，适合一次性任务、CI 流水线、批量脚本：

```bash
# 安装
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 非交互执行单次任务
codex exec "重构 src/utils.ts 中的 fetchData 函数，添加错误处理"

# 指定工作目录
codex exec --cwd /path/to/project "运行测试并修复失败的测试用例"
```

`codex exec` 在后台启动 exec-server，执行完毕后自动退出，适合无需持久会话的场景。

* * *

### 第二层：Codex SDK（程序化 Agent 编排）

SDK 位于 `openai/codex/sdk`，封装了 app-server 的协议，允许在代码中启动、恢复、编排 Agent 工作流：

```typescript
import { CodexAgent } from '@openai/codex-sdk'

const agent = new CodexAgent({
  model: 'gpt-5.6',          // 或任意 OpenAI 兼容端点
  cwd: '/path/to/project',
  approvalPolicy: 'auto',    // auto / manual / suggest
})

// 开启新会话
const thread = await agent.thread.start({
  input: '分析仓库中的性能瓶颈并提出优化方案',
})

// 流式接收事件
for await (const event of agent.stream(thread.id)) {
  if (event.type === 'item/agentMessage/delta') {
    process.stdout.write(event.delta)
  }
  if (event.type === 'turn/completed') {
    console.log('Token 用量：', event.usage)
    break
  }
}

// v0.149.0 新增：SDK 支持 max / ultra 推理强度
const agent_max = new CodexAgent({
  model: 'gpt-5.6',
  reasoningEffort: 'max',    // low / medium / high / max / ultra
})
```

SDK 支持 `thread/fork`（分叉会话）、`thread/resume`（恢复历史会话）、`turn/interrupt`（中断当前轮次），可构建完整的多轮 Agent 交互产品。

* * *

### 第三层：Codex app-server（持久会话 + 流式事件 + 审批）

app-server 是为产品级接入设计的进程间通信层，驱动 VS Code 插件和 Codex Desktop App 的运行时。协议基于 JSON-RPC 2.0，支持以下传输方式：

| 传输方式 | 命令示例 | 适用场景 |
|---|---|---|
| stdio（默认） | `codex app-server --stdio` | 嵌入子进程，stdin/stdout JSONL |
| Unix socket | `codex app-server --listen unix://` | 本地控制面板，同机多进程 |
| WebSocket | `codex app-server --listen ws://127.0.0.1:PORT` | 跨进程流式传输（实验性） |

**三大核心原语**：

- **Thread**：一次完整对话会话，包含多个 Turn，可 fork/resume
- **Turn**：单轮交互，从用户消息到 Agent 完成，包含流式 Item 序列
- **Item**：Turn 内的原子事件：用户消息、推理步骤、Shell 命令、文件编辑、工具调用结果

生成 Schema 的命令：

```bash
# 生成 TypeScript 类型定义
codex app-server generate-ts --out ./schema/

# 生成 JSON Schema
codex app-server generate-json-schema --out ./schema/
```

* * *

## v0.149.0 主要更新（2026-08-20）

此次开源的同时，Codex 发布了 v0.149.0 稳定版，包含以下重要更新：

### 新功能

`codex agents` **仪表盘**：交互式 Agent 管理界面，支持搜索、启动、打开、重命名、停止任务，快捷键可自定义。这是 Harness 开源后最直接体现"可操控 Agent 生命周期"设计理念的功能。

`codex queue`：向已运行的本地或远程会话发送消息，无需等待当前 Turn 完成。典型场景：Agent 正在跑测试，同时追加新需求到队列。

```bash
# 向已有会话追加消息
codex queue --thread-id <thread-id> "同时帮我更新 CHANGELOG.md"
```

**工作目录切换**（TUI 内）：新增 `/cd`、`/pwd`、`/cwd` 命令，无需退出会话即可切换工作目录。

**SDK 推理强度控制**：SDK 用户现在可以指定 `max` 或 `ultra` 推理强度：

```typescript
agent.config({ reasoningEffort: 'ultra' })
```

`codex doctor` **增强**：新增端点保护检查、网络/代理故障诊断、桌面 App 状态检查、更新连通性检查。遇到连接问题时优先运行：

```bash
codex doctor
```

### Bug 修复

- 队列消息现在能可靠唤醒空闲会话
- 恢复和分叉的线程现在正确还原权限 Profile，不再静默回退到默认值
- Sub-agent 重复活动问题修复
- Realtime WebRTC 侧信道连接断线后自动重连

* * *

## 接入自定义模型提供方

harness 的 `model-provider` 模块支持任意 OpenAI 兼容端点。多模型统一接入平台（如七牛云大模型广场 qiniu.com/ai/models，提供 DeepSeek、Kimi、GLM 等多款模型的统一 API Key）可通过修改 `base_url` 直接接入：

```bash
# 在 codex config 中设置自定义端点
export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"

# 使用自定义端点运行
codex exec --model deepseek-v4-flash "帮我优化这段代码"
```

配置文件方式（`~/.codex/config.toml`）：

```toml
[model]
provider = "openai"
model = "deepseek-v4-flash"
base_url = "https://api.qnaigc.com/v1"

[auth]
api_key_env = "YOUR_API_KEY_ENV"    # 引用环境变量名
```

* * *

## 开源组件总览

| 组件 | 仓库位置 | 协议 |
|---|---|---|
| Codex CLI + Harness 核心（codex-rs） | openai/codex | Apache-2.0 |
| Codex SDK（TypeScript） | openai/codex/sdk | Apache-2.0 |
| Codex app-server | openai/codex/codex-rs/app-server | Apache-2.0 |
| Codex Universal Cloud Environment | openai/codex-universal | — |
| Skills 库 | openai/skills | — |
| Plugins 库 | openai/plugins | — |
| Codex Security CLI | openai/codex-security | — |

**未开源**：IDE Extension 内部实现、Codex Cloud 托管服务本身。

* * *

## FAQ

**Q：Codex Harness 和 DeepSeek Harness 是同一套东西吗？**

不是，两者独立开发，但设计理念相近——均以 harness 为层级封装模型调用。Codex Harness 由 OpenAI 用 Rust 实现，以 app-server 为核心，面向生产级 Agent 产品嵌入；DeepSeek Harness 由 DeepSeek AI 用 TypeScript/Cordis 实现，以"Everything is a Plugin"为核心，面向开发者运行时灵活扩展。有意思的是，Codex 作为子代理（Profile Bundle）可以安装到 DeepSeek Harness 中，形成嵌套关系。

**Q：v0.149.0 用 Rust 重写和之前的 Node.js 版有什么区别？**

`codex-rs` 是当前的 Rust 核心，处理所有性能敏感路径（执行调度、沙箱、TUI 渲染、传输层）。TypeScript/Node.js 层（`sdk/`）保留为上层接口，供应用开发者调用，不直接接触 Rust 核心。对最终用户来说，切换感知不明显，但资源占用和稳定性有显著提升——`codex agents` 仪表盘在大量并发会话下的响应速度是 Node.js 时代无法达到的。

**Q：**`codex app-server` **的 WebSocket 传输现在能用于生产吗？**

目前标注为 "experimental / unsupported"，官方明确表示不应依赖用于生产工作负载。建议生产环境使用 stdio 或 unix socket 传输。WebSocket 模式在 `/healthz` 端点存在 Origin 头检查（有 Origin → 403），用于本地调试时绕过检查直接用 `localhost` 即可。

**Q：如何在 CI/CD 中运行 Codex Agent 而不触发人工审批弹窗？**

在 `codex exec` 中设置 `--approval-policy auto`（自动批准所有操作）或 `--approval-policy suggest`（仅建议，不阻塞）。v0.149.0 修复了 approval profile 在 resumed/forked 线程中静默回退的 bug，确保 CI 场景下的权限策略始终一致。

**Q：Codex OSS 计划是什么？**

OpenAI 面向开源维护者提供 Codex for OSS 申请，通过审核的项目可获得 API credits、ChatGPT Pro with Codex、Codex Security 选择性访问。入口：chatgpt.com/community/codex-for-oss。

* * *

![](https://news-static.qiniu.com/legacy/images/cc/cc23d11606411665c872167364baaa0015a44a62b0193565b483998cca47b52b.jpg)

## 结语

Codex Harness 全面开源的核心意义不在于"又一个开源工具"，而在于**OpenAI 把驱动自家商业产品的 Agent 运行时底层对外完全开放**。三层集成接口（exec → SDK → app-server）覆盖了从脚本到产品的完整连续体，开发者第一次可以用与 Codex App 完全相同的 harness 构建自己的 Agent 产品。ARC-AGI-3 上 harness 优化带来的 3 倍效果提升，直接反映了这套架构设计在生产环境中的实际价值。v0.149.0 同步上线的 `codex agents` 仪表盘和 `codex queue` 消息队列，是 harness 开放后"可编排 Agent 生命周期"能力的第一批直接体现。

**数据来源**（均为官方渠道，2026-08-21）：

- Codex 官方博客：learn.chatgpt.com/blog/codex-as-a-platform
- openai/codex 仓库：github.com/openai/codex
- v0.149.0 Release Notes：github.com/openai/codex/releases/tag/rust-v0.149.0
- app-server 文档：github.com/openai/codex/blob/main/codex-rs/app-server/README.md

* * *

## 延伸阅读

- Codex GitHub 仓库（Apache-2.0）：[https://github.com/openai/codex](https://github.com/openai/codex)
- v0.149.0 Release Notes：[https://github.com/openai/codex/releases/tag/rust-v0.149.0](https://github.com/openai/codex/releases/tag/rust-v0.149.0)
- Codex app-server 协议文档：[https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md](https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md)
- Codex 官方文档：[https://learn.chatgpt.com/docs](https://learn.chatgpt.com/docs)
- 七牛云大模型广场（多模型统一 API，可接入 Codex Harness）：[https://www.qiniu.com/ai/models](https://www.qiniu.com/ai/models)
