在正式开始配置和使用之前，理解 Codex 的内部架构和组成部分至关重要。这不仅能帮助您更好地进行排障，还能让您在面对复杂开发任务时，知道如何分配不同的“角色”给 AI。

1. 核心交互层 (Interface)

Codex 提供了三种主要的交互方式，它们共用底层的逻辑，但适用于不同的场景：

  • Codex CLI (命令行界面)：最强大的入口，适合自动化脚本、持续集成以及习惯于终端操作的开发者。它支持直接在当前目录下执行复杂的工程指令。
  • Codex Desktop App (桌面客户端)：为不习惯终端的用户提供可视化界面。它集成了模型配置管理、对话历史和任务监控。
  • IDE Extensions (IDE 插件)：深度集成在 VS Code 等编辑器中，支持实时代码补全、行间解释以及基于当前光标位置的上下文注入。

2. 任务引擎 (Task Engine)

这是 Codex 的“心脏”，负责将您的自然语言指令转化为可执行的操作序列。

  • Context Management (上下文管理)：Codex 会自动扫描您的项目结构，识别 package.json、README.md 等关键文件，从而理解项目的技术栈和业务逻辑。
  • Action Planning (行动规划)：当您要求“修复登录 Bug”时，任务引擎会先规划出：读取登录接口文件 -> 查找错误逻辑 -> 尝试修改 -> 运行测试的步骤。
  • Tool Calling (工具调用)：Codex 可以调用本地系统的工具，如 ls、grep、npm test、git status 等，这是它与普通聊天 AI 的本质区别。

3. 模型与提供商 (Models & Providers)

Codex 本身不产生智能，它通过 API 连接到大语言模型（LLM）。

  • Native Provider (原生提供商)：默认连接到 OpenAI 的 Codex 特化模型。注意：原生 Provider 仅支持 Responses API。
  • Custom Provider (自定义提供商)：允许接入 DeepSeek、通义千问、Kimi 等国内模型。
  • API 协议区别：
  • Responses API：支持更复杂的多步任务规划和工具调用，是 Codex 原生设计的基石。
  • Chat Completions API：主流的对话接口。严禁将仅支持此协议的 Base URL 直接写入 Codex 原生 Provider 配置，否则会导致工具调用失效或报错。

4. 配置文件与元数据 (Config & Metadata)

  • config.toml：全局配置文件，存储您的 API Key、默认模型选择、网络代理设置等。
  • AGENTS.md：项目级规范文件。您可以为每个项目定制 AI 的“工作守则”，例如：“禁止修改 /dist 目录”、“所有 UI 修改必须符合 Tailwind 规范”。
  • .codex 缓存目录：存储临时的上下文索引和任务历史，帮助 AI 在长会话中保持记忆。

5. 安全沙箱 (Security Sandbox)

为了保护您的代码安全，Codex 引入了多重保护机制：

  • Read-only Mode (只读模式)：建议在第一次阅读陌生项目时开启，防止 AI 产生非预期的文件修改。
  • Manual Approval (人工审批)：对于写操作（修改文件、提交 Git）、执行危险系统指令，Codex 默认会要求用户点击“确认”。
  • Security Checklist：在使用第三方工具或配置新模型前，请务必执行全站建议的安全自查。

---

下一步：环境搭建总览 —— 开始在您的本地或云端配置 Codex 运行环境。