Codex 命令行工具

Codex CLI 是官方命令行工具，用 Rust 编写，轻量高效，适合终端爱好者。

---

安装 CLI

Codex CLI 支持 macOS、Linux 和 Windows（实验性）。

npm 安装

npm 全局安装

# 使用 npm 安装
npm install -g @openai/codex
# 验证安装
codex --version

Homebrew 安装

# macOS 使用 Homebrew
brew install codex

更新 CLI

更新版本

# npm 更新
npm install -g @openai/codex@latest
# Homebrew 更新
brew upgrade codex

---

首次使用

首次运行 Codex 会引导你完成认证：

启动 Codex

# 启动交互式界面
codex
# 或指定初始任务
codex "解释这个项目结构"

Codex 会打开浏览器进行认证：

1. 使用 ChatGPT 账号登录
2. 或使用 OpenAI API Key
3. 授权后返回终端继续

---

交互式 TUI

CLI 默认进入终端用户界面（TUI）模式，提供沉浸式体验。

TUI 界面区域

区域	功能
消息区	显示对话历史、工具调用、执行结果
输入区	底部输入框，发送 Prompt
状态栏	显示模型、上下文使用、线程信息

TUI 模式设置

TUI 配置

# ~/.codex/config.toml
[tui]
# 替代屏幕模式
alternate_screen = "auto"  # auto | always | never
# 禁用替代屏幕时保留滚动历史
# alternate_screen = "never"

替代屏幕模式让 Codex 使用独立屏幕，退出时恢复原终端状态。

---

Approval 模式

Approval 模式控制 Codex 执行操作前的确认行为。

四种模式

模式	说明	行为
suggest	建议模式	Codex 提供建议但不执行
auto-edit	自动编辑	自动执行文件编辑，命令需确认
full-auto	全自动	自动执行所有操作（谨慎使用）
interactive	交互模式	敏感操作前询问（默认）

设置 Approval 模式

# 命令行指定模式
codex --approval-mode full-auto
# 或在会话中切换
/approval full-auto

full-auto 模式下 Codex 会自动执行所有操作，包括删除文件，请谨慎使用。

---

Sandbox 模式

Sandbox 模式限制 Codex 的文件和命令访问范围。

模式	文件修改	命令执行	网络访问
read-only	禁止	禁止	禁止
workspace-write	仅工作区	允许	禁止
danger-full-access	允许	允许	允许

设置 Sandbox 模式

# 只读模式
codex --sandbox read-only
# 工作区写入模式（推荐）
codex --sandbox workspace-write
# 完全访问模式（危险）
codex --sandbox danger-full-access

---

斜杠命令

CLI 提供丰富的斜杠命令：

命令	功能
/model	切换模型（如 /model gpt-5.4-mini）
/fast	切换 Fast 模式
/plan	进入计划模式
/review	审查代码变更
/new	开始新会话
/resume	恢复历史会话
/fork	克隆当前会话到新线程
/compact	压缩上下文历史
/status	显示会话状态
/clear	清除屏幕
/quit	退出 Codex

命令使用示例

斜杠命令

# 切换模型
/model gpt-5.4-mini
# 计划模式
/plan 实现用户认证系统
# 查看状态
/status

---

Shell 命令执行

在 CLI 中直接执行 Shell 命令：

执行命令

# 以 ! 开头执行命令
! ls -la
# 执行 git 命令
! git status
# 查看进程
! ps aux

命令确认

危险命令需要确认：

• 删除文件（rm）
• 终止进程（kill）
• 修改系统配置

---

图片输入

CLI 支持附加图片作为上下文：

附加图片

# 附加截图
codex -i screenshot.png
# 附加设计稿
codex --image design.png "根据这个设计实现页面"
# 多张图片
codex -i img1.png -i img2.png

图片用途

• 截图分析错误信息
• UI 设计稿转换为代码
• 图表数据解读

---

非交互模式（exec）

使用 exec 命令运行单次任务，适合脚本和 CI/CD：

exec 命令

# 执行单次任务
codex exec "审查代码并输出报告"
# 输出到文件
codex exec "生成 README" -o README.md
# 使用特定模型
codex exec -m gpt-5.4-mini "分析项目结构"
# 全自动模式
codex exec --full-auto "运行测试并修复失败"

exec 常用参数

参数	说明
-m	指定模型
-o	输出到文件
--full-auto	全自动执行
--ephemeral	不保存会话文件
--json	JSON 输出格式

---

快捷键

快捷键	功能
Enter	发送消息
Shift+Enter	换行
Ctrl+C	中断操作
Ctrl+C (两次)	退出 Codex
Ctrl+D	退出（输入空时）
Ctrl+R	搜索历史
Up/Down	浏览历史
Tab	自动补全
Esc Esc	编辑上一条消息
Ctrl+O	复制最后回复

---

常见问题

Q: Windows 支持情况？

Windows 原生支持实验性，推荐使用 WSL2 获得最佳体验。

Q: 如何禁用替代屏幕？

使用 codex --no-alt-screen 或配置 alternate_screen = "never"。

Q: 命令找不到？

确保 PATH 包含 npm 全局安装目录，或使用 Homebrew 安装。

Q: 如何查看详细日志？

日志位于 ~/.codex/log/ 目录。