一、基础用法

codex [OPTIONS] [PROMPT]          # 交互式启动（最常用）
codex [OPTIONS] <COMMAND> [ARGS]  # 非交互式子命令

---

二、核心选项（日常使用频率最高）

1. 模型相关

-m, --model <MODEL>           # 指定使用的模型，如 -m "gpt-4"
--oss                         # 使用开源模型提供商
--local-provider <PROVIDER>   # 配合 --oss 使用，指定 lmstudio 或 ollama

示例：

codex -m "claude-3.5-sonnet" "帮我写一个排序算法"
codex --oss --local-provider ollama "解释这段代码"

2. 工作目录

-C, --cd <DIR>                # 设置 Agent 的工作根目录
--add-dir <DIR>               # 额外可写的目录（可重复使用）

示例：

codex -C /my/project "重构这个函数"
codex -C /project --add-dir /tmp/data "读取两个目录的数据"

3. 沙箱安全控制

-s, --sandbox <SANDBOX_MODE>  # 沙箱策略
# 可选值：read-only, workspace-write, danger-full-access

-a, --ask-for-approval <POLICY>  # 命令审批策略
# 可选值：untrusted, on-failure(已弃用), on-request, never

--dangerously-bypass-approvals-and-sandbox  # ⚠️ 极端危险，跳过所有确认和沙箱

示例：

codex -s workspace-write -a on-request "部署这个应用"
codex -s danger-full-access -a never "执行自动化脚本"  # 完全自动化运行

4. 配置文件

-c, --config <key=value>      # 覆盖配置项（点号路径）
-p, --profile <PROFILE>       # 叠加额外的配置文件
--strict-config              # 遇到不识别的配置项时报错

示例：

codex -c model="o3" -c 'sandbox_permissions=["disk-full-read-access"]'
codex -p work -c features.experimental=true

5. 功能开关

--enable <FEATURE>            # 启用某个特性
--disable <FEATURE>           # 禁用某个特性

示例：

codex --enable web_search "查询今天的新闻"
codex --disable code_review "快速执行"

6. 其他实用选项

-i, --image <FILE>...         # 给提示附加图片
--search                      # 启用实时网络搜索
--no-alt-screen              # 禁用交替屏幕（保留终端滚动历史）
--remote <ADDR>              # 连接到远程应用服务器

示例：

codex -i screenshot.png "描述这张图片"
codex --search "解释量子计算"
codex --no-alt-screen  # 适合在 tmux 或脚本中使用

---

三、子命令（主要功能）

执行类

子命令	说明	示例
exec	非交互式运行	codex exec "格式化所有py文件"
review	代码审查	codex review --diff HEAD~1
apply	应用 agent 生成的 diff	codex apply
sandbox	在沙箱中运行命令	codex sandbox "ls -la"

会话管理

子命令	说明	示例
resume	恢复之前的会话	codex resume --last
fork	复制之前的会话	codex fork --last
archive	归档会话	codex archive session_123
delete	永久删除会话	codex delete session_123
unarchive	取消归档	codex unarchive session_123

配置与诊断

子命令	说明	示例
login / logout	登录/登出	codex login
doctor	诊断安装配置	codex doctor
update	更新到最新版	codex update
completion	生成 shell 补全	codex completion bash
features	查看功能开关	codex features

服务器/远程

子命令	说明	示例
mcp-server	启动为 MCP 服务器	codex mcp-server
app-server	实验性应用服务器	codex app-server
remote-control	管理远程控制	codex remote-control start
app	启动桌面应用	codex app
exec-server	执行服务器	codex exec-server

其他

子命令	说明	示例
cloud	实验性云任务	codex cloud list
debug	调试工具	codex debug logs
plugin	插件管理	codex plugin install xxx
mcp	MCP 服务器管理	codex mcp list

---

四、实战组合示例

场景1：日常交互式编程

codex -C ~/project -m "gpt-4" -a on-request

场景2：非交互式自动化

codex exec -s danger-full-access -a never "运行所有测试并修复失败的用例"

场景3：代码审查

codex review --pr 123 -m "claude-3.5-sonnet"

场景4：带额外权限和配置

codex -C /app --add-dir /data -c features.web_search=true -p prod "处理数据文件"

场景5：恢复上一次会话

codex resume --last

---

五、安全提示

1. --dangerously-bypass-approvals-and-sandbox：仅在完全受控的环境（如 CI/CD 隔离容器）中使用，切勿在本地开发机随意使用。

2. --dangerously-bypass-hook-trust：自动化场景中确保 hook 来源可信再使用。

3. -a never 配合沙箱使用时，确保 -s 策略足够严格。