# https://github.com/openai/codex 项目说明书 生成时间：2026-05-13 10:17:37 UTC ## 目录 - [项目概述](#page-overview) - [系统架构](#page-architecture) - [协议层详解](#page-protocol) - [核心Agent模块](#page-core-agent) - [执行系统](#page-execution) - [终端用户界面](#page-tui) - [技能系统](#page-skills) - [插件系统](#page-plugins) - [Hook系统](#page-hooks) - [沙箱与安全](#page-sandboxing) ## 项目概述 ### 相关页面 相关主题：[系统架构](#page-architecture), [核心Agent模块](#page-core-agent)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/openai/codex/blob/main/README.md) - [codex-rs/tui/src/slash_command.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/slash_command.rs) - [codex-rs/tui/src/bottom_pane/footer.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/footer.rs) - [codex-rs/config/src/profile_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/profile_toml.rs) - [codex-rs/config/src/tui_keymap.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/tui_keymap.rs) - [codex-rs/config/src/config_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_toml.rs)
# 项目概述 ## 什么是 Codex CLI Codex CLI 是 OpenAI 开发的本地编程智能助手，能够在用户的计算机上本地运行。它是一个跨平台的命令行工具，旨在帮助开发者完成各种编码任务，包括代码编写、文件编辑、Git 操作和终端命令执行。 资料来源：[README.md:1]() Codex 提供三种使用形态： | 使用形态 | 说明 | 访问方式 | |---------|------|---------| | **CLI 工具** | 本地终端界面，运行在用户计算机上 | 运行 `codex` 命令 | | **IDE 插件** | 集成在 VS Code、Cursor、Windsurf 等编辑器中 | 安装 IDE 插件 | | **桌面应用** | 独立的桌面客户端体验 | 运行 `codex app` 或访问网页版 | 对于云端智能助手版本（Codex Web），用户可以访问 chatgpt.com/codex。 资料来源：[README.md:8]() ## 安装与运行 ### 安装方式 Codex 支持两种主流安装方式： ```shell # 使用 npm 全局安装 npm install -g @openai/codex # 使用 Homebrew 安装 brew install --cask codex ``` 安装完成后，直接在终端运行 `codex` 即可启动。 资料来源：[README.md:17-28]() ## 核心功能模块 ### 命令系统（Slash Commands） Codex CLI 内置丰富的斜杠命令系统，用户可以通过 `/` 前缀调用各种功能： | 命令类别 | 功能项 | 说明 | |---------|-------|------| | 会话管理 | `/resume`, `/fork`, `/clear` | 恢复会话、分叉会话、清除终端 | | 文件操作 | `/mention`, `/diff` | 提及文件、显示 Git 差异 | | 配置管理 | `/status`, `/debug-config`, `/settings` | 查看状态、调试配置、设置选项 | | 开发工具 | `/skills`, `/hooks`, `/mcp` | 技能系统、生命周期钩子、MCP 工具 | | 界面定制 | `/theme`, `/keymap`, `/pets`, `/title` | 主题、快捷键、终端宠物、标题栏 | | 执行控制 | `/plan`, `/goal`, `/stop` | 计划模式、目标设置、停止后台进程 | | 权限管理 | `/permissions`, `/elevate-sandbox` | 权限配置、沙盒提升 | | 高级功能 | `/realtime`, `/collab`, `/agent` | 实时语音、协作模式、多代理 | 资料来源：[codex-rs/tui/src/slash_command.rs:1-50]() ### 快捷键系统 Codex 的文本用户界面（TUI）支持全面的快捷键绑定，主要包括： **运动类快捷键** | 操作 | 默认绑定 | 说明 | |------|---------|------| | `motion_left` | 左移 | 光标向左移动 | | `motion_right` | 右移 | 光标向右移动 | | `motion_up` | 上移 | 光标向上移动一行 | | `motion_down` | 下移 | 光标向下移动一行 | | `motion_word_forward` | `w` | 移动到下一个单词开头 | | `motion_word_backward` | `b` | 移动到上一个单词开头 | | `motion_word_end` | `e` | 移动到单词结尾 | | `motion_line_start` | `0` | 移动到行首 | | `motion_line_end` | `$` | 移动到行尾 | **分页器快捷键** | 操作 | 功能 | |------|------| | `scroll_up` / `scroll_down` | 按行滚动 | | `page_up` / `page_down` | 按页滚动 | | `half_page_up` / `half_page_down` | 半页滚动 | | `jump_top` / `jump_bottom` | 跳转到顶部/底部 | | `close` / `close_transcript` | 关闭分页器/转录 | **列表和审批快捷键** | 类别 | 操作 | |------|------| | 列表 | `move_up`, `move_down`, `accept`, `cancel` | | 审批 | `open_fullscreen`, `open_thread`, `approve`, `deny`, `decline` | 资料来源：[codex-rs/config/src/tui_keymap.rs:1-50]() ### 底部面板与状态栏 Codex 界面底部面板展示各类快捷操作提示，包括： - 命令执行相关快捷键 - Shell 命令快捷键 - 文件路径操作（粘贴图片、外部编辑器调用） - 历史记录搜索 - 推理模式切换（`reasoning_down` / `reasoning_up`） - 会话转录显示 底部面板采用双列布局展示各项功能，每列之间有 4 个字符的间距。 资料来源：[codex-rs/tui/src/bottom_pane/footer.rs:1-50]() ### 状态显示系统 状态栏提供实时的工作环境信息： | 状态项 | 说明 | 示例值 | |-------|------|--------| | `AppName` | 应用名称 | Codex | | `ProjectName` | 项目名称 | my-project | | `GitBranch` | 当前 Git 分支 | feat/awesome-feature | | `PullRequestNumber` | PR 编号 | PR #123 | | `BranchChanges` | 分支变更统计 | +12 -3 | | `Permissions` | 权限级别 | Workspace | | `ContextRemaining` | 剩余上下文 | Context 0% left | | `UsedTokens` | 已使用 Token | 0 used | | `Model` | 当前模型 | gpt-5.2-codex | | `SessionId` | 会话 ID | 550e8400-e29b-41d4 | 资料来源：[codex-rs/tui/src/status/card.rs:1-50](), [codex-rs/tui/src/status_surfaces.rs:1-40]() ## 配置系统 ### 配置文件结构 Codex 采用 TOML 格式的配置文件，支持多层级配置： ```toml # 全局配置 [profile.default] model = "gpt-5" include_apply_patch_tool = true include_permissions_instructions = true # TUI 配置 [profile.default.tui] session_picker_view = "grid" # 或 "list" # 实验性功能 [profile.default.features] codex_git_commit = true experimental_realtime = false ``` ### 配置选项说明 | 配置项 | 类型 | 说明 | |-------|------|------| | `model_instructions_file` | 路径 | 自定义模型指令文件（不推荐） | | `compact_prompt` | 字符串 | 历史压缩提示词 | | `commit_attribution` | 字符串 | 提交信息中的共同作者署名 | | `forced_chatgpt_workspace_id` | 字符串 | 限制登录到特定工作区 | | `forced_login_method` | 枚举 | 强制使用特定登录方式 | 资料来源：[codex-rs/config/src/profile_toml.rs:1-40](), [codex-rs/config/src/config_toml.rs:1-50]() ## 主题与语法高亮 Codex 内置多种语法高亮主题，支持自定义代码显示颜色： **可用主题列表** | 主题名称 | 类型 | |---------|------| | catppuccin-latte / macchiato / mocha | 暖色调 | | coldark-cold / dark | 冷色调 | | dark-neon | 霓虹风格 | | dracula | 经典紫红 | | github | GitHub 风格 | | gruvbox-dark / light | 复古风格 | | inspired-github | GitHub 灵感 | | 1337 (leet) | 黑客风格 | | monokai-extended 系列 | Monokai 扩展 | | nord | 北欧极简 | | one-half-dark / light | 简约双色 | 资料来源：[codex-rs/tui/src/render/highlight.rs:1-60]() ## 目标与预算系统 Codex 内置目标追踪系统，支持长时间运行任务的规划与监控： ```mermaid graph TD A[创建目标] --> B{预算检查} B -->|预算充足| C[执行任务] B -->|预算耗尽| D[触发预算限制提示] C --> E[目标更新] E --> F{任务完成?} F -->|否| C F -->|是| G[目标达成] D --> H[暂停或终止] ``` 目标系统包含以下组件： - **目标模板**：使用 Markdown 模板定义目标展示格式 - **预算限制**：监控任务消耗，必要时触发提醒 - **目标更新**：实时反馈目标进展状态 资料来源：[codex-rs/core/src/goals.rs:1-60]() ## 环境上下文 Codex 能够感知并注入当前工作环境信息： ```xml /path/to/project bash 2024-01-15 Asia/Shanghai ``` | 环境组件 | 说明 | |---------|------| | `cwd` | 当前工作目录 | | `shell` | 终端类型（bash/zsh/powershell） | | `network` | 网络状态信息 | | `subagents` | 子代理信息（多代理模式下） | 资料来源：[codex-rs/core/src/context/environment_context.rs:1-50]() ## 应用与插件系统 Codex 支持外部应用集成和 MCP（Model Context Protocol）工具： ```mermaid graph LR A[Codex CLI] --> B[应用系统] A --> C[MCP 工具] B --> D{应用配置} D -->|已启用| E[集成到界面] D -->|已禁用| F[隐藏] C --> G[工具列表] G --> H[详细工具说明] ``` **应用元数据结构** | 字段 | 说明 | |-----|------| | `id` | 应用唯一标识 | | `name` | 显示名称 | | `description` | 应用描述 | | `logo_url` | 图标 URL | | `is_enabled` | 是否启用 | | `install_url` | 安装链接 | 资料来源：[codex-rs/app-server-protocol/src/protocol/v2/apps.rs:1-50]() ## 架构总览 ```mermaid graph TB subgraph 前端层 A[命令行入口] --> B[文本用户界面 TUI] B --> C[底部面板] B --> D[状态栏] B --> E[快捷键系统] end subgraph 配置层 F[配置文件] --> G[配置解析器] G --> H[Profile 管理] H --> I[TUI 设置] H --> J[功能开关] end subgraph 核心层 K[会话管理] --> L[目标系统] K --> M[上下文管理] M --> N[环境感知] L --> O[预算控制] end subgraph 集成层 P[IDE 插件接口] --> Q[应用系统] P --> R[MCP 工具] Q --> S[应用市场] end A --> K G --> K ``` ## 技术栈概述 | 组件 | 技术选型 | 说明 | |-----|---------|------| | CLI 核心 | Rust | 高性能本地执行 | | 前端界面 | 自研 TUI | 终端文本用户界面 | | 配置格式 | TOML | 人类可读的配置文件 | | 主题系统 | TextMate 主题格式 | 兼容主流编辑器语法高亮 | | 序列化 | JSON Schema | API 数据结构定义 | | 类型导出 | TypeScript | 前端类型安全 | ## 快速入门 1. **安装 Codex**：`npm i -g @openai/codex` 或 `brew install --cask codex` 2. **启动应用**：运行 `codex` 命令 3. **查看帮助**：输入 `/help` 或查看底部快捷键提示 4. **自定义配置**：编辑 `~/.codex/config.toml` 5. **切换主题**：使用 `/theme` 命令选择语法高亮主题 ## 相关资源 - 官方文档：[developers.openai.com/codex/ide](https://developers.openai.com/codex/ide) - 桌面应用：运行 `codex app` 或访问 chatgpt.com/codex - IDE 插件：支持 VS Code、Cursor、Windsurf --- ## 系统架构 ### 相关页面 相关主题：[协议层详解](#page-protocol), [核心Agent模块](#page-core-agent), [终端用户界面](#page-tui)
相关源码文件 以下源码文件用于生成本页说明： - [codex-rs/config/src/state.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs) - [codex-rs/config/src/loader/mod.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/loader/mod.rs) - [codex-rs/config/src/config_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_toml.rs) - [codex-rs/config/src/profile_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/profile_toml.rs) - [codex-rs/core/src/context/environment_context.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/context/environment_context.rs) - [codex-rs/core/src/goals.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/goals.rs) - [codex-rs/tui/src/chatwidget.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs) - [codex-rs/file-search/README.md](https://github.com/openai/codex/blob/main/codex-rs/file-search/README.md)
# 系统架构 ## 1. 概述 Codex CLI 是 OpenAI 开发的一个本地代码智能助手，采用 Rust 语言重写实现。该项目遵循模块化架构设计，将功能拆分为多个独立但协作的子系统。 核心架构包含以下几个主要层次： | 层次 | 模块 | 职责 | |------|------|------| | 配置层 | `codex-rs/config/` | 管理配置加载、层级合并、需求约束 | | 核心层 | `codex-rs/core/` | 处理环境上下文、目标管理、推理逻辑 | | 交互层 | `codex-rs/tui/` | 终端用户界面、聊天组件、状态显示 | | 文件搜索 | `codex-rs/file-search/` | 模糊文件搜索、模式匹配 | | 沙箱层 | `codex-rs/windows-sandbox-rs/` | Windows 平台沙箱环境 | 资料来源：[codex-rs/README.md](https://github.com/openai/codex/blob/main/codex-rs/README.md) ## 2. 配置系统架构 ### 2.1 配置层级结构 Codex 采用多层配置架构，不同来源的配置按优先级合并。配置层级从低到高依次为： ```mermaid graph TD A[系统配置
System] --> B[用户配置
User] B --> C[项目配置
Project] C --> D[MDM 托管配置
MDM Managed] D --> E[会话标志配置
Session Flags] style A fill:#e1f5fe style E fill:#fff3e0 ``` `ConfigLayerStack` 结构维护配置层级列表，其中 `layers` 向量按从低优先级（基础）到高优先级（覆盖）的顺序排列。资料来源：[codex-rs/config/src/state.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs) ### 2.2 配置来源枚举 ```rust pub enum ConfigLayerSource { System { file: PathBuf }, User { file: PathBuf }, Project { dot_codex_folder: AbsolutePathBuf }, Mdm { domain: String, key: String }, SessionFlags, LegacyManagedConfigTomlFromFile { file: PathBuf }, LegacyManagedConfigTomlFromMdm, } ``` 每种配置来源对应不同的配置文件位置： | 来源类型 | 文件位置 | 说明 | |---------|---------|------| | System | 系统指定路径 | 系统级配置 | | User | 用户目录 `~/.codex/` | 用户个性化配置 | | Project | 项目 `.codex/` 目录 | 项目特定配置 | | MDM | 移动设备管理 | 企业托管配置 | | SessionFlags | 命令行参数 | 会话级别覆盖 | 资料来源：[codex-rs/config/src/state.rs:1-30](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs) ### 2.3 配置文件加载流程 配置加载器 (`ConfigLoader`) 负责协调多层级配置的读取和合并： ```mermaid sequenceDiagram participant User as 用户/CLI participant Loader as ConfigLoader participant FileSystem as 文件系统 participant Merger as 配置合并器 User->>Loader: 启动 Codex Loader->>FileSystem: 读取系统配置 FileSystem-->>Loader: system.toml Loader->>FileSystem: 读取用户配置 FileSystem-->>Loader: config.toml Loader->>FileSystem: 读取项目配置 FileSystem-->>Loader: .codex/config.toml Loader->>Merger: 合并配置层级 Merger-->>User: 最终配置 ``` 配置加载过程中的关键步骤包括： 1. 解析 TOML 格式的配置文件 2. 清理无效的项目配置键 3. 解析相对路径为绝对路径 4. 合并 Git worktree 的钩子配置 资料来源：[codex-rs/config/src/loader/mod.rs:1-80](https://github.com/openai/codex/blob/main/codex-rs/config/src/loader/mod.rs) ### 2.4 Profile 配置结构 Profile 机制允许用户定义命名配置集，每个 Profile 可包含独立的 TUI 设置、窗口配置和功能开关： ```rust pub struct ProfileTui { /// Resume/Fork 会话选择器的首选布局 pub session_picker_view: Option, } pub struct FeaturesToml { // 注入已知功能键到 schema } ``` Profile 作用域的配置包括： - TUI 布局偏好设置 - 窗口配置 - 功能特性开关 资料来源：[codex-rs/config/src/profile_toml.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/config/src/profile_toml.rs) ### 2.5 配置诊断系统 当配置解析失败时，诊断系统提供详细的错误报告： ```rust pub fn format_config_error(error: &ConfigError, contents: &str) -> String { // 输出格式: path:line:column: message // 包含错误位置的高亮行 } ``` 错误报告包含文件路径、行号、列号和错误消息，并从 TOML 解析的 span 信息中提取错误位置。资料来源：[codex-rs/config/src/diagnostics.rs:1-40](https://github.com/openai/codex/blob/main/codex-rs/config/src/diagnostics.rs) ## 3. 环境上下文系统 ### 3.1 上下文数据模型 环境上下文 (`EnvironmentContext`) 聚合了 Codex 运行所需的全部环境信息： ```mermaid graph TD EC[EnvironmentContext] --> Env[Environments] EC --> Date[CurrentDate] EC --> TZ[Timezone] EC --> Net[Network] EC --> Subs[Subagents] Env --> Single[Single Environment] Env --> Multiple[Multiple Environments] Env --> None[None] ``` 关键字段： - **environments**: 工作目录和 shell 信息 - **current_date**: 当前日期 - **timezone**: 时区设置 - **network**: 网络连接状态 - **subagents**: 子代理信息 资料来源：[codex-rs/core/src/context/environment_context.rs:1-60](https://github.com/openai/codex/blob/main/codex-rs/core/src/context/environment_context.rs) ### 3.2 上下文 XML 渲染 环境上下文以 XML 格式渲染，供模型理解当前执行环境： ```xml /path/to/project bash 2024-01-15 Asia/Shanghai ``` 资料来源：[codex-rs/core/src/context/environment_context.rs:60-100](https://github.com/openai/codex/blob/main/codex-rs/core/src/context/environment_context.rs) ## 4. 目标管理系统 ### 4.1 目标生命周期 Codex 的目标 (Goal) 系统管理长时间运行的任务： ```mermaid stateDiagram-v2 [*] --> NewGoal: 设置目标 NewGoal --> Active: 开始执行 Active --> Paused: 中断 Active --> Completed: 完成 Active --> Failed: 失败 Paused --> Active: 恢复 Failed --> [*] Completed --> [*] ``` `ExternalGoalPreviousStatus` 枚举表示外部目标变更前的状态： - `NewGoal`: 新创建的逻辑目标 - `Existing`: 更新的现有目标 资料来源：[codex-rs/core/src/goals.rs:1-80](https://github.com/openai/codex/blob/main/codex-rs/core/src/goals.rs) ### 4.2 预算限制与节流 目标系统内置预算限制提示模板： - `continuation.md`: 继续执行提示 - `budget_limit.md`: 预算耗尽提示 - `objective_updated.md`: 目标更新通知 资料来源：[codex-rs/core/src/goals.rs:80-120](https://github.com/openai/codex/blob/main/codex-rs/core/src/goals.rs) ## 5. TUI 终端用户界面 ### 5.1 组件架构 TUI 模块采用组件化设计： ``` tui/src/ ├── chatwidget.rs # 聊天消息组件 ├── markdown_render_tests.rs # Markdown 渲染测试 └── bottom_pane/ ├── footer.rs # 底部状态栏 ├── status_surface_preview.rs # 状态预览 └── approval_overlay.rs # 审批覆盖层 ``` ### 5.2 风险等级映射 聊天组件 (`chatwidget`) 处理来自应用服务器协议的风险等级映射： ```mermaid graph LR A[GuardianRiskLevel] --> B[AppServer] B --> C[chatwidget] C --> D[Protocol] D --> Low D --> Medium D --> High D --> Critical ``` | 应用服务器等级 | 协议等级 | |--------------|---------| | Low | Low | | Medium | Medium | | High | High | | Critical | Critical | 资料来源：[codex-rs/tui/src/chatwidget.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs) ### 5.3 状态栏配置 底部面板显示快捷命令和状态信息： | 类别 | 快捷键 | |------|--------| | 常规命令 | `/` | | Shell 命令 | `!` | | 队列消息 | `Tab` | | 退出 | `Ctrl+C` | | 推理导航 | `Ctrl+↑/↓` | 自定义快捷键可通过 `/keymap` 命令配置。资料来源：[codex-rs/tui/src/bottom_pane/footer.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/footer.rs) ### 5.4 状态预览项 状态表面预览显示会话的各类状态信息： | 预览项 | 示例值 | |-------|--------| | AppName | Codex | | GitBranch | feat/awesome-feature | | PullRequestNumber | PR #123 | | BranchChanges | +12 -3 | | ContextRemaining | Context 0% left | | UsedTokens | 0 used | | Model | gpt-5.2-codex | | FastMode | Fast on | 资料来源：[codex-rs/tui/src/bottom_pane/status_surface_preview.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/status_surface_preview.rs) ### 5.5 审批覆盖层 文件变更审批系统提供多种决策选项： | 选项 | 快捷键 | 效果 | |------|--------|------| | Yes, proceed | approve | 接受变更 | | Yes, don't ask again | approve_for_session | 本次会话接受 | | No, tell Codex | reject | 拒绝并说明 | 资料来源：[codex-rs/tui/src/bottom_pane/approval_overlay.rs:1-60](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/approval_overlay.rs) ## 6. 文件搜索模块 ### 6.1 搜索架构 `codex_file_search` 模块提供快速的模糊文件搜索能力： ```mermaid graph TD Input[搜索模式] --> Traverse[目录遍历] Traverse --> Ignore[应用 .gitignore] Ignore --> Files[文件列表] Files --> Fuzzy[模糊匹配] Fuzzy --> Results[结果排序] ``` 核心依赖： - **ignore**: 目录遍历（ripgrep 使用的 crate） - **nucleo-matcher**: 快速模糊匹配 资料来源：[codex-rs/file-search/README.md](https://github.com/openai/codex/blob/main/codex-rs/file-search/README.md) ## 7. Slash 命令系统 ### 7.1 命令分类 Slash 命令通过 `/` 触发，提供丰富的交互功能： | 类别 | 命令 | 功能 | |------|------|------| | 会话管理 | `/resume`, `/fork`, `/clear` | 恢复、分叉、清空会话 | | 文件操作 | `/diff`, `/mention` | Git 差异、提及文件 | | 模型控制 | `/model`, `/personality` | 选择模型、交流风格 | | 权限管理 | `/permissions`, `/elevate-sandbox` | 权限设置 | | 实验功能 | `/experimental`, `/realtime` | 开关实验特性 | 支持内联参数的命令： - `/review`, `/rename`, `/plan`, `/goal` - `/ide`, `/keymap`, `/mcp`, `/pets`, `/side` - `/resume`, `/sandbox-read-root` 资料来源：[codex-rs/tui/src/slash_command.rs:1-100](https://github.com/openai/codex/blob/main/codex-rs/tui/src/slash_command.rs) ## 8. 安装与部署 ### 8.1 安装方式 | 方式 | 命令 | |------|------| | npm | `npm i -g @openai/codex` | | Homebrew | `brew install --cask codex` | | GitHub Releases | 下载平台特定二进制 | ### 8.2 目录结构 ``` $CODEX_HOME/ ├── config.toml # 用户配置 ├── sessions/ # 会话数据 ├── log/ # 日志文件 └── hooks/ # 生命周期钩子 ``` - **sqlite_home**: SQLite 数据库路径，默认 `$CODEX_HOME` - **log_dir**: 日志目录，默认 `$CODEX_HOME/log` 资料来源：[codex-rs/config/src/config_toml.rs:1-50](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_toml.rs) ## 9. 模块依赖关系 ```mermaid graph TD App[codex-rs 主程序] Config[config 模块] Core[core 模块] TUI[TUI 模块] FileSearch[file-search 模块] Sandbox[windows-sandbox-rs] App --> Config App --> Core App --> TUI Core --> FileSearch Core --> Sandbox TUI --> Config TUI --> Core ``` 各模块职责清晰分离，通过公共接口交互，便于维护和测试。 --- ## 协议层详解 ### 相关页面 相关主题：[系统架构](#page-architecture), [核心Agent模块](#page-core-agent)
相关源码文件 以下源码文件用于生成本页说明： - [codex-rs/tui/src/chatwidget.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs) - [codex-rs/app-server-protocol/src/protocol/v2/apps.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v2/apps.rs) - [codex-rs/config/src/state.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs) - [codex-rs/config/src/config_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_toml.rs) - [codex-rs/config/src/config_requirements.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_requirements.rs) - [codex-rs/tui/src/bottom_pane/approval_overlay.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/approval_overlay.rs)
# 协议层详解 ## 1. 概述 Codex 项目的协议层是连接前端界面（TUI）、后端服务（App Server）和核心引擎（Core）之间的通信桥梁。该层定义了数据类型转换、API 协议版本管理、以及跨模块通信的数据结构规范。 协议层主要包含两个核心命名空间： - `codex_app_server_protocol`：应用服务器协议定义 - `codex_protocol`：Codex 核心协议定义 ## 2. 协议架构 ### 2.1 模块组织结构 ``` codex-rs/ ├── app-server-protocol/src/protocol/ │ ├── mod.rs # 协议主入口 │ ├── v1.rs # 版本 1 协议定义 │ └── v2/ # 版本 2 协议定义 │ ├── mod.rs │ ├── apps.rs # 应用相关协议 │ └── ... ``` ### 2.2 协议层次关系图 ```mermaid graph TD subgraph "前端层 TUI" A[ChatWidget] B[ApprovalOverlay] C[StatusSurface] end subgraph "协议转换层" D[codex_app_server_protocol] E[codex_protocol] end subgraph "核心层 Core" F[Guardian] G[Approvals] end A --> D B --> D C --> D D --> E E --> F E --> G style D fill:#f9f,color:#000 style E fill:#9f9,color:#000 ``` ## 3. 风险等级协议 ### 3.1 风险等级定义 Codex 使用统一的四层风险等级体系，用于评估操作的安全性和敏感度。 | 风险等级 | 说明 | 适用场景 | |---------|------|---------| | `Low` | 低风险操作 | 读取文件、查看状态 | | `Medium` | 中等风险 | 修改配置、创建文件 | | `High` | 高风险 | 执行命令、修改系统 | | `Critical` | 极高风险 | 删除文件、权限变更 | **资料来源**：[codex-rs/tui/src/chatwidget.rs:1-20](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs) ### 3.2 协议间转换 风险等级在 `codex_app_server_protocol` 和 `codex_protocol` 之间存在一一映射关系： ```rust (|risk_level| match risk_level { codex_app_server_protocol::GuardianRiskLevel::Low => { codex_protocol::approvals::GuardianRiskLevel::Low } codex_app_server_protocol::GuardianRiskLevel::Medium => { codex_protocol::approvals::GuardianRiskLevel::Medium } codex_app_server_protocol::GuardianRiskLevel::High => { codex_protocol::approvals::GuardianRiskLevel::High } codex_app_server_protocol::GuardianRiskLevel::Critical => { codex_protocol::approvals::GuardianRiskLevel::Critical } }) ``` **资料来源**：[codex-rs/tui/src/chatwidget.rs:1-20](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs) ## 4. 用户授权协议 ### 4.1 授权等级定义 | 授权等级 | 说明 | 权限范围 | |---------|------|---------| | `Unknown` | 未知状态 | 未确定授权级别 | | `Low` | 低授权 | 基础操作权限 | | `Medium` | 中等授权 | 常规开发操作 | | `High` | 高授权 | 敏感操作权限 | ### 4.2 授权协议转换 用户授权信息在协议间进行转换： ```rust user_authorization: review.user_authorization.map(|user_authorization| { match user_authorization { codex_app_server_protocol::GuardianUserAuthorization::Unknown => { codex_protocol::approvals::GuardianUserAuthorization::Unknown } codex_app_server_protocol::GuardianUserAuthorization::Low => { codex_protocol::approvals::GuardianUserAuthorization::Low } codex_app_server_protocol::GuardianUserAuthorization::Medium => { codex_protocol::approvals::GuardianUserAuthorization::Medium } codex_app_server_protocol::GuardianUserAuthorization::High => { codex_protocol::approvals::GuardianUserAuthorization::High } } }) ``` **资料来源**：[codex-rs/tui/src/chatwidget.rs:1-30](https://github.com/openai/codex/blob/main/codex-rs/tui/src/chatwidget.rs) ## 5. 应用协议（V2） ### 5.1 应用信息结构 应用元数据结构定义如下： ```rust pub struct AppInfo { pub id: String, pub name: String, pub description: Option, pub logo_url: Option, pub logo_url_dark: Option, pub distribution_channel: Option, pub branding: Option, pub app_metadata: Option, pub labels: Option>, pub install_url: Option, #[serde(default)] pub is_accessible: bool, #[serde(default = "default_enabled")] pub is_enabled: bool, #[serde(default)] pub plugin_display_names: Vec, } ``` **资料来源**：[codex-rs/app-server-protocol/src/protocol/v2/apps.rs:50-70](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v2/apps.rs) ### 5.2 应用元数据 应用元数据支持以下字段： | 字段 | 类型 | 说明 | |-----|------|-----| | `screenshots` | `Vec` | 应用截图列表 | | `developer` | `String` | 开发者信息 | | `version` | `String` | 版本号 | | `version_id` | `String` | 版本标识 | | `version_notes` | `String` | 版本说明 | | `first_party_type` | `String` | 第一方类型 | | `first_party_requires_install` | `bool` | 是否需要安装 | | `show_in_composer_when_unlinked` | `bool` | 未链接时显示 | **资料来源**：[codex-rs/app-server-protocol/src/protocol/v2/apps.rs:30-50](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v2/apps.rs) ## 6. 配置层协议 ### 6.1 配置层级来源 配置层定义在 `ConfigLayerSource` 枚举中，支持多种配置来源： | 来源类型 | 说明 | 优先级 | |---------|------|-------| | `Mdm` | MDM 托管偏好 | 最高 | | `System` | 系统级配置 | 高 | | `User` | 用户级配置 | 中 | | `Project` | 项目级 `.codex/config.toml` | 低 | | `SessionFlags` | 会话命令行参数 | 特殊 | ```rust pub enum ConfigLayerSource { Mdm { domain: String, key: String }, System { file: PathBuf }, User { file: PathBuf }, Project { dot_codex_folder: AbsolutePathBuf }, SessionFlags, LegacyManagedConfigTomlFromFile { file: PathBuf }, LegacyManagedConfigTomlFromMdm, } ``` **资料来源**：[codex-rs/config/src/state.rs:50-80](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs) ### 6.2 配置需求协议 配置需求通过 `RequirementSource` 定义来源： ```rust pub enum RequirementSource { Unknown, MdmManagedPreferences { domain: String, key: String }, CloudRequirements, SystemRequirementsToml { file: PathBuf }, LegacyManagedConfigTomlFromFile { file: PathBuf }, LegacyManagedConfigTomlFromMdm, } ``` **资料来源**：[codex-rs/config/src/config_requirements.rs:1-30](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_requirements.rs) ### 6.3 配置层堆栈 ```mermaid graph LR A[System Config] --> B[User Config] B --> C[Project Config] C --> D[Session Flags] D --> E[MDM Config] style A fill:#eee,color:#000 style E fill:#f96,color:#000 ``` 配置层堆栈顺序定义： ```rust pub enum ConfigLayerStackOrdering { LowestPrecedenceFirst, HighestPrecedenceFirst, } pub struct ConfigLayerStack { /// 从最低优先级（基础）到最高优先级（顶层） layers: Vec, /// 用户配置层索引 user_layer_index: Option, } ``` **资料来源**：[codex-rs/config/src/state.rs:80-100](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs) ## 7. 审批协议 ### 7.1 审批决策来源 自动审查决策来源定义： ```rust enum AutoReviewDecisionSource { Agent, } ``` ### 7.2 审批选项配置 审批覆盖层支持的选项： | 选项标签 | 决策类型 | 说明 | |---------|---------|------| | `Yes, proceed` | `Accept` | 接受变更 | | `Yes, and don't ask again for these files` | `AcceptForSession` | 本会话内接受 | | `No, and tell Codex what to do differently` | `Reject` | 拒绝并反馈 | **资料来源**：[codex-rs/tui/src/bottom_pane/approval_overlay.rs:50-80](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/approval_overlay.rs) ### 7.3 文件系统路径协议 | 特殊路径 | 说明 | |---------|------| | `:root` | 项目根目录 | | `:minimal` | 最小访问范围 | | `:project_roots` | 所有项目根目录 | | `:tmpdir` | 系统临时目录 | | `/tmp` | 传统临时目录路径 | **资料来源**：[codex-rs/tui/src/bottom_pane/approval_overlay.rs:20-50](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/approval_overlay.rs) ## 8. 状态显示协议 ### 8.1 状态行项目 状态行支持显示以下信息项目： | 项目 | 示例值 | 说明 | |-----|-------|------| | `AppName` | Codex | 应用名称 | | `ProjectName` | my-project | 项目名称 | | `GitBranch` | feat/awesome-feature | Git 分支 | | `PullRequestNumber` | PR #123 | PR 编号 | | `BranchChanges` | +12 -3 | 分支变更统计 | | `ContextRemaining` | Context 0% left | 上下文剩余 | | `ContextUsed` | Context 0% used | 上下文使用量 | | `Model` | gpt-5.2-codex | 当前模型 | | `ModelWithReasoning` | gpt-5.2-codex medium | 模型及推理级别 | **资料来源**：[codex-rs/tui/src/bottom_pane/status_surface_preview.rs:20-50](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/status_surface_preview.rs) ### 8.2 状态项目分类 状态项目按语义分类： | 分类 | 对应项目 | 语法高亮作用域 | |-----|---------|--------------| | `Model` | 模型名称 | `entity.name.type` | | `Path` | 路径信息 | `string` | | `Branch` | 分支信息 | `entity.name.function` | | `State` | 运行状态 | `keyword.control` | | `Usage` | 使用量统计 | `constant.numeric` | | `Limit` | 限制信息 | `constant.language` | | `Mode` | 模式切换 | `storage.modifier` | | `Thread` | 线程标题 | `markup.heading` | | `Progress` | 任务进度 | `markup.inserted` | **资料来源**：[codex-rs/tui/src/bottom_pane/status_line_style.rs:30-60](https://github.com/openai/codex/blob/main/codex-rs/tui/src/bottom_pane/status_line_style.rs) ## 9. 序列化与类型安全 ### 9.1 JSON Schema 生成 协议类型通过 `schemars` 库自动生成 JSON Schema： ```rust #[derive(JsonSchema)] #[schemars(schema_with = "crate::schema::features_schema")] pub features: Option, ``` ### 9.2 TypeScript 类型导出 使用 `serde` 和 `ts` 属性导出 TypeScript 类型： ```rust #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)] #[serde(rename_all = "camelCase")] #[ts(export_to = "v2/")] pub struct AppInfo { ... } ``` ## 10. 总结 Codex 的协议层设计遵循以下原则： 1. **类型安全**：使用 Rust 强类型系统确保协议转换的正确性 2. **版本管理**：支持 V1 和 V2 协议版本共存 3. **分层设计**：清晰的协议层次结构，便于维护和扩展 4. **双向转换**：支持 `codex_app_server_protocol` 与 `codex_protocol` 之间的无缝转换 5. **可扩展性**：通过可选字段和枚举变体支持功能扩展 --- ## 核心Agent模块 ### 相关页面 相关主题：[系统架构](#page-architecture), [执行系统](#page-execution), [技能系统](#page-skills)
相关源码文件 以下源码文件用于生成本页说明： - [codex-rs/core/src/lib.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/lib.rs) - [codex-rs/core/src/agent/mod.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/agent/mod.rs) - [codex-rs/core/src/client.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/client.rs) - [codex-rs/core/src/session/mod.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/session/mod.rs) - [codex-rs/core/src/tools/mod.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/mod.rs) - [codex-rs/core/src/goals.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/goals.rs) - [codex-rs/core/src/context/environment_context.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/context/environment_context.rs) - [codex-rs/config/src/state.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/state.rs) - [codex-rs/config/src/profile_toml.rs](https://github.com/openai/codex/blob/main/codex-rs/config/src/profile_toml.rs) - [codex-rs/tui/src/slash_command.rs](https://github.com/openai/codex/blob/main/codex-rs/tui/src/slash_command.rs)
# 核心Agent模块 ## 概述 Codex CLI 的核心Agent模块是整个系统的中枢组件，负责协调用户交互、工具调用、上下文管理和会话生命周期。该模块采用 Rust 实现，运行于本地计算机，提供零依赖的安装体验。 资料来源：[codex-rs/README.md:1-15]() ## 模块架构 ### 核心组件关系 ```mermaid graph TD subgraph "核心层" A[Agent] --> B[Client] A --> C[Session] A --> D[Tools] end subgraph "上下文层" C --> E[EnvironmentContext] C --> F[Goals] end subgraph "配置层" G[Config] --> C G --> A end subgraph "UI层" H[TUI] --> A H --> C end ``` ### 核心模块职责 | 模块 | 职责 | 主要文件 | |------|------|----------| | Agent | 主控制逻辑、任务调度、决策 | `core/src/agent/mod.rs` | | Client | 与后端API通信、协议处理 | `core/src/client.rs` | | Session | 会话状态管理、历史记录 | `core/src/session/mod.rs` | | Tools | 工具注册、调用、结果处理 | `core/src/tools/mod.rs` | | Goals | 目标跟踪、预算管理 | `core/src/goals.rs` | 资料来源：[codex-rs/core/src/lib.rs]() ## Agent主模块 ### 主控制流程 Agent模块作为协调者，处理用户输入并生成响应： ```mermaid graph LR A[用户输入] --> B[解析命令] B --> C{命令类型} C -->|工具调用| D[工具选择] C -->|聊天| E[模型推理] D --> F[执行工具] E --> G[生成响应] F --> H[结果处理] H --> G G --> I[渲染输出] ``` ### 任务执行状态 Agent维护任务执行的状态机： ```mermaid stateDiagram-v2 [*] --> Idle: 初始化 Idle --> Running: 接收任务 Running --> WaitingApproval: 需要确认 WaitingApproval --> Running: 批准 WaitingApproval --> Cancelled: 拒绝 Running --> Paused: 暂停/恢复 Paused --> Running: 恢复 Running --> Completed: 任务完成 Completed --> Idle: [*] Cancelled --> Idle: [*] ``` 资料来源：[codex-rs/core/src/agent/mod.rs]() ## Client客户端模块 ### API通信机制 Client模块负责与OpenAI后端服务通信，采用Protocol Buffers定义的协议： ```rust // 风险级别映射 GuardianRiskLevel::Low GuardianRiskLevel::Medium GuardianRiskLevel::High GuardianRiskLevel::Critical ``` 资料来源：[codex-rs/tui/src/chatwidget.rs:1-30]() ### 请求/响应处理 Client支持多种API交互模式： | 模式 | 描述 | 用途 | |------|------|------| | 标准对话 | 同步请求-响应 | 日常交互 | | 流式响应 | Server-Sent Events | 实时输出 | | 工具调用 | Tool Use协议 | 代码执行 | ## Session会话管理 ### 会话生命周期 会话模块管理Codex的完整交互周期： ```mermaid graph TD A[创建会话] --> B[加载配置] B --> C[初始化环境] C --> D[处理消息] D --> E{任务状态} E -->|完成| F[保存会话] E -->|暂停| G[保存草稿] E -->|失败| H[记录错误] F --> I[会话结束] G --> J[可恢复] H --> I ``` ### 配置层级 会话使用分层配置系统，按优先级从低到高： | 层级 | 来源 | 覆盖方式 | |------|------|----------| | 系统配置 | `/etc/codex/config.toml` | 不可覆盖 | | 用户配置 | `~/.config/codex/config.toml` | 可覆盖 | | 项目配置 | `.codex/config.toml` | 可覆盖 | | 会话标志 | 命令行参数 | 最高优先级 | 资料来源：[codex-rs/config/src/state.rs:1-50]() ### 配置配置文件结构 ```toml [profile.default] model = "gpt-4o" include_apply_patch_tool = true include_permissions_instructions = true include_environment_context = true [profile.default.tui] session_picker_view = "grid" [profile.default.features] experimental_unified_exec = true ``` 资料来源：[codex-rs/config/src/profile_toml.rs:1-80]() ## Tools工具系统 ### 工具注册与调用 Tools模块提供Codex的扩展能力： | 工具类别 | 功能 | 配置项 | |----------|------|--------| | 文件操作 | 读取、写入、编辑文件 | `include_apply_patch_tool` | | 权限管理 | 访问控制、审批流程 | `include_permissions_instructions` | | 应用集成 | Apps指令 | `include_apps_instructions` | | 协作模式 | 多人协作 | `include_collaboration_mode_instructions` | 资料来源：[codex-rs/config/src/profile_toml.rs:50-70]() ### 工具执行流程 ```mermaid sequenceDiagram participant U as 用户 participant A as Agent participant T as Tools participant S as 沙箱 U->>A: 发送请求 A->>T: 选择工具 T->>S: 执行命令 S-->>T: 返回结果 T-->>A: 工具响应 A-->>U: 生成回复 ``` ## Goals目标系统 ### 目标跟踪机制 Goals模块管理长时间运行任务的进度和预算： ```rust // 预算限制提示模板 static BUDGET_LIMIT_PROMPT_TEMPLATE: LazyLock