Codex CLI 是 OpenAI 推出的终端编码代理：不用切浏览器，直接在本地仓库里和 AI 对话，它能读你的文件、执行命令、改代码，而且每一步执行都有审批机制兜底。如果你习惯待在终端里干活，又厌倦了在网页 Chat 和编辑器之间来回粘贴上下文，这个工具值得一试。
这篇文章把我整理的安装、常用命令、AGENTS.md、MCP 和 Skills 的用法都过一遍，基本覆盖日常使用场景。
为什么选 Codex CLI
先用一张表对比它和传统网页 Chat 的差异，核心就是”上下文”和”可控性”这两点：
| 维度 | 传统 AI Chat 对话 | Codex CLI |
|---|---|---|
| 入口 | 浏览器/网页为主 | 终端统一入口，直接在本地仓库内工作（编辑器无关） |
| 上下文 | 主要靠手动粘贴/描述 | 可读取仓库文件与变更，任务上下文持续 |
| 可信控制 | 缺少命令级审批与执行控制 | 内建审批模式与会话状态，可控制何时执行命令 |
| 复用能力 | 以对话模板/复制粘贴为主 | 支持内置 Slash 命令、可扩展 Prompt 与 Skill |
| 扩展 | 需要手动切换外部工具 | 通过 MCP 接入第三方工具与上下文（如 Figma） |
安装与启动
全局装一个 npm 包就行：
npm i -g @openai/codex然后进入你的项目目录，直接运行：
codex首次运行会提示登录，用 ChatGPT 账号或 API key 都可以。
常用快捷键
进入交互界面后，这几个快捷键用得最多，建议先记住 /、@ 和 ! 三个：
- /：命令列表
- !：Shell 命令
- Ctrl+J：换行
- @：补全文件路径
- Ctrl+G：外部编辑器输入
- Ctrl+T：查看对话记录
- Ctrl+C：退出
- Tab：排队发送消息
- Ctrl+V：粘贴图片（Mac/Windows/Linux 通用）
- Esc Esc：编辑上一条消息
Slash 命令速查
在 CLI 里输入 / 会弹出命令列表，支持模糊过滤。内置命令不多，一张表就能列全：
| 命令 | 用途 |
|---|---|
| /approvals | 设置审批模式（例如只读/自动/需确认） |
| /compact | 对话压缩，保留要点 |
| /diff | 查看 Git diff（含未跟踪文件） |
| /exit /quit | 退出 CLI |
| /feedback | 发送诊断与反馈 |
| /init | 生成 AGENTS.md 模板 |
| /logout | 退出登录 |
| /mcp | 查看已配置 MCP 工具 |
| /mention | 添加文件/路径到上下文 |
| /model | 切换模型 |
| /new | 开新对话（同目录） |
| /review | 代码/改动审查 |
| /status | 查看会话配置与状态 |
| /undo | 撤销最近一次变更 |
一套典型的工作流程
上面的命令单看有点抽象，串成一个实际流程就清楚了：初始化、设权限、加上下文、看改动、审查。
初始化项目指令
/init生成 AGENTS.md 模板，作为项目级指令入口，后面会专门讲怎么写。
限制或放开权限
/approvals选择审批策略（例如只读/自动/需确认）。第一次用建议保守一点，熟了再放开。
把关键文件加入上下文
这一步的核心是：把你正在处理的关键文件加入上下文，不必拘泥固定路径。两种常见场景：
- 如果有现成文件（例如纯 HTML 待办演示）：
/mention index.html
- 如果目录暂时还不存在（或准备新建）：
然后让 Codex 生成/创建你要的目标文件。/mention README.md
文件加入上下文后，后续指令会自动带上，联动修改很方便。
查看和审查改动
改完之后先看 diff，再让它自己审一遍：
/diff/review实战：生成一个纯 HTML 待办页
拿一个完整例子走一遍上面的流程。目标：生成一个可直接打开的静态待办页面（HTML + CSS + 原生 JS，支持本地保存）。
先准备一个空项目：
mkdir codex-demo-pagecd codex-demo-pagetouch index.htmlcodex然后在 Codex CLI 里直接描述需求：
请生成一个纯 HTML 待办事项页面：包含任务输入、列表、完成状态、筛选（全部/未完成/已完成），数据存 localStorage；要求响应式、排版清晰、配色干净。
生成后检查改动：
/diff/review想在浏览器里看效果，起个本地服务即可：
python -m http.server 8000AGENTS.md：给仓库写持续指令
AGENTS.md 的作用是为当前仓库提供持续生效的指令，Codex 会自动读取并遵守——相当于把你每次都要重复交代的规矩写死在仓库里。用 /init 就能生成模板。
下面是我推荐的模板结构，可以直接复制改：
## Repository Guidelines
### 项目结构与模块组织- 说明主要目录与模块的职责边界- 指出入口文件与页面组件位置
### 构建与开发命令- 统一列出安装、开发、构建、预览命令
### 编码风格- 缩进、命名规范、组件职责边界
### 数据存储与约束- localStorage key 命名、后端接口、字段约束
### 代码审查重点- 修改功能时需补充的测试点- 高风险模块注意事项
### 输出要求（每次改动后需说明）- 说明改动内容（做了什么）- 说明影响范围（哪些文件/模块/功能受影响）- 提供回滚或兜底方案（如何恢复到改动前）MCP：接入外部工具
MCP（Model Context Protocol）让 Codex 能接入第三方工具与上下文，比如设计稿、浏览器、文档。下面以 Figma 为例，两种配置方式任选。
方式一，直接用命令行添加：
# 使用 HTTP MCP Server（以 Figma 为例，URL 以实际服务商提供为准）codex mcp add figma --url https://mcp.figma.com/mcp
# 查看已配置的 MCP 列表codex mcp list方式二，写配置文件（项目级或全局都行）：
# ~/.codex/config.toml 或 <repo>/.codex/config.toml[mcp_servers.figma]url = "https://mcp.figma.com/mcp"配置好之后，在 CLI 里输入 /mcp 就能查看已接入的工具。
Skills：把常用流程封装成可复用能力
如果你有一套固定流程反复在用（比如每天生成日报），可以封装成 Skill。
一个 Skill 长什么样
Skill 就是一个文件夹，核心是 SKILL.md（必需），外加可选的 scripts/、references/、assets/。SKILL.md 用 YAML Front Matter 描述元信息（至少 name 与 description），正文写具体流程说明。
怎么触发
Codex 启动时会扫描可用 Skill，但只读取 name 与 description 用于匹配；只有被触发时才加载完整内容，所以不用担心 Skill 多了拖慢上下文。触发方式两种：
- 显式：输入
/skills选择，或在提示中直接写$skill-name - 隐式：当任务描述与 Skill 的
description匹配时，Codex 自动启用
保存位置
Codex 会按由近到远的顺序扫描这些目录：
$CWD/.codex/skills$CWD/../.codex/skills$REPO_ROOT/.codex/skills$CODEX_HOME/skills（macOS/Linux 默认~/.codex/skills）/etc/codex/skills- 系统内置 Skills（随 Codex 发布）
注意同名 Skill 不会去重，选择器里可能同时出现多个。技能目录用软链接也是支持的。
创建与安装
方式 1：使用内置 $skill-creator
在 Codex CLI 中描述你要的能力，Codex 会引导你创建 Skill。
方式 2：手动创建
在任意有效技能目录下创建文件夹与 SKILL.md，保存后重启 Codex 生效。
安装官方示例（experimental）
$skill-installer install the create-plan skill from the .experimental folder安装完成后同样需要重启 Codex。
SKILL.md 完整示例
拿一个”生成 git 日报”的 Skill 做例子，可以直接复制改：
---name: Daily Git Log Reportdescription: 根据指定目录路径生成日报摘要---
## 目标在指定仓库与目录范围内，收集当天 git log 并生成日报摘要。
## 输入要求在执行前向用户确认以下信息：1) REPO_PATH：仓库路径（绝对路径）2) FOCUS_PATH：仅统计的目录或文件路径（相对 REPO_PATH）3) DATE：日报日期（YYYY-MM-DD；若未提供则使用当天）
## 执行步骤1) 在 shell 中执行 git log，范围限定为 DATE 当天。2) 排除 merge commit。3) 输出清单 + 摘要两段。
## 命令模板git -C "$REPO_PATH" log \ --since "$DATE 00:00" \ --until "$DATE 23:59" \ --no-merges \ --date=short \ --pretty=format:"%h %ad %s (%an)" \ -- "$FOCUS_PATH"
## 输出格式
### Commit 清单
- 逐条列出：hash + 日期 + 标题 + 作者
### 日报摘要
- 归纳为 3~6 条重点- 按功能模块或主题归类没有 Hooks？替代方案
官方文档目前聚焦在 Slash 命令、Skills 和 MCP 上，没有描述与”自动触发 Hook”等价的机制。想要类似效果，可以这样绕：
- Git hooks：在 pre-commit / pre-push 中调用 Codex 或固定脚本
- Skills：把流程固化成可分享的能力（比脚本更可读）
总结
Codex CLI 本质上是一个跑在终端里的本地编码代理，直接在你的仓库里执行、编辑与协作。它解决的是网页 Chat 的几个老问题：上下文零散、工具切换频繁、流程难复用、权限不可控。上手成本不高，装完先用 /init 和 /approvals 把规矩立好，再把常用流程沉淀成 AGENTS.md 和 Skills，日常开发里能省下不少重复沟通。