OpenAI Codex 是一款面向真实工程场景的软件工程 AI 代理（Coding Agent），它不只是一个简易的代码生成工具，而是能深入参与实际开发流程的工程级助手。 Codex 能理解 大型 或陌生的代码库结构、接收自然语言指令、自动生成代码、修复 Bug、运行测试、进行代码审查，并在安全隔离的环境中执行开发任务，它的目标不是简单回答“怎么写某段代码”，而是更像一名可以与工程师协同工作的虚拟开发者。
Codex 可以运行在多种环境中 —— 包括 IDE、终端命令行、Web 界面的 ChatGPT 侧边栏等，并能结合项目上下文调整输出结果，官方强调 Codex 能从整个代码仓库中提取上下文来理解依赖关系、计划新功能和查找问题，从而帮助团队更快规划与交付产品。
博主不太建议直接使用国内中间代理的 Codex，虽然口头上说是 “直连”，其实本质是走了代理，因此也踏了不少坑，费用是直连的几倍，最终使用了直连的方式。这里不讲述如何使用国内的，网上搜索应该一大堆。
直连的方式很简单，只需要 “魔法”+“注册” + “代充” 即可，相信大家都懂，费用大概一个月100多，而且根本用不完，相比国内的中间代理，省了不止一倍，而且不存在稳定性的问题。
怎么使用 “魔法”，这里不再阐述了，适合自己就好，现在官网并不支持注册，可以自己去某宝买一个账号，同时让他代充即可。最后登录成功的 web 页面如下，可以看到目前默认使用 GPT 5.2，同时也支持邀请团队成员（这里使用的是 team 版，plus 版本可能更贵）：
OpenAI 的 AI Codex 编程助手 并不是单独付费的单品，而是包含在不同 ChatGPT 订阅计划中的一项高级功能，用户通过这些计划即可在 Web、CLI、IDE 扩展等环境中使用 Codex 执行代码生成 、重构、代码审查等任务。
| 方案 /价格 | 定位 | 特性 |
|---|---|---|
| Plus($20/月 ) | 轻量编码需求 | 每周适合做几个中等规模的编码会话，可在 Web、CLI、IDE 中使用 Codex，以及获得最新模型和扩展使用额度 |
| Pro($200/月 ) | 全职开发者 | 包含 Plus 的所有内容，同时获得更高的使用限额、优先请求处理、更高性能的云任务等能力。 |
| Business($30/用户/月) | 团队与企业 | 适合公司团队使用，包括更大的 VM 实例、更强安全性控制、可共享使用额度等。 |
| Enterprise / Edu | 大规模组织 | 在 Business 的基础上提供企业级安全与管理功能，如 SAML/SSO、审计日志、用户分析、数据驻留等。 |
下面我帮你 补充完善 3.2 / 3.3 部分内容，尽可能保留原始链接的官方说明细节，并结合官方 Quickstart 页面信息进行整理。([OpenAI Developers][1])
| 类型 | 要求 |
|---|---|
| 操作系统 | macOS 11.0 及以上，Ubuntu 20.04+/Debian 11+，或 Windows 10+/11（推荐使用 WSL 2） |
| 硬件 | 至少 4GB 内存（推荐 8GB 及以上） |
| 处理器 | x86_64 或 ARM64 架构处理器 |
| 依赖软件 | Git 2.30+ Python 3.10+ Node.js 18+ |
| 运行环境 | Docker 20.10+（可选，但强烈推荐） |
| 网络 | 需要稳定的互联网连接，用于依赖下载、认证及模型调用 |
| Shell | Bash 或 Zsh（macOS / Linux），Windows 建议使用 WSL Bash |
| 权限 | 当前用户需具备本地软件安装与网络访问权限 |
Codex CLI 是一款运行在本地终端的轻量级 AI 编程代理，可通过命令行与代码库交互，CLI 支持 macOS / Windows / Linux 平台，并可结合 Git 管理本地项目。
首次运行时，会提示你使用 ChatGPT 账号登录 或 API key 登录，登录成功后，CLI 会提升权限读取当前目录的代码库，并允许你发出自然语言指令来完成任务。
Cloud 是 Codex 在线版，可直接在浏览器 使用，无需本地安装。你可以在浏览器中创建项目、执行任务，并将 Codex 与 GitHub 仓库连接。使用流程如下：
接下来，我们可以开发任务，例如：帮我创建一个静态的页面，打开后，是星空的动态效果。可以看到，Codex 在执行任务的过程中，会提示用户是否要执行该操作，上述有三个选项，我们可以选择2，意思是整个执行的过程都同意，不需要每次都提示：
不论是通过 IDE 插件、CLI 命令行，还是 Cloud Web 方式，Codex 都在试图改变我们与代码交互的方式 —— 从 “我告诉你怎么写代码” → “我告诉你我要做什么” 。希望本文能对大家理解和使用 Codex 有所帮助，也欢迎在评论区交流你的使用经验和踩坑心得，谢谢大家的阅读，本文完！
本文并非简单翻译文档，而是站在工程实践视角，将 Codex 的能力映射到日常开发中的典型任务（理解代码、修 Bug、写测试、重构、审查 PR 等），帮助你回答一个关键问题： 如何把 Codex 从“辅助工具”，真正变成工程流程中的一名“虚拟工程师”？
在任务执行过程中，Codex 也会从文件内容、工具输出以及正在进行的记录中收集上下文信息，所有信息必须适配模型的 上下文窗口（context window） 大小，它会根据不同模型而变化。
Step 1. 打开最相关的文件
Step 2. 选中你关注的代码段（推荐）
Step 1. 启动 Codex
Step 3. 校验
Step 1. 打开函数所在文件
Step 2. 选中函数定义
Step 3. 通过命令面板选择 Add to Codex Thread
Step 4. 提示词
Step 1. 启动 Codex
Step 2. 提示词
AI 模型所能执行的任务范围正在快速扩展，这对工程领域有深远影响，最先进的系统现在可以维持 多小时连续推理。截至 2025 年 8 月，METR 发现领先模型能够以 大约 50% 的准确率完成连续 2 小时 17 分钟的任务，这项能力正在迅速提升——任务长度约每七个月翻倍，几年前，模型只能处理约 30 秒的推理（足够提供小段代码建议），如今由于能维持更长连贯的推理，整个软件开发生命周期（SDLC）都可以引入 AI 辅助，让编码智能体在 规划、设计、开发、测试、代码审查和部署等阶段发挥作用。
这里将展示 AI 智能体如何在 SDLC 各阶段提供帮助，并给出工程领导者可以立即采用的实践建议，帮助团队构建 AI 原生工程流程与团队结构。
AI 编程工具已经远远超越了最初作为自动补全助手的角色，早期工具只能处理简单任务，例如建议下一行代码或填充函数模板，随着模型推理能力增强，开发者开始通过 IDE 中的聊天界面与智能体互动，用于结对编程和代码探索。如今的编程智能体能够：
AI 编程智能体正在重塑软件开发生命周期，它们能承担传统上耗时、重复的多步骤工作，让工程师专注于架构、设计、产品意图等高价值任务，成功打造 AI 原生工程团队不需要彻底重写流程，而是 以小型、精确的自动化开始积累效益，逐步扩大智能体责任范围，从而提升整体效率、质量与创新能力。
通过阅读本文，相信大家已经系统理解了 Codex 在工程场景中的核心设计理念与实践价值：它并不是一个“更聪明的自动补全工具”，而是一个以 提示词为接口、以线程与上下文为状态、以工作流为执行边界 的工程级编程智能体。
Codex 的关键意义在于：将真实的软件工程能力（代码库、构建工具、测试系统、代码审查与云端执行环境）有序、可验证地引入到模型的推理与行动闭环中，通过合理的 Prompt、Context 与 Workflow 设计，Codex 不再只停留在“生成代码”，而是能够 理解现有系统、执行多步任务、验证结果并持续迭代，从而真正参与到完整的软件开发生命周期中。
| 标题 | 标签 | 发布日期 |
|---|---|---|
| Build your own content fact checker with gpt-oss-120B, Cerebras, and Parallel | cerebras, fact-checking, gpt-oss, open-models, reasoning, search | 2026-01-13 |
| User guide for gpt-oss-safeguard | gpt-oss, guardrails, open-models | 2025-10-29 |
| Fine-tune gpt-oss for better Korean language performance | gpt-oss, open-models | 2025-08-26 |
| Verifying gpt-oss implementations | gpt-oss, gpt-oss-providers, open-models | 2025-08-11 |
| How to run gpt-oss locally with LM Studio | gpt-oss, gpt-oss-local, open-models | 2025-08-07 |
| How to run gpt-oss-20b on Google Colab | gpt-oss, gpt-oss-server, open-models | 2025-08-06 |
| Using NVIDIA TensorRT-LLM to run gpt-oss-20b | gpt-oss, gpt-oss-server, open-models | 2025-08-05 |
| OpenAI Harmony Response Format | gpt-oss, gpt-oss-fine-tuning, gpt-oss-providers, harmony, open-models | 2025-08-05 |
| How to run gpt-oss with vLLM | gpt-oss, gpt-oss-server, open-models | 2025-08-05 |
| How to run gpt-oss with Transformers | gpt-oss, gpt-oss-server, open-models | 2025-08-05 |
| How to run gpt-oss locally with Ollama | gpt-oss, gpt-oss-local, open-models | 2025-08-05 |
| How to handle the raw chain of thought in gpt-oss | gpt-oss, gpt-oss-fine-tuning, gpt-oss-providers, open-models | 2025-08-05 |
| Fine-tuning with gpt-oss and Hugging Face Transformers | gpt-oss, gpt-oss-fine-tuning, open-models | 2025-08-05 |
| 标题 | 标签 | 发布日期 |
|---|---|---|
| OpenAI Compliance Logs Platform quickstart | chatgpt, chatgpt-and-api, chatgpt-data, compliance, enterprise | 2025-12-11 |
| GPT Actions library - Salesforce & Gong | chatgpt, chatgpt-productivity, gpt-actions-library | 2025-04-07 |
| GPT Actions library - Tray.ai APIM | chatgpt, chatgpt-middleware, gpt-actions-library | 2024-11-26 |
| GPT Actions library - Google Calendar | chatgpt, chatgpt-communication, gpt-actions-library | 2024-11-22 |
| GPT Actions library - Workday | chatgpt, chatgpt-productivity, gpt-actions-library | 2024-11-20 |
| GPT Actions library - GitHub | chatgpt, chatgpt-productivity, gpt-actions-library | 2024-10-23 |
| GPT Actions library - Google Ads via Adzviser | chatgpt, chatgpt-data, chatgpt-middleware, chatgpt-productivity, gpt-actions-library | 2024-10-10 |
| GPT Actions library - Canvas Learning Management System | chatgpt, gpt-actions-library | 2024-09-17 |
| GPT Actions library - Retool Workflow | chatgpt, chatgpt-middleware, gpt-actions-library | 2024-08-28 |
| GPT Actions library - Snowflake Middleware | chatgpt, chatgpt-data, gpt-actions-library | 2024-08-14 |
| GPT Actions library - Snowflake Direct | chatgpt, chatgpt-data, gpt-actions-library | 2024-08-13 |
| GPT Actions library - Google Drive | chatgpt, chatgpt-productivity, gpt-actions-library | 2024-08-11 |
| GPT Actions library (Middleware) - Google Cloud Function | chatgpt, chatgpt-middleware, gpt-actions-library | 2024-08-11 |
| GPT Actions library - AWS Redshift | chatgpt, chatgpt-data, gpt-actions-library | 2024-08-09 |
| GPT Actions library - AWS Middleware | chatgpt, chatgpt-middleware, gpt-actions-library | 2024-08-09 |
| GPT Actions library - Zapier | chatgpt, chatgpt-middleware, gpt-actions-library | 2024-08-05 |
| GPT Actions library - Box | chatgpt, chatgpt-productivity, gpt-actions-library | 2024-08-02 |
| GPT Actions library - SQL Database | chatgpt, chatgpt-data, gpt-actions-library | 2024-07-31 |
| GPT Actions library - Confluence | chatgpt, chatgpt-productivity, gpt-actions-library | 2024-07-31 |
| GPT Actions library - Notion | chatgpt, chatgpt-productivity, gpt-actions-library | 2024-07-25 |
| GPT Actions library - Jira | chatgpt, chatgpt-productivity, gpt-actions-library | 2024-07-24 |
| GPT Actions library - Gmail | chatgpt, chatgpt-communication, gpt-actions-library | 2024-07-24 |
| GPT Actions library - Salesforce | chatgpt, gpt-actions-library | 2024-07-18 |
| GPT Actions library - Outlook | chatgpt, chatgpt-communication, gpt-actions-library | 2024-07-15 |
| GPT Actions library - getting started | chatgpt, gpt-actions-library | 2024-07-09 |
| GPT Actions library - BigQuery | chatgpt, chatgpt-data, gpt-actions-library | 2024-07-09 |
| GPT Actions library - Sharepoint (Return Text) | chatgpt, chatgpt-productivity, gpt-actions-library | 2024-05-24 |
| GPT Actions library - Sharepoint (Return Docs) | chatgpt, chatgpt-productivity, gpt-actions-library | 2024-05-24 |
| GPT Actions library (Middleware) - Azure Functions | chatgpt, chatgpt-middleware, gpt-actions-library | 2024-05-24 |
| 标题 | 标签 | 发布日期 |
|---|---|---|
| Context Engineering for Personalization - State Management with Long-Term Memory Notes using OpenAI Agents SDK | agents-sdk | 2026-01-05 |
| Build a coding agent with GPT 5.1 | agents-sdk | 2025-11-13 |
| Self-Evolving Agents - A Cookbook for Autonomous Agent Retraining | agent-retraining, evals, llmops, partners, prompt-engineering, self-evolving-agents | 2025-11-04 |
| Build, deploy, and optimize agentic workflows with AgentKit | agentkit, evals | 2025-10-17 |
| Using PLANS.md for multi-hour problem solving | agents, codex, documentation, gpt-5, planning | 2025-10-07 |
| Context Engineering - Short-Term Memory Management with Sessions from OpenAI Agents SDK | agents-sdk | 2025-09-09 |
| Optimize Prompts | agents-sdk, completions, prompt, responses, tracing | 2025-07-14 |
| Automate Jira ↔ GitHub with Codex | automation, codex | 2025-06-21 |
| Parallel Agents with the OpenAI Agents SDK | agents, agents-sdk, parallel-agents | 2025-05-01 |
| Evaluating Agents with Langfuse | agents-sdk, evals | 2025-03-31 |
| 标题 | 标签 | 发布日期 |
|---|---|---|
| Prompt Personalities | gpt-5, prompt-personalities | 2026-01-05 |
| Building resilient prompts using an evaluation flywheel | datasets, evals | 2025-10-06 |
| GPT-5 Troubleshooting Guide | gpt-5, prompt-optimization | 2025-09-17 |
| GPT-5 Prompt Migration and Improvement Using the New Optimizer | gpt-5, prompt-optimization, reasoning, responses | 2025-08-07 |
| Prompt Migration Guide | completions, prompt, responses | 2025-06-26 |
| Fine-Tuning Techniques - Choosing Between SFT, DPO, and RFT (With a Guide to DPO) | fine-tuning | 2025-06-18 |
| Exploring Model Graders for Reinforcement Fine-Tuning | fine-tuning, reinforcement-learning, reinforcement-learning-graders | 2025-05-23 |
| Leveraging model distillation to fine-tune a model | completions, fine-tuning | 2024-10-16 |
| Prompt Caching 101 | completions, cost, latency, prompt caching | 2024-10-01 |
| How to fine-tune chat models | completions, fine-tuning | 2024-07-23 |
| Fine-tuning OpenAI models with Weights & Biases | completions, fine-tuning, tiktoken | 2023-10-04 |
| Data preparation and analysis for chat model fine-tuning | completions, fine-tuning, tiktoken | 2023-08-22 |
| 标题 | 标签 | 发布日期 |
|---|---|---|
| Codex Prompting Guide | codex, compaction, responses | 2025-12-04 |
| Modernizing your Codebase with Codex | codex | 2025-11-19 |
| Build Code Review with the Codex SDK | codex | 2025-10-21 |
| Use Codex CLI to automatically fix CI failures | codex | 2025-09-30 |
| Automating Code Quality and Security Fixes with Codex CLI on GitLab | codex | 2025-08-29 |
| Reasoning over Code Quality and Security in GitHub Pull Requests | SDLC, completions, reasoning | 2024-12-24 |
| What makes documentation good | 2023-09-01 |
在前几篇文章里，博主已经把 Codex 的核心能力与关键概念做了系统梳理：它是什么、能做什么、以及为什么它更像“工程级 AI 编程代理”而不是普通的代码补全工具。有兴趣的童鞋可以先阅读：
如果要真正把 Codex 用“顺手”，往往不取决于你会不会写提示词，而取决于你选对了入口：有些任务适合在 IDE 里边写边改边跑；有些更适合在 CLI 里批处理、跑脚本或做审查；而当你希望它并行处理、自动跑测试、甚至直接产出可验证的 diff/PR 时，Codex 云端（Web/Cloud） 反而更高效…
因此，本文不再重复讲原理，而是聚焦一个更实用的问题：Codex 在不同端（IDE / CLI / Web / 集成平台）分别怎么用、各自适合什么场景、以及如何做选择。
原文地址：https://developers.openai.com/codex/ide
视频地址：https://youtu.be/sd21Igx4HtA
Codex 是 OpenAI 的编程智能代理，它可以读取、编辑和运行代码，帮助你更快构建项目、修复错误并理解不熟悉的代码，Codex 可以通过 VS Code 扩展 在你的 IDE 中并排工作，或将任务委托到云端执行。
Codex IDE 扩展支持 Visual Studio Code 的各类版本，包括 Visual Studio Code、Cursor、Windsurf，也可以从对应市场下载安装扩展：
注：macOS 和 Linux 上扩展支持完全；Windows 上当前为实验性支持。建议在 Windows 上使用 WSL 工作区获得最佳体验。
安装完成后：
也可以将 Codex 拖动到右侧侧边栏作为一个独立的标签页查看：
安装扩展后，它会提示你使用 ChatGPT 帐户登录 或使用 API 密钥。下面是使用 Codex IDE 扩展一些常用的工作方式：
1. 使用 Codex IDE 扩展可以做什么
Codex IDE 扩展让你可以在 VS Code、Cursor、Windsurf 及其他兼容 VS Code 的编辑器中直接访问 Codex。它使用与 Codex CLI 相同的智能体，并共享相同的配置。
2. Codex 提示词
在编辑器中使用 Codex 聊天、编辑和预览更改，当 Codex 拥有来自打开文件和选中代码的上下文时，你可以写更短的提示，并获得更快、更相关的结果
可以通过在提示中引用编辑器里的文件来指定上下文，例如（将 @example.tsx 作为参考文件）：
Use @example.tsx as a reference to add a new page named "Resources" to the app that contains a list of resources defined in @resources.tsshell
3. 切换模型（Switch between models）
可以在聊天输入框下方的切换 器中切换不同的模型。
4. 调整推理强度（Adjust reasoning effort）
你可以调整 Codex 的推理 强度，以控制 Codex 在响应前思考多久（更高的推理强度适用于更复杂的任务，但响应时间会更长，也会消耗更多令牌/配额）。
5. 选择审批模式（Choose an approval mode）
默认情况下，Codex 使用 “Agent”（代理）模式，在此模式下，Codex 可以自动读取文件、进行编辑并在工作目录中运行命令，如果 Codex 要访问工作目录以外的文件或网络，仍然需要你的批准，如果只是想聊天或先规划再修改，可以切换到 “Chat”（聊天）模式：
如果需要 Codex 读取文件、编辑并运行命令且无需批准，可以选择 “Agent（Full Access）”（完全访问）模式 — 但这种模式要谨慎使用。
6. 云端委派（Cloud delegation）
你可以将较大的任务委派给云端的 Codex，然后在 IDE 中跟踪进度并审查结果，而无需离开当前工作环境。
当你从本地对话启动云端任务时，Codex 会记住对话上下文，这样你可以在之后从相同位置继续进行。
7. 云端任务后续（Cloud task follow-up）
Codex 扩展让你轻松预览云端变更，你可以要求后续任务在云端运行，但通常你也可以将更改应用到本地以测试和完成任务，在本地继续对话时，Codex 仍会保留上下文以节省时间。
8. 将图片拖放到提示中
你可以将图片拖放到提示编辑器中作为上下文内容（按住 Shift 拖放图片），在 VS Code 中默认阻止扩展接收拖放，所以必须这样操作。
如果要更改设置，需要按照下面步骤操作：
注意： 有些行为（例如默认模型、审批策略和沙箱设置）不在编辑器设置中配置，而是在共享的 ~/.codex/config.toml 文件中设置（与 Codex CLI 共用）。
以下是可以在编辑器中直接配置的设置项及其含义：
| 设置项 | 说明 |
|---|---|
| chatgpt.cliExecutable | 仅限开发用途：指定 Codex CLI 可执行文件的路径,一般不需要手动设置，手动设置可能会导致扩展部分功能异常 |
| chatgpt.commentCodeLensEnabled | 在待办（TODO）注释上方显示 CodeLens，让你可以用 Codex 快速完成这些待办项。 |
| chatgpt.localeOverride | Codex UI 界面的首选语言，留空表示自动检测语言。 |
| chatgpt.openOnStartup | 启动扩展时自动聚焦到 Codex 侧边栏。 |
| chatgpt.runCodexInWindowsSubsystemForLinux | 仅 Windows 平台：当 Windows Subsystem for Linux（WSL）可用时，是否在 WSL 中运行 Codex，推荐开启以提升沙箱安全性和性能，目前在 Windows 上运行 Codex Agent 模式需要 WSL。更改此项后需要重新加载 VS Code 才会生效。 |
这是 Codex IDE 扩展 在 VS Code（及兼容 IDE）命令面板 中可用的命令列表，可以从命令面板运行这些命令，也可以将它们绑定到快捷键。如果想为某个 Codex 命令分配或更改快捷键，按如下步骤执行：
Step 1：打开命令面板：
Step 2：运行 Preferences: Open Keyboard Shortcuts（首选项：打开键盘快捷键）。
Step 3： 搜索 “Codex” 或命令 ID（例如 chatgpt.newChat）。
Step 4： 点击铅笔图标，然后输入你想使用的快捷键。
| 命令 ID | 默认快捷键 | 说明 |
|---|---|---|
| chatgpt.addToThread | - | 将选中的文本片段作为上下文添加到当前会话线程中。 |
| chatgpt.addFileToThread | - | 将当前整个文件作为上下文添加到当前会话线程中。 |
| chatgpt.newChat | macOS: Cmd + N Windows/Linux: Ctrl + N |
创建一个新的对话线程。 |
| chatgpt.implementTodo | - | 让 Codex 处理当前选中的 TODO 注释。 |
| chatgpt.newCodexPanel | - | 打开一个新的 Codex 面板。 |
| chatgpt.openSidebar | - | 打开 Codex 侧边栏面板。 |
这些命令可以更方便地与 Codex 交互并控制它在 IDE 中的工作方式。
斜杠命令是一种快速控制 Codex 的方式，在聊天输入中输入 / 然后选择或输入命令名称即可执行特定动作，具体的使用方式如下：
/。/status）。可用的斜杠命令 列表：
| 斜杠命令 | 说明 |
|---|---|
| /auto-context | 开启或关闭自动上下文功能，让 Codex 自动包括最近打开的文件和 IDE 上下文。 |
| /cloud | 切换到 云端模式，让任务在远程云环境执行（需要已启用云访问权限）。 |
| /cloud-environment | 选择要使用的云环境（仅在云端模式下可用）。 |
| /feedback | 打开反馈对话框，提交反馈内容，并可附带日志。 |
| /local | 切换到 本地模式，在本地工作区运行任务。 |
| /review | 启动代码复查模式，用于查看未提交的更改或与某个基础分支比较。 |
| /status | 显示当前线程 ID、上下文使用情况和速率限制等状态信息。 |
原文地址：https://developers.openai.com/codex/cli
视频地址：https://youtu.be/iqNzfK4_meQ
Codex CLI 是 OpenAI 发布的 终端编码代理工具，可以在本地的终端（Terminal / Shell）中运行它。Codex CLI 能 读取、修改和执行代码，与目录中的代码库交互，帮助你处理各种开发任务（包括编辑文件、运行命令等），它是开源的，用 Rust 语言实现，以提高速度和效率。
可以使用包管理器以及Homebrew的方式安装 CLI
# 使用 npm
npm install -g @openai/codex
# 使用 Homebrew 安装（macOS）
brew install --cask codexbash
安装完成后，在终端输入 codex 运行即可，首次运行时需要登录认证你的 ChatGPT 账户或使用 API Key。
运行：输入 codex 启动交互式会话，它会读取当前目录，生成和执行命令，并在全屏交互模式下与 Codex 进行对话。
1. 交互式模式（Interactive Mode）:运行 codex 不带参数时进入交互式界面，你可以在这个界面中：
2. 恢复会话：Codex 会保存历史会话，你可以使用命令恢复之前的工作状态，这样 Codex 可以继续利用已有的上下文，而不必重新输入信息
codex resume —— 选择并恢复某个会话codex resume --last —— 恢复最近一次的会话3.模型切换与推理设置：在 CLI 会话中，Codex 默认使用与平台匹配的模型，也可以使用 /model 命令或启动参数指定不同模型：
gpt-5-codexgpt-54. 图片输入：Codex CLI 支持将图片作为输入上下文，例如屏幕截图或设计规范，也可以同时附带多张图片（用逗号分隔）：
codex -i 错误截图.png "解释这个错误"bash
5.本地代码审查模式：在 CLI 中输入 /review 即可启动代码审查功能，这一过程不会修改你的工作区；建议在 pull request 之前使用。
6. 网络搜索支持（可选）：可以启用 Codex 调用网络搜索来获取新上下文（需要在配置或命令中启用）。
7. 自动完成 Shell 脚本：执行如下脚本，可以输出对应 shell（bash / zsh / fish 等）的自动补全脚本，方便日常使用
codex completion bashbash
8. 批准模式（Approval Modes）：这些模式控制 Codex 在执行编辑/命令之前是否需要你确认：
9. 自动化脚本（Scripting）：你可以使用子命令 codex exec 运行非交互任务，适合结合脚本或 CI/CD 流程自动化繁琐任务，例如：
codex exec "修复 CI 失败"bash
10. 与 Codex Cloud 集成：使用 codex cloud 命令可以：
例如：
codex cloud exec --env ENV_ID "总结未解决的 bug"bash
这样可以在本地终端启动云端 Codex 任务，并将更改合并到项目中。
11. 斜杠命令（Slash Commands）支持：可以利用以 / 开头的命令快速调用特定工作流，如 /review、/fork 或自定义的命令。
12. 模型上下文协议（MCP）支持：Codex CLI 也可以通过 Model Context Protocol（MCP） 连接到扩展工具，例如语言服务器或外部数据源，让 AI 能访问更多的上下文资源
下面是 Codex CLI（命令行界面） 的功能说明
交互模式（Interactive Mode）
运行命令：
codex
codex "Explain this codebase to me"bash
启动全屏终端 UI，你可以通过自然语言提示让 Codex 读取代码库、生成修改、执行命令 并实时互动。也可以发送提示、代码片段、甚至图像（截图）、实时查看 Codex 的计划，并批准或拒绝它要执行的步骤。
恢复会话（Resuming Conversations）
Codex 会将会话记录保存在本地，因此可以恢复之前的工作状态：
codex resume —— 选择并恢复某个交互式会话codex resume --last —— 恢复最近的一次codex resume <SESSION_ID> —— 根据 ID 直接恢复某次会话例如：
codex exec resume --last "Fix the race conditions you found"
codex exec resume 7f9f9a2e-1b3c-4c7a-9b0e-.... "Implement the plan"shell
恢复会话时，Codex 会保留历史对话、计划记录和批准状态，这样能继续用已有上下文工作。
模型与推理（Models and Reasoning）
默认情况下：
可以通过命令 /model 或 CLI 启动参数来切换模型。
codex --model gpt-5-codexshell
图像输入（Image Inputs）
你可以在命令行 中附带一或多张图片，让 Codex 一起分析图像内容，例如设计图、错误截图等：
codex -i screenshot.png "解释这个错误"
codex --image img1.png,img2.jpg "Summarize these diagrams"bash
支持常见格式（如 PNG、JPEG）并可以多个文件一起输入。
本地代码审查（Local Code Review）
在 CLI 中输入 /review，启动代码审查模式。可以：
Codex 会输出重点反馈，而不会自动更改文件。
网络搜索（Web Search）
Codex CLI 内置可选的网络搜索功能：
[features]
web_search_request = true
[sandbox_workspace_write]
network_access = trueshell
命令行提示执行（Running with an Input Prompt）
可以直接在命令行后跟提示，让 Codex 读取当前目录、规划步骤并返回结果，而不打开交互界面，并结合 --path、--model 等参数进一步控制行为。
codex "解释这个代码库"bash
Shell 自动补全（Shell Completions）
可以生成并安装自动补全脚本（bash/zsh/fish），让终端支持，然后将补全脚本加入你的 shell 配置文件，实现按 Tab 自动补全命令和参数。
codex completion bash
codex completion zsh
codex completion fishbash
批准模式（Approval Modes）
批准模式控制 Codex 在执行修改/命令前是否需要你的确认：
自动化与脚本运行（Scripting）
可以通过 codex exec 子命令让 Codex 非交互式执行任务，输出结果或计划到标准输出，方便结合脚本和自动化工作流，这对 自动化任务、CI/CD 流程非常有用。
codex exec "修复 CI 失败"bash
与 Codex Cloud 集成（Cloud Tasks）
可以使用：
codex cloud exec --env ENV_ID "Summarize open bugs"bash
在 CLI 中浏览、启动云端任务，并可以将任务生成的更改应用到本地项目，无需离开终端。
斜杠命令支持（Slash Commands）
命令行中也支持以 / 开头的快捷命令，例如：
/review/fork这些命令可以快速执行特定工作流。
提示编辑器（Prompt Editor）
在 CLI 会话中按 Ctrl+G 可打开系统定义的编辑器（如 Vim / VS Code），便于输入、修改大量提示文本，然后发送回 Codex 执行。
Model Context Protocol（MCP） 支持
Codex CLI 支持通过 MCP 协议连接额外工具和数据源：
~/.codex/config.toml 配置 MCP 服务器其他实用提示（Tips & Shortcuts）
下面是提升使用体验的快捷操作：
@ 在当前工作区快速模糊搜索文件路径! 执行本地 shell 命令codex --cd <目录>--add-dir 等| 键 | 类型 / 值 | 说明 |
|---|---|---|
--add-dir |
path | 在主工作区之外，额外授予目录写权限。可重复指定多个路径。 |
--ask-for-approval, -a |
untrusted | on-failure |
--cd, -C |
path | 在代理开始处理请求之前设置工作目录。 |
--config, -c |
key=value | 覆盖配置值。如果可能，值会按 JSON 解析；否则使用字面字符串。 |
--dangerously-bypass-approvals-and-sandbox, --yolo |
boolean | 在不请求批准且不使用沙箱的情况下运行所有命令。仅应在外部已加固的环境中使用。 |
--disable |
feature | 强制禁用某个功能标志（等价于 -c features.<name>=false）。可重复。 |
--enable |
feature | 强制启用某个功能标志（等价于 -c features.<name>=true）。可重复。 |
--full-auto |
boolean | 低摩擦本地工作的快捷方式：设置 --ask-for-approval on-request 和 --sandbox workspace-write。 |
--image, -i |
path[,path…] | 向初始提示附加一个或多个图像文件。多个路径用逗号分隔，或重复该标志。 |
--model, -m |
string | 覆盖配置中的模型（例如 gpt-5-codex）。 |
--oss |
boolean | 使用本地开源模型提供方（等价于 -c model_provider="oss"）。会验证 Ollama 是否正在运行。 |
--profile, -p |
string | 从 ~/.codex/config.toml 中加载的配置 profile 名称。 |
--sandbox, -s |
read-only | workspace-write |
--search |
boolean | 启用网络搜索。为 true 时，代理可在无需每次询问的情况下调用 web_search 工具。 |
PROMPT |
string | 用于启动会话的可选文本指令。省略则直接启动 TUI，不预填消息。 |
这些选项适用于基础 codex 命令，并会传递给每个子命令，除非下方某个部分另有说明。
在使用子命令时，请将全局标志放在子命令之后（例如 codex exec --oss ...），以确保它们按预期生效。
Maturity（成熟度）列使用诸如 Experimental（实验）、Beta（测试）、Stable（稳定） 等标签。
| 键 | 成熟度 | 说明 |
|---|---|---|
codex |
Stable | 启动终端 UI。接受上述全局标志以及可选提示或图像附件。 |
codex app-server |
Experimental | 启动 Codex 应用服务器，用于本地开发或调试。 |
codex apply |
Stable | 将 Codex Cloud 任务生成的最新 diff 应用到本地工作树。别名：codex a。 |
codex cloud |
Experimental | 在不打开 TUI 的情况下，从终端浏览或执行 Codex Cloud 任务。别名：codex cloud-tasks。 |
codex completion |
Stable | 生成 Bash、Zsh、Fish 或 PowerShell 的 shell 自动补全脚本。 |
codex exec |
Stable | 非交互方式运行 Codex。别名：codex e。将结果流式输出到 stdout 或 JSONL，并可恢复之前的会话。 |
codex execpolicy |
Experimental | 评估 execpolicy 规则文件，查看某个命令会被允许、提示还是阻止。 |
codex login |
Stable | 使用 ChatGPT OAuth、设备认证或通过 stdin 传入的 API key 进行认证。 |
codex logout |
Stable | 移除已存储的认证凭据。 |
codex mcp |
Experimental | 管理 Model Context Protocol 服务器（列出、添加、删除、认证）。 |
codex mcp-server |
Experimental | 将 Codex 本身作为 MCP 服务器通过 stdio 运行，供其他代理使用。 |
codex resume |
Stable | 通过 ID 继续先前的交互式会话，或恢复最近一次对话。 |
codex sandbox |
Experimental | 在 Codex 提供的 macOS seatbelt 或 Linux landlock 沙箱中运行任意命令。 |
在没有子命令的情况下运行 codex 会启动交互式终端 UI（TUI）。代理接受上述全局标志以及图像附件。使用 --search 启用网页浏览，使用 --full-auto 允许 Codex 在大多数情况下无需提示即可运行命令。
在本地启动 Codex 应用服务器,主要用于开发和调试，接口和行为可能随时更改，不另行通知。
将 Codex 云任务生成的最新 diff 应用到本地仓库,必须已经认证，并且对该任务有访问权限。
| 键 | 类型 / 值 | 说明 |
|---|---|---|
| TASK_ID | string | 要应用 diff 的 Codex Cloud 任务标识符。 |
Codex 会打印被打补丁的文件；如果 git apply 失败（例如发生冲突），将以非零状态码退出。
从终端与 Codex Cloud 任务交互，默认命令会打开交互式选择器，codex cloud exec 会直接提交一个任务。
| 键 | 类型 / 值 | 说明 |
|---|---|---|
| –attempts | 1–4 | Codex Cloud 运行的助手尝试次数（best-of-N）。 |
| –env | ENV_ID | 目标 Codex Cloud 环境标识符（必填）。使用 codex cloud 查看可选项。 |
| QUERY | string | 任务提示。如果省略，Codex 会交互式询问细节。 |
认证方式与主 CLI 相同，若任务提交失败，Codex 会以非零状态码退出。
生成 shell 自动补全脚本，并将输出重定向到合适的位置，例如：codex completion zsh > "${fpath[1]}/_codex"
| 键 | 类型 / 值 | 说明 |
|---|---|---|
| SHELL | bash、zsh 、 fish 、 power-shell 、 elvish | 要生成补全脚本的 shell，输出打印到 stdout。 |
使用 codex exec（或简写 codex e）进行脚本化或 CI 场景的运行，这类运行应当在无需人工交互的情况下完成。
| 键 | 类型 / 值 | 说明 |
|---|---|---|
--cd, -C |
path | 在执行任务前设置工作区根目录。 |
--color |
always 、never 、 auto | 控制 stdout 中的 ANSI 颜色。 |
--dangerously-bypass-approvals-and-sandbox, --yolo |
boolean | 跳过批准提示和沙箱。危险——仅在隔离的执行环境中使用。 |
--full-auto |
boolean | 应用低摩擦自动化预设（workspace-write 沙箱 + on-request 批准）。 |
--image, -i |
path[,path…] | 将图像附加到第一条消息。可重复；支持逗号分隔。 |
--json, --experimental-json |
boolean | 输出逐行 JSON 事件，而不是格式化文本。 |
--model, -m |
string | 覆盖本次运行使用的模型。 |
--oss |
boolean | 使用本地开源模型提供方（需要运行中的 Ollama 实例）。 |
--output-last-message, -o |
path | 将助手的最终消息写入文件，便于后续脚本处理。 |
--output-schema |
path | 描述期望最终响应结构的 JSON Schema 文件。Codex 会校验工具输出。 |
--profile, -p |
string | 选择在 config.toml 中定义的配置 profile。 |
--sandbox, -s |
read-only | workspace-write |
--skip-git-repo-check |
boolean | 允许在非 Git 仓库目录中运行（适用于一次性目录）。 |
-c, --config |
key=value | 为非交互式运行内联覆盖配置（可重复）。 |
PROMPT |
string | -（从 stdin 读取） |
codex exec resume [SESSION_ID]shell
通过 ID 恢复一个 exec 会话，或使用 --last 继续最近一次会话，可接受一个可选的后续提示。默认情况下 Codex 会输出格式化文本，添加 --json 可获得逐行 JSON 事件（每次状态变化一条）。
| 键 | 类型 / 值 | 说明 |
|---|---|---|
--last |
boolean | 跳过选择器，自动恢复最近一次对话。 |
PROMPT |
string 、 - |
恢复后立即发送的可选后续指令。 |
SESSION_ID |
uuid | 恢复指定会话；若省略则需使用 --last。 |
在保存 execpolicy 规则文件前进行检查。codex execpolicy check 接受一个或多个 --rules 标志（例如 ~/.codex/rules 下的文件），并输出 JSON，展示最严格的决策结果及匹配到的规则，添加 --pretty 可格式化输出，execpolicy 当前处于预览阶段。
| 键 | 类型 / 值 | 说明 |
|---|---|---|
--pretty |
boolean | 美化打印 JSON 结果。 |
--rules, -r |
path（可重复） | 要评估的 execpolicy 规则文件路径。可组合多个文件。 |
COMMAND... |
var-args | 要根据指定策略进行检查的命令。 |
使用 ChatGPT 账户或 API key 对 CLI 进行认证,不带标志时，Codex 会打开浏览器进入 ChatGPT OAuth 流程。
| 键 | 类型 | 说明 |
|---|---|---|
--with-api-key |
boolean | 从 stdin 读取 API key（例如 printenv OPENAI_API_KEY | codex login --with-api-key）。 |
| status、subcommand | codex login status | 打印当前激活的认证方式；在已登录时以状态码 0 退出，便于自动化脚本判断。 |
移除已保存的 API key 和 ChatGPT 认证凭据，该命令没有任何标志。
管理存储在 ~/.codex/config.toml 中的 Model Context Protocol 服务器条目。
| 子命令 | 选项 | 说明 |
|---|---|---|
add <name> |
-- <command...> |
--url <value> |
get <name> |
--json |
显示指定服务器配置，--json 输出原始配置条目 |
list |
--json |
列出已配置的 MCP 服务器，--json 用于机器可读输出 |
login <name> |
--scopes scope1,scope2 |
对支持 OAuth 的可流式 HTTP 服务器发起登录 |
logout <name> |
移除该 HTTP 服务器的 OAuth 凭据 | |
remove <name> |
删除已存储的 MCP 服务器定义 |
add 子命令的额外选项：
| 键 | 类型 / 值 | 说明 |
|---|---|---|
--bearer-token-env-var |
ENV_VAR | 连接可流式 HTTP 服务器时，将该环境变量的值作为 bearer token 发送。 |
--env KEY=VALUE |
可重复 | 启动 stdio 服务器时设置的环境变量。 |
--url |
https://… | 注册可流式 HTTP 服务器，与 COMMAND... 互斥。 |
COMMAND... |
stdio transport | 启动 MCP 服务器的可执行程序及其参数，放在 -- 之后。 |
OAuth 操作（login、logout）仅适用于可流式 HTTP 服务器，且服务器必须支持 OAuth。
通过 stdio 将 Codex 作为 MCP 服务器运行，以供其他工具连接，该命令会继承全局配置覆盖，并在下游客户端关闭连接时退出。
通过 ID 继续一个交互式会话，或恢复最近一次对话，codex resume 接受与 codex 相同的全局标志，包括模型和沙箱覆盖。
| 键 | 类型 / 值 | 说明 |
|---|---|---|
--last |
boolean | 跳过选择器，自动恢复最近一次对话。 |
PROMPT |
string | - |
SESSION_ID |
uuid | 恢复指定会话；若省略则需使用 --last。 |
使用沙箱辅助工具，在与 Codex 内部相同的策略下运行命令。
macOS Seatbelt：
| 键 | 类型 / 值 | 说明 |
|---|---|---|
--config, -c |
key=value | 向沙箱运行传入配置覆盖（可重复）。 |
--full-auto |
boolean | 无需批准地授予当前工作区和 /tmp 的写权限。 |
COMMAND... |
var-args | 在 macOS Seatbelt 下执行的 shell 命令，-- 之后的内容会被原样转发。 |
Linux Landlock:
| 键 | 类型 / 值 | 说明 |
|---|---|---|
--config, -c |
key=value | 在启动沙箱前应用的配置覆盖（可重复）。 |
--full-auto |
boolean | 在 Landlock 沙箱内授予当前工作区和 /tmp 的写权限。 |
COMMAND... |
var-args | 在 Landlock + seccomp 下执行的命令，可执行程序放在 -- 之后。 |
标志组合与安全建议:
--full-auto，但避免与 --dangerously-bypass-approvals-and-sandbox 组合使用，除非你身处专用的沙箱虚拟机中。--add-dir，而不是强制使用 --sandbox danger-full-access。--json 与 --output-last-message 搭配使用，可同时捕获机器可读的进度信息和最终的自然语言总结。斜杠命令能让你在交互式 Codex 会话中快速使用键盘进行控制。在对话输入框中输入 / 会出现斜杠命令弹窗，选择命令后，Codex 会执行对应操作，比如切换模型、调整审批设置，或在不离开终端的情况下总结长对话。下面是一些常用命令及其作用：
| 命令 | 作用 |
|---|---|
/approvals |
设置 Codex 在无需再次询问的情况下可以执行哪些类型的操作（调整审批策略）。 |
/compact |
总结当前可见对话内容，以节省上下文空间。 |
/diff |
显示 Git 差异，包括未被 Git 跟踪的文件。 |
/exit 或 /quit |
退出 CLI 会话。 |
/feedback |
发送日志和诊断信息给 Codex 维护者。 |
/init |
在当前目录生成一个 AGENTS.md 初始文件。 |
/logout |
登出 Codex（清除本地凭据）。 |
/mcp |
列出当前可用的 Model Context Protocol 工具。 |
/mention |
将某个文件附加到当前对话，让 Codex 关注它。 |
/model |
选择当前使用的模型。 |
/fork |
将已保存的会话分支为新线程。 |
/resume |
恢复一个已保存的会话。 |
/new |
在当前 CLI 会话里开始一个新的对话。 |
/review |
请求 Codex 审查当前工作目录的更改。 |
/status |
显示当前会话状态，例如活跃模型、审批策略、Token 使用情况等。 |
当然还可以创建属于自己的重复使用的提示（带参数或元数据），让它们像斜杠命令一样被调用，例如：
/prompts:<命令名>shell
在 Composer 中输入：
/modelshell
然后在弹出列表中选择所需的模型，例如 gpt-4.1-mini 或其他更深层次模型。
Codex 会确认模型已切换。使用 /status 可验证当前设置。([OpenAI][1])
输入：
/approvalsshell
然后选择适合的审批预设，比如 “Auto”（自动审批）或 “Read Only”（只读模式）。未来操作将按照这个策略执行。
在任何对话中输入：
/statusshell
Codex 会显示当前会话的主要信息，包括活跃模型、审批策略、可写根目录和当前上下文使用情况。
当对话很长时，使用：
/compactshell
Codex 会将已有对话摘要化，压缩内容以腾出更多上下文空间。
输入：
/diffshell
可以查看 Git diff 内容，包括已暂存和未暂存的变更，以及未被 Git 管理的文件，以便你决定接下来怎么处理。
输入：
/mention <路径>shell
可以让 Codex 将某个文件加入当前对话上下文，让后续操作更聚焦于该文件。
Codex 是 OpenAI 提供的智能编码代理，它可以读取、编辑并运行代码，帮助开发者更快地构建功能、修复错误、理解不熟悉的代码库等，通过 Codex 云端（Cloud），这些任务可以在后台由 Codex 的云环境并行执行，从而提升效率和自动化程度。 ([OpenAI][1])
Codex 云端实际上是 Codex 在云上的运行模式，在这种模式下：
Codex 云端如何设置
要在云端使用 Codex，需要：
Codex 云端带来的优势
Codex 云端是一个面向未来的软件工程智能体，它在云环境中后台执行代码任务，通过与 GitHub 和 IDE 的深度集成，让开发者能够更快速地完成复杂开发流程，无论是个人开发者还是大型团队，都可以借助 Codex 云端提升开发效率和协作效果。
使用 环境（environments） 来控制 Codex 在云端任务运行期间安装和执行的内容。
例如：
这些配置可以在 Codex 设置 中完成。
Codex 云任务如何运行？
当提交一个任务时，大致会发生以下流程：
Step 1: Codex 创建一个容器（container），并在指定的分支或指定的 commit SHA 处检出你的代码仓库（checkout）。
Step 2: Codex 运行你的 setup 脚本，必要时也会运行维护脚本（maintenance script），尤其是在使用缓存容器时。
Step 3: Codex 会应用你的 Internet 设置。
Step 4： Agent 会循环运行终端命令：
AGENTS.md 文件，agent 会使用它来了解项目的具体命令（例如运行测试、lint）。Step 5： 当任务完成后，结果会展示出来，并显示对文件的 diff（变更），然后你可以选择打开 Pull Request 或继续提出后续问题。
默认容器镜像（Default universal image）
Codex agent 在默认的容器镜像 universal 中运行，该镜像预装了常见语言、库和工具，在环境设置中，你可以选择固定 Python、Node.js 等运行时的版本，如果需要更多软件包，也可以通过 setup 脚本手动安装。
环境变量与密钥（Environment variables 和 secrets）
环境变量在任务全过程（setup 脚本 + agent 阶段）中有效。Secrets（密钥）在运行期间会被加密存储，仅在 setup 脚本阶段解密可用，为安全起见，在 agent 阶段会被移除。
自动与手动设置
自动设置：对于常用包管理工具（如 npm、yarn、pip、poetry 等），Codex 可以自动安装依赖和工具。
手动设置： 如果你的开发环境更复杂，也可以提供自定义 setup 脚本，例如：
# 安装类型检查器
pip install pyright
# 安装项目依赖
poetry install --with test
pnpm installbash
注意：setup 脚本与 agent 阶段分别在不同的 Bash 会话中运行，因此像
export这样的命令不会带到 agent 阶段。如果希望变量在 agent 阶段持续有效，请在~/.bashrc中设置，或者在环境设置中新增这些变量。
容器缓存（Container caching）
Codex 会缓存容器状态最长 12 小时，以加速后续任务和后续对话，当使用缓存容器时：
网络访问与代理
原文地址：https://developers.openai.com/codex/cloud/internet-access
默认情况下，在 agent 执行阶段，Codex 不允许访问互联网，但可以在环境设置中为特定环境开启访问，并精细控制访问范围。
网络访问默认行为
启用互联网访问的风险
在 agent 执行阶段开启互联网访问可能带来安全问题，包括：
配置互联网访问（按环境设置）
Off（关闭）：完全阻止 agent 在执行阶段访问互联网，这是默认设置。
On（开启） + 自定义控制：开启后你可以进一步控制域名允许列表（Domain Allowlist），可以选择：
之后还能手动添加或移除特定域名。
允许的 HTTP 方法
为了安全起见，你可以限定 agent 仅允许某些 HTTP 方法，例如：GET、HEAD、OPTIONS 等安全方法，禁止危险方法如 POST、PUT、DELETE 等，减少意外行为风险。
域名允许列表示例
官方提供了一个 常见依赖域名列表（Common dependencies），包括：
alpinelinux.org
anaconda.com
apache.org
apt.llvm.org
archlinux.org
azure.com
bitbucket.org
bower.io
centos.org
cocoapods.org
continuum.io
cpan.org
crates.io
debian.org
docker.com
docker.io
dot.net
dotnet.microsoft.com
eclipse.org
fedoraproject.org
gcr.io
ghcr.io
github.com
githubusercontent.com
gitlab.com
golang.org
google.com
goproxy.io
gradle.org
hashicorp.com
haskell.org
hex.pm
java.com
java.net
jcenter.bintray.com
json-schema.org
json.schemastore.org
k8s.io
launchpad.net
maven.org
mcr.microsoft.com
metacpan.org
microsoft.com
nodejs.org
npmjs.com
npmjs.org
nuget.org
oracle.com
packagecloud.io
packages.microsoft.com
packagist.org
pkg.go.dev
ppa.launchpad.net
pub.dev
pypa.io
pypi.org
pypi.python.org
pythonhosted.org
quay.io
ruby-lang.org
rubyforge.org
rubygems.org
rubyonrails.org
rustup.rs
rvm.io
sourceforge.net
spring.io
swift.org
ubuntu.com
visualstudio.com
yarnpkg.com
…plaintext
这些域名通常用于下载包、获取源代码、构建依赖等。
原文地址：https://developers.openai.com/codex/integrations/github
视频教程：https://youtu.be/HwbSWVg5Ln4
可以使用 Codex 在 GitHub 的 Pull Request（拉取请求）中执行代码审查，而无需离开 GitHub 界面。具体做法是在 Pull Request 的评论里写下@codex review，然后 Codex 会自动回复一个标准的 GitHub 代码审查。
在某个 Pull Request 里发表评论，写上@codex review
然后等待 Codex 处理并发布审查结果，就像一个团队成员那样发表评论。
默认情况下，Codex 会根据你的代码库中的 AGENTS.md 文件应用一些审查指南。你可以在仓库顶层添加或更新 AGENTS.md，写下自定义的审核规则。例如：
## Review guidelines
- 不要打印敏感个人信息（PII）。
- 确保每个路由都被身份验证中间件包裹。shell
这样，Codex 会按照这些规则执行审查，如果你在 Pull Request 评论里写类似：
@codex review for security regressionsshell
Codex 会根据语义做更具体的审查。
当你在评论里提到 @codex 并跟随其他指令（不是 review），Codex 会在云端将这个 Pull Request 作为上下文来创建一个新任务。例如：
@codex fix the CI failuresshell
Codex 会尝试定位并修复 CI（持续集成）失败的问题。
可以在 Slack 的频道或线程里调用 Codex 来执行编码任务。只需在消息中提及 @Codex 并附上提示，Codex 会创建一个 云任务 并回复结果。
@Codex：如果还没添加，Slack 会在你提及时提示。在 Slack 的某个频道或线程内，提及 @Codex 并写出你的提示。Codex 能引用线程内早先的消息，因此通常不需要重复背景上下文。可以在提示里指定环境或仓库，这样能明确 Codex 使用哪个环境或代码仓库，例如：
@Codex 修复上面的内容 在 openai/codexshell
等待 Codex 做出反应并回复一个任务链接，任务完成后，Codex 会将结果发布在该线程中（视设置而定）。
默认情况下，Codex 会在线程中发布结果，这可能包括它所运行环境的信息。如果你希望 Codex 只发送任务链接而不包含答案，企业管理员可以在 ChatGPT 工作区设置中关闭 “允许 Codex Slack 应用在任务完成时发布答案” 选项。
当提及 @Codex 时，Slack 的消息内容和线程历史会被发送给 Codex 以理解请求并创建任务。数据处理遵循 OpenAI 隐私政策、使用条款 以及其他适用政策。
注意：Codex 使用大型语言模型生成回答，它可能会犯错。请始终自行复查结果和 diff。
常见问题及解决方法：
请在 openai/openai 环境运行），然后再次 mention @Codex。原文地址：https://developers.openai.com/codex/integrations/linear
如果在 Linear 任务中运行 Codex，可以：
@Codex，Codex 会创建一个云端任务并回复进度与结果。按照下面步骤配置 Linear 与 Codex 的联动：
@Codex 来 链接你的 Linear 账户。你可以通过下面两种方式委派任务：
1) 将 issue 分配给 Codex：安装并启用集成后，你可以像将任务分配给团队成员一样，将 issue 分配给 Codex。 Codex 会开始处理任务，并在 issue 中发布进度更新。
2) 在评论中提及 @Codex：也可以在评论中写 @Codex 来委派任务或提问。Codex 回复后，你可以在同一个评论线程中继续提问或增加说明以延续当前会话。
Codex 开始工作后，会根据 issue 内容选择 合适的环境和仓库，如果你想指定固定仓库，可以在评论中写清楚，例如：
@Codex fix this in openai/codexplaintext
如果建议不明确，Codex 会采用最近一次使用的环境。任务默认运行在该环境仓库列表中第一个仓库的默认分支上。如需更改默认仓库或加入更多仓库，你可以在 Codex 配置中更新环境的仓库映射。
可以 在 issue 的 Activity（活动）视图 中查看更新，点击任务链接查看更详细的进度，当任务完成后，Codex 会发布摘要并附上完成任务的链接，你可以据此创建 Pull Request（PR）。
可以通过设置 triage rules（初筛规则）自动将新 issue 分派给 Codex：
当使用 triage 规则自动委派时，Codex 会使用 issue 创建者的账户 来运行任务。
当你 mention 尽量写清楚你想让 Codex 做什么，因为 Codex 会读取这段内容来理解请求并生成任务。数据处理遵循 OpenAI 的隐私政策与使用条款；详见官方文档。 Codex 生成的内容可能不总是正确，你仍需手动审核其回答和 diffs（变更差异）。
连接失败：如果 Codex 无法确认链接，它会在 issue 中回复一个连接账户的链接。
环境被选错了：在评论中补充你想要的环境，这样可指导 Codex 选择正确环境执行任务，例如：
@Codex please run this in openai/codexplaintext
代码上下文不准确或不完整：提供更多上下文或明确指令，有助于 Codex 更准确完成任务。
查看更多帮助：可以查阅 OpenAI 的帮助中心获取更完整的说明。
如果你想让 Codex 在本地访问 Linear issue（如通过 CLI 或 IDE 扩展），可以使用 Codex 的 MCP（Model Context Protocol）服务器，推荐方法（CLI）
codex mcp add linear --url https://mcp.linear.app/mcpbash
执行后系统会提示登录 Linear，完成账户连接。也可以使用手动方法，在 ~/.codex/config.toml 文件中添加：
[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"toml
然后运行，即可手动连接 Linear：
codex mcp login linearbash
好，这里给你一版第一人称（博主视角）+ 精简概括型的整篇博客文末总结，偏“收束观点 + 给读者方向”，不铺细节、不啰嗦：
到这里，本文从 IDE、CLI、Web（Cloud），一直到 GitHub / Slack / Linear 等集成平台，系统梳理了 Codex 在不同使用端的形态与适用场景。可以看到，Codex 并不是单一形态的“写代码工具”，而是一套可以嵌入个人开发与团队工程流程的 工程级编程智能体。
在博主看来，使用 Codex 的关键不在于“功能是否齐全”，而在于是否把它放在合适的位置：
当你不再纠结 “用不用 Codex”，而是开始思考“这一类工程问题该不该交给 Codex”，它的价值才会真正体现出来。希望本文能帮助大家，感谢阅读，本文完！
在前几篇文章里，博主已经编写了Codex相关的文章，有兴趣的童鞋可以先阅读：
Codex 会在本地执行命令、读写文件、请求审批，其行为几乎完全由 ~/.codex/config.toml 决定。默认配置虽然安全，但在真实工程场景下往往限制较多。
本文将围绕 Codex 的配置体系展开，从基础配置到高级用法，重点说明每个关键配置项的作用与影响范围，帮助大家快速搭建一套符合自己工作流的 Codex 运行环境。
Codex 会从 ~/.codex/config.toml 读取本地设置，你可以使用这个文件来更改默认值 （比如模型）、设置审批与沙箱行为，以及配置 MCP 服务器。
Codex 将其配置存储在：~/.codex/config.toml，要从 Codex IDE 扩展打开该配置文件：
CLI 与 IDE 扩展共用同一个 config.toml 文件。你可以使用它来：
Codex 在解析值时遵循以下顺序：
--model）；--profile <名称> 指定的配置文件值（Profile）；config.toml 顶层值；使用这种优先级意味着你可以在顶层设置共享默认值，将可变的值保持在 Profile 中，要进行单次覆盖（包括 TOML 引号规则），请参阅高级配置（Advanced Config）：https://developers.openai.com/codex/config-advanced#one-off-overrides-from-the-cli
备注：在受管理的机器上，你的组织也可能通过
requirements.toml强制执行约束，例如不允许approval_policy = "never"或sandbox_mode = "danger-full-access"。
以下是最常修改的一些配置，所有示例都在 config.toml 顶层配置中设置。
① 默认模型：选择 CLI 和 IDE 中 Codex 默认使用的模型
model = "gpt-5.2"shell
② 审批提示： 控制 Codex 在执行生成命令之前何时暂停询问
approval_policy = "on-request"shell
③ 沙箱级别：调整 Codex 在执行命令时对文件系统和网络访问的程度
sandbox_mode = "workspace-write"shell
④ 推理强度：调整在模型支持时 Codex 使用多少推理 能力
model_reasoning_effort = "high"shell
⑤ 命令环境：限制或扩展哪些环境变量会被传递给被启动的命令：
[shell_environment_policy]
include_only = ["PATH", "HOME"]shell
可选的实验性功能可以通过 config.toml 中的 [features] 表来切换：
[features]
shell_snapshot = true # 加快重复命令的速度
web_search_request = true # 允许模型请求网页搜索shell
支持的功能（成熟度标签表示该功能的稳定性与实验性质，可以根据需要选择开启或保持默认）：
| 键 | 默认值 | 成熟度 | 描述 |
|---|---|---|---|
| apply_patch_freeform | false | Experimental | 包含自由形式的 apply_patch 工具 |
| elevated_windows_sandbox | false | Experimental | 使用提升权限的 Windows 沙箱 |
| exec_policy | true | Experimental | 对 shell / unified_exec 强制策略检查 |
| experimental_windows_sandbox | false | Experimental | 使用 Windows 限制令牌沙箱 |
| remote_compaction | true | Experimental | 启用远程压缩（仅限 ChatGPT 授权） |
| remote_models | false | Experimental | 刷新远程模型列表以显示可用性 |
| shell_snapshot | false | Beta | 快速完成重复命令 |
| shell_tool | true | Stable | 启用默认的 shell 工具 |
| unified_exec | false | Beta | 使用统一的 PTY 执行工具 |
| undo | true | Stable | 支持通过每次操作的 git 快照进行撤销 |
| web_search_request | false | Stable | 允许模型发起网页搜索请求 |
如果要快速启用某个功能，可以 在 config.toml 的 [features] 部分添加：
feature_name = trueshell
或者从命令行运行：
codex --enable feature_nameshell
如果要同时启用多个功能：
codex --enable feature_a --enable feature_bshell
要停用某个功能，将其设置为：
feature_name = falseshell
这样就可以灵活控制 Codex 的实验性与高级功能。
Profiles 允许你保存一组具名的配置集合，并在 CLI 中快速切换。
Profiles 目前仍处于实验阶段，未来版本中可能会变更或移除；
Codex IDE 扩展目前 不支持 Profiles。
在 config.toml 中通过 [profiles.<name>] 定义profiles，然后运行：
codex --profile <name>bash
示例：
model = "gpt-5-codex"
approval_policy = "on-request"
[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"
[profiles.lightweight]
model = "gpt-4.1"
approval_policy = "untrusted"toml
如果你想让某个 profile 成为默认值，可在 config.toml 顶层添加：
profile = "deep-review"toml
除非在命令行中显式覆盖，否则 Codex 会自动加载该 profile。
除了编辑 ~/.codex/config.toml 之外，你还可以在 单次运行时 通过 CLI 覆盖配置：
--model）-c / --config示例：
# 专用参数
codex --model gpt-5.2
# 通用键值覆盖（值是 TOML，而不是 JSON）
codex --config model='"gpt-5.2"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'bash
注意事项：
mcp_servers.context7.enabled=false）；--config 的值会按 TOML 解析；shell 按空格拆分，如果无法解析为 TOML，Codex 会将其当作字符串处理。Codex 会将本地状态存储在 CODEX_HOME 目录下（默认是 ~/.codex），你可能会看到的常见文件包括：
config.toml：本地配置；auth.json：使用文件方式存储凭据时或系统的 keychain / keyring；history.jsonl：启用历史记录持久化时，其他每用户状态，例如日志和缓存。关于认证（包括凭据存储方式）的更多细节，请参见 Authentication，完整配置键列表请参见 Configuration Reference。
Codex 会从当前工作目录向上查找项目配置（例如 .codex/ 层级和 AGENTS.md），直到找到“项目根目录”，默认情况下，只要目录中包含 .git，就会被视为项目根目录，可以在 config.toml 中自定义该行为：
# 当目录中包含以下任意标记时，将其视为项目根目录
project_root_markers = [".git", ".hg", ".sl"]toml
如果设置为空数组：
project_root_markers = []toml
则 Codex 不再向上搜索父目录，而是将当前工作目录视为项目根目录。
模型提供方定义了 Codex 如何连接模型（基础 URL、API 协议、可选 HTTP 头），你可以定义额外的提供方，并通过 model_provider 指向它们：
model = "gpt-5.1"
model_provider = "proxy"
[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"
[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"toml
如有需要，可添加请求头：
[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }toml
如果你只是想让内置 OpenAI 提供方指向一个 LLM 代理或路由器，可以直接设置 OPENAI_BASE_URL，无需修改 config.toml：
export OPENAI_BASE_URL="https://api.openai.com/v1"
codexbash
当你使用 --oss 参数时，Codex 可以运行在本地“开源”模型提供方之上（例如 Ollama 或 LM Studio），如果使用 --oss 但未指定提供方，Codex 会使用 oss_provider 作为默认值：
# 使用 --oss 时的默认本地提供方
oss_provider = "ollama" # 或 "lmstudio"toml
[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
[model_providers.openai]
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000toml
model_reasoning_summary = "none" # 禁用推理摘要
model_verbosity = "low" # 缩短回复
model_supports_reasoning_summaries = true # 强制启用推理
model_context_window = 128000 # 上下文窗口大小toml
model_verbosity仅对使用 Responses API 的提供方生效。 Chat Completions 提供方会忽略该设置。
选择审批严格度（影响 Codex 何时暂停）以及沙箱级别（影响文件 / 网络访问）。更深入的示例请参见 Sandbox & approvals。
approval_policy = "untrusted" # 其他选项：on-request, on-failure, never
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
exclude_tmpdir_env_var = false # 允许 $TMPDIR
exclude_slash_tmp = false # 允许 /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false # 是否允许外部网络访问toml
在
workspace-write模式下，某些环境仍会将.git/和.codex/设为只读。因此，即使工作区可写，git commit等命令仍可能需要审批，如果你希望 Codex 跳过特定命令（例如阻止沙箱外的git commit），请使用 rules。
完全禁用沙箱（⚠️仅在你的环境已自行隔离进程时使用）：
sandbox_mode = "danger-full-access"toml
shell_environment_policy 控制 Codex 启动子进程时传递哪些环境变量（例如执行模型提出的工具命令时）。可以从一个干净环境（inherit = "none"）或精简环境（inherit = "core"）开始，再叠加排除、包含和覆盖规则，避免泄露密钥，同时仍保留必要路径或标志。
[shell_environment_policy]
inherit = "none"
set = { PATH = "/usr/bin", MY_FLAG = "1" }
ignore_default_excludes = false
exclude = ["AWS_*", "AZURE_*"]
include_only = ["PATH", "HOME"]toml
匹配规则为不区分大小写的 glob 模式（*, ?, [A-Z]）。当 ignore_default_excludes = false 时，会在你自定义规则前自动过滤 KEY/SECRET/TOKEN。
你可以启用 OpenTelemetry（OTel）日志导出，用于跟踪 Codex 运行情况（API 请求、SSE 事件、提示词、工具审批 / 结果等）。默认关闭，需要在 [otel] 中显式启用：
[otel]
environment = "staging" # 默认为 "dev"
exporter = "none" # 可设为 otlp-http 或 otlp-grpc
log_user_prompt = false # 默认不记录用户提示内容toml
选择导出器：
[otel]
exporter = { otlp-http = {
endpoint = "https://otel.example.com/v1/logs",
protocol = "binary",
headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}toml
[otel]
exporter = { otlp-grpc = {
endpoint = "https://otel.example.com:4317",
headers = { "x-otlp-meta" = "abc123" }
}}toml
当 exporter = "none" 时，Codex 会记录事件但不会发送，导出器会异步批量发送，并在退出时刷新。
会发送哪些事件？
Codex 会为运行和工具使用发送结构化日志事件，示例包括：
codex.conversation_starts(model, reasoning settings, sandbox/approval policy)codex.api_request and codex.sse_event (durations, status, token counts)codex.user_prompt(length; content redacted unless explicitly enabled)codex.tool_decision (approved/denied and whether the decision came from config vs user)codex.tool_result (duration, success, output snippet)更详细的安全与隐私说明请参见 Security。
指标（Metrics）
默认情况下，Codex 会周期性地向 OpenAI 发送少量匿名使用与健康数据，用于检测故障并了解功能使用情况。这些数据 不包含任何 PII（个人可识别信息），如需完全关闭指标收集：
[analytics]
enabled = falsetoml
默认上下文字段（适用于所有事件 / 指标）
surfaceversionauth_modemodel指标目录
| Metric | Type | Fields | Description |
|---|---|---|---|
features.state |
counter | key, value |
Feature values that differ from defaults (emit one row per non-default). |
thread.started |
counter | is_git |
New thread created. |
task.compact |
counter | type |
Number of compactions per type (remote or local), including manual and auto. |
task.user_shell |
counter | Number of user shell actions (! in the TUI for example). |
|
task.review |
counter | Number of reviews triggered. | |
approval.requested |
counter | tool, approved |
Tool approval request result (approved: yes or no). |
conversation.turn.count |
counter | User/assistant turns per thread, recorded at the end of the thread. | |
mcp.call |
counter | status |
MCP tool invocation result (ok or error string). |
model.call.duration_ms |
histogram | status, attempt |
Model API request duration. |
tool.call |
counter | tool, status |
Tool invocation result (ok or error string). |
tool.call.duration_ms |
histogram | tool, success |
Tool execution time. |
user.feedback.submitted |
counter | category, include_logs, success |
Feedback submission via /feedback. |
反馈控制
默认支持通过 /feedback 提交反馈，如需禁用：
[feedback]
enabled = falsetoml
隐藏或显示推理事件
hide_agent_reasoning = true
show_raw_agent_reasoning = truetoml
仅在你的工作流允许的情况下启用原始推理内容。
通知
使用 notify 在 Codex 触发事件时调用外部程序（目前支持 agent-turn-complete）。
notify = ["python3", "/path/to/notify.py"]toml
示例脚本：
#!/usr/bin/env python3
import json, subprocess, sys
def main() -> int:
notification = json.loads(sys.argv[1])
if notification.get("type") != "agent-turn-complete":
return 0
title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
message = " ".join(notification.get("input-messages", []))
subprocess.check_output([
"terminal-notifier",
"-title", title,
"-message", message,
"-group", "codex-" + notification.get("thread-id", ""),
"-activate", "com.googlecode.iterm2",
])
return 0
if __name__ == "__main__":
sys.exit(main())python
历史记录持久化
默认情况下，Codex 会将会话记录保存在 CODEX_HOME 下：
[history]
persistence = "none"toml
限制历史文件大小：
[history]
max_bytes = 104857600 # 100 MiBtoml
可点击的文件引用
file_opener = "vscode" # 或 cursor, windsurf, vscode-insiders, nonetoml
Codex 会读取 AGENTS.md 并在会话首轮中注入项目指引，相关配置：
project_doc_max_bytesproject_doc_fallback_filenames详见 Custom instructions with AGENTS.md。
TUI（终端界面）选项
直接运行 codex 会启动交互式 TUI，专属配置位于 [tui] 下，包括：
tui.notificationstui.animationstui.scroll_*以下是 Codex 的 config.toml 和 requirements.toml 的完整参考文档。
用户级别的配置位于：~/.codex/config.toml
| Key | Type / Values | Details |
|---|---|---|
| approval_policy | untrusted | on-failure |
| chatgpt_base_url | string | 覆盖 ChatGPT 登录流程中使用的基础 URL。 |
| check_for_update_on_startup | boolean | 在启动时检查 Codex 更新（仅在更新由集中管理时才设置为 false）。 |
| cli_auth_credentials_store | file | keyring |
| compact_prompt | string | 内联覆盖用于历史压缩的提示词。 |
| developer_instructions | string | 注入到会话中的额外开发者指令（可选）。 |
| disable_paste_burst | boolean | 在 TUI 中禁用批量粘贴检测。 |
| experimental_compact_prompt_file | string (path) | 从文件加载历史压缩提示词的覆盖版本（实验性）。 |
| experimental_instructions_file | string (path) | 实验性：使用该文件替代内置指令，而不是 AGENTS.md。 |
| experimental_use_freeform_apply_patch | boolean | 启用自由格式 apply_patch 的旧名称；推荐使用 [features].apply_patch_freeform 或 codex --enable apply_patch_freeform。 |
| experimental_use_unified_exec_tool | boolean | 启用 unified exec 的旧名称；推荐使用 [features].unified_exec 或 codex --enable unified_exec。 |
| features.apply_patch_freeform | boolean | 暴露自由格式的 apply_patch 工具（实验性）。 |
| features.elevated_windows_sandbox | boolean | 启用提升权限的 Windows 沙箱管道（实验性）。 |
| features.exec_policy | boolean | 对 shell / unified_exec 强制执行规则检查（实验性；默认开启）。 |
| features.experimental_windows_sandbox | boolean | 运行 Windows 受限令牌沙箱（实验性）。 |
| features.powershell_utf8 | boolean | 强制 PowerShell 使用 UTF-8 输出（默认 true）。 |
| features.remote_compaction | boolean | 启用远程历史压缩（仅 ChatGPT 登录；实验性；默认开启）。 |
| features.remote_models | boolean | 在显示就绪状态前刷新远程模型列表（实验性）。 |
| features.shell_snapshot | boolean | 对 shell 环境进行快照以加速重复命令（beta）。 |
| features.shell_tool | boolean | 启用默认的 shell 工具以运行命令（稳定版；默认开启）。 |
| features.tui2 | boolean | 启用 TUI2 界面（实验性）。 |
| features.unified_exec | boolean | 使用统一的、基于 PTY 的 exec 工具（beta）。 |
| features.web_search_request | boolean | 允许模型发起 Web 搜索请求（稳定）。 |
| feedback.enabled | boolean | 通过 /feedback 启用跨 Codex 界面的反馈提交（默认 true）。 |
| file_opener | vscode | vscode-insiders |
| forced_chatgpt_workspace_id | string (uuid) | 将 ChatGPT 登录限制到指定的工作区标识符。 |
| forced_login_method | chatgpt | api |
| hide_agent_reasoning | boolean | 在 TUI 和 codex exec 输出中隐藏推理事件。 |
| history.max_bytes | number | 如果设置，将通过丢弃最旧条目来限制历史文件大小（字节）。 |
| history.persistence | save-all | none |
| include_apply_patch_tool | boolean | 启用自由格式 apply_patch 的旧名称；推荐使用 [features].apply_patch_freeform。 |
| instructions | string | 保留供未来使用；推荐使用 experimental_instructions_file 或 AGENTS.md。 |
| mcp_oauth_credentials_store | auto | file |
| mcp_servers..args | array | 传递给 MCP stdio server 命令的参数。 |
| mcp_servers..bearer_token_env_var | string | 为 MCP HTTP server 提供 bearer token 的环境变量。 |
| mcp_servers..command | string | MCP stdio server 的启动命令。 |
| mcp_servers..cwd | string | MCP stdio server 进程的工作目录。 |
| mcp_servers..disabled_tools | array | 在 enabled_tools 之后应用的工具拒绝列表。 |
| mcp_servers..enabled | boolean | 在不移除配置的情况下禁用 MCP server。 |
| mcp_servers..enabled_tools | array | MCP server 暴露的工具名称白名单。 |
| mcp_servers..env | map<string,string> | 转发给 MCP stdio server 的环境变量。 |
| mcp_servers..env_http_headers | map<string,string> | 从环境变量填充的 HTTP Header（用于 MCP HTTP server）。 |
| mcp_servers..env_vars | array | 额外允许的 MCP stdio server 环境变量白名单。 |
| mcp_servers..http_headers | map<string,string> | 每次 MCP HTTP 请求都会包含的静态 Header。 |
| mcp_servers..startup_timeout_ms | number | startup_timeout_sec 的毫秒别名。 |
| mcp_servers..startup_timeout_sec | number | 覆盖 MCP server 默认 10 秒的启动超时。 |
| mcp_servers..tool_timeout_sec | number | 覆盖 MCP server 默认 60 秒的单工具超时。 |
| mcp_servers..url | string | MCP 可流式 HTTP server 的端点。 |
| model | string | 使用的模型（例如 gpt-5-codex）。 |
| model_auto_compact_token_limit | number | 触发自动历史压缩的 token 阈值（未设置则使用模型默认值）。 |
| model_context_window | number | 当前模型可用的上下文窗口 token 数。 |
| model_provider | string | 来自 model_providers 的 provider id（默认：openai）。 |
| model_providers..base_url | string | 模型提供方的 API 基础 URL。 |
| model_providers..env_http_headers | map<string,string> | 从环境变量填充的 HTTP Header。 |
| model_providers..env_key | string | 提供方 API Key 所在的环境变量。 |
| model_providers..env_key_instructions | string | 可选的 API Key 配置说明。 |
| model_providers..experimental_bearer_token | string | 直接提供 bearer token（不推荐；请使用 env_key）。 |
| model_providers..http_headers | map<string,string> | 添加到提供方请求中的静态 HTTP Header。 |
| model_providers..name | string | 自定义模型提供方的显示名称。 |
| model_providers..query_params | map<string,string> | 附加到请求中的额外查询参数。 |
| model_providers..request_max_retries | number | 提供方 HTTP 请求的最大重试次数（默认 4）。 |
| model_providers..requires_openai_auth | boolean | 提供方是否使用 OpenAI 认证（默认 false）。 |
| model_providers..stream_idle_timeout_ms | number | SSE 流的空闲超时（毫秒，默认 300000）。 |
| model_providers..stream_max_retries | number | SSE 流中断的最大重试次数（默认 5）。 |
| model_providers..wire_api | chat | responses |
| model_reasoning_effort | minimal | low |
| model_reasoning_summary | auto | concise |
| model_supports_reasoning_summaries | boolean | 即使是未知模型也强制 Codex 发送推理元数据。 |
| model_verbosity | low | medium |
| notice.hide_full_access_warning | boolean | 记录是否确认“完全访问权限”警告。 |
| notice.hide_gpt-5.1-codex-max_migration_prompt | boolean | 记录是否确认 gpt-5.1-codex-max 迁移提示。 |
| notice.hide_gpt5_1_migration_prompt | boolean | 记录是否确认 GPT-5.1 迁移提示。 |
| notice.hide_rate_limit_model_nudge | boolean | 记录是否选择退出速率限制模型切换提示。 |
| notice.hide_world_writable_warning | boolean | 记录是否确认 Windows 全局可写目录警告。 |
| notice.model_migrations | map<string,string> | 记录已确认的模型迁移映射（旧 → 新）。 |
| notify | array | 用于通知的命令；会接收来自 Codex 的 JSON 负载。 |
| oss_provider | lmstudio | ollama |
| otel.environment | string | 应用于 OpenTelemetry 事件的环境标签（默认 dev）。 |
| otel.exporter | none | otlp-http |
| otel.exporter..endpoint | string | OTEL 日志导出端点。 |
| otel.exporter..headers | map<string,string> | OTEL 导出请求中包含的静态 Header。 |
| otel.exporter..protocol | binary | json |
| otel.exporter..tls.ca-certificate | string | OTEL 导出器 TLS 的 CA 证书路径。 |
| otel.exporter..tls.client-certificate | string | OTEL 导出器 TLS 的客户端证书路径。 |
| otel.exporter..tls.client-private-key | string | OTEL 导出器 TLS 的客户端私钥路径。 |
| otel.log_user_prompt | boolean | 选择是否在 OpenTelemetry 日志中导出原始用户提示词。 |
| otel.trace_exporter | none | otlp-http |
| otel.trace_exporter..endpoint | string | Trace 导出端点。 |
| otel.trace_exporter..headers | map<string,string> | Trace 导出请求的静态 Header。 |
| otel.trace_exporter..protocol | binary | json |
| otel.trace_exporter..tls.ca-certificate | string | Trace 导出器 TLS 的 CA 证书路径。 |
| otel.trace_exporter..tls.client-certificate | string | Trace 导出器 TLS 的客户端证书路径。 |
| otel.trace_exporter..tls.client-private-key | string | Trace 导出器 TLS 的客户端私钥路径。 |
| profile | string | 启动时应用的默认 profile（等价于 --profile）。 |
| profiles..* | various | 对任意支持配置项的 profile 级别覆盖。 |
| profiles..experimental_use_freeform_apply_patch | boolean | 启用自由格式 apply_patch 的旧名称。 |
| profiles..experimental_use_unified_exec_tool | boolean | 启用 unified exec 的旧名称。 |
| profiles..include_apply_patch_tool | boolean | 启用自由格式 apply_patch 的旧名称。 |
| profiles..oss_provider | lmstudio | ollama |
| project_doc_fallback_filenames | array | 当 AGENTS.md 缺失时尝试的额外文件名。 |
| project_doc_max_bytes | number | 构建项目指令时从 AGENTS.md 读取的最大字节数。 |
| project_root_markers | array | 用于查找项目根目录的标记文件名列表。 |
| projects. .trust_level | string | 将项目或 worktree 标记为受信任或不受信任（"trusted" |
| review_model | string | /review 使用的模型覆盖。 |
| sandbox_mode | read-only | workspace-write |
| sandbox_workspace_write.exclude_slash_tmp | boolean | 在 workspace-write 模式下排除 /tmp。 |
| sandbox_workspace_write.exclude_tmpdir_env_var | boolean | 在 workspace-write 模式下排除 $TMPDIR。 |
| sandbox_workspace_write.network_access | boolean | 允许 workspace-write 沙箱内的外部网络访问。 |
| sandbox_workspace_write.writable_roots | array | workspace-write 模式下额外的可写目录。 |
| shell_environment_policy.exclude | array | 默认处理后移除的环境变量 glob 模式。 |
| shell_environment_policy.experimental_use_profile | boolean | 生成子进程时使用用户 shell profile。 |
| shell_environment_policy.ignore_default_excludes | boolean | 在其他过滤前保留包含 KEY/SECRET/TOKEN 的变量。 |
| shell_environment_policy.include_only | array | 白名单模式，仅保留匹配的变量。 |
| shell_environment_policy.inherit | all | core |
| shell_environment_policy.set | map<string,string> | 注入到每个子进程的显式环境变量。 |
| show_raw_agent_reasoning | boolean | 当模型输出推理时展示原始推理内容。 |
| skills.config | array | 存储在 config.toml 中的技能级别启用配置。 |
| skills.config..enabled | boolean | 启用或禁用对应技能。 |
| skills.config..path | string (path) | 包含 SKILL.md 的技能目录路径。 |
| tool_output_token_limit | number | 单个工具/函数输出存入历史的 token 上限。 |
| tui | table | TUI 专用选项，例如启用桌面内联通知。 |
| tui.animations | boolean | 启用终端动画（欢迎页、闪光、加载器）（默认 true）。 |
| tui.notifications | boolean | array |
| tui.scroll_events_per_tick | number | TUI2 中用于标准化滚动的事件密度。 |
| tui.scroll_invert | boolean | 反转 TUI2 的鼠标滚动方向。 |
| tui.scroll_mode | auto | wheel |
| tui.scroll_trackpad_accel_events | number | 触发 +1x 加速所需的触控板事件数。 |
| tui.scroll_trackpad_accel_max | number | 触控板滚动的最大加速倍数。 |
| tui.scroll_trackpad_lines | number | TUI2 的触控板滚动基础灵敏度。 |
| tui.scroll_wheel_like_max_duration_ms | number | 自动模式下回退为滚轮的持续时间阈值（毫秒）。 |
| tui.scroll_wheel_lines | number | TUI2 中每次滚轮刻度滚动的行数。 |
| tui.scroll_wheel_tick_detect_max_ms | number | 自动模式下滚轮刻度检测阈值（毫秒）。 |
| tui.show_tooltips | boolean | 在 TUI 欢迎界面显示新手提示（默认 true）。 |
| windows_wsl_setup_acknowledged | boolean | 记录 Windows 引导流程的确认状态（仅 Windows）。 |
requirements.toml 是由管理员强制执行的配置文件，用于限制用户无法覆盖的安全敏感设置。
有关详情、路径和示例，请参见 Admin-enforced requirements
| Key | Type / Values | Details |
|---|---|---|
| allowed_approval_policies | array<string> |
approval_policy 允许使用的取值。 |
| allowed_sandbox_modes | array<string> |
sandbox_mode 允许使用的取值。 |
下面的代码片段可以作为参考使用，只需将配置项和配置段复制到 ~/.codex/config.toml 中，然后根据你的实际环境调整相应的值。
# Codex 示例配置（config.toml）
#
# 本文件列出了 Codex 会从 config.toml 读取的所有键、它们的默认值，
# 以及简要说明。这里的值与 CLI 编译进来的“实际默认值”一致。
# 可按需调整。
#
# 备注
# - 根级键必须出现在 TOML 的表（table）之前。
# - 默认值为 “未设置（unset）” 的可选键会以注释形式展示并附带说明。
# - MCP 服务器、profiles（配置文件）以及模型提供方都是示例；可删除或修改。
################################################################################
# 核心模型选择
################################################################################
# Codex 使用的主模型。默认：所有平台均为 "gpt-5.2-codex"。
model = "gpt-5.2-codex"
# /review 功能（代码审查）使用的模型。默认："gpt-5.2-codex"。
review_model = "gpt-5.2-codex"
# 从 [model_providers] 中选择的提供方 id。默认："openai"。
model_provider = "openai"
# 用于 --oss 会话的默认开源提供方。未设置时，Codex 会提示选择。默认：未设置。
# oss_provider = "ollama"
# 可选的手动模型元数据。未设置时，Codex 会根据 model 自动检测。
# 取消注释以强制指定这些值。
# model_context_window = 128000 # token 数；默认：按模型自动决定
# model_auto_compact_token_limit = 0 # token 数；未设置时使用模型默认值
# tool_output_token_limit = 10000 # 每个工具输出存储的 token 数；对 gpt-5.2-codex 默认是 10000
################################################################################
# 推理与详细度（支持 Responses API 的模型）
################################################################################
# 推理强度：minimal | low | medium | high | xhigh（默认：medium；在 gpt-5.2-codex 与 gpt-5.2 上为 xhigh）
model_reasoning_effort = "medium"
# 推理摘要：auto | concise | detailed | none（默认：auto）
model_reasoning_summary = "auto"
# GPT-5 系列（Responses API）的文本输出详细度：low | medium | high（默认：medium）
model_verbosity = "medium"
# 为当前模型强制启用推理摘要（默认：false）
model_supports_reasoning_summaries = false
################################################################################
# 指令覆盖
################################################################################
# 额外的用户指令会在 AGENTS.md 之前注入。默认：未设置。
# developer_instructions = ""
#（已忽略）可选的旧版基础指令覆盖（建议使用 AGENTS.md）。默认：未设置。
# instructions = ""
# 历史压缩提示词（compaction prompt）的内联覆盖。默认：未设置。
# compact_prompt = ""
# 用文件路径覆盖内置的基础指令。默认：未设置。
# experimental_instructions_file = "/absolute/or/relative/path/to/instructions.txt"
# 从文件加载历史压缩提示词覆盖。默认：未设置。
# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"
################################################################################
# 通知
################################################################################
# 外部通知程序（argv 数组）。未设置时：禁用。
# 示例：notify = ["notify-send", "Codex"]
notify = [ ]
################################################################################
# 审批与沙箱
################################################################################
# 何时请求命令审批：
# - untrusted：仅已知安全的只读命令自动执行；其余命令会提示确认
# - on-failure：在沙箱中自动执行；仅在失败时提示升级/放权
# - on-request：由模型决定何时询问（默认）
# - never：从不询问（风险较大）
approval_policy = "on-request"
# 工具调用的文件系统/网络沙箱策略：
# - read-only（默认）
# - workspace-write
# - danger-full-access（无沙箱；极其危险）
sandbox_mode = "read-only"
################################################################################
# 认证与登录
################################################################################
# CLI 登录凭据的持久化方式：file（默认） | keyring | auto
cli_auth_credentials_store = "file"
# ChatGPT 认证流程的基础 URL（不是 OpenAI API）。默认：
chatgpt_base_url = "https://chatgpt.com/backend-api/"
# 将 ChatGPT 登录限制到指定 workspace id。默认：未设置。
# forced_chatgpt_workspace_id = ""
# 当 Codex 通常会自动选择时，强制指定登录机制。默认：未设置。
# 可选值：chatgpt | api
# forced_login_method = "chatgpt"
# MCP OAuth 凭据的首选存储方式：auto（默认） | file | keyring
mcp_oauth_credentials_store = "auto"
################################################################################
# 项目文档控制
################################################################################
# 从 AGENTS.md 中最多嵌入到首轮指令的字节数。默认：32768
project_doc_max_bytes = 32768
# 当某一层目录缺少 AGENTS.md 时，按顺序尝试的备用文件名。默认：[]
project_doc_fallback_filenames = []
# 在向上查找父目录时，用来识别项目根目录的标记文件名。默认：[".git"]
# project_root_markers = [".git"]
################################################################################
# 历史与文件打开方式
################################################################################
# 可点击引用（citations）的 URI scheme：vscode（默认） | vscode-insiders | windsurf | cursor | none
file_opener = "vscode"
################################################################################
# UI、通知与杂项
################################################################################
# 抑制内部推理事件的输出。默认：false
hide_agent_reasoning = false
# 当可用时显示原始推理内容。默认：false
show_raw_agent_reasoning = false
# 禁用 TUI 中的“突发粘贴（burst-paste）”检测。默认：false
disable_paste_burst = false
# 记录 Windows 入门设置确认（仅 Windows）。默认：false
windows_wsl_setup_acknowledged = false
# 启动时检查更新。默认：true
check_for_update_on_startup = true
################################################################################
# Profiles（命名预设）
################################################################################
# 当前启用的 profile 名称。未设置时，不应用任何 profile。
# profile = "default"
################################################################################
# Skills（按技能覆盖）
################################################################################
# 在不删除技能的情况下禁用或重新启用某个技能。
[[skills.config]]
# path = "/path/to/skill"
# enabled = false
################################################################################
# 实验性开关（旧版；优先使用 [features]）
################################################################################
experimental_use_unified_exec_tool = false
# 通过自由编辑路径包含 apply_patch（影响默认工具集）。默认：false
experimental_use_freeform_apply_patch = false
################################################################################
# 沙箱设置（表）
################################################################################
# 仅在 sandbox_mode = "workspace-write" 时使用的额外设置。
[sandbox_workspace_write]
# 除工作区（cwd）外额外允许写入的根目录。默认：[]
writable_roots = []
# 允许在沙箱内进行出站网络访问。默认：false
network_access = false
# 将 $TMPDIR 从可写根目录中排除。默认：false
exclude_tmpdir_env_var = false
# 将 /tmp 从可写根目录中排除。默认：false
exclude_slash_tmp = false
################################################################################
# 生成子进程的 Shell 环境策略（表）
################################################################################
[shell_environment_policy]
# inherit：all（默认） | core | none
inherit = "all"
# 对名称包含 KEY/SECRET/TOKEN（不区分大小写）的变量，跳过默认排除规则。默认：true
ignore_default_excludes = true
# 要移除的（不区分大小写）glob 模式（例如："AWS_*", "AZURE_*"）。默认：[]
exclude = []
# 显式 key/value 覆盖（始终优先）。默认：{}
set = {}
# 白名单；若非空，则只保留匹配的变量。默认：[]
include_only = []
# 实验性：通过用户 shell profile 运行。默认：false
experimental_use_profile = false
################################################################################
# 历史（表）
################################################################################
[history]
# save-all（默认） | none
persistence = "save-all"
# 历史文件最大字节数；超过后会裁剪最旧条目。示例：5242880
# max_bytes = 0
################################################################################
# UI、通知与杂项（表）
################################################################################
[tui]
# 来自 TUI 的桌面通知：布尔值或过滤列表。默认：true
# 示例：false | ["agent-turn-complete", "approval-requested"]
notifications = false
# 启用欢迎/状态/加载动画。默认：true
animations = true
# 在欢迎界面显示入门提示。默认：true
show_tooltips = true
# 可选的 TUI2 滚动调优（未设置则使用默认值）。
# scroll_events_per_tick = 0
# scroll_wheel_lines = 0
# scroll_trackpad_lines = 0
# scroll_trackpad_accel_events = 0
# scroll_trackpad_accel_max = 0
# scroll_mode = "auto" # auto | wheel | trackpad
# scroll_wheel_tick_detect_max_ms = 0
# scroll_wheel_like_max_duration_ms = 0
# scroll_invert = false
# 控制用户是否可以通过 `/feedback` 提交反馈。默认：true
[feedback]
enabled = true
# 产品内提示（多由 Codex 自动设置）。
[notice]
# hide_full_access_warning = true
# hide_world_writable_warning = true
# hide_rate_limit_model_nudge = true
# hide_gpt5_1_migration_prompt = true
# "hide_gpt-5.1-codex-max_migration_prompt" = true
# model_migrations = { "gpt-4.1" = "gpt-5.1" }
################################################################################
# 集中式功能开关（推荐）
################################################################################
[features]
# 将该表留空即可接受默认值。设置显式布尔值以选择加入/退出。
shell_tool = true
web_search_request = false
unified_exec = false
shell_snapshot = false
apply_patch_freeform = false
exec_policy = true
experimental_windows_sandbox = false
elevated_windows_sandbox = false
remote_compaction = true
remote_models = false
powershell_utf8 = true
tui2 = false
################################################################################
# 在此表下定义 MCP 服务器。留空则禁用。
################################################################################
[mcp_servers]
# --- 示例：STDIO 传输 ---
# [mcp_servers.docs]
# enabled = true # 可选；默认 true
# command = "docs-server" # 必填
# args = ["--port", "4000"] # 可选
# env = { "API_KEY" = "value" } # 可选：按原样复制的 key/value
# env_vars = ["ANOTHER_SECRET"] # 可选：从父进程环境转发这些变量
# cwd = "/path/to/server" # 可选：工作目录覆盖
# startup_timeout_sec = 10.0 # 可选；默认 10.0 秒
# # startup_timeout_ms = 10000 # 可选：启动超时（毫秒）的别名
# tool_timeout_sec = 60.0 # 可选；默认 60.0 秒
# enabled_tools = ["search", "summarize"] # 可选：允许列表
# disabled_tools = ["slow-tool"] # 可选：禁用列表（在允许列表之后生效）
# --- 示例：可流式 HTTP 传输 ---
# [mcp_servers.github]
# enabled = true # 可选；默认 true
# url = "https://github-mcp.example.com/mcp" # 必填
# bearer_token_env_var = "GITHUB_TOKEN" # 可选；Authorization: Bearer <token>
# http_headers = { "X-Example" = "value" } # 可选：静态请求头
# env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选：从环境变量填充的请求头
# startup_timeout_sec = 10.0 # 可选
# tool_timeout_sec = 60.0 # 可选
# enabled_tools = ["list_issues"] # 可选：允许列表
################################################################################
# 模型提供方（扩展/覆盖内置）
################################################################################
# 内置包括：
# - openai（Responses API；需要登录或通过认证流程提供 OPENAI_API_KEY）
# - oss（Chat Completions API；默认指向 http://localhost:11434/v1）
[model_providers]
# --- 示例：用显式 base URL 或 headers 覆盖 OpenAI ---
# [model_providers.openai]
# name = "OpenAI"
# base_url = "https://api.openai.com/v1" # 未设置时的默认值
# wire_api = "responses" # "responses" | "chat"（默认因情况而异）
# # requires_openai_auth = true # 内置 OpenAI 默认 true
# # request_max_retries = 4 # 默认 4；最大 100
# # stream_max_retries = 5 # 默认 5；最大 100
# # stream_idle_timeout_ms = 300000 # 默认 300_000（5 分钟）
# # experimental_bearer_token = "sk-example" # 可选：仅开发用途的直接 bearer token
# # http_headers = { "X-Example" = "value" }
# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }
# --- 示例：Azure（根据端点选择 Chat/Responses）---
# [model_providers.azure]
# name = "Azure"
# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
# wire_api = "responses" # 或按端点使用 "chat"
# query_params = { api-version = "2025-04-01-preview" }
# env_key = "AZURE_OPENAI_API_KEY"
# # env_key_instructions = "在环境变量中设置 AZURE_OPENAI_API_KEY"
# --- 示例：本地 OSS（例如 Ollama 兼容）---
# [model_providers.ollama]
# name = "Ollama"
# base_url = "http://localhost:11434/v1"
# wire_api = "chat"
################################################################################
# Profiles（命名预设）
################################################################################
[profiles]
# [profiles.default]
# model = "gpt-5.2-codex"
# model_provider = "openai"
# approval_policy = "on-request"
# sandbox_mode = "read-only"
# oss_provider = "ollama"
# model_reasoning_effort = "medium"
# model_reasoning_summary = "auto"
# model_verbosity = "medium"
# chatgpt_base_url = "https://chatgpt.com/backend-api/"
# experimental_compact_prompt_file = "./compact_prompt.txt"
# include_apply_patch_tool = false
# experimental_use_unified_exec_tool = false
# experimental_use_freeform_apply_patch = false
# tools_web_search = false
# features = { unified_exec = false }
################################################################################
# Projects（信任级别）
################################################################################
# 将特定 worktree 标记为可信或不可信。
[projects]
# [projects."/absolute/path/to/project"]
# trust_level = "trusted" # 或 "untrusted"
################################################################################
# OpenTelemetry（OTEL）- 默认禁用
################################################################################
[otel]
# 在日志中包含用户提示文本。默认：false
log_user_prompt = false
# 应用于遥测数据的环境标签。默认："dev"
environment = "dev"
# 导出器：none（默认） | otlp-http | otlp-grpc
exporter = "none"
# Trace 导出器：none（默认） | otlp-http | otlp-grpc
trace_exporter = "none"
# 示例：OTLP/HTTP 导出器配置
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs"
# protocol = "binary" # "binary" | "json"
# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}"
# 示例：OTLP/gRPC 导出器配置
# [otel.exporter."otlp-grpc"]
# endpoint = "https://otel.example.com:4317",
# headers = { "x-otlp-meta" = "abc123" }
# 示例：带双向 TLS 的 OTLP 导出器
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs"
# protocol = "binary"
# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}"
# [otel.exporter."otlp-http".tls]
# ca-certificate = "certs/otel-ca.pem"
# client-certificate = "/etc/codex/certs/client.pem"
# client-private-key = "/etc/codex/certs/client-key.pem"bash
本文从工程实践角度，系统整理了 Codex 的基础配置与高级配置方式。合理配置 approval_policy、sandbox_mode、模型与 Profiles，是提升 Codex 使用体验的关键。
如果你希望 Codex 在保证安全边界的前提下，尽量减少打断、提高执行效率，建议优先从审批策略与沙箱级别入手进行调整，其余配置按需逐步放开即可。谢谢大家的阅读，本文完。
在前几篇文章里，博主已经编写了Codex相关的文章，有兴趣的童鞋可以先阅读：
在本文中，博主继续整理Codex配置部分的内容，将围绕 Rules、AGENTS.md、自定义提示词 以及 MCP 四个核心主题展开，深入解析 Codex 在安全控制、指令发现、提示复用与工具扩展方面的设计哲学与最佳实践，从而让大家更好地去了解codex。
描述：控制 Codex 在沙箱外可以运行哪些命令
原文地址：https://developers.openai.com/codex/rules
可以使用规则（Rules）来控制 Codex 在沙箱（sandbox）之外可以运行的命令。
Step1：首先在 ~/.codex/rules 目录下创建一个 .rules 文件（例如：~/.codex/rules/default.rules）。
Step2：添加一条规则，下面这个示例会在 允许 gh pr view 在沙箱外运行之前进行提示确认。
# 在沙箱外运行以 `gh pr view` 为前缀的命令前进行提示。
prefix_rule(
# 要匹配的命令前缀。
pattern = ["gh", "pr", "view"],
# 当 Codex 请求运行匹配的命令时采取的动作。
decision = "prompt",
# 该规则存在的可选说明理由。
justification = "在获得批准的情况下允许查看 PR",
# `match` 和 `not_match` 是可选的“内联单元测试”，
# 用于提供应该（或不应该）匹配该规则的命令示例。
match = [
"gh pr view 7888",
"gh pr view --repo openai/codex",
"gh pr view 7888 --json title,body,comments",
],
not_match = [
# 不匹配，因为 `pattern` 必须是一个精确的前缀。
"gh pr --repo openai/codex view 7888",
],
)python
Step3：重启，Codex在启动时加载 ~/.codex/rules 目录下的所有 *.rules 文件，当你在 TUI（终端交互界面）中将某个命令加入允许列表时，Codex 会自动把对应规则追加到~/.codex/rules/default.rules，这样以后运行时就可以跳过提示。
prefix_rule() 支持以下字段：
pattern（必填）：一个非空列表，用于定义要匹配的命令前缀，列表中的每个元素可以是：
"pr"）["view", "list"]），用于在该参数位置匹配多种可能decision（默认值为 "allow"）：当规则匹配时采取的动作，当有多条规则同时匹配时，Codex 会选择限制性最强的决策（forbidden > prompt > allow）。可选值包括：
justification（可选）：一段非空的、对人类可读的规则说明，Codex 可能会在审批提示或拒绝信息中展示该内容。当你使用 forbidden 时，建议在说明中给出可替代方案，例如：“请使用 rg 代替 grep。”
match 和 not_match（默认值为 []）：用于在加载规则时由 Codex 验证的示例命令，它们可以帮助你在规则生效前发现错误配置。
当 Codex 判断是否运行某条命令时，会将该命令的参数列表与
pattern进行比较。在内部，Codex 会把命令当作一个参数数组处理（类似execvp(3)接收到的形式）。
有些工具会把多个 shell 命令包装成一次调用，例如：
["bash", "-lc", "git add . && rm -rf /"]text
由于这种形式可能在一个字符串中隐藏多个操作，
Codex 会对 bash -lc、bash -c 以及它们在 zsh / sh 中的等价形式进行特殊处理。
① 当 Codex 拆分脚本
如果 shell 脚本是一个简单、线性的命令链，并且只包含：
VAR=...、$FOO、* 等）&&、||、; 或 |）那么 Codex 会使用 tree-sitter 对脚本进行解析，并在应用规则之前将其拆分为多个独立命令。
例如，上面的脚本会被拆分为两个命令：
["git", "add", "."]
["rm", "-rf", "/"]text
Codex 会分别对每个命令应用规则，并最终采用限制性最强的结果。因此，即使你允许了：
pattern = ["git", "add"]text
Codex 也不会自动允许：
git add . && rm -rf /text
因为 rm -rf / 会被单独评估，并阻止整个命令的自动执行。这种机制可以防止把危险命令“夹带”在安全命令中一起执行。
② 当Codex 不拆分脚本
如果脚本使用了更复杂的 shell 特性，例如：
>、>>、<）$(...)、...）FOO=bar）*、?）if、for、带赋值的 && 等）那么 Codex 不会尝试解析或拆分脚本。在这种情况下，整个调用会被当作一个单独命令处理：
["bash", "-lc", "<完整脚本>"]text
规则也只会应用在这一次调用上。通过这种特殊处理方式，在安全可解析时实现逐命令评估，在无法确定安全性时采取更保守的行为。
可以使用以下命令来测试规则对某个命令的影响：
codex execpolicy check --pretty \
--rules ~/.codex/rules/default.rules \
-- gh pr view 7888 --json title,body,commentsbash
该命令会输出 JSON，展示：
justification 信息可以使用多个 --rules 参数来组合多个规则文件，并使用 --pretty 让输出结果更易读。
.rules 文件使用 Starlark 语言编写（可参考其语言规范）。它的语法类似 Python，但被设计为安全可执行，规则引擎可以运行它而不会产生副作用（例如访问或修改文件系统）。
描述：为你的项目向 Codex 提供额外的指令和上下文
原文链接：https://developers.openai.com/codex/guides/agents-md
Codex 在开始任何工作之前都会读取 AGENTS.md 文件，通过将全局指导与项目级别的覆盖规则分层组合，你可以在打开任何仓库时，都以一致的预期开始每一个任务。
Codex 在启动时会构建一条指令链（每次运行一次，在 TUI 中通常意味着每次启动一个会话）。指令发现遵循以下优先级顺序：
全局作用域（Global scope）：在你的 Codex 主目录中（默认为 ~/.codex，除非你设置了 CODEX_HOME），Codex 会：
AGENTS.override.md，则读取它AGENTS.md项目作用域（Project scope）：从项目根目录（通常是 Git 根目录）开始，Codex 会向下遍历到你当前的工作目录：
如果 Codex 无法找到项目根目录，则只检查当前目录
在路径上的每一个目录中，依次检查：
AGENTS.override.mdAGENTS.mdproject_doc_fallback_filenames 中配置的备用文件名合并顺序（Merge order）：
Codex 会跳过空文件，并在合并内容达到 project_doc_max_bytes 定义的大小上限时停止（默认是 32 KiB）。有关这些参数的详细说明，请参阅 Project instructions discovery。当你触及大小上限时，可以提高限制，或将指令拆分到更深层的子目录中。
在 Codex 主目录中创建持久化的默认规则，让每一个仓库都能继承你的工作约定。
Step1：需要确保目录存在：
mkdir -p ~/.codexbash
Step2： 创建 ~/.codex/AGENTS.md，写入可复用的偏好设置：
# ~/.codex/AGENTS.md
## Working agreements
- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.md
Step3：在任意位置运行 Codex，确认它加载了该文件：
codex --ask-for-approval never "Summarize the current instructions."bash
预期结果：Codex 会在提出工作建议之前，引用
~/.codex/AGENTS.md中的条目。
当你需要临时的全局覆盖规则而又不想删除基础文件时，可以使用~/.codex/AGENTS.override.md，删除该 override 文件即可恢复共享指引。
仓库级别的文件可以让 Codex 了解项目规范，同时仍然继承你的全局默认规则。
Step1：在仓库根目录中添加 AGENTS.md，用于基础设置：
# AGENTS.md
## Repository expectations
- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.md
Step2：当特定团队需要不同规则时，在子目录中添加覆盖文件
例如，在 services/payments/ 目录下创建 AGENTS.override.md：
# services/payments/AGENTS.override.md
## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.md
Step3：从 payments 目录启动 Codex
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."bash
预期结果：Codex 会依次报告 “全局指令文件” → “仓库根目录的
AGENTS.md” → “payments 目录下的 override 文件（最后加载）”
Codex 在到达当前工作目录后就会停止搜索，因此应尽量将 override 文件放在 最接近具体工作的目录中。添加了全局文件和 payments 专用 override 之后，一个示例仓库结构如下：
如果你的仓库已经使用了不同的文件名（例如 TEAM_GUIDE.md），可以将它加入备用列表，让 Codex 将其视为指令文件。
可以编辑 Codex 配置：
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536toml
然后重启 Codex，或运行一条新命令，使更新后的配置生效，Codex 会按以下顺序检查每个目录：
AGENTS.override.md ↓AGENTS.md ↓TEAM_GUIDE.md ↓.agents.md ↓不在该列表中的文件名将被忽略，更大的字节限制允许在被截断之前合并更多指引内容。在配置了 fallback 列表后，Codex 会将这些替代文件当作指令文件处理：
如果需要使用不同的配置（例如：项目专用的自动化用户）时，可以设置 CODEX_HOME 环境变量：
CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"bash
预期结果：输出会列出相对于自定义 .codex 目录的指令文件。
可以在仓库根目录运行如下命令，Codex 应按优先级顺序回显全局和项目指令：
codex --ask-for-approval never "Summarize the current instructions."bash
使用子目录验证覆盖规则：
codex --cd subdir --ask-for-approval never "Show which instruction files are active."bash
如果需要审计 Codex 加载了哪些指令文件：
~/.codex/log/codex-tui.logsession-*.jsonl 文件如果指令看起来是旧的：
① 什么都没加载
codex status 是否显示了你期望的工作区根目录② 出现了错误的指引
AGENTS.override.md（包括 Codex 主目录）③ Codex 忽略了 fallback 文件名
project_doc_fallback_filenames，且无拼写错误④ 指令被截断
project_doc_max_bytes⑤ 配置档案混乱（Profile confusion）
在启动 Codex 前运行：
echo $CODEX_HOMEbash
非默认值意味着 Codex 正在使用与你编辑的不同主目录
描述：定义可复用的提示，使其像斜杠命令一样工作
原文地址：https://developers.openai.com/codex/custom-prompts
自定义提示允许你将 Markdown 文件 转换为可复用的提示，并且可以在 Codex CLI 和 Codex IDE 扩展中通过斜杠命令来调用。自定义提示需要 显式调用，并且存放在你本地的 Codex 主目录中（例如 ~/.codex），因此不会随着你的代码仓库共享，如果希望共享一个提示（或者希望 Codex 能够隐式调用它），请使用 skills。接下来看看如何自定义提示词。
首先创建 prompts 目录：
mkdir -p ~/.codex/promptsbash
然后创建 ~/.codex/prompts/draftpr.md，并添加可复用的指导内容：
---
description: Prep a branch, commit, and open a draft PR
argument-hint: [FILES=<paths>] [PR_TITLE="<title>"]
---
Create a branch named `dev/<feature_name>` for this work.
If files are specified, stage them first: $FILES.
Commit the staged changes with a clear message.
Open a draft PR on the same branch. Use $PR_TITLE when supplied; otherwise write a concise summary yourself.markdown
最后重启 Codex 以加载新的提示（重启 CLI 会话；如果你在使用 IDE 扩展，请重新加载扩展）。
预期效果：在斜杠命令菜单中输入
/prompts:draftpr，你会看到自定义命令，其描述来自 front matter，并提示文件和 PR 标题是可选参数。
Codex 会在下次会话启动时读取提示元数据并解析占位符。
description: 设置。argument-hint: KEY=<value> 来说明期望的参数。$1 到 $9 会从你在命令后提供的、以空格分隔的参数中展开，$ARGUMENTS 包含所有这些参数。$FILE 或 $TICKET_ID），并通过 KEY=value 形式提供值，包含空格的值需要加引号（例如：FOCUS="loading state"）。$$ 来输出一个单独的 $。prompts 目录中非 Markdown 的文件。在 Codex（CLI 或 IDE 扩展）中，输入 / 打开斜杠命令菜单。输入 prompts: 或直接输入提示名称，例如：
/prompts:draftprtext
提供所需参数：
/prompts:draftpr FILES="src/pages/index.astro src/lib/api.ts" PR_TITLE="Add hero animation"text
按 Enter 发送展开后的指令（当不需要某个参数时，可以省略它）。
预期效果：Codex 会展开
draftpr.md的内容，用你提供的参数替换占位符，然后将结果作为一条消息发送。
可以通过编辑或删除 ~/.codex/prompts/ 目录下的文件来管理提示，Codex 只扫描该文件夹顶层的 Markdown 文件，因此请将每个自定义提示直接放在 ~/.codex/prompts/ 下，而不要放在子目录中。
描述：为 Codex 提供对第三方工具和上下文的访问能力
原文地址：https://developers.openai.com/codex/mcp
模型上下文协议（Model Context Protocol，简称 MCP）用于将模型连接到工具和上下文，你可以使用它让 Codex 访问第三方文档，或让它与开发者工具（如浏览器或 Figma）进行交互，Codex 在 CLI 和 IDE 扩展中都支持 MCP 服务器。
STDIO 服务器：作为本地进程运行的服务器（通过命令启动）
可流式的 HTTP 服务器：通过地址访问的服务器
codex mcp login <server-name>）Codex 会将 MCP 配置存储在 ~/.codex/config.toml 中，与其他 Codex 配置项放在一起，CLI 与 IDE 扩展 共享同一份配置，一旦配置好了 MCP 服务器，就可以在两个 Codex 客户端之间切换，而无需重新设置。
要配置 MCP 服务器，可以选择以下方式之一：
codex mcp 来添加和管理服务器。~/.codex/config.toml。添加一个 MCP 服务器
codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>bash
例如，要添加 Context7（一个免费的开发者文档 MCP 服务器），可以运行以下命令：
codex mcp add context7 -- npx -y @upstash/context7-mcpbash
要查看所有可用的 MCP 命令，可以运行：
codex mcp --helpbash
如果需要对 MCP 服务器选项进行更精细的控制，可以编辑 ~/.codex/config.toml，在 IDE 扩展中，可以通过齿轮菜单选择 MCP settings > Open config.toml 来打开该文件。
在配置文件中，为每个 MCP 服务器使用一个 [mcp_servers.<server-name>] 表进行配置。相关参数配置如下：
STDIO 服务器
可流式的 HTTP 服务器
Authorization 中发送 Bearer Token 的环境变量名。其他配置选项
false 可在不删除服务器的情况下禁用它；enabled_tools 之后生效）。config.toml 示例
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # 在 enabled_tools 之后生效
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = truetoml
MCP 服务器的列表仍在不断增长，以下是一些常见示例：
本文主要整理了 Codex 的 Rules（规则控制）、AGENTS.md （分层指令）、自定义提示词（Custom Prompts）与 MCP（工具扩展）等关键能力。希望能帮助到大家，谢谢大家的阅读，本文完。
在前几篇文章里，博主已经编写了Codex相关的文章，有兴趣的童鞋可以先阅读：
Agent Skills（代理技能） 可以为 Codex 扩展面向特定任务的能力，一个技能会将指令、资源以及可选脚本打包在一起，使 Codex 能够可靠地遵循某一工作流 ，你可以在团队之间共享技能，或将其分享给社区，技能都是基于开放的 Agent Skills 标准构建。
描述：为 Codex 赋予新的能力与专业知识
原文地址：https://developers.openai.com/codex/skills
一个技能通过位于 SKILL.md 文件中的 Markdown 指令 来表达某种能力，技能文件夹 中还可以包含脚本、资源和素材，供 Codex 在执行特定任务时使用。
技能使用渐进式披露（progressive disclosure）来高效管理上下文，在启动时，Codex 只会加载每个可用技能的名称和描述。随后，Codex 可以通过以下两种方式激活并使用技能：
显式调用（Explicit invocation）：可以在提示中直接包含技能。通过运行 /skills 斜杠命令来选择技能或输入 $ 来提及某个技能
 |
 |
|---|
隐式调用（Implicit invocation）：当你的任务与某个技能的描述匹配时，Codex 可以自行决定使用该技能。无论采用哪种方式，一旦技能被调用，Codex 都会读取该技能的完整指令以及技能目录中包含的所有附加参考资料。
当 Codex 从这些位置加载技能时，如果存在同名技能，则会用优先级更高的作用域中的技能覆盖优先级较低的，下表按优先级从高到低列出了技能作用域及其位置：
| 作用域 | 位置 | 建议 |
|---|---|---|
| REPO | $CWD/.codex/skills启动 Codex 时的当前工作目录 |
如果你在某个仓库或代码环境中，团队可以提交仅与该工作目录相关的技能，例如只适用于某个微服务或模块的技能 |
| REPO | $CWD/../.codex/skills在 Git 仓库中启动 Codex 时，位于 CWD 上一级的目录 |
当仓库存在多级子目录时，组织可以在父目录中提交适用于共享区域的技能 |
| REPO | $REPO_ROOT/.codex/skills在 Git 仓库中启动 Codex 时的最顶层根目录 |
适用于整个仓库的通用技能。它们可被任何子目录中的技能覆盖 |
| USER | $CODEX_HOME/skills（macOS 和 Linux 默认： ~/.codex/skills） |
用户个人目录中的技能，适用于用户可能使用的任何仓库 |
| ADMIN | /etc/codex/skills |
机器或容器中的系统级共享技能，适用于 SDK 脚本、自动化以及默认的管理员技能 |
| SYSTEM | 随 Codex 一起打包 | 面向广泛用户的通用技能（如 skill-creator、plan 技能），对所有用户可用，可被上层作用域覆盖 |
Codex 支持 符号链接（symlink） 的技能文件夹，在扫描这些位置时会跟随符号链接 的目标路径。
也可以在 ~/.codex/config.toml 中按技能粒度进行启用或禁用目前属于 实验性功能，未来可能会调整，你可以使用 [[skills.config]] 条目来禁用某个技能，而无需删除它，然后重启 Codex：
[[skills.config]]
path = "/path/to/skill"
enabled = falsetoml
描述：使用 Codex 创建自定义工作流，并在项目之间强制执行最佳实践
原文地址：https://developers.openai.com/codex/skills/create-skill
技能（Skills）让团队能够沉淀组织内部知识，并将其转化为可复用、可共享的工作流，技能可以帮助 Codex 在不同用户、代码仓库和会话之间保持一致的行为，尤其适用于希望自动应用标准约定和检查的场景。
一个技能是一个小型的组合体，包含以下内容：
Codex 在运行时上下文中只会注入技能的名称、描述和文件路径，指令正文不会被注入，除非该技能被明确调用。
当你希望在团队中共享行为、强制统一工作流，或将最佳实践编码一次并在各处复用时，应使用技能。典型使用场景包括：
不建议将技能用于一次性提示或探索性任务；应保持技能聚焦、单一职责，而不是试图建模大型多步骤系统。
Codex 内置了一个用于创建新技能的技能，使用该方法可以获得引导，并对技能进行迭代优化。
可通过 Codex CLI 或 Codex IDE 扩展调用技能创建器：
$skill-creatorshell
也可以添加你希望该技能实现功能的上下文说明。
$skill-creator
Create a skill that drafts a conventional commit message based on a short summary of changes.shell
创建器会询问：
于是继续输入：
Example trigger requests:
1) 根据以下改动摘要帮我写一条 conventional commit message：<改动摘要>
2) 把这段改动说明转换成符合 Conventional Commits 的提交信息：<改动说明>
3) 生成一条 conventional commit：<一句话总结/要点列表>
Conventional Commit constraints: default (standard types feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert; optional scope; use ! + BREAKING CHANGE footer when breaking; add Refs footer if issue id present)
shellshell
输出结果是一个 SKILL.md 文件，包含名称、描述和指令，目录在 skills/draft-conventional-commit/SKILL.md，内容如下：
当你需要完全控制，或直接在编辑器中操作时，可使用该方式。
Step1：选择存放位置（仓库级或用户级）
# 用户级技能（macOS/Linux 默认）
mkdir -p ~/.codex/skills/<skill-name>
# 仓库级技能（提交到代码仓库中）
mkdir -p .codex/skills/<skill-name>shell
Step2：创建 SKILL.md
---
name: <skill-name>
description: <功能说明及使用时机>
---
<指令、参考资料或示例>yaml
重启 Codex 以加载该技能。
技能使用 YAML front matter + 可选正文 的格式。必填字段：
name：非空，最多 100 个字符，单行description：非空，最多 500 个字符，单行Codex 会忽略多余的键，正文部分可以包含任意 Markdown 内容，会保存在磁盘上，且不会注入运行时上下文，除非技能被明确调用。
除了内联指令外，技能目录通常还包含：
示例目录结构：
技能指令可以引用这些资源，但它们仍保留在磁盘上，从而使运行时上下文保持小且可预测。真实世界的模式和示例可参考 agentskills.io，以及 github.com/openai/skills 上的技能目录。
Codex 会从以下位置加载技能（仓库级、用户级、管理员级和系统级）。根据技能适用对象选择合适位置：
.codex/skills/完整的支持路径和优先级规则，请参阅 Skills 概览中的 “Where to save skills” 部分。
示例技能如下：
---
name: draft-commit-message
description: Draft a conventional commit message when the user asks for help writing a commit message.
metadata:
short-description: Draft an informative commit message.
---
Draft a conventional commit message that matches the change summary provided by the user.
Requirements:
- Use the Conventional Commits format: `type(scope): summary`
- Use the imperative mood in the summary (for example, "Add", "Fix", "Refactor")
- Keep the summary under 72 characters
- If there are breaking changes, include a `BREAKING CHANGE:` footeryaml
触发该技能的示例提示：
Help me write a commit message for these changes: I renamed `SkillCreator` to `SkillsCreator` and updated the sidebar.shell
更多示例技能和创意请参阅 github.com/openai/skills 仓库。
编写技能时，建议遵循原则：
① 团队级技能（随代码走）
<repo>/
└── .codex/
└── skills/
└── <team-skill>/
└── SKILL.mdbash
② 个人常用技能
~/.codex/skills/<skill-name>/bash
③ 使用符号链接共享技能
ln -s ~/company-skills/review-skill ~/.codex/skills/review-skillbash
① 技能未显示（Skill doesn’t appear）
如果技能未出现在 Codex 中，请确认：
SKILL.md~/.codex/skills）如果你在 ~/.codex/config.toml 中禁用了某技能，请移除或修改对应的 [[skills.config]] 条目并重启 Codex。
如使用符号链接目录，请确认目标路径存在且可读。Codex 也会跳过 YAML 格式错误 或 name/description 超出长度限制 的技能。
② 技能未触发（Skill doesn’t trigger）
若技能已加载但未自动运行，最常见原因是触发条件不明确。
若多个技能意图重叠，请缩小描述范围，以便 Codex 选择正确技能。
③ 启动校验错误（Startup validation errors）
如果 Codex 在启动时报校验错误，请根据提示修复 SKILL.md 中的问题，最常见原因是 多行 或 超长 的 name 或 description，修复后重启 Codex 以重新加载技能。
随着 Agent Skills 标准逐步统一，社区已经出现了一批可直接复用或作为模板的 Skills 仓库。下面列出目前较为主流、与 Codex 兼容度高的仓库，并说明推荐的引入方式。
仓库地址： https://github.com/openai/skills
定位:
引入方式一：直接克隆到用户级技能目录
git clone https://github.com/openai/skills ~/.codex/skills/openai-skillsbash
引入方式二：只引入单个技能
mkdir -p ~/.codex/skills
cp -r skills/<skill-name> ~/.codex/skills/bash
重启 Codex 后即可通过 /skills 或 $<skill-name> 使用。
仓库地址： https://github.com/agentskills/agentskills
定位：
SKILL.md 格式、字段约束、设计原则推荐用途
引入方式：不建议整体放入 .codex/skills，建议作为文档仓库单独 clone 阅读
git clone https://github.com/agentskills/agentskillsbash
仓库地址： https://github.com/anthropics/skills
定位：
推荐用途
引入方式（选择性）
建议只复制单个技能目录，而不是整体引入。
git clone https://github.com/anthropics/skills
cp -r skills/<skill-name> ~/.codex/skills/bash
导入后重启内容如下：
定位
推荐用途
引入方式
~/.codex/skills/bash
至此，本文已经系统梳理了 Codex Agent Skills 的概念、创建方式以及社区中常见的 Skills 资源，帮助大家理解如何将零散的 Prompt 升级为可复用、可共享的工程化能力。希望本文的内容能对大家在实际使用 Codex 构建个人或团队工作流时有所帮助，感谢大家的阅读，本文完！
为了让读者更快建立一套稳定的心智模型，博主采用 5W1H（What / Why / Who / When / Where / How）把七篇内容 打通总结，并尽量以“可落地、可复用、可验收”的方式组织。
Codex 是面向真实工程场景的软件工程 AI 代理（Coding Agent）：它不是“只会生成代码的聊天模型”，而是能在工程工作台里 读仓库、改文件、跑命令、做审查、产出可验证证据 的“工程级协作者”。
一、它的本质：一个“可执行”的工程智能体
二、四个核心抽象：Prompts / Threads / Context / Workflows
1）Prompting（提示词）
$plan），由读者审查后再执行。2）Threads（线程/会话）
3）Context（上下文）
@path 或 /mention）。4）Workflows（工作流程）
一个可复用的工程 workflow 通常应包含：
三、它能“在哪些入口”工作：IDE / CLI / Web(Cloud) / 集成平台
IDE Extension（VS Code / Cursor / Windsurf 等兼容 VS Code 的编辑器）
/review、/status、/auto-context、/cloud、/local 等斜杠命令。CLI（终端）
codex resume）、非交互执行（codex exec）、云任务（codex cloud ...）、/review、/diff、/compact、/model、/approvals、/mention 等斜杠命令。Web / Cloud（云端 Codex）
Integrations（集成）
@codex review）。@Codex，并可结合 MCP 在本地访问 Linear。四、它如何“被工程化”：配置 + 安全边界 + 可复用资产
1）config.toml：Codex 的运行“总开关”
~/.codex/config.toml（CLI 与 IDE 共享）。2）Approvals & Sandbox：把“能做事”变成“可控地做事”
untrusted：仅安全只读命令自动执行，其余都要确认on-failure：沙箱内自动执行，失败时才提示升级/放权on-request：由模型决定何时询问（常见默认）never：从不询问（风险很高）read-only（默认）：只读workspace-write：允许写工作区（但某些目录仍可能只读）danger-full-access：无沙箱（极其危险，只建议在已有外部隔离时使用）术语澄清：文章（尤其是 CLI/IDE 章节）里也会出现“批准模式/Approval Modes（如 Auto / Read-Only / Full Access）”的说法，它更像是产品界面上的一组预设；而
config.toml中的approval_policy/sandbox_mode是底层配置键。不同版本/不同入口可能在命名上略有差异，但本质都是在控制“是否需要确认”以及“可访问的文件/网络边界”。
3）Rules：控制“哪些命令可以在沙箱外跑”
~/.codex/rules/*.rules：通过规则语言定义允许/提示/禁止的命令前缀（如 prefix_rule(pattern=["gh","pr","view"], decision="prompt", ...)）。forbidden > prompt > allow。4）AGENTS.md：让 Codex“默认懂项目与规范”
5）Custom Prompts vs Skills：提示复用的两条路
~/.codex/prompts/*.md，显式调用（如 /prompts:draftpr），更偏“个人复用”。6）MCP：把智能体连接到外部真实系统
config.toml 中配置 [mcp_servers.<name>]，支持 STDIO 进程型与可流式 HTTP 服务器型。五、学习资源：251 篇官方 Cookbooks（索引型内容）
第三篇文章本质上是一个“官方实战指南导航”，把 251 篇 Cookbooks（去除归档）按主题整理，覆盖：
一、它解决的核心不是“会不会写代码”，而是“交付闭环效率”
真实工程里最耗时的往往不是敲代码，而是：
Codex 的价值在于：它能在同一工作台里，把“理解 → 修改 → 执行 → 验证 → 复盘”尽量跑完，让人把时间更多用在架构判断与需求决策上。
二、它把“工程经验”变成默认流程（团队价值）
当团队开始把 Codex 当“工程成员”使用时，效率之外更重要的是稳定性：
AGENTS.md 把团队约束写出来（测试、lint、目录结构、禁忌操作、提交规范等）。config.toml 固化安全边界（审批策略、沙箱模式、网络访问、环境变量传递）。三、它让 SDLC 全阶段都能引入智能体（AI-Native Team）
第二篇文章把 SDLC 分成 Plan / Design / Build / Test / Review / Document / Deploy&Maintain，并给出“智能体能做什么、人类要做什么、入门清单”。核心结论是：
四、多端形态让 Codex“放在合适的位置”
第四篇文章强调：入口选对了，体验会从“能用”变成“顺手”：
一、个人开发者
二、Tech Lead / 架构与平台团队
AGENTS.md（规则与约束）、Skills（SOP 固化）、Rules（沙箱外命令门禁）、Cloud/Integrations（接入团队系统）。三、测试 / 质量工程
AGENTS.md 写清测试框架、覆盖要求、常用命令；用 workflow 指定“先写测试再修 bug”等策略。四、运维 / 安全 / 合规
sandbox_mode / approval_policy、Rules 的 forbidden/prompt、Cloud 的网络访问策略与 secrets 生命周期、MCP 的工具白名单/黑名单。五、协作场景的“入口角色”
这一部分把七篇内容里的“案例、能力与阶段”合并成一张“时间点地图”：读者可以按任务阶段（SDLC）或按任务类型来选入口与能力。
一、按 SDLC 阶段选 Codex 的用法（来自 AI-Native Team 章节）
/review 或 PR review；人类做最终合并判断与架构一致性把关。二、按“任务类型”选入口：IDE / CLI / Cloud / 集成
| 任务类型 | 更推荐入口 | 原因（概括） |
|---|---|---|
| 理解代码、追数据流、解释模块职责 | IDE | 打开文件/选区天然就是上下文 |
| 修 Bug（可复现）、跑测试验证 | CLI / IDE | CLI 更擅长执行命令与记录；IDE 更适合定位与修改 |
| 写测试（对齐项目习惯） | IDE（选区）/ CLI | IDE 选中函数更快；CLI 便于明确文件路径与批量跑测 |
| 从截图/设计稿生成 UI | CLI / IDE | 支持图像输入；可要求可运行交付物 + README |
| UI 快速迭代（改样式→预览→再改） | CLI + 本地 dev server | 双终端循环更顺畅 |
| 大型重构（本地规划 + 云端并行实现） | IDE → Cloud | 本地审计划、云端跑实现与验证，最后拉 diff/PR |
| 提交前质量检查 | CLI /review |
不改文件，集中输出可执行建议 |
| 审查 PR（无需拉分支） | GitHub 集成 | 评论触发 review，适合团队协作 |
| 更新文档与变更说明 | IDE / CLI | 方便引用文档并做链接校验 |
三、Workflows 里的 9 个典型案例（可直接当“模板”）
第二篇文章给了 9 个 workflow 案例，读者可以把它们理解为“最常用的九种提问方式”：
/review，聚焦边界与安全）@codex review ...）一、本地：读者需要记住的“Codex 工作目录体系”
1）主目录（CODEX_HOME，默认 ~/.codex）
~/.codex/config.toml：核心配置（模型/审批/沙箱/MCP/功能开关等）~/.codex/rules/*.rules：沙箱外命令规则（allow/prompt/forbidden）~/.codex/prompts/*.md：自定义提示（显式调用 /prompts:<name>）~/.codex/skills/：用户级技能（可跨仓库复用）auth.json、history.jsonl、日志与缓存等2）项目/仓库内（随代码走的沉淀）
AGENTS.md / AGENTS.override.md：项目与子目录的指令（分层合并）<repo>/.codex/skills/：仓库级技能（团队共享、随仓库分发）二、云端：任务在隔离容器内如何跑？
Cloud 任务大致流程：
三、Secrets 与网络访问：云端边界要特别注意
四、指令发现“在哪里发生”：AGENTS 的分层合并
Codex 启动时会构建指令链：
~/.codex/AGENTS.override.md（若存在）否则 ~/.codex/AGENTS.mdAGENTS.override.md → AGENTS.md → project_doc_fallback_filenames 中的文件名project_doc_max_bytes（32 KiB）五、技能“在哪里加载”：Skills 的作用域优先级
同名技能会被“更高优先级作用域”覆盖（从高到低概括）：
.codex/skills$CODEX_HOME/skills（默认 ~/.codex/skills）/etc/codex/skills这一章把七篇文章里所有“操作型内容”串成一条落地路径：先能用 → 再顺手 → 最后团队化与平台化。
Step 1：准备账号与入口（Web / CLI / IDE）
# npm
npm install -g @openai/codex
# Homebrew（macOS）
# 两种写法在文章中都出现过，按安装渠道选择其一：
brew install codex
brew install --cask codexbash
codex，选择 ChatGPT 登录 或 API Key，完成授权。Step 2：先把“安全边界”设好（配置 + 审批 + 沙箱）
在 ~/.codex/config.toml 里优先关注三件事：
示例（偏稳妥、适合日常开发）：
model = "gpt-5.2-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"toml
如果需要让工作区之外某些路径可写（如特定工具链目录），可在 sandbox_workspace_write.writable_roots 精确放行；如果要开网络访问，尽量只在必要时按环境开启，并配合 Rules/日志审计。
Step 3：学会写“工程级提示词”（把任务变成可验证的闭环）
博主建议提示至少包含 5 个元素（顺序可调）：
示例（Bug 修复类）：
示例（功能实现类）：
npm test，并给出变更摘要与验证结果”Step 4：把常用任务套进 Workflows（九大模板直接复用）
/review，加上安全/边界/性能关注点@codex review for ...Step 5：选模型与推理强度（把“质量/成本/速度”调到合适）
文章给出的典型模型选择思路：
gpt-5.2-codex（工程任务最强通用）gpt-5.1-codex-mini（更省但能力略弱）gpt-5.1-codex-max（更适合长链路编码任务）gpt-5.2 / gpt-5.1（更泛化）备注：在配置参考（config reference）片段中写明 “默认：所有平台均为
gpt-5.2-codex”。如果在某些地方看到 “macOS/Linux 默认gpt-5-codex、Windows 默认gpt-5” 之类描述，通常意味着它来自更早的版本/文档表述；以当前安装版本的/status与~/.codex/config.toml生效值为准。
CLI 可临时切换：
codex -m gpt-5.1-codex-minibash
也可在会话中 /model 切换。
Step 6：用 Rules 给“沙箱外命令”上门禁（允许/提示/禁止）
~/.codex/rules/ 下创建 *.rules。prefix_rule() 匹配命令前缀，指定 decision：
allow：直接放行prompt：每次提示确认forbidden：直接拒绝（建议写替代方案）match/not_match 当“内联单测”，避免误配。bash -lc 这类包装器可能隐藏复合命令，Codex 会做特殊处理；能拆分时会拆分后再判定规则。Step 7：用 AGENTS.md 让它“默认懂项目”（全局 + 仓库 + 子目录覆盖）
读者可以从两层开始：
1）全局 ~/.codex/AGENTS.md（个人工作约定）
2）仓库根 AGENTS.md（项目规范）
当某个子目录（如某个微服务）有特殊规则，用 AGENTS.override.md 放在子目录里覆盖。
验证是否生效：
codex --ask-for-approval never "Summarize the current instructions."bash
Step 8：把高频提示做成“自定义提示词”（个人复用）
~/.codex/prompts/xxx.md，在 YAML front matter 写 description 与 argument-hint。$FILES、$PR_TITLE 或 $1..$9）。/prompts:xxx 调用。适用：个人常用的“草稿 PR”“变更摘要”“统一 review 模板”等。
不适用：需要随仓库共享、希望隐式触发的 SOP（这更适合 Skills）。
Step 9：接入 MCP，让它能用“外部工具与真实系统”
两种方式：
codex mcp add ...~/.codex/config.toml 的 [mcp_servers.<name>]读者需要重点理解的配置维度：
command/args/env/env_vars/cwdurl、token 与 headers、OAuth（codex mcp login <name>）enabled、startup_timeout_sec、tool_timeout_sec、enabled_tools/disabled_toolsStep 10：用 Skills 把 SOP 封装成“团队可复用能力”
技能的核心是一个目录 + SKILL.md（可以附带脚本/资源/模板），Codex 采用“渐进式披露”：
/skills 或在提示中 $SkillName保存位置的三种常用方式：
~/.codex/skills/<skill>/SKILL.md（个人跨仓库复用）<repo>/.codex/skills/<skill>/SKILL.md（团队随仓库共享）~/.codex/skills/（统一维护）常见排查点：
SKILL.md社区/官方资源：
openai/skills（官方推荐，可直接用/可做模板）agentskills/agentskills（更偏规范与写技能指南）anthropics/skills（可借鉴复杂技能组织方式）agentskills.io（索引/市场）把这七篇文章合起来看，博主认为 Codex 的“主线”非常清晰：
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。