Codex CLI 完整命令参考。涵盖 codex（交互式 TUI）和所有子命令：exec（无人值守批处理）、resume/fork（会话延续）、login（认证）、mcp（MCP 服务器管理）、cloud（云端任务）、sandbox（沙箱测试）等。每个命令的参数表均含类型、默认值和使用场景说明。

Codex CLI 命令行参考

阅读指南

本页列出 Codex CLI 所有命令和参数。CLI 的大多数默认值来自 ~/.codex/config.toml，命令行的 -c key=value 覆盖仅对当次运行生效，优先级高于配置文件。

---

全局参数

以下参数适用于 codex 主命令，并向所有子命令传递（除非子命令文档另有说明）。运行子命令时请把全局参数放在子命令名称之后，例如 codex exec --oss ...。

参数	类型	默认值	说明
PROMPT	string	—	可选的初始提示词。省略则以空状态启动 TUI
--image, -i	path[,path...]	—	附加一张或多张图片到初始提示词
--model, -m	string	—	覆盖配置文件里的模型（例如 gpt-5.4）
--oss	boolean	false	使用本地开源模型（需要 Ollama 运行中），等效于 -c model_provider="oss"
--profile, -p	string	—	加载 ~/.codex/config.toml 里指定的配置 Profile
--sandbox, -s	read-only | workspace-write | danger-full-access	—	沙箱策略：只读 / 工作区可写 / 完全访问
--ask-for-approval, -a	untrusted | on-request | never	—	控制何时暂停等待人工审批。on-failure 已废弃，推荐用 on-request（交互式）或 never（自动化）
--full-auto	boolean	false	低摩擦本地工作快捷键：自动设 --ask-for-approval on-request 和 --sandbox workspace-write
--dangerously-bypass-approvals-and-sandbox, --yolo	boolean	false	跳过所有审批和沙箱。仅在外部已隔离的环境里使用
--cd, -C	path	—	在 Agent 开始处理前设置工作目录
--search	boolean	false	开启实时 Web 搜索（默认是缓存模式）
--add-dir	path	—	给额外目录授予写权限（可重复使用）
--no-alt-screen	boolean	false	禁用 TUI 的备用屏幕模式
--remote	ws://host:port | wss://host:port	—	将 TUI 连接到远端 app-server WebSocket 端点
--remote-auth-token-env	ENV_VAR	—	从指定环境变量读取 bearer token，用于 --remote 连接认证
--enable	feature	—	强制启用某个 feature flag（可重复）
--disable	feature	—	强制禁用某个 feature flag（可重复）
--config, -c	key=value	—	覆盖单个配置值，JSON 可解析时自动解析，否则作为字符串

---

命令总览

命令	成熟度	说明
codex	stable	启动交互式终端 UI（TUI），接受全局参数和可选提示词
codex app-server	experimental	启动 Codex app server，用于本地开发调试
codex app	stable	在 macOS 上启动 Codex 桌面 App，可选择打开指定目录
codex exec	stable	非交互式运行。别名 codex e。结果输出到 stdout 或 JSONL
codex resume	stable	继续上一次交互式会话（按 ID 或最近一次）
codex fork	stable	把当前会话分叉为新线程，原始记录保留
codex apply	stable	把 Codex Cloud 任务产生的 diff 应用到本地工作区
codex cloud	experimental	从终端管理 Codex Cloud 任务，无需打开 TUI
codex completion	stable	生成 Bash/Zsh/Fish/PowerShell 的 shell 补全脚本
codex features	stable	查看和持久化开关 feature flags
codex login	stable	通过 ChatGPT OAuth、设备验证或 API Key 认证
codex logout	stable	清除已保存的认证凭据
codex mcp	experimental	管理 MCP 服务器（列举、添加、删除、认证）
codex mcp-server	experimental	以 MCP server 模式运行 Codex，供其他工具调用
codex sandbox	experimental	在 Codex 同款沙箱里运行任意命令
codex execpolicy	experimental	检查 execpolicy 规则文件，预判命令是否会被允许/拦截
codex debug app-server send-message-v2	experimental	通过内置测试客户端向 app-server 发送单条 V2 消息调试

---

命令详解

codex（交互式 TUI）

不带子命令直接运行 codex 启动交互式终端 UI。Web 搜索默认是缓存模式，用 --search 切换到实时搜索；用 --full-auto 让 Codex 在大多数情况下无需审批就能运行命令。

用 --remote ws://host:port 或 --remote wss://host:port 可以把 TUI 连接到由 codex app-server --listen ws://IP:PORT 启动的远端 app server。需要 bearer token 认证时加上 --remote-auth-token-env <ENV_VAR>。

---

codex exec — 非交互式批处理

codex exec "修复所有 TypeScript 类型错误"
codex e "生成单元测试" --model gpt-5.4 --json

参数	类型	默认值	说明
PROMPT	string | -（读取 stdin）	—	任务指令，用 - 从 stdin 读取
--image, -i	path[,path...]	—	附加图片到第一条消息
--model, -m	string	—	覆盖本次运行的模型
--sandbox, -s	read-only / workspace-write / danger-full-access	—	沙箱策略
--full-auto	boolean	false	低摩擦自动化预设
--dangerously-bypass-approvals-and-sandbox, --yolo	boolean	false	跳过审批和沙箱（危险）
--cd, -C	path	—	执行前设置工作目录
--skip-git-repo-check	boolean	false	允许在非 Git 目录运行
--ephemeral	boolean	false	不持久化 session 文件
--output-schema	path	—	JSON Schema 文件，Codex 会验证最终输出是否符合
--color	always / never / auto	auto	ANSI 颜色输出控制
--json	boolean	false	输出换行分隔的 JSON 事件流（JSONL）
--output-last-message, -o	path	—	把助手最后一条消息写入文件，方便脚本集成

codex exec resume [SESSION_ID]：继续一个非交互式 session，--last 取最近的，--all 搜索所有目录。

CI 推荐组合：--json + --output-last-message 同时使用，既有机器可读的事件流，又有最终摘要文本。

---

codex resume — 继续交互式会话

继续上一次交互式 session，按 ID 或最近一次。接受与 codex 相同的全局参数（包括模型和沙箱覆盖）。

codex resume                    # 打开 session 选择器
codex resume --last             # 继续最近一次（当前目录）
codex resume --last --all       # 继续最近一次（所有目录）

---

codex fork — 分叉会话

把上一次交互式 session 分叉为新线程，原始记录保留不变，适合在不影响主线的情况下探索不同方案。

codex fork          # 打开 session 选择器
codex fork --last   # 分叉最近一次

---

codex login — 认证

参数	说明
--with-api-key	从 stdin 读取 API Key（例如 echo $OPENAI_API_KEY | codex login --with-api-key）
--device-auth	使用 OAuth 设备码流程，不需要浏览器
codex login status	检查是否已登录，退出码 0 表示凭据有效（适合 CI 检测）

---

codex logout — 清除凭据

清除 API Key 和 ChatGPT OAuth 两种认证方式保存的凭据，无参数。

---

codex mcp — MCP 服务器管理

子命令	说明
codex mcp list [--json]	列出已配置的 MCP 服务器
codex mcp get <name> [--json]	查看指定服务器配置
codex mcp add <name> -- <command...>	注册 stdio 类型 MCP 服务器
codex mcp add <name> --url <url>	注册 HTTP streamable 类型 MCP 服务器
codex mcp remove <name>	删除 MCP 服务器配置
codex mcp login <name>	为 HTTP 服务器发起 OAuth 登录
codex mcp logout <name>	清除 HTTP 服务器的 OAuth 凭据

add 命令支持 --env KEY=VALUE（为 stdio 服务器设置环境变量）和 --bearer-token-env-var（为 HTTP 服务器设置 bearer token）。

---

codex cloud — Cloud 任务

codex cloud exec "修复所有 lint 错误" --env ENV_ID
codex cloud list --json

参数	说明
codex cloud exec QUERY --env ENV_ID	提交 Cloud 任务，--attempts 1-4 控制并行尝试次数（最优结果）
codex cloud list	列出最近 Cloud 任务，支持 --env、--limit、--cursor、--json

---

codex apply — 应用 Cloud diff

codex apply TASK_ID

把指定 Cloud 任务产生的 diff 应用到本地工作区。git apply 失败（如冲突）时以非零退出码退出。

---

codex features — Feature Flags 管理

codex features list              # 查看所有 feature flag 状态
codex features enable subagents  # 持久启用
codex features disable subagents # 持久禁用

---

codex sandbox — 沙箱测试

在与 Codex 相同的沙箱环境里运行任意命令，用于验证沙箱策略配置：

• macOS Seatbelt：codex sandbox -- <command>
• Linux Landlock：codex sandbox -- <command>

加 --full-auto 给工作区和 /tmp 授予写权限。

---

安全建议

• --full-auto 适合无人值守的本地工作，但不要同时加 --yolo（--dangerously-bypass-approvals-and-sandbox），除非你已在独立的沙箱 VM 里。
• 需要给 Codex 额外写权限时，优先用 --add-dir 而不是强制开 danger-full-access 沙箱。
• CI 场景：--json + --output-last-message 组合使用，兼顾机器可读事件流和最终自然语言摘要。

---

常见问题

Q: codex exec 和直接运行 codex 的主要区别是什么？

A: codex（无子命令）启动的是交互式 TUI，需要人在场操作；codex exec 是非交互式批处理模式，任务完成后自动退出，适合 CI 脚本和自动化工作流。

Q: 怎么确认登录状态？

A: 运行 codex login status，退出码为 0 表示已登录，非 0 表示未登录或凭据失效，适合在 CI 启动前做前置检查。

Q: --profile 和 -c key=value 可以同时用吗？

A: 可以。--profile 加载整个 Profile 作为基础配置，-c key=value 在此基础上覆盖单个值，只对本次运行生效，不修改配置文件。