Skip to content
Jefferson Gonçalves
← Back to projects

Codex Field Guide

从零理解 OpenAI Codex Coding Agent：Agent Loop、Runtime、Context、Tool、安全边界与源码实现。

#Codex Field Guide

一份从零理解 OpenAI Codex / Codex CLI 的源码型技术教材。项目使用 Astro、TypeScript 和 MDX 构建，包含 14 章中文内容、8 类核心图解、交互式 Agent Loop 演示、本地搜索、代码复制、图表放大、阅读进度、深浅色模式与响应式三栏布局。

这不是 OpenAI 官方文档。源码分析固定在以下公开快照：

#运行

要求 Node.js 22+ 和 pnpm。

pnpm install
pnpm dev

打开终端显示的本地地址，默认通常是 http://localhost:4321。

生产构建：

pnpm build
pnpm preview

pnpm build 会先执行 astro check，再生成静态站点到 dist/。

Sites 托管包使用：

pnpm build:sites

该命令保留 Astro 静态输出，并将其整理为 dist/client，同时加入一个只负责静态资源路由的 Cloudflare Worker 入口。

#内容结构

src/
├─ components/
│  ├─ AgentLoopDemo.astro   # 可交互执行轨迹
│  ├─ Mermaid.astro         # Mermaid 渲染与放大
│  ├─ SourceRef.astro       # 固定 commit 源码引用
│  └─ ...
├─ content/docs/            # 14 章 MDX 教材
├─ data/
│  ├─ navigation.ts         # 学习路径与导航
│  └─ source.ts             # 研究快照和官方文档
├─ layouts/
│  ├─ BaseLayout.astro      # 全局交互、搜索、主题
│  └─ DocsLayout.astro      # 三栏文档布局
├─ pages/
│  ├─ index.astro
│  └─ docs/[...slug].astro
└─ styles/global.css
worker/index.js               # Sites 静态资源适配器
scripts/prepare-sites.mjs     # 托管包整理脚本

#扩展一章

  1. 在 src/content/docs/ 新建 .mdx；
  2. 按 src/content.config.ts 填写 frontmatter；
  3. 在 src/data/navigation.ts 加入章节；
  4. 使用 SourceRef 时给出相对于 openai/codex 根目录的真实路径；
  5. 运行 pnpm build，检查 schema、类型、链接与静态输出。

#证据约定

  • 源码可证实：固定 commit 中的类型、函数、控制流或测试直接支持；
  • 官方文档：公开文档描述的用户可见行为；
  • 公开证据上的分析：用于讲解设计取舍，不代表 OpenAI 的内部设计声明；
  • 教学示意：示意代码、流程或例子，不伪装成官方源码。

版本与研究边界见站内“研究基线与边界”一章。

#设计

视觉系统参考当前仓库 Design DNA 的结构原则：克制的开发者工具气质、三栏长文阅读、细边界、紧凑导航、单一强调色和高密度但不拥挤的信息层级。它复用的是设计语言，不是对任一模板的像素复制。

#License

站点源码按仓库所有者的许可策略使用。OpenAI、Codex 及其他产品名称归各自权利人所有；引用的第三方源码与文档遵循其原始许可。

New version available.