Codex 进阶用法

本页适合已经完成 Codex 基础安装和 UseGoodAI 接入的用户。首次配置 API Key、安装 CLI、Windows / WSL / macOS / Linux 路径排查，请先看 Codex。

本页主要讲系统终端里的外部 codex ... 命令、高级配置和多会话工作流。已经进入 Codex 交互界面后，输入框里的 /goal、/fork、/review、/model 等内部命令，请看 Codex CLI 内部命令。

以下内容基于当前本机可验证的 codex-cli 0.142.4 写作。不同版本的 Codex CLI 可能会增减命令、配置项和本地目录结构；遇到差异时，优先以本机 codex --help、Codex 输入框里的 / 菜单、codex doctor 和 UseGoodAI 后台生成配置为准。

先确认当前版本和命令

codex --version
codex --help
codex features list

当前可验证的主命令包括：

命令	用途
codex	进入交互式 Codex
codex exec	非交互执行一次任务
codex review	非交互代码审查
codex mcp	管理 MCP server
codex plugin	管理 Codex 插件
codex doctor	诊断安装、配置、认证和运行环境
codex debug	查看调试信息，例如模型目录和模型可见输入
codex apply	应用 Codex 任务产生的 diff
codex resume	继续历史会话
codex fork	从历史会话分叉新会话
codex features	查看、启用或禁用功能开关

这些是外部 CLI 命令，不等于进入 Codex 之后输入的内部 slash command。例如 /goal 是交互界面里的内部命令，不是 codex goal；/fork 是当前会话里的分叉入口，codex fork --last 是从系统终端启动分叉会话。

配置分层与模型切换

Codex 的配置可以来自基础配置、profile 和命令行参数。高级用户最常用的是“长期默认值放配置文件，临时选择放命令行”。

层级	适合放什么	示例
config.toml	默认模型、provider、sandbox、MCP 等长期配置	默认使用 UseGoodAI
profile	不同任务的模型、权限、工具组合	fast、review、deep
命令行参数	单次任务临时覆盖	-m、-p、-c

常用切换方式：

codex -m gpt-5.5
codex -p review
codex -c model='"gpt-5.5"'
codex exec -m gpt-5.5 "检查当前改动是否有明显 bug"

如果使用 UseGoodAI，优先复制后台生成的 Codex 配置，不要在高级配置里重新推导 provider 字段。UseGoodAI API 地址通常是 https://api.usegoodai.com；Codex 接入优先走 Responses。需要手动排障时，检查后台生成配置和基础接入页，不要把 Base URL 改成 Responses 或 Chat Completions 的最终请求路径。

Codex Home 目录解释

Codex Home 是 Codex 保存用户级配置、认证、会话和运行记录的目录。常见位置如下：

环境	常见 Codex Home
Windows 原生 PowerShell / CMD	%userprofile%\.codex
Windows WSL	~/.codex
macOS	~/.codex
Linux	~/.codex

常见文件和目录：

项目	作用
config.toml	用户级默认配置
<profile>.config.toml	profile 叠加配置，例如 review.config.toml
auth.json	API Key 或认证信息
sessions/	历史会话记录，供 resume、fork 等功能使用
logs/ 或类似目录	日志、诊断或运行记录

不同版本的本地目录结构可能略有差异，不建议写脚本依赖某个固定内部目录。需要排查时，优先运行：

codex doctor --summary
codex doctor --json

如果想为不同项目、不同客户或不同账号隔离配置，可以显式指定不同的 CODEX_HOME：

CODEX_HOME="$HOME/.codex-usegoodai" codex
CODEX_HOME="$HOME/.codex-review" codex -p review

工作区 / 上下文控制

Codex 对代码仓库的理解高度依赖工作目录、可读写目录和仓库内指导文件。高级用法的核心不是给更长提示词，而是控制它能看到什么、能改什么。

控制点	命令或文件	作用
工作根目录	-C <DIR>	指定 Codex 在哪个目录工作
额外可写目录	--add-dir <DIR>	允许 Codex 访问主工作区之外的目录
仓库规则	AGENTS.md	写入项目约定、验证命令、禁止事项
临时约束	启动 prompt	给当前任务的目标、范围和验收标准
沙箱	-s read-only/workspace-write/danger-full-access	限制命令和文件系统权限

示例：

codex -C ~/work/app
codex -C ~/work/app --add-dir ~/work/shared
codex -s read-only "只阅读代码，解释支付流程，不要修改文件"
codex -s workspace-write "修复登录页表单校验，并运行相关测试"

建议把稳定规则写进仓库里的 AGENTS.md，把单次任务目标写在 prompt 里。不要把所有背景一次性塞进 prompt；上下文越混杂，Codex 越难判断优先级。

非交互任务

codex exec 适合一次性任务、脚本化检查、批量说明生成和 CI 前的本地辅助检查。

codex exec "阅读当前仓库，指出最可能影响启动的配置问题"
codex exec -C ~/work/app "运行测试并修复一个最小失败点"

也可以从标准输入传入复杂说明：

cat task.md | codex exec -

需要给后续脚本读取最后回复时，可以写入文件：

codex exec -o codex-result.md "总结当前未提交改动"

需要结构化事件流时，可以使用 JSONL 输出：

codex exec --json "检查当前仓库的测试入口"

非交互任务更适合边界清楚的工作。对于大范围重构、需求不明确或需要多轮判断的任务，先用交互式 codex 梳理方案，再拆成小任务执行。

会话管理

Codex 会保存历史会话，便于继续、分叉或清理。

命令	适合场景
codex resume	从列表选择历史会话继续
codex resume --last	继续最近一次会话
codex fork	从某个历史会话分叉新方向
codex fork --last	从最近一次会话分叉
codex archive <SESSION>	归档指定历史会话
codex delete <SESSION>	删除指定历史会话
codex unarchive <SESSION>	恢复指定归档会话

典型工作流：

codex resume --last
codex fork --last "不要继续实现，改为只做代码审查"

resume 适合延续原目标，fork 适合保留原上下文但尝试另一个方向。例如一个会话已经分析了支付模块，可以 fork 出“修 bug”和“写测试计划”两条线。

resume 和 fork 不带参数时会打开选择列表；archive、delete、unarchive 需要明确传入 session id 或 session name。删除会话前先确认目标 session，避免误删。

诊断排错

先用 doctor 判断安装、配置、认证和运行环境：

codex doctor
codex doctor --summary
codex doctor --json

doctor --json 会输出经过脱敏的机器可读报告，适合发给技术支持或保存到排障记录中。

常见排查路径：

现象	优先检查
401	auth.json 是否为 UseGoodAI API Key，Key 是否完整
403	Key 所属分组是否支持当前模型，额度或权限是否允许
后台没有记录	Codex 是否读取了正确的 Codex Home 和 provider 配置
模型不存在	model 是否和 UseGoodAI 后台分组支持的模型名一致
配置不生效	是否在错误环境配置，例如 Windows 原生和 WSL 混用
行为和预期不一致	是否被 profile、命令行 -c 或项目规则覆盖

需要看模型目录或模型可见输入时，可以使用：

codex debug models
codex debug models --bundled
codex debug prompt-input

debug prompt-input 可能包含当前任务上下文。分享给他人前应先检查是否有敏感信息。

MCP / 插件 / 联网搜索

Codex 支持通过 MCP 接入外部工具，也支持插件管理。当前 CLI 可验证命令：

codex mcp list
codex mcp add --help
codex mcp get --help
codex mcp login --help

codex plugin list
codex plugin marketplace list
codex plugin add --help

MCP 更适合连接明确的数据源或工具，例如内部文档、Issue 系统、数据库只读查询、设计稿系统。插件更适合打包一组可复用能力，例如技能、MCP 配置、hooks、脚本或本地工具。

联网搜索是单次运行级能力，可以通过 --search 打开：

codex --search "查找这个报错的最新官方说明，并给出修复建议"
codex exec --search "基于最新官方文档，检查当前配置是否过时"

联网搜索会增加外部信息摄入，也可能增加消耗。涉及账号、账单、私有仓库、客户资料时，优先使用受控 MCP 或本地文档，不要把敏感信息直接放进联网搜索 prompt。

安全与权限

Codex 能读写文件、运行命令，因此权限配置应按任务风险选择。

模式	适合场景
read-only	只读分析、解释代码、审查方案
workspace-write	修改当前项目文件，常规开发推荐
danger-full-access	需要完整系统访问的特殊任务

常用示例：

codex -s read-only "解释当前项目结构"
codex -s workspace-write "修复当前测试失败"

谨慎使用：

codex --dangerously-bypass-approvals-and-sandbox

这个选项会跳过确认并取消沙箱限制，只适合已经由外部容器、虚拟机或一次性环境隔离的场景。不要在保存真实密钥、生产配置或重要个人文件的机器上随手使用。

如果需要让 Codex 读取或修改主项目之外的目录，优先用 --add-dir 精确授权，不要直接扩大到整个用户目录。

并行工作 / 多 Codex 工作流

并行使用 Codex 的重点是隔离上下文和工作区，而不是寻找一个不存在的公开 subagent 命令。当前 CLI 虽然显示 multi_agent feature 为 stable，但主帮助没有公开 codex subagent 子命令。不要把内部环境里的 agent 编排能力当成所有 Codex 用户都能直接调用的公开命令。

可用的高级工作流：

方法	适合场景
多个终端	同时处理不同任务
不同工作目录	分离前端、后端、文档、测试
不同 CODEX_HOME	分离账号、配置、插件和会话
不同 profile	分离模型、权限、MCP 和任务偏好
fork / resume	从同一分析上下文拆出多个方向

示例：

CODEX_HOME="$HOME/.codex-docs" codex -C ~/work/docs -p writing
CODEX_HOME="$HOME/.codex-api" codex -C ~/work/api -p review

从同一会话拆任务：

codex fork --last "基于刚才的分析，只修复登录 bug"
codex fork --last "基于刚才的分析，只补测试计划，不改代码"

并发会增加模型调用、工具调用和搜索消耗，也会增加冲突概率。多个 Codex 同时修改同一个仓库时，建议先按目录或文件划分边界，并在每条线结束后统一检查 diff。

目标管理

目标管理的核心是让 Codex 始终知道“完成标准”，不只是知道“要做什么”。注意：/goal 是进入 Codex 交互界面后的内部命令，不是系统终端里的 codex goal 子命令。内部命令的详细用法看 Codex CLI 内部命令。

推荐做法：

场景	方法
交互式长任务	在 Codex 输入框里使用 /goal <目标>
单次任务	在 prompt 开头写清目标、范围和验收标准
仓库长期约定	写入 AGENTS.md
多阶段任务	先让 Codex 输出任务清单，再逐项执行
会话延续	用 resume 保留上下文
方向分叉	用 fork 复制上下文后改变目标

交互式任务可以先设置目标：

/goal 修复登录页提交后不显示错误提示的问题。范围只包括 src/pages/login 和相关测试。完成标准是相关测试通过，并说明改动和未验证项。

如果不用内部命令，也可以在普通 prompt 开头写清目标：

目标：修复登录页提交后不显示错误提示的问题。
范围：只允许修改 src/pages/login 和相关测试。
验收：相关测试通过；不要改 API 层；最后说明改动和未验证项。

对于需要多轮推进的任务，可以先让 Codex 建立清单：

先不要改代码。请阅读当前模块，列出最小任务清单，每项都写明完成标准和验证命令。

目标管理不需要复杂系统。能稳定复用的规则放进 AGENTS.md，临时目标可以用 /goal 或写进 prompt，历史上下文用 resume，分支探索用 fork。