OpenAI Codex 目前有三个形态：桌面 App（macOS + Windows）、CLI（终端命令行）、IDE 扩展（VS Code 等）。2026 年 2 月桌面端正式发布，3 月登陆 Windows——自此，图形化的桌面 App 就成了绝大多数开发者的主力入口。

本文以桌面端为默认视角来组织内容，同时为 CLI 用户单列一章。无论你用哪种形态，核心能力（Skills、AGENTS.md、MCP、Automations）是打通的。

当前最新模型：GPT-5.5（2026 年 4 月 23 日发布），桌面端和 CLI 均可使用。Codex 也支持 GPT-5.3-Codex 和 GPT-5.3-Codex-Spark（后者速度可达 1000+ token/s）。

二、桌面端 Codex：开箱即用的图形化工作台
桌面端的哲学是"一切皆可点"——你很少需要手动编辑配置文件。点击左下角头像/齿轮 → Settings，所有设置都在 GUI 里。

2.1 桌面端 Settings 速览
设置分类 关键选项 建议
General Prevent sleep while running ✅ 开启——长任务时电脑休眠会导致 Codex 中断
General Detail level 选 Coding mode——可以看到 Codex 具体执行了哪些命令
General Follow-up behavior 开启——Codex 完成任务后主动问"还需要我做什么？"
Configuration Approval policy On request——涉及文件修改和命令执行时征求同意
Configuration Sandbox mode Workspace write——Codex 可在工作区内自由读写，但出不去
Configuration Model 选 GPT-5.5（Pro/Max 用户），日常用 High 推理强度
Personalization Personality Pragmatic（简洁直接）或 Friendly（更亲和）
Personalization Custom instructions 最重要的一项——见下文 2.2
Appearance Theme Light / Dark / System，还有色盲友好主题
Appearance Avatar 可设置一个浮动头像，Codex 在后台跑任务时你能在桌面上看到它
codex常规设置

2.2 个性化——自定义指令如何写得精简高效
桌面端入口：Settings → Personalization → Custom instructions。

codex个性化

这里写的内容会被写入 ~/.codex/AGENTS.md（全局级别），影响你在这台机器上所有项目的所有会话。所以只放真正通用的规则。

精简高效的核心原则：

❌ 不要写 ✅ 要写
“请你尽量写出高质量的、符合最佳实践的代码” “TypeScript 严格模式，禁止 any；React 函数组件 + Hooks”
“认真对待每一个细节” “改完代码后自动运行 pnpm typecheck && pnpm lint”
“使用合适的错误处理方式” “API 层统一用 Result<T, AppError> 模式，不抛裸异常”
长篇架构文档 放在项目 docs/ 下，需要时用 @docs/arch.md 引用
一份实用的全局自定义指令示例：

沟通

• 用中文回答，代码注释用英文
• 先给方案概述（2-3 句），再写代码
• 涉及架构决策时，列出选项和 trade-off，让我选

编码习惯

• TypeScript 严格模式，禁止 any
• 不写 TODO 注释——要么实现完整，要么在 PR 描述中说明
• 安装新依赖前先问我
• 绝不在代码中硬编码密钥和 Token

安全

• 不修改 .env 和 production 配置文件
• 涉及数据库 migration 必须先确认
  一句话口诀：自定义指令不是写给 AI 的情书，是你给它列的操作清单。每一条都应该是可验证的——“我能在做完后跑一条命令来确认它遵守了吗？”

2.3 桌面端独有功能：Plugins、Automations、多 Agent
桌面端有一些 CLI 不具备或体验差异很大的功能：

功能 干什么用 入口
Plugins 一键安装 Skills、MCP 服务器、App 集成（GitHub、Slack、Notion 等 90+ 插件） 左侧栏 Plugins 图标
Automations 定时任务——比如每天 9:00 让 Codex 检查 PR、生成日报 左侧栏 Automations 图标
多 Agent 并行 同时跑多个 Agent 处理不同任务 新建 Chat 即可自动分配
Projects 按项目组织会话，各自的上下文和配置独立 左侧栏 Projects
内置 Terminal 每个线程有独立终端，跑测试、启 dev server 不用切换窗口 线程内 Terminal Tab
三、CLI 版 Codex：终端极客的进阶武器
如果你更喜欢终端操作（或者需要在 CI/脚本中使用 Codex），CLI 版本提供了更细粒度的控制。

3.1 基本启动方式
codex # 启动交互式 TUI
codex “解释这个项目” # 带初始 prompt 启动
codex exec “检查类型” # 非交互模式，执行一次后退出
codex update # 更新到最新版
3.2 CLI 常用参数
参数 简写 作用 示例
–model -m 指定模型 codex -m gpt-5.5
–sandbox -s 沙箱策略 codex -s workspace-write
–ask-for-approval -a 审批时机 codex -a on-request
–full-auto workspace-write + on-request 一键组合 codex --full-auto
–image -i 附图片 codex -i error.png “修这个”
–search 启用实时联网搜索 codex --search “查最新 API”
–profile -p 加载预设配置 Profile codex -p review
–cd -C 指定工作目录 codex -C ./packages/api
–add-dir 添加额外工作目录 codex --add-dir …/shared-lib
3.3 CLI 用户什么时候需要碰 config.toml？
桌面端用户基本不需要手动编辑 ~/.codex/config.toml，因为 Settings GUI 已经覆盖了 90% 的常见配置。但 CLI 用户在以下场景可能需要直接编辑：

使用非 OpenAI 模型（如通过 LiteLLM 代理接入其他模型）
配置 MCP 服务器（虽然桌面端有 GUI，但 CLI 用户只能写文件）
精细化 Hooks（PreToolUse / PostToolUse / SessionStart 等生命周期钩子）
企业管控：管理员通过 requirements.toml 强制安全策略
创建多个 Profile（如 dev / review / ci），用 --profile 切换
一个简洁的 ~/.codex/config.toml 示例：

model = “gpt-5.5”
model_reasoning_effort = “high”
approval_policy = “on-request”
sandbox_mode = “workspace-write”
web_search = “cached”
personality = “pragmatic”

[profiles.review]
model_reasoning_effort = “medium”

[profiles.quick]
model_reasoning_effort = “low”
注意：config.toml 的优先级低于 CLI 参数，高于桌面端 GUI 设置。如果你同时使用桌面端和 CLI，建议以桌面端 GUI 为主，config.toml 只放 GUI 覆盖不到的项。

3.4 CLI 典型工作流

日常开发

codex --full-auto

代码审查（只读 + 每次确认）

codex -s workspace-write -a on-request “审查 src/ 代码”

脚本自动化

codex exec “检查 TypeScript 类型错误” --json

多仓库协作

codex --cd apps/frontend --add-dir …/backend --add-dir …/shared

贴截图 Debug

codex -i error.png “这个报错怎么修？”
四、AGENTS.md 撰写指南：让 Codex 真正懂你
AGENTS.md 是 Codex 的持久化上下文——每次会话启动时自动加载。桌面端和 CLI 共用同一套机制。

4.1 加载链与优先级
Codex 按以下顺序查找 AGENTS.md：

~/.codex/AGENTS.md ← 全局个人偏好（桌面端 Settings → Personalization 写入的）
└── 项目根/AGENTS.md ← 项目级规则（建议提交到 Git 给团队共享）
└── 子目录/AGENTS.md ← 模块/目录级细化
离当前工作目录越近的文件，优先级越高
同目录存在 AGENTS.override.md 时，完全替代同目录的 AGENTS.md（适合临时实验）
桌面端 Settings → Personalization → Custom instructions 编辑的就是 ~/.codex/AGENTS.md
4.2 该写什么、不该写什么
✅ 推荐写

AGENTS.md

技术栈

• 前端：React 18 + TypeScript 5 + Tailwind CSS 3
• 后端：Node.js + Express 4 + Prisma + PostgreSQL
• 测试：Vitest（单元）+ Playwright（E2E）
• 包管理：pnpm

启动与验证

• 安装依赖：pnpm install
• 启动 dev server：pnpm dev（端口 3000）
• 类型检查：pnpm typecheck
• 运行测试：pnpm test
• Lint：pnpm lint

编码规范

• TypeScript 严格模式，禁止 any
• React 函数组件 + Hooks，不用 class
• API 路由放在 src/app/api/，遵循 App Router 约定
• 每个组件对应一个 .test.tsx

安全

• 绝不硬编码密钥
• 修改 DB Schema 前必须确认
• 涉及认证/权限的改动，先出方案再看代码
  ❌ 不该写
  不该写的内容 原因 正确做法
  长文档、API 参考 占上下文窗口，大部分时候用不到 放 docs/，需要时 @docs/api.md 引用
  密钥和 Token 安全隐患，可能被提交到 Git 放 .env，权限中禁止 Codex 读取
  格式化规则（缩进/引号等） 应让工具自动执行，不靠 AI 遵守 Prettier/ESLint + Hooks 自动格式化
  "认真对待每个细节"等空话 占 token 无实际约束 换成可验证命令：“改完后跑 pnpm typecheck”
  4.3 进阶：让 AGENTS.md 持续进化
  “两次犯同一个错就加规则”——Codex 犯一次错，会话中指正它；同一个错犯第二次，写入 AGENTS.md。

但要定期清理——每月回顾一次，删掉过时或不再需要的条目。一个 40 行的 AGENTS.md 比一个 200 行的更有效。

五、Skills 生态系统：去哪里找、怎么选、如何取舍
Skills 是 Codex 的"插件"——Markdown 格式的可复用指令包，Codex 启动时自动发现元数据，需要时才加载完整内容。桌面端和 CLI 共用同一套 Skills 目录（~/.codex/skills/）。

5.1 Skills 核心概念
~/.codex/skills/ ← 个人 Skills（全局可用）
└── my-skill/
└── SKILL.md ← 必需：name、description、触发条件、执行步骤
└── scripts/ ← 可选：辅助脚本
└── references/ ← 可选：参考资料

.codex/skills/ ← 项目 Skills（随仓库共享给团队）
Skills 使用渐进式披露：启动时只加载 name + description（元数据），只有任务匹配时才拉取完整指令。即使装 50 个 Skill，真正占上下文的也只有被激活的那一两个。

5.2 去哪里搜寻 Skills？（已逐一验证）
平台 地址 说明
CocoLoop（中文） hub.cocoloop.cn 中文友好，含 CLS 安全评级，第三方 Skill 商店
Firecrawl 精选 firecrawl.dev/blog/best-codex-skills 含详细评测 + 安装命令 + 使用示例，2026 年持续更新
Composio Top 10 composio.dev/content/top-codex-skills 真实使用案例测试过的 10 个 Skills
LobeHub lobehub.com/skills 500+ Skills，分类清晰，跨 Agent 通用
FAOS Marketplace faosx.ai/open-source 526 个免费 Skills，Apache 2.0，覆盖工程/产品/增长/数据
OpenAI 官方渠道 桌面端 Plugins 面板搜索安装 最安全，官方审核
安装器方式 会话中 $skill-installer<名称>官方推荐：$skill-installer gh-fix-ci
npx 方式 npx skills add --skill CLI 通用：npx skills add mattpocock/skills --skill handoff