Codex CLI：OpenAI 开源的本机命令行编程 Agent，终端内读改代码、执行命令与审阅变更｜部署与使用全指南

项目仓库： https://github.com/openai/codex

开源协议：Apache-2.0（仓库 LICENSE，Copyright © OpenAI） · 运行语言：Rust（codex-rs Cargo 工作区） · 交付形态：本地命令行交互界面（TUI）、非交互执行器（codex exec）、本地后台 app-server 与可选桌面端联动 · 官方未提供 Docker 镜像 · 默认对外端口：无（CLI/TUI 不监听固定 Web 端口） · 官方文档：Codex Documentation

非官方声明：本文是基于官方 README、仓库 docs/ 目录、配置 Schema 与 CLI 源码整理的部署使用指南，不代表 OpenAI 官方立场。Codex、ChatGPT、OpenAI 等名称归各自权利人所有；本文不附带任何模型令牌、账号密码或会话凭据，所引用的套餐权益、模型目录与计费口径均以 OpenAI 官方账号页面与服务条款为准。项目按现状（AS-IS）提供，本文不构成对代码改动安全性、生成结果正确性、商用授权或平台账号状态的任何担保。

1 项目简介

Codex CLI 是 OpenAI 开源的一款运行在用户本机电脑上的命令行编程 Agent（coding agent）。按照官方 README 的自述，它是 “a coding agent from OpenAI that runs locally on your computer”：你在终端里用自然语言提出任务，Agent 会在当前代码仓库内浏览文件、读取代码、提出并应用补丁、执行 shell 命令、审阅变更，全过程通过终端交互界面（TUI）展示审批请求、命令结果与改动差异。

需要先区分 OpenAI Codex 产品体系中几个不同形态，避免把线上服务与本地工具混为一谈：

• Codex CLI（本文对象）：本机终端里的开源命令行 Agent，源码在 openai/codex 仓库的 codex-rs Rust 工作区中。
• Codex IDE 扩展：面向 VS Code、Cursor、Windsurf 等编辑器的插件形态，入口见官方 IDE 安装文档 developers.openai.com/codex/ide。
• Codex 桌面应用：在已安装 CLI 的 macOS / Windows 环境中执行 codex app 可拉起桌面端，也可访问 Codex App 页面 获取。
• Codex Web（云端 Agent）：OpenAI 的云端任务型 Agent，在线入口为 chatgpt.com/codex，与本机 CLI 是两套部署形态。

CLI 本身是一个本地客户端与编排层：模型推理通过登录后接入的 OpenAI 服务完成，也可以在配置中切换到用户自配的兼容 Provider 或本地模型运行时；代码文件、补丁与命令执行发生在本机沙箱之内。

1.1 核心信息一览

1.2 适用场景

• 在个人或团队的本地代码仓库中，用自然语言描述需求，让 Agent 通读相关文件、给出实现方案并直接落盘补丁，再由人工审阅差异后接受或拒绝。
• 存量代码理解：让 Agent 解释模块结构、调用关系与某段代码的行为，生成代码梳理文档或单元测试雏形。
• 非交互自动化：在 CI、脚本或定时任务中使用 codex exec 以无人值守方式执行修复、审阅或批量任务，事件以 JSONL 输出供流水线解析。
• 代码审阅：用 codex review 对未提交改动、指定基线分支差异或某个 commit 进行非交互审阅，输出问题清单与改进建议。
• 工具扩展：通过 MCP（Model Context Protocol）接入外部服务与本地工具，扩展 Agent 可调用的能力边界；通过插件（plugins）与市场（marketplace）管理扩展来源。
• 团队规范沉淀：在仓库根目录维护 AGENTS.md 与项目级 .codex/ 配置，把编码规范、目录约定与安全要求注入每次会话上下文。

1.3 能力边界（官方口径）

• 本地客户端不等于本地大模型：Codex CLI 运行在本机，但默认通过 ChatGPT 账号或 API Key 接入 OpenAI 云端模型完成推理；代码内容、提示词与工具结果会随请求发送到所选用的模型后端。切换到本地或自托管 Provider 后，对应数据流以该 Provider 为准。
• 模型能力以所选后端为准：支持的模型列表、上下文长度、推理强度档位、联网搜索模式均由当前模型目录（model catalog）与后端能力决定；CLI 不承诺在任何后端下提供完全一致的功能子集。
• 命令执行受沙箱与审批策略约束：Agent 提议的 shell 命令先经过平台沙箱策略（read-only / workspace-write / danger-full-access）与审批策略（on-request / never / 细粒度 granular 规则）两层控制；各平台沙箱实现不同（macOS Seatbelt、Linux bubblewrap / Landlock、Windows 受限令牌），详见 8.4 节与第 10 节。
• 桌面端、IDE 扩展与云端任务是独立形态：codex app 仅在 macOS / Windows 提供；IDE 扩展安装路径见官方文档；云端 Codex Web 的任务队列、权限与计费由 ChatGPT 账号体系管理，不在本机 CLI 配置范围内。
• 仓库不接受外部代码 Pull Request：官方 docs/contributing.md 明确说明，社区贡献以 Issue 报告、复现步骤、日志、根因分析与设计讨论为主，代码改动由 Codex 团队负责；本指南属于第三方整理文档，与官方文档口径冲突时以官方仓库与文档站最新版本为准。
• 官方未提供 Docker 部署路径：仓库内没有官方 Dockerfile 与 docker-compose.yml；本文第 6、7 节分别对应官方安装渠道与源码构建，不编造 Compose 服务、端口与环境变量。

2 功能特性

以下特性整理自官方 README、配置 Schema、CLI 源码（codex-rs/utils/cli、codex-rs/exec、codex-rs/tui、codex-rs/cli）与 TUI 斜杠命令定义；具体菜单位置与参数名称以安装版本内置帮助与 codex --help 输出为准。

2.1 交互式终端会话（TUI）

• 进入仓库目录执行 codex 即启动交互 TUI：上方为会话转录区（模型回复、工具调用、命令输出与改动差异），底部为输入框，状态行展示当前模型、推理强度、权限模式与任务状态。
• 输入框支持多行编辑、历史检索、粘贴突发检测、Vim 模式开关（/vim）、外部编辑器唤起；鼠标选择复制、右键粘贴行为可在配置中调整。
• 会话可随时发起新对话（/new）、保留现场分叉（/fork）、恢复历史会话（/resume、/resume --last）、归档（/archive）或永久删除（/delete）。
• 终端失焦时自动生成会话摘要（auto_recap）；对话过长时自动压缩上下文，也可手动执行 /compact 立即压缩、/recap 生成当前会话回顾。
• 内置 Plan 模式（/plan）用于只规划不执行的阶段；可设置长任务目标（/goal）并在任务进行中查看。

2.2 非交互执行与代码审阅

• codex exec（别名 codex e）以非交互方式运行一个新会话，适合脚本与 CI：支持事件 JSONL 输出（--json）、把最后一条 Agent 消息写入指定文件（--output-last-message/-o）、输出响应结构 Schema（--output-schema）、临时不落盘（--ephemeral）与跳过 Git 仓库检查（--skip-git-repo-check）。
• codex review 专门用于代码审阅：--uncommitted 审阅暂存、未暂存与未跟踪改动；--base <分支> 对比指定基线；--commit <SHA> 审阅单个 commit（可配 --commit-title）；也可以附带自定义审阅指令。
• 支持在独立 Git worktree 中运行会话（--worktree），把实验性改动隔离在新工作树中。

2.3 模型与 Provider 配置

• 登录方式一：启动后选择 Sign in with ChatGPT，使用 ChatGPT 账号套餐（Plus、Pro、Business、Edu、Enterprise 等可包含的 Codex 使用额度，权益以账号页为准）登录；方式二：使用 API Key 通过 codex login --with-api-key 从标准输入读入后保存。
• 内置模型目录之外，可在 config.toml 的 [model_providers.<id>] 中追加自定义 OpenAI 兼容 Provider，配置基础 URL、密钥环境变量、请求头、重试与流式超时、线协议等；model_provider 字段指定当前使用的 Provider。
• 本地开源模型运行时可通过 --oss 进入本地模型模式，配合 --local-provider <lmstudio|ollama> 指定本地服务提供方；对应配置项为 oss_provider。
• 模型粒度参数：model 覆盖所选模型、model_reasoning_effort 推理强度、model_reasoning_summary 推理摘要档位（auto / concise / detailed / none）、model_verbosity 输出详略（low / medium / high）、model_context_window 上下文窗口覆盖、service_tier 服务档位（default / priority / flex，兼容旧 fast 标识）。
• 历史自动压缩阈值由 model_auto_compact_token_limit 控制；工具输出进入上下文的额度由 tool_output_token_limit 控制。

2.4 沙箱、审批与权限体系

• 沙箱三档模式（sandbox_mode）：read-only（只读）、workspace-write（工作区可写，默认常用档）、danger-full-access（完全访问，绕过沙箱）；workspace-write 档下可进一步配置可写根目录、网络访问开关与临时目录排除项。
• 审批策略（approval_policy）：on-request（模型在需要时请求人工批准）、never（永不询问，失败直接返回模型），以及 granular 细粒度结构，分别控制 shell 命令审批、MCP 提示触发、request_permissions 工具触发、execpolicy 规则触发、技能脚本审批、MCP 唤起提示等分类是否放行或自动拒绝。
• 一键自动复核模式 --approve-for-me（别名 --not-so-yolo）：审批请求路由到自动复核器，底层叠加 workspace-write 沙箱与 on-request 策略；--dangerously-bypass-approvals-and-sandbox（别名 --yolo）跳过全部确认与沙箱，仅应在外部已隔离的环境中使用。
• 项目目录信任级别（projects 中的 trust_level：trusted / untrusted）决定套用的默认审批与沙箱策略；命名权限配置文件（permissions）可在 --permission-profile 中调用。
• 生命周期 Hooks（hooks）可在会话开始/结束、模型请求前后、工具使用前后、压缩前后等节点挂载外部命令；企业托管配置可通过 allow_managed_hooks_only 仅保留托管 Hooks。

2.5 MCP 工具接入与插件生态

• mcp_servers 配置块声明外部 MCP 服务，支持 stdio 命令型与 streamable HTTP 型两类传输；可配置环境变量、HTTP 头、OAuth 登录、启动超时、工具超时、工具白/黑名单与启动就绪策略。
• codex mcp 子命令行管理 MCP 服务：list、get <名称>、add <名称>、remove <名称>、login <名称>（OAuth）、logout <名称>；HTTP 型服务支持 Bearer Token 环境变量、OAuth 客户端标识、客户端密钥、注册策略（AUTO / CIMD / DCR）与资源参数。
• 插件体系（codex plugin）支持 add、list、remove 与 marketplace 子命令；marketplaces 配置块管理插件市场来源；插件与 MCP 工具的执行权限仍受审批策略约束。
• 技能（Skills）、记忆（Memories）、预设提示（Presets）、协作模式模板等扩展能力通过配置块与 TUI 命令分别管理；/skills、/memories、/presets 在交互界面内进入对应管理面板。

2.6 工程化与会话管理

• 会话持久化在本地 SQLite 状态库与历史文件中；codex resume、codex fork、codex queue、codex archive、codex unarchive、codex delete 完成会话的恢复、分叉、追加消息、归档、取消归档与删除；codex agents 打开后台共享服务器上的 Agent 任务总览。
• 历史记录写入 ~/.codex/history.jsonl，history.persistence 可取 save-all（保存全部）或 none（不落盘）；history.max_bytes 限制历史文件大小，超出后淘汰最旧条目。
• 诊断日志默认以有界本地存储记录；显式设置 log_dir 后会同时写出纯文本 TUI 日志并把 SQLite 日志库路由到该目录；RUST_LOG 环境变量控制 Rust 日志级别。
• 内置网络搜索工具（web_search）四档模式：disabled（关闭）、cached（缓存）、indexed（索引）、live（实时联网）；交互界面 --search 可在本次会话启用实时联网。
• 其他工程能力：Web 浏览工具（browser_use）、桌面操作工具（computer_use）、网络代理与域名 / Unix Socket 权限策略（network）、通知命令（notify）、OTEL 遥测导出（otel）、特性开关（features）、Shell 环境变量继承策略（shell_environment_policy）等，细节以配置 Schema 为准。

3 官方界面预览

开篇图即官方 README 中使用的 Codex CLI 封面素材（.github/codex-cli-splash.png）。

进入终端交互会话后，界面主要由以下区域构成（依据 TUI 源码与内置斜杠命令面板整理，实际布局以本机版本为准）：

• 会话转录区：展示系统上下文注入、模型回复、工具调用进度、shell 命令执行结果、文件补丁差异与审批弹窗；支持向上滚动检索、原生复制与 Mermaid / 表格 / 数学公式等富文本渲染开关。
• 输入框（composer）：多行自然语言输入，支持历史搜索、排队发送（queue）、Vim 模式与外部编辑器；输入 / 会弹出内置斜杠命令面板，命令按使用频率排序并附中文之外的官方英文描述。
• 状态行与终端标题：默认展示当前模型与推理强度、当前目录、任务活动状态等条目；/statusline 与 /title 可分别配置状态行与终端标签条目的显隐顺序，主题色跟随当前语法主题。
• 审批与权限弹窗：命令执行前按审批策略弹出批准 / 拒绝 / 前缀批准 / 会话内批准等选项；MCP 唤起、技能脚本执行、工具权限请求按 granular 规则分类提示。

官方文档站当前在部分网络环境下有访问限制；除 README 封面素材外，仓库未随附其他可直接下载的界面截图，因此本节不额外配图，避免使用非官方或与项目无关的图片。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• 操作系统（取自 docs/install.md 系统要求表）：
  • macOS 12 及以上；
  • Ubuntu 20.04+ / Debian 10+；
  • Windows 11（WSL2 口径）；README 同时提供 Windows 原生 PowerShell 安装脚本，沙箱能力与受限令牌后端支持范围以官方源码与版本说明为准。
• Git：2.23+，可选但推荐；内置 PR 辅助功能需要 Git 可用。仅使用发布二进制时不强制安装。
• 内存：4GB 最低，8GB 推荐；本地运行模型或同时打开多个会话时建议预留更多系统内存。
• npm 渠道额外要求：本机已安装 Node.js 与 npm；具体受支持的 Node 版本以 npm 包页面 engines 字段为准，本文不凭印象写版本号。
• Homebrew 渠道：仅 macOS；先完成 Homebrew 安装后再执行 brew install --cask codex。
• 源码构建额外要求：Rust 工具链（rustup）、Cargo、just、dotslash、cargo-nextest 等，完整步骤见第 7 节。
• 网络要求：首次登录与模型推理需要访问所选模型后端；MCP 服务、插件市场与更新检查的可达性取决于对应服务地址。使用本地模型 Provider 时，只需本机运行时可达。
• 官方未提供 Docker 镜像：仓库内没有官方 Dockerfile 与 docker-compose.yml；任何第三方打包的容器镜像均不属于官方分发，使用前应自行核验来源、签名与完整性，本文不提供编造的 Compose 路径。

5.2 硬件与系统建议

5.3 目录与环境变量分配

不要把模型 API Key、会话令牌、MCP OAuth 凭据写进公开仓库的 config.toml、截图、文档或聊天记录；自定义 Provider 的密钥优先通过 env_key 指向环境变量注入，参考 8.3 节。

6 方式一：官方安装脚本、npm 与 Homebrew（推荐日常使用）

CLI 工具没有官方 Docker 一键部署，日常使用首选 README 公布的四条官方渠道：安装脚本、npm 全局包、Homebrew Cask、GitHub Releases 原生二进制。

6.1 macOS / Linux：官方安装脚本

README 公布的 Mac / Linux 一键安装命令：

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

安装脚本默认从 https://releases.openai.com/codex 下载独立安装器；当元数据或资产下载不可用时回退到 GitHub Releases。若需要强制走 GitHub Releases 渠道，设置环境变量 CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false（0、no 同样被接受）：

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

安装完成后在终端执行 codex 即可启动。

6.2 Windows：PowerShell 安装脚本

README 公布的 Windows 安装命令：

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

强制使用 GitHub Releases 渠道：

$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false'; irm https://chatgpt.com/codex/install.ps1 | iex

6.3 npm 全局安装

README 公布的 npm 渠道命令：

npm install -g @openai/codex

前置条件是本机已安装 Node.js 与 npm；安装后同样执行 codex 启动。卸载与版本切换以 npm 全局包管理命令为准（如 npm uninstall -g @openai/codex、npm install -g @openai/codex@latest）。

6.4 Homebrew 安装（macOS）

README 公布的 Homebrew 渠道命令：

brew install --cask codex

后续升级用 brew upgrade --cask codex；Cask 包与官方安装器、npm 包三者安装路径相互独立，避免在同一台机器上混用多套安装方式导致命令指向不一致。

6.5 GitHub Releases 原生二进制

前往 latest GitHub Release 下载对应平台归档。README 给出的常用资产：

每个归档内是一个名称中带平台后缀的单文件可执行程序（例如 codex-x86_64-unknown-linux-musl），解压后建议重命名为 codex 并放入 PATH 中的目录：

# 以 Linux x86_64 为例（实际文件名以 Release 页面为准）
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex-x86_64-unknown-linux-musl ~/.local/bin/codex
chmod +x ~/.local/bin/codex
codex --version

6.6 首次登录与启动

1. 进入一个代码仓库目录（或任意目录，非仓库场景配合 --skip-git-repo-check），执行：

codex

2. 首次启动进入登录流程，选择 Sign in with ChatGPT：浏览器打开本机登录回调页面，完成账号授权后回到终端进入会话。ChatGPT Plus、Pro、Business、Edu、Enterprise 等套餐包含的 Codex 额度以 OpenAI 帮助中心 Codex 说明 与账号页面为准。
3. 不使用 ChatGPT 套餐时可改用 API Key 认证：把密钥从标准输入交给 codex login --with-api-key，例如：

printenv OPENAI_API_KEY | codex login --with-api-key

4. 登录状态可用 codex login status 查看；退出登录执行 codex logout。
5. 远程 / 无头服务器没有浏览器时，使用设备码方式登录：

codex login --device-auth

6. 启动后在输入框输入任务描述回车即可；模型、权限模式、联网搜索等可在 TUI 斜杠命令面板中切换，也可用命令行参数临时覆盖（见第 8、9 节）。

安装渠道之间不要混装：脚本安装器、Homebrew、npm 与 Releases 二进制各自的升级与回滚方式不同；切换渠道前先卸载旧版本，避免终端里的 codex 指向旧路径。

7 方式二：Rust 源码克隆与本地构建

适合需要跟踪最新提交、参与本地调试、阅读源码或二次打包的场景。构建步骤取自仓库 docs/install.md。

7.1 克隆仓库与安装 Rust 工具链

# 1. 克隆仓库并进入 Cargo 工作区根目录
git clone https://github.com/openai/codex.git
cd codex/codex-rs

# 2. 安装 Rust 工具链（如本机尚未安装）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

# 3. 安装格式化与 lint 组件
rustup component add rustfmt
rustup component add clippy

# 4. 安装工作区 justfile 使用的辅助工具
cargo install --locked just

# DotSlash 会在首次使用时拉取固定版本的开发工具（如 buildifier）
cargo install --locked dotslash

# 运行 just test 辅助命令使用 nextest
cargo install --locked cargo-nextest

7.2 构建与试运行

# 在 codex-rs 目录下构建
cargo build

# 用示例提示启动 TUI
cargo run --bin codex -- "explain this codebase to me"

构建产物位于 Cargo 工作区 target/ 目录；日常开发与提交前使用根目录 justfile 辅助命令（默认作用于 codex-rs）：

# 格式化
just fmt

# 修复指定 crate（替换为你改动的 crate 名称）
just fix -p <crate-you-touched>

# 运行指定 crate 的测试（示例：codex-tui）
just test -p codex-tui

# 通过 nextest 运行整体测试套件
just test

docs/install.md 同时提示：日常本地运行不要使用 --all-features，它会增加构建时间并让 target/ 磁盘占用额外编译多套特性组合。

7.3 开发者补充说明

• 项目业务逻辑集中在 codex-core crate，供各 Rust 界面（TUI、app-server、exec 服务等）复用；不同平台的沙箱后端分别在 linux-sandbox、bwrap、mxc-sandbox、shell-command 等 crate 中实现。
• 官方 docs/contributing.md 明确：不接收外部代码贡献与 Pull Request；本地构建仅用于学习、调试与打包实验，问题反馈请通过 Issue 提交复现步骤、日志与环境信息。
• 本地构建前确认本机 Rust 版本满足工作区 rust-toolchain 与各 Cargo.toml 要求；构建失败先检查 rustup show 与系统链接器（Linux 需 gcc / clang 与 pkg-config 等基础构建组件，按发行版包管理器补齐）。
• 源码调试时可配合 8.6 节日志配置与 9.5 节诊断命令；codex debug models 可导出当前模型目录 JSON，codex debug prompt-input 可查看发送给模型的上下文输入结构。

8 配置项说明

8.1 配置文件位置与加载层级

• 用户配置：$CODEX_HOME/config.toml（默认 ~/.codex/config.toml）。
• 配置 Profile：[profiles.<名称>] 定义命名配置单元，命令行 --profile/-p <名称> 叠加 $CODEX_HOME/<名称>.config.toml 到基础用户配置之上。
• 项目配置：在项目根目录（由 project_root_markers 默认标记 .git 向上查找）内的 .codex/ 目录与 AGENTS.md 指令文件。
• 托管 / 企业配置：由集中管理方下发的 requirements 与托管配置层；allow_managed_hooks_only = true 只能写在 requirements.toml 中，用于忽略用户、项目与会话级 Hooks 配置、仅保留托管 Hooks。
• 命令行覆盖：每次启动可用 -c key=value（或 --config key=value）追加任意数量覆盖项，支持点号路径嵌套，右侧值按 TOML 解析，解析失败则作为字面字符串。
• 单条命令示例：

codex -c model="gpt-5-codex" -c sandbox_mode="read-only" -c web_search="cached"

config.toml 中出现当前版本无法识别的字段时，可加 --strict-config 让程序直接报错退出，便于尽早发现配置拼写错误。

8.2 核心通用配置表

下表字段均来自仓库 codex-rs/core/config.schema.json；默认值以 Schema 与打包默认值 codex-rs/config/defaults.toml 为准，未列出的字段参考官方 配置参考 与 Schema 最新版本。

8.3 模型与 Provider 配置

8.3.1 内置 OpenAI 后端

默认使用 ChatGPT 登录态或内置 OpenAI API 后端；chatgpt_base_url 覆盖 ChatGPT（区别于 OpenAI API）请求的基础 URL；openai_base_url 覆盖内置 openai Provider 的基础 URL；openai_base_url 之外的自定义端点统一走 [model_providers]。

8.3.2 自定义 Provider 结构

[model_providers.<id>] 支持的字段（取自 ModelProviderInfo Schema）：

示例骨架（密钥通过环境变量注入，占位值请按自身环境替换）：

[model_providers."local-compat"]
name = "本地兼容端点"
base_url = "http://127.0.0.1:1234/v1"
env_key = "LOCAL_COMPAT_API_KEY"
wire_api = "responses"
requires_openai_auth = false

# 指定当前使用的 Provider（取消注释后生效）
# model_provider = "local-compat"
# model = "对应模型标识"

Schema 保留 experimental_bearer_token 字段用于直接写入 Bearer 令牌，但官方明确不鼓励使用，优先通过 env_key 或 auth 命令获取令牌。

8.3.3 本地开源模型

命令行 --oss 进入本地模型模式，--local-provider <lmstudio|ollama> 指定本地运行时；配置层对应 oss_provider = "ollama" 或 oss_provider = "lmstudio"。本地模型的可达地址、模型名与上下文窗口以所选用运行时的配置为准，CLI 不内置模型文件。

8.4 沙箱与审批配置

8.4.1 沙箱模式

sandbox_workspace_write 子字段：

8.4.2 审批策略

• approval_policy = "on-request"：模型在判断需要人工确认时发起审批请求。
• approval_policy = "never"：永不询问；执行失败立即返回模型，不再升级到人工审批。
• granular 对象 [approval_policy.granular] 字段：

8.4.3 平台沙箱实现口径（取自 codex-core README）

• macOS：依赖 /usr/bin/sandbox-exec，使用 Seatbelt 配置文件；workspace-write 策略在配置的可写根内开放写入，同时保持 .git、gitdir 目标与 .codex 只读；网络与文件读写根由 SandboxPolicy 统一控制。
• Linux：优先使用 PATH 中当前目录之外找到的 bwrap；bwrap 过旧不支持 --argv0 时走无 --argv0 兼容路径；缺失时回退到随 Codex 打包的 codex-resources/bwrap，并通过常规通知路径给出启动警告；无法创建用户命名空间时同样给出启动警告。WSL2 走普通 Linux bubblewrap 路径；WSL1 不支持 bubblewrap 沙箱，因为无法创建所需用户命名空间，会在进入 bwrap 路径前拒绝对应沙箱命令。
• Windows：遗留 read-only、workspace-write 策略等价于完整文件系统读访问；当前实现支持受限令牌后端与提权后端两种路径，精确可读 / 可写根由拆分文件系统策略表示；无法直接执行的策略会失败关闭（fail closed），而不是降级为弱强制。

8.5 MCP 服务配置

[mcp_servers.<名称>] 支持的主要字段（取自 RawMcpServerConfig Schema）：

配置示例骨架（命令与参数仅为结构演示，使用时替换为实际服务）：

[mcp_servers."example-stdio"]
command = "npx"
args = ["-y", "example-mcp-server"]
env = { "EXAMPLE_API_KEY" = "从环境变量注入，不要直接写密钥" }
enabled = true

[mcp_servers."example-http"]
url = "https://example-mcp.example.com/mcp"
bearer_token_env_var = "EXAMPLE_MCP_TOKEN"
enabled = true

也可以不手工编辑文件，使用 codex mcp add 写入配置（见 9.3 节）。

8.6 TUI、历史、日志与其他模块

• [tui]：交互界面专项配置，常用字段包括 animations（动画总开关，默认 true）、auto_recap（失焦自动摘要，默认 true）、alternate_screen（auto / always / never）、notifications（桌面通知总开关，默认 true）、notification_condition（unfocused / always）、notification_method（auto / osc9 / bel）、theme（kebab-case 主题名，覆盖自动明暗判定）、vim_mode_default（默认进入 Vim Normal 模式，默认 false）、mouse_scroll_speed、copy_on_select、right_click_paste、status_line / status_line_use_colors、terminal_title、effects（welcome / shimmer / spinner / starfield / progress / effort / title 分项动画）、rendering（列表、表格、数学公式、Mermaid 富文本渲染开关）、presets（数字 0–9 保存的快捷输入）、keymap（按上下文重绑快捷键）等。
• [history]：persistence = "save-all"（默认，落盘全部条目）或 "none"（不落盘）；max_bytes 为历史文件最大字节数，超出后淘汰最旧条目。
• 日志：RUST_LOG 环境变量控制 Rust 日志级别；非交互 codex exec 默认 RUST_LOG=error，消息内联打印，无需单独跟踪文件。显式设置 log_dir 后可查看纯文本 TUI 日志：

codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log

• [hooks]：支持 SessionStart、SessionEnd、UserPromptSubmit、PreModelRequest、PostModelRequest、PreToolUse、PostToolUse、PreCompact、PostCompact、Interrupt、Stop、SubagentStart、SubagentStop、PermissionRequest 等生命周期节点的命令数组；每个节点可挂多条命令；托管模式下可被企业配置整体覆盖。
• [skills]：按 SKILL.md 路径登记用户级技能条目，支持 enabled、按名称或路径选择。
• [profiles] / [projects]：命名配置单元复用；projects 按目录记录 trust_level（trusted / untrusted）等项目级覆盖。
• [network]：代理、域名与 Unix Socket 放行规则、本地回环绑定、SOCKS5 与 MITM 钩子等网络策略；详细字段以 Schema 为准。
• [browser_use] / [computer_use]：浏览器工具与桌面操作工具的来源与应用访问策略，默认按内置安全口径收口。
• [otel]：OpenTelemetry 导出器类型、协议、TLS 与指标开关；关闭 analytics.enabled 不影响自定义 OTLP 导出器。

9 常用运维命令

以下命令按日常使用场景整理；子命令与参数以本机 codex --help、codex <子命令> --help 输出为准。

9.1 登录、登出、更新与自检

# 查看当前登录状态
codex login status

# 使用 API Key 登录（密钥从标准输入读入，避免出现在 shell 历史中）
printenv OPENAI_API_KEY | codex login --with-api-key

# 使用访问令牌登录（环境变量 CODEX_ACCESS_TOKEN）
printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

# 无头 / 远程机器设备码登录
codex login --device-auth

# 登出并移除本机保存的凭据
codex logout

# 检查本机安装、配置、认证与运行时健康状态
codex doctor

# 更新到最新版本（安装渠道支持时）
codex update

# 生成 shell 补全脚本（默认 bash，可选 zsh / fish / powershell / elvish 等）
codex completion

9.2 交互式启动与常用参数

# 进入当前目录的交互会话
codex

# 启动时直接附带提示词
codex "梳理这个仓库的模块结构并给出测试建议"

# 指定模型与权限模式启动
codex --model "<模型标识>" --sandbox workspace-write --ask-for-approval on-request

# 进入工作目录（短选项 -C）
codex --cd /path/to/project

# 额外可写目录（可重复）
codex --add-dir /path/to/other/dir

# 本地模型模式并指定本地提供方
codex --oss --local-provider ollama

# 本次会话启用实时联网搜索
codex --search

# 不启动共享后台服务器
codex --no-daemon

# 不使用交替屏幕模式，保留终端回滚历史
codex --no-alt-screen

# 命令行配置覆盖（可多次出现）
codex -c web_search="cached" -c tui.theme="dark"

# 临时使用命名 Profile
codex --profile work

# 在新的 Git worktree 中运行会话
codex --worktree

常用共享参数（SharedCliOptions）：--model/-m、--oss、--local-provider、--profile/-p、--sandbox/-s、--approve-for-me（别名 --not-so-yolo）、--dangerously-bypass-approvals-and-sandbox（别名 --yolo）、--dangerously-bypass-hook-trust、--cd/-C、--worktree、--add-dir、--image/-i（逗号分隔多张附图）。

9.3 MCP 服务管理

# 列出已配置的 MCP 服务
codex mcp list
codex mcp list --json

# 查看单个服务配置
codex mcp list > /dev/null && codex mcp get <名称>
codex mcp get <名称> --json

# 添加 stdio 型服务（-- 后为启动命令与参数）
codex mcp add <名称> --env KEY=VALUE -- <启动命令> [参数...]

# 添加 streamable HTTP 型服务
codex mcp add <名称> --url https://example-mcp.example.com/mcp \
  --bearer-token-env-var EXAMPLE_MCP_TOKEN

# OAuth 登录 / 登出指定 MCP 服务
codex mcp login <名称>
codex mcp login <名称> --no-browser --scopes "scope-a,scope-b"
codex mcp logout <名称>

# 移除服务配置
codex mcp remove <名称>

HTTP 型服务可选 OAuth 参数：--oauth-client-id、--oauth-client-secret、--oauth-client-registration AUTO|CIMD|DCR、--oauth-resource；添加命令的参数细节以 codex mcp add --help 为准。

9.4 插件、特性开关与会话管理

# 插件列表 / 添加 / 移除 / 市场管理
codex plugin list
codex plugin add <插件标识>
codex plugin remove <插件标识>
codex plugin marketplace

# 列出全部特性开关及其阶段与启用状态
codex features list

# 启用 / 关闭指定特性
codex features enable <feature-key>
codex features disable <feature-key>

# 恢复历史会话（选择器默认；--last 继续最近一次；--all 显示全部目录下会话）
codex resume
codex resume --last
codex resume --all

# 分叉历史会话
codex fork
codex fork --last

# 归档 / 取消归档 / 永久删除会话
codex archive <会话ID或名称>
codex unarchive <会话ID或名称>
codex delete <会话ID或名称>
codex delete --force <UUID>

# 向已有会话追加消息
codex queue <会话ID或名称> "<消息>"

# 打开共享后台服务器上的 Agent 任务总览
codex agents

9.5 非交互执行、审阅与诊断

# 非交互方式执行任务（提示词缺省时从 stdin 读取）
codex exec "修复 README 中的拼写错误"

# 事件以 JSONL 输出，最后一条 Agent 消息写入指定文件
codex exec --json --output-last-message ./last-message.md "总结当前仓库变更"

# 不持久化会话文件；跳过 Git 仓库检查；忽略用户配置与规则文件
codex exec --ephemeral --skip-git-repo-check --ignore-user-config --ignore-rules "任务描述"

# 审阅未提交改动（暂存 + 未暂存 + 未跟踪）
codex review --uncommitted

# 对比指定基线分支审阅
codex review --base main

# 审阅单个 commit（可附带审阅标题与自定义指令）
codex review --commit <SHA> --commit-title "提交标题" "重点检查错误处理与边界条件"

# 调试：导出当前模型目录 JSON
codex debug models
codex debug models --bundled

# 调试：查看发送给模型的上下文输入结构
codex debug prompt-input

# 查看后台终端任务与停止
# （TUI 内）/ps 列出后台终端；/stop 停止全部后台终端

9.6 备份与恢复建议

# 仅备份配置与外观（不含凭据与会话库）的示例打包命令
tar -czf codex-config-backup.tar.gz \
  -C ~/.codex config.toml themes/ pets/ 2>/dev/null || true

10 常见故障排查

以下问题按官方文档、Schema 说明、codex-core README 平台口径与 Issue 高频场景整理；排查时先用 codex doctor 收集安装、配置、认证与运行时信息，再按小节逐项定位。

10.1 登录回调在无头服务器 / SSH 环境打不开浏览器

• 现象：codex 或 codex login 启动后提示本地登录服务器地址，浏览器无法在远程机器上打开，授权流程卡住。
• 处理：改用设备码登录：codex login --device-auth；按终端提示在任意可访问浏览器中完成授权。仍失败时检查本机能否访问 ChatGPT 登录域与回调端口，必要时通过 codex login status 确认旧凭据状态后 codex logout 重新登录。

10.2 API Key 登录失败或提示密钥无效

• 处理：确认通过 --with-api-key 从标准输入传入密钥（参考命令见 9.1 节），不要使用已废弃的 --api-key 直接内联传参；检查对应 Provider 的 env_key 环境变量是否在当前 shell 生效；切换自定义 Provider 时核对 base_url、wire_api 与后端兼容协议；错误信息中不要附上完整密钥，排查时仅保留脱敏片段。

10.3 Linux 沙箱警告：bwrap 缺失、版本过旧或无法创建用户命名空间

• 现象：启动或命令执行时提示 bubblewrap 不可用、过旧或无法创建用户命名空间；命令被沙箱路径拒绝。
• 口径（codex-core README）：helper 优先使用当前目录之外 PATH 中的 bwrap；过旧不支持 --argv0 时走兼容路径；缺失时回退打包的 codex-resources/bwrap 并给出启动警告；无法创建用户命名空间同样产生警告。
• 处理：确认系统已安装 bubblewrap 且版本支持所需参数；容器化或受限内核环境中用户命名空间可能被禁用，此时应在外部隔离环境中运行，并明确理解 danger-full-access 模式的风险；WSL1 不支持 bubblewrap 沙箱，需切换到 WSL2 或按官方文档口径选择可用模式。

10.4 只读 / 工作区模式下命令写文件或联网被拒绝

• 原因：read-only 不允许写入；workspace-write 默认 network_access = false，且 .git、.codex 等目录保持只读。
• 处理：确有跨目录写入需求时用 --add-dir 追加可写根，或在 sandbox_workspace_write.writable_roots 中声明；需要联网时设置 sandbox_workspace_write.network_access = true；不要在常规项目中直接切到 danger-full-access 解决局部权限问题。

10.5 配置字段不被识别或启动时报配置解析错误

• 处理：加 --strict-config 启动，让不识别字段直接报错并定位拼写错误；核对字段层级与 TOML 语法，数组与表内字符串按 Schema 类型书写；使用 -c key=value 覆盖时右侧值先按 TOML 解析，纯字符串需要加引号；多个 Profile 叠加时用 /debug-config（TUI 内）或对应调试命令查看各配置层来源。

10.6 MCP 服务启动失败、工具不出现或超时

• 现象：codex mcp list 中服务标记未就绪；TUI 工具面板看不到该服务工具；启动阶段卡住直到超时。
• 处理：核对 command / args / cwd / env 是否在当前 shell 可执行；HTTP 服务核对 url、bearer_token_env_var 与 OAuth 状态；调整 startup_timeout_ms / startup_timeout_sec；把 required 设为非必填可避免单服务拖慢启动；startup_readiness 允许使用已缓存工具目录；查看 log_dir 下纯文本日志中该服务的连接错误。

10.7 模型不可用、上下文超限或回复被压缩

• 处理：先用 codex debug models 核对当前模型目录与可选模型；上下文接近阈值时执行 /compact 或调整 model_auto_compact_token_limit；自定义 Provider 检查 model_context_window、流式超时与重试配置；切换 model_reasoning_effort、model_reasoning_summary 与 model_verbosity 档位观察是否为后端不支持的组合。

10.8 后台会话 / 任务状态异常或界面行为错乱

• 处理：先用 codex --no-daemon 启动绕开共享后台服务器，确认是否由守护进程状态引起；通过 codex daemon 相关命令查看与重启后台服务（命令集以 codex app-server --help / 文档为准）；异常会话用 codex archive 归档后新建会话；codex doctor 检查安装完整性；删除旧状态库前先备份 $CODEX_HOME。

10.9 非交互模式退出码、输出格式与 CI 集成问题

• 处理：CI 中固定使用 codex exec --json 解析事件流，用 --output-last-message 提取最终消息；按进程退出状态（codex-exec 退出码定义见 codex-exec crate）判断成功 / 失败 / 被拒绝；--ignore-rules、--ignore-user-config、--ephemeral 仅在受控流水线中使用；不要在无人值守流水线中开启 --dangerously-bypass-approvals-and-sandbox。

10.10 升级后命令找不到、版本不一致或安装渠道冲突

• 现象：终端 codex --version 与预期版本不符；which codex 指向脚本安装器、npm 或 Homebrew 的混合路径。
• 处理：确认当前使用的安装渠道（6.1–6.5 节），卸载其他渠道残留；脚本安装器与 Homebrew 可分别用对应包管理命令移除；npm 渠道用 npm uninstall -g @openai/codex；Releases 二进制删除 PATH 中的旧文件后替换新归档；codex update 仅对支持该机制的安装包生效，npm / Homebrew 渠道请回到对应渠道升级。

10.11 日志获取与敏感信息脱敏

• 常规排障：codex doctor；详细运行日志：设置 log_dir 后查看 codex-tui.log，并用 RUST_LOG=debug 调整 Rust 日志级别；非交互模式消息内联打印，无需单独跟踪文件。
• 向 Issue 提交日志前，按 docs/contributing.md 要求移除认证令牌、API Key、内网地址与未公开代码片段；官方安全漏洞请走 SECURITY.md 中的 Bugcrowd 渠道，不要在公开 Issue 中披露。

11 风险与合规说明

以下条款整理自仓库 LICENSE、README、docs/contributing.md、SECURITY.md、docs/open-source-fund.md、配置 Schema 与通用合规口径；如与官方原文不一致，以仓库 LICENSE、README 与 Codex Documentation 最新版本为准。

11.1 开源协议（Apache-2.0）

Codex CLI 源码采用 Apache License 2.0（LICENSE 文件，Copyright © OpenAI）。Apache-2.0 允许自由使用、修改与再分发，修改后再分发需保留版权声明、许可证副本与显著的修改说明；协议内含专利授权条款，不要求衍生作品强制开源（与 AGPL 等 copyleft 协议不同）。仓库中打包或引用的第三方组件各自遵循其原始许可证，二次集成前应逐项核对。

11.2 账号套餐、API 计费与服务条款

• ChatGPT 账号登录后可使用的 Codex 额度、模型范围与速率限制由所选套餐（Plus、Pro、Business、Edu、Enterprise 等）与 OpenAI 服务条款决定；本文不代表官方承诺具体额度、模型清单或可用性。
• API Key 模式下的调用量按 OpenAI 平台计费规则结算；自定义 Provider 的计费与额度由对应服务提供方规定。
• 官方 docs/contributing.md 明确不接收外部代码 Pull Request；社区规则反馈与功能建议通过 Issue 渠道提交，使用者应同时遵守 Contributor Covenant 行为准则。

11.3 代码与数据隐私

• 使用 OpenAI 云端模型后端时，提示词、读取到的代码文件、命令输出与 MCP 工具结果会随 API 请求发送到对应模型后端；在公开代码仓库、私有项目、商业代码与未发布素材上使用前，应确认所在组织的代码外发政策与合规要求。
• 切换到本地或自托管 Provider 后，数据流以该运行时与网络策略为准；[network]、browser_use、computer_use、MCP 工具仍可能把本机信息发送到外部服务，按需在配置中关闭未使用的工具。
• 认证凭据默认存放在 $CODEX_HOME/auth.json 与 $CODEX_HOME/.credentials.json；更安全的后端为系统 keyring（cli_auth_credentials_store = "keyring"、mcp_oauth_credentials_store = "keyring"）；不要把凭据提交到 Git 仓库、截图、公开文档或聊天记录。

11.4 命令执行与沙箱安全

• Agent 可以提议并执行 shell 命令、写入工作区文件；即使在 workspace-write 模式下，也应养成审阅补丁差异与审批弹窗后再确认的习惯。approval_policy = "never" 与 danger-full-access 会显著降低安全水位，仅应在容器、虚拟机或其他外部已隔离环境中短期使用。
• --dangerously-bypass-hook-trust 跳过 Hook 来源持久化信任校验，仅用于已经人工审核过 Hook 来源的自动化场景；自定义 Hooks 与技能脚本等价于在本机执行第三方代码，安装前应阅读其内容与更新状态。
• 项目目录信任级别（trusted / untrusted）影响默认套用的审批与沙箱策略；克隆陌生仓库后先以 read-only 模式进入会话，审阅后再放宽权限。
• 历史会话、补丁记录与日志可能包含敏感代码与环境信息；备份、归档与分享前先脱敏，公开发布前清理 $CODEX_HOME 中不需要的本地记录。

11.5 MCP、插件与供应链风险

• MCP 服务与插件可以访问本机文件、执行命令与发起网络请求；codex mcp add、codex plugin add 的来源应限定为可信市场与明确维护的项目，安装后定期更新并在不用时移除。
• HTTP 型 MCP 服务的 OAuth 凭据按所选后端存储；跨服务复用密钥、错误配置 env_http_headers 与 bearer_token_env_var 可能导致令牌泄露，配置后用 codex mcp get <名称> --json 复核字段是否指向正确环境变量。
• 第三方 Docker 镜像、打包脚本与安装器不属于官方分发渠道；本文未提供官方 Compose 文件，遇到声称 “Codex 官方镜像” 的第三方产物应核验签名、发布者与更新记录后再决定是否使用。

11.6 生成内容、代码版权与免责声明

• Agent 生成或修改的代码、注释、提交信息与文档建议需要人工复核：可能存在实现错误、安全漏洞、许可证冲突或引用不当；合入主干前应走项目自身的代码审阅、测试与 CI 流程。
• 模型训练数据与输出的版权归属因司法辖区与后端服务条款而异；CLI 不保证生成内容可注册版权、不保证原创性，也不替代法务审查。
• 安全漏洞应按 SECURITY.md 指向的 Bugcrowd 项目负责任披露，不要在公开 Issue 中上传账号凭据、模型 Token、未公开代码或敏感配置。

项目按现状（AS-IS）提供，官方不保证在特定操作系统、终端、模型组合与网络环境下持续可用，不保证命令执行结果正确、合规或无侵权风险；使用者自行承担代码改动质量、模型服务条款、数据外发、内容版权与业务损失风险。