无废话！源自官网的 Codex 命令速查手册！
前言
前几天写了个 Claude Code 的文章，反馈不错，这里写一篇 Codex 的命令手册，方便速查命令，从而高效使用 Codex，建议收藏。
另外推荐中转koalaapi稳定也很便宜。
image.png
基于 OpenAI Codex CLI v0.130.0，完整命令参考。本文纯命令速查，无废话。
> 命令总览：19 个 CLI 主命令 · 80+ 条用法条目 · 37 个 TUI 斜杠命令 · 10 个键盘快捷键 · 16 个 exec 专属 flags
> 参考资料：OpenAI 官方文档（CLI Reference，Slash Commands，Features）及 GitHub 仓库
> 成熟度标签：🟢 Stable（稳定）/ 🟡 Experimental（实验性）
一、安装
系统要求
macOS 12+、Ubuntu 20.04+、Windows 11 (WSL2)、Git 2.23+、最低 4GB 内存。
安装方式
# npm 全局安装
npm install -g @openai/codex
# Homebrew 安装（macOS）
brew install --cask codex
# 直接下载二进制（GitHub Release）
# macOS ARM: codex-aarch64-apple-darwin.tar.gz
# macOS x86: codex-x86_64-apple-darwin.tar.gz
# Linux x86: codex-x86_64-unknown-linux-musl.tar.gz
# Linux ARM: codex-aarch64-unknown-linux-musl.tar.gz
# DotSlash（仓库根目录的版本固定可执行文件）
# 从源码编译
git clone https://github.com/openai/codex.git && cd codex/codex-rs && cargo build
# 桌面应用
codex app
二、认证命令
| 命令 | 作用 | 使用场景 |
|---|
codex login | 浏览器 OAuth 登录 ChatGPT 账号 | 首次使用，有 Plus/Pro/Team/Business/Edu/Enterprise 订阅 |
codex login --device-auth | 设备码流程登录（无浏览器环境） | SSH 远程服务器、容器内 |
codex login --with-api-key | 从 stdin 读取 API Key 登录 | CI/CD、自动化脚本 |
codex login status | 查看当前认证状态 | 检查是否已登录 |
codex logout | 清除已保存的认证凭据 | 切换账号、退出登录 |
# 示例
codex login # 浏览器登录
printenv OPENAI_API_KEY | codex login --with-api-key # API Key 登录
codex login status # 检查登录状态
三、核心命令
3.1 交互式 TUI 🟢
| 命令 | 作用 | 使用场景 |
|---|
codex | 启动交互式终端 UI | 日常开发，人机协作编码 |
codex "你的提示" | 带初始提示启动 TUI | 直接指定任务，省去输入步骤 |
codex -i image.png "分析这张图" | 附带图片启动 | 分析截图、UI 设计稿、架构图 |
3.2 非交互执行（CI/脚本用）🟢
| 命令 | 作用 | 使用场景 |
|---|
codex exec "任务" | 非交互模式执行任务，输出到 stdout（别名 codex e） | CI/CD 流水线、批量自动化 |
codex exec --json "任务" | 输出 JSONL 格式事件流（别名 --experimental-json） | 程序化解析执行结果 |
codex exec -o result.txt "任务" | 将最终回复写入文件 | 下游脚本消费执行结果 |
codex exec --output-schema schema.json "任务" | 按 JSON Schema 校验输出 | 需要结构化输出的场景 |
| `echo "任务" \ | codex exec -` | 从 stdin 管道读取任务 | 与其他命令管道组合 |
codex exec resume 子命令
| 命令 | 作用 | 使用场景 |
|---|
codex exec resume | 交互选择历史执行会话恢复 | 续跑之前的执行 |
codex exec resume --last | 恢复最近一次执行 | CI 续跑 |
codex exec resume --all | 跨目录恢复执行会话 | 查找所有历史执行 |
codex exec resume --last --all | 跨目录恢复最近执行 | 在不同目录下恢复 |
codex exec resume <SESSION_ID> | 恢复指定 ID 的执行 | 精确恢复 |
codex exec resume --last "继续" | 恢复并附带新指令 | 在上次基础上追加任务 |
codex exec resume -i img.png --last "看这个" | 恢复并附加图片 | 带新截图继续 |
3.3 会话管理 🟢
| 命令 | 作用 | 使用场景 |
|---|
codex resume | 恢复历史会话（交互选择） | 继续之前中断的对话 |
codex resume --last | 恢复最近一次会话 | 快速回到上次对话 |
codex resume --all | 列出所有目录的会话 | 查找历史会话 |
codex resume --last --all | 跨目录恢复最近会话 | 在不同目录下恢复 |
codex resume <SESSION_ID> | 恢复指定 ID 的会话 | 精确恢复某个会话 |
codex fork | 分叉历史会话为新线程 | 基于之前对话另起一个方向探索 |
codex fork --last | 分叉最近一次会话 | 快速分叉 |
codex fork --all | 显示所有目录的会话 | 查找会话 |
codex fork <SESSION_ID> | 分叉指定会话 | 精确分叉 |
3.4 Cloud 任务 🟡
| 命令 | 作用 | 使用场景 |
|---|
codex cloud | 浏览/执行 Cloud 任务（别名 codex cloud-tasks） | 管理 Codex Cloud 远程任务 |
codex cloud exec --env <ENV_ID> "任务" | 提交 Cloud 任务 | 在云端环境执行任务 |
codex cloud exec --env <ENV_ID> --attempts 3 "任务" | 提交任务并指定重试次数（1-4） | 提高云任务成功率 |
codex cloud list | 列出最近 Cloud 任务 | 查看任务状态 |
codex cloud list --json | JSON 格式列出任务 | 脚本化查询 |
codex cloud list --env <ENV_ID> | 按环境筛选任务 | 查看特定环境任务 |
codex cloud list --limit 20 | 限制返回数量（1-20） | 控制输出条数 |
codex cloud list --cursor <CURSOR> | 分页游标 | 翻页查询 |
codex apply <TASK_ID> | 将 Cloud 任务 diff 应用到本地（别名 codex a） | 拉取云端生成的代码改动 |
3.5 桌面应用 🟢
| 命令 | 作用 | 使用场景 |
|---|
codex app | 启动 Codex 桌面应用 | 偏好 GUI 体验 |
codex app /path/to/project | 打开指定工作区的桌面应用 | 直接打开项目目录 |
codex app --download-url <URL> | 覆盖安装包下载地址 | 内网/镜像安装 |
四、全局 Flags
4.1 模型与配置
| Flag | 类型 | 作用 | 使用场景 |
|---|
-m, --model <model> | string | 指定模型 | codex -m gpt-5.5，切换模型 |
-p, --profile <name> | string | 加载配置 profile | 多环境/多项目配置切换 |
-c, --config key=value | key=value | 覆盖配置项（可重复） | 临时覆盖 ~/.codex/config.toml |
--oss | bool | 使用本地 Ollama 模型（等同 -c model_provider="oss"） | 无网络、私有部署、成本控制 |
--enable <feature> | string | 启用 feature flag（等同 -c features.<name>=true） | 开启实验性功能 |
--disable <feature> | string | 禁用 feature flag（等同 -c features.<name>=false） | 关闭某功能 |
--no-alt-screen | bool | 禁用 TUI 备用屏幕 | 终端兼容性问题 |
# 示例
codex -m gpt-5.5 "重构这个模块" # 指定模型
codex -p work "修复bug" # 使用 work profile
codex -c model_provider="oss" "写个脚本" # 临时用 Ollama
4.2 审批与沙箱
| Flag | 类型 | 作用 | 使用场景 |
|---|
-a, --ask-for-approval <mode> | untrusted / on-request / never | 控制命令审批策略 | 见下表 |
-s, --sandbox <policy> | read-only / workspace-write / danger-full-access | 沙箱安全策略 | 见下表 |
--yolo | bool | 跳过所有审批和沙箱（等同 --dangerously-bypass-approvals-and-sandbox） | 仅在隔离环境中使用 |
--add-dir <path> | path | 额外授权目录写权限（可重复） | 需要操作工作区外的目录 |
审批模式：
| 模式 | 行为 | 场景 |
|---|
untrusted | 每条命令都要审批 | 不可信输入、敏感项目 |
on-request | 仅在需要时请求审批（默认推荐） | 日常开发 |
never | 全自动，不暂停 | CI/CD、已信任的环境 |
> ⚠️ on-failure 模式已废弃，请使用 on-request 或 never。
沙箱策略：
| 策略 | 行为 | 场景 |
|---|
read-only | 只读，不能修改文件 | 代码审查、分析 |
workspace-write | 可写工作区，不能写外部 | 日常开发（推荐） |
danger-full-access | 无限制 | 需要 sudo、写系统目录 |
# 推荐组合：日常开发
codex -s workspace-write -a on-request "重构登录模块"
# CI 自动化
codex exec -s workspace-write -a never "运行测试并修复失败用例"
# 只读分析
codex -s read-only "分析这个项目的架构"
4.3 输入与搜索
| Flag | 类型 | 作用 | 使用场景 |
|---|
-i, --image <path> | path（逗号分隔或重复指定） | 附加图片 | 分析截图、设计稿 |
--search | bool | 启用实时网络搜索（live 模式） | 需要查最新文档/API |
PROMPT | string | 直接传提示文本 | codex "写个爬虫" |
-C, --cd <path> | path | 指定工作目录 | 不想 cd 到目标目录 |
> 搜索模式：默认 cached（OpenAI 维护索引），--search 切换为 live 实时搜索，配置中 web_search = "disabled" 可禁用。
4.4 远程连接
| Flag | 类型 | 作用 | 使用场景 |
|---|
--remote ws://host:port | URL | 连接远程 app-server | 本地 TUI 操作远程服务 |
--remote wss://host:port | URL | TLS 加密远程连接 | 安全要求高的远程连接 |
--remote-auth-token-env <ENV> | ENV_VAR | 远程认证 Token 环境变量 | 带鉴权的远程连接 |
> --remote 仅对 codex、codex resume、codex fork 有效。Token 仅通过 wss:// 或 localhost ws:// 发送。
# 本地启动 server
codex app-server --listen ws://0.0.0.0:8080
# 另一台机器连接
codex --remote ws://192.168.1.100:8080
五、辅助命令
5.1 功能管理 🟢
| 命令 | 作用 | 使用场景 |
|---|
codex features list | 列出所有 feature flags 及成熟度、生效状态 | 查看可用实验功能 |
codex features enable <feature> | 持久启用 feature flag | 开启某功能 |
codex features disable <feature> | 持久禁用 feature flag | 关闭某功能 |
> 支持 --profile 按配置环境切换。
5.2 MCP 服务器管理 🟡
| 命令 | 作用 | 使用场景 |
|---|
codex mcp list | 列出已配置的 MCP 服务器 | 查看当前 MCP 配置 |
codex mcp list --json | JSON 格式列出 | 脚本化查询 |
codex mcp add <name> -- <command...> | 添加 stdio MCP 服务器 | 集成本地工具 |
codex mcp add <name> --env KEY=VALUE -- <cmd> | 带环境变量添加 stdio MCP | 需要传入密钥等环境变量 |
codex mcp add <name> --url <url> | 添加 Streamable HTTP MCP 服务器 | 集成远程 API |
codex mcp add <name> --url <url> --bearer-token-env-var <ENV> | 带 Token 认证的 HTTP MCP | 需要鉴权的远程 MCP |
codex mcp get <name> | 查看指定 MCP 服务器配置 | 排查 MCP 问题 |
codex mcp get <name> --json | JSON 格式查看配置 | 脚本化排查 |
codex mcp remove <name> | 删除 MCP 服务器 | 清理不再需要的 MCP |
codex mcp login <name> | OAuth 登录 MCP 服务器 | 需要认证的 MCP |
codex mcp login <name> --scopes scope1,scope2 | 指定 OAuth scopes 登录 | 控制授权范围 |
codex mcp logout <name> | 退出 MCP 服务器认证 | 切换 MCP 认证 |
codex mcp-server | 将 Codex 自身作为 MCP 服务器运行（stdio） | 让其他 Agent 调用 Codex |
# 示例：添加本地 MCP
codex mcp add my-tool -- npx @my/mcp-server
# 示例：带环境变量
codex mcp add db-tool --env DB_URL=postgres://... -- npx @my/db-mcp
# 示例：添加远程 MCP
codex mcp add remote-api --url https://mcp.example.com/sse
# 示例：带认证的远程 MCP
codex mcp add secure-api --url https://mcp.example.com/sse --bearer-token-env-var API_TOKEN
5.3 插件市场 🟡
| 命令 | 作用 | 使用场景 |
|---|
codex plugin marketplace add <source> | 添加插件市场源（GitHub 简写/Git URL/SSH URL/本地目录） | 安装社区插件 |
codex plugin marketplace add <source> --ref main | 指定分支/标签 | 安装特定版本 |
codex plugin marketplace add <source> --sparse path/to/dir | 稀疏检出指定路径 | 只安装部分插件 |
codex plugin marketplace upgrade [name] | 更新指定或所有插件市场 | 获取最新插件 |
codex plugin marketplace remove <name> | 移除插件市场 | 清理 |
5.4 Shell 补全 🟢
| 命令 | 作用 | 使用场景 |
|---|
codex completion bash | 生成 Bash 补全脚本 | Bash 用户 |
codex completion zsh | 生成 Zsh 补全脚本 | Zsh 用户 |
codex completion fish | 生成 Fish 补全脚本 | Fish 用户 |
codex completion powershell | 生成 PowerShell 补全脚本 | Windows 用户 |
codex completion elvish | 生成 Elvish 补全脚本 | Elvish 用户 |
# Zsh 补全安装
codex completion zsh > "${fpath[1]}/_codex"
5.5 其他
| 命令 | 作用 | 使用场景 |
|---|
codex update 🟢 | 检查并更新 Codex CLI | 版本升级 |
codex sandbox -- <command> 🟡 | 在沙箱中执行命令 | 调试沙箱策略 |
codex debug models 🟡 | 打印可用模型列表 | 查看支持的模型 |
codex debug models --bundled 🟡 | 只显示内置模型目录（跳过刷新） | 离线查看 |
codex debug app-server send-message-v2 <msg> 🟡 | 向 V2 测试客户端发送消息 | 调试 app-server |
codex execpolicy check --rules <file> -- <cmd> 🟡 | 检查命令是否会被策略允许/阻止 | 调试执行策略 |
codex execpolicy check --rules <file> --pretty -- <cmd> 🟡 | 美化输出 JSON 结果 | 可读性更好的调试 |
codex sandbox 平台特定 flags 🟡
| Flag | 平台 | 作用 |
|---|
--permissions-profile <NAME> | 全平台 | 使用命名权限配置 |
--include-managed-config | 全平台 | 包含托管配置要求 |
--cd <DIR> | 全平台 | 设置工作目录（需配合 --permissions-profile） |
--allow-unix-socket <path> | macOS | 允许 Unix Socket 访问（可重复） |
--log-denials | macOS | 通过 log stream 捕获沙箱拒绝日志 |
六、App Server 命令 🟡
| 命令 | 作用 | 使用场景 |
|---|
codex app-server --listen stdio:// | JSONL-over-stdio 模式启动 | 程序化调用 |
codex app-server --listen ws://IP:PORT | WebSocket 模式启动 | 远程连接、多人协作 |
codex app-server --ws-auth capability-token --ws-token-file <path> | 共享 Token 认证 | 简单鉴权 |
codex app-server --ws-auth signed-bearer-token --ws-shared-secret-file <path> | JWT 签名认证 | 安全鉴权 |
codex app-server --ws-audience <aud> | 指定期望的 JWT aud 声明 | JWT 校验 |
codex app-server --ws-issuer <iss> | 指定期望的 JWT iss 声明 | JWT 校验 |
codex app-server --ws-max-clock-skew-seconds <N> | JWT 时钟偏差容忍秒数 | 时间不同步的服务器 |
codex app-server --experimental | 在生成 schema 中包含门控字段 | 实验性功能 |
七、codex exec 完整 Flags
| Flag | 作用 |
|---|
-C, --cd <path> | 设置工作目录 |
-m, --model <model> | 覆盖模型 |
-s, --sandbox <policy> | 沙箱策略 |
-a, --ask-for-approval <mode> | 审批模式 |
-i, --image <path> | 附加图片（逗号分隔或重复指定） |
-c, --config key=value | 覆盖配置（可重复） |
-p, --profile <name> | 选择 profile |
-o, --output-last-message <path> | 输出最终消息到文件 |
--json / --experimental-json | JSONL 格式输出 |
--output-schema <path> | 输出 JSON Schema 校验 |
--ephemeral | 不持久化会话文件 |
--oss | 使用本地 Ollama |
--yolo | 跳过审批和沙箱（危险） |
--full-auto | ⚠️ 已废弃，请用 -s workspace-write 替代 |
--color always/never/auto | 控制颜色输出 |
--skip-git-repo-check | 允许非 Git 目录执行 |
--ignore-rules | 不加载 .rules 文件 |
--ignore-user-config | 不加载用户配置 |
八、TUI 内部斜杠命令
> 在交互式 codex 会话中使用的命令，官方文档约 34 个，含未列出命令约 37 个。
8.1 会话管理
| 命令 | 作用 |
|---|
/clear | 清屏并开始新对话 |
/compact | 压缩对话释放 token |
/fork | 分叉当前对话为新线程 |
/side | 开启临时侧边对话 |
/resume | 从历史记录恢复对话 |
/new | 同会话开始新对话 |
/exit / /quit | 退出 CLI |
8.2 工作模式
| 命令 | 作用 |
|---|
/permissions | 设置审批模式：Auto / Read Only / Full Access |
/plan [prompt] | 切换到计划模式 |
| `/fast on\ | off\ | status` | 切换 Fast 模式（支持的模型） |
/model | 切换模型和推理强度 |
| `/personality friendly\ | pragmatic\ | none` | 选择沟通风格 |
/yolo | 切换完全访问模式（非官方文档命令） |
8.3 审查与分析
| 命令 | 作用 |
|---|
/review | 审查工作树（基础分支 / 未提交 / 指定 commit / 自定义指令） |
/diff | 显示 git diff（含未跟踪文件） |
/status | 显示会话配置、模型、token 用量 |
8.4 文件与上下文
| 命令 | 作用 |
|---|
/mention | 附加文件/文件夹到对话 |
/copy | 复制最近完成的输出到剪贴板（等同 Ctrl+O） |
8.5 Agent 与多线程
| 命令 | 作用 |
|---|
/agent | 切换活跃 agent/子 agent 线程 |
8.6 后台进程
| 命令 | 作用 |
|---|
/ps | 显示后台终端和最近输出 |
/stop / /clean | 停止所有后台终端 |
8.7 应用、插件与 Skill
| 命令 | 作用 |
|---|
/apps | 浏览并插入应用连接器（$app-slug） |
/plugins | 浏览已安装/可发现的插件 |
/skills | 浏览并选择可用的 Skill（代码审查、文档生成等预制能力） |
> Skill 也可在输入框中直接输入任务描述，Codex 会自动匹配合适的 Skill。
8.8 MCP
| 命令 | 作用 |
|---|
/mcp | 列出 MCP 工具，加 verbose 显示服务器详情 |
8.9 目标跟踪（实验性）
| 命令 | 作用 |
|---|
/goal <text> | 设置/查看实验性目标（需 features.goals） |
/goal pause | 暂停目标跟踪 |
/goal resume | 恢复目标跟踪 |
/goal clear | 清除当前目标 |
8.10 配置与诊断
| 命令 | 作用 |
|---|
/init | 生成 AGENTS.md 脚手架 |
/debug-config | 打印配置层和策略诊断 |
/statusline | 交互式配置 TUI 底部状态栏字段 |
/title | 配置终端窗口/标签页标题字段 |
/keymap | 重映射 TUI 键盘快捷键 |
/theme | 主题选择器（自定义 .tmTheme 放在 $CODEX_HOME/themes/） |
/experimental | 切换实验性功能 |
/logout | 在 TUI 中登出 |
8.11 其他
| 命令 | 作用 |
|---|
/feedback | 发送日志/诊断信息给维护者 |
/sandbox-add-read-dir | 授予沙盒额外读权限（仅 Windows） |
> /approvals 是 /permissions 的旧别名，已从弹出菜单中隐藏。
九、TUI 键盘快捷键
| 快捷键 | 作用 |
|---|
Tab | 任务运行时队列 follow-up 输入 |
Enter（运行中） | 注入指令到当前轮 |
Esc Esc（空输入框） | 编辑上一条用户消息 |
Ctrl+C | 退出交互式会话 |
Ctrl+G | 打开外部编辑器（$VISUAL 或 $EDITOR） |
Ctrl+L | 清屏（保留对话，区别于 /clear） |
Ctrl+O | 复制最近完成的输出 |
Ctrl+R | 搜索提示历史 |
Up / Down | 浏览历史草稿 |
! <命令> | 在 TUI 中直接执行本地 shell 命令（如 !ls、!git status） |
十、配置文件
| 路径 | 作用 |
|---|
~/.codex/config.toml | 全局配置（模型、沙箱、MCP 等） |
~/.codex/rules/ | 执行策略规则文件目录 |
~/.codex/sessions/ | 会话持久化存储目录 |
~/.codex/themes/ | 自定义 TUI 主题（.tmTheme 文件） |
AGENTS.md | 项目级持久指令（放在项目根目录或任意父目录） |
> 路径前缀可通过 CODEX_HOME 环境变量覆盖，默认 ~/.codex。
# 配置示例 config.toml
[model]
name = "gpt-5.5"
[sandbox]
policy = "workspace-write"
[approval]
mode = "on-request"
# 其他可用配置项
# web_search = "live" # 搜索模式：cached / live / disabled
# review_model = "gpt-5.5" # /review 命令使用的模型
# log_dir = "/tmp/codex" # 日志目录覆盖
十一、环境变量
| 变量 | 作用 |
|---|
CODEX_HOME | 覆盖 Codex 主目录（默认 ~/.codex） |
OPENAI_API_KEY | API 密钥认证（ChatGPT 登录的替代方案） |
RUST_LOG | 日志级别（error / warn / info / debug / trace），codex exec 默认 error |
$VISUAL / $EDITOR | Ctrl+G 外部编辑器 |
> 日志默认路径：~/.codex/log/codex-tui.log，可通过 -c log_dir=... 覆盖。
十二、可用模型
| 模型 | 说明 |
|---|
gpt-5.5 | 最新前沿模型，官方推荐 |
gpt-5.4 | 通用模型 |
gpt-5.3-Codex-Spark | 研究预览，仅 ChatGPT Pro |
gpt-4.1 | 上代模型 |
gpt-4.1-mini | 轻量版 |
gpt-image-2 | 内置图片生成 |
> 可通过 codex debug models 查看完整可用列表。
十三、常用组合速查
| 场景 | 命令 |
|---|
| 日常开发（推荐） | codex -s workspace-write -a on-request |
| 全自动本地执行 | codex -s workspace-write -a never |
| 带任务的快速启动 | codex "帮我梳理这个仓库" |
| 指定项目目录启动 | codex -C ./my-project |
| 只读代码审查 | codex -s read-only "审查这个PR" |
| CI 自动修复测试 | codex exec -s workspace-write -a never --json "修复失败测试" |
| 执行并保存结果 | codex exec -o result.txt "总结这个仓库" |
| 带搜索的研究 | codex --search "调研 React Server Components 最佳实践" |
| 用本地模型 | codex --oss "写个排序算法" |
| 远程开发 | codex --remote ws://dev-server:8080 |
| 分析截图 | codex -i screenshot.png "这个页面有什么问题" |
| 恢复上次对话 | codex resume --last |
| 跨目录恢复 | codex resume --last --all |
| 分叉探索 | codex fork --last |
| 查看可用模型 | codex debug models |
| 更新版本 | codex update |
| CI 续跑上次执行 | codex exec resume --last |
| 提交云任务 | codex cloud exec --env my-env "重构模块" |
| 拉取云任务结果 | codex apply <TASK_ID> |
| 初始化项目指令 | 在 TUI 中输入 /init |
| 释放 token | 在 TUI 中输入 /compact |
| 切换计划模式 | 在 TUI 中输入 /plan |
| 浏览可用 Skill | 在 TUI 中输入 /skills |
| 管理子代理线程 | 在 TUI 中输入 /agent |
| 切换模型 | 在 TUI 中输入 /model |
| 切换快速模式 | 在 TUI 中输入 /fast on |
