教程2026年5月13日4,983 浏览约 13 分钟阅读

源自官网的Codex 命令速查手册！

OpenAI Codex CLI 命令速查手册，收录辅助命令、TUI 斜杠指令、键盘快捷键、exec 参数，附带源码解析与实战避坑教程，适合开发者快速查阅使用。

无废话！源自官网的 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`

标签OpenAI CodexCodex CLI命令手册TUI 斜杠命令AI 编码终端指令

Koala API · 一站式大模型 API 中转

把博客读到的，落地到你的下一个项目

国内直连 · 兼容 OpenAI SDK · GPT / Claude / Gemini 等主流模型聚合

立即注册查看接入教程