Logo
Esc
输入关键词开始搜索
Overview

Codex CLI 使用教程：从安装到完整命令行工作流

发布于 2026年5月11日 08:00
编辑于 2026年5月11日 15:28
20 分钟阅读
-
学习 bash 自动化

写在前面

这是一篇面向“已经安装好 Codex CLI，但还不熟悉命令行用法”的完整使用手册。本文按 Codex CLI 0.130.0 编写；写作时通过 codex --help、各子命令 --help、npm view @openai/codex version 以及 OpenAI 官方 Codex 文档交叉确认。

  • 如果你的版本不同，先运行 codex --version 和 codex --help 对照。
  • Codex CLI 更新较快，任何长期脚本都建议把关键命令写清楚版本假设。
  • 文中的危险命令会单独标注，不建议为了省一次确认就直接关闭沙箱和审批。

1. Codex CLI 的心智模型

Codex CLI 有三类主要用法。

  1. 交互式 TUI：直接运行 codex，在终端里和代理对话，让它读代码、改代码、跑命令、解释结果。
  2. 非交互式执行：运行 codex exec，把一次性任务交给 Codex，适合脚本、CI、批处理、生成报告。
  3. 管理与扩展：用 codex login、codex mcp、codex plugin、codex features、codex sandbox 等命令管理认证、工具、插件、功能开关和沙箱。

最常见的入口格式是：

Bash 
codex [OPTIONS] [PROMPT]
codex [OPTIONS] COMMAND [ARGS]

没有子命令时，codex 会进入交互式终端界面。带 exec 时，Codex 会执行一次任务并输出结果。

2. 安装后先跑这组命令

Bash 
codex --version
codex --help
codex login
codex login status
codex --cd /path/to/your/repo

含义如下。

  • codex --version：确认安装版本。
  • codex --help：查看当前版本实际支持的命令。写脚本前优先信它。
  • codex login：登录 Codex。通常会走浏览器或设备授权流程。
  • codex login status：检查当前是否已登录。
  • codex --cd /path/to/your/repo：让 Codex 从指定目录启动，避免在错误目录里读写文件。

如果你要用 API key 登录，当前 0.130.0 的帮助信息显示用 stdin 传入：

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

不要把 API key 直接写进 shell history、Notion、README 或截图里。

3. 最常用的工作流速查

3.1 在当前仓库里启动交互会话

Bash 
cd /path/to/repo
codex

适合探索代码、连续改 bug、让 Codex 边读边验证。

3.2 带初始任务启动

Bash 
codex "阅读这个仓库，告诉我启动前端和后端分别需要什么命令"

适合一进入会话就给 Codex 明确目标。

3.3 指定工作目录

Bash 
codex --cd /path/to/repo "检查测试失败原因"

适合你当前 shell 不在项目根目录，或者要从脚本里调用。

3.4 只读分析

Bash 
codex --sandbox read-only --ask-for-approval on-request "分析这次重构风险，不要改文件"

适合代码审查、架构分析、日志诊断。

3.5 允许改当前工作区

Bash 
codex --sandbox workspace-write --ask-for-approval on-request "修复登录页的表单校验 bug，并运行相关测试"

适合日常开发。Codex 可以写工作区文件，但涉及更敏感操作时仍会请求批准。

3.6 非交互执行一次任务

Bash 
codex exec "总结这个仓库的目录结构，并列出最值得先读的 5 个文件"

适合自动化、一次性报告、CI 任务。

3.7 管道输入给 Codex

Bash 
git diff --stat | codex exec "根据输入总结这次改动的范围和风险"

如果同时提供 prompt 和 stdin，prompt 是指令，stdin 是上下文。

3.8 输出最后一条消息到文件

Bash 
codex exec -o codex-summary.md "生成本仓库的维护说明"

适合让脚本后续消费最终结果。

3.9 代码审查

Bash 
codex review --uncommitted
codex review --base main
codex review --commit HEAD

适合在提交前或合并前找 bug、回归风险和缺失测试。

3.10 恢复最近会话

Bash 
codex resume --last

适合继续昨天没完成的任务。

3.11 分叉最近会话做另一种尝试

Bash 
codex fork --last "换一种实现方案，不要沿用刚才的改法"

适合保留原会话，同时开一个分支方向探索。

4. 全局选项详解

以下选项通常可放在 codex、codex exec、codex resume、codex fork 等命令前后。

4.1 -C, --cd DIR

设置 Codex 的工作根目录。

Bash 
codex --cd ~/projects/my-app "修复 failing tests"

什么时候用：

  • 当前 shell 不在项目目录。
  • 自动化脚本里要显式指定仓库。
  • 同一台机器上同时处理多个项目，避免误读误写。

4.2 -m, --model MODEL

指定本次会话使用的模型。

Bash 
codex -m gpt-5.5 "解释这个模块的设计"

什么时候用：

  • 想临时覆盖默认模型。
  • 某个任务需要更强推理，或你想用账户可用的特定模型。
  • 不想改全局配置，只想影响这一次。

可用模型随账号和版本变化，先看官方模型说明，或运行：

Bash 
codex debug models

4.3 -p, --profile CONFIG_PROFILE

选择 ~/.codex/config.toml 中定义的配置 profile。

Bash 
codex --profile work "检查后端服务"

适合区分工作、个人、本地模型、不同审批策略等场景。

4.4 -c, --config key=value

临时覆盖配置。支持点路径，值按 TOML 解析。

Bash 
codex -c model="gpt-5.5" "总结代码"
codex -c shell_environment_policy.inherit=all "检查环境变量相关问题"
codex -c 'sandbox_workspace_write.network_access=true' "运行需要联网的测试"

什么时候用：

  • 快速试一个配置，不想编辑 config.toml。
  • CI 中需要固定配置。
  • 某次任务需要更细的开关。

4.5 --enable FEATURE 与 --disable FEATURE

临时打开或关闭功能开关，等价于覆盖 features.FEATURE=true/false。

Bash 
codex --enable unified_exec "检查当前功能开关影响"

如果要持久修改，用 codex features enable 或 codex features disable。

4.6 -i, --image FILE

给初始 prompt 附加图片。

Bash 
codex -i screenshot.png "根据截图找出页面布局问题"
codex exec -i error.png "解释截图里的错误信息"

适合 UI bug、设计还原、报错截图、图表解释。

4.7 --search

启用实时 web search，让模型可以查当前网页信息。

Bash 
codex --search "查官方文档，确认这个库的最新迁移方式"

适合依赖文档、最新版本、变更日志、错误码排查。涉及离线代码分析时不一定需要。

4.8 --add-dir DIR

把额外目录加入可写范围。

Bash 
codex --cd ~/repo --add-dir ~/shared-scripts "修改仓库代码，并同步更新 shared-scripts 里的脚本"

适合单次任务需要写多个目录。不要把整个 home 目录随手加进去。

4.9 --no-alt-screen

禁用终端 alternate screen。

Bash 
codex --no-alt-screen

适合 tmux、zellij 或你想保留终端滚动历史的场景。

5. 沙箱与审批：最重要的安全边界

Codex 会运行 shell 命令，因此安全设置必须先理解。

5.1 --sandbox

可选值：

  • read-only：只读。适合分析、审查、问答。
  • workspace-write：允许写工作区。适合日常改代码。
  • danger-full-access：几乎不限制文件系统访问。只在你完全理解风险、且环境本身已隔离时使用。

推荐组合：

Bash 
codex --sandbox read-only --ask-for-approval on-request "审查架构"
codex --sandbox workspace-write --ask-for-approval on-request "修复 bug 并跑测试"
codex exec --sandbox read-only --ask-for-approval never "生成报告"
codex exec --sandbox workspace-write --ask-for-approval never "按固定脚本更新文档"

5.2 --ask-for-approval

可选值：

  • untrusted：只对受信任命令免确认，其它命令会请求用户批准。
  • on-request：由模型判断什么时候请求批准。交互会话通常选它。
  • never：不请求用户批准，失败就把结果交回模型。非交互脚本通常选它。
  • on-failure：已废弃，不建议新脚本使用。

5.3 --dangerously-bypass-approvals-and-sandbox

跳过所有确认并关闭沙箱。这个选项名字已经说明风险。

只考虑在这些情况下使用：

  • 外层已经有 Docker、VM、CI runner、临时账号或一次性目录隔离。
  • 任务完全自动化，且你能接受它直接执行命令。
  • 没有任何生产凭据、重要文件或不可恢复数据暴露在环境里。

平时不要把它写成 alias，也不要放进通用脚本。

6. 认证命令

6.1 codex login

Bash 
codex login

启动登录流程。通常用于个人交互式使用。

6.2 codex login --with-api-key

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

从 stdin 读取 API key。适合自动化环境。不要把 key 明文写在命令参数里。

6.3 codex login --with-access-token

Bash 
printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

从 stdin 读取 access token。适合已有 token 管理流程的环境。

6.4 codex login --device-auth

Bash 
codex login --device-auth

适合远程服务器、无浏览器环境或需要设备码登录的终端。

6.5 codex login status

Bash 
codex login status

检查当前登录状态。

6.6 codex logout

Bash 
codex logout

删除本机保存的认证凭据。换账号、交接机器、清理 CI 环境时使用。

7. 交互式 codex

直接运行：

Bash 
codex

带初始 prompt：

Bash 
codex "先阅读 README 和 package.json，告诉我本地开发流程"

交互式适合需要多轮沟通的任务：

  • 让 Codex 读代码后先给计划。
  • 分步骤修复问题。
  • 边跑测试边调整。
  • 让 Codex解释它为什么要改某处。
  • 遇到不确定需求时让它先问你。

实用提示：

  • 在项目根目录启动，或者总是用 --cd。
  • 大改动前先要求 Codex 总结相关文件和风险。
  • 想要它谨慎一点，用 --sandbox read-only 先分析，再切到可写模式。
  • 需要最新文档时加 --search。
  • 如果它引用了错误目录，直接要求它重新检查 pwd 和仓库根目录。

8. Slash commands、会话模式与 /goal

Slash commands 是交互式 TUI 里的快捷控制命令。进入 codex 后，在输入框里输入 / 会打开命令弹窗；继续输入命令名可以过滤列表。它们不是普通 shell 命令，不是在外部终端直接执行的 codex xxx，而是在当前 Codex 会话内部改变状态、切换模式、查看信息或触发动作。

如果当前任务正在运行，部分 slash command 可以输入后按 Tab 排队，Codex 会在当前 turn 结束后再解析。不同版本、不同平台、不同功能开关下可见命令可能不同；以当前会话里的 /help 或 slash 弹窗为准。

8.1 先记住这几个模式类命令

/plan：计划模式

Plain Text 
/plan
/plan Propose a migration plan for this service

作用：切换到 plan mode，让 Codex 先做计划，再进入实现。适合大改动、迁移、重构、需求还不够清晰的任务。

什么时候用：

  • 你想先看方案，不希望 Codex 马上改文件。
  • 任务涉及多个模块，需要先拆步骤。
  • 你要比较几种实现路线。

注意：任务正在运行时，/plan 通常不可用。你可以等当前 turn 结束后再切换。

/goal：长期目标模式

Plain Text 
/goal Finish the migration and keep tests green
/goal
/goal pause
/goal resume
/goal clear

作用：给当前线程设置一个持续目标，让 Codex 把这个 objective 作为长期任务跟踪，而不是只完成普通一轮回复就停下。

当前官方说明里 /goal 仍是 experimental 功能，需要先启用 features.goals。启用方式有两种：

Plain Text 
/experimental

或在 config.toml 中加入：

TOML 
[features]
goals = true

子命令含义：

  • /goal <objective>：设置当前线程的目标。
  • /goal：查看当前目标。
  • /goal pause：暂停目标。
  • /goal resume：继续目标。
  • /goal clear：移除目标。

什么时候用：

  • 任务很长，比如“把整个项目迁移到新认证方案并保持测试通过”。
  • 你希望 Codex 记住最终目标，持续自检，而不是只完成一个小步骤。
  • 你要它在多轮对话中围绕同一目标推进。

和 /plan 的区别：/plan 主要是“先想清楚怎么做”；/goal 主要是“持续追踪并推进一个长期目标”。实际使用时可以组合：先 /plan 让 Codex 产出计划，再用 /goal 按这个计划完成迁移并通过测试 让它持续推进。

/permissions：权限/审批模式

Plain Text 
/permissions

作用：在会话中切换 Codex 可以自动做什么，比如更保守的只读审查，或更自动化的修改模式。它影响后续 shell 命令、文件写入和审批行为。

什么时候用：

  • 只想让 Codex 读代码、解释问题：切到更保守的模式。
  • 已经确认方案，想让它连续改文件：切到更自动的模式。
  • 发现它准备做危险操作，临时收紧权限。

这和启动参数里的 --sandbox、--ask-for-approval 是同一类安全边界：启动参数适合会话开始前定策略，/permissions 适合会话中临时调整。

/fast：快速模式

Plain Text 
/fast on
/fast off
/fast status

作用：对支持的模型切换 Fast mode，偏向更快响应。适合简单编辑、问答、重复性任务；复杂推理、关键重构、审查类任务可以关闭。

/personality：沟通风格

Plain Text 
/personality

作用：调整 Codex 的回复风格，比如更简洁、更协作或关闭个性化表达。它只改变沟通方式，不等于改变模型能力或权限。

8.2 会话与上下文控制

Plain Text 
/compact
/clear
/new
/resume
/fork
/side
  • /compact：压缩长对话，把前文总结成更短上下文，适合长任务快占满上下文时使用。
  • /clear：清空当前终端显示并开始新聊天。不同于 Ctrl+L，它会重置会话。
  • /new：在同一个 CLI 进程里开始新对话，但不一定清空终端显示。
  • /resume：从保存的会话列表恢复旧对话。
  • /fork：把当前对话分叉成新线程，用来尝试另一种方案。
  • /side：开一个临时侧边对话，问一个局部问题，不打乱主线程。

什么时候用：

  • 上下文太长：/compact。
  • 换一个完全不同任务：/new 或 /clear。
  • 继续旧任务：/resume。
  • 想试替代方案：/fork。
  • 临时问一个不想污染主线的问题：/side。

8.3 工作区检查与审查

Plain Text 
/diff
/review
/status
/debug-config
  • /diff：查看当前 Git diff，包括未跟踪文件，适合提交前确认 Codex 改了什么。
  • /review：让 Codex 审查当前 working tree，偏向找 bug、风险和缺失测试。
  • /status：查看当前模型、审批策略、可写目录、token/context 使用情况等。
  • /debug-config：查看配置层级和策略来源，用来排查为什么实际配置和 config.toml 不一致。

8.4 模型、工具和文件引用

Plain Text 
/model
/mcp
/mention
/apps
/plugins
/init
  • /model：切换当前会话模型和可用 reasoning 选项。
  • /mcp：查看当前配置的 MCP 工具；有些版本支持 verbose 查看更详细 server 信息。
  • /mention：把某个文件或目录加入当前对话上下文，适合明确要求 Codex 看指定文件。
  • /apps：浏览并插入 app/connectors。
  • /plugins：浏览已安装或可发现的插件。
  • /init：在当前目录生成 AGENTS.md 脚手架，方便沉淀项目级指令。

8.5 后台任务和终端 UI

Plain Text 
/ps
/stop
/statusline
/title
/keymap
  • /ps：查看实验后台终端及最近输出。
  • /stop：停止当前会话启动的后台终端；某些版本里 /clean 仍作为别名存在。
  • /statusline：配置 TUI 底部状态栏显示项，例如模型、context、git 分支、token、当前目录。
  • /title：配置终端窗口或标签标题显示项。
  • /keymap：查看、修改并持久化 TUI 快捷键。

8.6 退出、复制和反馈

Plain Text 
/copy
/logout
/feedback
/quit
/exit
  • /copy：复制最近一次已完成的 Codex 输出；有些版本也支持 Ctrl+O。
  • /logout：退出当前 Codex 登录状态。
  • /feedback：向 Codex 维护者发送日志或反馈。
  • /quit / /exit：退出 CLI。

8.7 一句话选择

  • 想先规划：用 /plan。
  • 想让 Codex 持续追一个长期目标：启用 features.goals 后用 /goal。
  • 想调权限：用 /permissions。
  • 想切模型：用 /model。
  • 想压缩上下文：用 /compact。
  • 想看改了什么：用 /diff。
  • 想审查当前改动：用 /review。
  • 想恢复、分叉或旁路提问：用 /resume、/fork、/side。
  • 想确认当前会话状态：用 /status。

9. 非交互 codex exec

codex exec 用于脚本和 CI，不打开 TUI。

Bash 
codex exec "总结最近 10 个 commit 的改动"

9.1 prompt 与 stdin

只传 prompt：

Bash 
codex exec "列出仓库中最可能缺测试的模块"

从 stdin 读取指令：

Bash 
printf '总结这个项目的风险' | codex exec -

prompt 加 stdin：

Bash 
git diff | codex exec "根据 diff 写一份中文 PR 摘要"

这种情况下，prompt 是任务说明，stdin 是补充上下文。

9.2 输出控制

Bash 
codex exec --json "检查项目并输出事件流"
codex exec -o result.md "生成维护手册"
codex exec --color never "输出纯文本摘要"
  • --json：输出 JSONL 事件流，适合机器消费。
  • -o, --output-last-message FILE：把最后一条 agent 消息写到文件。
  • --color always|never|auto：控制颜色输出。

9.3 会话与配置隔离

Bash 
codex exec --ephemeral "临时分析，不保存会话文件"
codex exec --ignore-user-config "不用我的用户配置，只按命令行参数执行"
codex exec --ignore-rules "忽略用户或项目 execpolicy rules"
codex exec --skip-git-repo-check "允许在非 git 目录里运行"

含义：

  • --ephemeral：不把 rollout/session 文件持久化到磁盘。
  • --ignore-user-config：不读取 $CODEX_HOME/config.toml，但认证仍使用 CODEX_HOME。
  • --ignore-rules：不加载 execpolicy .rules 文件。
  • --skip-git-repo-check：当前目录不是 Git 仓库时也运行。

9.4 结构化输出

Bash 
codex exec --output-schema schema.json "扫描项目并按 schema 输出结果"

--output-schema 接收 JSON Schema 文件，适合让 Codex 输出固定结构，供脚本继续处理。

9.5 非交互安全建议

  • 默认以只读为主。
  • 自动化脚本常配 --ask-for-approval never，避免挂住 CI。
  • 如果要写文件，显式加 --sandbox workspace-write。
  • 对可能联网、安装依赖、删除文件的任务，要么拆小，要么用外层容器隔离。

10. 代码审查命令

Codex 有两种审查入口。

Bash 
codex review [OPTIONS] [PROMPT]
codex exec review [OPTIONS] [PROMPT]

常用选项：

Bash 
codex review --uncommitted
codex review --base main
codex review --commit HEAD
codex review --title "feat: add billing webhook"

含义：

  • --uncommitted：审查 staged、unstaged 和 untracked changes。
  • --base BRANCH：审查当前分支相对某个 base 分支的改动。
  • --commit SHA：审查某个 commit 引入的改动。
  • --title TITLE：给审查摘要提供标题。

什么时候用：

  • 提交前找明显 bug。
  • PR 前检查回归风险。
  • 大改动后让 Codex 只做 review，不做修改。
  • 想让它按特定关注点审查时，把 prompt 加上：
Bash 
codex review --base main "重点检查安全问题、数据库迁移风险和缺失测试"

11. 会话管理：resume 与 fork

11.1 codex resume

Bash 
codex resume
codex resume --last
codex resume SESSION_ID
codex resume --all
codex resume --include-non-interactive

适合继续之前的交互会话。--last 直接恢复最近一次，不打开选择器。--all 显示所有会话，不按当前目录过滤。--include-non-interactive 会把 codex exec 产生的会话也纳入。

11.2 codex fork

Bash 
codex fork --last
codex fork SESSION_ID "尝试另一种方案"

fork 会基于旧会话开新线程，适合：

  • 对同一问题尝试不同实现。
  • 保留原会话，不污染上下文。
  • 从某个关键节点重新出发。

12. 项目指令：AGENTS.md

Codex 会在开始工作前读取指令文件。常用文件名：

  • ~/.codex/AGENTS.md：用户级默认规则。
  • ~/.codex/AGENTS.override.md：用户级临时覆盖。
  • 仓库中的 AGENTS.md：项目规则。
  • 仓库中的 AGENTS.override.md：当前层级覆盖规则。

推荐写法：

Markdown 
# AGENTS.md

## 工作约定
- 修改 TypeScript 后运行 npm test。
- 优先使用 pnpm。
- 不要改动未关联的格式化。
- 涉及数据库迁移时先说明风险。

验证当前会加载哪些指令：

Bash 
codex --ask-for-approval never "总结当前加载的指令来源"
codex --cd services/api --ask-for-approval never "说明这个目录下有哪些项目规则生效"

适合团队沉淀：测试命令、包管理器、代码风格、禁止事项、部署约定、安全边界。

13. 配置文件 config.toml

Codex 的用户配置通常在：

Plain Text 
~/.codex/config.toml

项目级配置可以放在：

Plain Text 
.codex/config.toml

官方文档说明，配置优先级从高到低大致是：命令行 flag 和 -c 覆盖、profile、项目配置、用户配置、系统配置、内置默认值。

一个基础示例：

TOML 
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.readonly]
approval_policy = "on-request"
sandbox_mode = "read-only"

[profiles.auto]
approval_policy = "never"
sandbox_mode = "workspace-write"

使用 profile：

Bash 
codex --profile readonly "分析风险，不要改文件"
codex exec --profile auto "更新生成文档"

什么时候写配置文件，什么时候用 flag：

  • 长期默认行为：写 config.toml。
  • 某次临时覆盖：用 -c 或 flag。
  • 团队共享规则：写仓库 .codex/config.toml 和 AGENTS.md，并确保成员理解信任边界。

14. MCP：给 Codex 接第三方工具和上下文

MCP 是 Model Context Protocol，用来把外部工具、文档、浏览器、Figma、数据库等能力接给 Codex。

14.1 查看 MCP 配置

Bash 
codex mcp list
codex mcp list --json
codex mcp get server_name
codex mcp get server_name --json

14.2 添加本地 stdio MCP server

Bash 
codex mcp add my-server -- npx -y my-mcp-server

带环境变量：

Bash 
codex mcp add my-server --env API_TOKEN=xxx -- npx -y my-mcp-server

更安全的做法是让 server 从环境变量名读取 token，不把密钥写进命令历史。

14.3 添加 HTTP MCP server

Bash 
codex mcp add docs --url https://example.com/mcp

如果 HTTP server 需要 bearer token：

Bash 
codex mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN

14.4 OAuth 登录和退出

Bash 
codex mcp login server_name
codex mcp login server_name --scopes scope1,scope2
codex mcp logout server_name

14.5 删除 MCP server

Bash 
codex mcp remove server_name

什么时候用 MCP：

  • 想让 Codex 查私有文档。
  • 想让 Codex 操作浏览器、Figma、Notion、GitHub 等工具。
  • 想把公司内部 API、数据库 schema、设计系统暴露给 Codex。
  • 希望 CLI 和 IDE extension 共用同一套工具配置。

15. 插件与 marketplace

Codex 插件用于安装成套能力。当前 CLI 的插件管理入口是：

Bash 
codex plugin marketplace add SOURCE
codex plugin marketplace upgrade
codex plugin marketplace upgrade marketplace_name
codex plugin marketplace remove marketplace_name

SOURCE 支持 GitHub owner/repo@ref、HTTP Git URL、SSH URL 或本地 marketplace 根目录。

示例：

Bash 
codex plugin marketplace add owner/repo@main
codex plugin marketplace add https://github.com/owner/repo.git
codex plugin marketplace add /path/to/local/marketplace

什么时候用：

  • 团队想统一分发技能、MCP server 和工具配置。
  • 你经常做同一类工作，比如 GitHub PR、Figma、浏览器测试、文档生成。
  • 希望把可复用工作流版本化。

16. Feature flags

查看功能开关：

Bash 
codex features list

持久启用或关闭：

Bash 
codex features enable feature_name
codex features disable feature_name

单次启用或关闭：

Bash 
codex --enable feature_name "运行一次实验功能"
codex --disable feature_name "本次不要使用某功能"

适合测试新功能、排查某个功能导致的问题、在团队里逐步启用实验能力。

17. Shell completion 与升级

生成补全脚本：

Bash 
codex completion bash
codex completion zsh
codex completion fish
codex completion powershell
codex completion elvish

例如 zsh 用户通常可以把输出写入自己的 completion 路径，再重新加载 shell。具体路径取决于你的 shell 配置。

升级 Codex：

Bash 
codex update

如果你是通过包管理器安装，实际升级方式可能仍取决于安装来源。升级后重新运行：

Bash 
codex --version
codex --help

18. Sandbox 子命令：单独在沙箱里跑命令

Codex 也提供直接运行沙箱命令的入口。

Bash 
codex sandbox macos -- ls
codex sandbox linux -- npm test
codex sandbox windows -- powershell -Command Get-ChildItem

平台差异：

  • macos 使用 macOS Seatbelt。
  • linux 默认基于 Linux sandbox。
  • windows 使用 Windows restricted token。

常用选项：

Bash 
codex sandbox macos -C /path/to/repo --permissions-profile default -- npm test
codex sandbox macos --log-denials -- npm test
codex sandbox macos --allow-unix-socket ./tmp/socket -- your-command

适合调试沙箱权限、复现某个命令在受限环境里的行为、给团队验证某个权限 profile。

19. Execpolicy rules

execpolicy 是实验能力，用于检查规则文件会如何处理某个命令。

Bash 
codex execpolicy check --rules ~/.codex/rules/default.rules gh pr view 123
codex execpolicy check --pretty --rules rules/default.rules npm test

可选项：

  • --rules PATH：指定一个或多个 rules 文件。
  • --pretty：格式化 JSON 输出。
  • --resolve-host-executables：解析 host executable 规则。

什么时候用：

  • 团队希望规定哪些命令自动允许、哪些必须提示、哪些直接禁止。
  • 你在调试为什么 Codex 会请求某条命令的批准。
  • 你想在 CI 或本地预先测试 rules 文件。

20. 调试命令

Bash 
codex debug models
codex debug prompt-input "解释当前 prompt 输入"
  • debug models：查看 Codex 能看到的模型 catalog。
  • debug prompt-input：把模型可见的输入列表渲染为 JSON，适合排查 AGENTS.md、图片、prompt 和上下文是否按预期进入模型。

如果怀疑指令没有加载，可以查看 Codex 日志或 session 文件，并用一个只读 prompt 让 Codex 复述当前指令来源。

21. Desktop、远程和 server 相关命令

这些命令多数面向 Codex App、远程连接或集成开发。

21.1 打开桌面应用

Bash 
codex app
codex app /path/to/workspace

如果桌面应用不存在，命令可能打开安装流程。

21.2 MCP server 模式

Bash 
codex mcp-server

让 Codex 自己作为 MCP server 通过 stdio 提供给其它 agent 使用。

21.3 App server

Bash 
codex app-server
codex app-server --listen stdio://
codex app-server --listen ws://127.0.0.1:PORT

适合 IDE、App 或远程控制场景。可配 WebSocket 认证参数，例如 token 文件、共享密钥、issuer、audience 等。

21.4 Remote control

Bash 
codex remote-control

启动带 remote control 的 headless app-server。属于实验能力，适合高级集成，不是普通日常开发入口。

21.5 Exec server

Bash 
codex exec-server --listen ws://127.0.0.1:PORT
codex exec-server --listen stdio://

用于独立执行服务或远程 executor 注册。普通本地开发很少需要。

22. Codex Cloud 命令

Codex Cloud 相关命令是实验能力，用于浏览云端任务并把 diff 应用到本地。

Bash 
codex cloud
codex cloud list
codex cloud list --env ENV_ID --limit 10 --json
codex cloud status TASK_ID
codex cloud diff TASK_ID
codex cloud diff TASK_ID --attempt 1
codex cloud apply TASK_ID
codex cloud apply TASK_ID --attempt 1

提交云端任务：

Bash 
codex cloud exec --env ENV_ID "修复这个仓库里的 failing test"
codex cloud exec --env ENV_ID --branch feature/foo --attempts 3 "实现用户设置页"

什么时候用：

  • 想让云端环境执行任务。
  • 本地不想拉完整依赖，但希望拿到云端 diff。
  • 同一个任务想跑多个 attempts 再挑一个应用。

应用云端 diff 前建议先看：

Bash 
codex cloud diff TASK_ID

确认后再：

Bash 
codex cloud apply TASK_ID

23. 本地 OSS provider

如果你要使用本地开源模型 provider：

Bash 
codex --oss
codex --oss --local-provider ollama
codex --oss --local-provider lmstudio

适合：

  • 本地实验。
  • 离线或内网场景。
  • 成本敏感但能接受能力差异的任务。

注意：本地模型能力、上下文长度、工具调用稳定性会影响体验。复杂代码任务仍建议用适合 Codex 的强模型。

24. 常见组合范式

24.1 安全分析，不改文件

Bash 
codex --sandbox read-only --ask-for-approval on-request --cd ~/repo "分析认证模块的安全风险，给出文件和行号"

24.2 日常修 bug

Bash 
codex --sandbox workspace-write --ask-for-approval on-request --cd ~/repo "修复用户注册失败的问题，并运行相关测试"

24.3 自动化生成报告

Bash 
codex exec --sandbox read-only --ask-for-approval never -o report.md "生成项目健康度报告"

24.4 CI 里审查当前改动

Bash 
codex exec review --base main --json -o codex-review.json

24.5 从 diff 生成 PR 描述

Bash 
git diff main...HEAD | codex exec --sandbox read-only "根据 diff 写一份中文 PR 描述，包含风险和测试"

24.6 临时覆盖模型和权限

Bash 
codex -m gpt-5.5 --sandbox workspace-write --ask-for-approval on-request "实现缓存层重构"

24.7 使用 live web search 查文档

Bash 
codex --search --sandbox workspace-write "查官方迁移文档，然后把项目升级到当前推荐写法"

24.8 多目录写入

Bash 
codex --cd ~/repo --add-dir ~/docs "修改代码，并同步更新外部 docs 目录里的说明"

24.9 恢复会话并追加图片

Bash 
codex resume --last -i screenshot.png "继续刚才的问题，现在根据截图修 UI"

24.10 分叉会话做替代方案

Bash 
codex fork --last "不要沿用当前实现，尝试更小改动的方案"

25. 什么时候用哪个命令

  • 想边聊边改：codex。
  • 想一次性生成结果：codex exec。
  • 想审查改动：codex review 或 codex exec review。
  • 想继续旧会话：codex resume。
  • 想从旧会话开新方向：codex fork。
  • 想接工具和私有上下文：codex mcp。
  • 想管理插件来源：codex plugin marketplace。
  • 想查看或固定实验功能：codex features。
  • 想调试模型和 prompt：codex debug。
  • 想单独验证沙箱：codex sandbox。
  • 想控制命令审批策略：配置 approval_policy、sandbox_mode，必要时用 execpolicy。
  • 想在云端跑任务：codex cloud。

26. 新项目推荐初始化

在新仓库里，建议按这个顺序配置。

  1. 建立项目规则：
Bash 
cat AGENTS.md

确认里面有测试命令、包管理器、代码风格和禁止事项。如果没有，就创建或补充。

  1. 用只读模式让 Codex 识别项目：
Bash 
codex --sandbox read-only "阅读项目规则和 README，总结开发、测试、构建命令"
  1. 让 Codex 先给计划：
Bash 
codex --sandbox read-only "针对我要修复的 bug，先找相关文件并给出修改计划，不要改文件"
  1. 再允许写入：
Bash 
codex --sandbox workspace-write --ask-for-approval on-request "按刚才计划实现，并运行相关测试"
  1. 提交前审查：
Bash 
codex review --uncommitted "重点找 bug、回归风险和缺失测试"

27. 排错清单

27.1 Codex 好像不在正确目录

Bash 
pwd
codex --cd /correct/repo "告诉我当前工作目录和 git root"

27.2 指令没有生效

Bash 
codex --ask-for-approval never "列出你加载到的 AGENTS.md 指令来源"

检查：~/.codex/AGENTS.override.md、仓库根目录 AGENTS.md、子目录 AGENTS.override.md、CODEX_HOME。

27.3 CI 卡住

检查是否用了会请求确认的审批策略。CI 通常需要：

Bash 
codex exec --ask-for-approval never --sandbox read-only "任务"

如果要写文件，用 workspace-write，并确保外层环境安全。

27.4 权限不够

先不要直接上 danger-full-access。优先考虑：

Bash 
codex --sandbox workspace-write --add-dir /needed/path "任务"

或者在 config.toml 中配置 sandbox_workspace_write.writable_roots。

27.5 需要联网

交互模式查资料可用：

Bash 
codex --search "查官方文档后回答"

如果是沙箱内命令需要联网，检查 sandbox_workspace_write.network_access 或外层网络策略。

27.6 输出要给其它脚本消费

优先用：

Bash 
codex exec --json "任务"
codex exec --output-schema schema.json "任务"
codex exec -o result.md "任务"

28. 最小安全原则

  • 先读后写：复杂任务先 read-only 分析，再 workspace-write 实现。
  • 小步提交：让 Codex 做小范围修改，跑相关测试，再继续。
  • 明确边界：prompt 里写清楚“不要改哪些文件”“只关注哪些目录”。
  • 保留人工判断：danger-full-access 和绕过审批只放在隔离环境里。
  • 版本锁定：长期脚本记录 Codex 版本和关键选项。
  • 审查输出：应用云端 diff、批量改动、依赖升级前先看 diff。

29. 一张总览表

30. 资料来源

评论