Codex 使用指南

本文档整理自 OpenAI Codex 官方文档，用于记录 Codex CLI、IDE 集成、配置、权限、安全和扩展能力的实用用法。

注意： 本文档面向本机/WSL 开发工作流。涉及价格、模型、额度、可用地区、企业策略等信息时，以 OpenAI 官方文档和当前账号实际界面为准。
维护： 涉及模型名称、CLI 参数、订阅权益、沙箱行为、Rules、Hooks、Plugins、MCP、Skills、Subagents、IDE 和 App 能力时，使用前应重新核对官方文档；本仓库最后核对日期为 2026-05-26。

概述
安装与入门
运行形态
核心概念
AGENTS.md — 项目指令
配置体系
权限、沙箱与安全
Rules 命令规则
Hooks 生命周期脚本
Slash Commands 常用命令
MCP 集成
Skills 技能
Subagents 子代理
IDE 集成
非交互模式
Windows / WSL 使用建议
提示词与工作流
最佳实践清单
常见问题
迭代记录
参考

概述

Codex 是 OpenAI 的 AI 编程代理，可以在本地终端、IDE、Web/App 或云端环境中读代码、改代码、运行命令、解释代码、做 review、拆分任务和自动化重复工作。

Codex CLI 是本地终端客户端。它在选定目录中工作，可以读取、修改并运行本机代码；CLI 是开源项目，并用 Rust 构建。Codex 的账号权益、额度、模型和可用入口会随计划变化，使用前以当前账号界面为准。

适合的任务：

阅读陌生代码库并总结架构
修复 bug、补测试、改实现
做代码 review 和风险排查
生成迁移计划、重构计划
执行受控的本地命令、测试、lint
把重复流程沉淀成 Skills、Hooks、MCP、Plugins、非交互脚本

不适合直接放权的任务：

未隔离环境中的破坏性数据库操作
未审阅的生产部署、密钥操作、账单操作
对大范围文件系统或网络的无审批访问
没有测试和验收标准的大规模重写

安装与入门

环境要求

推荐在 WSL2 / Linux shell 中使用：

Node.js 22+（本仓库的 WSL 栈建议用 nvm 管理）
Git、ripgrep、curl 等基础 CLI
可访问 OpenAI / ChatGPT 登录或 API key
项目源码放在 WSL 文件系统，例如 ~/workspace/<project>

安装

1	npm i -g @openai/codex

升级：

1	npm i -g @openai/codex@latest

启动：

1 2	cd ~/workspace/<project> codex

首次运行会提示登录，可使用 ChatGPT 账号或 API key。

常用启动方式

# 在当前目录启动交互式 TUI
codex

# 指定工作目录
codex --cd ~/workspace/my-app

# 启用某个模型
codex --model <model>

# 使用更严格的只读模式
codex --sandbox read-only

# 自动模式：允许在工作区内读写和运行命令，越权时询问
codex --sandbox workspace-write --ask-for-approval on-request

# 附带图片上下文
codex --image screenshot.png

# 临时给额外目录写权限
codex --add-dir ~/workspace/shared

# 启用 live web search
codex --search

# 使用本地开源模型 provider，需要 Ollama 等本地 provider 已运行
codex --oss

危险模式：

1
2
3

codex --dangerously-bypass-approvals-and-sandbox
# 等价短名
codex --yolo

只应在外部隔离的容器、临时 VM、CI runner 中使用，不要在主力工作区里使用。

运行形态

形态	典型入口	适合场景
CLI	`codex`	本地开发、调试、批量修改、终端工作流
IDE Extension	VS Code / JetBrains 插件	和编辑器上下文配合、边写边问、局部改动
Codex App / Web	ChatGPT / Codex Web	云端任务、长任务、异步 review
Non-interactive	`codex exec`	脚本、CI、生成报告、自动化检查
SDK / App Server	Codex SDK / app server	集成到自有系统或平台

当前本机首选：

WSL2 Ubuntu
  -> ~/workspace/<project>
  -> codex

JetBrains Remote Development -> WSL
  -> 使用 WSL 后端和 WSL 工具链

核心概念

机制	作用	是否入库
`AGENTS.md`	给 Codex 的持久项目指令	项目级建议入库
`~/.codex/config.toml`	用户级默认配置	不入库
`.codex/config.toml`	项目级配置	谨慎入库，仅可信项目加载
`.codex/rules/*.rules`	控制哪些命令可越过沙箱	可入库，但要审慎
`hooks.json` / `[hooks]`	在生命周期事件运行脚本	可入库，但要审慎
MCP	连接外部工具和上下文	个人或项目配置
Skills	可复用专业工作流	个人、项目或插件
Subagents	并行代理和自定义代理	按任务使用
Plugins	分发 Skills、MCP、Apps 等能力	按团队策略

Codex 的核心工作方式：

加载指令：全局 AGENTS.md、项目 AGENTS.md、规则、配置。
读取上下文：文件、Git 状态、用户指定的 @file、图片或 MCP 工具。
计划和执行：按权限和沙箱约束读写文件、运行命令。
汇报结果：说明改动、测试、风险和后续建议。

AGENTS.md — 项目指令

AGENTS.md 是 Codex 的项目基础设施。它用于记录 Codex 不容易从代码里自动推断出的约定。

发现顺序

Codex 会在启动时构建指令链：

全局：~/.codex/AGENTS.override.md 优先，否则读 ~/.codex/AGENTS.md
项目：从 Git 根目录向当前目录逐层查找 AGENTS.override.md、AGENTS.md
合并：越靠近当前目录的指令越靠后，覆盖力越强

创建全局指令

1 2	mkdir -p ~/.codex vim ~/.codex/AGENTS.md

示例：

# 全局工作约定

- 使用中文解释关键设计和风险。
- 修改代码前先读取相关文件，不要凭空猜测。
- 修改后优先运行项目已有测试。
- 不要提交或暴露 `.env`、密钥、token。

创建项目指令

1 2	cd ~/workspace/<project> codex

在 Codex CLI 内：

/init

或者手写：

# AGENTS.md

## 项目概述

这是一个 ...

## 常用命令

- 安装依赖：`pnpm install`
- 本地开发：`pnpm dev`
- 测试：`pnpm test`

## 代码规范

- 保持现有目录结构。
- 优先使用项目已有 helper。
- 修改 shared 模块必须补测试。

## 注意事项

- 不要直接修改生成文件。
- 数据库迁移需要用户确认。

应该写什么

应该写	不该写
项目启动、测试、构建命令	能从代码直接读出的逐文件说明
特殊架构约定	泛泛的“写好代码”
禁止触碰的目录或文件	过期的 API 文档全文
非显而易见的坑	频繁变化的临时状态
代码 review、提交、分支规范	密钥、token、内部凭据

配置体系

Codex 使用 TOML 配置。CLI 和 IDE extension 共享配置层。

配置位置

层级	位置	作用
用户级	`~/.codex/config.toml`	个人默认设置
项目级	`.codex/config.toml`	项目覆盖设置，可信项目才加载
系统级	`/etc/codex/config.toml`	机器级默认设置

优先级

从高到低：

CLI flags 和 --config 覆盖
--profile <name> 指定的 profile
项目 .codex/config.toml
用户 ~/.codex/config.toml
系统 /etc/codex/config.toml
内置默认值

基础示例

# ~/.codex/config.toml

model = "gpt-5.5"
model_reasoning_effort = "medium"

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[features]
hooks = true

一次性覆盖

1 2	codex -c model='"gpt-5.5"' -c model_reasoning_effort='"high"' codex -c sandbox_mode='"read-only"'

Profiles

[profiles.review]
model = "gpt-5.5"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "on-request"

[profiles.fast]
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

使用：

1 2	codex --profile review codex --profile fast

权限、沙箱与安全

Codex 的安全控制分两层：

层	作用
Sandbox mode	技术上允许 Codex 读写哪些路径、是否能访问网络
Approval policy	什么时候必须停下来向用户确认

常见沙箱模式

模式	作用
`read-only`	只读，用于审查、解释、计划
`workspace-write`	可写当前工作区，适合日常开发
`danger-full-access`	无沙箱，必须外部隔离

常见审批策略

策略	作用
`untrusted`	更谨慎，适合陌生仓库
`on-request`	日常推荐，越权/网络/危险命令时询问
`never`	不询问，适合受控自动化，不适合主力工作区

场景	推荐
阅读陌生项目	`read-only` + `on-request`
日常编码	`workspace-write` + `on-request`
CI 自动总结	`read-only` + `never`
隔离容器内自动修复	`workspace-write` + `never`
主力机器无沙箱	不推荐

CLI 示例

1
2
3

codex --sandbox read-only
codex --sandbox workspace-write --ask-for-approval on-request
codex exec --sandbox read-only "总结这个仓库的风险点"

Rules 命令规则

Rules 用来控制哪些命令可以在沙箱外执行，或在执行前提示用户。它是实验性功能，格式未来可能变化。

位置

1 2	~/.codex/rules/default.rules <repo>/.codex/rules/default.rules

项目级 rules 只有在项目 .codex/ 配置层被信任时才加载。

示例

# ~/.codex/rules/default.rules

prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "查看 PR 允许，但需要确认",
    match = [
        "gh pr view 123",
        "gh pr view --repo owner/repo",
    ],
    not_match = [
        "gh pr --repo owner/repo view 123",
    ],
)

decision 常见值：

值	含义
`allow`	匹配时允许
`prompt`	匹配时询问
`forbidden`	匹配时禁止

规则应保持窄前缀，避免用过宽的 ["npm"]、["python"] 放开大量未知行为。

Hooks 生命周期脚本

Hooks 是 Codex 的生命周期脚本机制，可以在会话开始、工具调用前后、用户提交 prompt、压缩上下文、子代理启动/结束、停止等时机运行确定性脚本。

启用与关闭

Hooks 当前默认启用。如果需要关闭，在 config.toml 中设置：

1
2
3

# ~/.codex/config.toml
[features]
hooks = false

hooks 是当前规范名称；旧的 codex_hooks 仍可作为兼容别名，但不建议继续写入新配置。

位置

~/.codex/hooks.json
~/.codex/config.toml
<repo>/.codex/hooks.json
<repo>/.codex/config.toml

项目级 hooks 只在可信项目中加载。

常见事件

事件	用途
`SessionStart`	注入会话上下文、加载记忆
`PreToolUse`	工具调用前检查
`PostToolUse`	工具调用后格式化、记录
`PermissionRequest`	审批请求前后做策略检查
`PreCompact` / `PostCompact`	压缩前后保存状态或生成摘要
`UserPromptSubmit`	检查用户 prompt 是否误贴密钥
`SubagentStart` / `SubagentStop`	子代理启动或结束时记录和校验
`Stop`	turn 结束后做校验或通知

示例

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_start.py",
            "statusMessage": "Loading session notes"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/check_command.py"
          }
        ]
      }
    ]
  }
}

注意事项：

多个匹配 hook 都会运行。
同一事件的多个命令 hook 可能并发运行。
Hooks 不应依赖隐式顺序。
非 managed command hook 需要用户审查并信任后才会运行。
可以用 /hooks 查看 hook 来源、信任状态和是否被禁用。
会阻断工作的 hook 要非常可靠，否则会拖慢每次交互。

Slash Commands 常用命令

在 Codex CLI 输入 / 可以打开命令菜单。任务运行中也可以输入 slash command 并按 Tab 排队到下一轮。命令列表会随 CLI 版本变化，以下按 2026-05-26 官方文档和本机工作流整理。

命令	作用
`/permissions`	调整权限、审批和 sandbox 策略
`/model`	切换模型和推理强度
`/fast`	切换当前模型可用的 Fast tier
`/plan`	进入计划模式，可附带 prompt
`/personality`	调整沟通风格
`/diff`	查看当前 Git diff，包括未跟踪文件
`/compact`	压缩上下文
`/clear`	清空终端并开始新对话
`/copy`	复制最近一次完成的 Codex 输出
`/ide`	拉取 IDE 打开的文件、选区等上下文
`/mention`	把文件或目录附加到对话
`/mcp`	查看 MCP 工具；可用 `verbose` 看服务器详情
`/apps`	浏览 apps/connectors 并插入到 prompt
`/plugins`	浏览和管理插件
`/skills`	浏览和使用 skills
`/hooks`	查看、信任或禁用生命周期 hooks
`/agent`	切换子代理线程
`/goal`	设置、查看、暂停或恢复长期目标
`/approve`	对最近被 auto review 拒绝的动作批准一次重试
`/memories`	配置 memory 注入或生成
`/keymap`	配置 TUI 快捷键
`/vim`	切换 Vim 输入模式
`/sandbox-add-read-dir`	Windows 下给 sandbox 增加额外只读目录
`/ps`	查看实验性后台终端输出
`/stop`	停止当前会话启动的后台终端
`/fork`	从当前对话分叉新线程
`/side`	开启临时 side conversation
`/raw`	切换 raw scrollback，便于复制长输出
`/status`	查看模型、权限、上下文、token 等状态
`/init`	生成 `AGENTS.md` 脚手架
`/logout`	登出当前账号
`/quit` / `/exit`	退出 CLI

常用流程：

/plan
让 Codex 先读代码并提出计划，不直接改文件。

/diff
查看 Codex 改了什么。

/permissions
任务中途从 Auto 改成 Read Only，或反过来。

/compact
长会话中保留关键信息，释放上下文。

MCP 集成

MCP（Model Context Protocol）让 Codex 访问外部工具和上下文，例如浏览器、Figma、文档服务、内部 API、数据库只读查询工具。

Codex CLI 和 IDE extension 共享 MCP 配置。

CLI 添加 MCP

1 2	codex mcp add context7 -- npx -y @upstash/context7-mcp codex mcp --help

在 TUI 中查看：

/mcp

config.toml 配置

1
2
3

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

带环境变量：

[mcp_servers.internal-docs]
command = "node"
args = ["/home/user/tools/internal-docs-mcp/server.js"]
env = { DOCS_TOKEN = "..." }

建议：

MCP 工具优先只读，写操作必须可审计。
不把生产密钥写进项目配置。
项目级 MCP 只在可信仓库加载。
危险 MCP 工具要依赖审批，而不是完全静默执行。

Skills 技能

Skills 是 Codex 的可复用工作流。一个 skill 是一个目录，至少包含带 name 和 description 元数据的 SKILL.md，也可以包含 scripts/、references/、assets/、agents/。

Skills 是工作流的作者格式；Plugins 是更适合分发和安装的打包单位。团队内部先写 skill，等需要跨项目分发时再考虑打包成 plugin。

结构

my-skill/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── agents/

SKILL.md：

---
name: my-skill
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.

触发方式

方式	说明
显式	在 prompt 里提到 skill，或用 `/skills` / `$skill-name` 选择
隐式	Codex 根据 `description` 判断是否适用

description 会进入初始上下文用于匹配，应写清楚触发条件和不适用边界。Codex 会在真正使用某个 skill 时再读取完整 SKILL.md，避免一开始塞入大量上下文。

存放位置

范围	位置
当前目录/仓库	`.agents/skills`
用户级	`~/.agents/skills`
系统级	`/etc/codex/skills`
插件	插件包内

如果要创建新 skill，优先使用内置 $skill-creator；手写时也要保持 SKILL.md 元数据准确。

建议：

skill 的 description 写清触发条件和不适用条件。
大段参考资料放 references/，不要全塞进 SKILL.md。
重复命令优先放 scripts/，减少手写错误。
团队通用 skill 可以入库，个人偏好放用户级。

Subagents 子代理

Codex 可以显式启动子代理，把复杂任务拆成并行工作。典型用途：

多角度 code review
大代码库并行探索
多模块改造
安全、性能、测试、可维护性分项审查

当前 Codex release 默认启用 subagent workflow。CLI 和 Codex App 可以看到子代理活动；IDE Extension 的可见性以当前版本为准。

示例 prompt：

请针对当前 PR 派生多个子代理并行 review：
1. 安全问题
2. 业务逻辑 bug
3. 测试遗漏
4. 并发和竞态风险
5. 可维护性

等待所有子代理完成后，按严重程度汇总。

内置代理：

代理	作用
`default`	通用
`worker`	实现、修复、执行
`explorer`	代码库探索、只读分析

CLI 中可以用：

/agent

注意：

Codex 只在你明确要求时启动子代理。
子代理会消耗更多 token 和本地资源。
子代理继承当前沙箱策略。
子代理也会继承当前 turn 的运行时权限覆盖，例如 /permissions 调整或 --yolo。
交互式 CLI 中，非当前线程的子代理也可能弹出审批请求；审批前要确认来源线程。
并行任务要拆成互不冲突的读写范围，避免互相覆盖。

IDE 集成

Codex IDE extension 支持 VS Code、Cursor、Windsurf，也有 JetBrains IDE 集成。JetBrains 集成支持 ChatGPT 登录、API key 或 JetBrains AI subscription。

适合 IDE 的场景

选中代码后解释或重构
使用打开文件和 selection 作为上下文
小步修改和 follow-up
在 IDE 中发起云端任务并应用 diff

JetBrains + WSL 建议

本机建议：

1
2
3

IDEA Remote Development -> WSL
项目路径：/home/<user>/workspace/<project>
Codex / Git / Node / Java / Python：都来自 WSL

检查：

pwd
which git
which node
which java
which python

不要让 IDE 指向 Windows JDK、Windows Node、Windows Git 来处理 WSL 项目。

非交互模式

codex exec 用于脚本、CI、报告生成，不打开 TUI。

基本用法

1	codex exec "总结这个仓库结构，并列出 5 个风险点"

管道：

1	git diff --cached \| codex exec "按 code review 风格总结这次 staged diff"

输出到文件：

1	codex exec "生成最近 10 个 commit 的 release notes" > release-notes.md

不保存会话 rollout：

1	codex exec --ephemeral "分析这个仓库的测试策略"

JSON Lines：

1	codex exec --json "总结仓库结构" \| jq

权限

codex exec 默认使用只读 sandbox。需要写文件时显式声明：

1	codex exec --sandbox workspace-write "修复 lint 问题并运行测试"

隔离环境才考虑：

1	codex exec --sandbox danger-full-access "..."

codex exec --full-auto 仍可能作为兼容参数存在，但官方建议新脚本使用明确的 --sandbox workspace-write。自动化中如果不希望加载用户配置，可以使用 --ignore-user-config；如果要跳过用户和项目 .rules，使用 --ignore-rules。

只需要最终回复写入文件时，可使用：

1	codex exec --output-last-message report.md "总结本次改动"

Windows / WSL 使用建议

Codex CLI 支持 Windows 原生、macOS、Linux。Windows 上可原生在 PowerShell 中运行，也可以在 WSL2 中运行。

本机建议以 WSL2 为主：

Windows
  GUI、浏览器、IDE 前端、Clash、Docker Desktop

WSL2
  源码、Git、Node、Java、Python、Codex、测试、构建

启动方式：

1 2	cd ~/workspace/<project> codex

不要在 /mnt/c、/mnt/d 下作为主力工作区长期开发。不要混用 Windows Git/Node/Java 和 WSL 工作区。

代理、WSL interop、工具链版本管理详见：

1	tools/wsl2-development-stack.md

Windows 原生 Codex app、原生 sandbox、WSL2 启动方式和常见排障详见：

1	tools/codex-windows-guide.md

提示词与工作流

Codex 最稳的 prompt 包含四块：

目标：要改什么或解决什么问题
上下文：相关文件、错误、日志、设计约束
限制：不能动什么、必须遵守什么规范
完成标准：测试通过、行为变化、输出格式

示例：

目标：修复登录页刷新后 session 丢失的问题。
上下文：重点看 src/auth、src/api/session.ts 和最近的错误日志。
限制：不要改数据库 schema，不要引入新依赖。
完成标准：补一个回归测试，运行 auth 相关测试，说明根因和风险。

复杂任务先计划：

1	先进入 plan mode。请阅读相关代码，提出修改计划、风险和需要确认的问题。不要改文件。

实现阶段：

1	按刚才方案实现。改动保持最小范围，完成后运行现有测试。

review 阶段：

1 2	/diff 请按 code review 视角检查当前 diff，优先找 bug、风险和测试遗漏。

最佳实践清单

在 Git 工作区干净或已明确当前 diff 的情况下启动 Codex。
大任务先 /plan，不要直接要求大范围改写。
用 AGENTS.md 沉淀项目约定，不要每次重复口头说明。
让 Codex 先读代码，再要求它修改。
修改后要求 Codex 说明测试结果和未验证风险。
关键改动自己 review git diff。
对陌生仓库先用 read-only 模式。
不在主力机器使用 --dangerously-bypass-approvals-and-sandbox。
MCP、Hooks、Rules 先从只读和窄权限开始。
反复使用的工作流沉淀成 Skill 或脚本。
子代理用于可并行任务，不用于紧耦合的立即阻塞步骤。
CI 中用 codex exec 时显式声明 sandbox，并避免默认加载不受控用户配置。

常见问题

Codex CLI 和 IDE extension 配置是否共享？

共享配置层。用户级配置在 ~/.codex/config.toml，项目级配置在 .codex/config.toml。

为什么项目级 `.codex/` 不生效？

项目级 .codex/ 只在可信项目中加载。未信任项目会跳过项目配置、hooks、rules，但仍加载用户和系统配置。

AGENTS.md 和 config.toml 区别是什么？

AGENTS.md
  写“怎么做”：项目约定、命令、风格、注意事项。

config.toml
  写“能做什么”：模型、审批、沙箱、MCP、功能开关。

Rules 和 Hooks 区别是什么？

Rules
  控制命令是否允许、提示或禁止，重点是权限策略。

Hooks
  在生命周期事件运行脚本，重点是自动化和校验。

Codex 为什么不能联网？

默认情况下，本地 Codex 运行命令时网络通常是关闭或受控的。需要网络时会按审批策略请求权限，或在配置中调整 sandbox/network 策略。优先用明确的审批，而不是直接放开全部网络。

什么时候使用子代理？

适合并行探索和多角度 review。不适合“下一步马上依赖结果”的单一阻塞任务。

什么时候用 codex exec？

适合脚本、CI、报告生成、release notes、批量检查。不适合需要大量来回确认的探索式任务。

迭代记录

2026-05-26：按 OpenAI 官方文档复核 CLI 参数、配置优先级、Hooks feature key、Slash Commands、Skills、Subagents 和 codex exec 非交互模式；补充 Plugins、Apps、Goals、Hooks trust、--yolo、--ignore-user-config 等变化，并移除过期的 /review 示例。
2026-05-06：初始化 Codex 使用指南，整理 CLI、配置、权限、Hooks、MCP、Skills、Subagents、IDE 和非交互模式。

参考

Codex CLI: https://developers.openai.com/codex/cli
Command line options: https://developers.openai.com/codex/cli/reference
CLI slash commands: https://developers.openai.com/codex/cli/slash-commands
Config basics: https://developers.openai.com/codex/config-basic
Agent approvals & security: https://developers.openai.com/codex/agent-approvals-security
AGENTS.md: https://developers.openai.com/codex/guides/agents-md
Rules: https://developers.openai.com/codex/rules
Hooks: https://developers.openai.com/codex/hooks
MCP: https://developers.openai.com/codex/mcp
Skills: https://developers.openai.com/codex/skills
Subagents: https://developers.openai.com/codex/subagents
Plugins: https://developers.openai.com/codex/plugins
IDE extension: https://developers.openai.com/codex/ide
Non-interactive mode: https://developers.openai.com/codex/noninteractive
Best practices: https://developers.openai.com/codex/learn/best-practices