Codex CLI 介绍和使用

基于：Codex CLI 0.165.0（2026-10-27 发布），macOS arm64 ｜日期：2026-10-29

Codex CLI 是 OpenAI 官方的终端编程智能体：在终端里用自然语言下任务，由它读代码、改文件、跑命令、看结果并迭代。本文覆盖安装登录、TUI 与非交互用法、沙箱与审批、config.toml 配置体系、AGENTS.md / Skills / Hooks / MCP 扩展、多形态入口与排障；命令与配置项按 0.165.0 的 CLI 源码和配置 schema 核对，模型清单取自仓库内置 models.json。

[Codex 是什么](#Codex 是什么)
- [1.1 四种形态](#1.1 四种形态)
- [1.2 核心能力与 2026 现状](#1.2 核心能力与 2026 现状)
安装与登录
- [2.1 安装](#2.1 安装)
- [2.2 登录与认证](#2.2 登录与认证)
- [2.3 升级与自检](#2.3 升级与自检)
交互式使用（TUI）
- [3.1 启动与常用参数](#3.1 启动与常用参数)
- [3.2 一次典型会话](#3.2 一次典型会话)
- [3.3 会话管理](#3.3 会话管理)
- [3.4 斜杠命令速查](#3.4 斜杠命令速查)
沙箱与审批：安全模型
- [4.1 两层防线](#4.1 两层防线)
- [4.2 沙箱三档](#4.2 沙箱三档)
- [4.3 审批策略与 Guardian](#4.3 审批策略与 Guardian)
- [4.4 验证沙箱](#4.4 验证沙箱)
非交互模式与自动化
- [5.1 codex exec](#5.1 codex exec)
- [5.2 codex review](#5.2 codex review)
- [5.3 接入 CI](#5.3 接入 CI)
- [5.4 app-server](#5.4 app-server)
配置体系
- [6.1 配置文件与优先级](#6.1 配置文件与优先级)
- [6.2 常用配置项](#6.2 常用配置项)
- [6.3 完整 config.toml 示例](#6.3 完整 config.toml 示例)
- [6.4 模型与推理强度](#6.4 模型与推理强度)
- [6.5 profiles 多套配置](#6.5 profiles 多套配置)
- [6.6 自定义模型 provider](#6.6 自定义模型 provider)
- [6.7 AGENTS.md 项目规范](#6.7 AGENTS.md 项目规范)
- [6.8 本机配置现状](#6.8 本机配置现状)
扩展体系
- [7.1 Skills](#7.1 Skills)
- [7.2 Hooks](#7.2 Hooks)
- [7.3 MCP](#7.3 MCP)
- [7.4 Plugins / Apps](#7.4 Plugins / Apps)
- [7.5 Memories / Goals / 子代理](#7.5 Memories / Goals / 子代理)
[常见问题 FAQ](#常见问题 FAQ)
参考资料

1. Codex 是什么

Codex CLI 是 OpenAI 的本地 coding agent ，用 Rust 实现：它运行在你的机器上，直接操作当前仓库。和"代码补全"不同，它拥有完整的 agent loop------规划、调用工具、观察结果、自我修正，直到任务完成。
#mermaid-svg-8bJEJ1WNJDqope5i{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-8bJEJ1WNJDqope5i .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-8bJEJ1WNJDqope5i .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-8bJEJ1WNJDqope5i .error-icon{fill:#552222;}#mermaid-svg-8bJEJ1WNJDqope5i .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-8bJEJ1WNJDqope5i .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-8bJEJ1WNJDqope5i .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-8bJEJ1WNJDqope5i .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-8bJEJ1WNJDqope5i .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-8bJEJ1WNJDqope5i .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-8bJEJ1WNJDqope5i .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-8bJEJ1WNJDqope5i .marker{fill:#333333;stroke:#333333;}#mermaid-svg-8bJEJ1WNJDqope5i .marker.cross{stroke:#333333;}#mermaid-svg-8bJEJ1WNJDqope5i svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-8bJEJ1WNJDqope5i p{margin:0;}#mermaid-svg-8bJEJ1WNJDqope5i .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-8bJEJ1WNJDqope5i .cluster-label text{fill:#333;}#mermaid-svg-8bJEJ1WNJDqope5i .cluster-label span{color:#333;}#mermaid-svg-8bJEJ1WNJDqope5i .cluster-label span p{background-color:transparent;}#mermaid-svg-8bJEJ1WNJDqope5i .label text,#mermaid-svg-8bJEJ1WNJDqope5i span{fill:#333;color:#333;}#mermaid-svg-8bJEJ1WNJDqope5i .node rect,#mermaid-svg-8bJEJ1WNJDqope5i .node circle,#mermaid-svg-8bJEJ1WNJDqope5i .node ellipse,#mermaid-svg-8bJEJ1WNJDqope5i .node polygon,#mermaid-svg-8bJEJ1WNJDqope5i .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-8bJEJ1WNJDqope5i .rough-node .label text,#mermaid-svg-8bJEJ1WNJDqope5i .node .label text,#mermaid-svg-8bJEJ1WNJDqope5i .image-shape .label,#mermaid-svg-8bJEJ1WNJDqope5i .icon-shape .label{text-anchor:middle;}#mermaid-svg-8bJEJ1WNJDqope5i .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-8bJEJ1WNJDqope5i .rough-node .label,#mermaid-svg-8bJEJ1WNJDqope5i .node .label,#mermaid-svg-8bJEJ1WNJDqope5i .image-shape .label,#mermaid-svg-8bJEJ1WNJDqope5i .icon-shape .label{text-align:center;}#mermaid-svg-8bJEJ1WNJDqope5i .node.clickable{cursor:pointer;}#mermaid-svg-8bJEJ1WNJDqope5i .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-8bJEJ1WNJDqope5i .arrowheadPath{fill:#333333;}#mermaid-svg-8bJEJ1WNJDqope5i .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-8bJEJ1WNJDqope5i .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-8bJEJ1WNJDqope5i .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-8bJEJ1WNJDqope5i .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-8bJEJ1WNJDqope5i .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-8bJEJ1WNJDqope5i .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-8bJEJ1WNJDqope5i .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-8bJEJ1WNJDqope5i .cluster text{fill:#333;}#mermaid-svg-8bJEJ1WNJDqope5i .cluster span{color:#333;}#mermaid-svg-8bJEJ1WNJDqope5i div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-8bJEJ1WNJDqope5i .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-8bJEJ1WNJDqope5i rect.text{fill:none;stroke-width:0;}#mermaid-svg-8bJEJ1WNJDqope5i .icon-shape,#mermaid-svg-8bJEJ1WNJDqope5i .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-8bJEJ1WNJDqope5i .icon-shape p,#mermaid-svg-8bJEJ1WNJDqope5i .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-8bJEJ1WNJDqope5i .icon-shape .label rect,#mermaid-svg-8bJEJ1WNJDqope5i .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-8bJEJ1WNJDqope5i .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-8bJEJ1WNJDqope5i .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-8bJEJ1WNJDqope5i :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 放行
需升级权限
允许
拒绝
未完成
完成
你用自然语言下任务
模型规划并拆解
调用工具

读文件 / apply_patch / 执行命令 / 联网
沙箱与审批

是否放行？
在沙箱内执行
审批：你 / Guardian
观察结果

测试输出 / 报错 / diff
总结 + 改动清单

1.1 四种形态

形态	入口	说明
终端 CLI / TUI	`codex`	主形态，本文重点；交互式 + `codex exec` 非交互
IDE 扩展	VS Code / Cursor / Windsurf 插件	编辑器内使用，和 CLI 共享同一套配置
桌面 App	`codex app`（macOS / Windows）	图形化体验；`/app` 可把当前会话接续到桌面端
云端 Codex Web	https://chatgpt.com/codex	云端任务；`codex cloud` 可在本地浏览云端任务并应用改动

另外还有一个可编程入口 codex app-server：IDE 插件、桌面端和自动化系统都通过它驱动同一个 agent 内核（见 5.4）。

1.2 核心能力与 2026 现状

能力	说明
代码理解	在当前仓库内检索、阅读、跨文件推理
代码修改	用 `apply_patch` 统一 diff 格式编辑，失败按 hunk 重试
执行验证	跑测试、构建、启动服务，根据输出继续修
联网检索	`--search` 或 `web_search` 配置启用实时搜索
多智能体	`spawn_agent` / 子代理；`/agents`、`/subagents` 管理
跨会话记忆	Memories v2（0.165 起新 profile 默认启用）
安全边界	三平台原生 OS 沙箱 + 审批策略 + Guardian 自动审查
扩展	AGENTS.md、Skills、Hooks、MCP、Plugins、Apps

关键认知 ：各家的 agent loop 已经趋同，差异主要在 沙箱/审批治理 和 扩展生态。Codex 的招牌是"OS 级沙箱 + 与 OpenAI 模型联合调优"------这也是它和模型中立型 harness（opencode、Aider）的本质区别，详见 $\[编程智能体Harness对比$ ]。

0.165.0 值得注意的变化：

模型目录加入 GPT-6.1 Terra（500K 上下文）；主力已转向 GPT-6.x
新增 Google Cloud Vertex AI 内置 provider（model_provider = "gcp"）
Memories v2 对新 profile 默认开启，并支持导入其他 agent 的记忆
对话中可动态调整 reasoning effort（受支持的模型）
app-server API 新增实验性的 attached thread forks

2. 安装与登录

2.1 安装

三种官方方式，按环境选一种即可：

bash 复制代码

# ① 官方安装器（推荐；自带 codex update 自更新）
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# ② Homebrew（macOS）
brew install --cask codex

# ③ npm 全局安装
npm install -g @openai/codex

# 验证
codex --version

Windows（PowerShell）：

powershell 复制代码

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

方式	优点	注意
官方安装器	独立二进制，不依赖 Node，可用 `codex update`	装到 `~/.local/bin` 一类目录，注意 PATH
Homebrew cask	与 mac 生态一致，升级简单	cask 与 npm 混装会产生多个 `codex`
npm	熟悉 Node 工具链	平台二进制包缺失时会报 ENOENT（见 Q1）

也可以直接从 GitHub Releases 下载对应平台压缩包（macOS arm64 选 codex-aarch64-apple-darwin.tar.gz）。

⚠️ 不要混装 ：同一台机器上同时存在 npm 版、brew 版、安装器版时，which codex 可能指向旧的那一份。升级前先确认路径。

2.2 登录与认证

首次运行 codex 会引导登录；也可以显式执行：

bash 复制代码

codex login                    # 浏览器 OAuth，Sign in with ChatGPT
codex login --device-auth      # 无浏览器 / 远程机器：设备码登录
codex login status             # 查看当前登录状态
codex logout                   # 退出登录

# API Key 方式（从 stdin 读入，避免进入 shell history）
printenv OPENAI_API_KEY | codex login --with-api-key

维度	ChatGPT 登录（推荐）	API Key
计费	走 ChatGPT 计划额度（Plus / Pro / Business / Edu / Enterprise）	按 token 计费
云端/桌面等能力	完整	部分能力受限，需要额外配置
典型场景	日常开发	CI、脚本、无交互环境

建议：日常用 ChatGPT 登录；CI 里用 OPENAI_API_KEY 环境变量或 --with-api-key，并配合 codex exec 的非交互模式。

2.3 升级与自检

bash 复制代码

codex update                 # 自更新（安装器/二进制方式最可靠）
codex doctor                 # 诊断安装、配置、认证、运行时健康度
codex --version
codex features list          # 查看特性开关及生效状态
codex completion zsh         # 生成 zsh 补全，重定向到 fpath 目录后生效

codex doctor 是排障的第一站：它会检查二进制是否完整、~/.codex/config.toml 是否合法、认证是否过期。遇到"命令能跑但行为怪异"时先跑它。

3. 交互式使用（TUI）

3.1 启动与常用参数

bash 复制代码

codex                                   # 在当前目录开一个交互式会话
codex "给 OrderService 加分页查询"        # 直接带首个 prompt 启动
codex -C ~/IdeaProjects/spring-ai "梳理这个模块的调用链"
codex -m gpt-6.1-sol "重构这段代码"
codex -s workspace-write -a on-request  # 显式指定沙箱与审批
codex --search "查一下 Spring Boot 3.4 的变更"
codex --add-dir ../shared-lib "同步这个公共库的接口变更"
codex --worktree "在独立 worktree 里试一版方案"

参数	作用
`PROMPT`	首个任务；省略则进入空会话
`-m, --model`	指定模型（如 `gpt-6.1-sol`）
`-s, --sandbox`	`read-only` / `workspace-write` / `danger-full-access`
`-a, --ask-for-approval`	`on-request` / `never`
`-C, --cd`	指定工作根目录
`--add-dir`	额外可写目录（与主工作区并列）
`-i, --image`	附带图片（截图、设计稿），可多张
`--search`	本会话启用实时联网搜索
`--approve-for-me`	用 Guardian 自动审查代替人工审批（`workspace-write` + `on-request`）
`--dangerously-bypass-approvals-and-sandbox`	别名 `--yolo`：关掉沙箱和审批，仅限已外部隔离的环境
`--worktree`	在托管 Git worktree 中开新会话
`-p, --profile`	选用一套 profile 配置
`--oss` / `--local-provider`	使用本地开源模型（Ollama / LM Studio）
`-c, --config`	临时覆盖配置项，见下
`--no-alt-screen`	不用备用屏幕，保留终端滚动历史
`--enable / --disable`	临时开关 feature flag

-c 覆盖示例（优先级最高，适合临时试验）：

bash 复制代码

codex -c 'model="gpt-6.1-terra"' -c 'model_reasoning_effort="high"' "总结这个仓库的架构"

3.2 一次典型会话

先让它读：描述目标 + 约束（技术栈、不许动的文件、验收命令）
计划模式 ：/plan 让它先给方案，不改文件
精确指路 ：用 @src/main/java/.../OrderService.java 提及文件，减少盲搜
小步执行 ：让它先写/改测试，再改实现，再跑 mvn test
审查 diff ：/diff 看全部改动（含未跟踪文件）
收尾：/export 导出对话，或直接让它生成提交信息

提示：Codex 更擅长"有明确验证信号"的任务。把测试命令、构建命令写进 AGENTS.md，它会自己反复跑，直到通过。

3.3 会话管理

命令	作用
`codex resume`	交互式选择历史会话；`--last` 直接续最近一次
`codex fork`	从某个会话分叉出新会话（保留上下文，原会话不变）
`codex queue`	向已存在的会话排队投递一条消息
`codex archive` / `unarchive` / `delete`	归档 / 取消归档 / 永久删除（按 id 或名字）
`codex agents`	打开 agent 控制中心，浏览本地 daemon 上的全部会话
`/rename`、`/export`、`/rollout`	会话内重命名、导出 Markdown、打印 rollout 文件路径

会话默认持久化在 ~/.codex/（sessions/、history.jsonl、state_*.sqlite）。不想落盘时用：

bash 复制代码

codex exec --ephemeral "只跑一次，别留会话"

3.4 斜杠命令速查

在 TUI 输入 / 会弹出命令面板。0.165 的常用命令：

分组	命令
会话	`/new` 新会话、`/resume` 恢复、`/fork` 分叉、`/rename` 重命名、`/archive`、`/delete`、`/clear`、`/compact` 压缩上下文、`/recap` 立即总结、`/export` 导出、`/copy`、`/diff`、`/mention`
模型与权限	`/model` 选模型与推理强度、`/permissions` 管权限、`/approve` 重试一次被 auto-review 拒绝的操作、`/plan` 计划模式、`/goal` 设定长任务目标、`/status` 当前配置与 token 用量、`/usage` 账户额度
扩展	`/skills`、`/hooks`、`/mcp`、`/plugins`、`/apps`、`/memories`、`/init` 生成 AGENTS.md、`/import` 从 Claude Code 导入配置
工作区	`/worktree`、`/cd`、`/pwd`、`/agents`、`/subagents`、`/side`（临时侧聊）、`/ide` 引入编辑器上下文
界面与诊断	`/theme`、`/statusline`、`/title`、`/vim`、`/keymap`、`/tui`、`/raw`、`/ps` 后台终端列表、`/stop`、`/daemon`、`/warnings`、`/debug-config`、`/feedback`、`/logout`、`/quit`

⚠️ 旧教程里的 /approvals 已被 /permissions 取代；遇到对不上的命令，用 / 面板为准。

4. 沙箱与审批：安全模型

4.1 两层防线

Codex 的安全性由沙箱（能做什么）和审批（越界时问谁）共同决定：
#mermaid-svg-Z5L16TAezchnLxgy{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Z5L16TAezchnLxgy .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Z5L16TAezchnLxgy .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Z5L16TAezchnLxgy .error-icon{fill:#552222;}#mermaid-svg-Z5L16TAezchnLxgy .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Z5L16TAezchnLxgy .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Z5L16TAezchnLxgy .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Z5L16TAezchnLxgy .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Z5L16TAezchnLxgy .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Z5L16TAezchnLxgy .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Z5L16TAezchnLxgy .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Z5L16TAezchnLxgy .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Z5L16TAezchnLxgy .marker.cross{stroke:#333333;}#mermaid-svg-Z5L16TAezchnLxgy svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Z5L16TAezchnLxgy p{margin:0;}#mermaid-svg-Z5L16TAezchnLxgy .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-Z5L16TAezchnLxgy .cluster-label text{fill:#333;}#mermaid-svg-Z5L16TAezchnLxgy .cluster-label span{color:#333;}#mermaid-svg-Z5L16TAezchnLxgy .cluster-label span p{background-color:transparent;}#mermaid-svg-Z5L16TAezchnLxgy .label text,#mermaid-svg-Z5L16TAezchnLxgy span{fill:#333;color:#333;}#mermaid-svg-Z5L16TAezchnLxgy .node rect,#mermaid-svg-Z5L16TAezchnLxgy .node circle,#mermaid-svg-Z5L16TAezchnLxgy .node ellipse,#mermaid-svg-Z5L16TAezchnLxgy .node polygon,#mermaid-svg-Z5L16TAezchnLxgy .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Z5L16TAezchnLxgy .rough-node .label text,#mermaid-svg-Z5L16TAezchnLxgy .node .label text,#mermaid-svg-Z5L16TAezchnLxgy .image-shape .label,#mermaid-svg-Z5L16TAezchnLxgy .icon-shape .label{text-anchor:middle;}#mermaid-svg-Z5L16TAezchnLxgy .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Z5L16TAezchnLxgy .rough-node .label,#mermaid-svg-Z5L16TAezchnLxgy .node .label,#mermaid-svg-Z5L16TAezchnLxgy .image-shape .label,#mermaid-svg-Z5L16TAezchnLxgy .icon-shape .label{text-align:center;}#mermaid-svg-Z5L16TAezchnLxgy .node.clickable{cursor:pointer;}#mermaid-svg-Z5L16TAezchnLxgy .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Z5L16TAezchnLxgy .arrowheadPath{fill:#333333;}#mermaid-svg-Z5L16TAezchnLxgy .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Z5L16TAezchnLxgy .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Z5L16TAezchnLxgy .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Z5L16TAezchnLxgy .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Z5L16TAezchnLxgy .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Z5L16TAezchnLxgy .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Z5L16TAezchnLxgy .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Z5L16TAezchnLxgy .cluster text{fill:#333;}#mermaid-svg-Z5L16TAezchnLxgy .cluster span{color:#333;}#mermaid-svg-Z5L16TAezchnLxgy div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Z5L16TAezchnLxgy .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Z5L16TAezchnLxgy rect.text{fill:none;stroke-width:0;}#mermaid-svg-Z5L16TAezchnLxgy .icon-shape,#mermaid-svg-Z5L16TAezchnLxgy .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Z5L16TAezchnLxgy .icon-shape p,#mermaid-svg-Z5L16TAezchnLxgy .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Z5L16TAezchnLxgy .icon-shape .label rect,#mermaid-svg-Z5L16TAezchnLxgy .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Z5L16TAezchnLxgy .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Z5L16TAezchnLxgy .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Z5L16TAezchnLxgy :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 允许
越界
on-request
never
approvals_reviewer = user
auto_review
允许
低风险
高风险
模型提出一个动作

（shell 命令 / 写文件 / 联网）
沙箱策略

允许吗？
沙箱内执行

Seatbelt / bwrap / Windows Sandbox
审批策略
审查者
不询问

失败结果回传给模型
询问你

允许一次 / 本会话 / 拒绝
Guardian 子代理

风险判断
结果回传模型

4.2 沙箱三档

模式	可写范围	网络	适用
`read-only`	不可写	默认禁	只读分析、代码审查、生成文档
`workspace-write`	当前工作区 + 显式 `writable_roots`	默认禁	日常开发（推荐默认）
`danger-full-access`	全盘	放开	已外部隔离的容器/CI，谨慎

bash 复制代码

codex -s read-only "解释这个模块的调用链，不要改代码"
codex -s workspace-write "修复 OrderServiceTest 的失败用例"
codex -s danger-full-access "在容器里跑完整迁移脚本"   # 慎用

workspace-write 的细节在配置里调：

toml 复制代码

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
# 额外可写目录（与主工作区并列）
writable_roots = ["/Users/zhangqin/zzx/shared-lib"]
# 默认 false：沙箱内不能访问网络
network_access = true
# 默认 false 表示 $TMPDIR 与 /tmp 在可写范围内；设为 true 可把它们排除
exclude_tmpdir_env_var = false
exclude_slash_tmp = false

也可以不改配置，用 --add-dir 临时加可写目录。

平台实现：

平台	机制
macOS	Seatbelt（`sandbox-exec` 策略）
Linux	Bubblewrap（仓库内置）+ seccomp；Landlock 作为兜底
Windows	原生受限沙箱（低权限用户 + ACL + 防火墙规则），已不再需要 WSL

子进程继承沙箱边界；恢复会话时也会恢复对应的权限与网络策略。

4.3 审批策略与 Guardian

策略	行为	适用
`on-request`	模型需要越界时才发起审批（受信任项目的默认值）	日常
`never`	从不询问；越界直接失败并把错误回给模型	严格沙箱 + 自动化
`{ granular = {...} }`	按类别细粒度开关（见下）	高级治理

注：旧版的 untrusted / on-failure 已不再作为可配置的审批策略。非受信任项目会由 Codex 自动采用更严格的询问策略；在 TUI 中信任目录后才会放宽。

细粒度审批（按类别关闭打扰）：

toml 复制代码

# true = 该类请求允许弹审批；false = 自动拒绝、不打扰你
approval_policy = { granular = {
  sandbox_approval = true,     # shell 命令越界
  rules = true,                # execpolicy 的 prompt 规则
  request_permissions = true,  # request_permissions 工具
  mcp_elicitations = false,    # MCP 交互式追问
  skill_approval = false       # 技能脚本执行
} }

让 Guardian 替你审（0.147 起）：

bash 复制代码

codex --approve-for-me "修复这个 bug"     # 别名 --not-so-yolo

它等价于 sandbox=workspace-write + approval=on-request + approvals_reviewer=auto_review：Guardian 子代理会检查数据外泄、凭据探测、持久化、破坏性操作；严重风险直接拒绝，高风险升级给你，审查器自身失败时默认拒绝（fail closed）。可调超时：

toml 复制代码

approvals_reviewer = "auto_review"

[auto_review]
timeout_ms = 90000          # 默认 90 秒
policy = "额外审查策略：禁止修改 CI 配置"   # 追加到 Guardian prompt

推荐组合：

场景	命令
只读审查	`codex -s read-only -a on-request "review 这次改动"`
日常开发	`codex -s workspace-write -a on-request`（或 `--approve-for-me`）
CI 自动化	`codex exec -s read-only -c 'approval_policy="never"' ...`
完全隔离的容器	才考虑 `--yolo`

⚠️ --dangerously-bypass-approvals-and-sandbox 会同时关闭沙箱与审批。它只适合"已经在外层容器里隔离"的场景；本机日常使用等于把整个 home 目录交给模型。

4.4 验证沙箱

用 codex sandbox 在同一套策略下跑任意命令，提前确认权限是否够用：

bash 复制代码

# 验证可写范围
codex sandbox -- bash -lc 'echo ok > /tmp/codex-sbx-test && cat /tmp/codex-sbx-test'

# 验证网络是否被禁（应失败）
codex sandbox --log-denials -- curl -sS https://example.com > /dev/null

# 按命名权限 profile 执行
codex sandbox -P ci -- ./scripts/check.sh

--log-denials 会在命令结束后打印 macOS 沙箱拒绝记录，非常适合排查"为什么写不进去/连不上"。

5. 非交互模式与自动化

5.1 codex exec

codex exec（别名 codex e）是无 TUI 的一次性执行入口，适合脚本和 CI：

bash 复制代码

# 直接传 prompt
codex exec "列出这个仓库的所有定时任务"

# 从 stdin 读（省略 prompt 或使用 -）
git diff | codex exec "总结这次改动并生成提交信息"

# 机器可读输出：每行一个 JSON 事件
codex exec --json "跑一遍测试并汇总失败原因" | jq -c 'select(.type=="turn.completed")'

# 只要最终回复，写入文件
codex exec -o /tmp/summary.md "为这个模块补一段架构说明"

# 约束最终输出结构（JSON Schema）
codex exec --output-schema ./review.schema.json "审查这次改动"

# 续跑 / 分叉 / 审查
codex exec resume --last "继续刚才的重构"
codex exec fork <SESSION_ID> "换一个方案试试"
codex exec review --base main

参数	作用
`--json`	输出 JSONL 事件流（适合管道、日志采集）
`-o, --output-last-message`	把最后一条消息写入文件
`--output-schema`	用 JSON Schema 约束最终回答的结构
`--skip-git-repo-check`	允许在非 Git 仓库运行
`--ephemeral`	不持久化会话
`--ignore-user-config`	不加载 `~/.codex/config.toml`（认证仍用 CODEX_HOME）
`--ignore-rules`	不加载 execpolicy 规则
`-s / -C / --add-dir`	与交互式一致

提示：--json 的事件类型会随版本演进（thread.*、item.*、turn.*）；写解析脚本时用 jq 按 type 过滤，不要假设字段全集。

5.2 codex review

专门做代码审查，比"让模型自己看 diff"更结构化：

bash 复制代码

codex review --uncommitted          # 审查暂存 + 未暂存 + 未跟踪
codex review --base main            # 审查相对 main 的改动
codex review --commit abc1234       # 审查某个提交
codex review --commit abc1234 --title "订单幂等修复"
codex review "重点检查事务边界和 N+1 查询"

5.3 接入 CI

GitHub Actions 示例（只读审查，不修改仓库）：

yaml 复制代码

name: codex-review
on: pull_request

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm install -g @openai/codex@0.165.0

      - name: Codex review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex exec -s read-only -c 'approval_policy="never"' --json \
            "审查本次 PR 的改动，按严重程度列出问题，不要修改文件" \
            > codex-review.jsonl
          codex review --base origin/${{ github.base_ref }} >> codex-review.log || true

      - uses: actions/upload-artifact@v4
        with:
          name: codex-review
          path: |
            codex-review.jsonl
            codex-review.log

要点：

CI 里用 API Key + -s read-only + -c 'approval_policy="never"'，避免任何交互
需要 fetch-depth: 0，否则 --base origin/main 拿不到对比基准
想让 Codex 直接改代码并开 PR，才需要 workspace-write，并显式授予 token 权限

5.4 app-server

IDE 插件、桌面端、远程控制都通过 codex app-server 驱动：

bash 复制代码

# 以 WebSocket 方式监听（供 IDE / 桌面端 / 自研客户端连接）
codex app-server --listen ws://127.0.0.1:4222

# 也可用 stdio / unix socket
codex app-server --listen stdio://
codex app-server --listen unix:///tmp/codex.sock

它是实验性接口，适合做集成而不是日常使用；普通开发者用 CLI/TUI 即可。

6. 配置体系

6.1 配置文件与优先级

位置	作用
`~/.codex/config.toml`	用户级主配置
`~/.codex/<name>.config.toml`	profile 文件，`--profile <name>` 时叠加
`<repo>/.codex/config.toml`	项目级配置，仅在受信任项目中加载
`~/.codex/requirements.toml`	企业/管理员约束（限制可选的沙箱、审批、hooks 来源）
命令行 `-c key=value`	最高优先级的临时覆盖

覆盖顺序大致为：CLI 覆盖 → 项目配置 → profile 文件 → 用户配置 → 系统/管理配置。项目级配置不会覆盖管理配置的强制约束。

项目信任：

toml 复制代码

[projects."/Users/zhangqin/IdeaProjects/new_start_2025/spring-ai"]
trust_level = "trusted"

首次在某个目录启动时 TUI 会询问是否信任；信任后才加载该项目的 .codex/config.toml 与项目级 hooks（.agents/skills 里的技能仍会被发现）。不确定当前层级时，在会话里执行 /debug-config，它会打印配置层与来源。

6.2 常用配置项

键	取值 / 默认	说明
`model`	模型 slug	默认模型；也可用 `/model` 临时切
`model_provider`	`openai` 等	选择 provider
`model_reasoning_effort`	模型支持档位	推理强度（见 6.4）
`model_verbosity`	`low` / `medium` / `high`	回答详略（GPT-5+）
`model_reasoning_summary`	`auto` / `concise` / `detailed` / `none`	推理摘要
`approval_policy`	`on-request` / `never` / granular	审批策略
`approvals_reviewer`	`user` / `auto_review`	审批交给谁
`sandbox_mode`	三档	沙箱模式
`sandbox_workspace_write.*`	见 4.2	可写目录、网络、/tmp
`web_search`	`disabled` / `cached` / `indexed` / `live`	联网搜索模式
`service_tier`	`default` / `priority` / `flex`	`priority` 即 Fast（约 1.5--2x 速度，按模型；更多额度）
`project_doc_max_bytes`	`32768`	AGENTS.md 合并后的最大字节数
`project_doc_fallback_filenames`	`[]`	AGENTS.md 缺失时的回退文件名
`project_root_markers`	`[".git"]`	项目根标记
`model_context_window`	由模型决定	覆盖上下文窗口
`model_auto_compact_token_limit`	由模型决定	自动压缩阈值
`check_for_update_on_startup`	`true`	启动时检查更新
`[features]`	见 `codex features list`	特性开关（hooks、plugins、multi_agent...）
`[skills]`	见 7.1	技能启用与预算
`[memories]`	见 7.5	记忆生成与整理模型
`[history]`	---	历史记录策略
`[tui]`	---	主题、状态栏等
`[otel]`	---	OpenTelemetry 上报

6.3 完整 config.toml 示例

一份"日常可用"的保守配置（无敏感信息）：

toml 复制代码

# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "high"      # 日常 high；复杂重构可临时 xhigh
model_verbosity = "medium"
approval_policy = "on-request"
approvals_reviewer = "user"
sandbox_mode = "workspace-write"
web_search = "cached"                 # 默认缓存搜索；需要实时用 --search
service_tier = "default"
check_for_update_on_startup = true

[sandbox_workspace_write]
network_access = false                # 需要联网装依赖时临时改 true
writable_roots = []

# 受信任项目：信任后才加载项目级 .codex/config.toml 与项目 hooks
[projects."/Users/zhangqin/IdeaProjects/new_start_2025/spring-ai"]
trust_level = "trusted"

[features]
hooks = true
plugins = true

6.4 模型与推理强度

内置模型目录（codex debug models --bundled 可查看完整 JSON）：

Slug	显示名	上下文	定位
`gpt-6.1-sol`	GPT-6.1-Sol	272K	最新主力，日常编码与综合任务
`gpt-6-astra`	GPT-6-Astra	272K	前沿智能，最难的任务
`gpt-6.1-terra`	GPT-6.1 Terra	500K	Codex 专用，长上下文
`gpt-6-sol` / `gpt-6-luna`	GPT-6-Sol / Luna	272K	同代不同档位
`gpt-5.6-sol/terra/luna`	GPT-5.6 系列	272K	旧版平衡档（提示升级到 GPT-6-Sol）
`gpt-5.5`	GPT-5.5	272K	Legacy（提示升级）
`gpt-daybreak-blue-latest`	Daybreak Blue	272K	Daybreak 计划（高级网络访问）
`gpt-daybreak-red-latest`	Daybreak Red	372K	同上，上下文更大
`codex-auto-review`	Codex Auto Review	272K	自动审批审查（隐藏）

模型目录由服务端 + 内置目录共同决定，以 /model 实际列表为准 。模型被下线时 Codex 会在 [notice.model_migrations] 里记录迁移提示。

推理强度 （以 gpt-6.1-sol 为例）：

档位	特点	适合
`low`	快，推理浅（该模型默认）	改文案、简单查询
`medium`	速度与深度平衡	常规开发
`high`	更深推理	多文件改造、复杂 bug
`xhigh`	很高	跨模块重构、疑难问题
`max`	最大	极难问题，慢且耗额度
`ultra`	最高档	最难任务（自动任务编排）

切换方式：会话内 /model、启动时 -m、或配置 model_reasoning_effort。0.165 起，受支持的模型可在对话中途调整强度。

6.5 profiles 多套配置

两代写法都支持：

① 内联 profiles （config.toml 里）：

toml 复制代码

[profiles.quick]
model = "gpt-6.1-sol"
model_reasoning_effort = "low"
approval_policy = "never"

[profiles.deep]
model = "gpt-6.1-sol"
model_reasoning_effort = "xhigh"

bash 复制代码

codex -p quick "批量改注释"
codex -p deep "重构订单模块"

② profile 文件 （0.134 起的主推方式）：把上面 [profiles.deep] 的键值单独放到 ~/.codex/deep.config.toml（不要带 [profiles.deep] 表头），然后 codex -p deep。好处是配置隔离、不会把所有实验项堆进主文件。

场景	建议
临时一次	`-c` 覆盖
固定几套习惯	内联 `[profiles.*]`
团队/多环境切换	`~/.codex/<name>.config.toml`

6.6 自定义模型 provider

⚠️ 重要：0.165 的 wire_api 只支持 responses （OpenAI Responses API）。旧教程里的 wire_api = "chat" 已被移除。只有暴露 /v1/responses 兼容端点的网关才能直接接入；普通 OpenAI Chat Completions 服务（包括 DeepSeek 官方 API）不能直接作为 provider。

内置 Vertex AI（0.165 新增）：

toml 复制代码

model_provider = "gcp"
model = "gpt-6.1-sol"

项目与区域通过环境变量指定（GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_LOCATION），认证走 Google ADC（gcloud auth application-default login 或 GOOGLE_APPLICATION_CREDENTIALS）。

自建 Responses 网关：

toml 复制代码

model_provider = "internal"
model = "gpt-6.1-sol"

[model_providers.internal]
name = "Internal Gateway"
base_url = "https://llm.internal.example.com/v1"
env_key = "INTERNAL_LLM_KEY"       # 从该环境变量读取 API Key
wire_api = "responses"
requires_openai_auth = false
request_max_retries = 3
stream_idle_timeout_ms = 300000

# 需要额外请求头时（值是环境变量名，不是明文）
env_http_headers = { "X-Tenant" = "TENANT_ID" }

本地模型：不要手写 provider，直接用内置 OSS 通道：

bash 复制代码

codex --oss --local-provider ollama "..."
codex --oss --local-provider lmstudio "..."

本地/开源模型的能力与工具调用兼容性远不如 GPT 系列，适合离线或隐私场景；配置见 $\[ollama介绍和使用$ ]。如果你在研究 DeepSeek 作为后端的 agent 框架，参考 $\[deepseek-harness介绍和使用$ ]，而不是把 Codex 硬接到 Chat Completions 上。

6.7 AGENTS.md 项目规范

Codex 的项目级上下文来自 AGENTS.md，加载规则（按 0.165 源码）：

从当前目录向上找项目根（默认以 .git 为标记；可用 project_root_markers 改）
从项目根向下到当前目录 ，逐层收集所有 AGENTS.md，按顺序拼接
同一目录下 AGENTS.override.md 优先于 AGENTS.md
合并后总字节数受 project_doc_max_bytes 限制（默认 32 KB）
AGENTS.md 不存在时，按 project_doc_fallback_filenames 依次找替代文件

在项目里生成模板：

bash 复制代码

codex
# 会话内执行
/init

一个 Java/Spring 项目的示例：

markdown 复制代码

# AGENTS.md

## 项目概览
- Spring Boot 3.x + Java 21，Maven 多模块
- 入口：`app-web`；领域服务：`app-domain`

## 构建与测试
- 编译：`mvn -q -DskipTests package`
- 测试：`mvn test -pl app-domain`
- 单测失败时先看 `target/surefire-reports`

## 约定
- 不允许修改 `src/main/resources/application-prod.yml`
- Controller 不写业务逻辑，统一放 Service
- 新增接口必须补 MockMvc 测试
- 提交前必须跑 `mvn test`

## 禁区
- 不要执行数据库迁移脚本
- 不要动 `.github/workflows/`

复用现有 CLAUDE.md（迁移期）：

toml 复制代码

project_doc_fallback_filenames = ["CLAUDE.md"]

Codex 找不到 AGENTS.md 时会读 CLAUDE.md。长期建议只保留一份，避免两套规范漂移；TUI 的 /import 也能从 Claude Code 导入项目设置与最近会话。

6.8 本机配置现状

2026-10-29 实测（~/.codex/config.toml，已隐去密钥与完整路径）：

项	现状	建议
安装	`/usr/local/bin/codex`（npm 全局包），平台二进制缺失，运行报 `spawn ... ENOENT`	按 2.1 重装（见 Q1）
版本记录	更新检查停留在 0.121.0（2026-04-19）	升级到 0.165.0
`model`	`gpt-5.3-codex`（已带迁移提示 → `gpt-5.4`）	改为 `gpt-6.1-sol`
`model_reasoning_effort`	`xhigh`	保留，或日常降到 `high` 省额度
`approvals_reviewer`	`user`	想少打断可改 `auto_review`
受信任项目	6 个（含 `spring-ai` 等）	保持；新目录首次进入时确认信任
认证	已登录（`auth.json` 存在）	升级后 `codex login status` 复核

本机当前状态属于"装了但跑不起来"：version.json 说明 CODE_HOME 正常、更新检查曾经成功，缺的是 npm 包里的 @openai/codex-darwin-arm64 平台二进制。通常是安装中断或 npm 缓存损坏，重装即可，不需要清空 ~/.codex（会话和配置会保留）。

7. 扩展体系

7.1 Skills

Skill 是"给模型看的操作手册"：一个目录 + 一份 SKILL.md，声明何时使用、怎么做。Codex 发现技能的位置：

作用域	路径
用户级（新标准）	`~/.agents/skills/<skill-name>/SKILL.md`
用户级（兼容旧位置，已标记 deprecated）	`~/.codex/skills/<skill-name>/SKILL.md`
项目级	`<repo>/.agents/skills/` 或 `<repo>/.codex/skills/`
内置/插件	Codex 自带技能 + 插件提供的技能根

示例 ~/.agents/skills/spring-review/SKILL.md：

markdown 复制代码

---
name: spring-review
description: 按团队规范审查 Spring Boot 代码，重点检查事务边界、异常处理、N+1 查询与分层。当用户要求 review Spring 代码或 PR 时使用。
---

# Spring Boot 代码审查

## 步骤
1. 先读根目录 `AGENTS.md`，确认项目约定
2. 按 Controller → Service → Repository 顺序检查调用链
3. 重点检查：
   - `@Transactional` 是否加在 public 方法上、是否被同类内部调用绕过
   - 异常是否被统一处理，是否吞异常
   - Repository 是否存在循环查询 / N+1
   - DTO 与实体是否混用
4. 输出：按 `严重 / 建议 / 风格` 三档列出，每条给文件和行号

## 禁忌
- 不要直接改代码；只输出审查意见
- 不要臆测未读过的文件

调用方式：

自动触发 ：模型根据 description 判断是否使用
显式提及 ：输入 $spring-review 或 /skills 选择
关闭/启用：

toml 复制代码

[skills]
include_instructions = true
max_context_tokens = 4000          # 技能目录预算，默认约上下文 2%，上限 10000

[[skills.config]]
path = "/Users/zhangqin/.agents/skills/spring-review/SKILL.md"
enabled = false

Skill 与 Claude Code 的格式基本互通（SKILL.md + frontmatter），可以两边共用一份。

7.2 Hooks

Hooks 在 agent 生命周期事件上执行外部命令，用于审计、拦截、注入上下文。事件（0.165）：

事件	触发时机
`SessionStart` / `SessionEnd`	会话开始 / 结束
`UserPromptSubmit`	用户提交 prompt 后、模型调用前
`PreToolUse`	工具调用前（可阻断）
`PermissionRequest`	Codex 本来要发起审批时
`PostToolUse`	工具调用后
`PreModelRequest` / `PostModelRequest`	每次模型请求前后
`PreCompact` / `PostCompact`	上下文压缩前后
`Stop`	正常结束一轮
`SubagentStart` / `SubagentStop`	子代理开始 / 结束
`Interrupt`	用户中断

配置写在 config.toml（项目级 .codex/config.toml 需项目受信任）：

toml 复制代码

# 记录每次会话开始时间
[[hooks.SessionStart]]
[[hooks.SessionStart.hooks]]
type = "command"
command = "date '+%FT%T' >> ~/.codex/session-audit.log"

# 审计所有工具调用的原始 JSON
[[hooks.PostToolUse]]
[[hooks.PostToolUse.hooks]]
type = "command"
command = "cat >> ~/.codex/tool-audit.jsonl"
timeout = 5

# 拦截疑似危险删除（PreToolUse 退出码 2 = 阻断）
# matcher 匹配工具名；不同版本/别名可能是 shell 或 Bash，
# 不确定时先不写 matcher（对所有工具生效），用脚本自行判断
[[hooks.PreToolUse]]
matcher = "^(shell|Bash)$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "grep -qE 'rm[[:space:]]+-rf[[:space:]]+/' && { echo '阻止：疑似危险删除' >&2; exit 2; } || exit 0"
timeout = 5

行为约定：

hook 从 stdin 收到 JSON 事件，stdout 可作为上下文返回
PreToolUse 退出码 2 表示阻断，stderr 作为拒绝原因回给模型
匹配同一事件的多个 hook 都会执行（不会互相替换）
项目级 hooks 需要项目可信；非托管 hook 首次使用要在 /hooks 中审查，定义变化后需重新审查
自动化场景可用 --dangerously-bypass-hook-trust 跳过信任检查（仅限已审核来源）

Hook 事件名与 Claude Code 基本逐字一致，迁移成本低；但细节字段仍有差异，写脚本前先用一个 cat >> audit.jsonl 观察真实输入。

7.3 MCP

MCP server 为 Codex 提供额外工具。管理命令：

bash 复制代码

# stdio server：命令后面用 -- 分隔
codex mcp add github -- npx -y @modelcontextprotocol/server-github

# Streamable HTTP server
codex mcp add docs --url https://mcp.example.com/mcp

codex mcp list
codex mcp get github
codex mcp login docs        # 需要 OAuth 的 server
codex mcp logout docs
codex mcp remove github

等价配置：

toml 复制代码

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_xxx" }
tool_timeout_sec = 60

[mcp_servers.docs]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "DOCS_MCP_TOKEN"
enabled_tools = ["search_docs", "read_page"]
# disabled_tools = ["delete_page"]

会话内用 /mcp 查看已连接的工具；/mcp verbose 看详情，/mcp login <name> 完成授权。MCP 工具的调用同样受沙箱与审批约束。

7.4 Plugins / Apps

Plugins ：把 skills、hooks、MCP、命令打包分发。TUI 里 /plugins 浏览；CLI 用 codex plugin 管理；配置里通过 [marketplaces] / [plugins] 固定来源与启用状态。
Apps ：Codex 与外部应用（如知识库、工单系统）的连接层，TUI 里 /apps 管理。

插件体系仍在快速演进；企业环境可以用 requirements.toml 限制允许的 marketplace。

7.5 Memories / Goals / 子代理

能力	入口	说明
Memories	`/memories`、`[memories]`	跨会话记忆；0.165 起新 profile 默认启用 v2，可导入其他 agent 的记忆
Goals	`/goal`	为长任务设定目标，后续轮次围绕目标推进
Plan mode	`/plan`	只读规划，不改文件；确认后再执行
子代理	`/agents`、`/subagents`	查看控制中心、在会话的子代理之间切换；`spawn_agent` 由模型自动派生
Worktree	`--worktree`、`/worktree`	在独立 Git worktree 中开会话，互不污染
侧聊	`/side`、`/btw`	临时 fork 一个旁支讨论，不打断主线

8. 常见问题 FAQ

Q1：运行 `codex` 报 `spawn ... codex ENOENT`

本机实测就是这个错误 ：npm 包 @openai/codex 的主包在，但平台二进制 @openai/codex-darwin-arm64 的 vendor 文件缺失。常见原因是安装中断、npm 缓存损坏，或从 Intel 包迁到 arm64 时残留。

bash 复制代码

# 方案一：重装 npm 包
npm uninstall -g @openai/codex
npm cache verify
npm install -g @openai/codex@latest
codex --version

# 方案二：改用官方安装器（不依赖 npm）
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 方案三：Homebrew
brew install --cask codex

# 修复后自检
codex doctor

如果用的是 nvm/fnm，确认 which codex 与当前 Node 前缀一致；/usr/local/bin/codex 与 ~/.nvm/.../bin/codex 同时存在时，优先删掉旧 shim。

重装不会删除 ~/.codex/config.toml、sessions/、auth.json，会话和历史都在。

Q2：升级后提示模型迁移

config.toml 里写死的旧模型（如 gpt-5.3-codex）已不在目录中，Codex 会通过 [notice.model_migrations] 建议新模型。处理方式：

会话内 /model 查看当前可用列表并选择
或直接改配置：model = "gpt-6.1-sol"（日常主力）或 gpt-6.1-terra（长上下文）
查看内置目录：codex debug models --bundled | jq '.models[].slug'

Q3：如何减少审批打断？

按"信任换便利"的顺序：

在 TUI 中信任项目目录（projects 表）
用 --approve-for-me，让 Guardian 自动审查低风险操作
收窄可写范围：workspace-write + 精确的 writable_roots / --add-dir
受控自动化里才用 -a never（TUI）或 -c 'approval_policy="never"'（exec）；不要为了省事直接 --yolo
审批类别太吵时，用 granular 配置逐项关闭（见 4.3）

Q4：沙箱里网络请求失败 / 装不了依赖

workspace-write 默认禁网。几种做法：

toml 复制代码

# 全局放开（不推荐长期开）
[sandbox_workspace_write]
network_access = true

临时用 codex sandbox --log-denials -- curl ... 确认是沙箱拒绝还是网络本身不通
需要联网搜索时，用 --search 或 web_search = "live"，走 Codex 的搜索工具而不是 shell 网络
企业代理：在启动 Codex 的环境里设置 HTTPS_PROXY / HTTP_PROXY，并确认沙箱策略允许代理地址

Q5：写文件被拒绝

read-only 模式下任何写入都会被拒：换 -s workspace-write
目标在仓库外：用 --add-dir 或 writable_roots
/tmp、$TMPDIR 默认在可写范围内；若配置里把 exclude_slash_tmp / exclude_tmpdir_env_var 设成了 true，写这里会被拒
仍失败：codex sandbox --log-denials -- ...（macOS）复现，读沙箱拒绝日志

Q6：能接 DeepSeek / 其他第三方模型吗？

不能直接接 Chat Completions 服务 。当前 wire_api 只支持 responses，DeepSeek 官方 API 是 /chat/completions，协议不匹配。可行路径：

方案	说明
自建 Responses 网关	把上游 chat 协议转换成 `/v1/responses`，再按 6.6 配 `model_providers`
本地模型	`--oss --local-provider ollama` / `lmstudio`
换用模型中立 harness	需要 DeepSeek 原生接入时，用 $\[deepseek-harness介绍和使用$ ] 这类方案

旧教程的 wire_api = "chat" 配方在 0.165 已失效，照抄会报配置错误。

Q7：会话文件在哪里？怎么清理？

内容	位置
会话 rollout	`~/.codex/sessions/`
历史索引	`~/.codex/history.jsonl`
SQLite 状态	`~/.codex/state_.sqlite`、`logs_.sqlite`
认证	`~/.codex/auth.json`（不要提交/外传）

清理优先用 codex archive / codex delete，不要直接删 SQLite（可能损坏索引）。敏感任务用 codex exec --ephemeral 不落盘。

Q8：如何禁止危险命令？

分层设防：

受信任项目的默认策略是 workspace-write + on-request，危险操作会先问
PreToolUse hook 用正则直接阻断（见 7.2）
只读任务用 -s read-only
企业环境用 requirements.toml 锁定可选沙箱与审批策略，并 allow_managed_hooks_only = true
永远不要把 --yolo 写进 shell alias

Q9：和 Claude Code 怎么选？

维度	Codex CLI	Claude Code
厂商/模型	OpenAI，GPT-6.x 系列	Anthropic，Claude 系列
实现/许可	Rust，Apache-2.0	TypeScript，闭源
沙箱	三平台原生 OS 沙箱	可选 sandbox-runtime + worktree
审批	on-request + Guardian 自动审查	权限模式 + hooks
扩展	AGENTS.md / Skills / Hooks / MCP / Plugins	CLAUDE.md / Skills / Subagents / Hooks / MCP
云形态	Codex Cloud / 桌面端 / IDE	Claude Code web / 桌面端 / IDE
互通	支持 `SKILL.md`；`/import` 可从 Claude Code 导入	支持 `SKILL.md`

两者都支持 SKILL.md 规范，技能可以共用；日常可以按"模型偏好 + 团队订阅"二选一，不必强行统一。细节见 $\[claudecode介绍和使用$ ] 与 $\[编程智能体Harness对比$ ]。

Q10：团队如何统一管控？

用 requirements.toml 下发强制约束：允许的审批策略、沙箱模式、reviewer、网络白名单、hook 来源
allow_managed_hooks_only = true 只允许管理员 hook
通过 MDM / 企业配置分发 ~/.codex/config.toml
项目级只提交 <repo>/.codex/config.toml 与 <repo>/.agents/skills/，不要提交个人模型偏好

Q11：怎么看 token 用量？

会话内 /status：当前模型、上下文占用、token 统计
/usage：账户额度与重置时间
脚本：codex exec --json，从 turn.completed 一类事件里取 usage（字段随版本变，先 jq 看一遍再写死）

Q12：为什么每次进新目录都问信任？

Codex 的 projects 信任是按绝对路径记录的。新 clone 的仓库、移动过的目录、worktree 都会被视为新项目，需要重新确认。确认后会写入 config.toml 的 [projects."..."]，可手工整理但不要在未确认来源时批量设 trusted。

Codex CLI 介绍和使用

目录

1. Codex 是什么

1.1 四种形态

1.2 核心能力与 2026 现状

2. 安装与登录

2.1 安装

2.2 登录与认证

2.3 升级与自检

3. 交互式使用（TUI）

3.1 启动与常用参数

3.2 一次典型会话

3.3 会话管理

3.4 斜杠命令速查

4. 沙箱与审批：安全模型

4.1 两层防线

4.2 沙箱三档

4.3 审批策略与 Guardian

4.4 验证沙箱

5. 非交互模式与自动化

5.1 codex exec

5.2 codex review

5.3 接入 CI

5.4 app-server

6. 配置体系

6.1 配置文件与优先级

6.2 常用配置项

6.3 完整 config.toml 示例

6.4 模型与推理强度

6.5 profiles 多套配置

6.6 自定义模型 provider

6.7 AGENTS.md 项目规范

6.8 本机配置现状

7. 扩展体系

7.1 Skills

7.2 Hooks

7.3 MCP

7.4 Plugins / Apps

7.5 Memories / Goals / 子代理

8. 常见问题 FAQ

Q1：运行 codex 报 spawn ... codex ENOENT

Q2：升级后提示模型迁移

Q3：如何减少审批打断？

Q4：沙箱里网络请求失败 / 装不了依赖

Q5：写文件被拒绝

Q6：能接 DeepSeek / 其他第三方模型吗？

Q7：会话文件在哪里？怎么清理？

Q8：如何禁止危险命令？

Q9：和 Claude Code 怎么选？

Q10：团队如何统一管控？

Q11：怎么看 token 用量？

Q12：为什么每次进新目录都问信任？

9. 参考资料

Q1：运行 `codex` 报 `spawn ... codex ENOENT`