OpenAI Codex CLI 命令行参考笔记

OpenAI Codex CLI 命令行参考笔记

来源: https://developers.openai.com/codex/cli/reference

概述

Codex CLI 是 OpenAI 提供的终端客户端工具，用于在命令行中与 AI 进行交互。配置文件默认位于 ~/.codex/config.toml。

---

一、全局标志 (Global Flags)

标志	类型	说明
--add-dir	path	授予额外目录的写入权限，可重复使用
--ask-for-approval, -a	`untrusted	on-request
--cd, -C	path	设置工作目录
--config, -c	key=value	覆盖配置值
--dangerously-bypass-approvals-and-sandbox, --yolo	boolean	跳过所有审批和沙箱（危险）
--disable	feature	禁用功能标志
--enable	feature	启用功能标志
--full-auto	boolean	低摩擦本地工作快捷方式
--image, -i	path[,path...]	附加图片到初始提示
--model, -m	string	覆盖模型设置
--no-alt-screen	boolean	禁用 TUI 备用屏幕模式
--oss	boolean	使用本地开源模型（需 Ollama）
--profile, -p	string	加载配置文件
--sandbox, -s	`read-only	workspace-write
--search	boolean	启用实时网络搜索
PROMPT	string	可选的初始指令

---

二、命令概览

稳定命令 (Stable)

命令	说明
codex	启动终端 UI
codex app	启动桌面应用（仅 macOS）
codex apply	应用 Cloud 任务差异到本地
codex completion	生成 shell 补全脚本
codex exec	非交互模式运行
codex features	管理功能标志
codex fork	分叉之前的会话
codex login	身份验证
codex logout	移除凭证
codex resume	恢复之前的会话

实验性命令 (Experimental)

命令	说明
codex app-server	启动本地应用服务器
codex cloud	浏览/执行 Cloud 任务
codex execpolicy	评估执行策略规则
codex mcp	管理 MCP 服务器
codex mcp-server	将 Codex 作为 MCP 服务器运行
codex sandbox	在沙箱中运行命令

---

三、常用命令详解

1. codex (交互模式)

# 启动交互式终端 UI
codex

# 带初始提示启动
codex "帮我分析这个项目"

# 附加图片
codex -i screenshot.png "这个 UI 有什么问题？"

# 全自动模式（低摩擦）
codex --full-auto "重构这个模块"

2. codex exec (非交互模式)

用于 CI/CD 或脚本化运行。

# 基本用法
codex exec "运行测试并修复失败的用例"

# JSON 输出
codex exec --json "分析代码质量"

# 输出最后消息到文件
codex exec -o result.txt "生成报告"

# 从 stdin 读取提示
echo "分析代码" | codex exec -

# 恢复之前的 exec 会话
codex exec resume --last

主要选项：

• --json - 输出 JSONL 格式
• --output-last-message, -o - 输出到文件
• --output-schema - JSON Schema 验证
• --ephemeral - 不持久化会话
• --skip-git-repo-check - 允许非 Git 目录

3. codex login (身份验证)

# 浏览器 OAuth 登录
codex login

# 设备码流程（无浏览器）
codex login --device-auth

# 使用 API Key
echo $OPENAI_API_KEY | codex login --with-api-key

# 检查登录状态
codex login status

4. codex resume (恢复会话)

# 恢复最近会话
codex resume --last

# 恢复指定会话
codex resume <SESSION_ID>

# 搜索所有目录的会话
codex resume --last --all

5. codex fork (分叉会话)

# 分叉最近会话为新线程
codex fork --last

6. codex mcp (MCP 服务器管理)

# 列出 MCP 服务器
codex mcp list

# 添加 stdio 服务器
codex mcp add my-server -- npx -y @my/mcp-server

# 添加 HTTP 服务器
codex mcp add my-http --url https://example.com/mcp

# 删除服务器
codex mcp remove my-server

7. codex features (功能标志)

# 列出所有功能标志
codex features list

# 启用功能
codex features enable <feature>

# 禁用功能
codex features disable <feature>

8. codex cloud (Cloud 任务)

# 交互式选择任务
codex cloud

# 执行任务
codex cloud exec --env <ENV_ID> "任务描述"

# 列出任务
codex cloud list --json

9. codex completion (Shell 补全)

# Bash
codex completion bash > /etc/bash_completion.d/codex

# Zsh
codex completion zsh > "${fpath[1]}/_codex"

# Fish
codex completion fish > ~/.config/fish/completions/codex.fish

# PowerShell
codex completion power-shell

---

四、沙箱策略

策略	说明
read-only	只读访问
workspace-write	可写工作区（推荐）
danger-full-access	完全访问（危险）

---

五、安全提示

1. 推荐组合 ：使用 --full-auto 进行无人值守本地工作
2. 避免 ：将 --full-auto 与 --dangerously-bypass-approvals-and-sandbox 组合使用
3. 额外目录 ：使用 --add-dir 而非 --sandbox danger-full-access
4. CI 场景 ：组合 --json 和 --output-last-message 捕获输出

---

六、常用场景示例

# 快速代码审查
codex --full-auto "审查 src/ 目录的代码质量"

# 带图片的分析
codex -i bug-screenshot.png "这个错误怎么修复？"

# CI 中的自动化任务
codex exec --json --full-auto "运行测试并生成报告"

# 指定模型运行
codex -m gpt-5-codex "优化这个算法"

# 使用本地模型
codex --oss "帮我写单元测试"

# 启用网络搜索
codex --search "查找最新的 React 最佳实践"

---

七、配置文件

配置文件位置：~/.codex/config.toml

可以通过 -c key=value 在命令行覆盖配置。

---

相关资源

• Codex CLI 概览
• 配置基础
• 高级配置
• AGENTS.md 指南