OpenAI Codex CLI Skill 入门：安装配置与精选推荐

手把手教你安装 OpenAI Codex CLI、配置 AGENTS.md 技能文件，并从社区精选 8 个最实用的 Skill，让你的终端编程助手生产力翻倍。

什么是 Codex CLI？

Codex CLI 是 OpenAI 开源的命令行编程 Agent。它连接 OpenAI 模型（默认 GPT-4.1 和 o3），直接在终端中运行——读取你的代码库、编写代码、执行命令，并在每一步等待你的确认。

与浏览器端的编程助手不同，Codex CLI 在开发者最熟悉的环境中工作：终端。它通过扫描文件理解你的项目结构，你可以通过 AGENTS.md 文件教它项目专属的工作流。

核心特点：

• 完全开源 — MIT 许可证，代码在 GitHub 上完全可查
• 终端原生 — 作为 CLI 工具运行，不需要浏览器或 IDE 插件
• 多模型支持 — 支持 GPT-4.1、o3、o4-mini 等 OpenAI 模型
• 沙盒执行 — 在隔离环境中运行命令，保障安全
• 技能感知 — 读取 AGENTS.md 文件学习项目专属指令

如果你用过 Claude Code 或打算试试 Gemini CLI，Codex CLI 就是 OpenAI 的对应产品——技能在三者之间可以互相迁移，只需要做少量格式调整。

安装 Codex CLI

前提条件

• Node.js 22 或更高版本
• 拥有 GPT-4.1 或 o3 访问权限的 OpenAI API Key

第 1 步：通过 npm 安装

npm install -g @openai/codex

第 2 步：设置 API Key

export OPENAI_API_KEY="sk-..."

写入 shell 配置文件使其永久生效：

echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc
source ~/.zshrc

第 3 步：验证安装

codex --version

第 4 步：运行第一条命令

进入任意项目目录，运行：

codex "解释这个项目的结构"

Codex 会扫描你的文件并给出详细的项目概览。之后你可以让它写代码、修 Bug、重构，或者执行任何你描述的工作流。

审批模式

Codex CLI 提供三种模式，控制 Agent 的自主权限：

• suggest（默认） — Codex 读取文件并建议修改，每次编辑和命令都需要你确认
• auto-edit — Codex 可以自动编辑文件，但执行命令前仍会询问
• full-auto — Codex 读取、写入、执行命令全自动（建议仅在沙盒环境中使用）

codex --approval-mode full-auto "给 auth 模块添加单元测试"

Codex CLI 如何读取技能

Codex CLI 使用 AGENTS.md 文件发现项目专属指令。这相当于 Claude Code 的 .claude/commands/ 目录或自定义指令文件。

AGENTS.md 格式

在项目根目录（或任意子目录——Codex 会递归发现）放一个 AGENTS.md 文件，使用标准 Markdown 格式：

# AGENTS.md

## 项目概览
这是一个 Nuxt 3 + Go-Zero 全栈应用。
前端在 /frontend-nuxt，后端在 /backend-go。

## 代码规范
- 使用 TypeScript 严格模式
- 优先使用 Composition API 而非 Options API
- 所有 API 响应遵循 {code, data, message} 格式

## 测试
- 提交前运行 `npm test`
- 单元测试使用 Vitest
- E2E 测试在 /tests/e2e/ 目录

## 部署
- 不要直接修改生产环境配置
- 前端部署使用 `bash deploy.sh frontend`
- 后端部署需要先通过 PR 审查

自动发现规则

Codex CLI 通过层级结构自动发现 AGENTS.md 文件：

1. 根目录 AGENTS.md — 对整个项目生效
2. 子目录 AGENTS.md — 仅在该目录及其子目录中生效
3. 多文件合并 — 如果两者同时存在，Codex 会合并内容（子目录指令在冲突时优先）

这意味着你可以有一个顶层 AGENTS.md 管理全局规范，再在 frontend/AGENTS.md 中写前端专属规则。

AGENTS.md 应该包含什么

最好的 AGENTS.md 文件覆盖以下内容：

• 项目架构 — 目录结构、关键文件位置
• 代码规范 — 命名、格式化、设计模式
• 常用命令 — 构建、测试、部署、代码检查
• 注意事项 — Agent 绝对不能做的事、需要注意的边界情况
• 工作流指令 — 针对重复性任务的分步操作手册

把它想象成给 AI 队友写的入职文档。你写得越具体，Codex 表现越好。

从 TokRepo 安装技能

TokRepo 是一个社区技能注册中心。发布在 TokRepo 上的技能可以同时用于 Claude Code、Codex CLI 和 Gemini CLI——你只需要把它放到正确的位置。

方法 1：TokRepo CLI（推荐）

最快的安装方式：

npx tokrepo install <asset-uuid>

这会下载技能文件并放到你项目的技能目录中。对于 Codex CLI，你可能需要把指令内容整合到 AGENTS.md 中，或者把技能文件放到 Codex 可以引用的位置。

方法 2：手动复制

1. 在 TokRepo 上访问技能页面
2. 复制 Markdown 内容
3. 粘贴到你项目的 AGENTS.md 文件中，或者保存为单独的 .md 文件

对于 Codex CLI，最干净的做法是把技能指令合并到 AGENTS.md 中，使用清晰的标题分段：

# AGENTS.md

## 调试工作流
<!-- 来自 Systematic Debugging 技能 -->
调试时请遵循以下步骤：
1. 用最小测试用例重现问题
2. 在关键决策点添加日志
3. 先形成假设再修改代码
4. 验证修复没有引入新的回归问题

方法 3：软链接（适合多 Agent 项目）

如果你在同一个项目中同时使用 Claude Code 和 Codex CLI，可以维护单一信息源：

# 技能文件在 .claude/commands/ 中（给 Claude Code 用）
# 把关键内容合并到 AGENTS.md（给 Codex CLI 用）
cat .claude/commands/*.md >> AGENTS.md

8 个推荐的 Codex CLI 技能

以下技能已在 Codex CLI 上测试通过，能带来即时的生产力提升。每个都可以在 TokRepo 上找到，安装或复制到你的 AGENTS.md 中。

1. Get Shit Done (GSD)

做什么： 完整的项目管理框架，把大项目拆分为里程碑、阶段和任务。通过持久化的 .planning/ 目录跨会话追踪进度。

为什么适合 Codex： Codex CLI 擅长处理聚焦的任务，但在多步骤项目中容易丢失方向。GSD 提供了让复杂工作保持在正轨上的脚手架。

npx tokrepo install e108cf5c-c34e-4d27-a694-66a693301e87

在 TokRepo 查看

2. Vercel Skills — Agent Skill 生态

做什么： 13,000+ 社区贡献的技能集合，覆盖 Next.js、React、部署模式和全栈开发工作流。

为什么适合 Codex： 如果你使用 Vercel、Next.js 或 React，这个集合能给 Codex 注入领域专属知识，显著提升代码质量。

npx tokrepo install d1eba6f1-5166-4762-bbbd-cf00f14892b7

在 TokRepo 查看

3. Claude SEO — 完整 SEO 技能

做什么： 运行全面的 SEO 审计——关键词研究、页面分析、内容缺口识别、技术检查和竞品对比。

为什么适合 Codex： SEO 需要遵循结构化的检查清单。这个技能确保 Codex 覆盖所有要点，而不是即兴发挥一个不完整的审计。

npx tokrepo install cb068086-48bc-4dc2-b53e-9a16eba5b51f

在 TokRepo 查看

4. Systematic Debugging（系统化调试）

做什么： 结构化的调试方法论——重现、隔离、假设、修复、验证。防止"随便改改看能不能行"的常见陷阱。

为什么适合 Codex： 当 Codex 在 full-auto 模式下运行时，调试技能能防止它陷入试错循环，强制进行有条理的调查。

npx tokrepo install 78ed006e-0c05-4bab-91de-c0c72c3e4cc4

在 TokRepo 查看

5. Planning with Files（文件化规划）

做什么： 在执行复杂任务前创建结构化的计划文件。把计划写到磁盘上，跨上下文窗口和会话保持持久化。

为什么适合 Codex： Codex CLI 的会话可能很长。规划技能确保 Agent 先思考再行动，并保留书面记录。

npx tokrepo install 034be597-dbb5-4649-ad6e-98f9ff6332b8

在 TokRepo 查看

6. Web Access（网页访问）

做什么： 给 Agent 提供获取和解析网页内容的结构化方法——文档页面、API 参考和实时数据。

为什么适合 Codex： 默认情况下 Codex CLI 无法浏览网页。当 Agent 需要参考文档或检查线上接口时，这个技能提供了引入外部信息的方法。

npx tokrepo install 5766b7f4-bfdb-4048-87e7-50af1e5f6f88

在 TokRepo 查看

7. Skill Creator（技能创建器）

做什么： 一个元技能，引导你创建新的 Agent 技能——编写 frontmatter、触发条件、指令和测试步骤。

为什么适合 Codex： 用过几个技能之后，你会想创建自己的。这个技能让创建过程可重复，并确保你的自定义技能遵循最佳实践。

npx tokrepo install 0b7c0a41-97e1-4187-9cc5-4dc32d91a9cd

在 TokRepo 查看

8. Agent Skills Standard（技能标准规范）

做什么： 定义 Agent 技能文件的通用标准——元数据字段、指令格式、触发约定，以及不同 AI Agent 之间的兼容性规则。

为什么适合 Codex： 如果你希望技能在 Codex CLI、Claude Code 和 Gemini CLI 之间通用，这个标准告诉你应该包含哪些字段、如何组织结构。

npx tokrepo install 1a1292f5-c88b-4eb5-b7dd-a3bf7bb29ee8

在 TokRepo 查看

Codex CLI vs Claude Code：技能兼容性对比

Codex CLI 和 Claude Code 都支持 Agent 技能，但读取方式不同。理解差异有助于你编写两者都能用的技能。

核心结论

为 Claude Code 编写的技能可以通过把指令内容复制到 AGENTS.md 来适配 Codex CLI。核心逻辑——步骤、规则和工作流——可以直接迁移。只有包装方式不同。

想深入了解所有主流 AI 编程 Agent 的技能格式差异，请看 Skills vs MCP vs Rules 完整对比。

常见问题

Claude Code 的技能能直接用在 Codex CLI 上吗？

可以，只需少量调整。Claude Code 的技能本质上是 Markdown 指令文件，和 Codex CLI 从 AGENTS.md 中读取的格式相同。把指令内容（frontmatter 下面的所有内容）复制到你的 AGENTS.md 文件中即可。triggers 等 frontmatter 字段是 Claude Code 专属的，在 Codex 中可以删除。

Codex CLI 支持像 Claude Code 那样的斜杠命令吗？

不支持。Codex CLI 没有斜杠命令系统。AGENTS.md 中的所有指令会自动加载到上下文中。你通过自然语言描述来激活特定工作流——比如说"用系统化调试方法排查这个问题"，而不是输入 /debug。

Codex CLI 免费吗？

Codex CLI 本身免费且开源。但它调用 OpenAI 的 API，需要付费的 API Key。费用取决于你使用的模型——GPT-4.1 处理日常任务更经济，o3 在复杂推理上更强。具体价格请查看 OpenAI 定价页面。

下一步

安装配置好 Codex CLI 和技能之后，继续探索这些相关指南：

• 如何创建你的第一个 Agent Skill — 从零开始构建自定义技能
• Skills vs MCP vs Rules 完整对比 — 理解何时使用哪种扩展方式
• 15 个最佳 Claude Code Skill — 更多技能推荐（大多数也适用于 Codex）
• Gemini CLI 技能指南 — 为 Google 的 CLI Agent 配置技能

在 TokRepo 上浏览完整技能目录，找到适合你技术栈和工作流的技能。