[AI Agent/应用] OpenAI Codex 概述

0 序

  • 先看当前全球范围内的 AI Agent 趋势

[数据/AI] AI Agent产品趋势观察 - 博客园/数据知音

image

Hermes（开源产品，成熟度不如商业产品） > Codex（商业产品） > Claude Code > Cursor（不支持第三方模型） > Trae（国内Top1） > OpenClaw（建议弃用，软件成熟度已日渐落后） (2026.8.6)

[AI应用] OpenClaw(龙虾) 概述 - 博客园/数据知音

1 概述：OpenAI Codex

产品介绍

  • OpenAI Codex 是由 OpenAI 研发的下一代自主编程 Agent（Autonomous AI Coding Agent）与代码智能引擎。

其早期版本于 2021 年作为 GPT-3 的衍生代码补全模型面世，并曾作为 GitHub Copilot 的核心驱动引擎。
经过数代迭代，现代的 Codex 已演变为一套涵盖模型引擎（如 codex-1、gpt-5.2-codex）、云端隔离沙盒（Cloud Sandbox）、命令行工具（Codex CLI）以及基于 MCP（Model Context Protocol）的插件与技能（Skills）体系的【完整智能软件工程平台】。

image

https://developers.openai.ac.cn/codex

诞生背景与原因

  • 诞生背景与原因：传统代码补全工具（Autocomplete）仅能提供行级或函数级的短上下文生成，难以解决复杂系统的架构重构、长时多步骤 Bug 修复及跨文件工程搭建。随着大语言模型推理与 Agent 工具调用能力的飞跃，需要一个能够自主阅读全仓库上下文、安全运行代码、自我测试与审查的协同开发者。

  • 解决的核心问题：

    • 研发上下文断层与低效协同：解决开发者频繁拷贝代码、提示词上下文受限的问题。
    • 长耗时复杂任务执行：通过规划文件（ExecPlans）实现长达数小时的不间断复杂工程调度与实现。
    • 代码交付质量保障：在独立隔离沙盒中运行真实构建与测试，避免“幻觉代码”直接入库。

发展历程

OpenAI Codex 的演进路线体现了从“代码补全模型”向“自主编程 Agent”的范式转移：

  • 2021年6月 - 早期发布：OpenAI 推出基于 GPT-3 架构的【初始 Codex 模型】（120亿参数，基于 5400万 GitHub 仓库训练），并作为 GitHub Copilot 早期版本的核心引擎。
  • 2021年8月 - API 开放与评估：发布经典论文《Evaluating Large Language Models Trained on Code》（推出 HumanEval 基准测试），公开 API 供全球开发者测试代码生成与自动程序修复（APR）。
  • 2023年3月 - 服务重构：OpenAI 宣布停用早期的独立 Codex API，将代码能力全面融入 GPT-3.5-Turbo 及 GPT-4 等通用旗舰模型中。
  • 2025年10月 - ExecPlans 与 Agent 化：开发者平台引入基于 PLANS.md 的复杂任务长时规划能力，使 AI Agent 能够持续独立工作数小时。
  • 2026年 - 现代 Codex 架构面世：发布专为编码 Agent 优化的推理模型（codex-1 / gpt-5.2-codex），集成云端沙盒、MCP 协议支持以及 CLI 终端接口，形成全闭环的【软件工程协同工具链】。

核心功能

  • 自主任务规划与长时执行（ExecPlans）：

    • 支持通过配置 AGENTS.md 与 PLANS.md 引导 Codex 制定详尽设计规划。
    • 能够针对大型重构或新功能开发，连续自主工作数小时而不丢失目标上下文。

  • 云端隔离沙盒（Cloud Sandbox Environment）：

    • 在完全隔离的云端容器中自动克隆仓库、搭建依赖环境并执行构建脚本。
    • 允许 Agent 运行真实单元测试、集成测试与代码检查器（Linters），捕获报错并自动修复。

  • 全仓库级上下文推理（Repo-level Reasoning）：

    • 具备跨文件代码理解能力，能够精准定位涉及多个模块的变更范围。
    • 结合代码库自读性（Harness Engineering），从源码与架构设计直接推导业务逻辑。

  • 自动化 Pull Request（PR）异步提交与 Review 循环：

    • 支持接收 GitHub Issue 或需求描述后，在后台异步完成工作、创建分支并提交 PR。
    • 能够响应人类开发者或自动化 Review Agent 的反馈，并自动迭代修复直至测试通过]。

  • 基于 MCP 与 Skill 的扩展生态：

    • 原生支持 Model Context Protocol (MCP) 协议，无缝接入各类外部数据源与 API 服务的工具扩展。
    • 允许通过结构化的 SKILL.md 声明式定义业务流程与代码规范（如 iOS SwiftUI、Figma 设计转代码等）。

主要特点

  • Agent-First 架构设计：打破传统的“对话式 AI”边界，聚焦于异步解耦、任务导向、沙盒化运行的完整工单履约。
  • Ralph Wiggum 循环自我审查：内置自闭环的 Review 机制，在本地与云端发起自我检查与测试，循环迭代直至达到交付标准。
  • 标准化的 MCP 与 Skills 生态：将数据/工具层（MCP Server）与业务工作流/规范层（Skills）解耦，便于企业自定义工程规范。
  • 本地与云端双模协同：通过网页端/ChatGPT 订阅提供云端后台异步处理，同时提供 Codex CLI 满足本地终端下的快速协同。

同类竞品

  • Claude Code (Anthropic)：主打终端命令行交互与实时对话推理，本地工具调用能力强；而 Codex 则侧重于云端异步沙盒 + PR 驱动的工程交付。
  • GitHub Copilot / Copilot Workspace：微软与 GitHub 旗下的 AI 编程助手，擅长编辑器内行间补全与 IDE 深度集成。
  • Cursor / Windsurf：专注于 AI 原生 IDE 体验的代码辅助工具。
  • Devin (Cognition)：自主 AI 软件工程师 Agent，具备完整的全栈自主开发流程。

发展趋势

  • 开源社区活跃趋势：围绕 Codex 扩展体系的官方仓库 openai/plugins 在 GitHub 上已获得 5.0k+ Stars 与 670+ Forks，社区开发者持续贡献包括 Figma、Notion、iOS、Web 开发在内的标准 Skill 与 MCP 插件。
  • 生态演进趋势：正逐步从单纯的 LLM 代码生成模型，向“标准化工具协议（MCP） + 规范化流程指引（Skills） + 自主任务引擎（Codex Agent）”的三层智能软件工程基础设施演进。
  • 总结：OpenAI Codex 正在重新定义软件工程范式，将 AI 从“【输入提示词补全代码的辅助工具】”提升为“【可独立承担工单、自主规划与交付 PR 的数字工程师】”。

2 架构原理篇

概念术语

  • codex-1 / gpt-5.2-codex：专为深度代码推理、多步骤逻辑计算与代码语法树（AST）理解而微调的专属模型体系。
  • ExecPlan (PLANS.md)：用于指导 AI Agent 完成长耗时、高复杂任务的可演进设计文档，确保 Agent 在数小时的执行过程中保持上下文一致性。
  • Skill (SKILL.md)：一种包含特定工作流指令、参考规范与脚本的文件夹结构，教导 Agent 在特定业务场景下使用工具的标准化 SOP。
  • MCP Server (Model Context Protocol)：提供实时数据获取、身份验证与受控操作的通用上下文协议服务器。
  • Cloud Sandbox：隔离的云端容器环境，包含 Git 仓库副本、语言运行时与构建工具，确保代码在安全受控的环境中编译测试。
  • Ralph Wiggum Loop：一种自主闭环审查机制，Agent 在执行完修改后自动在本地/云端发起自检、请求多 Agent 审查并迭代修复直至满意。

架构与运行原理

  • Codex 的整体架构由交互触发层、任务调度与 Agent 引擎、云端隔离沙盒、MCP/Skills 扩展层以及 Git 服务集成层组成：
flowchart TD subgraph "1 交互与触发层 (Client & Entry)" A1["ChatGPT Web / Pro / Team"] A2["Codex CLI 本地终端"] A3["GitHub Webhook / Issue"s] end subgraph "2 Codex Agent 核心引擎" B1["Task Manager & Orchestrator"] B2["Reasoning Engine: codex-1 / gpt-5.2-codex"] B3["ExecPlan Engine: PLANS.md"] end subgraph "3 云端隔离沙盒 (Cloud Sandbox)" C1["Git Clone & Context Loader"] C2["Execution Sandbox: Bash / Linter / Tests"] C3["Ralph Wiggum Self-Review Loop"] end subgraph "4 扩展与能力层 (MCP & Skills)" D1["Skills Framework: SKILL.md"] D2["MCP Servers: Figma, DB, Private APIs"] end subgraph "5 交付产出层 (Output)" E1["Git Branch & Commits"] E2["GitHub Pull Request"] end A1 --> B1 A2 --> B1 A3 --> B1 B1 <--> B2 B2 <--> B3 B1 --> C1 C1 --> C2 C2 <--> C3 B2 <--> D1 D1 <--> D2 C3 --> E1 E1 --> E2
  • 核心运行流程拆解：
  1. 任务接收与上下文加载：
    • 开发者通过 GitHub Issue、ChatGPT 界面或 Codex CLI 提交任务需求 [cite: 1.1.3]。
    • Codex 检索仓库内部结构，加载 AGENTS.md 与可能存在的 PLANS.md [cite: 1.1.4]。
  2. 计划制定（ExecPlan Phase）：
    • 如果是复杂任务，Codex 在 PLANS.md 中编写长时执行计划，明确设计方案、待修改模块及测试策略 [cite: 1.1.4]。
  3. 沙盒构建与自动化编码：
    • 云端沙盒自动搭建对应的 Node.js/Python/Go/Rust 环境，配置依赖 [cite: 1.1.3]。
    • Codex 按照规划跨文件执行代码修改，并调用终端命令（如 npm test、pytest、cargo check）进行构建验证 [cite: 1.1.3]。
  4. Ralph Wiggum 循环迭代自检：
    • 当构建或单测出现 Failure 时，错误信息重新输入模型 [cite: 1.1.3]。
    • Agent 分析报错堆栈、进行针对性调整，直至所有自动化测试与审查通过 [cite: 1.1.2, 1.1.3]。
  5. PR 提交与外部审查响应：
    • 任务完成后，Codex 自动将改动推送到新分支并开启 Pull Request [cite: 1.1.3]。
    • 若后续收到人类审查意见，Agent 可重新激活并在线修正 [cite: 1.1.2]。

3 部署使用篇

3.1 安装部署

  • Codex的软件形态
  • Codex 桌面应用
  • Codex CLI
  • Codex 插件: VSCode / Cursor / ...

Codex 桌面应用

CASE Codex Desktop 借助 CC-Switch 接入第三方大模型(硅基流动/DeekSeek)

  • 想要可视化、对话式的工作流程，可以使用Codex桌面应用程序：
codex app

https://chatgpt.com/codex | https://chatgpt.com/zh-Hans-CN/codex/

  • 桌面应用提供：
  • 基于聊天窗口的自然语言描述任务的界面
  • 一个文件浏览器，显示Codex计划修改的文件
  • 一键批准或拒绝拟议变更
  • 会话历史，方便你回顾过去的任务

该应用可在macOS和Windows上使用。如果你还没安装，可以从OpenAI Codex产品页面下载。

Codex CLI

  • npm （全平台）的安装方式
npm install -g @openai/codex
codex --version

此方式在macOS、Linux和Windows上都有效

image

查看命令帮助

$ codex --help
Codex CLI

If no subcommand is specified, options will be forwarded to the interactive CLI.

Usage: codex [OPTIONS] [PROMPT]
       codex [OPTIONS] <COMMAND> [ARGS]

Commands:
  exec            Run Codex non-interactively [aliases: e]
  review          Run a code review non-interactively
  login           Manage login
  logout          Remove stored authentication credentials
  mcp             Manage external MCP servers for Codex
  plugin          Manage Codex plugins
  mcp-server      Start Codex as an MCP server (stdio)
  app-server      [experimental] Run the app server or related tooling
  remote-control  [experimental] Manage the app-server daemon with remote control enabled
  app             Launch the Desktop app (opens the app installer if missing)
  completion      Generate shell completion scripts
  update          Update Codex to the latest version
  doctor          Diagnose local Codex installation, config, auth, and runtime health
  sandbox         Run commands within a Codex-provided sandbox
  debug           Debugging tools
  apply           Apply the latest diff produced by Codex agent as a `git apply` to your local
                  working tree [aliases: a]
  resume          Resume a previous interactive session (picker by default; use --last to continue
                  the most recent)
  archive         Archive a saved session by id or session name
  delete          Permanently delete a saved session by id or session name
  unarchive       Unarchive a saved session by id or session name
  fork            Fork a previous interactive session (picker by default; use --last to fork the
                  most recent)
  cloud           [EXPERIMENTAL] Browse tasks from Codex Cloud and apply changes locally
  exec-server     [EXPERIMENTAL] Run the standalone exec-server service
  features        Inspect feature flags
  help            Print this message or the help of the given subcommand(s)

Arguments:
  [PROMPT]
          Optional user prompt to start the session

Options:
  -c, --config <key=value>
          Override a configuration value that would otherwise be loaded from `~/.codex/config.toml`.
          Use a dotted path (`foo.bar.baz`) to override nested values. The `value` portion is parsed
          as TOML. If it fails to parse as TOML, the raw string is used as a literal.

          Examples: - `-c model="o3"` - `-c 'sandbox_permissions=["disk-full-read-access"]'` - `-c
          shell_environment_policy.inherit=all`

      --enable <FEATURE>
          Enable a feature (repeatable). Equivalent to `-c features.<name>=true`

      --disable <FEATURE>
          Disable a feature (repeatable). Equivalent to `-c features.<name>=false`

      --remote <ADDR>
          Connect the TUI to a remote app server endpoint.

          Accepted forms: `ws://host:port`, `wss://host:port`, `unix://`, or `unix://PATH`.

      --remote-auth-token-env <ENV_VAR>
          Name of the environment variable containing the bearer token to send to a remote app
          server websocket

      --strict-config
          Error out when config.toml contains fields that are not recognized by this version of
          Codex

  -i, --image <FILE>...
          Optional image(s) to attach to the initial prompt

  -m, --model <MODEL>
          Model the agent should use

      --oss
          Use open-source provider

      --local-provider <OSS_PROVIDER>
          Specify which local provider to use (lmstudio or ollama). If not specified with --oss,
          will use config default or show selection

  -p, --profile <CONFIG_PROFILE_V2>
          Layer $CODEX_HOME/<name>.config.toml on top of the base user config

  -s, --sandbox <SANDBOX_MODE>
          Select the sandbox policy to use when executing model-generated shell commands

          [possible values: read-only, workspace-write, danger-full-access]

      --approve-for-me
          Route approval requests through automatic review using the workspace-write sandbox

      --dangerously-bypass-approvals-and-sandbox
          Skip all confirmation prompts and execute commands without sandboxing. EXTREMELY
          DANGEROUS. Intended solely for running in environments that are externally sandboxed

      --dangerously-bypass-hook-trust
          Run enabled hooks without requiring persisted hook trust for this invocation. DANGEROUS.
          Intended only for automation that already vets hook sources

  -C, --cd <DIR>
          Tell the agent to use the specified directory as its working root

      --add-dir <DIR>
          Additional directories that should be writable alongside the primary workspace

  -a, --ask-for-approval <APPROVAL_POLICY>
          Configure when the model requires human approval before executing a command

          Possible values:
          - untrusted:  Only run "trusted" commands (e.g. ls, cat, sed) without asking for user
            approval. Will escalate to the user if the model proposes a command that is not in the
            "trusted" set
          - on-request: The model decides when to ask the user for approval
          - never:      Never ask for user approval Execution failures are immediately returned to
            the model

      --search
          Enable live web search. When enabled, the native Responses `web_search` tool is available
          to the model (no per鈥慶all approval)

      --no-alt-screen
          Disable alternate screen mode

          Runs the TUI in inline mode, preserving terminal scrollback history.

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version
  • GitHub Release 的安装方式

直接从 OpenAI Codex 的 GitHub 仓库发布页面下载最新的二进制文件。这非常适合CI环境或没有 Node.js 的机器：

  • 请访问Codex GitHub发布页面。
  • 下载针对你操作系统和架构的归档。
  • 提取二进制并添加到你的PATH中。

提示：GitHub 版本包含无运行时依赖的独立二进制文件，使其成为 Docker 容器或最小化服务器安装的最佳选择

IDE 插件: VS Code

Codex 通过官方扩展直接集成到流行的IDE/代码编辑器中。

  • VS Code 插件
  • 用 VS Code 打开扩展市场（Ctrl+Shift+X 或 Cmd+Shift+X）。
  • 搜索 OpenAI Codex。
  • 点击安装。
  • 在提示时进行身份验证——该扩展使用相同的ChatGPT或API密钥凭证。

IDE 插件: Cursor

  • 打开 Cursor 设置。
  • 进入扩展面板。
  • 搜索 OpenAI Codex 并安装。

Codex 命令会出现在命令面板中（Ctrl+Shift+P）。

查验版本

  • 方式1: 查看~/version.json
{"latest_version":"0.147.0","last_checked_at":"2026-08-10T12:21:31.731717Z","dismissed_version":null}
  • 方式2: 界面操作: 帮助-关于

image

3.2 登录/认证

可以通过 ChatGPT 账号 或 Api Key 进行认证，略讲。

//chatgpt 账号登录 到 codex cli
codex auth login

//使用预付费使用OpenAI API密钥 到 codex cli
codex auth login --api-key
(或 设置OPENAI_API_KEY环境变量：export OPENAI_API_KEY="sk-..." ，将这行添加到你的shell配置文件（~/.bashrc，~/.zshrc），以便在会话间持久保存)

//查看身份验证状态 (这会确认你的活跃账户类型和会话有效性)
codex auth status

如果是 CC-Switch 代理了，则账号信息由其创建了一个假帐号，如: siliconflow。

3.3 关键配置

目录讲解: C:\Users\用户\.codex

  • 核心配置目录: C:\Users\用户\.codex

这是 OpenAI Codex Desktop/CLI（或基于它的衍生项目，如 codex-mini、codex-local 等）的【本地运行时数据目录】
这个目录通常位于 ~/.codex（macOS/Linux）或 %USERPROFILE%\.codex（Windows，你当前的环境）。
Codex 目录 = 配置 + 会话 + 沙箱 + 插件 + 日志 + 记忆

$ ls -la
total 40755
drwxr-xr-x 1 XxxUser 197121        0 8月   8 18:12 ./
drwxr-xr-x 1 XxxUser 197121        0 8月   7 16:18 ../
-rw-r--r-- 1 XxxUser 197121    13644 8月   8 18:12 .codex-global-state.json
-rw-r--r-- 1 XxxUser 197121    13644 8月   8 18:12 .codex-global-state.json.bak
drwxr-xr-x 1 XxxUser 197121        0 8月   7 18:44 .sandbox/
-rw-r--r-- 1 XxxUser 197121        3 8月   4 14:08 .sandbox_migration
drwxr-xr-x 1 XxxUser 197121        0 8月   7 01:39 .sandbox-bin/
drwxr-xr-x 1 XxxUser 197121        0 8月   4 14:10 .sandbox-secrets/
drwxr-xr-x 1 XxxUser 197121        0 8月   6 20:30 .tmp/
-rw-r--r-- 1 XxxUser 197121        0 8月   4 14:09 AGENTS.md
-rw-r--r-- 1 XxxUser 197121       77 8月   7 01:17 auth.json
drwxr-xr-x 1 XxxUser 197121        0 8月   7 02:00 browser/
-rw-r--r-- 1 XxxUser 197121     1634 8月   7 02:36 cap_sid
-rw-r--r-- 1 XxxUser 197121   234056 8月   8 00:38 cc-switch-model-catalog.json
drwxr-xr-x 1 XxxUser 197121        0 8月   8 00:44 computer-use/
-rw-r--r-- 1 XxxUser 197121     3524 8月   8 17:57 config.toml
drwxr-xr-x 1 XxxUser 197121        0 8月   6 20:34 dictation-history/
-rw-r--r-- 1 XxxUser 197121    32768 8月   8 01:03 goals_1.sqlite
-rw-r--r-- 1 XxxUser 197121    32768 8月   8 17:56 goals_1.sqlite-shm
-rw-r--r-- 1 XxxUser 197121     4152 8月   8 17:56 goals_1.sqlite-wal
-rw-r--r-- 1 XxxUser 197121       36 8月   3 20:33 installation_id
-rw-r--r-- 1 XxxUser 197121 36700160 8月   8 18:13 logs_2.sqlite
-rw-r--r-- 1 XxxUser 197121    32768 8月   8 17:56 logs_2.sqlite-shm
-rw-r--r-- 1 XxxUser 197121  4202432 8月   8 18:13 logs_2.sqlite-wal
-rw-r--r-- 1 XxxUser 197121    40960 8月   8 18:06 memories_1.sqlite
drwxr-xr-x 1 XxxUser 197121        0 8月   7 01:57 node_repl/
drwxr-xr-x 1 XxxUser 197121        0 8月   4 14:09 pets/
drwxr-xr-x 1 XxxUser 197121        0 8月   8 17:57 plugins/
-rw-r--r-- 1 XxxUser 197121     1103 8月   7 02:36 session_index.jsonl
drwxr-xr-x 1 XxxUser 197121        0 8月   4 14:08 sessions/
drwxr-xr-x 1 XxxUser 197121        0 8月   8 17:56 skills/
drwxr-xr-x 1 XxxUser 197121        0 8月   8 17:55 sqlite/
-rw-r--r-- 1 XxxUser 197121   184320 8月   8 01:03 state_5.sqlite
-rw-r--r-- 1 XxxUser 197121    32768 8月   8 17:56 state_5.sqlite-shm
-rw-r--r-- 1 XxxUser 197121    53592 8月   8 17:56 state_5.sqlite-wal
drwxr-xr-x 1 XxxUser 197121        0 8月   7 02:45 thread-writer-locks/
drwxr-xr-x 1 XxxUser 197121        0 8月   3 20:33 tmp/
-rw-r--r-- 1 XxxUser 197121        0 8月   8 17:59 transcription-history.jsonl
drwxr-xr-x 1 XxxUser 197121        0 8月   3 20:33 vendor_imports/
drwxr-xr-x 1 XxxUser 197121        0 8月   6 20:34 visualizations/

全局状态与配置 *

文件 / 目录 作用
.codex-global-state.json 全局状态文件。记录 Codex 的全局配置、上次使用的模型、UI 状态、功能开关等。
.codex-global-state.json.bak 上一次状态的备份文件，用于崩溃恢复。
config.toml 用户主配置文件。包含模型选择、API Key、插件开关、沙箱策略等。
auth.json 认证信息（OAuth Token / Session Token）。
installation_id 本机唯一安装 ID，用于遥测或许可校验。
AGENTS.md Agent 行为说明或提示词模板（部分分支版本使用）。

建议重点备份：config.toml、auth.json、AGENTS.md

  • AGENTS.md
  • 对应桌面版菜单路径：【设置-个性化-自定义指令】

image

  • config.toml

经 CC-Switch 代理的第三方模型(硅基流动)的配置效果：

model_provider = "custom"
model = "deepseek-ai/DeepSeek-V4-Flash"
model_catalog_json = "cc-switch-model-catalog.json"
model_reasoning_effort = "high"
disable_response_storage = true

notify = [ "C:\\Users\\XxxUser\\AppData\\Local\\OpenAI\\Codex\\runtimes\\cua_node\\f1bf3cd3a5929acd\\bin\\node_modules\\@oai\\sky\\bin\\windows\\codex-computer-use.exe", "turn-ended" ]

[model_providers.custom]
name = "siliconflow"
base_url = "http://127.0.0.1:15721/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "PROXY_MANAGED"

...
  • 关键配置字段
场地 类型 默认 描述
model String o4-mini 默认型号标识符
sandbox String workspace-write 沙盒关卡
ask_for_approval String untrusted 批准政策
api_key_env String OPENAI_API_KEY 持有API密钥的环境变量
add_dir List [] 可访问的额外目录
search Boolean false 启用网页搜索
oss Boolean false 开源模式

会话与历史记录（核心）

文件 / 目录 作用
sessions/ 所有对话会话目录。每个子目录是一个独立会话（含消息、上下文、文件变更）。
session_index.jsonl 会话索引（JSONL），用于 UI 中列出历史会话。
logs_2.sqlite* 主日志数据库。记录命令执行、Agent 决策、错误日志。
goals_1.sqlite* Goal / Task 管理数据库（Codex 的“目标驱动模式”）。
state_5.sqlite* 运行时状态数据库。保存当前任务栈、上下文窗口、内存快照。
memories_1.sqlite Agent 长期记忆（部分版本启用 Memory 功能）。

删除会导致历史丢失，但不会影响程序运行。

沙箱与安全隔离（非常重要）

文件 / 目录 作用
.sandbox/ 主沙箱根目录。Codex 执行代码、运行 shell、修改文件时的隔离环境。
.sandbox-bin/ 沙箱内可用的二进制工具（裁剪版 bash、python 等）。
.sandbox-secrets/ 注入到沙箱内的临时密钥（不会泄露到宿主机）。
.sandbox_migration 沙箱版本迁移标记文件。
thread-writer-locks/ 多线程写入锁（防止 SQLite 并发损坏）。

安全相关：沙箱是 Codex 能“安全跑代码”的关键，不要随意修改。

插件与扩展系统

文件 / 目录 作用
plugins/ 已加载的插件（JS/TS/WASM 插件）。
skills/ Agent “技能包”（prompt + tool 的组合定义）。
vendor_imports/ 第三方依赖或 vendoring 的代码。

工具集成（Browser / Computer Use）

文件 / 目录 作用
browser/ 浏览器自动化数据（Playwright / CDP 会话）。
computer-use/ 计算机控制功能（鼠标、键盘、截图等）。
cc-switch-model-catalog.json 模型切换时的模型目录缓存。
cap_sid 屏幕捕获 Session ID（用于 GUI 自动化）。

语音与转录（新功能）

文件 / 目录 作用
dictation-history/ 语音输入的音频缓存。
transcription-history.jsonl Whisper 转录历史（JSONL）。

临时与缓存目录（可安全清理）

文件 / 目录 作用
.tmp/ 通用临时文件。
tmp/ 旧版临时目录。
sqlite/ SQLite 辅助文件或中间缓存。
node_repl/ Node.js REPL 会话缓存。
visualizations/ 图表 / 可视化结果缓存。
pets/ 彩蛋或实验性功能（如“宠物进程”）。
  • 可以定期清理：
rm -rf .tmp tmp sqlite node_repl visualizations pets

SQLite 数据库文件说明（常见后缀）

后缀 含义
.sqlite 主数据库
.sqlite-wal Write-Ahead Log（运行中产生）
.sqlite-shm 共享内存文件
-wal / -shm 不可单独删除，需随主库一起处理

目录讲解: C:\Users\用户\.agents\ = Codex 编码智能体的个人工作区

  • C:\Users\用户\.agents\ : Codex 编码智能体的个人工作区
C:\Users\用户\.agents\
    skills\
    plugins\

目录讲解: C:\Users\用户\Documents\Codex\ = Codex 当前用户的默认项目空间

  • C:\Users\<user>\Documents\Codex\ = Codex 当前用户的默认项目空间

当然，也可单独新建 Codex 项目空间。

  Codex/
  ├── .agents/                       # 根级工程指南（用户自己定义的全局项目级 AGENTS.md）
  │   ├── AGENTS.md          (2967 B)
  │   └── test.txt           (9 B)
  ├── 2026-08-04/                    # 日期会话工作区 — 内部只含一个子目录 er/
  ├── 2026-08-06/                    # 日期会话工作区 — 内部只含 he-l/
  ├── 2026-08-07/                    # 日期会话工作区（内容最多）
  │   ├── ai/
  │   ├── ...
  └── .../                           # 实际项目目录
  └── flink-realtime-etl/            # 实际项目目录
      └── .agents/
          └── AGENTS.md      (9593 B) # 项目级工程指南

C:\Users\用户\Documents\Codex\、C:\Users\用户\.codex\、C:\Users\用户\.agent\ 的区别？

  • 3个目录的定位完全不同，按层级梳理如下：

1. C:\Users<user>\Documents\Codex\ — 用户的工作空间与项目工作区

  • 用户的工作空间。存放：
  • 实际项目代码（如 flink-realtime-etl/）
  • 与 Codex 对话产生的会话产物（按日期组织的目录，如 2026-08-11/）
  • 全局项目级 .agents/AGENTS.md（工程规范指南）
  • 性质：用户自主管理的项目根目录，Codex 在这里执行代码操作。

2. C:\Users<user>.codex\ — Codex 工具自身安装目录（$CODEX_HOME）

  • Codex 应用的内部 home 目录，存放工具自身运行时所需的：
  • 内置技能（skills）
  • 依赖的工具链
  • 核心配置
  • 性质：Codex 工具的内部基础设施目录，用户一般不直接触碰。由 $CODEX_HOME 环境变量定位。

3. C:\Users<user>.agents\ — 用户级 Agent 配置目录

  • 存放用户个人化扩展：
  • 自定义技能（skills/）
  • 自定义插件（plugins/）
  • 插件市场配置（marketplace.json）
  • 性质：用户在 Codex 之上安装的个人扩展和能力集合。Codex 启动时会加载此目录中的技能和插件来扩展自身能力。

另外：.agent/（单数）— 项目级规划目录

  • 这是 AGENTS.md 中提到的 ExecPlan 目录（注意是单数 .agent/ 而非复数 .agents/），位于项目内部。用于存放 PLANS.md，在复杂功能开发或重大重构时记录设计到实现的执行计划。

总结

目录                  角色                   谁管理
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Documents/Codex/      我的项目工作区          用户
────────────────────  ─────────────────────  ─────────────────────
~/.codex/             Codex 工具本体          Codex 自己
────────────────────  ─────────────────────  ─────────────────────
~/.agents/            我的 Agent 扩展         用户安装的技能/插件
────────────────────  ─────────────────────  ─────────────────────
.agent/ (在项目内)     执行计划 (ExecPlan)     开发过程中使用

3.4 Codex 的自定义指令体系(AGENTS.md)

推荐文献

  • AGENTS.md 是 Codex 的自定义指令文件，允许你为 Codex 设置全局指导和工作流规范。

AGENTS.md = 为 AI Agent 提供项目的 "上下文" * （必读）

位置： C:\Users\Johnny\.codex\AGENTS.md
Prompt 即 提示词 即 指令

image

  • AGENTS.md 是什么？
  • AGENTS.md 是 Codex 的【自定义指令文件】——在不修改源代码的情况下引导 AI 编码代理行为的主要机制。

可以把它想象成一个【项目级系统提示】，Codex 每次会话开始时【自动读取】它。与在聊天中输入的临时指令不同，【AGENTS.md】 会【跨会话】持续存在，存在于你的仓库中，并且可以与代码一同进行版本控制。

  • AGENTS.md 的作用是给 AI 编程助手（Agent）提供这个项目的“上下文”——比如技术栈、目录结构、命令规范、代码风格、业务背景等，让 Agent 在进入项目时能快速“读懂”这个项目，而不是从零开始猜。

类似的文件还有 CLAUDE.md（Claude 用）、.github/copilot-instructions.md（GitHub Copilot 用）、AGENTS.md 等，思路都一样：给 AI 看的项目说明书。
项目根目录下的一个"给 AI 看的 README"，用来承载这个项目的上下文信息。

  • 每次Codex会话开始时，都会发现并加载一个或多个 AGENTS.md 文件。这些文件告诉Codex如何导航你的代码库，遵循哪些惯例，偏好哪些工具，避免哪些，以及如何处理边缘情况。

精心设计的 AGENTS.md 将Codex从一个通用的编码助手转变为一个领域专门的协作者，了解你的项目架构和规则。

发现层级：Codex 如何找到你的 Prompt/提示词?

  • Codex 通过【多层发现系统】加载【自定义指令】，并有明确的优先规则。理解这一层级结构至关重要，因为它决定了冲突发生时哪些指令胜出。

第1层：全局指令（~/.codex/AGENTS.md）

  • 全局文件位于~/.codex/AGENTS.md（或$CODEX_HOME/AGENTS.md 如果CODEX_HOME环境变量已设置）。这个文件适用于你机器上的每一个Codex会话，无论你正在做哪个项目。它非常适合涵盖所有项目的个人偏好：偏好的编码风格、文档习惯、测试惯例以及通用的最佳实践。

  • 全局文件的示例用例：

  • “实现功能前一定要写测试。”
  • “更喜欢功能性组件而非类组件。”
  • “在所有导出函数上包含JSDoc注释。”
  • 你可以通过设置来覆盖全局主目录CODEX_HOME任何道路。Codex 将寻找AGENTS.md在该目录内，而不是~/.codex/.

第2层：Project Root Walk（项目级根部漫步）

  • Codex 从项目根目录向下移动到当前工作目录，在每个层级收集 AGENTS.md 文件。如果你的仓库有以下结构：
/~/projects/myapp/AGENTS.md          (project root)
/~/projects/myapp/src/AGENTS.md      (src subtree)
/~/projects/myapp/src/api/AGENTS.md  (API subtree)
  • 你会从这里运行Codex /~/projects/myapp/src/api/ 它会按顺序加载三个文件：先root，然后是src，最后是api。后期文件会覆盖之前的文件，以解决指令冲突，意味着最具体（最接近CWD）的文件获胜。这让你可以在项目根节点设置大致惯例，并在子目录中进行细化。

第3层：覆盖文件（AGENTS.override.md）

  • 在任何目录层级，如果Codex找到一个名为 AGENTS.override.md，它绝对优先于在同一目录中的AGENTS.md。

这是刻意为之逃脱 舱口对于需要完全替换（而不仅仅是修改）某个层级说明的情况。

  • AGENTS.override.md的适用场景：
  • 子目录与项目其他部分有根本不同的惯例。
  • 你正在尝试替代说明，想要一个干净的起点。
  • 自动化流水线注入的指令应取代手写指令。
  • 覆盖文件不会取消父目录的文件——它只替换AGENTS.md在它自己的层面上。

通过配置实现备份文件名

  • Codex 还支持通过 project_doc_fallback_filenames 在你的config.toml.该数组告诉Codex如果找不到其他文件名 AGENTS.md 就要寻找。常见的后备方案包括：
[project]
project_doc_fallback_filenames = [".cursorrules", ".claude", "CONVENTIONS.md"]

这对从其他AI编码工具迁移过来、已经有指令文件的团队非常有用。
Codex 会按顺序检查每个备用文件名，并使用它找到的第一个。
注意，只有在该目录层面缺少 AGENTS.md 时才会查询【备援】——如果存在，AGENTS.md 会跳过【备援】。

大小限制与截断

  • Codex 对所有加载指令文件的总大小的强制执行默认的 32 KiB 限制，配置如下 project_doc_max_bytes 在 config.toml 中。如果你的 AGENTS.md 文件在串联时超过了这个限制，Codex会截断结果。提高限制：
[project]
project_doc_max_bytes = 65536  # 64 KiB

要有意识地选择你包含的内容。臃肿的 AGENTS.md 会占用【上下文窗口空间】，而这些空间本可用于你的实际代码和对话。优先考虑简洁、高影响力的指令，而非详尽的文档。

带 /init 的脚手架#

  • Codex 内置【斜杠命令】用于引导 AGENTS.md。

在Codex会话中运行/init，会根据你项目检测到的特性生成一个起始的 AGENTS.md——package.json依赖、目录结构、现有配置文件和检测到的框架。

  • 脚手架文件包含上述每个类别的占位符部分，检测成功时预先填充项目特定的默认值。你应该审查并定制输出：脚手架只是起点，不是最终产品。添加你团队的具体惯例，删除不适用的内容。

  • 使用时只需在Codex提示词输入/init即可。生成的文件会写入项目根节点下作为AGENTS.md。

默认原生支持识别 AGENTS.md 的 Agents 软件（必读）

真正原生默认读取 AGENTS.md / AGENTS.override.md 的 Agent 软件：

  • OpenAI Codex (CLI / Desktop / VSCode 插件 / ...)

VSCode插件名称: Codex – OpenAI’s coding agent | OpenAI （有不少同名的，任意混淆，认准 OpenAI 官方认证LOGO就不会错）

  • Cursor

  • Gemini CLI

  • Kimi Code

  • CodeBuddy / WorkBuddy

  • Trae (需手动打开开关)

  • Windsurf / Cascade

  • Github Copilot Coding Agent

  • Google Jules

  • VS Code Copilot Chat

  • Aider

  • Zed

  • 明显的例外
  • Claude Code

最佳实践: AGENTS.md 的编写原则 （软件开发领域） * （必读）

AGENTS.md 中应包含什么？

个强有力的 AGENTS.md 档案在广度与精准之间取得平衡。以下是能带来最大价值的类别：

  • 项目背景:简报架构、技术栈和目录布局的描述。Codex不会在开始前阅读你的全部代码库——它依赖你来定位它。
  • 代码惯例：命名模式、文件组织规则、导入顺序和格式标准。具体点：“文件名用kebab-case”比“遵循标准规范”更好。
  • 测试要求：使用哪个测试运行器，测试在哪里，覆盖期望，以及如何运行套件。示例：“跑pnpm test在承诺之前。所有新功能都必须至少有一次单元测试。”
  • Git 和提交规则：分支命名、提交消息格式、PR 模板的期望。示例：“提交消息遵循常规提交：feat（scope）： description.”
  • 安全界限：Codex 绝不应修改的文件和目录，应避免的危险指令，以及需要人工审核的安全敏感区域。示例：“切勿修改文件中的文件。运行数据库迁移前一定要先征求意见。”config/secrets/
  • 工具偏好：使用哪个包管理器、模板、格式化器和构建工具。举例：“用pnpm代替npm。在承诺之前，先用Prettier格式。”
  • 错误处理模式：如何一致处理错误、日志约定及重试策略。

不可包含的内容？

  • 避免包含Codex通过直接阅读文件能发现的信息：

详尽的API文档、完整功能签名或逐步教程。

  • AGENTS.md 是【说明书】，不是参考资料。还要避免像“写好代码”这样模糊的指令——它们增加了负担，却没有实际价值。

基本原则: 简洁至上

# ✅ 有价值的 AGENTS.md 内容

## 编码规范
- 使用 Composition API（Vue 3）或 Hooks（React 18+）
- 所有 API 调用通过 `src/api/` 下的统一封装
- 错误处理使用自定义 `AppError` 类

## 目录结构
- `src/composables/` — 可复用的状态逻辑
- `src/features/` — 按业务域组织的模块
- `src/lib/` — 第三方服务封装

基本原则: 场景化指令

  • 根据不同场景提供针对性指令：
1) 分支和提交（示例）
  • 分支命名：feature/、fix/、docs/、refactor/ 前缀
  • 提交信息遵循 Conventional Commits 格式
  • 英文提交信息，中文 PR 描述
2) 测试（示例）
  • 使用 Vitest，运行命令：npm run test:unit
  • E2E 测试使用 Playwright
  • 覆盖率阈值：80%

3) 代码审查清单 (示例)

  • 提交前确认：
  • [ ] 类型检查通过（npm run typecheck）
  • [ ] Lint 无错误（npm run lint）
  • [ ] 相关测试已添加
  • [ ] console.log 已移除
## 团队协作场景

### 新成员入职

在项目根级 AGENTS.md 中加入入门信息，新成员（或 Codex）能快速了解项目：

```markdown
## 快速开始

npm install
npm run dev

项目在 http://localhost:3000 启动。

## 关键依赖

- 状态管理：Pinia
- UI 组件库：Element Plus
- HTTP 客户端：Axios（封装在 `src/api/index.ts`）
- 构建工具：Vite 5

最佳实践: 一个带AGENTS.md项目的完整目录结构示例 *

  • AGENTS.md 文件可以放置在项目目录树中的任何位置。Codex 会从当前工作目录开始向上查找，并在每次会话开始时加载找到的所有 AGENTS.md 文件。
  • 一个典型仓库加载 AGENTS.md 后的目录布局:
  • 示例1
project-repo/
├── AGENTS.md                          # 项目仓库级约定（加载）
└── services/
    ├── payments/
    │   ├── AGENTS.md                  # 被跳过（override 优先）
    │   └── AGENTS.override.md         # 支付服务覆写（加载）
    └── search/
        └── AGENTS.md                  # 搜索服务约定（加载）
  • 示例2
my-project/
├── AGENTS.md                    # 根级指令（所有子目录继承）
├── src/main/java/
│   ├── AGENTS.md                # src 目录特定指令
│   ├── xxx-components/
│   │   └── AGENTS.md            # 组件目录特定指令
│   └── utils/
│       └── AGENTS.md            # 工具函数目录特定指令
└── docs/
    └── AGENTS.md                # 文档目录特定指令

最佳实践: 全局级 AGENTS.md

# AGENTS.md — 全局级工程指南
## 角色/Role
- 资深的软件工程师

# 执行计划/ExecPlans
- 在编写复杂功能或进行重大重构时，应从设计到实现使用 ExecPlan（如 .agent/PLANS.md 中所述）。

----------

## 核心原则

1. **上下文优先**：在修改代码之前，先理解现有模块的边界、所有权和约定。不要引入与代码库已有模式冲突的新抽象。
2. **务实而非教条**：每种设计模式都有成本。只有在消除真实重复、降低实质性复杂度时才引入抽象；不要为了"整洁"而提前分层。
3. **最小阻力路径**：优先使用代码库已有的框架、工具链和内部 API，而不是发明新的风格。
4. **渐进式完备**：先让正确的行为跑通，再微调结构、性能与测试覆盖。不要一次提交中混入无关的重构。

## 代码规范
- **语言**：Java / Scala / Python / TypeScript 均以 ASCII 为默认字符集。非 ASCII 字符仅在有明确理由且文件已处于该字符集中时引入。
- **注释**：只对不易自明的逻辑块添加简短定向注释。避免空泛的叙述（如"将值赋给变量"）。代码应当首先通过命名和结构表达意图。
- **测试**：测试覆盖范围与变更的风险和影响半径成正比。窄变更保持聚焦；跨模块契约或用户可见行为的改动需要更广泛的测试。
- **提交**：一个提交聚焦一件事。无关的格式修正、元数据改动或重构应单独提交。

## 目录与文件约定

\`\`\`
.project-root/
├── .agents/
│   └── AGENTS.md            # 全局指南（本文件）
├── <module-a>/
│   └── .agents/
│       └── AGENTS.md         # 模块/项目级指南
├── docs/
├── scripts/
└── ...
\`\`\`

- 全局 `AGENTS.md` 定义跨项目通用的规范。
- 项目或模块级 `AGENTS.md` 定义该特定范围内适用的补充或覆盖规则。层级越近，优先级越高。
- 任何 `AGENTS.md` 不应重复上级已有的内容，只做增补或例外说明。

## 技术债务与演进

- 遇到技术债务时，在改动处留下 `// TODO(your-name): <原因>`，但不要在同一提交中修复无关债务。
- 架构决策（为什么选 A 而非 B）应记录在 ADR（`docs/adr/`）中。简单理由可在 PR 描述中交代。
- 依赖升级要有明确动机（安全、性能、功能需求），不做无理由的追新。

## 协作模式

- 收到需求时先确认问题域是否已清晰；若不清晰，通过短问题收敛范围。
- 除非用户明确要求只做计划或分析，否则默认推进到可工作的实现。
- 代码审查关注：正确性 > 性能 > 可读性 > 风格。先找 bug 和回归风险，再谈改进建议。

## 工程文化

- 保持好奇与务实。对领域知识、历史背景和业务上下文同样重视。
- 承认不确定性和权衡。宁愿说"我还不确定，让我验证"而不是假装确定。
- 对自己和同伴输出的代码质量负责。——没有"别人的代码"。
- 持续学习。新技术值得尝试，但要在真实约束下评估，而不是在真空中比较。

3.5 技能与插件：扩展你的 Agent * （必读）

  • Codex 【技能与插件系统】的全面指南——【技能/Skill】如何定义、存储、调用、捆绑到【插件/Plugin】中以及为 OpenAI 代理配置。

推荐文献

主要要点

  • 技能/Skill ：其是Codex中的原子扩展单元，由带有YAML前言和降注指令的 SKILL.md 文件定义。
  • 5个存储位置 ：决定技能的存放位置及其范围：仓库、用户、管理员、系统和捆绑默认。
  • 隐性召唤：在相关时自动激活技能;显式调用使用$skill名进行精确控制。
  • $skill创造者：其是内置技能，用于搭建新技能;$skill安装器安装了社区注册库中精选的技能。
  • 插件：将【技能】、【应用】和【MCP服务器】打包到一个【可分发包】中，通过/plugins或 Codex 应用管理。
  • agents/openai.yaml : 携带了诸如 display_name、依赖和策略等元数据，这些内容规范了 OpenAI 代理如何与该技能交互。
  • 技能/Skill: 可以在config.toml的[skills]部分按项目开启或禁用。

理解 Codex 技能系统

  • Codex的【可扩展性模型】聚焦于【技能/Skill】——自包含的教学单元，教Agent如何执行专业任务。

Skill 不是【函数调用】或【传统的插件钩子】;
Skill 是一份【结构化文档】，在合适的时刻将上下文、程序和参考材料注入 Agent 的【工作记忆】中。
就是这样设计这样可以扩展Codex的知识和行为，而无需修改核心代码。

SKILL.md 格式 * （必读）

  • 每个【技能/Skill】的文件夹内都有一个 SKILL.md 文件。

该文件使用 YAML 前文处理机器可读元数据，后面是 markdown 主体，代理将其读取为指令。前言通常包括：

  • 名称/name：技能的唯一标识符，用于显式调用（例如，deploy-kubernetes）。
  • 描述/description：Codex用来判断该技能是否与当前任务相关，简明扼要的总结。
  • 版本/metadata.version（可选字段）：当前技能的版本
  • markdown 正文包含实际指令——逐步操作、决策树、代码模板、约束以及代理所需的任何上下文知识。因为这是标准的 Markdown，你可以用头部代码方块、表格和嵌入引用，使指令尽可能丰富且结构化。
---
name: deploy-kubernetes
description: Deploy containerized applications to Kubernetes clusters with best-practice manifests
---

## Deployment Workflow

1. Verify kubectl context points to the target cluster.
2. Generate or retrieve manifests from the references/ directory.
3. Apply manifests with kubectl apply -f.
4. Wait for rollout and validate with kubectl rollout status.

目录结构 * （必读）

  • 直接从 Codex 的 GitHub 仓库发布页面下载最新的二进制文件。这非常适合CI环境或没有 Node.js 的机器：
my-skill/
  SKILL.md          # Required: frontmatter + instructions
  scripts/          # Executable scripts the skill can invoke
  references/       # Templates, schemas, config examples
  assets/           # Non-code resources (diagrams, sample data)
  agents/
    openai.yaml     # Agent-specific metadata
  • SKILL.md : 是唯一需要的文件。其他都是可选的，但强烈建议用在非简单技能上。
  • scripts/ : 保存shell脚本、Python文件或技能引用的任何可执行文件。Codex可以直接运行这些技能，只要技能指示。
  • references/ : 存储静态资产，比如 YAML 模板、JSON 模式，或技能注入提示或传递给脚本的配置片段。
  • assets/ : 包含辅助文件——架构图、示例数据集或文档图像，帮助代理推理任务。
  • agents/openai.yaml : 提供针对 agent 的配置。在这里你声明了 OpenAI 驱动的代理应如何与该技能交互，包括显示命名、依赖声明和执行策略（见下文）。

技能存储地点 *（必读）

  • Codex从五个不同地点解决技能，每个地点有不同的范围和管理模式：
位置 路径 范围 使用场景及建议
REPO 项目根节点中的.agents/skills/;
(Codex默认项目的路径:~\Documents\Codex\)		 仅限项目 【团队共享技能】被录入Git仓库进行【版本控制】
USER ~/.agents/skills/ 全用户 所有项目中都能提供个人技能;
建议：个人自定义的（但又不适合团队协作共享的）skill建议统一存放此处，便于不同厂商的Agent软件（如: 豆包、Codex等）之间、多个项目之间默认共享与复用；此目录的技能，Codex CLI及Desktop是实时读取，无需重启来加载。
ADMIN /etc/codex/skills/ 全机 对主机上所有用户强制执行IT管理技能
SYSTEM 随 Codex 安装捆绑
如:C:\Users\(用户)\.codex\skills\my-research-opensource-project\		 整个设施 随Codex附带的内置技能
建议：适合存放与codex/openai软件强相关的技能
DEFAULTS 内部默认设置
具体位置:~\.codex\skills\.system\		 随时待命 核心行为
比如$skill创造者(C:\Users\用户\.codex\skills\.system\skill-creator)
  • 当多个地点定义【同名 skill】时，优先顺序依据： REPO > USER > ADMIN > SYSTEM 排序。

这使得【项目专属技能】可以覆盖用户或系统级技能，类似于 .env 文件在配置中叠加。

查看/列出 * （必读）

  • codex cli 交互模式下

无需重启，实时加载

/skiils

image

  • codex Desktop 交互模式下

无需重启，实时加载

  • 菜单路径： 设置-插件-技能-（技能列表）

image

  • Codex 系统内置的技能

C:\Users\用户\.codex\skills\.system

image

召唤/调用：隐性与显式

  • 技能 可以通过2种方式激活：
  • 隐式调用 : 默认方式。当用户请求与 skill 的描述匹配时，Codex 会自动将 skill 的 prompt 加载到上下文中。

例如，如果你有一个技能描述为“使用 GitHub Actions 设置 CI/CD 管道”，那么当你向 Codex 请求“为我的仓库创建一个 CI 管道”时，该技能将被隐式激活。无需特殊语法。

  • 显式调用 : 则提供直接控制。输入 $skill-name（以美元符号开头）可【强制加载特定技能】，无论其在上下文中的相关性如何。

这在需要使用可能与请求自然语言不匹配的技能，或当多个技能都适用且希望精确指定时非常有用。
例如，$deploy-kubernetes 保证即使你的提示仅为“部署这个”，也会加载 Kubernetes 部署技能。

内置技能： $skill-creator/Skill创建者 + $skill-installer/Skill安装者

Codex 配备了2项内置技能，旨在帮助您管理技能生态系统：

  • $skill-creator : 【从零开始】创建新技能。当您调用 $skill-creator 时，Codex 会提示您输入名称和描述，然后生成完整的目录结构——包括带有正确前导信息的 SKILL.md 文件，以及空的 scripts/、references/ 和 assets/ 目录，还有 starter agents/openai.yaml 文件。这确保每个新技能从第一天起就遵循标准布局。

  • $skill-installer : 从【社区注册表】中安装经过筛选的技能。运行 $skill-installer 会显示一个可搜索的目录列表，其中包含其他用户提交的经过审核的技能。

选择其中一个后，Codex 将将其下载到指定位置（默认为 USER，如果您指定了 --local 则为 REPO）。
安装程序还会自动解析依赖项——如果某个技能需要其他技能或 MCP 服务器，$skill-installer 会提示您一并安装这些组件。

插件/Plugin：捆绑Skill、Agent应用、MCP服务器

  • 虽然 Skill 本身就很强大，Codex的【插件/Plugin】提供更高级的封装机制。【插件】将一个或多个技能捆绑在一起，包括：
  • Agent/应用：预配置的应用集成（例如，提供连接细节和模式内省的PostgreSQL应用）。
  • MCP服务器：模型上下文协议服务器，向代理展示额外工具和数据源。

这种捆绑意味着只需安装一个 Plugin，Codex 就能部署到 AWS——技能提供指令，应用持有 AWS 凭证和区域配置，MCP 服务器则暴露 CloudFormation 和 EC2 工具。

安装插件

  • 【插件】可以通过2种方式安装：
  • 通过 /plugins CLI 命令：运行 /plugins install 从注册表获取并安装插件。Codex 负责下载软件包、将技能放入正确的目录、注册 MCP 服务器以及配置应用。
  • 通过 Codex 应用（桌面端 或 Web端）：桌面或网页应用包含插件浏览器，您可以一键搜索、预览和安装插件。应用在安装前还会显示依赖树和权限。

启用和禁用插件与技能

  • 并不是所有安装的技能或插件都需要一直开启。Codex 使用 config.toml 进行细粒度控制：
[skills]
# Explicitly enable or disable skills by name
deploy-kubernetes = true
legacy-deploy = false

[plugins]
# Enable or disable entire plugins
aws-toolkit = true
experimental-ml = false**
  • 当 Skill 被禁用时，它不会被考虑为【隐式召唤】，也不能在【显式召唤】中调用。

当插件被禁用时，其所有捆绑的技能、应用和MCP服务器都会一起停用。
这对管理绩效很有用（技能越少，上下文开销越少），也能关闭与特定项目惯例冲突的技能。

构建自定义插件

  • 创建【自己的插件】包含3个步骤：
  • 定义技能——按照标准格式和目录结构编写一个或多个 SKILL.md 文件。
  • 添加代理元数据——为每个技能创建agents/openai.yaml（或插件共享的），指定OpenAI代理如何处理该技能。
  • 打包和分发——将技能、任何支持的应用和MCP服务器配置打包到插件目录中。发布到社区注册库或私下分发目录。
  • agents/openai.yaml 文件对于兼容 OpenAI 的代理尤为重要。其中包括：
  • display_name：Codex 界面中显示的人类可读名称（例如，“AWS 部署工具包”）。
  • 依赖：列出该技能所需的其他技能、应用或MCP服务器。Codex会在加载时检查这些，并警告是否有缺失。
  • 策略：执行策略规则——例如，技能是否要求用户确认后才能运行脚本，或是否允许修改项目目录外的文件。
display_name: "AWS Deployment Toolkit"
dependencies:
  - skill: docker-build
  - mcp: aws-cloudformation
policy:
  require_confirmation: true
  file_scope: project-only
  max_execution_time: 300

config.toml中的技能：完全控制

  • 除了简单的启用/禁用开关外，config.toml 还支持高级技能配置：
[skills.deploy-kubernetes]
enabled = true
invocation = "explicit"   # Force explicit-only; never auto-activate
priority = 10             # Higher priority wins when multiple skills match

[skills.code-review]
enabled = true
invocation = "implicit"   # Auto-activate when relevant
priority = 5

将Skill的调用设置为“explicit”意味着它永远不会被【隐式激活】——只能用 $skill 名的显示唤醒方式来调用。
优先级字段用于解决当两个技能都可能同时应用于请求时的冲突;优先考虑优先级更高的技能。

最佳实践 for Skill

  • 保持技能聚焦：每个技能应处理一个领域或工作流程。一个涵盖Kubernetes、ECS和裸机的“部署”技能比三个独立技能更难维护。
  • 使用引用而非内联内容：将大型模板和模式存储在引用中/而不是嵌入 SKILL.md 中。这保持了指令体的简洁性和代理上下文窗口的高效性。
  • 先测试显式召唤：在开发新技能时，明确调用以验证行为，然后再依赖隐性激活。这样可以隔离问题并加快迭代速度。
  • 善用$skill创建器：不要手动创建目录结构。$skill-creator 确保一致性，并及时发现常见错误，比如漏掉前页字段。
  • 版本化你的 REPO 技能：因为 REPO 级别的技能存储在 .agents/skills/ 中，它们会被 git 验证。在更新日志中标记它们，并像对待其他项目工件一样处理。
  • 在openai.yaml中记录依赖关系：始终在依赖字段声明你的技能需要什么。这防止了缺少必需MCP服务器或伴随技能时出现的隐性失败。

3.6 Codex CLI 常用命令

  • 推荐文献

删除会话

当某些会话确实无意义时，可进行删除。
用户会话的默认存储路径: ~/.codex/sessions/<年>/<月>/<日>/文件夹下：
image

  • step1 GUI 界面中选中待删除的对话，右键【复制会话ID】

image

  • step2 进入命令行窗口（如 powershell），输入删除对话的命令
PS Xxxxxx > codex delete 019ff4c7-0150-7353-8227-d0969a21a955
Permanently delete session 019ff4c7-0150-7353-8227-d0969a21a955?
This cannot be undone. Subagent threads will also be deleted.
Continue? [y/N]: y
Deleted session 019ff4c7-0150-7353-8227-d0969a21a955.

此命令会从本地 ~/.codex/sessions 中移除对应记录。

  • step3 再重启 Codex GUI——即可发现：待删除的那个会话已看不见了。

3.7 使用案例

CASE AI Coding

例如：

  • "Add a hello world function to main.py"

Codex 读取你的代码库，理解上下文，生成变更。它会在应用前显示差别，这样你就能控制。

  • “为认证模块编写单元测试”

  • “《修复src/api/handlers.ts中的类型错误》”

  • “向所有导出函数添加JSDoc注释”

  • “重构数据库连接以使用连接池”

  • 在全自动模式下使用Codex处理可信任务：

Codex 桌面端，需在【设置-配置-用户配置-批准策略-从不请求审批】进行操作。

codex --full-auto "Add input validation to the registration form"

CASE 基于计划模式/协作模式，使用 ExecPlan 驱动长耗时任务

  • 推荐文献

CASE 创建与使用自定义 Skill (SKILL.md) 【待更新】

  • 为团队定制特定编码规范或工作流 Skill
---
name: code-style-checker
description: 检查并修复符合团队规范的代码格式与 注释要求
---
Use this skill when reviewing or writing Python code.
1. 确保所有函数都包含完整 Type Hints。
2. 运行 `flake8` 与 `black --check`。
3. 检查是否有未处理的 Exception 捕获。
  • 在 Codex CLI 中调用自定义 Skill
codex skill load ./skills/code-style-checker
codex run "审查 src/services/user.py 并应用 code-style-checker 规范"

Z FAQ for Codex

Q: Codex 与 2021 年发布的初始版 OpenAI Codex 有什么区别？

早期 2021 版的 Codex 是一个基于 GPT-3 的纯文本/代码补全大语言模型，主要通过 Completion API 输出行级或代码块建议。
而现代的 Codex 是一个自主 Agent 平台，集成了专门训练的推理模型（如 codex-1）、云端隔离沙盒、MCP 协议与 PLANS.md 长耗时规划能力，能够自主在沙盒中运行构建、测试、自修复并异步提交 PR。

Q: Codex 如何保证在执行命令和改动代码时的安全性？

Codex 采用了隔离云端沙盒（Isolated Cloud Sandbox）技术。所有的代码克隆、依赖安装、Bash 命令执行与测试都在与生产环境隔离的独立容器中运行。
对外部网络的访问需受权限策略约束，且最终产出以 Git Pull Request 的形式呈现，交由人类开发者统一审查（Human-in-the-loop）。

Q: PLANS.md (ExecPlans) 在 Codex 执行长耗时任务时起到了什么作用？

对于长达数小时、跨越数十个文件的复杂重构任务，上下文窗口限制往往会导致 Agent 丢失长期目标。
PLANS.md 扮演了一个“动态设计文档与工作日志”的角色。
Codex 在每一步操作前会更新进度，记录已完成的模块与下一步计划，确保其在连续数小时的不间断执行中始终方向明确。

Q: Codex 如何结合 MCP (Model Context Protocol) 扩展能力？

MCP 是 OpenAI 与开源社区推荐的通用上下文与工具协议。
Codex 可以接入任何标准 MCP Server（如数据库查询、Figma 设计接口、Sentry 报错日志）。
同时，配合 SKILL.md，Codex 知道何时以及按何种顺序调用这些 MCP 工具，从而完成复杂的跨系统业务流程。

Q: Windows 端建议使用 Codex 的哪款终端？ *

  • Codex Desktop + Codex CLI （二选一 或 混合使用）
  • Windows Shell 环境：推荐已充分兼容的 Powershell 。

不推荐 Git Bash 环境，其 codex 容易产生乱码问题。

Y 推荐文献

  • OpenAI/Codex
  • Codex 的相关研究

X 参考文献

posted @ 2026-08-08 23:48  数据知音  阅读(28)  评论(0)    收藏  举报