Codex 入门实践笔记：从安装到安全避坑

一、Codex 是什么

OpenAI Codex 是 OpenAI 推出的 AI 编程 Agent，2026 年已全面升级，提供本地 CLI、VS Code 扩展、Cursor/Windsurf 集成和桌面应用四种使用形态。核心能力是在终端中自主完成代码编写、修改、执行 Shell 命令、搜索文件和抓取网页等完整工程任务。

Codex CLI 已在 GitHub 完整开源（Apache-2.0），支持 ChatGPT 订阅登录和 API Key 两种认证方式，并通过config.toml支持接入任意 OpenAI 兼容的第三方推理后端。

二、安装与登录

安装方式

Codex 支持四种安装方式，按场景选择即可。

方式一：官方安装脚本（推荐）

macOS / Linux：

bash

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows PowerShell：

powershell

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

脚本会自动下载最新版、校验 checksum，并将codex命令加入 PATH。

方式二：npm（适合已有 Node 环境）

bash

npm install -g @openai/codex

方式三：Homebrew（macOS）

bash

brew install --cask codex

方式四：二进制直接下载：从 GitHub Releases 下载对应平台压缩包，解压后重命名为codex放入 PATH。

验证安装：codex --version

环境要求：macOS 12+、Ubuntu 20.04+/Debian 10+、Windows 11（WSL2），最低 4GB 内存（建议 8GB），可选 Git 2.23+。

登录

两种认证方式：

• Sign in with ChatGPT：适合已有 ChatGPT Plus / Pro / Business 套餐的用户，在订阅额度内使用，无额外按量计费。执行codex login后自动打开浏览器完成 OAuth 授权。

• API Key 登录：适合 CI/CD 等编程化调用场景。推荐使用printenv OPENAI_API_KEY | codex login --with-api-key，避免密钥暴露在 shell history 中。

凭据缓存在~/.codex/auth.json，等同于密码，不要提交到 Git。

三、核心交互：CLI 命令与会话内斜杠命令

Codex 的交互分两层：启动 CLI 时的命令行参数，以及进入会话后使用的斜杠命令。

常用 CLI 命令：

常用斜杠命令（会话内）：

斜杠命令执行的是程序写死的固定动作，不依赖模型推理，响应更快、行为更确定。

四、记忆系统：两套机制，别搞混

Codex 的记忆相关功能实际上是两套各管各的系统——一套你手写（AGENTS.md），一套它自己写（Memories）。

AGENTS.md是你手动编写的指令文件，用于声明构建命令、测试要求、代码规范、安全边界和审查规则。Codex 每次开工前都会读取它。

Memories是 Codex 自己在后台总结的“私人笔记”——你纠正它一次，它在会话闲置后异步生成记忆，下次开工自动想起。但记忆不是实时生效的，你前脚说完后脚就考它，它可能还没记下来。必须每次都生效的规则，应该写进 AGENTS.md，别赌记忆。

关于 AGENTS.md 的作用域优先级，Codex 按以下顺序读取：

1. 全局层：~/.codex/AGENTS.override.md（不存在则读~/.codex/AGENTS.md）

2. 项目层：项目根目录的AGENTS.md

文件大小上限默认 32 KiB，超出部分会被截断。建议从最小化的 AGENTS.md 开始，发现 Codex 需要知道什么再逐步补充。

⚠️ 安全警示：AGENTS.md 不是万能的

AGENTS.md 是“软约束”而非“硬边界”。真正限制 Codex 行为的是沙箱和审批策略，不是你在 AGENTS.md 里写了什么。安全相关的内容将在第八节展开。

五、Git 工作流：分叉回滚与 worktree 并行开发

分叉回滚：对话 + 代码的双重回退

Codex 的fork（分叉）功能可以创建一条继承历史的新对话分支。操作方式：找到上一次对话结尾的位置，点击分叉按钮，选择“派生到本地”。分叉后的新对话剔除了你不想要的部分。

但关键点是：分叉只回退对话历史，不同步回退代码。完整的回滚需要两步走：

1. 用 Codex 分叉回退对话历史

2. 在 VS Code 的 Source Control 中找到目标提交的 commit hash，让 Codex 把代码回退到该状态

两步结合，才能实现从代码层面和对话历史层面的完全回滚。

Git worktree：并行开发两个功能

Worktree 本质上是用 git 创建新分支，并将该分支的代码完整复制到一个新文件夹。主文件夹和分支文件夹可以并行工作，互不干扰。

典型使用场景：你想同时优化“客户评价”和“门店信息”两个模块。操作流程：

1. 在项目上右键创建永久工作树，分别命名（如customer-rating和store-info）

2. 在第一个工作树中开新对话，要求优化客户评价部分

3. 在第二个工作树中开新对话，要求优化门店信息部分

4. 两个分支并行开发，互不干扰

5. 开发完毕后各自合并回主干

在终端中，Codex 也支持codex fork --last或codex fork [session_id]命令来创建分叉会话，结合 git worktree 可实现对话与文件系统的双重隔离。

六、云端运行环境

Codex 支持在云端运行任务，适合处理需要隔离环境或并行执行的工作。前提是先将代码同步到 GitHub。

云端任务的运行流程如下：

1. Codex 创建容器，在指定分支或 commit SHA 上检出你的仓库

2. 运行 setup 脚本（缓存容器恢复时还会运行 maintenance 脚本）

3. 应用网络访问设置（Agent 阶段的网络默认关闭，可配置为受限或不受限）

4. Agent 在循环中执行终端命令、编辑代码、运行检查

5. 如果仓库包含 AGENTS.md，Agent 会用它来找到项目特定的 lint 和 test 命令

6. 完成后展示回答和文件变更的 diff，你可以开启 PR 或追问

云端环境预装了常用语言和工具（codex-universal镜像），也可以自定义 setup 脚本安装额外依赖。容器状态最多缓存 12 小时，加速后续任务。

七、插件与自动化

Skill：能力封装的最小单元

Skill 用任务专属能力扩展 Codex，把指令、资源和可选脚本打包成可复用单元，基于开放的 Agent Skills 标准。

每个 Skill 是一个独立目录，核心是SKILL.md文件。创建方式有两种：

方式一：用内置 creator（推荐入门）

text

$skill-creator Create a skill named xxx that ...

方式二：手动创建文件结构

text

skills/ my-skill/ SKILL.md # 必需：指令和元数据 references/ # 可选：文档、示例、背景材料 scripts/ # 可选：确定性计算或文件处理的脚本 assets/ # 可选：模板、资源文件

SKILL.md以 name 和 description 开头，description 决定了模型何时考虑使用该 skill。正文写详细流程、格式和安全指令。

Skill 可以通过两种方式触发：显式调用（在提示词里写$skill-name，或用/打开菜单选择）和隐式匹配（任务描述与 skill 的 description 匹配时自动选择）。

插件（Plugin）：Skill 的分发格式

Skill 是“编写格式”，Plugin 是“分发格式”。个人自用写 Skill，团队分发用 Plugin。

一个 Plugin 可以打包一个或多个 Skill，也可以同时包含 MCP 配置。Plugin 的清单文件放在.codex-plugin/plugin.json中，声明 skill 目录和 MCP 配置。

Hooks：生命周期扳机

Hooks 解决的是“干活流程走到某个点，自动替我跑段脚本”的问题。它挂在生命周期的固定时机上，事件一到就触发，不依赖模型决策。

主要时机包括：

• UserPromptSubmit：发送指令时——可做敏感信息检查

• PreToolUse：工具执行前——可阻断危险操作

• PostToolUse：工具执行后——可做自动检查、格式化或记录

MCP 集成

MCP（Model Context Protocol）让 Codex 可以连接外部工具和数据源。以 Supabase 为例，官方提供了 Codex 插件，包含：

• MCP Server：远程连接 Supabase MCP 服务器，支持项目管理、SQL 执行、迁移等

• Skills：来自 supabase/agent-skills 的 Agent 技能，如postgres-best-practices

安装方式（以阿里云 Supabase MCP 为例）：

bash

codex mcp add aliyun-supabase \ -- npx -y @aliyun-supabase/mcp-server-supabase@latest

MCP 服务器兼容 Claude Code、Codex 以及任何符合 MCP 规范的 Agent 运行时。

八、安全实践：沙箱、审批与执行策略

一个问题：在 full-auto 模式下，AGENTS.md 的规则可能被忽略。

Codex 实际的安全机制是三层结构：

第一层：沙箱

Codex 使用操作系统级沙箱限制其可访问的资源。默认情况下，写权限限于当前工作区，网络默认关闭。.git和.codex目录即使在可写根目录下也始终为只读。

三种沙箱模式：

第二层：审批策略

三种审批级别：untrusted（不可信）、on-request（按需请求）、never（从不询问）。与沙箱模式可两两组合。不要把danger-full-access+never作为日常配置。

第三层：执行策略

Execution Policies 在沙箱之前评估，可以：

• 允许安全命令免审批执行（allowlist）

• 阻止危险命令执行（blocklist）

实践建议：默认使用workspace-write+on-request，在需要时通过/命令临时提权。AGENTS.md 里写规则有用，但它是提示层的约束，不是安全边界。真正的边界靠沙箱和审批。

九、Code Review 与 PR 自动化

Codex 可以集成到 GitHub 工作流中，实现自动代码审查：

• 在 Codex 设置中开启 Code review 后，可以配置为自动审查每个新 PR，也可以在 PR 评论中通过@codex review手动触发

• 审查完成后，通过@codex fix可以让它直接修改代码并推回分支

• 也可以通过 Codex SDK 的 headless 模式，在 GitHub Actions、Jenkins 等 CI 中构建自定义的代码审查 Action

十、常用命令速查